diff options
-rw-r--r-- | doc/ref/web.texi | 70 | ||||
-rw-r--r-- | module/web/client.scm | 6 | ||||
-rw-r--r-- | module/web/http.scm | 6 | ||||
-rw-r--r-- | module/web/response.scm | 6 | ||||
-rw-r--r-- | module/web/uri.scm | 28 |
5 files changed, 61 insertions, 55 deletions
diff --git a/doc/ref/web.texi b/doc/ref/web.texi index 70e0f2e43..0d41f9f7a 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -10,7 +10,7 @@ @cindex HTTP It has always been possible to connect computers together and share -information between them, but the rise of the World-Wide Web over the +information between them, but the rise of the World Wide Web over the last couple of decades has made it much easier to do so. The result is a richly connected network of computation, in which Guile forms a part. @@ -206,9 +206,10 @@ 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. -@deffn {Scheme Procedure} build-uri scheme [#:userinfo=@code{#f}] [#:host=@code{#f}] @ - [#:port=@code{#f}] [#:path=@code{""}] [#:query=@code{#f}] @ - [#:fragment=@code{#f}] [#:validate?=@code{#t}] +@deffn {Scheme Procedure} build-uri scheme @ + [#:userinfo=@code{#f}] [#:host=@code{#f}] [#:port=@code{#f}] @ + [#:path=@code{""}] [#:query=@code{#f}] [#:fragment=@code{#f}] @ + [#:validate?=@code{#t}] Construct a URI object. @var{scheme} should be a symbol, @var{port} either a positive, exact integer or @code{#f}, and the rest of the fields are either strings or @code{#f}. If @var{validate?} is true, @@ -216,7 +217,7 @@ also run some consistency checks to make sure that the constructed URI is valid. @end deffn -@deffn {Scheme Procedure} uri? x +@deffn {Scheme Procedure} uri? obj @deffnx {Scheme Procedure} uri-scheme uri @deffnx {Scheme Procedure} uri-userinfo uri @deffnx {Scheme Procedure} uri-host uri @@ -249,9 +250,9 @@ Percent-decode the given @var{str}, according to @var{encoding}, which should be the name of a character encoding. Note that this function should not generally be applied to a full URI -string. For paths, use split-and-decode-uri-path instead. For query -strings, split the query on @code{&} and @code{=} boundaries, and decode -the components separately. +string. For paths, use @code{split-and-decode-uri-path} instead. For +query strings, split the query on @code{&} and @code{=} boundaries, and +decode the components separately. Note also that percent-encoded strings encode @emph{bytes}, not characters. There is no guarantee that a given byte sequence is a valid @@ -378,7 +379,8 @@ For more on the set of headers that Guile knows about out of the box, @pxref{HTTP Headers}. To add your own, use the @code{declare-header!} procedure: -@deffn {Scheme Procedure} declare-header! name parser validator writer [#:multiple?=@code{#f}] +@deffn {Scheme Procedure} declare-header! name parser validator writer @ + [#:multiple?=@code{#f}] Declare a parser, validator, and writer for a given header. @end deffn @@ -450,7 +452,7 @@ like @code{GET}. @end deffn @deffn {Scheme Procedure} parse-http-version str [start] [end] -Parse an HTTP version from @var{str}, returning it as a major-minor +Parse an HTTP version from @var{str}, returning it as a major--minor pair. For example, @code{HTTP/1.1} parses as the pair of integers, @code{(1 . 1)}. @end deffn @@ -471,7 +473,7 @@ Write the first line of an HTTP request to @var{port}. @deffn {Scheme Procedure} read-response-line port Read the first line of an HTTP response from @var{port}, returning three -values: the HTTP version, the response code, and the "reason phrase". +values: the HTTP version, the response code, and the ``reason phrase''. @end deffn @deffn {Scheme Procedure} write-response-line version code reason-phrase port @@ -1130,13 +1132,13 @@ any loss of generality. @subsubsection Request API -@deffn {Scheme Procedure} request? -@deffnx {Scheme Procedure} request-method -@deffnx {Scheme Procedure} request-uri -@deffnx {Scheme Procedure} request-version -@deffnx {Scheme Procedure} request-headers -@deffnx {Scheme Procedure} request-meta -@deffnx {Scheme Procedure} request-port +@deffn {Scheme Procedure} request? obj +@deffnx {Scheme Procedure} request-method request +@deffnx {Scheme Procedure} request-uri request +@deffnx {Scheme Procedure} request-version request +@deffnx {Scheme Procedure} request-headers request +@deffnx {Scheme Procedure} request-meta request +@deffnx {Scheme Procedure} request-port request A predicate and field accessors for the request type. The fields are as follows: @table @code @@ -1170,7 +1172,9 @@ request, you may read the body separately, and likewise for writing requests. @end deffn -@deffn {Scheme Procedure} build-request uri [#:method='GET] [#:version='(1 . 1)] [#:headers='()] [#:port=#f] [#:meta='()] [#:validate-headers?=#t] +@deffn {Scheme Procedure} build-request uri [#:method='GET] @ + [#:version='(1 . 1)] [#:headers='()] [#:port=#f] [#:meta='()] @ + [#:validate-headers?=#t] Construct an HTTP request object. If @var{validate-headers?} is true, the headers are each run through their respective validators. @end deffn @@ -1253,12 +1257,12 @@ A helper routine to determine the absolute URI of a request, using the As with requests (@pxref{Requests}), Guile offers a data type for HTTP responses. Again, the body is represented separately from the request. -@deffn {Scheme Procedure} response? -@deffnx {Scheme Procedure} response-version -@deffnx {Scheme Procedure} response-code +@deffn {Scheme Procedure} response? obj +@deffnx {Scheme Procedure} response-version response +@deffnx {Scheme Procedure} response-code response @deffnx {Scheme Procedure} response-reason-phrase response -@deffnx {Scheme Procedure} response-headers -@deffnx {Scheme Procedure} response-port +@deffnx {Scheme Procedure} response-headers response +@deffnx {Scheme Procedure} response-port response A predicate and field accessors for the response type. The fields are as follows: @table @code @@ -1384,6 +1388,10 @@ Return @code{#t} if @var{type}, a symbol as returned by @code{(web client)} provides a simple, synchronous HTTP client, built on the lower-level HTTP, request, and response modules. +@example +(use-modules (web client)) +@end example + @deffn {Scheme Procedure} open-socket-for-uri uri Return an open input/output port for a connection to URI. @end deffn @@ -1419,9 +1427,9 @@ If you already have a port open, pass it as @var{port}. Otherwise, a connection will be opened to the server corresponding to @var{uri}. Any extra headers in the alist @var{headers} will be added to the request. -If @var{body} is not #f, a message body will also be sent with the HTTP -request. If @var{body} is a string, it is encoded according to the -content-type in @var{headers}, defaulting to UTF-8. Otherwise +If @var{body} is not @code{#f}, a message body will also be sent with +the HTTP request. If @var{body} is a string, it is encoded according to +the content-type in @var{headers}, defaulting to UTF-8. Otherwise @var{body} should be a bytevector, or @code{#f} for no body. Although a message body may be sent with any request, usually only @code{POST} and @code{PUT} requests have bodies. @@ -1480,8 +1488,8 @@ The life cycle of a server goes as follows: @enumerate @item -The @code{open} hook is called, to open the server. @code{open} takes 0 or -more arguments, depending on the backend, and returns an opaque +The @code{open} hook is called, to open the server. @code{open} takes +zero or more arguments, depending on the backend, and returns an opaque server socket object, or signals an error. @item @@ -1578,8 +1586,8 @@ in, allowing the user's handler to explicitly manage its state. @end deffn @deffn {Scheme Procedure} sanitize-response request response body -"Sanitize" the given response and body, making them appropriate for the -given request. +``Sanitize'' the given response and body, making them appropriate for +the given request. As a convenience to web handler authors, @var{response} may be given as an alist of headers, in which case it is used to construct a default diff --git a/module/web/client.scm b/module/web/client.scm index 9fbb25bba..7d5ea4989 100644 --- a/module/web/client.scm +++ b/module/web/client.scm @@ -248,10 +248,10 @@ pass it as PORT. The port will be closed at the end of the request unless KEEP-ALIVE? is true. Any extra headers in the alist HEADERS will be added to the request. -If BODY is not #f, a message body will also be sent with the HTTP +If BODY is not ‘#f’, a message body will also be sent with the HTTP request. If BODY is a string, it is encoded according to the content-type in HEADERS, defaulting to UTF-8. Otherwise BODY should be -a bytevector, or #f for no body. Although it's allowed to send a +a bytevector, or ‘#f’ for no body. Although it's allowed to send a message body along with any request, usually only POST and PUT requests have bodies. See ‘http-put’ and ‘http-post’ documentation, for more. @@ -317,7 +317,7 @@ This function is similar to ‘http-get’, except it uses the \"HEAD\" method. See ‘http-get’ for full documentation on the various keyword arguments that are accepted by this function. -Returns two values: the resulting response, and #f. Responses to HEAD +Returns two values: the resulting response, and ‘#f’. Responses to HEAD requests do not have a body. The second value is only returned so that other procedures can treat all of the http-foo verbs identically.") diff --git a/module/web/http.scm b/module/web/http.scm index c79d57d78..712208b69 100644 --- a/module/web/http.scm +++ b/module/web/http.scm @@ -167,7 +167,7 @@ The default writer is ‘display’." (define *eof* (call-with-input-string "" read)) (define (read-header port) - "Reads one HTTP header from PORT. Returns two values: the header + "Read one HTTP header from PORT. Return two values: the header name and the parsed Scheme value. May raise an exception if the header was known but the value was invalid. @@ -220,7 +220,7 @@ as an ordered alist." (define (write-headers headers port) "Write the given header alist to PORT. Doesn't write the final -@samp{\\r\\n}, as the user might want to add another header." +‘\\r\\n’, as the user might want to add another header." (let lp ((headers headers)) (if (pair? headers) (begin @@ -971,7 +971,7 @@ as an ordered alist." (define *known-versions* '()) (define* (parse-http-version str #:optional (start 0) (end (string-length str))) - "Parse an HTTP version from STR, returning it as a major-minor + "Parse an HTTP version from STR, returning it as a major–minor pair. For example, ‘HTTP/1.1’ parses as the pair of integers, ‘(1 . 1)’." (or (let lp ((known *known-versions*)) diff --git a/module/web/response.scm b/module/web/response.scm index 3f97dffa5..570a2d7d2 100644 --- a/module/web/response.scm +++ b/module/web/response.scm @@ -267,10 +267,10 @@ closes PORT, unless KEEP-ALIVE? is true." (define* (response-body-port r #:key (decode? #t) (keep-alive? #t)) "Return an input port from which the body of R can be read. The encoding of the returned port is set according to R's ‘content-type’ -header, when it's textual, except if DECODE? is #f. Return #f when no -body is available. +header, when it's textual, except if DECODE? is ‘#f’. Return #f when +no body is available. -When KEEP-ALIVE? is #f, closing the returned port also closes R's +When KEEP-ALIVE? is ‘#f’, closing the returned port also closes R's response port." (define port (cond diff --git a/module/web/uri.scm b/module/web/uri.scm index 25406b368..7fe010096 100644 --- a/module/web/uri.scm +++ b/module/web/uri.scm @@ -53,8 +53,8 @@ (query uri-query) (fragment uri-fragment)) -(define (absolute-uri? x) - (and (uri? x) (uri-scheme x) #t)) +(define (absolute-uri? obj) + (and (uri? obj) (uri-scheme obj) #t)) (define (uri-error message . args) (throw 'uri-error message args)) @@ -309,17 +309,16 @@ serialization." which should be the name of a character encoding. Note that this function should not generally be applied to a full URI -string. For paths, use split-and-decode-uri-path instead. For query +string. For paths, use ‘split-and-decode-uri-path’ instead. For query strings, split the query on ‘&’ and ‘=’ boundaries, and decode the components separately. -Note also that percent-encoded strings encode @emph{bytes}, not -characters. There is no guarantee that a given byte sequence is a valid -string encoding. Therefore this routine may signal an error if the -decoded bytes are not valid for the given encoding. Pass ‘#f’ for -ENCODING if you want decoded bytes as a bytevector directly. -@xref{Ports, ‘set-port-encoding!’}, for more information on -character encodings. +Note also that percent-encoded strings encode _bytes_, not characters. +There is no guarantee that a given byte sequence is a valid string +encoding. Therefore this routine may signal an error if the decoded +bytes are not valid for the given encoding. Pass ‘#f’ for ENCODING if +you want decoded bytes as a bytevector directly. ‘set-port-encoding!’, +for more information on character encodings. Returns a string of the decoded characters, or a bytevector if ENCODING was ‘#f’." @@ -380,11 +379,10 @@ ENCODING was ‘#f’." UNESCAPED-CHARS. The default character set includes alphanumerics from ASCII, as well as -the special characters @samp{-}, @samp{.}, @samp{_}, and @samp{~}. Any -other character will be percent-encoded, by writing out the character to -a bytevector within the given ENCODING, then encoding each byte as -‘%HH’, where HH is the hexadecimal representation of -the byte." +the special characters ‘-’, ‘.’, ‘_’, and ‘~’. Any other character will +be percent-encoded, by writing out the character to a bytevector within +the given ENCODING, then encoding each byte as ‘%HH’, where HH is the +hexadecimal representation of the byte." (define (needs-escaped? ch) (not (char-set-contains? unescaped-chars ch))) (if (string-index str needs-escaped?) |