Reasonably complete and up-to-date docs.
This commit is contained in:
sperber
parent
ec99930213
commit
6a283ab875
|
|
@ -1,130 +1,111 @@
|
|||
\chapter{URL}\label{cha:url}
|
||||
\chapter{Parsing and Processing URLs}\label{cha:url}
|
||||
%
|
||||
\begin{description}
|
||||
\item[Used files:] url.scm
|
||||
\item[Name of the package:] url
|
||||
\end{description}
|
||||
%
|
||||
\section{Overview}
|
||||
This modules contains procedures to parse and unparse URLs. Till now,
|
||||
only the parsing of http URLs is implemented.
|
||||
This modules contains procedures to parse and unparse URLs. Until
|
||||
now, only the parsing of HTTP URLs is implemented.
|
||||
|
||||
\section{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}
|
||||
\section{Server Records}
|
||||
|
||||
A \textit{server} value describes path prefixes of the form
|
||||
\var{user}:\var{password}@\var{host}:\var{port}. These are
|
||||
frequently used as the initial prefix of URLs describing Internet
|
||||
resources.
|
||||
|
||||
\defun{make-server}{user password host port}{server}
|
||||
\defunx{server?}{thing}{boolean}
|
||||
\defunx{server-user}{server}{string-or-\sharpf}
|
||||
\defunx{server-password}{server}{string-or-\sharpf}
|
||||
\defunx{server-host}{server}{string-or-\sharpf}
|
||||
\defunx{server-port}{server}{string-or-\sharpf}
|
||||
\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{Make-server} creates a new server record. Each slot is a
|
||||
decoded string or \sharpf. (\var{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.
|
||||
\ex{server?} is the corresponding predicate, \ex{server-user},
|
||||
\ex{server-password}, \ex{server-host} and \ex{server-port}
|
||||
are the correspondig selectors.
|
||||
\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').
|
||||
\defun{parse-server}{path default}{server}
|
||||
\defunx{server->string}{server}{string}
|
||||
\begin{desc}
|
||||
\ex{Parse-server} parses a URI path \var{path} (a list representing
|
||||
a path, not a string) into a server value. Default values are taken
|
||||
from the server \var{default} except for the host. The values
|
||||
are unescaped and stored into a server 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.
|
||||
\ex{server->string} just does the inverse job: it unparses
|
||||
\var{server} into a string. The elements of the record
|
||||
are escaped before they are put together.
|
||||
|
||||
Example:
|
||||
\begin{alltt}
|
||||
> (define default
|
||||
(make-userhost
|
||||
"andreas" "se ret" "www.sf.net" "80"))
|
||||
> (userhost->string default)
|
||||
> (define default (make-server "andreas" "se ret" "www.sf.net" "80"))
|
||||
> (server->string default)
|
||||
"andreas:se\%20ret@www.sf.net:80"
|
||||
> (parse-userhost
|
||||
'("" "" "foo\%20bar@www.scsh.net" "docu" "index.html")
|
||||
> (parse-server '("" "" "foo\%20bar@www.scsh.net" "docu" "index.html")
|
||||
default)
|
||||
'#{userhost}
|
||||
> (userhost->string ##)
|
||||
'#{server}
|
||||
> (server->string ##)
|
||||
"foo\%20bar:se\%20ret@www.scsh.net:80"
|
||||
\end{alltt}
|
||||
|
||||
For details about escaping and unescaping see Chapter ``Handle
|
||||
URIs'' at page \pageref{cha: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 Chapter \ref{cha:uri} on page
|
||||
\pageref{cha: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.
|
||||
%
|
||||
For details about escaping and unescaping see Chapter~\ref{cha:uri}.
|
||||
\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.
|
||||
\section{HTTP URLs}
|
||||
|
||||
\ex{http-url->string} just does the inverse job. It converts a
|
||||
\ex{http\=url} record into a \str.
|
||||
\defun{make-http-url}{server path search frag-id}{http-url}
|
||||
\defunx{http-url?}{thing}{boolean}
|
||||
\defunx{http-url-server}{http-url}{server}
|
||||
\defunx{http-url-path}{http-url}{list}
|
||||
\defunx{http-url-search}{http-url}{string-or-\sharpf}
|
||||
\defunx{http-url-frag-ment-identifier}{http-url}{string-or-\sharpf}
|
||||
%
|
||||
\begin{desc}
|
||||
\ex{Make-http-url} creates a new \ex{httpd-url} record.
|
||||
\var{Server} is a record, containing the initial part of the address
|
||||
(like \ex{anonymous@clark.lcs.mit.edu:80}). \var{Path} contains the
|
||||
URL's URI path ( a list). These elements are in raw, unescaped
|
||||
format. To convert them back to a string, use
|
||||
\ex{(uri-path-list->path (map escape-uri pathlist))}. \var{Search}
|
||||
and \var{frag-id} are the last two parts of the URL. (See
|
||||
Chapter~\ref{cha:uri} about parts of an URI.)
|
||||
|
||||
\ex{Http-url?} is the predicate for HTTP URL values, and
|
||||
\ex{http-url-server}, \ex{http-url-path}, \ex{http-url-search} and
|
||||
\ex{http-url-fragment-identifier} are the corresponding selectors.
|
||||
\end{desc}
|
||||
|
||||
\defun{parse-http-url}{path search frag-id}{http-url}
|
||||
\begin{defundescx}{http-url->string}{http-url}{string}
|
||||
This constructs an HTTP URL record from a URI path (a list of path
|
||||
components), a search, and a frag-id component.
|
||||
|
||||
\ex{Http-url->string} just does the inverse job. It converts an
|
||||
HTTP URL record into a string.
|
||||
\end{defundescx}
|
||||
%
|
||||
Note: The URI parser \ex{parse-uri} maps a string to four parts:
|
||||
\var{scheme}, \var{path}, \var{search} and \var{frag-id} (see
|
||||
Section~\ref{proc:parse-uri} for details). If \var{scheme} is
|
||||
\ex{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. \var{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.
|
||||
|
||||
The following procedure combines the jobs of \ex{parse-uri} and
|
||||
\ex{parse-http-url}:
|
||||
|
||||
\defun{parse-http-url-string}{string}{http-url}
|
||||
\begin{desc}
|
||||
This parses an HTTP URL and returns the corresponding URL value; it
|
||||
calls \ex{fatal-syntax-error} if the URL string doesn't have an
|
||||
\ex{http} scheme.
|
||||
\end{desc}
|
||||
|
||||
%%% Local Variables:
|
||||
%%% mode: latex
|
||||
|
|
|
|||
Loading…
Reference in New Issue