[Guile-commits] GNU Guile branch, master, updated. release_1-9-14-41-g58baff0

[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=58baff08bc9daa01b7c9a1ce3eea829b228f9611

The branch, master has been updated
       via  58baff08bc9daa01b7c9a1ce3eea829b228f9611 (commit)
      from  4a655e50a3890da9cd453a0b2c83dacc2cfcc34e (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 58baff08bc9daa01b7c9a1ce3eea829b228f9611
Author: Andy Wingo <address@hidden>
Date:   Fri Jan 7 09:31:36 2011 -0800

    revert unfinished web.texi changes
    
    These were prematurely committed in
    17072fd2c6acad1d4f2b5c98eb0d62911ea07406.

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

Summary of changes:
 doc/ref/web.texi |  238 ++++++++++++++++++------------------------------------
 1 files changed, 80 insertions(+), 158 deletions(-)

diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 0fab8d3..ca5b122 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -472,49 +472,14 @@ Write the first line of an HTTP response to @var{port}.
 @node HTTP Headers
 @subsection HTTP Headers
 
-In addition to defining the infrastructure to parse headers, the
address@hidden(web http)} module defines specific parsers and unparsers for all
-headers defined in the HTTP/1.1 standard.
-
-For example, if you receive a header named @samp{Accept-Language} with a
-value @samp{en, es;q=0.8}, Guile parses it as follows:
-
address@hidden
-(parse-header "Accept-Language" "en, es;q=0.8")
address@hidden accept-language
address@hidden ((1000 . "en") (800 . "es"))
address@hidden example
-
-There are two results, because @code{parse-header} returns two
-values.  The first value is a symbol, because the @code{accept-language}
-header is known to Guile and has a parser registered.  The format of the
-value for @code{accept-language} headers is defined below, along with
-all other headers defined in the HTTP standard.  (If the header were not
-recognized, it and the value would be returned as strings.)
-
-For brevity, the header definitions below are given in the form,
address@hidden @address@hidden, indicating that values for the header
address@hidden@var{name}} will be of the given @var{type}.  A short description
-of the each header's purpose and an example follow.  For full details on
-the meanings of all of these headers, see the HTTP 1.1 standard, RFC
-2616.
-
address@hidden HTTP Header Types
address@hidden {HTTP Header Type} Date
-foo
address@hidden deftp
-
-So for example if you are implementing a
-
-This section describes the
+The @code{(web http)} module defines parsers and unparsers for all
+headers defined in the HTTP/1.1 standard.  This section describes the
 parsed format of the various headers.
 
 We cannot describe the function of all of these headers, however, in
 sufficient detail.  The interested reader would do well to download a
 copy of RFC 2616 and have it on hand.
 
-example? and examples in each, and brief meaning description.
-
 To begin with, we should make a few definitions:
 
 @table @dfn
@@ -526,6 +491,11 @@ which is the symbol or string key, and the cdr is the 
parsed value.
 Parsed values for known keys have key-dependent formats.  Parsed values
 for unknown keys are strings.
 
address@hidden param list
+A param list is a list of key-value lists.  When serialized to a string,
+items in the inner lists are separated by semicolons.  Again, known keys
+are parsed to symbols.
+
 @item quality
 A number of headers have quality values in them, which are decimal
 fractions between zero and one indicating a preference for various kinds
@@ -545,7 +515,8 @@ true iff the entity tag is a ``strong'' entity tag.
 
 @subsubsection General Headers
 
address@hidden {HTTP Header} KVList cache-control
address@hidden @code
address@hidden cache-control
 A key-value list of cache-control directives. Known keys are
 @code{max-age}, @code{max-stale}, @code{min-fresh},
 @code{must-revalidate}, @code{no-cache}, @code{no-store},
@@ -559,82 +530,68 @@ integers.
 If present, parameters to @code{private} and @code{no-cache} are parsed
 as lists of header names, represented as symbols if they are known
 headers or strings otherwise.
address@hidden deftypevr
 
address@hidden {HTTP Header} @i{List of Strings} connection
address@hidden connection
 A list of connection tokens.  A connection token is a string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {date} date
address@hidden date
 A SRFI-19 date record.
address@hidden deftypevr
 
address@hidden {HTTP Header} {Key-Value List} pragma
address@hidden pragma
 A key-value list of pragma directives.  @code{no-cache} is the only
 known key.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} trailer
address@hidden trailer
 A list of header names.  Known header names are parsed to symbols,
 otherwise they are left as strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} transfer-encoding
address@hidden transfer-encoding
 A param list of transfer codings.  @code{chunked} is the only known key.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} upgrade
address@hidden upgrade
 A list of strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} via
address@hidden via
 A list of strings.  There may be multiple @code{via} headers in ne
 message.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} warning
