128 lines
4.4 KiB
TeX
128 lines
4.4 KiB
TeX
\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:
|