GNU Info

(emacs-mime)Interface Functions

---

Next: Basic Functions Prev: Top Up: Top

---

Enter node , (file) or (file)node

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:

 - Function: mail-header-parse-content-type string
     Parse STRING, a `Content-Type' header, and return a content-type
     list in 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"))

 - Function: mail-header-parse-content-disposition string
     Parse STRING, a `Content-Disposition' header, and return a
     content-type list in the format above.

 - Function: mail-content-type-get ct attribute
     Returns the value of the given ATTRIBUTE from the content-type
     list CT.

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

 - Function: mail-header-encode-parameter param value
     Takes a parameter string `PARAM=VALUE' and returns an encoded
     version of it.  This is used for parameters in headers like
     `Content-Type' and `Content-Disposition'.

 - Function: mail-header-remove-comments string
     Return a comment-free version of STRING.

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

 - Function: mail-header-remove-whitespace string
     Remove linear white space from STRING.  Space inside quoted
     strings and comments is preserved.

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

 - Function: mail-header-get-comment string
     Return the last comment in STRING.

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

 - Function: mail-header-parse-address string
     Parse an address string STRING 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")

 - Function: mail-header-parse-addresses string
     Parse STRING as a 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"))

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

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

 - Function: mail-header-narrow-to-field
     Narrow the buffer to the header under point.

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

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

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

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

 - Function: mail-decode-encoded-word-region start end
     Decode the encoded words in the region STARTto END.

 - Function: mail-decode-encoded-word-string string
     Decode the encoded words in 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.