From e471a3ee2f84979cee8b3d6f2301986aa2ba7c60 Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Thu, 16 Dec 2010 19:31:50 +0100 Subject: [PATCH] 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. --- doc/ref/web.texi | 134 +++++++++++++++++++++++++++++++---------------- 1 file changed, 88 insertions(+), 46 deletions(-) diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 90e7edfcf..47025c5b3 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 +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. + +@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. +@end defun + @defun request? -@end defun - -@defun request-method -@end defun - -@defun request-uri -@end defun - -@defun request-version -@end defun - -@defun request-headers -@end defun - -@defun request-meta -@end defun - -@defun request-port +@defunx request-method +@defunx request-uri +@defunx request-version +@defunx request-headers +@defunx request-meta +@defunx request-port +A predicate and field accessors for the request type. The fields are as +follows: +@table @code +@item method +The HTTP method, for example, @code{GET}. +@item uri +The URI as a URI record. +@item version +The HTTP version pair, like @code{(1 . 1)}. +@item headers +The request headers, as an alist of parsed values. +@item meta +An arbitrary alist of other data, for example information returned in +the @code{sockaddr} from @code{accept} (@pxref{Network Sockets and +Communication}). +@item port +The port on which to read or write a request body, if any. +@end 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 -@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. -@end 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 +@code{host} 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? -@end defun - -@defun response-version -@end defun - -@defun response-code -@end 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 - -@defun response-headers -@end defun - -@defun response-port +@defunx response-version +@defunx response-code +@defunx response-reason-phrase response +@defunx response-headers +@defunx response-port +A predicate and field accessors for the response type. The fields are as +follows: +@table @code +@item version +The HTTP version pair, like @code{(1 . 1)}. +@item code +The HTTP response code, like @code{200}. +@item reason-phrase +The reason phrase, or the standard reason phrase for the response's +code. +@item headers +The response headers, as an alist of parsed values. +@item port +The port on which to read or write a response body, if any. +@end 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. +@xref{HTTP 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 -@node Web Handlers -@subsection 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 +@node Web Examples +@subsection Web Examples + +This section has yet to be written, really. But for now, try this: + +@example + (use-modules (web server)) + + (define (handler request body) + (values '((content-type . ("text/plain"))) + "Hello, World!")) + (run-server handler) +@end 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: