\chapter{RFC~822 Library}\label{cha:rfc822}
%
The \ex{rfc822} structure provides rudimentary support for parsing
headers according to RFC 822 \textit{Standard for the format of ARPA
  Internet text messages}.  These headers show up in SMTP messages,
HTTP headers, etc.

\defun{read-rfc822-field} {[port] [read-line]} {name body}
\begin{desc}
  
  Read one field from the port, and return two values:

  \begin{description}
  \item[\var{name}] This is a symbol describing the RFC 822 field
    name, such as \ex{subject} or \ex{to}.  The symbol consists of all
    lower-case letters.\footnote{In fact, it \ex{read-rfc822-field}
      uses the preferred case for symbols of the underlying Scheme
      implementation which, in the case of scsh, happens to be lower-case.}
  \item[\var{body}] This is list of strings which are the field's
    body, e.g.  Each list element is one line from the field's body,
    so if the field spreads out over three lines, then the body is a
    list of three strings. The terminating \ex{cr}/\ex{lf}'s are
    trimmed from each string.  Note that header bodies frequently contain
    space after the colon like this:
    %
\begin{verbatim}
Subject: RFC 822 can format itself in the ARPA
\end{verbatim}
    %
    In this case, \var{body} will be
\begin{verbatim}
(" RFC 822 can format itself in the ARPA")
\end{verbatim}
  \end{description}
  %
  When there are no more fields---EOF or a blank line has terminated
  the header section---then \ex{read-rfc822-field} returns [\sharpf\ \sharpf].

  \var{Port} is an optional input port to read from---it defaults to
  the value of \ex{(current-input-port)}.
  
  \var{Read-line} is an optional parameter specifying a procedure of
  one argument (the input port) used to read the raw header lines.
  The default used by \ex{read-rfc822-field} terminates lines with
  either \ex{cr}/\ex{lf} or just \ex{lf}, and it trims the terminator
  from the line.  This procedure should trim the terminator of the
  line, so an empty line is returned as an empty string.
  
  The procedure raises an error if the syntax of the read field (the
  line returned by the read-line-function) is illegal according to
  RFC~822.
\end{desc}

\defun{read-rfc822-headers} {[port] [read-line]} {association-list}
\begin{desc}
  This procedure reads in and parses a section of text that looks like
  the header portion of an RFC~822 message.  It returns an association
  list mapping a field name (a symbol such as 'date or 'subject) to a
  list of field bodies----one for each occurence of the field in the
  header. So if there are five \ex{Received-by} fields in the header,
  the alist maps \ex{received-by} to a five-element list. Each body is
  in turn represented by a list of strings----one for each line of the
  field.  So a field spread across three lines would produce a
  three-element body.
  
  \var{Port} and \var{read-line} are as with \ex{read-rfc822-field}.
\end{desc}

\defun{rejoin-header-lines} {alist [seperator]}  {association list}
\begin{desc}
  
  Takes a field \var{alist} such as is returned by
  \ex{read-rfc822-headers} and returns an equivalent association list.
  Each body (\str list) in the input \var{alist} is joined into a
  single list in the output alist. \var{separator} is the string used
  to join these elements together; it defaults to a single space, but
  can usefully be ``\verb|\n|'' (linefeed) or ``\verb|\r\n|''
  (carriage-return/line-feed).
  
  To rejoin a single body list, use scsh's \ex{join-strings}
  procedure.
\end{desc}
%
For the following definitions' examples, let's use this set of of
RFC~822 headers:
\begin{alltt}
     From: shivers
     To: ziggy,
       newts
     To: gjs, tk
\end{alltt}
%

\defun{get-header-all} {headers name} {string list list}
\begin{desc}
  Returns all entries or \sharpf, e.g.\
  \codex{(get-header-all hdrs 'to)}
  returns
  \codex{'((" ziggy," "  newts") (" gjs, tk"))}
\end{desc}

\defun{get-header-lines} {headers name} {string list}
\begin{desc}
  Returns all lines of the first entry or \sharpf, e.g.\
  \codex{(get-header-lines hdrs 'to)}
  returns
  \codex{(" ziggy," "  newts")}
\end{desc}

\defun{get-header} {headers name [separator]} {string}
\begin{desc}
  Returns the first entry with the lines joined together by seperator
  (newline by default), e.g.\
  \codex{(get-header hdrs 'to)}
  returns
\begin{alltt}
" ziggy,
  newts"
\end{alltt}
%
  Note, that \ex{newts} is led by two spaces.
\end{desc}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "man"
%%% End: