Reasonably complete and up-to-date docs.

doc/latex/url.tex

@@ -1,130 +1,111 @@
-\chapter{URL}\label{cha:url}
+\chapter{Parsing and Processing URLs}\label{cha:url}
 %
-\begin{description}
+This modules contains procedures to parse and unparse URLs.  Until
-\item[Used files:] url.scm
+now, only the parsing of HTTP URLs is implemented.
-\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}
+\section{Server Records}
-\defun{make-userhost}{user password host port}{userhost-record}
+
-\defunx{userhost?}{thing}{boolean}
+A \textit{server} value describes path prefixes of the form
-\defunx{userhost:user}{userhost-record}{value}
+\var{user}:\var{password}@\var{host}:\var{port}. These are
-\defunx{userhost:password}{userhost-record}{value}
+frequently used as the initial prefix of URLs describing Internet
-\defunx{userhost:host}{userhost-record}{value}
+resources.
-\defunx{userhost:port}{userhost-record}{value}
+
-\defunx{set-userhost:user}{userhost-record new-value}{void}
+\defun{make-server}{user password host port}{server}
-\defunx{set-userhost:password}{userhost-record new-value}{void}
+\defunx{server?}{thing}{boolean}
-\defunx{set-userhost:host}{userhost-record new-value}{void}
+\defunx{server-user}{server}{string-or-\sharpf}
-\defunx{set-userhost:port}{userhost-record new-value}{void}
+\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
+  \ex{Make-server} creates a new server record.  Each slot is a
-  describes path-prefixes of the form
+  decoded string or \sharpf. (\var{Port} is also a string.)
-  \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{server?} is the corresponding predicate, \ex{server-user},
-  \ex{userhost:\ob{}user}, \ex{userhost:\ob{}pass\ob{}word},
+  \ex{server-password}, \ex{server-host} and \ex{server-port}
-  \ex{userhost:\ob{}host} and \ex{userhost:\ob{}port} are the
+  are the correspondig selectors.
-  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}
+\defun{parse-server}{path default}{server}
-\begin{defundescx}{userhost->string}{userhost-record}{string}
+\defunx{server->string}{server}{string}
-  \ex{parse\=userhost} parses a URI \semvar{path} (a list representing
+\begin{desc}
-  a path, not a string!) into a userhost record. Default values are
+  \ex{Parse-server} parses a URI path \var{path} (a list representing
-  taken from the userhost record \semvar{default} except for the
+  a path, not a string) into a server value.  Default values are taken
-  host. The values are unescaped and stored into a userhost record
+  from the server \var{default} except for the host.  The values
-  that is returned.  \ex{fatal\=syntax\=error} is called, if the
+  are unescaped and stored into a server record that is returned.
-  specified path has no initial to slashes (i.e., it starts with
+  \ex{Fatal-syntax-error} is called, if the specified path has no
-  `//\ldots').
+  initial to slashes (i.e., it starts with `//\ldots').
   
-  \ex{userhost->string} just does the inverse job: it unparses
+  \ex{server->string} just does the inverse job: it unparses
-  \semvar{userhost-record} into a string. The elements of the record
+  \var{server} into a string. The elements of the record
-  are escaped before the are put together.  
+  are escaped before they are put together.  
 
   Example:
 \begin{alltt}
-> (define default 
+> (define default (make-server "andreas"  "se ret" "www.sf.net" "80"))
-    (make-userhost 
+> (server->string default)
-     "andreas"  "se ret" "www.sf.net" "80"))
-> (userhost->string default)
 "andreas:se\%20ret@www.sf.net:80"
-> (parse-userhost 
+> (parse-server '("" "" "foo\%20bar@www.scsh.net" "docu" "index.html") 
-   '("" "" "foo\%20bar@www.scsh.net" "docu" "index.html") 
+                default)
-   default)
+'#{server}
-'#{userhost}
+> (server->string ##)
-> (userhost->string ##)
 "foo\%20bar:se\%20ret@www.scsh.net:80"
 \end{alltt}
-
+%
-  For details about escaping and unescaping see Chapter ``Handle
+For details about escaping and unescaping see Chapter~\ref{cha:uri}.
-  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}
+\section{HTTP URLs}
-\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
+\defun{make-http-url}{server path search frag-id}{http-url}
-  \ex{http\=url} record into a \str.
+\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