diff --git a/collects/scribblings/guide/apply.scrbl b/collects/scribblings/guide/apply.scrbl index b13e7500ce..6bacfcaaf0 100644 --- a/collects/scribblings/guide/apply.scrbl +++ b/collects/scribblings/guide/apply.scrbl @@ -133,7 +133,7 @@ list contains a corresponding argument for each keyword. The third list contains by-position function arguments, as for @scheme[apply]. @schemeblock[ -(keyword-apply go +(keyword-apply go '(#:mode) '(fast) '("super.ss")) diff --git a/collects/scribblings/guide/class.scrbl b/collects/scribblings/guide/class.scrbl index d1397ce1f4..45a26c87b9 100644 --- a/collects/scribblings/guide/class.scrbl +++ b/collects/scribblings/guide/class.scrbl @@ -6,7 +6,7 @@ @title[#:tag "classes"]{Classes and Objects} -A @scheme[class] expression denotes a first-class value, +A @scheme[class] expression denotes a first-class value, just like a @scheme[lambda] expression: @specform[(class superclass-expr decl-or-expr ...)] @@ -31,7 +31,7 @@ public methods @scheme[get-size], @scheme[grow], and @scheme[eat]: (super-new) (code:comment #,(t "superclass initialization")) - (define/public (get-size) + (define/public (get-size) current-size) (define/public (grow amt) @@ -47,13 +47,13 @@ public methods @scheme[get-size], @scheme[grow], and @scheme[eat]: (init size) (define current-size size) (super-new) - (define/public (get-size) + (define/public (get-size) current-size) (define/public (grow amt) (set! current-size (+ amt current-size))) (define/public (eat other-fish) (grow (send other-fish get-size)))))] - + The @scheme[size] initialization argument must be supplied via a named argument when instantiating the class through the @scheme[new] form: @@ -61,7 +61,7 @@ The @scheme[size] initialization argument must be supplied via a named (new (class object% (init size) ...) [size 10]) ] -Of course, we can also name the class and its instance: +Of course, we can also name the class and its instance: @schemeblock[ (define fish% (class object% (init size) ...)) @@ -150,7 +150,7 @@ finding a method in the target object's class at run time, making contrast, @scheme[inherit]-based method invocations use an offset within the class's method table that is computed when the class is created. - + To achieve performance similar to @scheme[inherit]-based method calls when invoking a method from outside the method's class, the programmer must use the @scheme[generic] form, which produces a class- and method-specific @@ -168,7 +168,7 @@ method name to a location in the class's method table. As illustrated by the last example, sending through a generic method checks that its argument is an instance of the generic's class. -Whether a method is called directly within a @scheme[class], +Whether a method is called directly within a @scheme[class], through a generic method, or through @scheme[send], method overriding works in the usual way: diff --git a/collects/scribblings/guide/cond.scrbl b/collects/scribblings/guide/cond.scrbl index e4285b5a65..7d37f95ef0 100644 --- a/collects/scribblings/guide/cond.scrbl +++ b/collects/scribblings/guide/cond.scrbl @@ -101,7 +101,7 @@ as follows: @refalso["mz:cond"]{@scheme[cond]} -@specform[(cond [test-expr expr ...+] +@specform[(cond [test-expr expr ...+] ...)] Each @scheme[_test-expr] is evaluated in order. If it produces diff --git a/collects/scribblings/guide/define-struct.scrbl b/collects/scribblings/guide/define-struct.scrbl index b6fd93e866..add6c80762 100644 --- a/collects/scribblings/guide/define-struct.scrbl +++ b/collects/scribblings/guide/define-struct.scrbl @@ -145,7 +145,7 @@ To make a structure type @defterm{transparent}, use the field-name sequence: @def+int[ -(define-struct posn (x y) +(define-struct posn (x y) #:inspector #f) (make-posn 1 2) ] @@ -169,7 +169,7 @@ by the library. The full syntax of @scheme[define-struct] supports many options, both at the structure-type level and at the level of individual fields: -@specform/subs[(define-struct id-maybe-super (field ...) +@specform/subs[(define-struct id-maybe-super (field ...) struct-option ...) ([id-maybe-super struct-id (struct-id super-id)] @@ -229,7 +229,7 @@ A @scheme[_struct-option] always starts with a keyword: #:guard (lambda (name type-name) (cond [(string? name) name] - [(number? name) + [(number? name) (number->string name)] [else (error "bad name" name)]))) (make-thing "apple") @@ -260,7 +260,7 @@ A @scheme[_struct-option] always starts with a keyword: @defexamples[ (define-struct greeter (name) - #:property prop:procedure + #:property prop:procedure (lambda (self other) (string-append "Hi " other @@ -269,7 +269,7 @@ A @scheme[_struct-option] always starts with a keyword: (greeter-name joe-greet) (joe-greet "Mary") (joe-greet "John")]} - + @specspecsubform[(code:line #:super super-expr)]{ An alternative to supplying a @scheme[super-id] next to diff --git a/collects/scribblings/guide/for.scrbl b/collects/scribblings/guide/for.scrbl index b1de88236e..30c57aea50 100644 --- a/collects/scribblings/guide/for.scrbl +++ b/collects/scribblings/guide/for.scrbl @@ -312,10 +312,10 @@ current value, and the last @scheme[_body] provides the value of @scheme[_accum-id] for the netx iteration. @examples[ -(for/fold ([len 0]) +(for/fold ([len 0]) ([chapter '("Intro" "Conclusion")]) (+ len (string-length chapter))) -(for/fold ([prev #f]) +(for/fold ([prev #f]) ([i (in-naturals 1)] [chapter '("Intro" "Details" "Details" "Conclusion")] #:when (not (equal? chapter prev))) @@ -334,7 +334,7 @@ multiple values for the results. ([chapter '("Intro" "Details" "Details" "Conclusion")] #:when (not (equal? chapter prev))) (printf "~a. ~a\n" counter chapter) - (values chapter + (values chapter (add1 counter))) ] diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl index 3f8a6f2d9e..6d3d5bf6c7 100644 --- a/collects/scribblings/guide/guide.scrbl +++ b/collects/scribblings/guide/guide.scrbl @@ -9,7 +9,7 @@ This guide is intended for programmers who are new to Scheme, new to PLT Scheme, or new to some part of PLT Scheme. It assumes programming experience, so if you are new to programming, consider instead reading @|HtDP|. If you want a quick and pretty overview of PLT -Scheme, start with @|Quick|. +Scheme, start with @|Quick|. @seclink["to-scheme"]{Chapter 2} provides a brief introduction to Scheme. From @seclink["datatypes"]{Chapter 3} on, this guide dives @@ -66,7 +66,7 @@ using @idefterm{contracts}. The @scheme[case] form dispatches to a clause by matching the result of an expression to the values for the clause: -@specform[(case [(_datum ...+) expr ...+] +@specform[(case [(_datum ...+) expr ...+] ...)] @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/guide/io.scrbl b/collects/scribblings/guide/io.scrbl index ae2fb493ff..2cff0604f6 100644 --- a/collects/scribblings/guide/io.scrbl +++ b/collects/scribblings/guide/io.scrbl @@ -7,7 +7,7 @@ @define[(twocolumn a b) (make-table #f - (list (list (make-flow (list a)) + (list (list (make-flow (list a)) (make-flow (list (make-paragraph (list (hspace 1))))) (make-flow (list b)))))] @interaction-eval[(print-hash-table #t)] @@ -81,7 +81,7 @@ with the output port; when the function returns, the port is closed. ]} @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + @item{@bold{TCP Connections:} The @scheme[tcp-connect] function creates both an input port and an output port for the client side of a TCP communication. The @scheme[tcp-listen] function creates a @@ -100,7 +100,7 @@ with the output port; when the function returns, the port is closed. ]} @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + @item{@bold{Process Pipes:} The @scheme[process] function runs a new process at the OS level and returns ports that correspond to the subprocess's stdin, stdout, and stderr. (The first three arguments @@ -121,7 +121,7 @@ with the output port; when the function returns, the port is closed. ]} @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + @item{@bold{Internal Pipes:} The @scheme[make-pipe] function returns two ports that are ends of a pipe. This kind of pipe is internal to Scheme, and not related to OS-level pipes for communicating between diff --git a/collects/scribblings/guide/lambda.scrbl b/collects/scribblings/guide/lambda.scrbl index 6d9697ca75..54e92ea4b9 100644 --- a/collects/scribblings/guide/lambda.scrbl +++ b/collects/scribblings/guide/lambda.scrbl @@ -19,9 +19,9 @@ A @scheme[lambda] form with @math{n} @scheme[_arg-id]s accepts @interaction[ ((lambda (x) x) 1) -((lambda (x y) (+ x y)) +((lambda (x y) (+ x y)) 1 2) -((lambda (x y) (+ x y)) +((lambda (x y) (+ x y)) 1) ] @@ -41,7 +41,7 @@ function accepts any number of arguments, and the arguments are put into a list bound to @scheme[_rest-id]. @examples[ -((lambda x x) +((lambda x x) 1 2 3) ((lambda x x)) ((lambda x (car x)) @@ -54,7 +54,7 @@ another function that accepts any number of arguments. @guideother{@secref["guide:apply"] describes @scheme[apply].} @defexamples[ -(define max-mag +(define max-mag (lambda nums (apply max (map magnitude nums)))) @@ -75,7 +75,7 @@ arguments as @scheme[_arg-id]s, and also accepts any number of additional arguments. @defexamples[ -(define max-mag +(define max-mag (lambda (num . nums) (apply max (map magnitude (cons num nums))))) diff --git a/collects/scribblings/guide/let.scrbl b/collects/scribblings/guide/let.scrbl index 491353b18f..3216ff4ad8 100644 --- a/collects/scribblings/guide/let.scrbl +++ b/collects/scribblings/guide/let.scrbl @@ -123,9 +123,9 @@ The @scheme[_expr]s in a @scheme[letrec] form are most often (letrec ([swing (lambda (t) (if (eq? (car t) 'tarzan) - (cons 'vine + (cons 'vine (cons 'tarzan (cddr t))) - (cons (car t) + (cons (car t) (swing (cdr t)))))]) (swing '(vine tarzan vine vine))) ] diff --git a/collects/scribblings/guide/module-basics.scrbl b/collects/scribblings/guide/module-basics.scrbl index e1dde38c90..28c7d93e5f 100644 --- a/collects/scribblings/guide/module-basics.scrbl +++ b/collects/scribblings/guide/module-basics.scrbl @@ -57,7 +57,7 @@ big (require (lib "mzlib/date.ss")) -(printf "Today is ~s\n" +(printf "Today is ~s\n" (date->string (seconds->date (current-seconds)))) ] diff --git a/collects/scribblings/guide/module-paths.scrbl b/collects/scribblings/guide/module-paths.scrbl index e9e18f9b41..99d93b9d37 100644 --- a/collects/scribblings/guide/module-paths.scrbl +++ b/collects/scribblings/guide/module-paths.scrbl @@ -63,14 +63,14 @@ as part of PLT Scheme. (module m (lib "big/lang.ss") (require (lib "mzlib/date.ss")) - (printf "Today is ~s\n" + (printf "Today is ~s\n" (date->string (seconds->date (current-seconds))))) (require m) ]} @; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @specsubform/subs[#:literals (planet) - (planet rel-string (user-string pkg-string vers ...)) + (planet rel-string (user-string pkg-string vers ...)) ([vers nat (nat nat) (= nat) diff --git a/collects/scribblings/guide/module-provide.scrbl b/collects/scribblings/guide/module-provide.scrbl index 331a047462..726994d178 100644 --- a/collects/scribblings/guide/module-provide.scrbl +++ b/collects/scribblings/guide/module-provide.scrbl @@ -93,4 +93,3 @@ beginning of the external name for each exported binding. } - \ No newline at end of file diff --git a/collects/scribblings/guide/module-require.scrbl b/collects/scribblings/guide/module-require.scrbl index 6e52951b5c..e044b6ef04 100644 --- a/collects/scribblings/guide/module-require.scrbl +++ b/collects/scribblings/guide/module-require.scrbl @@ -105,11 +105,11 @@ The @scheme[only], @scheme[except], @scheme[rename], and @scheme[prefix] forms can be nested to implement more complex manipulations of imported bindings. For example, -@schemeblock[(require (prefix (except m ghost) m:))] +@schemeblock[(require (prefix (except m ghost) m:))] imports all bindings that @scheme[m] exports, except for the @scheme[ghost] binding, and with local names -that are prefixed with @scheme[m:]. +that are prefixed with @scheme[m:]. Equivalently, the @scheme[prefix] could be applied before @scheme[except], as long as the omission with @scheme[except] is diff --git a/collects/scribblings/guide/named-let.scrbl b/collects/scribblings/guide/named-let.scrbl index d424026ca6..6d8fe73010 100644 --- a/collects/scribblings/guide/named-let.scrbl +++ b/collects/scribblings/guide/named-let.scrbl @@ -25,7 +25,7 @@ A named @scheme[let] form is equivalent to That is, a named @scheme[let] binds a function identifier that is visible only in the function's body, and it implicitly calls the -function with the values of some initial expressions. +function with the values of some initial expressions. @defexamples[ (define (duplicate pos lst) diff --git a/collects/scribblings/guide/numbers.scrbl b/collects/scribblings/guide/numbers.scrbl index 2dfcebb0f8..2cbf582e8c 100644 --- a/collects/scribblings/guide/numbers.scrbl +++ b/collects/scribblings/guide/numbers.scrbl @@ -94,7 +94,7 @@ non-integer exact numbers can be much more expensive than computation with inexact numbers. @def+int[ -(define (sigma f a b) +(define (sigma f a b) (if (= a b) 0 (+ (f a) (sigma f (+ a 1) b)))) diff --git a/collects/scribblings/guide/pairs.scrbl b/collects/scribblings/guide/pairs.scrbl index 81eb188130..77f4a8e1d9 100644 --- a/collects/scribblings/guide/pairs.scrbl +++ b/collects/scribblings/guide/pairs.scrbl @@ -80,9 +80,9 @@ iterate through the lists elements: '(1 2 3)) (for-each (lambda (i) (display i)) '(1 2 3)) -(member "Keys" +(member "Keys" '("Florida" "Keys" "U.S.A.")) -(assoc 'where +(assoc 'where '((when "3:30") (where "Florida") (who "Mickey"))) ] diff --git a/collects/scribblings/guide/read.scrbl b/collects/scribblings/guide/read.scrbl index 62d9ed3256..14564445c3 100644 --- a/collects/scribblings/guide/read.scrbl +++ b/collects/scribblings/guide/read.scrbl @@ -3,4 +3,4 @@ The set of syntactic forms and even lexem syntax for a Scheme program is extensible, so a conventional BNF grammar cannot capture the -grammar of Scheme. \ No newline at end of file +grammar of Scheme. diff --git a/collects/scribblings/guide/set.scrbl b/collects/scribblings/guide/set.scrbl index 0522f29d45..fb40281855 100644 --- a/collects/scribblings/guide/set.scrbl +++ b/collects/scribblings/guide/set.scrbl @@ -107,7 +107,7 @@ guidelines may help explain when using @scheme[set!] is appropriate. s)) (sum '(1 2 3)) ]] - + @as-examples[@t{Ok example:} @def+int[ (define (sum lst) diff --git a/collects/scribblings/guide/simple-syntax.scrbl b/collects/scribblings/guide/simple-syntax.scrbl index a9385478c6..ca562706d5 100644 --- a/collects/scribblings/guide/simple-syntax.scrbl +++ b/collects/scribblings/guide/simple-syntax.scrbl @@ -169,7 +169,7 @@ special characters @moreguide["guide:binding"]{identifiers} @t{ - @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} + @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} @litchar["{"] @litchar["}"] @litchar{"} @litchar{,} @litchar{'} @litchar{`} @litchar{;} @litchar{#} @litchar["|"] @litchar["\\"] @@ -250,7 +250,7 @@ evaluted for the result of the whole @scheme[if] expression, otherwise the third @nonterm{expr} is evaluated for the result. @examples[ -(if (> 2 3) +(if (> 2 3) "bigger" "smaller") ] @@ -354,11 +354,11 @@ clearly written as follows: @def+int[ (define (reply-more s) (cond - [(equal? "hello" (substring s 0 5)) + [(equal? "hello" (substring s 0 5)) "hi!"] - [(equal? "goodbye" (substring s 0 7)) + [(equal? "goodbye" (substring s 0 7)) "bye!"] - [(equal? "?" (substring s (- (string-length s) 1))) + [(equal? "?" (substring s (- (string-length s) 1))) "I don't know"] [else "huh?"])) (reply-more "hello scheme") diff --git a/collects/scribblings/guide/symbols.scrbl b/collects/scribblings/guide/symbols.scrbl index 4f8d512bb1..b380e830f8 100644 --- a/collects/scribblings/guide/symbols.scrbl +++ b/collects/scribblings/guide/symbols.scrbl @@ -39,7 +39,7 @@ input, any character can appear directly in an identifier, except for whitespace and the following special characters: @t{ - @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} + @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} @litchar["{"] @litchar["}"] @litchar{"} @litchar{,} @litchar{'} @litchar{`} @litchar{;} @litchar{#} @litchar["|"] @litchar["\\"] diff --git a/collects/scribblings/guide/truth.scrbl b/collects/scribblings/guide/truth.scrbl index a6f5418b83..60cd9f6ee3 100644 --- a/collects/scribblings/guide/truth.scrbl +++ b/collects/scribblings/guide/truth.scrbl @@ -61,7 +61,7 @@ In general, the rule for printing a pair is as follows: use the dot notation always, but if the dot is immediately followed by an open parenthesis, then remove the dot, the open parenthesis, and the matching close parenthesis. Thus, @schemeresultfont{(0 . (1 . 2))} -becomes @schemeresult[(0 1 . 2)], and +becomes @schemeresult[(0 1 . 2)], and @schemeresultfont{(1 . (2 . (3 . ())))} becomes @schemeresult[(1 2 3)]. @;------------------------------------------------------------------------ diff --git a/collects/scribblings/guide/welcome.scrbl b/collects/scribblings/guide/welcome.scrbl index 91d7a762c2..99cff61a5d 100644 --- a/collects/scribblings/guide/welcome.scrbl +++ b/collects/scribblings/guide/welcome.scrbl @@ -164,5 +164,5 @@ they're fundamental limitations of the traditional top-level environment, which Scheme and Lisp implementations have historically fought with ad hoc command-line flags, compiler directives, and build tools. The module system is to designed to avoid the problems, -so start with @schemefont{#module}, and you'll be happier with +so start with @schemefont{#module}, and you'll be happier with PLT Scheme in the long run. diff --git a/collects/scribblings/quick/quick.scrbl b/collects/scribblings/quick/quick.scrbl index 37cc0f1a34..4b88786e87 100644 --- a/collects/scribblings/quick/quick.scrbl +++ b/collects/scribblings/quick/quick.scrbl @@ -182,7 +182,7 @@ instead of requiring a separate @scheme[define] for each identifier: (let ([p12 (hc-append p1 p2)] [p21 (hc-append p2 p1)]) (vc-append p12 p21))) -(checker (colorize (square 10) "red") +(checker (colorize (square 10) "red") (colorize (square 10) "black")) ] diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index a6f2e327ae..42fdd52a5a 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -42,7 +42,7 @@ positions are initialized with the given @scheme[b]s. @examples[(bytes 65 112 112 108 101)]} -@defproc[(bytes->immutable-bytes [bstr bytes?]) +@defproc[(bytes->immutable-bytes [bstr bytes?]) (and/c bytes? immutable?)]{ Returns an immutable byte string with the same content @@ -110,9 +110,9 @@ positions are initialized with the given @scheme[b]s. @defproc[(bytes-copy! [dest (and/c bytes? (not/c immutable?))] [dest-start exact-nonnegative-integer?] [src bytes?] - [src-start exact-nonnegative-integer? 0] + [src-start exact-nonnegative-integer? 0] [src-end exact-nonnegative-integer? (bytes-length src)]) - void?]{ + void?]{ Changes the bytes of @scheme[dest] from positions @scheme[dest-start] (inclusive) to @scheme[dest-end] (exclusive) to match the bytes in @scheme[src] from @scheme[src-start] @@ -199,8 +199,8 @@ positions are initialized with the given @scheme[b]s. @section{Bytes to/from Characters, Decoding and Encoding} -@defproc[(bytes->string/utf-8 [bstr bytes?] - [err-char (or/c false/c char?) #f] +@defproc[(bytes->string/utf-8 [bstr bytes?] + [err-char (or/c false/c char?) #f] [start exact-nonnegative-integer? 0] [end exact-nonnegative-integer? (bytes-length bstr)]) string?]{ @@ -214,7 +214,7 @@ positions are initialized with the given @scheme[b]s. @scheme[start] to @scheme[end] substring of @scheme[bstr] is not a valid UTF-8 encoding overall, then the @exnraise[exn:fail:contract].} -@defproc[(bytes->string/locale [bstr bytes?] +@defproc[(bytes->string/locale [bstr bytes?] [err-char (or/c false/c char?) #f] [start exact-nonnegative-integer? 0] [end exact-nonnegative-integer? (bytes-length bstr)]) @@ -239,9 +239,9 @@ positions are initialized with the given @scheme[b]s. Latin-1 footnote of @secref["encodings"].) The @scheme[err-char] argument is ignored, but present for consistency with the other operations.} - + @defproc[(string->bytes/utf-8 [str string?] - [err-byte (or/c false/c byte?) #f] + [err-byte (or/c false/c byte?) #f] [start exact-nonnegative-integer? 0] [end exact-nonnegative-integer? (string-length str)]) bytes?]{ @@ -250,8 +250,8 @@ positions are initialized with the given @scheme[b]s. @scheme[err-byte] argument is ignored, but included for consistency with the other operations.} -@defproc[(string->bytes/locale [str string?] - [err-byte (or/c false/c byte?) #f] +@defproc[(string->bytes/locale [str string?] + [err-byte (or/c false/c byte?) #f] [start exact-nonnegative-integer? 0] [end exact-nonnegative-integer? (string-length str)]) bytes?]{ @@ -264,7 +264,7 @@ positions are initialized with the given @scheme[b]s. then the @exnraise[exn:fail:contract].} @defproc[(string->bytes/latin-1 [str string?] - [err-byte (or/c false/c byte?) #f] + [err-byte (or/c false/c byte?) #f] [start exact-nonnegative-integer? 0] [end exact-nonnegative-integer? (string-length str)]) bytes?]{ @@ -298,7 +298,7 @@ positions are initialized with the given @scheme[b]s. result is @scheme[#f]. Otherwise, @scheme[err-char] is used to resolve decoding errors as in @scheme[bytes->string/utf-8].} -@defproc[(bytes-utf-8-ref [bstr bytes?] +@defproc[(bytes-utf-8-ref [bstr bytes?] [skip exact-nonnegative-integer? 0] [err-char (or/c false/c char?) #f] [start exact-nonnegative-integer? 0] diff --git a/collects/scribblings/reference/define-struct.scrbl b/collects/scribblings/reference/define-struct.scrbl index 0a597710a2..a1c6850f19 100644 --- a/collects/scribblings/reference/define-struct.scrbl +++ b/collects/scribblings/reference/define-struct.scrbl @@ -5,7 +5,7 @@ @guideintro["guide:define-struct"]{@scheme[define-struct]} -@defform/subs[(define-struct id-maybe-super (field ...) +@defform/subs[(define-struct id-maybe-super (field ...) struct-option ...) ([id-maybe-super id (id super-id)] @@ -137,7 +137,7 @@ cp This form can only appear as an expression within a @scheme[define-struct] form; normally, it is used with @scheme[#:property], especially for a property like -@scheme[prop:procedure]. The result of +@scheme[prop:procedure]. The result of @defexamples[ (define-struct mood-procedure ([base #:immutable] rating) diff --git a/collects/scribblings/reference/exns.scrbl b/collects/scribblings/reference/exns.scrbl index 44f92db733..98a7786e30 100644 --- a/collects/scribblings/reference/exns.scrbl +++ b/collects/scribblings/reference/exns.scrbl @@ -48,7 +48,7 @@ string. The different forms produce the error string in different ways: @itemize{ - + @item{@scheme[(error sym)] creates a message string by concatenating @scheme["error: "] with the string form of @scheme[sym].} @@ -84,7 +84,7 @@ for end users.} @defproc*[([(raise-type-error [name symbol?][expected string?][v any/c]) any] [(raise-type-error [name symbol?][expected string?][bad-pos non-negative-exact-integer?][v any/c]) any])]{ - + Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as an exception. The @scheme[name] argument is used as the source procedure's name in the error message. The @scheme[expected] argument @@ -113,7 +113,7 @@ the procedure. The printed form of @scheme[v] is appended to @defproc[(raise-arity-error [name (or/c symbol? procedure?)] [arity-v (or/c exact-nonnegative-integer? arity-at-least? - (listof + (listof (or/c exact-nonnegative-integer? arity-at-least?)))] [arg-v any/c #f] ...) @@ -134,7 +134,7 @@ message.} @defproc[(raise-syntax-error [name (or/c symbol? false/c)] [message string?] [expr any/c #f] - [sub-expr any/c #f]) + [sub-expr any/c #f]) any]{ Creates an @scheme[exn:fail:syntax] value and @scheme[raise]s it as an @@ -191,7 +191,7 @@ extension of the current continuation that does not have its own exception handler), then @scheme[f] is applied to the @scheme[raise]d value in the continuation of the @scheme[raise] call (but extended with a continuation barrier; see @secref["mz:continuations"]). - + Any procedure that takes one argument can be an exception handler. If the exception handler returns a value when invoked by @scheme[raise], then @scheme[raise] propagates the value to the ``previous'' exception diff --git a/collects/scribblings/reference/for.scrbl b/collects/scribblings/reference/for.scrbl index f2a8773d23..feae931991 100644 --- a/collects/scribblings/reference/for.scrbl +++ b/collects/scribblings/reference/for.scrbl @@ -208,17 +208,17 @@ Like @scheme[for/fold], but with the implicit nesting of @scheme[for*].} @;------------------------------------------------------------------------ @section{Deriving New Iteration Forms} -@defform[(for/fold/derived orig-datum +@defform[(for/fold/derived orig-datum ([accum-id init-expr] ...) (for-clause ...) . body)]{ Like @scheme[fold/fold], but the extra @scheme[orig-datum] is used as the source for all syntax errors. } -@defform[(for*/fold/derived orig-datum +@defform[(for*/fold/derived orig-datum ([accum-id init-expr] ...) (for-clause ...) . body)]{ Like @scheme[fold*/fold], but the extra @scheme[orig-datum] is used as the source for all syntax errors. } -@defform[(define-sequence-syntax id +@defform[(define-sequence-syntax id expr-transform-expr clause-transform-expr)]{ @@ -255,7 +255,7 @@ use @scheme[:do-in].} (loop-arg ...))]{ A form that can only be used as a @scheme[_seq-expr] in a -@scheme[_clause] of @scheme[for] (or one of its variants). +@scheme[_clause] of @scheme[for] (or one of its variants). Within a @scheme[for], the pieces of the @scheme[:do-in] form are spliced into the iteration essentially as follows: diff --git a/collects/scribblings/reference/model.scrbl b/collects/scribblings/reference/model.scrbl index 7c6f2de5a9..873caa2935 100644 --- a/collects/scribblings/reference/model.scrbl +++ b/collects/scribblings/reference/model.scrbl @@ -23,7 +23,7 @@ @define[(*state c e) (make-element #f (list langle c comma e rangle))] @define-syntax[state (syntax-rules () [(_ a b) (*state (scheme a) (scheme b))])] -@define[(frame n) (make-element "schemevariable" +@define[(frame n) (make-element "schemevariable" (list "C" (make-element 'subscript (list (format "~a" n)))))] @;------------------------------------------------------------------------ diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index 21facb6bc5..e11d92c2fb 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -146,7 +146,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(inexact->exact 1) (inexact->exact 1.0)]} - + @defproc[(exact->inexact [z number?]) inexact?]{ Coerces @scheme[z] to an inexact number. If @scheme[z] is already inexact, it is returned. @@ -188,7 +188,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(/ 3 4) (/ 81 3 3) (/ 10.0) (/ 1+2i 3+4i)] -@defproc[(quotient [n integer?] [m integer?]) integer?]{ Returns +@defproc[(quotient [n integer?] [m integer?]) integer?]{ Returns @scheme[(truncate (/ n m))].} @examples[(quotient 10 3) (quotient -10.0 3) (quotient +inf.0 3)] @@ -371,7 +371,7 @@ noted above). Two numbers are @scheme[equal?] when they are @examples[(integer-sqrt 4.0) (integer-sqrt 5)]} -@defproc[(integer-sqrt/remainder [n integer?]) +@defproc[(integer-sqrt/remainder [n integer?]) (values integer? integer?)]{ Returns @scheme[(integer-sqrt n)] and @scheme[(- n (expt (integer-sqrt n) 2))]. @@ -531,7 +531,7 @@ noted above). Two numbers are @scheme[equal?] when they are @; ------------------------------------------------------------------------ @section{Number--String Conversions} -@defproc[(number->string [z number?] +@defproc[(number->string [z number?] [radix (one-of/c 2 8 10 16) 10]) string?]{ Returns a string that is the printed form of @scheme[z] in the base specific by @scheme[radix]. If @scheme[z] is inexact, @@ -549,6 +549,6 @@ noted above). Two numbers are @scheme[equal?] when they are base for the number, which can be overriden by @litchar{#b}, @litchar{#o}, @litchar{#d}, or @litchar{#x} in the string. -@examples[(string->number "3.0+2.5i") (string->number "hello") +@examples[(string->number "3.0+2.5i") (string->number "hello") (string->number "111" 7) (string->number "#b111" 7)] -} \ No newline at end of file +} diff --git a/collects/scribblings/reference/procedures.scrbl b/collects/scribblings/reference/procedures.scrbl index 238898e54f..9bdded131d 100644 --- a/collects/scribblings/reference/procedures.scrbl +++ b/collects/scribblings/reference/procedures.scrbl @@ -25,10 +25,10 @@ is called in tail position with respect to the @scheme[apply] call. ]} -@defproc[(keyword-apply [proc procedure?] +@defproc[(keyword-apply [proc procedure?] [kw-lst (listof keyword?)] [kw-val-lst list?] - [v any/c] ... + [v any/c] ... [lst list?]) any]{ @@ -53,10 +53,10 @@ and @scheme[lst]; otherwise, the @exnraise[exn:fail:contract]. (keyword-apply f '(#:y #:z) '(2 3) '(1)) ]} -@defproc[(procedure-arity [proc procedure?]) +@defproc[(procedure-arity [proc procedure?]) (or/c exact-nonnegative-integer? arity-at-least? - (listof + (listof (or/c exact-nonnegative-integer? arity-at-least?)))]{ @@ -100,7 +100,7 @@ when no keyword arguments are supplied, @scheme[#f] otherwise. @defproc[(procedure-keywords [proc procedure?]) (values (listof keyword?) - (or/c (listof keyword?) + (or/c (listof keyword?) false/c))]{ Returns information about the keyword arguments required and accepted diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl index 7c0390b741..9dab65bfe8 100644 --- a/collects/scribblings/reference/read.scrbl +++ b/collects/scribblings/reference/read.scrbl @@ -47,10 +47,10 @@ Along with @schemelink[char-whitespace?]{whitespace}, the following characters are @defterm{delimiters}: @t{ - @hspace[2] @ilitchar{(} @ilitchar{)} @ilitchar{[} @ilitchar{]} + @hspace[2] @ilitchar{(} @ilitchar{)} @ilitchar{[} @ilitchar{]} @ilitchar["["] @ilitchar["]"] @ilitchar{"} @ilitchar{,} @ilitchar{'} @ilitchar{`} - @ilitchar{;} + @ilitchar{;} } A delimited sequence that starts with any other character is typically @@ -235,7 +235,7 @@ with any other mark, double-precision IEEE floating point is used. @BNF-seq[@nonterm{sign} @nunterm{inexact-special}]) (list @nunterm{inexact-unsigned} @BNF-alt[@nunterm{inexact-normal} @nunterm{inexact-special}]) - (list @nunterm{inexact-normal} @BNF-seq[@nunterm{inexact-simple} @optional{@nunterm{exp-mark} + (list @nunterm{inexact-normal} @BNF-seq[@nunterm{inexact-simple} @optional{@nunterm{exp-mark} @optional[@nonterm{sign}] @nunterm{digits#}}]) (list @nunterm{inexact-simple} @BNF-seq[@nunterm{digits#} @optional{@litchar{.}} @kleenestar{@litchar{#}}] @BNF-seq[@optional{@nunterm{exact-integer}} @litchar{.} @nunterm{digits#}] @@ -364,7 +364,7 @@ Within a string sequence, the following escape sequences are recognized: @itemize{ - + @item{@as-index{@litchar["\\a"]}: alarm (ASCII 7)} @item{@as-index{@litchar["\\b"]}: backspace (ASCII 8)} @item{@as-index{@litchar["\\t"]}: tab (ASCII 9)} @@ -625,7 +625,7 @@ following forms: do not match any of the previous cases, and as long as the character after @nonterm{c} is not @schemelink[char-alphabetic?]{alphabetic}.} - + } @reader-examples diff --git a/collects/scribblings/reference/regexps.scrbl b/collects/scribblings/reference/regexps.scrbl index 39bb11ab8d..5278db5a64 100644 --- a/collects/scribblings/reference/regexps.scrbl +++ b/collects/scribblings/reference/regexps.scrbl @@ -225,7 +225,7 @@ The first [byte] string in a result list is the portion of @scheme[input] that matched @scheme[pattern]. If two portions of @scheme[input] can match @scheme[pattern], then the match that starts earliest is found. - + Additional [byte] strings are returned in the list if @scheme[pattern] contains parenthesized sub-expressions (but not when the open parenthesis is followed by @litchar{?:}). Matches for the @@ -313,7 +313,7 @@ match succeeds, @scheme[#f] otherwise.} (or/c (listof (or/c (cons bytes? bytes?) false/c)) false/c)]{ - + Like @scheme[regexp-match] on input ports, but only peeks bytes from @scheme[input-port] instead of reading them. Furthermore, instead of an output port, the last optional argument is a progress event for @@ -379,7 +379,7 @@ then returns a string in which the matching portion of @scheme[input] is replaced with @scheme[insert-string]. If @scheme[char-pattern] matches no part of @scheme[string], then @scheme[string] is returned unmodified. - + The @scheme[char-pattern] must be a string or a character regexp value (not a byte string or a byte regexp value). diff --git a/collects/scribblings/reference/sequences.scrbl b/collects/scribblings/reference/sequences.scrbl index 3be528163d..45210e202e 100644 --- a/collects/scribblings/reference/sequences.scrbl +++ b/collects/scribblings/reference/sequences.scrbl @@ -67,7 +67,7 @@ previous element. The sequence starts before an element that would be greater or equal to @scheme[end] if @scheme[step] is non-negative, or less or equal to @scheme[end] if @scheme[step] is negative. @speed[in-range "number"]} - + @defproc[(in-naturals [start exact-nonnegative-integer? 0]) sequence?]{ Returns an infinite sequence of exact integers starting with @scheme[start], where each element is one more than the preceeding diff --git a/collects/scribblings/reference/strings.scrbl b/collects/scribblings/reference/strings.scrbl index f454464a05..99615affab 100644 --- a/collects/scribblings/reference/strings.scrbl +++ b/collects/scribblings/reference/strings.scrbl @@ -103,9 +103,9 @@ Returns an immutable string with the same content as @defproc[(string-copy! [dest (and/c string? (not/c immutable?))] [dest-start exact-nonnegative-integer?] [src string?] - [src-start exact-nonnegative-integer? 0] + [src-start exact-nonnegative-integer? 0] [src-end exact-nonnegative-integer? (string-length src)]) - void?]{ + void?]{ Changes the characters of @scheme[dest] from positions @scheme[dest-start] (inclusive) to @scheme[dest-end] (exclusive) to match the characters in @scheme[src] from @scheme[src-start] @@ -169,7 +169,7 @@ Returns an immutable string with the same content as @examples[(string=? "Apple" "apple") (string=? "a" "as" "a")] -@define[(string-sort direction folded?) +@define[(string-sort direction folded?) (if folded? @elem{Like @scheme[string-ci any)]) thread]{ +@defproc[(thread/suspend-to-kill [thunk (-> any)]) thread]{ Like @scheme[thread], except that ``killing'' the thread through @scheme[kill-thread] or @scheme[custodian-shutdown-all] merely diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl index ac4c86063e..1561d09d95 100644 --- a/collects/scribblings/scribble/basic.scrbl +++ b/collects/scribblings/scribble/basic.scrbl @@ -106,7 +106,7 @@ style @scheme[#f].} Produces an element containing @scheme[n] spaces and style @scheme['hspace]. } -@defproc[(span-class [style-name string?] [pre-content any/c] ...) +@defproc[(span-class [style-name string?] [pre-content any/c] ...) element?]{ Parses the @scheme[pre-content] list using @scheme[decode-content], diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl index 3af9acb34a..19becfb32b 100644 --- a/collects/scribblings/scribble/decode.scrbl +++ b/collects/scribblings/scribble/decode.scrbl @@ -41,10 +41,10 @@ in the enclosing flow. } -@defproc[(decode-part [lst list?] - [tag string?] - [title (or/c false/c list?)] - [depth excat-nonnegative-integer?]) +@defproc[(decode-part [lst list?] + [tag string?] + [title (or/c false/c list?)] + [depth excat-nonnegative-integer?]) part?]{ Like @scheme[decode], but given a tag for the section, a title (if diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index 7b5745e92c..cd800ce4c2 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -162,8 +162,8 @@ in a form definition.} @; ------------------------------------------------------------------------ @section{Definition Reference} -@defform[(defproc (id arg-spec ...) - result-contract-expr-datum +@defform[(defproc (id arg-spec ...) + result-contract-expr-datum pre-flow ...)]{ Produces a sequence of flow elements (encaptured in a @scheme[splice]) @@ -209,7 +209,7 @@ source layout.} @defform[(defproc* ([(id arg-spec ...) - result-contract-expr-datum] ...) + result-contract-expr-datum] ...) pre-flow ...)]{ Like @scheme[defproc], but for multiple cases with the same @@ -240,8 +240,8 @@ layout, like @scheme[schemeblock], and unlike @scheme[defproc].} Like @scheme[defform], but for multiple forms using the same @scheme[id].} -@defform/subs[(defform/subs maybe-literals (id . datum) - ([nonterm-id clause-datum ...+] ...) +@defform/subs[(defform/subs maybe-literals (id . datum) + ([nonterm-id clause-datum ...+] ...) pre-flow ...) ([maybe-literals code:blank (code:line #:literals (literal-id ...))])]{ diff --git a/collects/scribblings/scribble/reader.scrbl b/collects/scribblings/scribble/reader.scrbl index 2221a91743..d212fab344 100644 --- a/collects/scribblings/scribble/reader.scrbl +++ b/collects/scribblings/scribble/reader.scrbl @@ -61,7 +61,7 @@ constructs on an interactive REPL since reading an expression succeeds only when there is a new expression available.) In the readtable, @litchar["@"] is set as a terminating reader macro, so if you want to use it in Scheme code, you need to quote it as @scheme{\@} or the whole -identifier with @scheme[|ba@rs|]. Of course, @litchar["@"] is not treated +identifier with @scheme[|ba@rs|]. Of course, @litchar["@"] is not treated specially in Scheme strings, character constants, etc. Roughly, a form matching the grammar above is read as @@ -120,7 +120,7 @@ the surrounding context must provide a binding for @scheme[foo] @scribble-examples[(list @litchar["'@foo{bar}"] @scheme['(foo "bar")])] -@; - - - - - - - - - - - - - - - - - - - - - - - - +@; - - - - - - - - - - - - - - - - - - - - - - - - @subsection{The Command Part} Besides being a Scheme identifier, the @nonterm{cmd} part of an @at @@ -332,7 +332,7 @@ instead. "@foo[\"@literally{}\"]" ] -@; - - - - - - - - - - - - - - - - - - - - - - - - +@; - - - - - - - - - - - - - - - - - - - - - - - - @subsubsub*section{Quoting in Body Texts} To quote braces or @at, precede them with a backslash. Note that this @@ -352,7 +352,7 @@ preserved in the text as usual. "@foo{b\\\\ar}" ] -@; - - - - - - - - - - - - - - - - - - - - - - - - +@; - - - - - - - - - - - - - - - - - - - - - - - - @subsubsub*section{Newlines and Indentation} When indentation is used, all-space indentation string syntaxes are diff --git a/collects/web-server/docs/reference/configuration.scrbl b/collects/web-server/docs/reference/configuration.scrbl index 3f6102f92a..e08699de2b 100644 --- a/collects/web-server/docs/reference/configuration.scrbl +++ b/collects/web-server/docs/reference/configuration.scrbl @@ -15,7 +15,7 @@ configuring the @web-server . @file{configuration/configuration-table-structs.ss} provides the following structures that represent a standard configuration (see @secref["web-server-unit.ss"]) of the @web-server . The contracts on this structure influence the valid types of values in -the configuration table S-expression file format described in +the configuration table S-expression file format described in @secref["configuration-table.ss"]. @defstruct[configuration-table @@ -25,14 +25,14 @@ the configuration table S-expression file format described in [default-host host-table?] [virtual-hosts (listof (cons/c string? host-table?))])] -@defstruct[host-table +@defstruct[host-table ([indices (listof string?)] [log-format symbol?] [messages messages?] [timeouts timeouts?] [paths paths?])] -@defstruct[host +@defstruct[host ([indices (listof string?)] [log-format symbol?] [log-path (or/c false/c path-string?)] @@ -60,14 +60,14 @@ the configuration table S-expression file format described in [protocol string?] [collect-garbage string?])] -@defstruct[timeouts +@defstruct[timeouts ([default-servlet number?] [password number?] [servlet-connection number?] [file-per-byte number?] [file-base number?])] -@defstruct[paths +@defstruct[paths ([conf (or/c false/c path-string?)] [host-base (or/c false/c path-string?)] [log (or/c false/c path-string?)] @@ -79,8 +79,8 @@ the configuration table S-expression file format described in @; ------------------------------------------------------------ @section[#:tag "configuration-table.ss"]{Configuration Table} -@file{configuration/configuration-table.ss} provides functions for -reading, writing, parsing, and printing @scheme[configuration-table] +@file{configuration/configuration-table.ss} provides functions for +reading, writing, parsing, and printing @scheme[configuration-table] structures. @defthing[default-configuration-table-path path?]{The default configuration table S-expression file.} @@ -166,7 +166,7 @@ to the @scheme[(current-namespace)] of the call-site. Example: @schemeblock[ - (make-make-servlet-namespace + (make-make-servlet-namespace #:to-be-copied-module-specs `((lib "database.ss" "my-module"))) ] } @@ -199,7 +199,7 @@ turn the paths given in the @scheme[configuration-table] into responders for the as the corresponding fields; with the content of the @scheme[text-file] as the body; and, with the @scheme[header]s as, you guessed it, headers. } - + @defproc[(servlet-loading-responder (url url?) (exn any/c)) response?]{ Prints the @scheme[exn] to standard output and responds with a "Servlet didn't load." @@ -215,7 +215,7 @@ message. ((url url?) (exn any/c) . -> . response?)]{ Prints the @scheme[exn] to standard output and responds with a "Servlet error." message with content from @scheme[file]. } - + @defproc[(gen-servlets-refreshed (file path-string?)) (-> response?)]{ Returns a function that generates a standard "Servlet cache refreshed." message with content from @scheme[file]. @@ -245,4 +245,4 @@ message. @defproc[(gen-collect-garbage-responder (file path-string?)) (-> response?)]{ Returns a function that generates a standard "Garbage collection run" message with content from @scheme[file]. -} \ No newline at end of file +} diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/reference/dispatchers.scrbl index a35142b458..dcadb94f28 100644 --- a/collects/web-server/docs/reference/dispatchers.scrbl +++ b/collects/web-server/docs/reference/dispatchers.scrbl @@ -21,10 +21,10 @@ documentation will be useful. @defthing[dispatcher? contract?]{ Equivalent to @scheme[(connection? request? . -> . void)]. } - + @defproc[(dispatcher-interface-version? (any any/c)) boolean?]{ Returns @scheme[#t] if @scheme[any] is @scheme['v1]. Returns @scheme[#f] otherwise. -} +} @defstruct[exn:dispatcher ()]{ An exception thrown to indicate that a dispatcher does not apply to a particular @@ -53,7 +53,7 @@ Consider the following example dispatcher, that captures the essence of URL rewr (copy-struct request req (code:comment "with a new URL!") [request-uri (rule (request-uri req))])))) -] +] @; ------------------------------------------------------------ @section[#:tag "filesystem-map.ss"]{Mapping URLs to Paths} @@ -70,7 +70,7 @@ URLs to paths on the filesystem. url-path?]{ The @scheme[url-path?] returned by this procedure considers the root URL to be @scheme[base]. It ensures that @scheme[".."]s in the URL - do not escape the @scheme[base] and removes them silently otherwise.} + do not escape the @scheme[base] and removes them silently otherwise.} @defproc[(make-url->valid-path (url->path url->path?)) url->path?]{ @@ -78,7 +78,7 @@ URLs to paths on the filesystem. refers to a file that actually exists. If it is does not, then the suffix elements of the URL are removed until a file is found. If this never occurs, then an error is thrown. - + This is primarily useful for dispatchers that allow path information after the name of a service to be used for data, but where the service is represented by a file. The most prominent example is obviously servlets.} @@ -95,7 +95,7 @@ that invokes a sequence of dispatchers until one applies. calls @scheme[next-dispatcher]. If no @scheme[dispatcher] applies, then it calls @scheme[next-dispatcher] itself. } - + @; XXX Kind of timeout that is proportional to bindings @; ------------------------------------------------------------ @section[#:tag "dispatch-timeout.ss"]{Timeouts} @@ -109,7 +109,7 @@ dispatcher. Changes the timeout on the connection with @scheme[adjust-connection-timeout!] called with @scheme[new-timeout]. } - + @; ------------------------------------------------------------ @section[#:tag "dispatch-lift.ss"]{Lifting Procedures} @@ -119,13 +119,13 @@ dispatcher. dispatcher?]{ Constructs a dispatcher that calls @scheme[proc] on the request object, and outputs the response to the connection. -} +} @; XXX Change filtering to take predicate, rather than regexp @; ------------------------------------------------------------ @section[#:tag "dispatch-filter.ss"]{Filtering Requests} -@file{dispatchers/dispatch-filter.ss} defines a dispatcher constructor +@file{dispatchers/dispatch-filter.ss} defines a dispatcher constructor that calls an underlying dispatcher with all requests that pass a predicate. @@ -133,7 +133,7 @@ with all requests that pass a predicate. dispatcher?]{ Calls @scheme[inner] if the URL path of the request, converted to a string, matches @scheme[regex]. Otherwise, calls @scheme[next-dispatcher]. -} +} @; ------------------------------------------------------------ @section[#:tag "dispatch-pathprocedure.ss"]{Procedure Invocation upon Request} @@ -147,10 +147,10 @@ URL path. Checks if the request URL path as a string is equal to @scheme[path] and if so, calls @scheme[proc] for a response. } - + This is used in the standard @web-server pipeline to provide a URL that refreshes the password file, servlet cache, etc. - + @; ------------------------------------------------------------ @section[#:tag "dispatch-log.ss"]{Logging} @@ -180,7 +180,7 @@ for transparent logging of requests. (referer ,(let ([R (headers-assq* #"Referer" (request-headers/raw req))]) (if R (header-value R) - #f))) + #f))) (uri ,(url->string (request-uri req))) (time ,(current-seconds)))) ]} @@ -195,14 +195,14 @@ for transparent logging of requests. @scheme['extended] to @scheme[extended-format], and @scheme['apache-default] to @scheme[apache-default-format]. } - + @defproc[(make [#:format format format-req/c paren-format] [#:log-path log-path path-string? "log"]) dispatcher?]{ Logs requests to @scheme[log-path] by using @scheme[format] to format the requests. Then invokes @scheme[next-dispatcher]. } - + @; ------------------------------------------------------------ @section[#:tag "dispatch-passwords.ss"]{Password Protection} @@ -210,22 +210,22 @@ for transparent logging of requests. that performs HTTP Basic authentication filtering. @defproc[(make [#:password-file password-file path-string? "passwords"] - [#:authentication-responder - authentication-responder + [#:authentication-responder + authentication-responder ((url url?) (header (cons/c symbol? string?)) . -> . response?) (gen-authentication-responder "forbidden.html")]) (values (-> void) dispatcher?)]{ The first returned value is a procedure that refreshes the password file used by the dispatcher. - - The dispatcher that is returned does the following: + + The dispatcher that is returned does the following: Checks if the request contains Basic authentication credentials, and that - they are included in @scheme[password-file]. If they are not, + they are included in @scheme[password-file]. If they are not, @scheme[authentication-responder] is called with a @scheme[header] that requests credentials. If they are, then @scheme[next-dispatcher] is invoked. - + @; XXX Separate out password-file work @scheme[password-file] is parsed as: @schemeblock[(list ([domain : string?] @@ -250,8 +250,8 @@ that calls a different dispatcher based upon the host requested. calls @scheme[lookup-dispatcher] with the host, and invokes the returned dispatcher. If no host can be extracted, then @scheme['none] is used. -} - +} + @; ------------------------------------------------------------ @section[#:tag "dispatch-files.ss"]{Serving Files} @@ -269,9 +269,9 @@ It defines a dispatcher construction procedure: a file already, @scheme[path->mime-type] is consulted for the MIME Type of the path. The file is then streamed out the connection object. - + This dispatcher supports HTTP Range GET requests and HEAD requests.} - + @; ------------------------------------------------------------ @section[#:tag "dispatch-servlets.ss"]{Serving Scheme Servlets} @@ -281,11 +281,11 @@ that runs servlets written in Scheme. @; XXX Remove config:scripts @defproc[(make [config:scripts (box/c cache-table?)] [#:url->path url->path url->path?] - [#:make-servlet-namespace + [#:make-servlet-namespace make-servlet-namespace make-servlet-namespace? (make-make-servlet-namespace)] - [#:responders-servlet-loading + [#:responders-servlet-loading responders-servlet-loading ((url url?) (exn any/c) . -> . response?) servlet-loading-responder] @@ -301,8 +301,8 @@ that runs servlets written in Scheme. dispatcher?)]{ The first returned value is a procedure that refreshes the servlet code cache. - - The dispatcher does the following: + + The dispatcher does the following: If the request URL contains a continuation reference, then it is invoked with the request. Otherwise, @scheme[url->path] is used to resolve the URL to a path. The path is evaluated as a module, in a namespace constructed by @scheme[make-servlet-namespace]. @@ -310,7 +310,7 @@ that runs servlets written in Scheme. with the exception. If it succeeds, then @scheme[start] export of the module is invoked. If there is an error when a servlet is invoked, then @scheme[responders-servlet] is used to format a response with the exception. - + Servlets that do not specify timeouts are given timeouts according to @scheme[timeouts-default-servlet]. } @@ -321,7 +321,7 @@ that runs servlets written in Scheme. that runs servlets written in the Web Language. @defproc[(make [#:url->path url->path url->path?] - [#:make-servlet-namespace make-servlet-namespace + [#:make-servlet-namespace make-servlet-namespace make-servlet-namespace? (make-make-servlet-namespace)] [#:responders-servlet-loading responders-servlet-loading servlet-loading-responder] @@ -334,4 +334,4 @@ that runs servlets written in the Web Language. with the exception. If it succeeds, then @scheme[start] export of the module is invoked. If there is an error when a servlet is invoked, then @scheme[responders-servlet] is used to format a response with the exception. -} +} diff --git a/collects/web-server/docs/reference/lang.scrbl b/collects/web-server/docs/reference/lang.scrbl index 9ff1df17ad..0ebdeefc67 100644 --- a/collects/web-server/docs/reference/lang.scrbl +++ b/collects/web-server/docs/reference/lang.scrbl @@ -13,7 +13,7 @@ is different and what API is provided. @; ------------------------------------------------------------ @section[#:tag "lang-servlets"]{Definition} -A @defterm{Web language servlet} is a module written in the +A @defterm{Web language servlet} is a module written in the @scheme[(lib "lang.ss" "web-server")] module language. It should provide the following identifier: @@ -25,7 +25,7 @@ the following identifier: @; ------------------------------------------------------------ @section[#:tag "considerations"]{Usage Considerations} - + A servlet has the following process performed on it automatically: @itemize[ @@ -33,7 +33,7 @@ A servlet has the following process performed on it automatically: @scheme[let] and imperative features. (@file{lang/elim-letrec.ss})} @item{The program is converted into ANF (Administrative Normal Form), making all continuations explicit. (@file{lang/anormal.ss})} - @item{All continuations (and other continuations marks) are recorded in the + @item{All continuations (and other continuations marks) are recorded in the continuation marks of the expression they are the continuation of. (@file{lang/elim-callcc.ss})} @item{All calls to external modules are identified and marked. @@ -87,7 +87,7 @@ Fifth, the store is NOT serialized. If you rely on the store you will be taking huge risks. You will be assuming that the serialized continuation is invoked before the server is restarted or the memory is garbage collected. -This process is derived from the paper +This process is derived from the paper @href-link["http://www.cs.brown.edu/~sk/Publications/Papers/Published/pcmkf-cont-from-gen-stack-insp/" "\"Continuations from Generalized Stack Inspection\""]. We thank Greg Pettyjohn for his initial implementation of this algorithm. @@ -119,7 +119,7 @@ by the Web language API. the response to the client. If the URL is invoked with form data containing the hidden form, the request is returned to this continuation. - + Note: The continuation is NOT stuffed. } @@ -129,13 +129,13 @@ by the Web language API. Serializes and stuffs @scheme[proc] into @scheme[k-url]. For use with @scheme[extract-proc/url]. } - + @defproc[(extract-proc/url [req request?]) any/c]{ Inspects the URL of @scheme[req] and attempts to extract the procedure embedded with @scheme[embed-proc/url]. If successful, it is invoked with @scheme[req] as an argument. -} +} @; ------------------------------------------------------------ @section[#:tag "lang/stuff-url.ss"]{Stuff URL} @@ -153,12 +153,12 @@ the future. @file{$HOME/.urls/M} where `M' is the MD5. `M' is then placed in @scheme[u] as a URL param. } - + @defproc[(stuffed-url? [u url?]) boolean?]{ Checks if @scheme[u] appears to be produced by @scheme[stuff-url]. } - + @defproc[(unstuff-url [u url?]) serializable?]{ Extracts the value previously serialized into @scheme[u] by @scheme[stuff-url]. @@ -190,37 +190,37 @@ boxes in a safe way. @defproc[(file-box? [v any/c]) boolean?]{Checks if @scheme[v] is a file-box.} - + @defproc[(file-box [p path?] [v serializable?]) file-box?]{ Creates a file-box that is stored at @scheme[p], with the default contents of @scheme[v]. } - + @defproc[(file-unbox [fb file-box?]) serializable?]{ Returns the value inside @scheme[fb] } - + @defproc[(file-box-set? [fb file-box?]) boolean?]{ Returns @scheme[#t] if @scheme[fb] contains a value. } - + @defproc[(file-box-set! [fb file-box?] [v serializable?]) void]{ Saves @scheme[v] in the file represented by @scheme[fb]. } - + @warning{If you plan on using a load-balancer, make sure your file-boxes are on a shared medium.} @; ------------------------------------------------------------ @section[#:tag "lang/web-param.ss"]{Web Parameters} -As mentioned earlier, it is not easy to use @scheme[parameterize] in the +As mentioned earlier, it is not easy to use @scheme[parameterize] in the Web Language. @file{lang/web-param.ss} provides (roughly) the same functionality in a way that is serializable. Like other serializable things in the Web Language, they are sensitive to source code modification. @@ -231,15 +231,15 @@ things in the Web Language, they are sensitive to source code modification. a procedure that, when called with zero arguments, returns @scheme[default] or the last value @scheme[web-parameterize]d in the dynamic context of the call. -} +} @defproc[(web-parameter? [v any/c]) boolean?]{ Checks if @scheme[v] appears to be a web-parameter. -} +} @defform[(web-parameterize ([web-parameter-expr value-expr] ...) expr ...)]{ - Runs @scheme[(begin expr ...)] such that the web-parameters that + Runs @scheme[(begin expr ...)] such that the web-parameters that the @scheme[web-parameter-expr]s evaluate to are bound to the @scheme[value-expr]s. From the perspective of the @scheme[value-expr]s, this is like @scheme[let]. } diff --git a/collects/web-server/docs/reference/managers.scrbl b/collects/web-server/docs/reference/managers.scrbl index a79be33fb3..847ccf0db9 100644 --- a/collects/web-server/docs/reference/managers.scrbl +++ b/collects/web-server/docs/reference/managers.scrbl @@ -6,7 +6,7 @@ Since Scheme servlets store their continuations on the server, they take up memory on the server. Furthermore, garbage collection can not be used -to free this memory, because there are roots outside the system: users' +to free this memory, because there are roots outside the system: users' browsers, bookmarks, brains, and notebooks. Therefore, some other strategy must be used if memory usage is to be controlled. This functionality is pluggable through the manager interface. @@ -25,40 +25,40 @@ the users and implementers of managers. [continuation-store! (number? any/c expiration-handler? . -> . (list/c number? number?))] [continuation-lookup (number? number? number? . -> . any/c)])]{ @scheme[create-instance] is called to initialize a instance, to hold the - continuations of one servlet session. It is passed + continuations of one servlet session. It is passed a function to call when the instance is expired. It runs the id of the instance. - + @scheme[adjust-timeout!] is a to-be-deprecated function that takes an instance-id and a number. It is specific to the timeout-based manager and will be removed. - + @scheme[clear-continuations!] expires all the continuations of an instance. - + @scheme[continuation-store!] is given an instance-id, a continuation value, - and a function to include in the exception thrown if the continuation is + and a function to include in the exception thrown if the continuation is looked up and has been expired. The two numbers returned are a continuation-id and a nonce. - + @scheme[continuation-lookup] finds the continuation value associated with the instance-id, continuation-id, and nonce triple it is given. } - -@defstruct[(exn:fail:servlet-manager:no-instance exn:fail) + +@defstruct[(exn:fail:servlet-manager:no-instance exn:fail) ([message string?] [continuation-marks continuation-mark-set?] [expiration-handler expiration-handler?])]{ This exception should be thrown by a manager when an instance is looked up that does not exist. } - + @defstruct[(exn:fail:servlet-manager:no-continuation exn:fail) ([message string?] [continuation-marks continuation-mark-set?] [expiration-handler expiration-handler?])]{ This exception should be thrown by a manager when a continuation is looked up that does not exist. -} +} @; ------------------------------------------------------------ @section[#:tag "none.ss"]{No Continuations} @@ -71,7 +71,7 @@ the users and implementers of managers. You could use it if you know your servlet does not use the continuation capturing functions and want the server to not allocate meta-data structures for each instance. -} +} If you are considering using this manager, also consider using the Web Language. (See @secref["lang"].) @@ -89,20 +89,20 @@ Web Language. (See @secref["lang"].) seconds after the last time it is accessed. If an expired instance is looked up, the @scheme[exn:fail:servlet-manager:no-instance] exception is thrown with @scheme[instance-exp-handler] as the expiration handler. - + Continuations managed by this manager will be expired @scheme[continuation-timeout] seconds after the last time it is accessed. If an expired continuation is looked up, the @scheme[exn:fail:servlet-manager:no-continuation] exception is thrown with @scheme[instance-exp-handler] as the expiration handler, if no expiration-handler was passed to @scheme[continuation-store!]. - - @scheme[adjust-timeout!] corresponds to @scheme[reset-timer!] on the timer + + @scheme[adjust-timeout!] corresponds to @scheme[reset-timer!] on the timer responsible for the servlet instance. } This manager has been found to be... problematic... in large-scale deployments of the @web-server . - + @; ------------------------------------------------------------ @section[#:tag "lru.ss"]{LRU} @@ -127,20 +127,20 @@ deployments of the @web-server . up, the @scheme[exn:fail:servlet-manager:no-continuation] exception is thrown with @scheme[instance-exp-handler] as the expiration handler, if no expiration-handler was passed to @scheme[continuation-store!]. - + Every @scheme[check-interval] seconds @scheme[collect?] is called to determine if the collection routine should be run. Every @scheme[collect-interval] seconds - the collection routine is run. - + the collection routine is run. + Every time the collection routine runs, the "Life Count" of every continuation is decremented by @scheme[1]. If a continuation's count reaches @scheme[0], it is expired. The @scheme[inform-p] function is called if any continuations are expired, with the number of continuations expired. } - + The recommended use of this manager is to pass, as @scheme[collect?], a -function that checks the memory usage of the system, through +function that checks the memory usage of the system, through @scheme[current-memory-use]. Then, @scheme[collect-interval] should be sufficiently large compared to @scheme[check-interval]. This way, if the load on the server spikes---as indicated by memory usage---the server will quickly expire diff --git a/collects/web-server/docs/reference/private.scrbl b/collects/web-server/docs/reference/private.scrbl index 998248e372..6a4e3cf883 100644 --- a/collects/web-server/docs/reference/private.scrbl +++ b/collects/web-server/docs/reference/private.scrbl @@ -10,7 +10,7 @@ Some of these are documented here. @local-table-of-contents[] - + @; ------------------------------------------------------------ @section[#:tag "timer.ss"]{Timers} @@ -23,38 +23,38 @@ procedures after a given amount of time, that may be extended. @scheme[evt] is an @scheme[alarm-evt] that is ready at @scheme[expire-seconds]. @scheme[action] should be called when this @scheme[evt] is ready. } - + @defproc[(start-timer-manager [cust custodian?]) void]{ Handles the execution and management of timers. Resources are charged to @scheme[cust]. } - + @defproc[(start-timer [s number?] [action (-> void)]) timer?]{ Registers a timer that runs @scheme[action] after @scheme[s] seconds. } - + @defproc[(reset-timer! [t timer?] [s number?]) void]{ Changes @scheme[t] so that it will fire after @scheme[s] seconds. } - + @defproc[(increment-timer! [t timer?] [s number?]) void]{ Changes @scheme[t] so that it will fire after @scheme[s] seconds from when it does now. } - + @defproc[(cancel-timer! [t timer?]) void]{ Cancels the firing of @scheme[t] ever and frees resources used by @scheme[t]. } - + @; XXX Generalize @; ------------------------------------------------------------ @section[#:tag "connection-manager.ss"]{Connection Manager} @@ -72,14 +72,14 @@ for doing this. associated with the connection should be allocated under @scheme[custodian]. The connection will last until @scheme[timer] triggers. } - + @; XXX Don't pass in parent-cust @defproc[(start-connection-manager [parent-cust custodian?]) void]{ Runs the connection manager (now just the timer manager) will @scheme[parent-cust] as the custodian. -} - +} + @defproc[(new-connection [timeout number?] [i-port input-port?] [o-port output-port?] @@ -89,18 +89,18 @@ for doing this. Constructs a connection with a timer with a trigger of @scheme[timeout] that calls @scheme[kill-connection!]. } - + @defproc[(kill-connection! [c connection?]) void]{ Closes the ports associated with @scheme[c], kills the timer, and shuts down the custodian. } - + @defproc[(adjust-connection-timeout! [c connection?] [t number?]) void]{ Calls @scheme[reset-timer!] with the timer behind @scheme[c] with @scheme[t]. -} +} @; ------------------------------------------------------------ @section[#:tag "dispatch-server-unit.ss"]{Dispatching Server} @@ -147,7 +147,7 @@ which actually implements a dispatching server. @defthing[dispatch-server\@ (unit/c (tcp^ dispatch-server-config^) (dispatch-server^))]{ Runs the dispatching server config in a very basic way, except that it uses @secref["connection-manager.ss"] to manage connections. -} +} @; ------------------------------------------------------------ @section[#:tag "closure.ss"]{Serializable Closures} @@ -166,12 +166,12 @@ requires an explicit representation of closures that is serializable. @scheme[proc], which is assumed to be syntax of @scheme[lambda] or @scheme[case-lambda]. } - + @defproc[(closure->deserialize-name [c closure?]) symbol?]{ Extracts the unique tag of a closure @scheme[c] } - + These are difficult to use directly, so @file{private/define-closure.ss} defines a helper form: @@ -179,7 +179,7 @@ defines a helper form: Defines a closure, constructed with @scheme[make-tag] that accepts @scheme[freevars ...], that when invoked with @scheme[formals] executes @scheme[body]. -} +} @; XXX Example @@ -193,7 +193,7 @@ functions. cache-table?]{ Constructs a cache-table. } - + @defproc[(cache-table-lookup! [ct cache-table?] [id symbol?] [mk (-> any/c)]) @@ -201,17 +201,17 @@ functions. Looks up @scheme[id] in @scheme[ct]. If it is not present, then @scheme[mk] is called to construct the value and add it to @scheme[ct]. } - + @defproc[(cache-table-clear! [ct cache-table?]) void?]{ Clears all entries in @scheme[ct]. } - + @defproc[(cache-table? [v any/c]) boolean?]{ Determines if @scheme[v] is a cache table. -} - +} + @; ------------------------------------------------------------ @section[#:tag "mime-types.ss"]{MIME Types} @@ -223,12 +223,12 @@ files. Reads the @file{mime.types} file from @scheme[p] and constructs a hash table mapping extensions to MIME types. } - + @defproc[(make-path->mime-type [p path?]) (path? . -> . bytes?)]{ Uses a @scheme[read-mime-types] with @scheme[p] and constructs a function from paths to their MIME type. -} +} @; XXX Rename mod-map.ss @; ------------------------------------------------------------ @@ -241,14 +241,14 @@ values. @file{private/mod-map.ss} compresses the serialized representation. compressed-serialized-value?]{ Collapses multiple occurrences of the same module in the module map of the serialized representation, @scheme[sv]. -} - +} + @defproc[(decompress-serial [csv compressed-serialized-value?]) serialized-value?]{ Expands multiple occurrences of the same module in the module map of the compressed serialized representation, @scheme[csv]. -} - +} + @; ------------------------------------------------------------ @section[#:tag "url-param.ss"]{URL Param} @@ -265,14 +265,14 @@ with this process. Associates @scheme[k] with @scheme[v] in the final URL param of @scheme[u], overwritting any current binding for @scheme[k]. } - + @defproc[(extract-param [u url?] [k string?]) (or/c string? false/c)]{ Extracts the string associated with @scheme[k] in the final URL param of @scheme[u], if there is one, returning @scheme[#f] otherwise. -} - +} + @; ------------------------------------------------------------ @section[#:tag "util.ss"]{Miscellaneous Utilities} @@ -297,13 +297,13 @@ needs. They are provided by @file{private/util.ss}. url?]{ Replaces the URL path of @scheme[u] with @scheme[proc] of the former path. } - -@; XXX Remove use or take url? + +@; XXX Remove use or take url? @defproc[(url-path->string [url-path (listof path/param?)]) string?]{ Formats @scheme[url-path] as a string with @scheme["/"] as a delimiter and no params. -} +} @subsection{Paths} @defproc[(explode-path* [p path?]) @@ -317,24 +317,24 @@ needs. They are provided by @file{private/util.ss}. Returns, as a list, the portion of @scheme[p] after @scheme[base], assuming @scheme[base] is a prefix of @scheme[p]. } - + @defproc[(directory-part [p path?]) path?]{ Returns the directory part of @scheme[p], returning @scheme[(current-directory)] if it is relative. } - + @defproc[(build-path-unless-absolute [base path-string?] [p path-string?]) path?]{ Prepends @scheme[base] to @scheme[p], unless @scheme[p] is absolute. } - + @defproc[(strip-prefix-ups [p (listof path-element?)]) (listof path-element?)]{ Removes all the prefix @scheme[".."]s from @scheme[p]. } - + @subsection{Exceptions} @defproc[(pretty-print-invalid-xexpr [exn exn:invalid-xexpr?] @@ -342,7 +342,7 @@ needs. They are provided by @file{private/util.ss}. void]{ Prints @scheme[v] as if it were almost an X-expression highlighting the error according to @scheme[exn]. -} +} @; XXX Remove @defproc[(network-error [s symbol?] @@ -351,25 +351,25 @@ needs. They are provided by @file{private/util.ss}. void]{ Like @scheme[error], but throws a @scheme[exn:fail:network]. } - + @defproc[(exn->string [exn (or/c exn? any/c)]) string?]{ Formats @scheme[exn] with @scheme[(error-display-handler)] as a string. } - + @subsection{Strings} @defproc[(lowercase-symbol! [sb (or/c string? bytes?)]) symbol?]{ Returns @scheme[sb] as a lowercase symbol. } - + @defproc[(read/string [s string?]) serializable?]{ @scheme[read]s a value from @scheme[s] and returns it. } - + @defproc[(write/string [v serializable?]) string?]{ @scheme[write]s @scheme[v] to a string and returns it. -} +} diff --git a/collects/web-server/docs/reference/reference.scrbl b/collects/web-server/docs/reference/reference.scrbl index 529dd2ec9d..406db7e6d4 100644 --- a/collects/web-server/docs/reference/reference.scrbl +++ b/collects/web-server/docs/reference/reference.scrbl @@ -27,10 +27,10 @@ develop Web applications in Scheme. We thank Matthew Flatt for his superlative work on MzScheme. We thank the previous maintainers of the @web-server : Paul T. Graunke, Mike Burns, and Greg Pettyjohn -Numerous people have -provided invaluable feedback on the server, including Eli Barzilay, Ryan Culpepper, Robby -Findler, Dan Licata, Matt Jadud, Jacob Matthews, Matthias Radestock, Andrey Skylar, -Michael Sperber, Dave Tucker, Anton van Straaten, and Noel Welsh. We also thank the +Numerous people have +provided invaluable feedback on the server, including Eli Barzilay, Ryan Culpepper, Robby +Findler, Dan Licata, Matt Jadud, Jacob Matthews, Matthias Radestock, Andrey Skylar, +Michael Sperber, Dave Tucker, Anton van Straaten, and Noel Welsh. We also thank the many other PLT Scheme users who have exercised the server and offered critiques. -@index-section["web-server-ref-index"] \ No newline at end of file +@index-section["web-server-ref-index"] diff --git a/collects/web-server/docs/reference/running.scrbl b/collects/web-server/docs/reference/running.scrbl index 953a338db8..d6866f9e36 100644 --- a/collects/web-server/docs/reference/running.scrbl +++ b/collects/web-server/docs/reference/running.scrbl @@ -3,7 +3,7 @@ @title[#:tag "run.ss" #:style 'toc]{Running the Web Server} - + There are a number of ways to run the Web Server. The two primary ways are through a command-line tool or through a function call. @@ -19,7 +19,7 @@ Two command-line utilities are provided with the @web-server : @exec{plt-web-server [-f -p -a ]} The first runs the @web-server with MzScheme, while the second runs -the server with MrEd, providing a graphical UI. The optional file-name +the server with MrEd, providing a graphical UI. The optional file-name argument specifies the path to a @scheme[configuration-table] S-expression (see @secref["configuration-table.ss"].) If this is not provided, the default configuration shipped with the server is used. The optional port and ip-address @@ -58,7 +58,7 @@ dispatcher. See @file{run.ss} for an example of such a script. Calls @scheme[serve] multiple times, once for each @scheme[port], and returns a function that shuts down all of the server instances. } - + @defproc[(serve/ips+ports [#:dispatch dispatch dispatcher?] [#:tcp\@ tcp\@ tcp-unit^ raw:tcp\@] [#:ips+ports ips+ports (listof (cons/c (or/c string? false/c) (listof integer?))) (list (cons #f (list 80)))] @@ -67,8 +67,8 @@ dispatcher. See @file{run.ss} for an example of such a script. (-> void)]{ Calls @scheme[serve/ports] multiple times, once for each @scheme[ip], and returns a function that shuts down all of the server instances. -} - +} + @defproc[(do-not-return) void]{ This function does not return. If you are writing a script to load the @web-server you are likely to want to call this functions at the end of your script. diff --git a/collects/web-server/docs/reference/servlet-env.scrbl b/collects/web-server/docs/reference/servlet-env.scrbl index 1b002319af..abca8b206a 100644 --- a/collects/web-server/docs/reference/servlet-env.scrbl +++ b/collects/web-server/docs/reference/servlet-env.scrbl @@ -10,7 +10,7 @@ from within DrScheme, or any other REPL. @file{servlet-env.ss} provides the servlet API from @file{servlet.ss} as well as the following: -@defthing[send-url (parameter/c ([url string?] [separate-window? boolean?] . -> . void))]{ +@defthing[send-url (parameter/c ([url string?] [separate-window? boolean?] . -> . void))]{ Should open @scheme[url]. In another window if @scheme[separate-window?] is true. By default this is from @scheme[(lib "sendurl.ss" "net")]. } @@ -23,4 +23,4 @@ as well as the following: @scheme[send-url] with a URL for the constructed servlet. The call blocks until the servlet finishes its computation, i.e. @scheme[servlet-expr] is evaluated, and returns its result. @scheme[servlet-expr] may use the entire Scheme servlet API. -} \ No newline at end of file +} diff --git a/collects/web-server/docs/reference/servlet.scrbl b/collects/web-server/docs/reference/servlet.scrbl index 061a33ed6b..7864206751 100644 --- a/collects/web-server/docs/reference/servlet.scrbl +++ b/collects/web-server/docs/reference/servlet.scrbl @@ -20,7 +20,7 @@ A @defterm{servlet} is a module that provides the following: to. This influences the other provided identifiers. } -If @scheme[interface-version] is @scheme['v1], then the servlet +If @scheme[interface-version] is @scheme['v1], then the servlet provides: @defthing[timeout integer?]{ @@ -36,7 +36,7 @@ provides: The argument is the HTTP request that initiated the instance. } -If @scheme[interface-version] is @scheme['v2], then the servlet +If @scheme[interface-version] is @scheme['v2], then the servlet provides: @defthing[manager manager?]{ @@ -54,7 +54,7 @@ provides: @file{servlet/servlet-structs.ss} provides a number of contracts for use in servlets. - + @defthing[k-url? contract?]{Equivalent to @scheme[string?].} @defthing[response-generator? contract?]{Equivalent to @scheme[(k-url? . -> . response?)].} @@ -94,21 +94,21 @@ related to HTTP request data structures. [value bytes?])]{ Represents a form binding of @scheme[id] to @scheme[value]. } - + @defstruct[(binding:file binding) ([id bytes?] [filename bytes?] [content bytes?])]{ Represents the uploading of the file @scheme[filename] with the id @scheme[id] and the content @scheme[content]. -} +} @defproc[(bindings-assq [id bytes?] [binds (listof binding?)]) (or/c false/c binding?)]{ Returns the binding with an id equal to @scheme[id] from @scheme[binds] or @scheme[#f]. } - -@defstruct[request ([method symbol?] - [uri url?] + +@defstruct[request ([method symbol?] + [uri url?] [headers/raw (listof header?)] [bindings/raw (listof binding?)] [post-data/raw (or/c false/c bytes?)] @@ -135,21 +135,21 @@ for accessing request bindings. of @scheme[binding:file] bindings, which are left as is. Ids are then translated into lowercase symbols. } - + @defproc[(request-headers [req request?]) (listof (cons/c symbol? string?))]{ Translates the @scheme[request-headers/raw] of @scheme[req] by interpreting @scheme[bytes?] as @scheme[string?]s. Ids are then translated into lowercase symbols. -} - +} + @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 raises @scheme[exn:fail]. } - + @defproc[(extract-bindings [id symbol?] [binds (listof (cons/c symbol? string?))]) (listof string?)]{ @@ -160,8 +160,8 @@ for accessing request bindings. [binds (listof (cons/c symbol? string))]) boolean?]{ Returns @scheme[#t] if @scheme[binds] contains a binding for @scheme[id]. - Otherwise, @scheme[#f]. -} + Otherwise, @scheme[#f]. +} These functions, while convenient, could introduce subtle bugs into your application. Examples: that they are case-insensitive could introduce @@ -170,7 +170,7 @@ to a string will fail; if an attacked submits a form field as if it were a file, when it is not, then the @scheme[request-bindings] will hold a @scheme[bytes?] object and your program will error; and, for file uploads you lose the filename. - + @; ------------------------------------------------------------ @section[#:tag "response-structs.ss"]{HTTP Responses} @@ -188,7 +188,7 @@ HTTP responses. @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) @@ -201,7 +201,7 @@ HTTP responses. As with @scheme[response/basic], except with @scheme[body] as the response body. } - + @defstruct[(response/incremental response/basic) ([code number?] [message string?] @@ -223,7 +223,7 @@ HTTP responses. @item{A value matching @scheme[xexpr?].} ] } - + @defthing[TEXT/HTML-MIME-TYPE bytes?]{Equivalent to @scheme[#"text/html; charset=utf-8"].} @warning{If you include a Content-Length header in a response that is inaccurate, there WILL be an error in @@ -254,24 +254,24 @@ servlet developer. continuation URL is invoked, the captured continuation is invoked and the request is returned from this call to @scheme[send/suspend]. } - + @defproc[(continuation-url? [u url?]) (or/c false/c (list/c number? number? number?))]{ Checks if @scheme[u] is a URL that refers to a continuation, if so returns the instance id, continuation id, and nonce. } - -@; XXX Move + +@; XXX Move @defproc[(adjust-timeout! [t number?]) void?]{ Calls the servlet's manager's @scheme[adjust-timeout!] function. } - + @defproc[(clear-continuation-table!) void?]{ Calls the servlet's manager's @scheme[clear-continuation-table!] function. } - + @defproc[(send/forward [make-response response-generator?] [exp expiration-handler? (current-servlet-continuation-expiration-handler)]) request?]{ @@ -282,37 +282,37 @@ servlet developer. void?]{ Calls @scheme[clear-continuation-table!], then @scheme[send/back]. } - + @defproc[(send/suspend/dispatch [make-response (embed/url? . -> . response?)]) any/c]{ Calls @scheme[make-response] with a function that, when called with a procedure from @scheme[request?] to @scheme[any/c] will generate a URL, that when invoked will call the function with the @scheme[request?] object and return the result to the caller of @scheme[send/suspend/dispatch]. -} - +} + @defproc[(redirect/get) request?]{ Calls @scheme[send/suspend] with @scheme[redirect-to]. } - + @defproc[(redirect/get/forget) request?]{ Calls @scheme[send/forward] with @scheme[redirect-to]. } -@; XXX Remove +@; XXX Remove @defproc[(embed-ids [ids (list/c number? number? number?)] [u url?]) string?]{ Creates a @scheme[continuation-url?]. } - -@; XXX Remove + +@; XXX Remove @defthing[current-url-transform parameter?]{ Holds a @scheme[url-transform?] function that is called by @scheme[send/suspend] to transform the URLs it generates. -} +} @; ------------------------------------------------------------ @section[#:tag "helpers.ss"]{Helpers} @@ -328,12 +328,12 @@ servlet developer. Generates an HTTP response that redirects the browser to @scheme[uri], while including the @scheme[headers] in the response. } - + @defproc[(redirection-status? [v any/c]) boolean?]{ Determines if @scheme[v] is one of the following values. } - + @defthing[permanently redirection-status?]{A @scheme[redirection-status?] for permanent redirections.} @defthing[temporarily redirection-status?]{A @scheme[redirection-status?] for temporary redirections.} @@ -344,7 +344,7 @@ servlet developer. [thunk (-> any)])]{ Calls @scheme[thunk] with an exception handler that generates an HTML error page and calls @scheme[send/finish-or-back]. -} +} @; XXX Depreciate @; ------------------------------------------------------------ @@ -361,8 +361,8 @@ They may eventually provided by another module. Returns a URL string without the continuation information in the URL that went into @scheme[su] } - -@; XXX Support Digest + +@; XXX Support Digest @; ------------------------------------------------------------ @section[#:tag "basic-auth.ss"]{Basic Authentication} @@ -373,8 +373,8 @@ implementation of HTTP Basic Authentication. (or/c false/c (cons/c bytes? bytes?))]{ Returns a pair of the username and password from the authentication header in @scheme[heads] if they are present, or @scheme[#f] -} - +} + @; ------------------------------------------------------------ @section[#:tag "web-cells.ss"]{Web Cells} @@ -396,23 +396,23 @@ generated. For more information on their semantics, consult the paper @href-link boolean?]{ Determines if @scheme[v] is a web-cell. } - + @defproc[(make-web-cell [v any/c]) web-cell?]{ Creates a web-cell with a default value of @scheme[v]. } - + @defproc[(web-cell-ref [wc web-cell?]) any/c]{ Looks up the value of @scheme[wc] found in the nearest frame. } - + @defproc[(web-cell-shadow [wc web-cell?] [v any/c]) void]{ Binds @scheme[wc] to @scheme[v] in the current frame, shadowing any other bindings to @scheme[wc] in the current frame. -} +} -@include-section["servlet-env.scrbl"] \ No newline at end of file +@include-section["servlet-env.scrbl"] diff --git a/collects/web-server/docs/reference/web-server-unit.scrbl b/collects/web-server/docs/reference/web-server-unit.scrbl index 87b1c41dd2..7a0af29a35 100644 --- a/collects/web-server/docs/reference/web-server-unit.scrbl +++ b/collects/web-server/docs/reference/web-server-unit.scrbl @@ -8,17 +8,17 @@ The @web-server offers a unit-based approach to running the server. @file{web-server-sig.ss} provides the @defthing[web-server^ signature?] signature with two elements: - + @defproc[(serve) (-> void)]{ Runs the server and returns a procedure that shuts down the server. } - + @defproc[(serve-ports [ip input-port?] [op output-port?]) void]{ Serves a single connection represented by the ports @scheme[ip] and @scheme[op]. - } + } @file{web-server-unit.ss} provides the @defthing[web-server\@ unit?] unit. It imports a @scheme[web-config^] unit and a @scheme[tcp^] unit. It uses the