sunet/doc/latex/rfc822.tex

128 lines
4.4 KiB
TeX
Raw Normal View History

\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: