[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Interface Functions

The mail-parse library is an abstraction over the actual low-level libraries that are described in the next chapter.

Standards change, and so programs have to change to fit in the new mold. For instance, RFC2045 describes a syntax for the Content-Type header that only allows ASCII characters in the parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme for continuation headers and non-ASCII characters.

The traditional way to deal with this is just to update the library functions to parse the new syntax. However, this is sometimes the wrong thing to do. In some instances it may be vital to be able to understand both the old syntax as well as the new syntax, and if there is only one library, one must choose between the old version of the library and the new version of the library.

The Emacs MIME library takes a different tack. It defines a series of low-level libraries (`rfc2047.el', `rfc2231.el' and so on) that parses strictly according to the corresponding standard. However, normal programs would not use the functions provided by these libraries directly, but instead use the functions provided by the mail-parse library. The functions in this library are just aliases to the corresponding functions in the latest low-level libraries. Using this scheme, programs get a consistent interface they can use, and library developers are free to create write code that handles new standards.

The following functions are defined by this library:

mail-header-parse-content-type
Parse a Content-Type header and return a list on the following format:

 
("type/subtype"
 (attribute1 . value1)
 (attribute2 . value2)
 ...)

Here's an example:

 
(mail-header-parse-content-type
 "image/gif; name=\"b980912.gif\"")
=> ("image/gif" (name . "b980912.gif"))

mail-header-parse-content-disposition
Parse a Content-Disposition header and return a list on the same format as the function above.

mail-content-type-get
Takes two parameters--a list on the format above, and an attribute. Returns the value of the attribute.

 
(mail-content-type-get
 '("image/gif" (name . "b980912.gif")) 'name)
=> "b980912.gif"

mail-header-encode-parameter
Takes a parameter string and returns an encoded version of the string. This is used for parameters in headers like Content-Type and Content-Disposition.

mail-header-remove-comments
Return a comment-free version of a header.

 
(mail-header-remove-comments
 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
=> "Gnus/5.070027  "

mail-header-remove-whitespace
Remove linear white space from a header. Space inside quoted strings and comments is preserved.

 
(mail-header-remove-whitespace
 "image/gif; name=\"Name with spaces\"")
=> "image/gif;name=\"Name with spaces\""

mail-header-get-comment
Return the last comment in a header.

 
(mail-header-get-comment
 "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)")
=> "Finnish Landrace"

mail-header-parse-address
Parse an address and return a list containing the mailbox and the plaintext name.

 
(mail-header-parse-address
 "Hrvoje Niksic <hniksic@srce.hr>")
=> ("hniksic@srce.hr" . "Hrvoje Niksic")

mail-header-parse-addresses
Parse a string with list of addresses and return a list of elements like the one described above.

 
(mail-header-parse-addresses
 "Hrvoje Niksic <hniksic@srce.hr>, Steinar Bang <sb@metis.no>")
=> (("hniksic@srce.hr" . "Hrvoje Niksic")
     ("sb@metis.no" . "Steinar Bang"))

mail-header-parse-date
Parse a date string and return an Emacs time structure.

mail-narrow-to-head
Narrow the buffer to the header section of the buffer. Point is placed at the beginning of the narrowed buffer.

mail-header-narrow-to-field
Narrow the buffer to the header under point. Understands continuation headers.

mail-header-fold-field
Fold the header under point.

mail-header-unfold-field
Unfold the header under point.

mail-header-field-value
Return the value of the field under point.

mail-encode-encoded-word-region
Encode the non-ASCII words in the region. For instance, `Naïve' is encoded as `=?iso-8859-1?q?Na=EFve?='.

mail-encode-encoded-word-buffer
Encode the non-ASCII words in the current buffer. This function is meant to be called narrowed to the headers of a message.

mail-encode-encoded-word-string
Encode the words that need encoding in a string, and return the result.

 
(mail-encode-encoded-word-string
 "This is naïve, baby")
=> "This is =?iso-8859-1?q?na=EFve,?= baby"

mail-decode-encoded-word-region
Decode the encoded words in the region.

mail-decode-encoded-word-string
Decode the encoded words in the string and return the result.

 
(mail-decode-encoded-word-string
 "This is =?iso-8859-1?q?na=EFve,?= baby")
=> "This is naïve, baby"

Currently, mail-parse is an abstraction over ietf-drums, rfc2047, rfc2045 and rfc2231. These are documented in the subsequent sections.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.