sunet/doc/latex/url.tex

\chapter{URL}\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.

\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}
\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 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.
\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"
%%% End: