Prelimanary documenation.
 
 Class: mime-part-parsed
 Subclass of: mime-part
 
 Slot accessors:
 
     * mime-part-type 
       <update comment about mime-part-parsed objects>
     * mime-part-subtype
       <update comment about mime-part-parsed objects>
     * mime-part-parameters
     * mime-part-id
       <update comment about mime-part-parsed objects>
     * mime-part-description
       <update comment about mime-part-parsed objects>
     * mime-part-encoding
       <update comment about mime-part-parsed objects>
     * mime-part-headers
     * mime-part-parts
     * mime-part-boundary
       <update comment about mime-part-parsed objects>
 
     * mime-part-headers-size
       This is the size, in bytes, of the header portion of the part
       (including the blank line terminator)
 
     * mime-part-body-size
       This is the size, in bytes, of the body of the part.
 
     * mime-part-lines
       For non-multipart types, this is the number of lines that make
       up the part body.
    
     * mime-part-position 
       This is the file positon of the start of the part headers,
       relative to the beginning of the topmost part.
   
     * mime-part-body-position
       This is the file position of the start of the part body,
       relative to the beginning of the topmost part.
 
     * mime-part-message 
       For message/rfc822 parts, this slot contains the
       mime-part-parsed object which represents the encapsulated message.
 
 Function: parse-mime-structure
 
 Arguments: stream &key mbox
 
 Return values: 
 The function returns two values:
 
  1) A mime-part-parsed object which represents the topmost MIME part
     (which may possibly contain subparts).  If there was no message to
     parse (such as if the stream is at EOF), then nil is returned.
 
  2) The number of bytes that were read.
 
 'stream' should be a stream that is positioned at the first header of
 a MIME-compliant email message.  
 
 If 'mbox' is true, then parsing will terminate at EOF or when a line
 which begins with "From " is read.
 
 MIME messages always have a topmost part and may possibly have
 multiple subparts which may recursively have their own subparts.  This
 function reads 'stream' and creates a mime-part-parsed object which
 contains information about these parts and subparts.  For each part,
 the following information is collected:
 
 * The major content type, (e.g, "text", if the Content-Type header
   is "text/html").
 * The content subtype, (e.g., "html", if the Content-Type header is
   "text/html").
 * Any parameter information that was supplied in the Content-Type
   header.
 * The part id, as determined by the Content-Id header, if there was
   one.
 * The part description, as determined by the Content-Description
   header, if there was one.
 * The part encoding, as determined by the Content-Transfer-Encoding
   header.
 * The boundary string, for multipart types.  
 * The list of subparts (which are also mime-part-parsed objects) for
   multipart parts.
 * The encapsulated message (which is a mime-part-parsed object) for
   message/rfc822 parts.
 * The size of the part headers (in bytes).
 * The size of the part body (in bytes).
 * The number of lines comprising the part body.
 * The file position of the beginning of the part headers, relative to the
   position of the topmost part.  For the topmost part, this value will
   always be zero.  
 * The file position of the beginning of the part body, relative to the
   position of the topmost part.  
 
 See also: <the documentation page which lists the slots of the
 mime-part-parsed class>.
 
 
 Function: map-over-parts 
 Arguments: part function
 
 'part' must be a mime-part.
 
 'function' must be a function (or symbol naming a function) which
 takes a single argument, a mime-part.
 
 map-over-parts calls 'function' on 'part', then, if part contains
 subparts (or an encapsulated message in the case of a message/rfc822
 part), map-over-parts is called recursively for each subpart (or
 encapsulated message).
 
 Function: qp-encode-stream
 Arguments: instream outstream &key wrap-at
 
 This function reads bytes from instream and writes them in
 quoted-printable format to outstream.  Lines in the output are wrapped
 approximately every 'wrap-at' output characters (which defaults to
 72).  Wrapping may be late by up to 3 characters under some
 circumstances (e.g., when using the default 'wrap-at' value of 72,
 some lines may be 75 characters long).
 
 'instream' is read until EOF is seen.
 
 'instream' must be a stream capable of being read in an octet-oriented
 manner.  In particular, it cannot be a string stream.
 
 See also: qp-decode-stream, base64-encode-stream, base64-decode-stream
 
 
 
 Function: qp-decode-stream
 Arguments: instream outstream
 
 This function reads quoted-printable encoded text from 'instream' and
 writes the decoded text to 'outstream'.  Reading continues until
 end-of-file is seen on 'instream'.  
 
 See also: qp-encode-stream, base64-encode-stream, base64-decoed-stream
 
 
 Macro: with-part-stream
 Arguments: (sym part instream &key (header t)) &body body
 
 with-part-stream evaluates 'body' with 'sym' bound to an input stream
 which, when read, supplies bytes from 'instream'.  'instream' must be
 positioned either at the beginning of the part headers (if keyword
 argument 'header' is true) or at the beginning of the part body (if
 keyword argument 'header' is false).  The 'part' argument is used by
 the macro to determine how many bytes from 'instream' will be used.
 
 The primary purpose of this macro is to create a stream that will
 generate an end-of-file indicator when the contents of a part have
 been completely read.  Such a stream is useful for passing to
 functions which expect to read a stream until EOF (such as
 'decode-quoted-printable' or 'excl:base64-decode-stream').
 
 See also: with-decoded-part-body-stream
 
 Macro: with-decoded-part-body-stream
 Arguments: (sym part instream) &body body
 
 with-decoded-part-body-stream evaluates 'body' with 'sym' bound to an
 input stream which, when read, supplies decoded bytes.  The encoded
 bytes are read from 'instream', which should be an input stream whose
 file position is at the beginning of the part body.  The 'part'
 argument is used by the macro to determine the size of the part body
 and also to determine the content transfer encoding of the part.  The
 input stream bound to 'sym' will signal end-of-file when the part body
 has been exhausted.
 
 Example:
 
 (use-package :net.post-office)
 
 (defun extract-all-jpegs (filename)
   (with-open-file (f filename)
     (let ((toppart (parse-mime-structure f))
 	  (count 0))
       
       (flet ((extract-jpeg (part)
 	       (if* (and (equalp (mime-part-type part) "image")
 			 (equalp (mime-part-subtype part) "jpeg"))
 		  then (incf count)
 		       (let ((filename (format nil "image~d.jpg" count)))
 			 (format t "Saving ~a...~%" filename)
 			 (with-open-file (out filename :direction :output)
 			   ;; Position source file pointer to the beginning
 			   ;; of the part body.
 			   (file-position f (mime-part-body-position part))
 			   (with-decoded-part-body-stream (bod part f)
 			     (sys:copy-file bod out)))))))
       
 	(map-over-parts toppart #'extract-jpeg)))))
 
 See also: mime-part-body-position slot accessor.