diff --git a/doc/latex/url.tex b/doc/latex/url.tex index a159981..687fb1e 100644 --- a/doc/latex/url.tex +++ b/doc/latex/url.tex @@ -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