sunet/doc/latex/url.tex

133 lines
5.5 KiB
TeX

\section{URL}\label{sec:url}
%
\begin{description}
\item[Used files:] url.scm
\item[Name of the package:] url
\end{description}
%
\subsection{Overview}
This modules contains procedures to parse and unparse URLs. Till now,
only the parsing of http URLs is implemented.
\subsection{Entry points}
\defun{make-userhost}{user password host port}{userhost-record}
\defunx{userhost?}{thing}{boolean}
\defunx{userhost:user}{userhost-record}{value}
\defunx{userhost:password}{userhost-record}{value}
\defunx{userhost:host}{userhost-record}{value}
\defunx{userhost:port}{userhost-record}{value}
\defunx{set-userhost:user}{userhost-record new-value}{void}
\defunx{set-userhost:password}{userhost-record new-value}{void}
\defunx{set-userhost:host}{userhost-record new-value}{void}
\defunx{set-userhost:port}{userhost-record new-value}{void}
\begin{desc}
\ex{make\=userhost} creates a new \ex{userhost} record. This record
describes path-prefixes of the form
\semvar{user}:\semvar{password}@\semvar{host}:\semvar{port}. These
are frequently used as the initial prefix of URL's describing
Internet resources. Each slot is a decoded string or \sharpf\ (yes,
\semvar{port} is also a string).
\ex{userhost?} is the corresponding predicate,
\ex{userhost:\ob{}user}, \ex{userhost:\ob{}pass\ob{}word},
\ex{userhost:\ob{}host} and \ex{userhost:\ob{}port} are the
correspondig selectors and \ex{set\=userhost:\ob{}user},
\ex{set\=userhost:\ob{}pass\ob{}word}, \ex{set\=userhost:\ob{}host}
and \ex{set\=userhost:\ob{}port} the corresponding mutators. As you
can store everything into the record fields, the selectors may
return any type of value. However, under normal circumstances, only
\str\ or \sharpf\ is returned.
\end{desc}
\defun{parse-userhost}{path default}{userhost-record}
\begin{defundescx}{userhost->string}{userhost-record}{string}
\ex{parse\=userhost} parses a URI \semvar{path} (a list representing
a path, not a string!) into a userhost record. Default values are
taken from the userhost record \semvar{default} except for the
host. The values are unescaped and stored into a userhost record
that is returned. \ex{fatal\=syntax\=error} is called, if the
specified path has no initial to slashes (i.e., it starts with
`//\ldots').
\ex{userhost->string} just does the inverse job: it unparses
\semvar{userhost-record} into a string. The elements of the record
are escaped before the are put together.
Example:
\begin{alltt}
> (define default
(make-userhost
"andreas" "se ret" "www.sf.net" "80"))
> (userhost->string default)
"andreas:se\%20ret@www.sf.net:80"
> (parse-userhost
'("" "" "foo\%20bar@www.scsh.net" "docu" "index.html")
default)
'#{userhost}
> (userhost->string ##)
"foo\%20bar:se\%20ret@www.scsh.net:80"
\end{alltt}
For details about escaping and unescaping see section ``Handle
URIs'' at page \pageref{sec:uri}.
\end{defundescx}
\defun{make-http-url}{userhost path search frag-id}{http-url-record}
\defunx{http-url?}{thing}{boolean}
\defunx{http-url:userhost}{http-url}{value}
\defunx{http-url:path}{http-url}{value}
\defunx{http-url:search}{http-url}{value}
\defunx{http-url:frag-id}{http-url}{value}
\defunx{set-http-url:userhost}{http-url new-value}{void}
\defunx{set-http-url:path}{http-url new-value}{void}
\defunx{set-http-url:search}{http-url new-value}{void}
\defunx{set-http-url:frag-id}{http-url new-value}{void}
\begin{desc}
\ex{make\=http\=url} creates a new \ex{httpd\=url} record.
\semvar{userhost} is a record, containing the initial part of the
address (like
\ex{ano\ob{}ny\ob{}mous@\ob{}clark.\ob{}lcs.\ob{}mit.\ob{}edu:\ob{}80}).
\semvar{path} contains the URL's path split at slashes, e.g.\
\ex{"foo/\ob{}bar/\ob{}baz/"} becomes \ex{'("foo" "bar" "baz" "")}.
These elements are in raw, unescaped format. To convert them back to
a string, use \ex{(uri\=path\=list->path (map escape\=uri
pathlist))}. \semvar{search} and \semvar{frag\=id} are the last
two parts of the URL (see section \ref{sec:uri} on page
\pageref{sec:uri} about parts of an URI).
\ex{http\=url:userhost}, \ex{http\=url:path}, \ex{http\=url:search}
and \ex{http\=url:frag\=id} are the corresponding selectors,
\ex{set\=http\=url:userhost}, \ex{set\=http\=url:path},
\ex{set\=http\=url:search} and \ex{set\=http\=url:frag\=id} the
corresponding mutators. As you can store every type of value into
the record fields, the selectors can return any type of value.
However, \ex{http\=:userhost} usually returns a \ex{userhost}
record, \ex{http\=:path} returns a list of \str{}s and
\ex{http\=url:search} and \ex{http\=url:frag\=id} return both
\str{}s.
\end{desc}
\defun{parse-http-url}{path search frag-id}{http-url-record}
\begin{defundescx}{http-url->string}{http-url-record}{string}
The URI parser (\ex{parse\=uri} in \ex{uri.\ob{}scm}) maps a string
to four parts: \semvar{scheme}, \semvar{path}, \semvar{search} and
\semvar{frag-id} (see section \ref{proc:parse-uri} at page
\pageref{proc:parse-uri} for details). If \semvar{scheme} is
``http'', then the other three parts can be passed to
\ex{parse\=http\=url}, which parses them into a \ex{http\=url}
record. All strings come back from the URI parser encoded.
\semvar{search} and \var{frag\=id} are left that way; this parser
decodes the path elements. The first two list elements of the path
indicating the leading double-slash are omitted.
\ex{http-url->string} just does the inverse job. It converts a
\ex{http\=url} record into a \str.
\end{defundescx}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: man.tex
%%% End: