suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Adjusting documentation

Browse Source
This commit is contained in:
Jay McCarthy 2010-12-04 22:45:48 -07:00
parent a246ddebde
commit e7c71921bb
8 changed files with 44 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
collects/web-server/scribblings/contracts.scrbl
View File

@ -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.

6
collects/web-server/scribblings/dispatch-servlets.scrbl
View File

@ -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,

18
collects/web-server/scribblings/dispatch.scrbl
View File

@ -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].
}

4
collects/web-server/scribblings/http.scrbl
View File

@ -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]

4
collects/web-server/scribblings/servlet-env.scrbl
View File

@ -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

6
collects/web-server/scribblings/servlet-setup.scrbl
View File

@ -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.
}

2
collects/web-server/scribblings/servlet.scrbl
View File

@ -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.
}

18
collects/web-server/scribblings/web.scrbl
View File

@ -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