address@hidden warning
 A list of warnings.  Each warning is a itself a list of four elements: a
 code, as an exact integer between 0 and 1000, a host as a string, the
 warning text as a string, and either @code{#f} or a SRFI-19 date.
 
 There may be multiple @code{warning} headers in one message.
address@hidden deftypevr
address@hidden table
 
 
 @subsubsection Entity Headers
 
address@hidden {HTTP Header} {tp} allow
address@hidden @code
address@hidden allow
 A list of methods, as strings.  Methods are parsed as strings instead of
 @code{parse-http-method} so as to allow for new methods.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-encoding
address@hidden content-encoding
 A list of content codings, as strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-language
address@hidden content-language
 A list of language tags, as strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-length
address@hidden content-length
 An exact, non-negative integer.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-location
address@hidden content-location
 A URI record.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-md5
address@hidden content-md5
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-range
address@hidden content-range
 A list of three elements: the symbol @code{bytes}, either the symbol
 @code{*} or a pair of integers, indicating the byte rage, and either
 @code{*} or an integer, for the instance length.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} content-type
address@hidden content-type
 A pair, the car of which is the media type as a string, and the cdr is
 an alist of parameters, with strings as keys and values.
 
@@ -642,144 +599,116 @@ For example, @code{"text/plain"} parses as 
@code{("text/plain")}, and
 @code{"text/plain;charset=utf-8"} parses as @code{("text/plain"
 ("charset" . "utf-8"))}.
 
-note charset and encoding
address@hidden deftypevr
-
address@hidden {HTTP Header} {tp} expires
address@hidden expires
 A SRFI-19 date.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} last-modified
address@hidden last-modified
 A SRFI-19 date.
address@hidden deftypevr
+
address@hidden table
 
 
 @subsubsection Request Headers
 
address@hidden {HTTP Header} {tp} accept
address@hidden @code
address@hidden accept
 A param list.  Each element in the list indicates one media-range
 with accept-params.  They only known key is @code{q}, whose value is
 parsed as a quality value.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} accept-charset
address@hidden accept-charset
 A quality-list of charsets, as strings.
 
-charset and encoding
address@hidden deftypevr
address@hidden {HTTP Header} {tp} accept-encoding
address@hidden accept-encoding
 A quality-list of content codings, as strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} accept-language
address@hidden accept-language
 A quality-list of languages, as strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} authorization
address@hidden authorization
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} expect
address@hidden expect
 A param list of expectations.  The only known key is
 @code{100-continue}.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} from
address@hidden from
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} host
address@hidden host
 A pair of the host, as a string, and the port, as an integer. If no port
 is given, port is @code{#f}.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} if-match
address@hidden if-match
 Either the symbol @code{*}, or a list of entity tags (see above).
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} if-modified-since
address@hidden if-modified-since
 A SRFI-19 date.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} if-none-match
address@hidden if-none-match
 Either the symbol @code{*}, or a list of entity tags (see above).
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} if-range
address@hidden if-range
 Either an entity tag, or a SRFI-19 date.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} if-unmodified-since
address@hidden if-unmodified-since
 A SRFI-19 date.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} max-forwards
address@hidden max-forwards
 An exact non-negative integer.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} proxy-authorization
address@hidden proxy-authorization
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} range
address@hidden range
 A pair whose car is the symbol @code{bytes}, and whose cdr is a list of
 pairs. Each element of the cdr indicates a range; the car is the first
 byte position and the cdr is the last byte position, as integers, or
 @code{#f} if not given.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} referer
address@hidden referer
 A URI.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} te
address@hidden te
 A param list of transfer-codings.  The only known key is
 @code{trailers}.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} user-agent
address@hidden user-agent
 A string.
address@hidden deftypevr
address@hidden table
 
 
 @subsubsection Response Headers
 
address@hidden {HTTP Header} {tp} accept-ranges
address@hidden @code
address@hidden accept-ranges
 A list of strings.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} age
address@hidden age
 An exact, non-negative integer.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} etag
address@hidden etag
 An entity tag.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} location
address@hidden location
 A URI.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} proxy-authenticate
address@hidden proxy-authenticate
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} retry-after
address@hidden retry-after
 Either an exact, non-negative integer, or a SRFI-19 date.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} server
address@hidden server
 A string.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} vary
address@hidden vary
 Either the symbol @code{*}, or a list of headers, with known headers
 parsed to symbols.
address@hidden deftypevr
 
address@hidden {HTTP Header} {tp} www-authenticate
-A string. (FIXME)
address@hidden deftypevr
address@hidden www-authenticate
+A string.
address@hidden table
 
 
 @node Requests
@@ -794,8 +723,6 @@ the body is not part of the request, but the port is.  Once 
you have
 read a request, you may read the body separately, and likewise for
 writing requests.
 
-discussion of charsets and bytes and stuff.
-
 @defun build-request [#:method] [#:uri] [#:version] [#:headers] [#:port] 
[#:meta] [#:validate-headers?]
 Construct an HTTP request object. If @var{validate-headers?} is true,
 the headers are each run through their respective validators.
@@ -838,12 +765,10 @@ discussion of character sets in "HTTP Requests" in the 
manual, for more
 information.
 @end defun
 
-Fixme^
-
 @defun write-request r port
 Write the given HTTP request to @var{port}.
 
-Return a new request, whose @code{request-port} will continue writing
+Returns a new request, whose @code{request-port} will continue writing
 on @var{port}, perhaps using some transfer encoding.
 @end defun
 
@@ -852,7 +777,7 @@ Reads the request body from @var{r}, as a string.
 
 Assumes that the request port has ISO-8859-1 encoding, so that the
 number of characters to read is the same as the
address@hidden  Return @code{#f} if there was no request
address@hidden Returns @code{#f} if there was no request
 body.
 @end defun
 
@@ -862,7 +787,7 @@ corresponding to the HTTP request @var{r}.
 @end defun
 
 @defun read-request-body/bytevector r
-Reads the request body from @var{r}, as a bytevector.  Return @code{#f}
+Reads the request body from @var{r}, as a bytevector. Returns @code{#f}
 if there was no request body.
 @end defun
 
@@ -971,14 +896,13 @@ Construct an HTTP response object. If 
@var{validate-headers?} is true,
 the headers are each run through their respective validators.
 @end defun
 
-FIXME
 @defun extend-response r k v . additional
 Extend an HTTP response by setting additional HTTP headers @var{k},
address@hidden  Return a new HTTP response.
address@hidden Returns a new HTTP response.
 @end defun
 
 @defun adapt-response-version response version
-Adapt the given response to a different HTTP version.  Return a new HTTP
+Adapt the given response to a different HTTP version. Returns a new HTTP
 response.
 
 The idea is that many applications might just build a response for the
@@ -991,7 +915,7 @@ the version field.
 @defun write-response r port
 Write the given HTTP response to @var{port}.
 
-Return a new response, whose @code{response-port} will continue writing
+Returns a new response, whose @code{response-port} will continue writing
 on @var{port}, perhaps using some transfer encoding.
 @end defun
 
@@ -1000,7 +924,7 @@ Reads the response body from @var{r}, as a string.
 
 Assumes that the response port has ISO-8859-1 encoding, so that the
 number of characters to read is the same as the
address@hidden Return @code{#f} if there was no
address@hidden Returns @code{#f} if there was no
 response body.
 @end defun
 
@@ -1010,7 +934,7 @@ corresponding to the HTTP response @var{r}.
 @end defun
 
 @defun read-response-body/bytevector r
-Read the response body from @var{r}, as a bytevector.  Return @code{#f}
+Reads the response body from @var{r}, as a bytevector. Returns @code{#f}
 if there was no response body.
 @end defun
 
@@ -1104,7 +1028,7 @@ A user-provided handler procedure is called, with the 
request
 and body as its arguments.  The handler should return two
 values: the response, as a @code{<response>} record from @code{(web
 response)}, and the response body as a string, bytevector, or
address@hidden if not present.  We also allow the response to be simply an
address@hidden if not present.  We also allow the reponse to be simply an
 alist of headers, in which case a default response object is
 constructed with those headers.
 
@@ -1147,16 +1071,16 @@ that we don't expose the accessors for the various 
fields of a
 any access to the impl objects.
 
 @defun open-server impl open-params
-Open a server for the given implementation.  Return one value, the new
+Open a server for the given implementation. Returns one value, the new
 server object. The implementation's @code{open} procedure is applied to
 @var{open-params}, which should be a list.
 @end defun
 
 @defun read-client impl server
 Read a new client from @var{server}, by applying the implementation's
address@hidden procedure to the server.  If successful, return three
address@hidden procedure to the server. If successful, returns three
 values: an object corresponding to the client, a request object, and the
-request body. If any exception occurs, return @code{#f} for all three
+request body. If any exception occurs, returns @code{#f} for all three
 values.
 @end defun
 
@@ -1208,7 +1132,7 @@ Given the procedures above, it is a small matter to make 
a web server:
 
 @defun serve-one-client handler impl server state
 Read one request from @var{server}, call @var{handler} on the request
-and body, and write the response to the client.  Return the new state
+and body, and write the response to the client. Returns the new state
 produced by the handler procedure.
 @end defun
 
@@ -1236,8 +1160,6 @@ Additional return values are accumulated into a new 
@var{state}, which
 will be used for subsequent requests. In this way a handler can
 explicitly manage its state.
 
-FIXME: elide?
-
 The default server implementation is @code{http}, which accepts
 @var{open-params} like @code{(#:port 8081)}, among others. See "Web
 Server" in the manual, for more information.
@@ -1413,9 +1335,9 @@ Here we see the power of keyword arguments with default 
initializers. By
 the time the arguments are fully parsed, the @code{sxml} local variable
 will hold the templated SXML, ready for sending out to the client.
 
-Also, instead of returning the body as a string, @code{respond} gives a
-procedure, which will be called by the web server to write out the
-response to the client.
+Instead of returning the body as a string, here we give a procedure,
+which will be called by the web server to write out the response to the
+client.
 
 Now, a simple example using this responder, which lays out the incoming
 headers in an HTML table.


hooks/post-receive
-- 
GNU Guile