added WWW sections

1 files changed, 108 insertions, 0 deletions

diff --git a/Doc/librfc822.tex b/Doc/librfc822.tex
new file mode 100644
index 0000000..43a5cea
--- /dev/null
+++ b/Doc/librfc822.tex
@@ -0,0 +1,108 @@
+\section{Built-in module \sectcode{rfc822}}
+\stmodindex{rfc822}
+
+This module defines a class, \code{Message}, which represents a
+collection of ``email headers'' as defined by the Internet standard
+RFC 822.  It is used in various contexts, usually to read such headers
+from a file.
+
+A \code{Message} instance is instantiated with an open file object as
+parameter.  Instantiation reads headers from the file up to a blank
+line and stores them in the instance; after instantiation, the file is
+positioned directly after the blank line that terminates the headers.
+
+Input lines as read from the file may either be terminated by CR-LF or
+by a single linefeed; a terminating CR-LF is replaced by a single
+linefeed before the line is stored.
+
+All header matching is done independent of upper or lower case;
+e.g. \code{m['From']}, \code{m['from']} and \code{m['FROM']} all yield
+the same result.
+
+A \code{Message} instance has the following methods:
+
+\begin{funcdesc}{rewindbody}{}
+Seek to the start of the message body.  This only works if the file
+object is seekable.
+\end{funcdesc}
+
+\begin{funcdesc}{getallmatchingheaders}{name}
+Return a list of lines consisting of all headers whose header matches
+\var{name}, if any.  Each physical line, whether it is a continuation
+line or not, is a separate list item.  Return the empty list if no
+header matches \var{name}.
+\end{funcdesc}
+
+\begin{funcdesc}{getfirstmatchingheader}{name}
+Return a list of lines comprising the first header matching
+\var{name}, and its continuation line(s), if any.  Return \code{None}
+if there is no header matching \var{name}.
+\end{funcdesc}
+
+\begin{funcdesc}{getrawheader}{name}
+Return a single string consisting of the text after the colon in the
+first header matching \var{name}.  This includes leading whitespace,
+the trailing linefeed, and internal linefeeds and whitespace if there
+any continuation line(s) were present.  Return \code{None} if there is
+no header matching \var{name}.
+\end{funcdesc}
+
+\begin{funcdesc}{getheader}{name}
+Like \code{getrawheader(\var{name})}, but strip leading and trailing
+whitespace (but not internal whitespace).
+\end{funcdesc}
+
+\begin{funcdesc}{getaddr}{name}
+Return a pair (full name, email address) parsed from the string
+returned by \code{getheader(\var{name})}.  If no header matching
+\var{name} exists, return \code{None, None}; otherwise both the full
+name and the address are (possibly empty )strings.
+
+Example: if \code{m}'s first \code{From} header contains the string
+\code{'guido@cwi.nl (Guido van Rossum)'}, then
+\code{m.getaddr('From')} will yield the pair
+\code{('Guido van Rossum', 'guido\@cwi.nl')}.
+If the header contained
+\code{'Guido van Rossum <guido\@cwi.nl>'} instead, it would yield the
+exact same result.
+\end{funcdesc}
+
+\begin{funcdesc}{getaddrlist}{name}
+This is similar to \code{getaddr(\var{list})}, but parses a header
+containing a list of email addresses (e.g. a \code{To} header) and
+returns a list of (full name, email address) pairs (even if there was
+only one address in the header).  If there is no header matching
+\var{name}, return an empty list.
+
+XXX The current version of this function is not really correct.  It
+yields bogus results if a full name contains a comma.
+\end{funcdesc}
+
+\begin{funcdesc}{getdate}{name}
+Retrieve a header using \code{getheader} and parse it into a 9-tuple
+compatible with \code{time.kmtime()}.  If there is no header matching
+\var{name}, or it is unparsable, return \code{None}.
+
+Date parsing appears to be a black art, and not all mailers adhere to
+the standard.  While it has been tested and found correct on a large
+collection of email from many sources, it is still possible that this
+function may occasionally yield an incorrect result.
+\end{funcdesc}
+
+\code{Message} instances also support a read-only mapping interface.
+In particular: \code{m[name]} is the same as \code{m.getheader(name)};
+and \code{len(m)}, \code{m.has_key(name)}, \code{m.keys()},
+\code{m.values()} and \code{m.items()} act as expected (and
+consistently).
+
+Finally, \code{Message} instances have two public instance variables:
+
+\begin{datadesc}{headers}
+A list containing the entire set of header lines, in the order in
+which they were read.  Each line contains a trailing newline.  The
+blank line terminating the headers is not contained in the list.
+\end{datadesc}
+
+\begin{datadesc}{fp}
+The file object passed at instantiation time.
+\end{datadesc}