* Info Catalog Prev emacs-mime: Composing Up emacs-mime: Top Next emacs-mime: Basic Functions

emacs-mime: Interface Functions

 
 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.
* Info Catalog Prev emacs-mime: Composing Up emacs-mime: Top Next emacs-mime: Basic Functions