129 lines
5.3 KiB
Plaintext
129 lines
5.3 KiB
Plaintext
(define nntp-doc
|
|
(mk-document {nntp}
|
|
{The PLT NNTP Toolkit}
|
|
|
|
{[(paragraph {The NNTP toolkit implements routines which form the
|
|
basis for a client that can converse with an NNTP (Usenet
|
|
News) server. The toolkit defines both procedures to
|
|
interface with the server, and exceptions which indicate
|
|
erroneous behavior.})]
|
|
|
|
[(paragraph
|
|
{The toolkit is parameterized over [(italic
|
|
{communicator})]s, which are structures representing a
|
|
connection to a particular server. Several communicators can
|
|
be open at any given time. A communicator has four fields:
|
|
|
|
[(mk-itemize
|
|
(list
|
|
{[(italic {sender})], an output port which sends
|
|
commands to the the server;
|
|
}
|
|
{[(italic {receiver})], an input port for receiving
|
|
responses from the server;
|
|
}
|
|
{[(italic {server})], a string containing the name of
|
|
the server, which is useful for error messages and
|
|
identification; and,
|
|
}
|
|
{[(italic {port})], a number denoting the port number
|
|
on the server to which this connection was
|
|
established.
|
|
}))]})]
|
|
|
|
[(paragraph {The following procedures are defined:})]
|
|
|
|
[(mk-itemize
|
|
(list
|
|
{[(bold {connect-to-server})] accepts a string, the server's
|
|
name, and optionally the port number. If no port number
|
|
is provided, the default NNTP port (119) is used. A
|
|
communicator is returned.}
|
|
{[(bold {disconnect-from-server})] takes a communicator and
|
|
closes its connections.}
|
|
{[(bold {open-news-group})] accepts a communicator and a
|
|
string, representing the group's name, and makes it the
|
|
current group. Three values are returned: the number of
|
|
articles the server has for the group, the first
|
|
available article number, and the last article number.}
|
|
{[(bold {head-of-message})] takes a communicator and a
|
|
message number, and returns the message's headers as a
|
|
list of strings.}
|
|
{[(bold {body-of-message})] takes a communicator and a
|
|
message number, and returns the message's body as a list
|
|
of strings.}
|
|
{[(bold {make-desired-header})] takes a string representing a
|
|
header, and returns a regular expression which can be
|
|
matched against header lines. The string should be given
|
|
sans a trailing colon; regular expressions may be used
|
|
within the string.}
|
|
{[(bold {extract-desired-headers})] accepts a list of strings
|
|
representing the header and a list of regular expressions
|
|
representing desired headers, and returns a list of
|
|
strings denoting the desired headers.}))]
|
|
|
|
[(paragraph {This library only interfaces using the NNTP
|
|
protocol; it does not attempt to improve it by providing an
|
|
alternative, perhaps more functional, formulation. Hence, it
|
|
generates the same errors as those returned by NNTP servers.
|
|
These errors are expressed as Scheme exceptions. They are
|
|
all sub-types of the exception [(bold {nntp})] (which has
|
|
no fields).})]
|
|
|
|
[(itemize
|
|
{[(bold {unexpected-response})] has two fields: [(italic
|
|
{code})], a number and [(italic {text})], a string containing
|
|
the error message returned by the server. This is raised
|
|
when the return code is not recognized by the toolkit.}
|
|
|
|
{[(bold {premature-close})] is raised when the server
|
|
generates an end-of-file in the midst of a multi-line
|
|
response (such as the message header or body). The exception
|
|
has a [(italic {communicator})] field.}
|
|
|
|
{[(bold {non-existent-group})] is raised when the group being
|
|
opened is not recognized by the server. Note that not all
|
|
servers carry all groups.}
|
|
|
|
{[(bold {article-not-in-group})] is raised when an attempt is
|
|
made to get the header or body of a group outside the range
|
|
for the group or which has expired or been cancelled. The
|
|
[(italic {article})] field holds the article number.}
|
|
|
|
{[(bold {article-not-found})] is raised in other situations
|
|
when an article cannot be found. The article number is given
|
|
in the [(italic {article})] field.}
|
|
|
|
{[(bold {no-group-selected})] is raised when an attempt is
|
|
made to get the header or body of an article before any group
|
|
has been selected.}
|
|
|
|
{[(bold {bad-newsgroup-line})] is raised when the server is
|
|
not following the RFC specification acknowledging that a
|
|
newsgroup has been set. It holds the line in the [(italic
|
|
{line})] field.}
|
|
|
|
{[(bold {bad-status-line})] has one field: [(italic {line})],
|
|
a string. This is only flagged when the server does not
|
|
follow the RFC specification.})]
|
|
|
|
[(paragraph {There are at least two routes to take when
|
|
improving the library's design. One possibility is to
|
|
provide a construct, similar to Scheme's i/o functions, in
|
|
whose dynamic range groups are selected, and inside which all
|
|
article reading is done. Another approach is to require all
|
|
article accesses to also specify a group. The current group
|
|
state would be maintained by the implementation, which can
|
|
optimize away the need to make the current group setting for
|
|
each article read. It can also anticipate certain errors.
|
|
The state would be cached with each communicator.})]
|
|
|
|
[(paragraph {This implementation currently provides no posting
|
|
conveniences, though since the output port to the server is
|
|
available, the user could implement this. However, that same
|
|
argument can be made for the rest of the toolkit as well.})]
|
|
|
|
}))
|
|
|
|
(render-html nntp-doc)
|