From e7c71921bb84519a3a9b420efa2328606157aab2 Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Sat, 4 Dec 2010 22:45:48 -0700 Subject: [PATCH] Adjusting documentation --- .../web-server/scribblings/contracts.scrbl | 15 +++++++++++++-- .../scribblings/dispatch-servlets.scrbl | 6 +++--- collects/web-server/scribblings/dispatch.scrbl | 18 +++++++++--------- collects/web-server/scribblings/http.scrbl | 4 ++++ .../web-server/scribblings/servlet-env.scrbl | 4 ++-- .../web-server/scribblings/servlet-setup.scrbl | 6 +++--- collects/web-server/scribblings/servlet.scrbl | 2 +- collects/web-server/scribblings/web.scrbl | 18 +++++++++--------- 8 files changed, 44 insertions(+), 29 deletions(-) diff --git a/collects/web-server/scribblings/contracts.scrbl b/collects/web-server/scribblings/contracts.scrbl index c2c4f4fac8..a1ee371398 100644 --- a/collects/web-server/scribblings/contracts.scrbl +++ b/collects/web-server/scribblings/contracts.scrbl @@ -11,13 +11,24 @@ This module provides a number of contracts for use in servlets. +@defparam[current-response/c ctc contract?]{ +The contract used by @racket[response/c] dynamically. Defaults to @racket[any/c]. +} + +@defthing[response/c contract?]{ +A contract corresponding to @racket[(dynamic/c any/c current-response/c response?)]. + +This allows Web applications to customize the Web Server's handling of responses, while ensuring that the Web Server +always receives @racket[response?] structures. +} + @defthing[k-url? contract?]{ Equivalent to @racket[string?]. Example: @racket["http://localhost:8080/servlets;1*1*20131636/examples/add.rkt"]} @defthing[response-generator/c contract?]{ -Equivalent to @racket[(k-url? . -> . response?)]. +Equivalent to @racket[(k-url? . -> . response/c)]. Example: @racketblock[(lambda (k-url) (response/xexpr @@ -28,7 +39,7 @@ Example: @racketblock[(lambda (k-url) } @defthing[expiration-handler/c contract?]{ -Equivalent to @racket[(or/c false/c (request? . -> . response?))]. +Equivalent to @racket[(or/c false/c (request? . -> . response/c))]. Typically @racket[#f] uses the default expiration handler, which displays an error message. diff --git a/collects/web-server/scribblings/dispatch-servlets.scrbl b/collects/web-server/scribblings/dispatch-servlets.scrbl index 369679c4f2..1d4b92ca4e 100644 --- a/collects/web-server/scribblings/dispatch-servlets.scrbl +++ b/collects/web-server/scribblings/dispatch-servlets.scrbl @@ -28,11 +28,11 @@ @defproc[(make [url->servlet url->servlet/c] [#:responders-servlet-loading responders-servlet-loading - (url? exn? . -> . response?) + (url? exn? . -> . response/c) servlet-loading-responder] [#:responders-servlet responders-servlet - (url? exn? . -> . response?) + (url? exn? . -> . response/c) servlet-error-responder]) dispatcher/c]{ This dispatcher runs racket servlets, using @racket[url->servlet] to resolve URLs to the underlying servlets. @@ -53,7 +53,7 @@ [namespace namespace?] [manager manager?] [directory path-string?] - [handler (request? . -> . response?)]) + [handler (request? . -> . response/c)]) #:mutable]{ Instances of this structure hold the necessary parts of a servlet: the @racket[custodian] responsible for the servlet's resources, diff --git a/collects/web-server/scribblings/dispatch.scrbl b/collects/web-server/scribblings/dispatch.scrbl index 166a87ca24..ca2cdc3dca 100644 --- a/collects/web-server/scribblings/dispatch.scrbl +++ b/collects/web-server/scribblings/dispatch.scrbl @@ -105,9 +105,9 @@ After mastering the world of blogging software, you decide to put the ubiquitous [dispatch-pattern dispatch-fun] ...)] #:contracts - ([else-fun (request? . -> . response?)] - [dispatch-fun (request? any/c ... . -> . response?)])]{ - Returns two values: the first is a dispatching function with the contract @racket[(request? . -> . response?)] + ([else-fun (request? . -> . response/c)] + [dispatch-fun (request? any/c ... . -> . response/c)])]{ + Returns two values: the first is a dispatching function with the contract @racket[(request? . -> . response/c)] that calls the appropriate @racket[dispatch-fun] based on the first @racket[dispatch-pattern] that matches the request's URL; the second is a URL-generating function with the contract @racket[(procedure? any/c ... . -> . string?)] that generates a URL using @racket[dispatch-pattern] for the @racket[dispatch-fun] given as its first argument. @@ -131,8 +131,8 @@ After mastering the world of blogging software, you decide to put the ubiquitous [dispatch-pattern dispatch-fun] ...)] #:contracts - ([else-fun (request? . -> . response?)] - [dispatch-fun (request? any/c ... . -> . response?)])]{ + ([else-fun (request? . -> . response/c)] + [dispatch-fun (request? any/c ... . -> . response/c)])]{ Like @racket[dispatch-rules], except returns a third value with the contract @racket[(request? . -> . boolean?)] that returns @racket[#t] if the dispatching rules apply to the request and @racket[#f] otherwise. } @@ -146,8 +146,8 @@ After mastering the world of blogging software, you decide to put the ubiquitous [dispatch-pattern dispatch-fun] ...)] #:contracts - ([else-fun (request? . -> . response?)] - [dispatch-fun (request? any/c ... . -> . response?)])]{ + ([else-fun (request? . -> . response/c)] + [dispatch-fun (request? any/c ... . -> . response/c)])]{ Returns a dispatching function as described by @racket[dispatch-rules]. } @@ -156,11 +156,11 @@ After mastering the world of blogging software, you decide to put the ubiquitous [dispatch-pattern dispatch-fun] ...) #:contracts - ([dispatch-fun (request? any/c ... . -> . response?)])]{ + ([dispatch-fun (request? any/c ... . -> . response/c)])]{ Returns a URL-generating function as described by @racket[dispatch-rules]. } -@defproc[(serve/dispatch [dispatch (request? . -> . response?)]) +@defproc[(serve/dispatch [dispatch (request? . -> . response/c)]) void]{ Calls @racket[serve/servlet] with a @racket[#:servlet-regexp] argument (@racket[#rx""]) so that every request is handled by @racket[dispatch]. } diff --git a/collects/web-server/scribblings/http.scrbl b/collects/web-server/scribblings/http.scrbl index 4e2a414067..0c3e7868cb 100644 --- a/collects/web-server/scribblings/http.scrbl +++ b/collects/web-server/scribblings/http.scrbl @@ -471,6 +471,10 @@ web-server/insta xml)) @defmodule[web-server/http/xexpr]{ + +@defthing[xexpr-response/c contract?]{ +A contract for use with @racket[current-response/c] that coerces +X-expressions into @racket[response?] structures using @racket[response/xexpr].} @defproc[(response/xexpr [xexpr xexpr/c] [#:code code number? 200] diff --git a/collects/web-server/scribblings/servlet-env.scrbl b/collects/web-server/scribblings/servlet-env.scrbl index 02c625cc1a..f825303f74 100644 --- a/collects/web-server/scribblings/servlet-env.scrbl +++ b/collects/web-server/scribblings/servlet-env.scrbl @@ -128,7 +128,7 @@ Like always, you don't even need to save the file. @section{Full API} -@defproc[(serve/servlet [start (request? . -> . response?)] +@defproc[(serve/servlet [start (request? . -> . response/c)] [#:command-line? command-line? boolean? #f] [#:connection-close? connection-close? boolean? #f] [#:launch-browser? launch-browser? boolean? (not command-line?)] @@ -152,7 +152,7 @@ Like always, you don't even need to save the file. [#:servlets-root servlets-root path-string? (build-path server-root-path "htdocs")] [#:servlet-current-directory servlet-current-directory path-string? servlets-root] [#:file-not-found-responder file-not-found-responder - (request? . -> . response?) + (request? . -> . response/c) (gen-file-not-found-responder (build-path server-root-path diff --git a/collects/web-server/scribblings/servlet-setup.scrbl b/collects/web-server/scribblings/servlet-setup.scrbl index 96b6036f7c..e74d074de5 100644 --- a/collects/web-server/scribblings/servlet-setup.scrbl +++ b/collects/web-server/scribblings/servlet-setup.scrbl @@ -16,14 +16,14 @@ This module is used internally to build and load servlets. It may be useful to t @defproc[(make-v1.servlet [directory path-string?] [timeout integer?] - [start (request? . -> . response?)]) + [start (request? . -> . response/c)]) servlet?]{ Creates a version 1 servlet that uses @racket[directory] as its current directory, a timeout manager with a @racket[timeout] timeout, and @racket[start] as the request handler. } @defproc[(make-v2.servlet [directory path-string?] [manager manager?] - [start (request? . -> . response?)]) + [start (request? . -> . response/c)]) servlet?]{ Creates a version 2 servlet that uses @racket[directory] as its current directory, a @racket[manager] as the continuation manager, and @racket[start] as the request handler. } @@ -31,7 +31,7 @@ This module is used internally to build and load servlets. It may be useful to t @defproc[(make-stateless.servlet [directory path-string?] [stuffer (stuffer/c serializable? bytes?)] [manager manager?] - [start (request? . -> . response?)]) + [start (request? . -> . response/c)]) servlet?]{ Creates a stateless @racketmodname[web-server] servlet that uses @racket[directory] as its current directory, @racket[stuffer] as its stuffer, and @racket[manager] as the continuation manager, and @racket[start] as the request handler. } diff --git a/collects/web-server/scribblings/servlet.scrbl b/collects/web-server/scribblings/servlet.scrbl index 84c84b861a..6bf16cdf77 100644 --- a/collects/web-server/scribblings/servlet.scrbl +++ b/collects/web-server/scribblings/servlet.scrbl @@ -23,7 +23,7 @@ A stateful servlet should @racket[provide] the following exports: } @defproc[(start [initial-request request?]) - response?]{ + response/c]{ This function is called when an instance of this servlet is started. The argument is the HTTP request that initiated the instance. } diff --git a/collects/web-server/scribblings/web.scrbl b/collects/web-server/scribblings/web.scrbl index aed8f461b2..46e8f16f3f 100644 --- a/collects/web-server/scribblings/web.scrbl +++ b/collects/web-server/scribblings/web.scrbl @@ -12,7 +12,7 @@ @racketmodname[web-server/servlet/web] library provides the primary functions of interest for the servlet developer. -@defproc[(send/back [response response?]) +@defproc[(send/back [response response/c]) void?]{ Sends @racket[response] to the client. No continuation is captured, so the servlet is done. @@ -28,11 +28,11 @@ functions of interest for the servlet developer. ] } -@defproc[(send/suspend [make-response (string? . -> . response?)]) +@defproc[(send/suspend [make-response (string? . -> . response/c)]) request?]{ Captures the current continuation, stores it with @racket[exp] as the expiration handler, and binds it to a URL. @racket[make-response] is called with this URL and - is expected to generate a @racket[response?], which is sent to the client. If the + is expected to generate a @racket[response/c], which is sent to the client. If the continuation URL is invoked, the captured continuation is invoked and the request is returned from this call to @racket[send/suspend]. @@ -53,12 +53,12 @@ functions of interest for the servlet developer. Thus, the request will be ``returned'' from @racket[send/suspend] to the continuation of this call. } -@defproc[(send/suspend/url [make-response (url? . -> . response?)]) +@defproc[(send/suspend/url [make-response (url? . -> . response/c)]) request?]{ Like @racket[send/suspend] but with a URL struct. } -@defproc[(send/suspend/dispatch [make-response (((request? . -> . any) . -> . string?) . -> . response?)]) +@defproc[(send/suspend/dispatch [make-response (((request? . -> . any) . -> . string?) . -> . response/c)]) any]{ Calls @racket[make-response] with a function (@racket[embed/url]) that, when called with a procedure from @racket[request?] to @racket[any/c] will generate a URL, that when invoked will call @@ -121,19 +121,19 @@ functions of interest for the servlet developer. ] } -@defproc[(send/suspend/url/dispatch [make-response (((request? . -> . any) . -> . url?) . -> . response?)]) +@defproc[(send/suspend/url/dispatch [make-response (((request? . -> . any) . -> . url?) . -> . response/c)]) any]{ Like @racket[send/suspend/dispatch], but with a URL struct. } -@defproc[(send/forward [make-response (string? . -> . response?)]) +@defproc[(send/forward [make-response (string? . -> . response/c)]) request?]{ Calls @racket[clear-continuation-table!], then @racket[send/suspend]. Use this if the user can logically go `forward' in your application, but cannot go backward. } -@defproc[(send/finish [response response?]) +@defproc[(send/finish [response response/c]) void?]{ Calls @racket[clear-continuation-table!], then @racket[send/back]. @@ -182,7 +182,7 @@ functions of interest for the servlet developer. captured continuations. } -@defproc[(with-errors-to-browser [send/finish-or-back (response? . -> . request?)] +@defproc[(with-errors-to-browser [send/finish-or-back (response/c . -> . request?)] [thunk (-> any)]) any]{ Calls @racket[thunk] with an exception handler that generates an HTML error page