document new URL parser

doc/latex/url.tex

@@ -1,74 +1,70 @@
 \chapter{Parsing and Processing URLs}\label{cha:url}
 %
-This modules contains procedures to parse and unparse HTTP 1.1 Request-URIs.
+The \ex{url} module 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}
+\defun{url-string->http-url}{string}{http-url}
 \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.
+ \ex{Url-string->http-url} parses the Request-URI \var{string} into a
+ \ex{http-url} record.
 \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}
+\defun{http-url?}{thing}{boolean}
+\begin{desc}
+  \ex{http-url?} is the predicate for the \ex{http-url} record.
+\end{desc}
+
+\defun{http-url-host}{http-url}{string or \sharpf}
+\defunx{http-url-port}{http-url}{integer or \sharpf}
 \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}
-%
+\defunx{http-url-query}{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.
+  \ex{http-url-host}, \ex{http-url-port}, \ex{http-url-path} and
+  \ex{http-url-query} are the selectors for the \ex{http-url} record.
+
+  The \var{host} slot is a non-empty string or \sharpf. 
+
+  The \var{port} slot is an integer or \sharpf.
+ 
+  The \var{path} slot is a list containing the Request-URI's  path
+  split at slashes and \emph{unescaped}.
+
+  The \var{query} slot is an non-empty-string, still in its
+  \emph{escaped} representation, or \sharpf.
+\end{desc}
+%
+Examples for Request-URI strings and the slots of the corresponding http-url record:
+\begin{alltt}
+"http://foo.bar.org:7777///foo%20foo//bar.htm?bulb%20bulb"
+\(\Rightarrow\) "foo.bar.org" 7777 '("foo foo" "bar.htm") "bulb%20bulb"
+
+"http://foo.bar.org/"
+\(\Rightarrow\) "foo.bar.org" #f '() #f
+
+"/foo%20foo//bar.htm?bulb%20bulb"
+\(\Rightarrow\)  #f #f '("foo foo" "bar.htm") "bulb%20bulb"
+
+"/" 
+\(\Rightarrow\) #f #f '() #f
+\end{alltt}
+
+
+\defun{http-url->url-string}{http-url}{string}
+\begin{desc}
+  \ex{http-url->url-string} unparses a http-url record into its
+  corresponding Request-URI.
 \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}
+\defun{http-url-path->path-string}{http-url-path}{string}
 \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.
+  \ex{http-url-path->url-string} unparses the http-url-path field of
+  an http-url record into its corresponding part of the Request-URI,
+  re-escaping the path.
 \end{desc}
+Example:
+\begin{alltt} 
+'("foo foo" "bar.htm") \(\Rightarrow\) "/foo%20foo/bar.htm"
+\end{alltt}
 
 %%% Local Variables: 
 %%% mode: latex