From cdbca619e3d918a8654fa7eab41ad2ef321fa6bd Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Tue, 5 Jun 2007 18:39:11 +0000 Subject: [PATCH] Updating docs svn: r6486 --- .../web-server/docs/reference/servlet.scrbl | 78 ++++++++++++++++++- .../web-server/private/response-structs.ss | 21 +---- collects/web-server/private/response.ss | 1 + 3 files changed, 79 insertions(+), 21 deletions(-) diff --git a/collects/web-server/docs/reference/servlet.scrbl b/collects/web-server/docs/reference/servlet.scrbl index 40a5d3ef03..67e0be08ab 100644 --- a/collects/web-server/docs/reference/servlet.scrbl +++ b/collects/web-server/docs/reference/servlet.scrbl @@ -131,13 +131,87 @@ related to HTTP request data structures. @; ------------------------------------------------------------ @section[#:tag "bindings.ss"]{Request Bindings} -XXX +@file{servlet/bindings.ss} provides a number of helper functions +for accessing request bindings. + +@; XXX Move in request-bindings +@; XXX Rename extract-binding +@defproc[(extract-binding/single [id symbol?] + [binds (listof (cons/c symbol? string?))]) + string?]{ + Returns the single binding associated with @scheme[id] in the a-list @scheme[binds] + if there is exactly one binding. Otherwise errors. +} + +@defproc[(extract-bindings [id symbol?] + [binds (listof (cons/c symbol? string?))]) + (listof string?)]{ + Returns a list of all the bindings of @scheme[id] in the a-list @scheme[binds]. +} + +@defproc[(exists-binding? [id symbol?] + [binds (listof (cons/c symbol? string))]) + boolean?]{ + Returns @scheme[#t] if @scheme[binds] contains a binding for @scheme[id]. + Otherwise, @scheme[#f]. +} @; ------------------------------------------------------------ @section[#:tag "response-structs.ss"]{HTTP Responses} -XXX +@file{private/response-structs.ss} provides structures and functions related to +HTTP responses. +@; XXX Rename extras to headers +@; XXX Make extras a listof header? +@defstruct[response/basic + ([code number?] + [message string?] + [seconds number?] + [mime bytes?] + [extras (listof (cons/c symbol? string?))])]{ + A basic HTTP response containing no body. @scheme[code] is the response code, + @scheme[message] the message, @scheme[seconds] the generation time, @scheme[mime] + the MIME type of the file, and @scheme[extras] are the extra headers, in addition + to those produced by the server. +} + +@; XXX Rename string? option +@defstruct[(response/full response/basic) + ([code number?] + [message string?] + [seconds number?] + [mime bytes?] + [extras (listof (cons/c symbol? string?))] + [body (listof (or/c string? bytes?))])]{ + As with @scheme[response/basic], except with @scheme[body] as the response + body. +} + +@defstruct[(response/incremental response/basic) + ([code number?] + [message string?] + [seconds number?] + [mime bytes?] + [extras (listof (cons/c symbol? string?))] + [generator ((() (listof (or/c bytes? string?)) . ->* . any) . -> . any)])]{ + As with @scheme[response/basic], except with @scheme[generator] as a function that is + called to generate the response body, by being given an @scheme[output-response] function + that outputs the content it is called with. +} + +@defproc[(response? [v any/c]) + boolean?]{ + Checks if @scheme[v] is a valid response. A response is either: + @itemize[ + @item{A @scheme[response/basic] structure.} + @item{A value matching the contract @scheme[(cons/c (or/c bytes? string?) (listof (or/c bytes? string?)))].} + @item{A value matching @scheme[xexpr?].} + ] +} + +@defthing[TEXT/HTML-MIME-TYPE bytes?]{Equivalent to @scheme[#"text/html; charset=utf-8"].} + @; ------------------------------------------------------------ @section[#:tag "web.ss"]{Web} diff --git a/collects/web-server/private/response-structs.ss b/collects/web-server/private/response-structs.ss index 0171922c24..f63040f30c 100644 --- a/collects/web-server/private/response-structs.ss +++ b/collects/web-server/private/response-structs.ss @@ -4,12 +4,8 @@ (define TEXT/HTML-MIME-TYPE #"text/html; charset=utf-8") - ;; ************************************************** - ;; (make-response/basic number string number string (listof (cons symbol string))) (define-struct response/basic (code message seconds mime extras)) - ;; (make-response/full ... (listof string)) (define-struct (response/full response/basic) (body)) - ;; (make-response/incremental ... ((string* -> void) -> void)) (define-struct (response/incremental response/basic) (generator)) ; response = (cons string (listof string)), where the first string is a mime-type @@ -17,22 +13,10 @@ ; | (make-response/full ... (listof string)) ; | (make-response/incremental ... ((string* -> void) -> void)) - ;; ************************************************** ;; response?: any -> boolean ;; Determine if an object is a response (define (response? x) - (or (and (response/basic? x) - (number? (response/basic-code x)) - (string? (response/basic-message x)) - (number? (response/basic-seconds x)) - (bytes? (response/basic-mime x)) - (and (list? (response/basic-extras x)) - (andmap - (lambda (p) - (and (pair? p) - (symbol? (car p)) - (string? (cdr p)))) - (response/basic-extras x)))) + (or (response/basic? x) ; this could fail for dotted lists - rewrite andmap (and (pair? x) (pair? (cdr x)) (andmap (lambda (x) @@ -64,7 +48,6 @@ [seconds number?] [mime bytes?] [extras (listof (cons/c symbol? string?))] - [generator ((() (listof (or/c bytes? string?)) . ->* . any) . -> - . any)])] + [generator ((() (listof (or/c bytes? string?)) . ->* . any) . -> . any)])] [response? (any/c . -> . boolean?)] [TEXT/HTML-MIME-TYPE bytes?])) \ No newline at end of file diff --git a/collects/web-server/private/response.ss b/collects/web-server/private/response.ss index 0f96a2fc30..ab0814d53a 100644 --- a/collects/web-server/private/response.ss +++ b/collects/web-server/private/response.ss @@ -244,6 +244,7 @@ ;; ************************************************** ;; output-response/incremental: connection response/incremental -> void ;; Write a chunked response to an output port. + ; XXX How does this end? (define (output-response/incremental conn resp/inc) (let ([o-port (connection-o-port conn)]) (cond