diff --git a/collects/scribblings/guide/case.scrbl b/collects/scribblings/guide/case.scrbl index f38d4dd149..b0e26f8198 100644 --- a/collects/scribblings/guide/case.scrbl +++ b/collects/scribblings/guide/case.scrbl @@ -4,7 +4,7 @@ "guide-utils.ss" (for-label scheme/match)) -@title{Simple Dispatch: @scheme[case]} +@title[#:tag "case"]{Simple Dispatch: @scheme[case]} The @scheme[case] form dispatches to a clause by matching the result of an expression to the values for the clause: diff --git a/collects/scribblings/guide/forms.scrbl b/collects/scribblings/guide/forms.scrbl index 6d82094f9f..50a981099d 100644 --- a/collects/scribblings/guide/forms.scrbl +++ b/collects/scribblings/guide/forms.scrbl @@ -90,3 +90,4 @@ form, a @scheme[_thing] is either an identifier or a keyword. @include-section["quote.scrbl"] @include-section["qq.scrbl"] @include-section["case.scrbl"] +@include-section["parameterize.scrbl"] diff --git a/collects/scribblings/guide/parameterize.scrbl b/collects/scribblings/guide/parameterize.scrbl new file mode 100644 index 0000000000..8099f64beb --- /dev/null +++ b/collects/scribblings/guide/parameterize.scrbl @@ -0,0 +1,67 @@ +#lang scribble/doc +@(require scribble/manual + scribble/eval + "guide-utils.ss") + +@title[#:tag "parameterize"]{Dynamic Binding: @scheme[parameterize]} + +The @scheme[parameterize] form supports a kind of dynamic binding that +is useful for adjusting defaults or passing extra arguments through +layers of function calls. The settings that are adjusted by a +@scheme[parameterize] form are called @deftech{parameters}. + +@margin-note{The term ``parameter'' is sometimes used to refer to the + arguments of a function, but ``parameter'' in PLT Scheme + has the more specific meaning described here.} + +@specform[(parameterize ([parameter-expr value-expr] ...) + body ...+)] + +The result of a @scheme[parameterize] form is the result of the last +@scheme[_body] expression. While the @scheme[_body] expressions are +evaluated, the parameter produced by each @scheme[_parameter-expr] is +set to the result of the corresponding @scheme[_value-expr]. + +Many parameters are built in. For example, the +@scheme[error-print-width] parameter controls how many characters of a +value are printed in an error message (in case the printed form of the +value is very large): + +@interaction[ +(parameterize ([error-print-width 10]) + (car (expt 10 1024))) +(parameterize ([error-print-width 5]) + (car (expt 10 1024))) +] + +The @scheme[error-print-width] parameter acts like a kind of default +argument to the function that formats error messages. This +parameter-based argument can be configured far from the actual call to +the error-formatting function, which in this case is called deep +within the implementation of @scheme[car]. + +The @scheme[parameterize] form adjusts the value of a parameter only +while evaluating its body expressions. After the body produces a +value, the parameter reverts to its previous value. If control escapes +from the body due to an exception, as in the above example, then the +parameter value is restored in that case, too. Finally, parameter +values are thread-specific, so that multiple threads do not interfere +with each others' settings. + +Use @scheme[make-parameter] to create a new parameter that works with +@scheme[parameterize]. The argument to @scheme[make-parameter] is the +value of the parameter when it is not otherwise set by +@scheme[parameterize]. To access the current value of the parameter, +call it like a function. + +@interaction[ +(define favorite-flavor (make-parameter 'chocolate)) +(favorite-flavor) +(define (scoop) + `(scoop of ,(favorite-flavor))) +(define (ice-cream n) + (list (scoop) (scoop) (scoop))) +(parameterize ([favorite-flavor 'strawberry]) + (ice-cream 3)) +(ice-cream 3) +] diff --git a/collects/scribblings/more/more.scrbl b/collects/scribblings/more/more.scrbl index b1766264a1..f34735388b 100644 --- a/collects/scribblings/more/more.scrbl +++ b/collects/scribblings/more/more.scrbl @@ -4,6 +4,7 @@ scribble/eval "../quick/keep.ss" (for-label scheme + scheme/enter readline net/url xml @@ -422,7 +423,7 @@ To parse the incoming URL and to more easily format HTML output, we'll require two extra libraries: @schemeblock[ -(require net/url xml) +(require xml net/url) ] The @schememodname[xml] library gives us @scheme[xexpr->string], which @@ -582,15 +583,12 @@ connection. Inside @scheme[accept-and-handle], after the definition of @whole-prog["7"] -We're assuming that 50MB should be plenty for any servlet. Due to the -way that memory accounting is defined, @scheme[cust] might also be -charged for the core server implementation and all of the libraries -loaded on start-up, so the limit cannot be too small. Also, -garbage-collector overhead means that the actual memory use of the -system can be some small multiple of 50 MB. An important guarantee, -however, is that different connections will not be charged for each -other's memory use, so one misbehaving connection will not interfere -with a different one. +We're assuming that 50MB should be plenty for any +servlet. Garbage-collector overhead means that the actual memory use +of the system can be some small multiple of 50 MB. An important +guarantee, however, is that different connections will not be charged +for each other's memory use, so one misbehaving connection will not +interfere with a different one. So, with the new line above, and assuming that you have a couple of hundred megabytes available for the @exec{mzscheme} process to use, diff --git a/collects/scribblings/reference/class.scrbl b/collects/scribblings/reference/class.scrbl index e77876a0b7..adbb77410c 100644 --- a/collects/scribblings/reference/class.scrbl +++ b/collects/scribblings/reference/class.scrbl @@ -75,6 +75,8 @@ @title[#:tag "mzlib:class" #:style 'toc]{Classes and Objects} +@guideintro["classes"]{classes and objects} + @note-lib[scheme/class #:use-sources (scheme/private/class-internal)] A @deftech{class} specifies diff --git a/collects/scribblings/reference/match.scrbl b/collects/scribblings/reference/match.scrbl index 9ce8a15150..2c692cd4af 100644 --- a/collects/scribblings/reference/match.scrbl +++ b/collects/scribblings/reference/match.scrbl @@ -8,6 +8,8 @@ @title[#:tag "match"]{Pattern Matching} +@guideintro["match"]{pattern matching} + The @scheme[match] form and related forms support general pattern matching on Scheme values. See also @secref["regexp"] for information on regular-expression matching on strings, bytes, and streams. diff --git a/collects/scribblings/reference/parameters.scrbl b/collects/scribblings/reference/parameters.scrbl index 263de8ec40..8a04c40e6f 100644 --- a/collects/scribblings/reference/parameters.scrbl +++ b/collects/scribblings/reference/parameters.scrbl @@ -3,6 +3,8 @@ @title[#:tag "parameters"]{Parameters} +@guideintro["parameterize"]{parameters} + See @secref["parameter-model"] for basic information on the parameter model. Parameters correspond to @defterm{preserved thread fluids} in Scsh @cite["Gasbichler02"]. @@ -45,6 +47,8 @@ applied to the initial @scheme[v].} @defform[(parameterize ((parameter-expr value-expr) ...) body ...+)]{ +@guideintro["parameterize"]{@scheme[parameterize]} + The result of a @scheme[parameterize] expression is the result of the last @scheme[body]. The @scheme[parameter-expr]s determine the parameters to set, and the @scheme[value-expr]s determine the