summaryrefslogtreecommitdiff
path: root/module/web/response.scm
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-12-16 12:21:56 +0100
committerAndy Wingo <wingo@pobox.com>2010-12-16 14:48:34 +0100
commitcc1e26c2cd015fe17a9c581ba3c0f523508f897a (patch)
tree0e429da48646e1ca7a10777169ffcccd7e98e6bc /module/web/response.scm
parent92c5c0b67c873a38ba0884b0199ac43f7edfaf1e (diff)
downloadguile-cc1e26c2cd015fe17a9c581ba3c0f523508f897a.tar.gz
docstrings in (web request) and (web response)
* module/web/request.scm: * module/web/response.scm: Add docstrings.
Diffstat (limited to 'module/web/response.scm')
-rw-r--r--module/web/response.scm39
1 files changed, 38 insertions, 1 deletions
diff --git a/module/web/response.scm b/module/web/response.scm
index c3c69cd4d..295b2f4bf 100644
--- a/module/web/response.scm
+++ b/module/web/response.scm
@@ -95,9 +95,13 @@
(define* (build-response #:key (version '(1 . 1)) (code 200) reason-phrase
(headers '()) port)
+ "Construct an HTTP response object. If @var{validate-headers?} is true,
+the headers are each run through their respective validators."
(make-response version code reason-phrase headers port))
(define (extend-response r k v . additional)
+ "Extend an HTTP response by setting additional HTTP headers @var{k},
+@var{v}. Returns a new HTTP response."
(let ((r (build-response #:version (response-version r)
#:code (response-code r)
#:reason-phrase (%response-reason-phrase r)
@@ -156,22 +160,43 @@
"(Unknown)"))
(define (response-reason-phrase response)
+ "Return the reason phrase given in @var{response}, or the standard
+reason phrase for the response's code."
(or (%response-reason-phrase response)
(code->reason-phrase (response-code response))))
(define (read-response port)
+ "Read an HTTP response from @var{port}, optionally attaching the given
+metadata, @var{meta}.
+
+As a side effect, sets the encoding on @var{port} to
+ISO-8859-1 (latin-1), so that reading one character reads one byte. See
+the discussion of character sets in \"HTTP Responses\" in the manual,
+for more information."
(set-port-encoding! port "ISO-8859-1")
(call-with-values (lambda () (read-response-line port))
(lambda (version code reason-phrase)
(make-response version code reason-phrase (read-headers port) port))))
(define (adapt-response-version response version)
+ "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
+default HTTP version, and this method could handle a number of
+programmatic transformations to respond to older HTTP versions (0.9 and
+1.0). But currently this function is a bit heavy-handed, just updating
+the version field."
(build-response #:code (response-code response)
#:version version
#:headers (response-headers response)
#:port (response-port response)))
(define (write-response r port)
+ "Write the given HTTP response to @var{port}.
+
+Returns a new response, whose @code{response-port} will continue writing
+on @var{port}, perhaps using some transfer encoding."
(write-response-line (response-version r) (response-code r)
(response-reason-phrase r) port)
(write-headers (response-headers r) port)
@@ -185,6 +210,12 @@
;; per char because we are in latin-1 encoding.
;;
(define (read-response-body/latin-1 r)
+ "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
+@code{response-content-length}. Returns @code{#f} if there was no
+response body."
(cond
((response-content-length r) =>
(lambda (nbytes)
@@ -205,12 +236,16 @@
(else #f)))
;; Likewise, assumes that body can be written in the latin-1 encoding,
-;; and that the latin-1 encoding is what is expected by the server.
+;; and that the latin-1 encoding is what is expected by the client.
;;
(define (write-response-body/latin-1 r body)
+ "Write @var{body}, a string encodable in ISO-8859-1, to the port
+corresponding to the HTTP response @var{r}."
(display body (response-port r)))
(define (read-response-body/bytevector r)
+ "Reads the response body from @var{r}, as a bytevector. Returns
+@code{#f} if there was no response body."
(let ((nbytes (response-content-length r)))
(and nbytes
(let ((bv (get-bytevector-n (response-port r) nbytes)))
@@ -220,6 +255,8 @@
(bytevector-length bv) nbytes))))))
(define (write-response-body/bytevector r bv)
+ "Write @var{body}, a bytevector, to the port corresponding to the HTTP
+response @var{r}."
(put-bytevector (response-port r) bv))
(define-syntax define-response-accessor