sunet/doc/latex/url.tex

\chapter{Parsing and Processing URLs}\label{cha:url}
%
This modules contains procedures to parse and unparse HTTP 1.1 Request-URIs.

\section{HTTP URLs}

\defun{parse-uri} {uri-string } {host port path query} \label{proc:parse-uri}
\begin{desc}
  Parses an HTTP 1.1 Request-URI \var{uri\=string} into its four fields.
  The fields returned are \emph{not} decoded. 
  If \var{uri\=string} is not an http URL but an abs\_path 
  the \var{host}, \var{port}
  and \var{query} portions are not specified, they are \sharpf.
  Otherwise, \var{host}, \var{port}, and \var{query} are
  strings. \var{path} is a non-empty string list---the path split
  at slashes.
\end{desc}
This parser does not absolutely conform to RFC 2616 in allowing 
a fragment-suffix. Furthermore only http URLs, not absolute URIs in general are
recognized (see source for further explanation).

\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->uri (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
%%% TeX-master: "man"
%%% End: