[Guile-commits] GNU Guile branch, master, updated. release_1-9-13-200-g0bfba83

[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=0bfba83a038ba03924eb82841407d387310181d5

The branch, master has been updated
       via  0bfba83a038ba03924eb82841407d387310181d5 (commit)
       via  92022c447d884d32fc05507ec82f672b28a6b676 (commit)
       via  e471a3ee2f84979cee8b3d6f2301986aa2ba7c60 (commit)
      from  1148d029736fea3e3e5002f7a042565a1ecc6623 (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 0bfba83a038ba03924eb82841407d387310181d5
Author: Andy Wingo <address@hidden>
Date:   Thu Dec 16 19:38:48 2010 +0100

    update web-response tests for http header parsing change
    
    * test-suite/tests/web-response.test ("example-1"): Update for change in
      parsing Vary header.

commit 92022c447d884d32fc05507ec82f672b28a6b676
Author: Andy Wingo <address@hidden>
Date:   Thu Dec 16 19:33:16 2010 +0100

    update NEWS
    
    * NEWS: Update for Web documentation.

commit e471a3ee2f84979cee8b3d6f2301986aa2ba7c60
Author: Andy Wingo <address@hidden>
Date:   Thu Dec 16 19:31:50 2010 +0100

    more web.texi work
    
    * doc/ref/web.texi (Requests, Responses): Flesh out.
      (Web Examples): New section, replacing "Web Handlers". The only one
      that's not really written yet.

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

Summary of changes:
 NEWS                               |    7 +-
 doc/ref/web.texi                   |  130 ++++++++++++++++++++++++------------
 test-suite/tests/web-response.test |    2 +-
 3 files changed, 91 insertions(+), 48 deletions(-)

diff --git a/NEWS b/NEWS
index b2fbb2e..cd1e5b9 100644
--- a/NEWS
+++ b/NEWS
@@ -31,12 +31,13 @@ Rottmann.
 ** New module: `(ice-9 poll)', a poll wrapper
 ** New module: `(web server http)', HTTP-over-TCP web server implementation
 
-These modules are as yet without documentation.  But try the following
-command line:
+See "Web" in the manual, for more information, but as a taste of things,
+try the following command line:
 
   meta/guile examples/web/debug-sxml.scm
 
-Then visit localhost:8080 in your web browser.  Let us know how it goes!
+Then visit http://localhost:8080/ in your web browser.  Let us know how
+it goes!
 
 ** Better Emacs Lisp implementation
 
diff --git a/doc/ref/web.texi b/doc/ref/web.texi
index 90e7edf..47025c5 100644
--- a/doc/ref/web.texi
+++ b/doc/ref/web.texi
@@ -36,8 +36,8 @@ the thing?  Read on!
 * HTTP Headers::                How Guile represents specific header values.
 * Requests::                    HTTP requests.
 * Responses::                   HTTP responses.
-* Web Handlers::                A simple web application interface.
 * Web Server::                  Serving HTTP to the internet.
+* Web Examples::                How to use this thing.
 @end menu
 
 @node URIs
@@ -548,25 +548,41 @@ A string.
 (use-modules (web request))
 @end example
 
address@hidden request? 
address@hidden defun
-
address@hidden request-method 
address@hidden defun
+The request module contains a data type for HTTP requests.  Note that
+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.
 
address@hidden request-uri 
address@hidden defun
-
address@hidden request-version 
address@hidden defun
-
address@hidden request-headers 
address@hidden defun
-
address@hidden request-meta 
address@hidden 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.
 @end defun
 
address@hidden request-port 
address@hidden request? 
address@hidden request-method 
address@hidden request-uri 
address@hidden request-version 
address@hidden request-headers 
address@hidden request-meta 
address@hidden request-port 
+A predicate and field accessors for the request type.  The fields are as
+follows:
address@hidden @code
address@hidden method
+The HTTP method, for example, @code{GET}.
address@hidden uri
+The URI as a URI record.
address@hidden version
+The HTTP version pair, like @code{(1 . 1)}.
address@hidden headers
+The request headers, as an alist of parsed values.
address@hidden meta
+An arbitrary alist of other data, for example information returned in
+the @code{sockaddr} from @code{accept} (@pxref{Network Sockets and
+Communication}).
address@hidden port
+The port on which to read or write a request body, if any.
address@hidden table
 @end defun
 
 @defun read-request port [meta]
@@ -579,11 +595,6 @@ discussion of character sets in "HTTP Requests" in the 
manual, for more
 information.
 @end defun
 
address@hidden 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.
address@hidden defun
-
 @defun write-request r port
 Write the given HTTP request to @var{port}.
 
@@ -615,6 +626,10 @@ Write @var{body}, a bytevector, to the port corresponding 
to the HTTP
 request @var{r}.
 @end defun
 
+The various headers that are typically associated with HTTP requests may
+be accessed with these dedicated accessors.  @xref{HTTP Headers}, for
+more information on the format of parsed headers.
+
 @defun request-accept request [default='()]
 @defunx request-accept-charset request [default='()]
 @defunx request-accept-encoding request [default='()]
@@ -653,9 +668,12 @@ request @var{r}.
 @defunx request-user-agent request [default=#f]
 @defunx request-via request [default='()]
 @defunx request-warning request [default='()]
+Return the given request header, or @var{default} if none was present.
 @end defun
 
 @defun request-absolute-uri r [default-host] [default-port]
+A helper routine to determine the absolute URI of a request, using the
address@hidden header and the default host and port.
 @end defun
 
 
@@ -667,25 +685,30 @@ request @var{r}.
 (use-modules (web response))
 @end example
 
+As with requests (@pxref{Requests}), Guile offers a data type for HTTP
+responses.  Again, the body is represented separately from the request.
 
 @defun response? 
address@hidden defun
-
address@hidden response-version 
address@hidden defun
-
address@hidden response-code 
address@hidden defun
-
address@hidden response-reason-phrase response
-Return the reason phrase given in @var{response}, or the standard reason
-phrase for the response's code.
address@hidden defun
-
address@hidden response-headers 
address@hidden defun
-
address@hidden response-port 
address@hidden response-version 
address@hidden response-code 
address@hidden response-reason-phrase response
address@hidden response-headers 
address@hidden response-port 
+A predicate and field accessors for the response type.  The fields are as
+follows:
address@hidden @code
address@hidden version
+The HTTP version pair, like @code{(1 . 1)}.
address@hidden code
+The HTTP response code, like @code{200}.
address@hidden reason-phrase
+The reason phrase, or the standard reason phrase for the response's
+code.
address@hidden headers
+The response headers, as an alist of parsed values.
address@hidden port
+The port on which to read or write a response body, if any.
address@hidden table
 @end defun
 
 @defun read-response port
@@ -750,6 +773,11 @@ Write @var{body}, a bytevector, to the port corresponding 
to the HTTP
 response @var{r}.
 @end defun
 
+As with requests, the various headers that are typically associated with
+HTTP responses may be accessed with these dedicated accessors.
address@hidden Headers}, for more information on the format of parsed
+headers.
+
 @defun response-accept-ranges response [default=#f]
 @defunx response-age response [default='()]
 @defunx response-allow response [default='()]
@@ -778,14 +806,10 @@ response @var{r}.
 @defunx response-via response [default='()]
 @defunx response-warning response [default='()]
 @defunx response-www-authenticate response [default=#f]
+Return the given request header, or @var{default} if none was present.
 @end defun
 
 
address@hidden Web Handlers
address@hidden Web Handlers
-
-from request to response
-
 @node Web Server
 @subsection Web Server
 
@@ -959,6 +983,24 @@ Server" in the manual, for more information.
 @end example
 
 
address@hidden Web Examples
address@hidden Web Examples
+
+This section has yet to be written, really. But for now, try this:
+
address@hidden 
+ (use-modules (web server))
+
+ (define (handler request body)
+   (values '((content-type . ("text/plain")))
+           "Hello, World!"))
+ (run-server handler)
address@hidden example
+
+Then visit @code{http://localhost:8080/} on your web browser.  Let us
+know how it goes!
+
+
 @c Local Variables:
 @c TeX-master: "guile.texi"
 @c End:
diff --git a/test-suite/tests/web-response.test 
b/test-suite/tests/web-response.test
index 41cd3d1..7c94275 100644
--- a/test-suite/tests/web-response.test
+++ b/test-suite/tests/web-response.test
@@ -76,7 +76,7 @@ abcdefghijklmnopqrstuvwxyz0123456789")
          (cache-control . ((max-age . 543234)))
          (expires . ,(string->date "Thu, 28 Oct 2010 15:33:13 GMT +0000"
                                    "~a, ~d ~b ~Y ~H:~M:~S ~z"))
-         (vary . ("Accept-Encoding"))
+         (vary . (accept-encoding))
          (content-encoding . ("gzip"))
          (content-length . 36)
          (content-type . ("text/html" ("charset" . "utf-8"))))))


hooks/post-receive
-- 
GNU Guile