117 lines
5.1 KiB
TeX
117 lines
5.1 KiB
TeX
\section{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 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.
|
|
|
|
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: t
|
|
%%% End:
|