README
¶
go-message
A Go library for the Internet Message Format. It implements:
- RFC 5322: Internet Message Format
- RFC 2045, RFC 2046 and RFC 2047: Multipurpose Internet Mail Extensions
- RFC 2183: Content-Disposition Header Field
Features
- Streaming API
- Automatic encoding and charset handling
- A
mailsubpackage to read and write mail messages
License
MIT
Documentation
¶
Overview ¶
Package message implements reading and writing multipurpose messages.
RFC 2045, RFC 2046 and RFC 2047 defines MIME, and RFC 2183 defines the Content-Disposition header field.
Example (Transform) ¶
// Let's assume r is an io.Reader that contains a message.
var r io.Reader
m, err := message.Read(r)
if message.IsUnknownEncoding(err) {
log.Println("Unknown encoding:", err)
} else if err != nil {
log.Fatal(err)
}
// We'll add "This message is powered by Go" at the end of each text entity.
poweredBy := "\n\nThis message is powered by Go."
var b bytes.Buffer
w, err := message.CreateWriter(&b, m.Header)
if err != nil {
log.Fatal(err)
}
// Define a function that transforms message.
var transform func(w *message.Writer, e *message.Entity) error
transform = func(w *message.Writer, e *message.Entity) error {
if mr := e.MultipartReader(); mr != nil {
// This is a multipart entity, transform each of its parts
for {
p, err := mr.NextPart()
if err == io.EOF {
break
} else if err != nil {
return err
}
pw, err := w.CreatePart(p.Header)
if err != nil {
return err
}
if err := transform(pw, p); err != nil {
return err
}
pw.Close()
}
return nil
} else {
body := e.Body
if strings.HasPrefix(m.Header.Get("Content-Type"), "text/") {
body = io.MultiReader(body, strings.NewReader(poweredBy))
}
_, err := io.Copy(w, body)
return err
}
}
if err := transform(w, m); err != nil {
log.Fatal(err)
}
w.Close()
log.Println(b.String())
Output:
Index ¶
- func IsUnknownEncoding(err error) bool
- type Entity
- type Header
- func (h Header) Add(key, value string)
- func (h Header) ContentDescription() (string, error)
- func (h Header) ContentDisposition() (disp string, params map[string]string, err error)
- func (h Header) ContentType() (t string, params map[string]string, err error)
- func (h Header) Del(key string)
- func (h Header) Get(key string) string
- func (h Header) Set(key, value string)
- func (h Header) SetContentDescription(desc string)
- func (h Header) SetContentDisposition(disp string, params map[string]string)
- func (h Header) SetContentType(t string, params map[string]string)
- type MultipartReader
- type Writer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsUnknownEncoding ¶
IsUnknownEncoding returns a boolean indicating whether the error is known to report that the transfer encoding or the charset advertised by the entity is unknown.
Types ¶
type Entity ¶
type Entity struct {
Header Header // The entity's header.
Body io.Reader // The decoded entity's body.
// contains filtered or unexported fields
}
An Entity is either a whole message or a one of the parts in the body of a multipart entity.
func New ¶
New makes a new message with the provided header and body. The entity's transfer encoding and charset are automatically decoded to UTF-8.
If the message uses an unknown transfer encoding or charset, New returns an error that verifies IsUnknownEncoding, but also returns an Entity that can be read.
func NewMultipart ¶
NewMultipart makes a new multipart message with the provided header and parts. The Content-Type header must begin with "multipart/".
If the message uses an unknown transfer encoding, NewMultipart returns an error that verifies IsUnknownEncoding, but also returns an Entity that can be read.
func Read ¶
Read reads a message from r. The message's encoding and charset are automatically decoded to UTF-8. Note that this function only reads the message header.
If the message uses an unknown transfer encoding or charset, Read returns an error that verifies IsUnknownEncoding, but also returns an Entity that can be read.
Example ¶
// Let's assume r is an io.Reader that contains a message.
var r io.Reader
m, err := message.Read(r)
if message.IsUnknownEncoding(err) {
// This error is not fatal
log.Println("Unknown encoding:", err)
} else if err != nil {
log.Fatal(err)
}
if mr := m.MultipartReader(); mr != nil {
// This is a multipart message
log.Println("This is a multipart message containing:")
for {
p, err := mr.NextPart()
if err == io.EOF {
break
} else if err != nil {
log.Fatal(err)
}
t, _, _ := p.Header.ContentType()
log.Println("A part with type", t)
}
} else {
t, _, _ := m.Header.ContentType()
log.Println("This is a non-multipart message with type", t)
}
Output:
func (*Entity) MultipartReader ¶
func (e *Entity) MultipartReader() MultipartReader
MultipartReader returns a MultipartReader that reads parts from this entity's body. If this entity is not multipart, it returns nil.
type Header ¶
A Header represents the key-value pairs in a message header.
func (Header) Add ¶
Add adds the key, value pair to the header. It appends to any existing values associated with key.
func (Header) ContentDescription ¶
ContentDescription parses the Content-Description header field.
func (Header) ContentDisposition ¶
ContentDisposition parses the Content-Disposition header field, as defined in RFC 2183.
func (Header) ContentType ¶
ContentType parses the Content-Type header field.
If no Content-Type is specified, it returns "text/plain".
func (Header) Get ¶
Get gets the first value associated with the given key. If there are no values associated with the key, Get returns "".
func (Header) Set ¶
Set sets the header entries associated with key to the single element value. It replaces any existing values associated with key.
func (Header) SetContentDescription ¶
SetContentDescription parses the Content-Description header field.
func (Header) SetContentDisposition ¶
SetContentDisposition formats the Content-Disposition header field, as defined in RFC 2183.
type MultipartReader ¶
type MultipartReader interface {
io.Closer
// NextPart returns the next part in the multipart or an error. When there are
// no more parts, the error io.EOF is returned.
//
// Entity.Body must be read completely before the next call to NextPart,
// otherwise it will be discarded.
NextPart() (*Entity, error)
}
MultipartReader is an iterator over parts in a MIME multipart body.
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
A Writer formats entities.
Example ¶
var b bytes.Buffer
h := make(message.Header)
h.SetContentType("multipart/alternative", nil)
w, err := message.CreateWriter(&b, h)
if err != nil {
log.Fatal(err)
}
h1 := make(message.Header)
h1.SetContentType("text/html", nil)
w1, err := w.CreatePart(h1)
if err != nil {
log.Fatal(err)
}
io.WriteString(w1, "<h1>Hello World!</h1><p>This is an HTML part.</p>")
w1.Close()
h2 := make(message.Header)
h1.SetContentType("text/plain", nil)
w2, err := w.CreatePart(h2)
if err != nil {
log.Fatal(err)
}
io.WriteString(w2, "Hello World!\n\nThis is a text part.")
w2.Close()
w.Close()
log.Println(b.String())
Output:
func CreateWriter ¶
CreateWriter creates a new Writer writing to w. If header contains an encoding, data written to the Writer will automatically be encoded with it.
func (*Writer) CreatePart ¶
CreatePart returns a Writer to a new part in this multipart entity. If this entity is not multipart, it fails. The body of the part should be written to the returned io.WriteCloser.
Source Files
Directories