[Guile-commits] GNU Guile branch, master, updated. release_1-9-13-193-g299cd1a

[Andy Wingo]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=299cd1a22941e1685a36f0956302c870b0d824cb

The branch, master has been updated
       via  299cd1a22941e1685a36f0956302c870b0d824cb (commit)
      from  8db7e0947d7d6ac7e85ca45fa4d58e94794bb5c4 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 299cd1a22941e1685a36f0956302c870b0d824cb
Author: Andy Wingo <address@hidden>
Date:   Thu Dec 16 16:43:01 2010 +0100

    update web.texi
    
    * doc/ref/web.texi (URIs, HTTP): Update these sections.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/web.texi |  222 +++++++++++++++++++++++++++++++-----------------------
 1 files changed, 129 insertions(+), 93 deletions(-)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index e59e1a1..efa6ae7 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -42,44 +42,58 @@ the thing?  Read on!
 @node URIs
 @subsection Universal Resource Identifiers
 
address@hidden
-(use-modules (web uri))
address@hidden example
-
address@hidden 
- A data type for Universal Resource Identifiers, as defined in RFC
- 3986. 
address@hidden verbatim
+Guile provides a standard data type for Universal Resource Identifiers
+(URIs), as defined in RFC 3986.
 
address@hidden uri? 
address@hidden defspec
+The generic URI syntax is as follows:
 
address@hidden uri-scheme 
address@hidden defspec
-
address@hidden uri-userinfo 
address@hidden defspec
address@hidden
+URI := scheme ":" ["//" [userinfo "@"] host [":" port]] path \
+       [ "?" query ] [ "#" fragment ]
address@hidden example
 
address@hidden uri-host 
address@hidden defspec
+So, all URIs have a scheme and a path. Some URIs have a host, and some
+of those have ports and userinfo. Any URI might have a query part or a
+fragment.
 
address@hidden uri-port 
address@hidden defspec
+Userinfo is something of an abstraction, as some legacy URI schemes
+allowed userinfo of the form @address@hidden:@var{passwd}}.
+Passwords don't belong in URIs, so the RFC does not want to condone
+this, but neither can it say that what is before the @address@hidden sign is
+just a username, so the RFC punts on the issue and calls it
address@hidden
 
address@hidden uri-path 
address@hidden defspec
+Also, strictly speaking, a URI with a fragment is a @dfn{URI
+reference}.  A fragment is typically not serialized when sending a URI
+over the wire; that is, it is not part of the identifier of a resource.
+It only identifies a part of a given resource.  But it's useful to have
+a field for it in the URI record itself, so we hope you will forgive the
+inconsistency.
 
address@hidden uri-query 
address@hidden defspec
address@hidden
+(use-modules (web uri))
address@hidden example
 
address@hidden uri-fragment 
address@hidden defspec
+The following procedures can be found in the @code{(web uri)}
+module. Load it into your Guile, using a form like the above, to have
+access to them.
 
 @defun build-uri scheme [#:userinfo] [#:host] [#:port] [#:path] [#:query] 
[#:fragment] [#:validate?]
 Construct a URI object. If @var{validate?} is true, also run some
 consistency checks to make sure that the constructed URI is valid.
 @end defun
 
address@hidden uri? x
address@hidden uri-scheme uri
address@hidden uri-userinfo uri
address@hidden uri-host uri
address@hidden uri-port uri
address@hidden uri-path uri
address@hidden uri-query uri
address@hidden uri-fragment uri
+A predicate and field accessors for the URI record type.
address@hidden defun
+
 @defun declare-default-port! scheme port
 Declare a default port for the given URI scheme.
 
@@ -136,41 +150,66 @@ strings, and join the parts together with @code{/} as a 
delimiter.
 @node HTTP
 @subsection The Hyper-Text Transfer Protocol
 
+The initial motivation for including web functionality in Guile, rather
+than rely on an external package, was to establish a standard base on
+which people can share code.  To that end, we continue the focus on data
+types by providing a number of low-level parsers and unparsers for
+elements of the HTTP protocol.
+
+If you are want to skip the low-level details for now and move on to web
+pages, @pxref{Web Server}.  Otherwise, load the HTTP module, and read
+on.
+
 @example
 (use-modules (web http))
 @end example
 
-This module has a number of routines to parse textual
-representations of HTTP data into native Scheme data structures.
-
-It tries to follow RFCs fairly strictly---the road to perdition
-being paved with compatibility hacks---though some allowances are
-made for not-too-divergent texts (like a quality of .2 which should
-be 0.2, etc).
-
address@hidden header-decl? 
address@hidden defspec
-
address@hidden make-header-decl 
address@hidden defspec
-
address@hidden header-decl-sym 
address@hidden defspec
-
address@hidden header-decl-name 
address@hidden defspec
-
address@hidden header-decl-multiple? 
address@hidden defspec
-
address@hidden header-decl-parser 
address@hidden defspec
-
address@hidden header-decl-validator 
address@hidden defspec
+The focus of the @code{(web http)} module is to parse and unparse
+standard HTTP headers, representing them to Guile as native data
+structures.  For example, a @code{Date:} header will be represented as a
+SRFI-19 date record (@pxref{SRFI-19}), rather than as a string.
+
+Guile tries to follow RFCs fairly strictly---the road to perdition being
+paved with compatibility hacks---though some allowances are made for
+not-too-divergent texts.
+
+The first bit is to define a registry of parsers, validators, and
+unparsers, keyed by header name.  That is the function of the
address@hidden<header-decl>} object.
+
address@hidden make-header-decl sym name multiple? parser validator writer
address@hidden header-decl? x
address@hidden header-decl-sym decl
address@hidden header-decl-name decl
address@hidden header-decl-multiple? decl
address@hidden header-decl-parser decl
address@hidden header-decl-validator decl
address@hidden header-decl-writer decl.
+A constructor, predicate, and field accessors for the
address@hidden<header-decl>} type. The fields are as follows:
+
address@hidden @code
address@hidden sym
+The symbol name for this header field, always in lower-case.  For
+example, @code{"Content-Length"} has a symbolic name of
address@hidden
address@hidden name
+The string name of the header, in its preferred capitalization.
address@hidden multiple?
address@hidden iff this header may appear multiple times in a message.
address@hidden parser
+A procedure which takes a string and returns a parsed value.
address@hidden validator
+A predicate, returning @code{#t} iff the value is valid for this header.
address@hidden writer
+A writer, which writes a value to the port given in the second argument.
address@hidden table
address@hidden defun
 
address@hidden header-decl-writer 
address@hidden defspec
address@hidden declare-header! sym name [#:multiple?] [#:parser] [#:validator] 
[#:writer]
+Make a header declaration, as above, and register it by symbol and by
+name.
address@hidden defun
 
 @defun lookup-header-decl name
 Return the @var{header-decl} object registered for the given @var{name}.
@@ -179,15 +218,14 @@ Return the @var{header-decl} object registered for the 
given @var{name}.
 a case-insensitive fashion.
 @end defun
 
address@hidden declare-header! sym name [#:multiple?] [#:parser] [#:validator] 
[#:writer]
-Define a parser, validator, and writer for the HTTP header, @var{name}.
-
address@hidden should be a procedure that takes a string and returns a
-Scheme value. @var{validator} is a predicate for whether the given
-Scheme value is valid for this header. @var{writer} takes a value and a
-port, and writes the value to the port.
address@hidden valid-header? sym val
+Returns a true value iff @var{val} is a valid Scheme value for the
+header with name @var{sym}.
 @end defun
 
+Now that we have a generic interface for reading and writing headers, we
+do just that.
+
 @defun read-header port
 Reads one HTTP header from @var{port}. Returns two values: the header
 name and the parsed Scheme value. May raise an exception if the header
@@ -206,11 +244,6 @@ found, the header name will be returned as a symbol. If a 
parser was not
 found, both the header name and the value are returned as strings.
 @end defun
 
address@hidden valid-header? sym val
-Returns a true value iff @var{val} is a valid Scheme value for the
-header with name @var{sym}.
address@hidden defun
-
 @defun write-header name val port
 Writes the given header name and value to @var{port}. If @var{name} is a
 symbol, looks up a declared header and uses that writer. Otherwise the
@@ -227,6 +260,9 @@ Write the given header alist to @var{port}. Doesn't write 
the final
 \r\n, as the user might want to add another header.
 @end defun
 
+The @code{(web http)} module also has some utility procedures to read
+and write request and response lines.
+
 @defun parse-http-method str [start] [end]
 Parse an HTTP method from @var{str}. The result is an upper-case symbol,
 like @code{GET}.
@@ -269,26 +305,26 @@ Write the first line of an HTTP response to @var{port}.
 (use-modules (web request))
 @end example
 
address@hidden request? 
address@hidden defspec
address@hidden request? 
address@hidden defun
 
address@hidden request-method 
address@hidden defspec
address@hidden request-method 
address@hidden defun
 
address@hidden request-uri 
address@hidden defspec
address@hidden request-uri 
address@hidden defun
 
address@hidden request-version 
address@hidden defspec
address@hidden request-version 
address@hidden defun
 
address@hidden request-headers 
address@hidden defspec
address@hidden request-headers 
address@hidden defun
 
address@hidden request-meta 
address@hidden defspec
address@hidden request-meta 
address@hidden defun
 
address@hidden request-port 
address@hidden defspec
address@hidden request-port 
address@hidden defun
 
 @defun read-request port [meta]
 Read an HTTP request from @var{port}, optionally attaching the given
@@ -389,25 +425,25 @@ request @var{r}.
 @end example
 
 
address@hidden response? 
address@hidden defspec
address@hidden response? 
address@hidden defun
 
address@hidden response-version 
address@hidden defspec
address@hidden response-version 
address@hidden defun
 
address@hidden response-code 
address@hidden defspec
address@hidden response-code 
address@hidden defun
 
 @defun response-reason-phrase response
 Return the reason phrase given in @var{response}, or the standard reason
 phrase for the response's code.
 @end defun
 
address@hidden response-headers 
address@hidden defspec
address@hidden response-headers 
address@hidden defun
 
address@hidden response-port 
address@hidden defspec
address@hidden response-port 
address@hidden defun
 
 @defun read-response port
 Read an HTTP response from @var{port}, optionally attaching the given
@@ -569,8 +605,8 @@ If the user interrupts the loop, the @code{close} hook is 
called on
 the server socket.
 @end enumerate
 
address@hidden define-server-impl name open read write close
address@hidden defspec
address@hidden define-server-impl name open read write close
address@hidden defun
 
 @defun lookup-server-impl impl
 Look up a server implementation. If @var{impl} is a server


hooks/post-receive
-- 
GNU Guile