summaryrefslogtreecommitdiff
path: root/module/web/request.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/request.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/request.scm')
-rw-r--r--module/web/request.scm25
1 files changed, 25 insertions, 0 deletions
diff --git a/module/web/request.scm b/module/web/request.scm
index da91c40b8..adf1dd287 100644
--- a/module/web/request.scm
+++ b/module/web/request.scm
@@ -156,6 +156,8 @@
(define* (build-request #:key (method 'GET) uri (version '(1 . 1))
(headers '()) port (meta '())
(validate-headers? #t))
+ "Construct an HTTP request object. If @var{validate-headers?} is true,
+the headers are each run through their respective validators."
(cond
((not (and (pair? version)
(non-negative-integer? (car version))
@@ -173,6 +175,13 @@
(make-request method uri version headers meta port))
(define* (read-request port #:optional (meta '()))
+ "Read an HTTP request 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 Requests\" in the manual, for
+more information."
(set-port-encoding! port "ISO-8859-1")
(call-with-values (lambda () (read-request-line port))
(lambda (method uri version)
@@ -180,6 +189,10 @@
;; FIXME: really return a new request?
(define (write-request r port)
+ "Write the given HTTP request to @var{port}.
+
+Returns a new request, whose @code{request-port} will continue writing
+on @var{port}, perhaps using some transfer encoding."
(write-request-line (request-method r) (request-uri r)
(request-version r) port)
(write-headers (request-headers r) port)
@@ -193,6 +206,12 @@
;; per char because we are in latin-1 encoding.
;;
(define (read-request-body/latin-1 r)
+ "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
+@code{request-content-length}. Returns @code{#f} if there was no request
+body."
(cond
((request-content-length r) =>
(lambda (nbytes)
@@ -216,9 +235,13 @@
;; and that the latin-1 encoding is what is expected by the server.
;;
(define (write-request-body/latin-1 r body)
+ "Write @var{body}, a string encodable in ISO-8859-1, to the port
+corresponding to the HTTP request @var{r}."
(display body (request-port r)))
(define (read-request-body/bytevector r)
+ "Reads the request body from @var{r}, as a bytevector. Returns
+@code{#f} if there was no request body."
(let ((nbytes (request-content-length r)))
(and nbytes
(let ((bv (get-bytevector-n (request-port r) nbytes)))
@@ -228,6 +251,8 @@
(bytevector-length bv) nbytes))))))
(define (write-request-body/bytevector r bv)
+ "Write @var{body}, a bytevector, to the port corresponding to the HTTP
+request @var{r}."
(put-bytevector (request-port r) bv))
(define-syntax define-request-accessor