scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reasonably complete and up-to-date docs.

This commit is contained in:
sperber 2003-01-15 12:21:18 +00:00
parent ec99930213
commit 6a283ab875
1 changed files with 90 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
doc/latex/url.tex
View File

@ -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")
default)
'#{userhost}
> (userhost->string ##)
> (parse-server '("" "" "foo\%20bar@www.scsh.net" "docu" "index.html")
default)
'#{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