From 737b6fac01cd07bda65436c376ab93fb0a105eb0 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 27 Apr 2010 08:20:16 -0600 Subject: [PATCH] rackety reference; any lingering reference to racket as scheme is a doc bug --- collects/racket/promise.rkt | 135 +++-- .../reference/async-channels.scrbl | 5 +- collects/scribblings/reference/breaks.scrbl | 88 +-- collects/scribblings/reference/bytes.scrbl | 2 +- collects/scribblings/reference/collects.scrbl | 98 +-- .../scribblings/reference/concurrency.scrbl | 2 +- .../scribblings/reference/cont-marks.scrbl | 126 ++-- .../scribblings/reference/contracts.scrbl | 534 ++++++++--------- .../scribblings/reference/encodings.scrbl | 62 +- collects/scribblings/reference/eval.scrbl | 262 ++++---- collects/scribblings/reference/evts.scrbl | 306 +++++----- collects/scribblings/reference/exit.scrbl | 12 +- collects/scribblings/reference/exns.scrbl | 336 +++++------ .../scribblings/reference/file-ports.scrbl | 130 ++-- .../scribblings/reference/filesystem.scrbl | 20 +- collects/scribblings/reference/futures.scrbl | 42 +- collects/scribblings/reference/help.scrbl | 4 +- collects/scribblings/reference/init.scrbl | 18 +- .../scribblings/reference/load-lang.scrbl | 46 +- .../scribblings/reference/match-grammar.ss | 1 + collects/scribblings/reference/match.scrbl | 243 ++++---- collects/scribblings/reference/memory.scrbl | 64 +- collects/scribblings/reference/mpairs.scrbl | 78 +-- collects/scribblings/reference/mz.ss | 2 +- .../scribblings/reference/networking.scrbl | 302 +++++----- collects/scribblings/reference/numbers.scrbl | 560 +++++++++--------- collects/scribblings/reference/package.scrbl | 76 +-- collects/scribblings/reference/promise.scrbl | 114 ++-- collects/scribblings/reference/sandbox.scrbl | 2 +- collects/scribblings/reference/startup.scrbl | 3 - collects/scribblings/reference/syntax.scrbl | 4 +- collects/scribblings/reference/threads.scrbl | 8 +- collects/scribblings/reference/unsafe.scrbl | 8 +- 33 files changed, 1860 insertions(+), 1833 deletions(-) diff --git a/collects/racket/promise.rkt b/collects/racket/promise.rkt index 02fce13e0e..0d91e9da98 100644 --- a/collects/racket/promise.rkt +++ b/collects/racket/promise.rkt @@ -90,20 +90,24 @@ (provide (rename-out [delay/thread* delay/thread])) (define (delay/thread thunk group) - (define (run) - (call-with-exception-handler - (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) - (lambda () (pset! p (call-with-values thunk list))))) - (define p - (make-promise/thread - (make-running-thread - (object-name thunk) - (if group - (parameterize ([current-thread-group (make-thread-group)]) (thread run)) - (thread run))))) - p) + (unless (or (not group) + (thread-group? group)) + (raise-type-error 'delay/thread "thread group" group)) + (let () + (define (run) + (call-with-exception-handler + (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) + (lambda () (pset! p (call-with-values thunk list))))) + (define p + (make-promise/thread + (make-running-thread + (object-name thunk) + (if group + (parameterize ([current-thread-group group]) (thread run)) + (thread run))))) + p)) (define-syntax delay/thread* - (let ([kwds (list (cons '#:group #'#t))]) + (let ([kwds (list (cons '#:group #'(make-thread-group)))]) (lambda (stx) (make-delayer stx #'delay/thread kwds)))) (define-struct (promise/idle promise/thread) () @@ -122,54 +126,63 @@ (provide (rename-out [delay/idle* delay/idle])) (define (delay/idle thunk wait-for work-while tick use*) - (define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*])) - (define work-time (* tick use)) - (define rest-time (- tick work-time)) - (define (work) - (call-with-exception-handler - (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) - (lambda () (pset! p (call-with-values thunk list))))) - (define (run) - ;; this thread is dedicated to controlling the worker thread, so it's - ;; possible to dedicate messages to signaling a `force'. - (define force-evt (thread-receive-evt)) - (sync wait-for force-evt) - (pset! p (make-running-thread (object-name thunk) controller-thread)) - (let ([worker (parameterize ([current-thread-group (make-thread-group)]) - (thread work))]) - (cond - [(and (use . >= . 1) (equal? work-while always-evt)) - ;; as if it was pre-forced - (thread-wait worker)] - [(use . <= . 0) - ;; work only when explicitly forced - (thread-suspend worker) - (sync force-evt) - (thread-wait worker)] - [else - (thread-suspend worker) - (let loop () - ;; rest, then wait for idle time, then resume working - (if (eq? (begin0 (or (sync/timeout rest-time force-evt) - (sync work-while force-evt)) - (thread-resume worker)) - force-evt) - ;; forced during one of these => let it run to completion - (thread-wait worker) - ;; not forced - (unless (sync/timeout work-time worker) - (thread-suspend worker) - (loop))))]))) - ;; I don't think that a thread-group here is needed, but it doesn't hurt - (define controller-thread - (parameterize ([current-thread-group (make-thread-group)]) - (thread run))) - ;; the thunk is not really used in the above, make it a function that returns - ;; the controller thread so it can be forced (used in the `prop:force') - (define p (make-promise/idle - (procedure-rename (lambda () controller-thread) - (or (object-name thunk) 'idle-thread)))) - p) + (unless (evt? wait-for) + (raise-type-error 'delay/idle "evt" wait-for)) + (unless (evt? work-while) + (raise-type-error 'delay/idle "evt" work-while)) + (unless (and (real? tick) (not (negative? tick))) + (raise-type-error 'delay/idle "nonnegative real" tick)) + (unless (real? use*) + (raise-type-error 'delay/idle "real" use*)) + (let () + (define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*])) + (define work-time (* tick use)) + (define rest-time (- tick work-time)) + (define (work) + (call-with-exception-handler + (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) + (lambda () (pset! p (call-with-values thunk list))))) + (define (run) + ;; this thread is dedicated to controlling the worker thread, so it's + ;; possible to dedicate messages to signaling a `force'. + (define force-evt (thread-receive-evt)) + (sync wait-for force-evt) + (pset! p (make-running-thread (object-name thunk) controller-thread)) + (let ([worker (parameterize ([current-thread-group (make-thread-group)]) + (thread work))]) + (cond + [(and (use . >= . 1) (equal? work-while always-evt)) + ;; as if it was pre-forced + (thread-wait worker)] + [(use . <= . 0) + ;; work only when explicitly forced + (thread-suspend worker) + (sync force-evt) + (thread-wait worker)] + [else + (thread-suspend worker) + (let loop () + ;; rest, then wait for idle time, then resume working + (if (eq? (begin0 (or (sync/timeout rest-time force-evt) + (sync work-while force-evt)) + (thread-resume worker)) + force-evt) + ;; forced during one of these => let it run to completion + (thread-wait worker) + ;; not forced + (unless (sync/timeout work-time worker) + (thread-suspend worker) + (loop))))]))) + ;; I don't think that a thread-group here is needed, but it doesn't hurt + (define controller-thread + (parameterize ([current-thread-group (make-thread-group)]) + (thread run))) + ;; the thunk is not really used in the above, make it a function that returns + ;; the controller thread so it can be forced (used in the `prop:force') + (define p (make-promise/idle + (procedure-rename (lambda () controller-thread) + (or (object-name thunk) 'idle-thread)))) + p)) (define-syntax delay/idle* (let ([kwds (list (cons '#:wait-for #'(system-idle-evt)) (cons '#:work-while #'(system-idle-evt)) diff --git a/collects/scribblings/reference/async-channels.scrbl b/collects/scribblings/reference/async-channels.scrbl index 22de9ad336..21f9d054d4 100644 --- a/collects/scribblings/reference/async-channels.scrbl +++ b/collects/scribblings/reference/async-channels.scrbl @@ -90,9 +90,10 @@ the event itself. See also @scheme[sync].} (async-channel-put to-server 'add) (async-channel-put to-server 4) (printf "Result is ~a\n" (async-channel-get from-server)) -(printf "Ask server to do a long computation that might take a while\n") +(printf "Ask server to do a long computation\n") (async-channel-put to-server 'long) (printf "I can do other stuff\n") -(printf "Ok, computation from server is ~a\n" (async-channel-get from-server)) +(printf "Ok, computation from server is ~a\n" + (async-channel-get from-server)) (async-channel-put to-server 'quit) ] diff --git a/collects/scribblings/reference/breaks.scrbl b/collects/scribblings/reference/breaks.scrbl index e89776049b..d31067fb4c 100644 --- a/collects/scribblings/reference/breaks.scrbl +++ b/collects/scribblings/reference/breaks.scrbl @@ -7,47 +7,47 @@ A @deftech{break} is an asynchronous exception, usually triggered through an external source controlled by the user, or through the -@scheme[break-thread] procedure. A break exception can only occur in a +@racket[break-thread] procedure. A break exception can only occur in a thread while breaks are enabled. When a break is detected and enabled, the @exnraise[exn:break] in the thread sometime afterward; if breaking -is disabled when @scheme[break-thread] is called, the break is +is disabled when @racket[break-thread] is called, the break is suspended until breaking is again enabled for the thread. While a thread has a suspended break, additional breaks are ignored. -Breaks are enabled through the @scheme[break-enabled] parameter-like -procedure, and through the @scheme[parameterize-break] form, which is -analogous to @scheme[parameterize]. The @scheme[break-enabled] +Breaks are enabled through the @racket[break-enabled] parameter-like +procedure, and through the @racket[parameterize-break] form, which is +analogous to @racket[parameterize]. The @racket[break-enabled] procedure does not represent a parameter to be used with -@scheme[parameterize], because changing the break-enabled state of a +@racket[parameterize], because changing the break-enabled state of a thread requires an explicit check for breaks, and this check is -incompatible with the tail evaluation of a @scheme[parameterize] +incompatible with the tail evaluation of a @racket[parameterize] expression's body. -Certain procedures, such as @scheme[semaphore-wait/enable-break], +Certain procedures, such as @racket[semaphore-wait/enable-break], enable breaks temporarily while performing a blocking action. If breaks are enabled for a thread, and if a break is triggered for the -thread but not yet delivered as an @scheme[exn:break] exception, then +thread but not yet delivered as an @racket[exn:break] exception, then the break is guaranteed to be delivered before breaks can be disabled -in the thread. The timing of @scheme[exn:break] exceptions is not +in the thread. The timing of @racket[exn:break] exceptions is not guaranteed in any other way. -Before calling a @scheme[with-handlers] predicate or handler, an +Before calling a @racket[with-handlers] predicate or handler, an exception handler, an error display handler, an error escape handler, -an error value conversion handler, or a @scheme[pre-thunk] or -@scheme[post-thunk] for a @scheme[dynamic-wind], the call is -@scheme[parameterize-break]ed to disable breaks. Furthermore, breaks +an error value conversion handler, or a @racket[pre-thunk] or +@racket[post-thunk] for a @racket[dynamic-wind], the call is +@racket[parameterize-break]ed to disable breaks. Furthermore, breaks are disabled during the transitions among handlers related to -exceptions, during the transitions between @scheme[pre-thunk]s and -@scheme[post-thunk]s for @scheme[dynamic-wind], and during other +exceptions, during the transitions between @racket[pre-thunk]s and +@racket[post-thunk]s for @racket[dynamic-wind], and during other transitions for a continuation jump. For example, if breaks are disabled when a continuation is invoked, and if breaks are also disabled in the target continuation, then breaks will remain disabled until from the time of the invocation until the target continuation -executes unless a relevant @scheme[dynamic-wind] @scheme[pre-thunk] or -@scheme[post-thunk] explicitly enables breaks. +executes unless a relevant @racket[dynamic-wind] @racket[pre-thunk] or +@racket[post-thunk] explicitly enables breaks. If a break is triggered for a thread that is blocked on a nested -thread (see @scheme[call-in-nested-thread]), and if breaks are enabled +thread (see @racket[call-in-nested-thread]), and if breaks are enabled in the blocked thread, the break is implicitly handled by transferring it to the nested thread. @@ -55,7 +55,7 @@ When breaks are enabled, they can occur at any point within execution, which makes certain implementation tasks subtle. For example, assuming breaks are enabled when the following code is executed, -@schemeblock[ +@racketblock[ (with-handlers ([exn:break? (lambda (x) (void))]) (semaphore-wait s)) ] @@ -64,18 +64,18 @@ then it is @italic{not} the case that a @|void-const| result means the semaphore was decremented or a break was received, exclusively. It is possible that @italic{both} occur: the break may occur after the semaphore is successfully decremented but before a @|void-const| -result is returned by @scheme[semaphore-wait]. A break exception will +result is returned by @racket[semaphore-wait]. A break exception will never damage a semaphore, or any other built-in construct, but many -built-in procedures (including @scheme[semaphore-wait]) contain +built-in procedures (including @racket[semaphore-wait]) contain internal sub-expressions that can be interrupted by a break. -In general, it is impossible using only @scheme[semaphore-wait] to +In general, it is impossible using only @racket[semaphore-wait] to implement the guarantee that either the semaphore is decremented or an -exception is raised, but not both. Scheme therefore supplies -@scheme[semaphore-wait/enable-break] (see @secref["semaphore"]), +exception is raised, but not both. Racket therefore supplies +@racket[semaphore-wait/enable-break] (see @secref["semaphore"]), which does permit the implementation of such an exclusive guarantee: -@schemeblock[ +@racketblock[ (parameterize-break #f (with-handlers ([exn:break? (lambda (x) (void))]) (semaphore-wait/enable-break s))) @@ -84,13 +84,13 @@ which does permit the implementation of such an exclusive guarantee: In the above expression, a break can occur at any point until breaks are disabled, in which case a break exception is propagated to the enclosing exception handler. Otherwise, the break can only occur -within @scheme[semaphore-wait/enable-break], which guarantees that if +within @racket[semaphore-wait/enable-break], which guarantees that if a break exception is raised, the semaphore will not have been decremented. To allow similar implementation patterns over blocking port -operations, MzScheme provides @scheme[read-bytes-avail!/enable-break], -@scheme[write-bytes-avail/enable-break], and other procedures. +operations, Racket provides @racket[read-bytes-avail!/enable-break], +@racket[write-bytes-avail/enable-break], and other procedures. @;------------------------------------------------------------------------ @@ -99,26 +99,26 @@ operations, MzScheme provides @scheme[read-bytes-avail!/enable-break], [(break-enabled [on? any/c]) void?])]{ Gets or sets the break enabled state of the current thread. If -@scheme[on?] is not supplied, the result is @scheme[#t] if breaks are -currently enabled, @scheme[#f] otherwise. If @scheme[on?] is supplied -as @scheme[#f], breaks are disabled, and if @scheme[on?] is a true +@racket[on?] is not supplied, the result is @racket[#t] if breaks are +currently enabled, @racket[#f] otherwise. If @racket[on?] is supplied +as @racket[#f], breaks are disabled, and if @racket[on?] is a true value, breaks are enabled.} @defform[(parameterize-break boolean-expr body ...+)]{Evaluates -@scheme[boolean-expr] to determine whether breaks are initially -enabled in while evaluating the @scheme[body]s in sequence. The result -of the @scheme[parameter-break] expression is the result of the last -@scheme[expr]. +@racket[boolean-expr] to determine whether breaks are initially +enabled in while evaluating the @racket[body]s in sequence. The result +of the @racket[parameter-break] expression is the result of the last +@racket[expr]. -Like @scheme[parameterize] (see @secref["parameters"]), a fresh +Like @racket[parameterize] (see @secref["parameters"]), a fresh @tech{thread cell} (see @secref["threadcells"]) is allocated to hold the break-enabled state of the continuation, and calls to -@scheme[break-enabled] within the continuation access or modify the +@racket[break-enabled] within the continuation access or modify the new cell. Unlike parameters, the break setting is not inherited by new threads.} @defproc[(current-break-parameterization) break-parameterization?]{ -Analogous to @scheme[(current-parameterization)] (see +Analogous to @racket[(current-parameterization)] (see @secref["parameters"]); it returns a break-parameterization (effectively a thread cell) that holds the current continuation's break-enable state.} @@ -127,8 +127,8 @@ break-enable state.} [break-param break-parameterization?] [thunk (-> any)]) any]{ -Analogous to @scheme[(call-with-parameterization parameterization -thunk)] (see @secref["parameters"]), calls @scheme[thunk] in a -continuation whose break-enabled state is in @scheme[break-param]. The -@scheme[thunk] is @italic{not} called in tail position with respect to -the @scheme[call-with-break-parameterization] call.} +Analogous to @racket[(call-with-parameterization parameterization +thunk)] (see @secref["parameters"]), calls @racket[thunk] in a +continuation whose break-enabled state is in @racket[break-param]. The +@racket[thunk] is @italic{not} called in tail position with respect to +the @racket[call-with-break-parameterization] call.} diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index 5288738db5..85d01a3dd1 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -459,7 +459,7 @@ guaranteed combinations not involving @scheme[""] under Unix, or if it is any of the guaranteed combinations (including @scheme[""]) under Windows and Mac OS X. -@margin-note{In PLT's software distributions for Windows, a suitable +@margin-note{In the Racket software distributions for Windows, a suitable @filepath{iconv.dll} is included with @filepath{libmzsch@italic{VERS}.dll}.} The set of available encodings and combinations varies by platform, diff --git a/collects/scribblings/reference/collects.scrbl b/collects/scribblings/reference/collects.scrbl index 4b6c9b0880..8939252685 100644 --- a/collects/scribblings/reference/collects.scrbl +++ b/collects/scribblings/reference/collects.scrbl @@ -3,67 +3,67 @@ @title[#:tag "collects"]{Libraries and Collections} -A @deftech{library} is @scheme[module] declaration for use by multiple -programs. Scheme further groups libraries into @deftech{collections} -that can be easily distributed and easily added to a local MzScheme +A @deftech{library} is @racket[module] declaration for use by multiple +programs. Racket further groups libraries into @deftech{collections} +that can be easily distributed and easily added to a local Racket installation. Some collections are distributed via @|PLaneT|. Such collections are -referenced through a @scheme[planet] module path (see -@scheme[require]) and are downloaded by Scheme on demand. +referenced through a @racket[planet] module path (see +@racket[require]) and are downloaded by Racket on demand. -Other collections are distributed with PLT Scheme, in which case each +Other collections are distributed with Racket, in which case each collection is a directory that is located in a @filepath{collects} -directory relative to the @exec{mzscheme}. A collection can also be +directory relative to the Racket executable. A collection can also be installed in a user-specific directory. More generally, the search path for installed collections can be configured through the -@scheme[current-library-collection-paths] parameter. In all of these -cases, the collections are referenced through @scheme[lib] paths (see -@scheme[require]). +@racket[current-library-collection-paths] parameter. In all of these +cases, the collections are referenced through @racket[lib] paths (see +@racket[require]). -For example, the following module uses the @filepath{getinfo.ss} +For example, the following module uses the @filepath{getinfo.rkt} library module from the @filepath{setup} collection, and the -@filepath{cards.ss} library module from the @filepath{games} +@filepath{cards.rkt} library module from the @filepath{games} collection's @filepath{cards} subcollection: -@schememod[ -scheme -(require (lib "setup/getinfo.ss") - (lib "games/cards/cards.ss")) +@racketmod[ +racket +(require (lib "setup/getinfo.rkt") + (lib "games/cards/cards.rkt")) .... ] This example is more compactly and more commonly written as -@schememod[ -scheme +@racketmod[ +racket (require setup/getinfo games/cards/cards) .... ] -When an identifier @scheme[_id] is used in a @scheme[require] form, it -is converted to @scheme[(lib _rel-string)] where @scheme[_rel-string] -is the string form of @scheme[_id]. +When an identifier @racket[_id] is used in a @racket[require] form, it +is converted to @racket[(lib _rel-string)] where @racket[_rel-string] +is the string form of @racket[_id]. -A @scheme[_rel-string] in @scheme[(lib _rel-string)] consists of one +A @racket[_rel-string] in @racket[(lib _rel-string)] consists of one or more path elements that name collections, and then a final path element that names a library file; the path elements are separated by -@litchar{/}. If @scheme[_rel-string] contains no @litchar{/}s, then -then @litchar{/main.ss} is implicitly appended to the path. If -@scheme[_rel-string] contains @litchar{/} but does not end with a file -suffix, then @litchar{.ss} is implicitly appended to the path. +@litchar{/}. If @racket[_rel-string] contains no @litchar{/}s, then +then @litchar{/main.rkt} is implicitly appended to the path. If +@racket[_rel-string] contains @litchar{/} but does not end with a file +suffix, then @litchar{.rkt} is implicitly appended to the path. -The translation of a @scheme[planet] or @scheme[lib] path to a -@scheme[module] declaration is determined by the @tech{module name -resolver}, as specified by the @scheme[current-module-name-resolver] +The translation of a @racket[planet] or @racket[lib] path to a +@racket[module] declaration is determined by the @tech{module name +resolver}, as specified by the @racket[current-module-name-resolver] parameter. For the default @tech{module name resolver}, The search path for collections is determined by the -@scheme[current-library-collection-paths] parameter. The list of paths -in @scheme[current-library-collection-paths] is searched from first to -last to locate the first collection in a @scheme[_rel-string]. To find +@racket[current-library-collection-paths] parameter. The list of paths +in @racket[current-library-collection-paths] is searched from first to +last to locate the first collection in a @racket[_rel-string]. To find a sub-collection, the enclosing collection is first found; if the sub-collection is not present in the found enclosing collection, then the search continues by looking for another instance of the enclosing @@ -73,9 +73,9 @@ trees of other path elements. (The ``splicing'' of tress applies only to directories; a file within a collection is found only within the first instance of the collection.) -The value of the @scheme[current-library-collection-paths] parameter -is initialized in @exec{mzscheme} to the result of -@scheme[(find-library-collection-paths)]. +The value of the @racket[current-library-collection-paths] parameter +is initialized in the Racket executable to the result of +@racket[(find-library-collection-paths)]. @defproc[(find-library-collection-paths [pre-extras (listof path-string?) null] @@ -86,37 +86,37 @@ Produces a list of paths as follows: @itemize[ -@item{The path produced by @scheme[(build-path (find-system-path +@item{The path produced by @racket[(build-path (find-system-path 'addon-dir) (version) "collects")] is the first element of the default collection path list, unless the value of the - @scheme[use-user-specific-search-paths] parameter is @scheme[#f].} + @racket[use-user-specific-search-paths] parameter is @racket[#f].} - @item{Extra directories provided in @scheme[pre-extras] are included + @item{Extra directories provided in @racket[pre-extras] are included next to the default collection path list, converted to complete paths relative to the executable.} - @item{If the directory specified by @scheme[(find-system-path + @item{If the directory specified by @racket[(find-system-path 'collects-dir)] is absolute, or if it is relative (to the executable) and it exists, then it is added to the end of the default collection path list.} - @item{Extra directories provided in @scheme[post-extras] are included + @item{Extra directories provided in @racket[post-extras] are included last in the default collection path list, converted to complete paths relative to the executable.} @item{If the @indexed-envvar{PLTCOLLECTS} environment variable is defined, it is combined with the default list using - @scheme[path-list-string->path-list]. If it is not defined, the + @racket[path-list-string->path-list]. If it is not defined, the default collection path list (as constructed by the first three bullets above) is used directly. Note that under @|AllUnix|, paths are separated by @litchar{:}, and under Windows by @litchar{;}. Also, - @scheme[path-list-string->path-list] splices the default paths at an + @racket[path-list-string->path-list] splices the default paths at an empty path, for example, with many Unix shells you can set @envvar{PLTCOLLECTS} to @tt{":`pwd`"}, @tt{"`pwd`:"}, or @tt{"`pwd`"} to specify search the current directory after, before, - or instead of the default paths respectively.} + or instead of the default paths, respectively.} ]} @@ -124,22 +124,22 @@ Produces a list of paths as follows: @defproc[(collection-path [collection string?] ...+) path?]{ Returns the path to a directory containing the libraries of the -collection indicated by @scheme[collection]s, where the second -@scheme[collection] (if any) names a sub-collection, and so on. If the +collection indicated by @racket[collection]s, where the second +@racket[collection] (if any) names a sub-collection, and so on. If the collection is not found, the @exnraise[exn:fail:filesystem].} @defparam[current-library-collection-paths paths (listof (and/c path? complete-path?))]{ Parameter that determines a list of complete directory paths for -library collections used by @scheme[require]. See +library collections used by @racket[require]. See @secref["collects"] for more information.} @defboolparam[use-user-specific-search-paths on?]{ Parameter that determines whether user-specific paths, which are in -the directory produced by @scheme[(find-system-path 'addon-dir)], are +the directory produced by @racket[(find-system-path 'addon-dir)], are included in search paths for collections and other files. For example, -@scheme[find-library-collection-paths] omits the user-specific -collection directory when this parameter's value is @scheme[#f].} +@racket[find-library-collection-paths] omits the user-specific +collection directory when this parameter's value is @racket[#f].} diff --git a/collects/scribblings/reference/concurrency.scrbl b/collects/scribblings/reference/concurrency.scrbl index be2c6f312c..52db2de0b6 100644 --- a/collects/scribblings/reference/concurrency.scrbl +++ b/collects/scribblings/reference/concurrency.scrbl @@ -3,7 +3,7 @@ @title[#:tag "concurrency" #:style 'toc]{Concurrency} -PLT Scheme supports multiple threads of control within a program, +Racket supports multiple threads of control within a program, thread-local storage, some primitive synchronization mechanisms, and a framework for composing synchronization abstractions. In addition, the @scheme[racket/future] library provides some support for parallelism diff --git a/collects/scribblings/reference/cont-marks.scrbl b/collects/scribblings/reference/cont-marks.scrbl index 95f90e2555..aa2b2ba1c2 100644 --- a/collects/scribblings/reference/cont-marks.scrbl +++ b/collects/scribblings/reference/cont-marks.scrbl @@ -1,6 +1,6 @@ #lang scribble/doc @(require scribble/struct - scribble/scheme + scribble/racket "mz.ss") @(define (cont n) @@ -12,65 +12,65 @@ See @secref["mark-model"] and @secref["prompt-model"] for general information about continuation marks. -The list of continuation marks for a key @scheme[_k] and a continuation -@scheme[_C] that extends @cont[0] is defined as follows: +The list of continuation marks for a key @racket[_k] and a continuation +@racket[_C] that extends @cont[0] is defined as follows: @itemize[ - @item{If @scheme[_C] is an empty continuation, then the mark list is - @scheme[null].} + @item{If @racket[_C] is an empty continuation, then the mark list is + @racket[null].} - @item{If @scheme[_C]'s first frame contains a mark @scheme[_m] for @scheme[_k], - then the mark list for @scheme[_C] is @scheme[(cons _m _lst)], - where @scheme[_lst] is the mark list for @scheme[_k] in @cont[0].} + @item{If @racket[_C]'s first frame contains a mark @racket[_m] for @racket[_k], + then the mark list for @racket[_C] is @racket[(cons _m _lst)], + where @racket[_lst] is the mark list for @racket[_k] in @cont[0].} - @item{If @scheme[_C]'s first frame does not contain a mark keyed by - @scheme[_k], then the mark list for @scheme[_C] is the mark list for + @item{If @racket[_C]'s first frame does not contain a mark keyed by + @racket[_k], then the mark list for @racket[_C] is the mark list for @cont[0].} ] -The @scheme[with-continuation-mark] form installs a mark on the first +The @racket[with-continuation-mark] form installs a mark on the first frame of the current continuation (see @secref["wcm"]). Procedures -such as @scheme[current-continuation-marks] allow inspection of marks. +such as @racket[current-continuation-marks] allow inspection of marks. -Whenever Scheme creates an exception record for a primitive exception, -it fills the @scheme[continuation-marks] field with the value of -@scheme[(current-continuation-marks)], thus providing a snapshot of +Whenever Racket creates an exception record for a primitive exception, +it fills the @racket[continuation-marks] field with the value of +@racket[(current-continuation-marks)], thus providing a snapshot of the continuation marks at the time of the exception. When a continuation procedure returned by -@scheme[call-with-current-continuation] or -@scheme[call-with-composable-continuation] is invoked, it restores the +@racket[call-with-current-continuation] or +@racket[call-with-composable-continuation] is invoked, it restores the captured continuation, and also restores the marks in the continuation's frames to the marks that were present when -@scheme[call-with-current-continuation] or -@scheme[call-with-composable-continuation] was invoked. +@racket[call-with-current-continuation] or +@racket[call-with-composable-continuation] was invoked. @defproc[(continuation-marks [cont (or/c continuation? thread?)] [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) continuation-mark-set?]{ Returns an opaque value containing the set of continuation marks for -all keys in the continuation @scheme[cont] (or the current -continuation of @scheme[cont] if it is a thread) up to the prompt -tagged by @scheme[prompt-tag]. If @scheme[cont] is an escape +all keys in the continuation @racket[cont] (or the current +continuation of @racket[cont] if it is a thread) up to the prompt +tagged by @racket[prompt-tag]. If @racket[cont] is an escape continuation (see @secref["prompt-model"]), then the current -continuation must extend @scheme[cont], or the -@exnraise[exn:fail:contract]. If @scheme[cont] was not captured with -respect to @scheme[prompt-tag] and does not include a prompt for -@scheme[prompt-tag], the @exnraise[exn:fail:contract]. If -@scheme[cont] is a dead thread, the result is an empty set of +continuation must extend @racket[cont], or the +@exnraise[exn:fail:contract]. If @racket[cont] was not captured with +respect to @racket[prompt-tag] and does not include a prompt for +@racket[prompt-tag], the @exnraise[exn:fail:contract]. If +@racket[cont] is a dead thread, the result is an empty set of continuation marks.} @defproc[(current-continuation-marks [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) continuation-mark-set?]{ Returns an opaque value containing the set of continuation marks for -all keys in the current continuation up to @scheme[prompt-tag]. In +all keys in the current continuation up to @racket[prompt-tag]. In other words, it produces the same value as -@schemeblock[ +@racketblock[ (call-with-current-continuation (lambda (k) (continuation-marks k prompt-tag)) @@ -82,11 +82,11 @@ other words, it produces the same value as [key-v any/c] [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) list?]{ -Returns a newly-created list containing the marks for @scheme[key-v] -in @scheme[mark-set], which is a set of marks returned by -@scheme[current-continuation-marks]. The result list is truncated at +Returns a newly-created list containing the marks for @racket[key-v] +in @racket[mark-set], which is a set of marks returned by +@racket[current-continuation-marks]. The result list is truncated at the first point, if any, where continuation frames were originally -separated by a prompt tagged with @scheme[prompt-tag]..} +separated by a prompt tagged with @racket[prompt-tag]..} @defproc[(continuation-mark-set->list* [mark-set continuation-mark-set?] @@ -95,13 +95,13 @@ separated by a prompt tagged with @scheme[prompt-tag]..} [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) (listof vector?)]{ Returns a newly-created list containing vectors of marks in -@scheme[mark-set] for the keys in @scheme[key-list], up to -@scheme[prompt-tag]. The length of each vector in the result list is -the same as the length of @scheme[key-list], and a value in a +@racket[mark-set] for the keys in @racket[key-list], up to +@racket[prompt-tag]. The length of each vector in the result list is +the same as the length of @racket[key-list], and a value in a particular vector position is the value for the corresponding key in -@scheme[key-list]. Values for multiple keys appear in a single vector +@racket[key-list]. Values for multiple keys appear in a single vector only when the marks are for the same continuation frame in -@scheme[mark-set]. The @scheme[none-v] argument is used for vector +@racket[mark-set]. The @racket[none-v] argument is used for vector elements to indicate the lack of a value.} @defproc[(continuation-mark-set-first @@ -110,11 +110,11 @@ elements to indicate the lack of a value.} [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) any]{ Returns the first element of the list that would be returned by -@scheme[(continuation-mark-set->list (or mark-set +@racket[(continuation-mark-set->list (or mark-set (current-continuation-marks prompt-tag)) key-v prompt-tag)], or -@scheme[#f] if the result would be the empty list. Typically, this +@racket[#f] if the result would be the empty list. Typically, this result can be computed more quickly using -@scheme[continuation-mark-set-first].} +@racket[continuation-mark-set-first].} @defproc[(call-with-immediate-continuation-mark [key-v any/c] @@ -122,44 +122,44 @@ result can be computed more quickly using [default-v any/c #f]) any]{ -Calls @scheme[proc] with the value associated with @scheme[key-v] in +Calls @racket[proc] with the value associated with @racket[key-v] in the first frame of the current continuation (i.e., a value that would be replaced if the call to -@scheme[call-with-immediate-continuation-mark] were replaced with a -@scheme[with-continuation-mark] form using @scheme[key-v] as the key +@racket[call-with-immediate-continuation-mark] were replaced with a +@racket[with-continuation-mark] form using @racket[key-v] as the key expression). If no such value exists in the first frame, -@scheme[default-v] is passed to @scheme[proc]. The @scheme[proc] is +@racket[default-v] is passed to @racket[proc]. The @racket[proc] is called in tail position with respect to the -@scheme[call-with-immediate-continuation-mark] call. +@racket[call-with-immediate-continuation-mark] call. This function could be implemented with a combination of -@scheme[with-continuation-mark], @scheme[current-continuation-marks], -and @scheme[continuation-mark-set->list], but -@scheme[call-with-immediate-continuation-mark] is implemented more +@racket[with-continuation-mark], @racket[current-continuation-marks], +and @racket[continuation-mark-set->list], but +@racket[call-with-immediate-continuation-mark] is implemented more efficiently; it inspects only the first frame of the current continuation.} @defproc[(continuation-mark-set? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a mark set created by -@scheme[continuation-marks] or @scheme[current-continuation-marks], -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a mark set created by +@racket[continuation-marks] or @racket[current-continuation-marks], +@racket[#f] otherwise.} @defproc[(continuation-mark-set->context [mark-set continuation-mark-set?]) list?]{ Returns a list representing an approximate ``@index["stack -dump"]{@as-index{stack trace}}'' for @scheme[mark-set]'s -continuation. The list contains pairs, where the @scheme[car] of each -pair contains either @scheme[#f] or a symbol for a procedure name, and -the @scheme[cdr] of each pair contains either @scheme[#f] or a -@scheme[srcloc] value for the procedure's source location (see -@secref["linecol"]); the @scheme[car] and @scheme[cdr] are never both -@scheme[#f]. +dump"]{@as-index{stack trace}}'' for @racket[mark-set]'s +continuation. The list contains pairs, where the @racket[car] of each +pair contains either @racket[#f] or a symbol for a procedure name, and +the @racket[cdr] of each pair contains either @racket[#f] or a +@racket[srcloc] value for the procedure's source location (see +@secref["linecol"]); the @racket[car] and @racket[cdr] are never both +@racket[#f]. Conceptually, the stack-trace list is the result of -@scheme[continuation-mark-set->list] with @scheme[mark-set] and -Scheme's private key for procedure-call marks. The implementation may +@racket[continuation-mark-set->list] with @racket[mark-set] and +Racket's private key for procedure-call marks. The implementation may be different, however, and the results may merely approximate the correct answer. Thus, while the result may contain useful hints to humans about the context of an expression, it is not reliable enough @@ -167,8 +167,8 @@ for programmatic use. A stack trace is extracted from an exception and displayed by the default error display handler (see -@scheme[error-display-handler]) for exceptions other than -@scheme[exn:fail:user] (see @scheme[raise-user-error] in +@racket[error-display-handler]) for exceptions other than +@racket[exn:fail:user] (see @racket[raise-user-error] in @secref["errorproc"]).} @examples[ diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl index 542acdd3b6..53fb9785c1 100644 --- a/collects/scribblings/reference/contracts.scrbl +++ b/collects/scribblings/reference/contracts.scrbl @@ -14,7 +14,7 @@ The contract system guards one part of a program from another. Programmers specify the behavior of a module exports via -@scheme[provide/contract] and the contract system enforces those +@racket[provide/contract] and the contract system enforces those constraints. @note-lib[racket/contract #:use-sources (racket/contract/private/ds @@ -25,23 +25,23 @@ constraints. @deftech{Contracts} come in two forms: those constructed by the various operations listed in this section of the manual, and various -ordinary Scheme values that double as contracts, including +ordinary Racket values that double as contracts, including @itemize[ @item{@tech{symbols}, @tech{booleans}, @tech{characters}, and -@scheme[null], which are treated as contracts that recognize -themselves, using @scheme[eq?], } +@racket[null], which are treated as contracts that recognize +themselves, using @racket[eq?], } @item{@tech{strings} and @tech{byte strings}, which are treated as contracts -that recognize themselves using @scheme[equal?], } +that recognize themselves using @racket[equal?], } @item{@tech{numbers}, which are treated as contracts -that recognize themselves using @scheme[=],} +that recognize themselves using @racket[=],} @item{@tech{regular expressions}, which are treated as contracts that recognize @tech{byte strings} and @tech{strings} that match the regular expression, and } @item{predicates: any procedure of arity 1 is treated as a predicate. During contract checking, it is applied to the values that -appear and should return @scheme[#f] to indicate that the contract +appear and should return @racket[#f] to indicate that the contract failed, and anything else to indicate it passed.} ] @@ -57,17 +57,17 @@ a given value. @defproc[(flat-contract [predicate (any/c . -> . any/c)]) flat-contract?]{ -Constructs a @tech{flat contract} from @scheme[predicate]. A value +Constructs a @tech{flat contract} from @racket[predicate]. A value satisfies the contract if the predicate returns a true value.} @defproc[(flat-named-contract [type-name any/c] [predicate (or/c flat-contract? (any/c . -> . any))]) flat-contract?]{ -On predicates like @scheme[flat-contract], but the first argument must be the +On predicates like @racket[flat-contract], but the first argument must be the (quoted) name of a contract used for error reporting. For example, -@schemeblock[(flat-named-contract +@racketblock[(flat-named-contract 'odd-integer (lambda (x) (and (integer? x) (odd? x))))] turns the predicate into a contract with the name @tt{odd-integer}. @@ -81,7 +81,7 @@ the name. A flat contract that accepts any value. When using this contract as the result portion of a function contract, -consider using @scheme[any] instead; using @scheme[any] leads to +consider using @racket[any] instead; using @racket[any] leads to better memory performance, but it also allows multiple results.} @@ -97,11 +97,11 @@ Takes any number of contracts and returns a contract that accepts any value that any one of the contracts accepts, individually. -The @scheme[or/c] result tests any value by applying the contracts in +The @racket[or/c] result tests any value by applying the contracts in order, from left to right, with the exception that it always moves the non-@tech{flat contracts} (if any) to the end, checking them -last. Thus, a contract such as @scheme[(or/c (not/c real?) -positive?)] is guaranteed to only invoke the @scheme[positive?] +last. Thus, a contract such as @racket[(or/c (not/c real?) +positive?)] is guaranteed to only invoke the @racket[positive?] predicate on real numbers. If all of the arguments are procedures or @tech{flat contracts}, the @@ -110,21 +110,21 @@ higher-order contract, the result is a contract that just checks the flat contracts and, if they don't pass, applies the higher-order contract. -If there are multiple higher-order contracts, @scheme[or/c] uses -@scheme[contract-first-order-passes?] to distinguish between -them. More precisely, when an @scheme[or/c] is checked, it first +If there are multiple higher-order contracts, @racket[or/c] uses +@racket[contract-first-order-passes?] to distinguish between +them. More precisely, when an @racket[or/c] is checked, it first checks all of the @tech{flat contracts}. If none of them pass, it -calls @scheme[contract-first-order-passes?] with each of the -higher-order contracts. If only one returns true, @scheme[or/c] uses +calls @racket[contract-first-order-passes?] with each of the +higher-order contracts. If only one returns true, @racket[or/c] uses that contract. If none of them return true, it signals a contract violation. If more than one returns true, it also signals a contract violation. For example, this contract -@schemeblock[ +@racketblock[ (or/c (-> number? number?) (-> string? string? string?)) ] -does not accept a function like this one: @scheme[(lambda args ...)] +does not accept a function like this one: @racket[(lambda args ...)] since it cannot tell which of the two arrow contracts should be used with the function. } @@ -138,7 +138,7 @@ accepts any value that satisfies all of the contracts, simultaneously. If all of the arguments are procedures or @tech{flat contracts}, the result is a @tech{flat contract}. -The contract produced by @scheme[and/c] tests any value by applying +The contract produced by @racket[and/c] tests any value by applying the contracts in order, from left to right.} @@ -152,41 +152,41 @@ that checks the inverse of the argument.} @defproc[(=/c [z real?]) flat-contract?]{ Returns a flat contract that requires the input to be a number and -@scheme[=] to @scheme[z].} +@racket[=] to @racket[z].} @defproc[(/c [n real?]) flat-contract?]{ -Like @scheme[].} +Like @racket[].} @defproc[(<=/c [n real?]) flat-contract?]{ -Like @scheme[=/c [n real?]) flat-contract?]{ -Like @scheme[=].} +Like @racket[=].} @defproc[(between/c [n real?] [m real?]) flat-contract?]{ Returns a flat contract that requires the -input to be a between @scheme[n] and @scheme[m] or equal to +input to be a between @racket[n] and @racket[m] or equal to one of them.} @defproc[(real-in [n real?][m real?]) flat-contract?]{ Returns a flat contract that requires the input to be a real number -between @scheme[n] and @scheme[m], inclusive.} +between @racket[n] and @racket[m], inclusive.} @defproc[(integer-in [j exact-integer?][k exact-integer?]) flat-contract?]{ Returns a flat contract that requires the input to be an exact integer -between @scheme[j] and @scheme[k], inclusive.} +between @racket[j] and @racket[k], inclusive.} @defthing[natural-number/c flat-contract?]{ @@ -197,25 +197,25 @@ A flat contract that requires the input to be an exact non-negative integer.} @defproc[(string-len/c [len exact-nonnegative-integer?]) flat-contract?]{ Returns a flat contract that recognizes strings that have fewer than -@scheme[len] characters.} +@racket[len] characters.} @defthing[false/c flat-contract?]{ -This is just @scheme[#f]. It is here for backwards compatibility.} +This is just @racket[#f]. It is here for backwards compatibility.} @defthing[printable/c flat-contract?]{ A flat contract that recognizes values that can be written out and -read back in with @scheme[write] and @scheme[read].} +read back in with @racket[write] and @racket[read].} @defproc[(one-of/c [v any/c] ...+) flat-contract?]{ Accepts any number of atomic values and returns a flat contract that -recognizes those values, using @scheme[eqv?] as the comparison -predicate. For the purposes of @scheme[one-of/c], atomic values are +recognizes those values, using @racket[eqv?] as the comparison +predicate. For the purposes of @racket[one-of/c], atomic values are defined to be: characters, symbols, booleans, null keywords, numbers, void, and undefined.} @@ -229,108 +229,108 @@ recognizes those symbols.} @defproc[(vectorof [c (or/c flat-contract? (any/c . -> . any/c))]) flat-contract?]{ Accepts a @tech{flat contract} (or a predicate that is converted to a -flat contract via @scheme[flat-contract]) and returns a flat contract +flat contract via @racket[flat-contract]) and returns a flat contract that checks for vectors whose elements match the original contract.} @defproc[(vector-immutableof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ -Like @scheme[vectorof], but the contract needs not be a @tech{flat +Like @racket[vectorof], but the contract needs not be a @tech{flat contract}. Beware that when this contract is applied to a -value, the result is not @scheme[eq?] to the input.} +value, the result is not @racket[eq?] to the input.} @defproc[(vector/c [c (or/c flat-contract? (any/c . -> . any/c))] ...) flat-contract?]{ Accepts any number of flat contracts (or predicates that are converted -to flat contracts via @scheme[flat-contract]) and returns a +to flat contracts via @racket[flat-contract]) and returns a flat-contract that recognizes vectors. The number of elements in the vector must match the number of arguments supplied to -@scheme[vector/c], and each element of the vector must match the +@racket[vector/c], and each element of the vector must match the corresponding flat contract.} @defproc[(vector-immutable/c [c (or/c contract? (any/c . -> . any/c))] ...) contract?]{ -Like @scheme[vector/c], but the individual contracts need not be +Like @racket[vector/c], but the individual contracts need not be @tech{flat contracts}. Beware that when this contract is applied to a -value, the result is not @scheme[eq?] to the input.} +value, the result is not @racket[eq?] to the input.} @defproc[(box/c [c (or/c flat-contract? (any/c . -> . any/c))]) flat-contract?]{ Returns a flat-contract that recognizes boxes. The content of the box -must match @scheme[c].} +must match @racket[c].} @defproc[(box-immutable/c [c (or/c contract? (any/c . -> . any/c))]) contract?]{ -Like @scheme[box/c], but @scheme[c] need not be @tech{flat +Like @racket[box/c], but @racket[c] need not be @tech{flat contract}. Beware that when this contract is applied to a value, the -result is not @scheme[eq?] to the input.} +result is not @racket[eq?] to the input.} @defproc[(listof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ Returns a contract that recognizes a list whose every element matches -the contract @scheme[c]. Beware that when this contract is applied to -a value, the result is not necessarily @scheme[eq?] to the input.} +the contract @racket[c]. Beware that when this contract is applied to +a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(non-empty-listof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ Returns a contract that recognizes non-empty lists whose elements match -the contract @scheme[c]. Beware that when this contract is applied to -a value, the result is not necessarily @scheme[eq?] to the input.} +the contract @racket[c]. Beware that when this contract is applied to +a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(cons/c [car-c contract?][cdr-c contract?]) contract?]{ Produces a contract the recognizes pairs first and second elements -match @scheme[car-c] and @scheme[cdr-c], respectively. Beware that +match @racket[car-c] and @racket[cdr-c], respectively. Beware that when this contract is applied to a value, the result is not -necessarily @scheme[eq?] to the input.} +necessarily @racket[eq?] to the input.} @defproc[(list/c [c (or/c contract? (any/c . -> . any/c))] ...) contract?]{ Produces a contract for a list. The number of elements in the list -must match the number of arguments supplied to @scheme[list/c], and +must match the number of arguments supplied to @racket[list/c], and each element of the list must match the corresponding contract. Beware that when this contract is applied to a value, the result is not -necessarily @scheme[eq?] to the input.} +necessarily @racket[eq?] to the input.} @defproc[(syntax/c [c flat-contract?]) flat-contract?]{ Produces a flat contract that recognizes syntax objects whose -@scheme[syntax-e] content matches @scheme[c].} +@racket[syntax-e] content matches @racket[c].} @defform[(struct/c struct-id flat-contract-expr ...)]{ Produces a flat contract that recognizes instances of the structure -type named by @scheme[struct-id], and whose field values match the -@tech{flat contracts} produced by the @scheme[flat-contract-expr]s.} +type named by @racket[struct-id], and whose field values match the +@tech{flat contracts} produced by the @racket[flat-contract-expr]s.} @defproc[(parameter/c [c contract?]) contract?]{ Produces a contract on parameters whose values must match -@scheme[contract].} +@racket[contract].} @defproc[(hash/c [key contract?] [val contract?] [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care]) contract?]{ -Produces a contract that recognizes @scheme[hash] tables with keys and values -as specified by the @scheme[key] and @scheme[val] arguments. +Produces a contract that recognizes @racket[hash] tables with keys and values +as specified by the @racket[key] and @racket[val] arguments. -If the @scheme[immutable] argument is @scheme[#f] or -@scheme['dont-care], then the resulting contract is a flat contract, -and the @scheme[key] and @scheme[val] arguments must also be flat +If the @racket[immutable] argument is @racket[#f] or +@racket['dont-care], then the resulting contract is a flat contract, +and the @racket[key] and @racket[val] arguments must also be flat contracts. -If @scheme[immutable] is @scheme[#t], then the other arguments do not +If @racket[immutable] is @racket[#t], then the other arguments do not have to be flat contracts, the result is not a flat contract, and checking this contract involves making a copy of the hash-table. } @@ -339,12 +339,12 @@ checking this contract involves making a copy of the hash-table. @defform[(flat-rec-contract id flat-contract-expr ...)] Constructs a recursive @tech{flat contract}. A -@scheme[flat-contract-expr] can refer to @scheme[id] to refer +@racket[flat-contract-expr] can refer to @racket[id] to refer recursively to the generated contract. For example, the contract -@schemeblock[ +@racketblock[ (flat-rec-contract sexp (cons/c sexp sexp) number? @@ -352,8 +352,8 @@ For example, the contract ] is a flat contract that checks for (a limited form of) -S-expressions. It says that an @scheme[sexp] is either two -@scheme[sexp] combined with @scheme[cons], or a number, or a symbol. +S-expressions. It says that an @racket[sexp] is either two +@racket[sexp] combined with @racket[cons], or a number, or a symbol. Note that if the contract is applied to a circular value, contract checking will not terminate.} @@ -361,23 +361,23 @@ checking will not terminate.} @defform[(flat-murec-contract ([id flat-contract-expr ...] ...) body ...+)]{ -A generalization of @scheme[flat-rec-contract] for defining several -mutually recursive flat contracts simultaneously. Each @scheme[id] is -visible in the entire @scheme[flat-murec-contract] form, and the -result of the final @scheme[body] is the result of the entire form.} +A generalization of @racket[flat-rec-contract] for defining several +mutually recursive flat contracts simultaneously. Each @racket[id] is +visible in the entire @racket[flat-murec-contract] form, and the +result of the final @racket[body] is the result of the entire form.} @defidform[any]{ Represents a contract that is always satisfied. In particular, it can accept multiple values. It can only be used in a result position of contracts like -@scheme[->]. Using @scheme[any] elsewhere is a syntax error.} +@racket[->]. Using @racket[any] elsewhere is a syntax error.} @defform[(promise/c expr)]{ Constructs a contract on a promise. The contract does not force the promise, but when the promise is forced, the contract checks that the -result value meets the contract produced by @scheme[expr].} +result value meets the contract produced by @racket[expr].} @defproc[(new-∃/c [name symbol?]) contract?]{ Constructs a new existential contract. @@ -389,14 +389,14 @@ result value meets the contract produced by @scheme[expr].} for the wrappers). For example, this contract: - @schemeblock[(let ([a (new-∃/c 'a)]) + @racketblock[(let ([a (new-∃/c 'a)]) (-> (-> a a) any/c))] describes a function that accepts the identity function (or a non-terminating function) - and returns an arbitrary value. That is, the first use of the @scheme[a] appears in a + and returns an arbitrary value. That is, the first use of the @racket[a] appears in a positive position and thus inputs to that function are wrapped with an opaque struct. Then, when the function returns, it is checked to see if the result is wrapped, since - the second @scheme[a] appears in a negative position. + the second @racket[a] appears in a negative position. } @@ -408,19 +408,19 @@ A @deftech{function contract} wraps a procedure to delay checks for its arguments and results. There are three primary function contract combinators that have increasing amounts of expressiveness and increasing additional -overheads. The first @scheme[->] is the cheapest. It +overheads. The first @racket[->] is the cheapest. It generates wrapper functions that can call the original -function directly. Contracts built with @scheme[->*] require +function directly. Contracts built with @racket[->*] require packaging up arguments as lists in the wrapper function and -then using either @scheme[keyword-apply] or -@scheme[apply]. Finally, @scheme[->d] is the most expensive, +then using either @racket[keyword-apply] or +@racket[apply]. Finally, @racket[->d] is the most expensive, because it requires delaying the evaluation of the contract expressions for the domain and range until the function itself is called or returns. -The @scheme[case->] contract is a specialized contract, -designed to match @scheme[case-lambda] and -@scheme[unconstrained-domain->] allows range checking +The @racket[case->] contract is a specialized contract, +designed to match @racket[case-lambda] and +@racket[unconstrained-domain->] allows range checking without requiring that the domain have any particular shape (see below for an example use). @@ -432,21 +432,21 @@ without requiring that the domain have any particular shape Produces a contract for a function that accepts a fixed number of arguments and returns either a fixed number of results or completely unspecified results (the latter when -@scheme[any] is specified). +@racket[any] is specified). -Each @scheme[dom-expr] is a contract on an argument to a -function, and each @scheme[range-expr] is a contract on a +Each @racket[dom-expr] is a contract on an argument to a +function, and each @racket[range-expr] is a contract on a result of the function. -@margin-note{Using an @scheme[->] between two whitespace-delimited -@schemeparenfont{.}s is the same as putting the @scheme[->] right +@margin-note{Using an @racket[->] between two whitespace-delimited +@racketparenfont{.}s is the same as putting the @racket[->] right after the enclosing open parenthesis. See @guidesecref["lists-and-syntax"] or @secref["parse-pair"] for more information.} For example, -@schemeblock[(integer? boolean? . -> . integer?)] +@racketblock[(integer? boolean? . -> . integer?)] produces a contract on functions of two arguments. The first argument must be an integer, and the second argument must be a boolean. The @@ -457,18 +457,18 @@ accept corresponding (mandatory) keyword arguments, and the values for the keyword arguments must match the corresponding contracts. For example: -@schemeblock[(integer? #:x boolean? . -> . integer?)] +@racketblock[(integer? #:x boolean? . -> . integer?)] is a contract on a function that accepts a by-position argument that -is an integer and a @scheme[#:x] argument is that a boolean. +is an integer and a @racket[#:x] argument is that a boolean. -If @scheme[any] is used as the last sub-form for @scheme[->], no +If @racket[any] is used as the last sub-form for @racket[->], no contract checking is performed on the result of the function, and thus any number of values is legal (even different numbers on different invocations of the function). -If @scheme[(values range-expr ...)] is used as the last sub-form of -@scheme[->], the function must produce a result for each contract, and +If @racket[(values range-expr ...)] is used as the last sub-form of +@racket[->], the function must produce a result for each contract, and each value must match its respective contract.} @@ -479,22 +479,22 @@ each value must match its respective contract.} [rest (code:line) (code:line #:rest rest-expr)] [range range-expr (values range-expr ...) any])]{ -The @scheme[->*] contract combinator produces contracts for +The @racket[->*] contract combinator produces contracts for functions that accept optional arguments (either keyword or positional) and/or arbitrarily many arguments. The first -clause of a @scheme[->*] contract describes the mandatory +clause of a @racket[->*] contract describes the mandatory arguments, and is similar to the argument description of a -@scheme[->] contract. The second clause describes the +@racket[->] contract. The second clause describes the optional arguments. The last clause describes the range of -the function. It can either be @scheme[any] or a +the function. It can either be @racket[any] or a sequence of contracts, indicating that the function must -return multiple values. If present, the @scheme[rest-expr] +return multiple values. If present, the @racket[rest-expr] contract governs the arguments in the rest parameter. As an example, the contract -@schemeblock[(->* () (boolean? #:x integer?) #:rest (listof symbol?) symbol?)] +@racketblock[(->* () (boolean? #:x integer?) #:rest (listof symbol?) symbol?)] matches functions that optionally accept a boolean, an -integer keyword argument @scheme[#:x] and arbitrarily more +integer keyword argument @racket[#:x] and arbitrarily more symbols, and that return a symbol. } @@ -517,7 +517,7 @@ symbols, and that return a symbol. [post-cond (code:line) (code:line #:post-cond boolean-expr)] )]{ -The @scheme[->d] is similar in shape to @scheme[->*], with +The @racket[->d] is similar in shape to @racket[->*], with two extensions: names have been added to each argument and result, which allows the contracts to depend on the values of the arguments and results, and pre- and post-condition @@ -525,31 +525,31 @@ expressions have been added in order to express contracts that are not naturally tied to a particular argument or result. -The first two subforms of a @scheme[->d] contract cover the +The first two subforms of a @racket[->d] contract cover the mandatory and optional arguments. Following that is an optional rest-args contract, and an optional -pre-condition. The @scheme[dep-range] non-terminal covers +pre-condition. The @racket[dep-range] non-terminal covers the possible post-condition contracts. If it is -@scheme[any], then any result (or results) are +@racket[any], then any result (or results) are allowed. Otherwise, the result contract can be a name and a result contract, or a multiple values return and, in either of the last two cases, it may be optionally followed by a post-condition. -Each of the @scheme[id]s on an argument (including the rest +Each of the @racket[id]s on an argument (including the rest argument) is visible in all of the sub-expressions of -@scheme[->d]. Each of the @scheme[id]s on a result is -visible in the subexpressions of the @scheme[dep-range]. +@racket[->d]. Each of the @racket[id]s on a result is +visible in the subexpressions of the @racket[dep-range]. If the identifier position of the range contract is -@scheme[_] (an underscore), then the range contract +@racket[_] (an underscore), then the range contract expressions are evaluated when the function is called (and the underscore is not bound in the range). Otherwise the range expressions are evaluated when the function returns. If there are optional arguments that are not supplied, then the corresponding variables will be bound to a special value -called the @scheme[unsupplied-arg] value. +called the @racket[unsupplied-arg] value. } @defform*/subs[#:literals (any values ->) @@ -557,19 +557,19 @@ called the @scheme[unsupplied-arg] value. ([rest (code:line) (code:line #:rest rest-expr)] [range range-expr (values range-expr ...) any])]{ This contract form is designed to match -@scheme[case-lambda]. Each argument to @scheme[case->] is a +@racket[case-lambda]. Each argument to @racket[case->] is a contract that governs a clause in the -@scheme[case-lambda]. If the @scheme[#:rest] keyword is +@racket[case-lambda]. If the @racket[#:rest] keyword is present, the corresponding clause must accept an arbitrary -number of arguments. The @scheme[range] specification is -just like that for @scheme[->] and @scheme[->*]. +number of arguments. The @racket[range] specification is +just like that for @racket[->] and @racket[->*]. } @defform[(unconstrained-domain-> range-expr ...)]{ Constructs a contract that accepts a function, but makes no constraint -on the function's domain. The @scheme[range-expr]s determine the number +on the function's domain. The @racket[range-expr]s determine the number of results and the contract for each result. Generally, this contract must be combined with another contract to @@ -578,7 +578,7 @@ function itself. For example, the contract -@schemeblock[ +@racketblock[ (provide/contract [f (->d ([size natural-number/c] [proc (and/c (unconstrained-domain-> number?) @@ -588,16 +588,16 @@ For example, the contract number?)]) ] -says that the function @scheme[f] accepts a natural number -and a function. The domain of the function that @scheme[f] -accepts must include a case for @scheme[size] arguments, -meaning that @scheme[f] can safely supply @scheme[size] +says that the function @racket[f] accepts a natural number +and a function. The domain of the function that @racket[f] +accepts must include a case for @racket[size] arguments, +meaning that @racket[f] can safely supply @racket[size] arguments to its input. -For example, the following is a definition of @scheme[f] that cannot +For example, the following is a definition of @racket[f] that cannot be blamed using the above contract: -@schemeblock[ +@racketblock[ (define (f i g) (apply g (build-list i add1))) ]} @@ -611,9 +611,9 @@ be blamed using the above contract: (define-contract-struct id (field-id ...)) ]{ -Like @scheme[define-struct], but with two differences: it does not +Like @racket[define-struct], but with two differences: it does not define field mutators, and it does define two contract constructors: -@scheme[id]@schemeidfont{/c} and @scheme[id]@schemeidfont{/dc}. The +@racket[id]@racketidfont{/c} and @racket[id]@racketidfont{/dc}. The first is a procedure that accepts as many arguments as there are fields and returns a contract for struct values whose fields match the arguments. The second is a syntactic form that also produces contracts @@ -626,20 +626,20 @@ actually inspected. More precisely, a lazy data structure contract is not checked until a selector extracts a field of a struct. @specsubform/subs[ -(#,(elem (scheme id) (schemeidfont "/dc")) field-spec ...) +(#,(elem (racket id) (racketidfont "/dc")) field-spec ...) ([field-spec [field-id contract-expr] [field-id (field-id ...) contract-expr]]) ]{ -In each @scheme[field-spec] case, the first @scheme[field-id] +In each @racket[field-spec] case, the first @racket[field-id] specifies which field the contract applies to; the fields must be specified in the same order as the original -@scheme[define-contract-struct]. The first case is for when the +@racket[define-contract-struct]. The first case is for when the contract on the field does not depend on the value of any other field. The second case is for when the contract on the field does -depend on some other fields, and the parenthesized @scheme[field-id]s +depend on some other fields, and the parenthesized @racket[field-id]s indicate which fields it depends on; these dependencies can only be to earlier fields.} @@ -652,16 +652,16 @@ racket (define-contract-struct kons (hd tl)) -;; @scheme[sorted-list/gt : number -> contract] +;; @racket[sorted-list/gt : number -> contract] ;; produces a contract that accepts ;; sorted kons-lists whose elements -;; are all greater than @scheme[num]. +;; are all greater than @racket[num]. (define (sorted-list/gt num) (or/c null? (kons/dc [hd (>=/c num)] [tl (hd) (sorted-list/gt hd)]))) -;; @scheme[product : kons-list -> number] +;; @racket[product : kons-list -> number] ;; computes the product of the values ;; in the list. if the list contains ;; zero, it avoids traversing the rest @@ -679,14 +679,14 @@ racket (provide/contract [product (-> (sorted-list/gt -inf.0) number?)]) ]) -The module provides a single function, @scheme[product] whose contract +The module provides a single function, @racket[product] whose contract indicates that it accepts sorted lists of numbers and produces numbers. Using an ordinary flat contract for sorted lists, the product function cannot avoid traversing having its entire argument be traversed, since the contract checker will traverse it before the function is called. As written above, however, when the product function aborts the traversal of the list, the contract checking also -stops, since the @scheme[kons/dc] contract constructor generates a +stops, since the @racket[kons/dc] contract constructor generates a lazy contract.} @; ------------------------------------------------------------------------ @@ -706,12 +706,12 @@ lazy contract.} [exists-variables identifier (identifier ...)])]{ -Can only appear at the top-level of a @scheme[module]. As with -@scheme[provide], each @scheme[id] is provided from the module. In +Can only appear at the top-level of a @racket[module]. As with +@racket[provide], each @racket[id] is provided from the module. In addition, clients of the module must live up to the contract specified -by @scheme[contract-expr] for each export. +by @racket[contract-expr] for each export. -The @scheme[provide/contract] form treats modules as units of +The @racket[provide/contract] form treats modules as units of blame. The module that defines the provided variable is expected to meet the positive (co-variant) positions of the contract. Each module that imports the provided variable must obey the negative @@ -720,24 +720,24 @@ that imports the provided variable must obey the negative Only uses of the contracted variable outside the module are checked. Inside the module, no contract checking occurs. -The @scheme[rename] form of a @scheme[provide/contract] exports the +The @racket[rename] form of a @racket[provide/contract] exports the first variable (the internal name) with the name specified by the second variable (the external name). -The @scheme[struct] form of a @scheme[provide/contract] clause +The @racket[struct] form of a @racket[provide/contract] clause provides a structure definition, and each field has a contract that dictates the contents of the fields. The struct definition must come before the provide clause in the module's body. If the struct has a -parent, the second @scheme[struct] form (above) must be used, with the +parent, the second @racket[struct] form (above) must be used, with the first name referring to the struct itself and the second name -referring to the parent struct. Unlike @scheme[define-struct], +referring to the parent struct. Unlike @racket[define-struct], however, all of the fields (and their contracts) must be listed. The contract on the fields that the sub-struct shares with its parent are only used in the contract for the sub-struct's maker, and the selector or mutators for the super-struct are not provided. -The @scheme[#:∃] and @scheme[#:exists] clauses define new abstract -contracts. The variables are bound in the remainder of the @scheme[provide/contract] +The @racket[#:∃] and @racket[#:exists] clauses define new abstract +contracts. The variables are bound in the remainder of the @racket[provide/contract] expression to new contracts that hide the values they accept and ensure that the exported functions are treated parametrically. } @@ -755,61 +755,61 @@ ensure that the exported functions are treated parametrically. (code:line #:freevar id contract-expr)])]{ Generates a local contract boundary. -The first @scheme[with-contract] form cannot appear in expression position. -All names defined within the first @scheme[with-contract] form are -visible externally, but those names listed in the @scheme[wc-export] -list are protected with the corresponding contract. The @scheme[body] of +The first @racket[with-contract] form cannot appear in expression position. +All names defined within the first @racket[with-contract] form are +visible externally, but those names listed in the @racket[wc-export] +list are protected with the corresponding contract. The @racket[body] of the form allows definition/expression interleaving if its context does. -The second @scheme[with-contract] form must appear in expression position. -The final @scheme[body] expression should return the same number of values -as the number of contracts listed in the @scheme[result-spec], and each +The second @racket[with-contract] form must appear in expression position. +The final @racket[body] expression should return the same number of values +as the number of contracts listed in the @racket[result-spec], and each returned value is contracted with its respective contract. The sequence -of @scheme[body] forms is treated as for @scheme[let]. +of @racket[body] forms is treated as for @racket[let]. -The @scheme[blame-id] is used for the positive positions of -contracts paired with exported @scheme[id]s. Contracts broken -within the @scheme[with-contract] @scheme[body] will use the -@scheme[blame-id] for their negative position. +The @racket[blame-id] is used for the positive positions of +contracts paired with exported @racket[id]s. Contracts broken +within the @racket[with-contract] @racket[body] will use the +@racket[blame-id] for their negative position. If a free-var-list is given, then any uses of the free variables -inside the @scheme[body] will be protected with contracts that -blame the context of the @scheme[with-contract] form for the positive -positions and the @scheme[with-contract] form for the negative ones.} +inside the @racket[body] will be protected with contracts that +blame the context of the @racket[with-contract] form for the positive +positions and the @racket[with-contract] form for the negative ones.} @defform*[[(define/contract id contract-expr free-var-list init-value-expr) (define/contract (head args) contract-expr free-var-list body ...+)]]{ -Works like @scheme[define], except that the contract -@scheme[contract-expr] is attached to the bound value. For the -definition of @scheme[head] and @scheme[args], see @scheme[define]. -For the definition of @scheme[free-var-list], see @scheme[with-contract]. +Works like @racket[define], except that the contract +@racket[contract-expr] is attached to the bound value. For the +definition of @racket[head] and @racket[args], see @racket[define]. +For the definition of @racket[free-var-list], see @racket[with-contract]. -The @scheme[define/contract] form treats the individual definition as +The @racket[define/contract] form treats the individual definition as a contract region. The definition itself is responsible for positive (co-variant) positions of the contract and references to -@scheme[id] outside of the definition must meet the negative +@racket[id] outside of the definition must meet the negative positions of the contract. Since the contract boundary is between the definition and the surrounding context, references to -@scheme[id] inside the @scheme[define/contract] form are not checked. +@racket[id] inside the @racket[define/contract] form are not checked. If a free-var-list is given, then any uses of the free variables -inside the @scheme[body] will be protected with contracts that -blame the context of the @scheme[define/contract] form for the positive -positions and the @scheme[define/contract] form for the negative ones.} +inside the @racket[body] will be protected with contracts that +blame the context of the @racket[define/contract] form for the positive +positions and the @racket[define/contract] form for the negative ones.} @defform*[[(define-struct/contract struct-id ([field contract-expr] ...) struct-option ...) (define-struct/contract (struct-id super-struct-id) ([field contract-expr] ...) struct-option ...)]]{ -Works like @scheme[define-struct], except that the arguments to the constructor, +Works like @racket[define-struct], except that the arguments to the constructor, accessors, and mutators are protected by contracts. For the definitions of -@scheme[field] and @scheme[struct-option], see @scheme[define-struct]. +@racket[field] and @racket[struct-option], see @racket[define-struct]. -The @scheme[define-struct/contract] form only allows a subset of the -@scheme[struct-option] keywords: @scheme[#:mutable], @scheme[#:transparent], -@scheme[#:auto-value], @scheme[#:omit-define-syntaxes], @scheme[#:property] and -@scheme[#:omit-define-values]. +The @racket[define-struct/contract] form only allows a subset of the +@racket[struct-option] keywords: @racket[#:mutable], @racket[#:transparent], +@racket[#:auto-value], @racket[#:omit-define-syntaxes], @racket[#:property] and +@racket[#:omit-define-values]. @examples[#:eval (contract-eval) (define-struct/contract fish ([color number?])) @@ -829,30 +829,30 @@ The @scheme[define-struct/contract] form only allows a subset of the value-name-expr source-location-expr)]]{ The primitive mechanism for attaching a contract to a value. The -purpose of @scheme[contract] is as a target for the expansion of some +purpose of @racket[contract] is as a target for the expansion of some higher-level contract specifying form. -The @scheme[contract] expression adds the contract specified by -@scheme[contract-expr] to the value produced by -@scheme[to-protect-expr]. The result of a @scheme[contract] expression -is the result of the @scheme[to-protect-expr] expression, but with the -contract specified by @scheme[contract-expr] enforced on -@scheme[to-protect-expr]. +The @racket[contract] expression adds the contract specified by +@racket[contract-expr] to the value produced by +@racket[to-protect-expr]. The result of a @racket[contract] expression +is the result of the @racket[to-protect-expr] expression, but with the +contract specified by @racket[contract-expr] enforced on +@racket[to-protect-expr]. -The values of @scheme[positive-blame-expr] and @scheme[negative-blame-expr] +The values of @racket[positive-blame-expr] and @racket[negative-blame-expr] indicate how to assign blame for positive and negative positions of the contract -specified by @scheme[contract-expr]. They may be any value, and are formatted -as by @scheme[display] for purposes of contract violation error messages. +specified by @racket[contract-expr]. They may be any value, and are formatted +as by @racket[display] for purposes of contract violation error messages. -If specified, @scheme[value-name-expr] indicates a name for the protected value -to be used in error messages. If not supplied, or if @scheme[value-name-expr] -produces @scheme[#f], no name is printed. Otherwise, it is also formatted as by -@scheme[display]. +If specified, @racket[value-name-expr] indicates a name for the protected value +to be used in error messages. If not supplied, or if @racket[value-name-expr] +produces @racket[#f], no name is printed. Otherwise, it is also formatted as by +@racket[display]. -If specified, @scheme[source-location-expr] indicates the source location -reported by contract violations. The expession must produce a @scheme[srcloc] -structure, @tech{syntax object}, @scheme[#f], or a list or vector in the format -accepted by the third argument to @scheme[datum->syntax]. +If specified, @racket[source-location-expr] indicates the source location +reported by contract violations. The expession must produce a @racket[srcloc] +structure, @tech{syntax object}, @racket[#f], or a list or vector in the format +accepted by the third argument to @racket[datum->syntax]. } @@ -870,10 +870,10 @@ spirit of Dana Scott) that enforce the contract. A projection is a function that accepts an arbitrary value, and returns a value that satisfies the corresponding contract. For example, a projection that accepts only -integers corresponds to the contract @scheme[(flat-contract +integers corresponds to the contract @racket[(flat-contract integer?)], and can be written like this: -@schemeblock[ +@racketblock[ (define int-proj (lambda (x) (if (integer? x) @@ -884,7 +884,7 @@ integer?)], and can be written like this: As a second example, a projection that accepts unary functions on integers looks like this: -@schemeblock[ +@racketblock[ (define int->int-proj (lambda (f) (if (and (procedure? f) @@ -904,12 +904,12 @@ the names of two parties that are the candidates for blame, as well as a record of the source location where the contract was established and the name of the contract. They can then, in turn, pass that information -to @scheme[raise-blame-error] to signal a good error +to @racket[raise-blame-error] to signal a good error message. Here is the first of those two projections, rewritten for use in the contract system: -@schemeblock[ +@racketblock[ (define (int-proj blame) (lambda (x) (if (integer? x) @@ -931,12 +931,12 @@ the ``positive'' person and the second the ``negative''. So, in the case of just the integer contract, the only thing that can go wrong is that the value provided is not an integer. Thus, only the positive party can ever accrue -blame. The @scheme[raise-blame-error] function always blames +blame. The @racket[raise-blame-error] function always blames the positive party. Compare that to the projection for our function contract: -@schemeblock[ +@racketblock[ (define (int->int-proj blame) (let ([dom (int-proj (blame-swap blame))] [rng (int-proj blame)]) @@ -957,15 +957,15 @@ where either a non-procedure is supplied to the contract, or where the procedure does not accept one argument. As with the integer projection, the blame here also lies with the producer of the value, which is -why @scheme[raise-blame-error] is passed @scheme[blame] unchanged. +why @racket[raise-blame-error] is passed @racket[blame] unchanged. The checking for the domain and range are delegated to -the @scheme[int-proj] function, which is supplied its +the @racket[int-proj] function, which is supplied its arguments in the first two line of -the @scheme[int->int-proj] function. The trick here is that, -even though the @scheme[int->int-proj] function always +the @racket[int->int-proj] function. The trick here is that, +even though the @racket[int->int-proj] function always blames what it sees as positive we can swap the blame parties by -calling @scheme[blame-swap] on the given @tech{blame object}, replacing +calling @racket[blame-swap] on the given @tech{blame object}, replacing the positive party with the negative party and vice versa. This is not just a cheap trick to get this example to work, @@ -989,7 +989,7 @@ We can use this insight to generalize the function contracts and build a function that accepts any two contracts and returns a contract for functions between them. -@schemeblock[ +@racketblock[ (define (make-simple-function-contract dom-proj range-proj) (lambda (blame) (let ([dom (dom-proj (blame-swap blame))] @@ -1039,24 +1039,24 @@ These functions build simple procedure-based contracts and flat contracts, respectively. They both take the same set of three optional arguments: a name, a first order predicate, and a blame-tracking projection. -The @scheme[name] argument is any value to be rendered using @scheme[display] to +The @racket[name] argument is any value to be rendered using @racket[display] to describe the contract when a violation occurs. The default name for simple -higher order contracts is @schemeresult[anonymous-contract], and for flat -contracts is @schemeresult[anonymous-flat-contract]. +higher order contracts is @racketresult[anonymous-contract], and for flat +contracts is @racketresult[anonymous-flat-contract]. -The first order predicate @scheme[test] can be used to determine which values +The first order predicate @racket[test] can be used to determine which values the contract applies to; usually this is the set of values for which the contract fails immediately without any higher-order wrapping. This test is used -by @scheme[contract-first-order-passes?], and indirectly by @scheme[or/c] to +by @racket[contract-first-order-passes?], and indirectly by @racket[or/c] to determine which of multiple higher order contracts to wrap a value with. The default test accepts any value. -The projection @scheme[proj] defines the behavior of applying the contract. It +The projection @racket[proj] defines the behavior of applying the contract. It is a curried function of two arguments: the first application accepts a blame object, and the second accepts a value to protect with the contract. The projection must either produce the value, suitably wrapped to enforce any higher-order aspects of the contract, or signal a contract violation using -@scheme[raise-blame-error]. The default projection produces an error when the +@racket[raise-blame-error]. The default projection produces an error when the first order test fails, and produces the value unchanged otherwise. Projections for flat contracts must fail precisely when the first order test @@ -1105,33 +1105,33 @@ extracts the names from any contracts it is supplied with.} @defproc[(coerce-contract [id symbol?] [x any/c]) contract?]{ -Converts a regular scheme value into an instance of a contract struct, +Converts a regular racket value into an instance of a contract struct, converting it according to the description of @tech{contracts}. -If @scheme[x] is not one of the coercable values, -@scheme[coerce-contract] signals an error, using the first argument in +If @racket[x] is not one of the coercable values, +@racket[coerce-contract] signals an error, using the first argument in the error message.} @defproc[(coerce-contracts [id symbol?] [xs (listof any/c)]) (listof contract?)]{ Coerces all of the arguments in 'xs' into contracts (via -@scheme[coerce-contract/f]) and signals an error if any of them are not +@racket[coerce-contract/f]) and signals an error if any of them are not contracts. The error messages assume that the function named by -@scheme[id] got @scheme[xs] as its entire argument list. +@racket[id] got @racket[xs] as its entire argument list. } @defproc[(coerce-flat-contract [id symbol?] [x any/c]) flat-contract?]{ - Like @scheme[coerce-contract], but requires the result + Like @racket[coerce-contract], but requires the result to be a flat contract, not an arbitrary contract. } @defproc[(coerce-flat-contracts [id symbol?] [x (listof any/c)]) (listof/c flat-contract?)]{ - Like @scheme[coerce-contracts], but requires the results + Like @racket[coerce-contracts], but requires the results to be flat contracts, not arbitrary contracts. } @defproc[(coerce-contract/f [x any/c]) (or/c contract? #f)]{ - Like @scheme[coerce-contract], but returns @scheme[#f] if + Like @racket[coerce-contract], but returns @racket[#f] if the value cannot be coerced to a contract. } @@ -1151,18 +1151,18 @@ negative parties of a blame object. @defproc[(blame-contract [b blame?]) any/c]{ This function produces a description of the contract associated with a blame -object (the result of @scheme[contract-name]). +object (the result of @racket[contract-name]). } @defproc[(blame-value [b blame?]) any/c]{ This function produces the name of the value to which the contract was applied, -or @scheme[#f] if no name was provided. +or @racket[#f] if no name was provided. } @defproc[(blame-source [b blame?]) srcloc?]{ This function produces the source location associated with a contract. If no source location was provided, all fields of the structure will contain -@scheme[#f]. +@racket[#f]. } @defproc[(blame-swap [b blame?]) blame?]{ @@ -1184,18 +1184,18 @@ the other; both are provided for convenience and clarity. @defproc[(raise-blame-error [b blame?] [x any/c] [fmt string?] [v any/c] ...) none/c]{ -Signals a contract violation. The first argument, @scheme[b], records the +Signals a contract violation. The first argument, @racket[b], records the current blame information, including positive and negative parties, the name of the contract, the name of the value, and the source location of the contract -application. The second argument, @scheme[x], is the value that failed to +application. The second argument, @racket[x], is the value that failed to satisfy the contract. The remaining arguments are a format string, -@scheme[fmt], and its arguments, @scheme[v ...], specifying an error message +@racket[fmt], and its arguments, @racket[v ...], specifying an error message specific to the precise violation. } @defproc[(exn:fail:contract:blame? [x any/c]) boolean?]{ -This predicate recognizes exceptions raised by @scheme[raise-blame-error]. +This predicate recognizes exceptions raised by @racket[raise-blame-error]. } @defproc[(exn:fail:contract:blame-object [e exn:fail:contract:blame?]) blame?]{ @@ -1208,10 +1208,10 @@ This accessor extracts the blame object associated with a contract violation. The interface in this section is unstable and subject to change.} @para{ -The property @scheme[prop:contract] allows arbitrary structures to act as -contracts. The property @scheme[prop:flat-contract] allows arbitrary structures -to act as flat contracts; @scheme[prop:flat-contract] inherits both -@scheme[prop:contract] and @scheme[prop:procedure], so flat contract structures +The property @racket[prop:contract] allows arbitrary structures to act as +contracts. The property @racket[prop:flat-contract] allows arbitrary structures +to act as flat contracts; @racket[prop:flat-contract] inherits both +@racket[prop:contract] and @racket[prop:procedure], so flat contract structures may also act as general contracts and as predicate procedures. } @@ -1220,10 +1220,10 @@ may also act as general contracts and as predicate procedures. @defthing[prop:flat-contract struct-type-property?] )]{ These properties declare structures to be contracts or flat contracts, -respectively. The value for @scheme[prop:contract] must be a @tech{contract -property} constructed by @scheme[build-contract-property]; likewise, the value -for @scheme[prop:flat-contract] must be a @tech{flat contract property} -constructed by @scheme[build-flat-contract-property]. +respectively. The value for @racket[prop:contract] must be a @tech{contract +property} constructed by @racket[build-contract-property]; likewise, the value +for @racket[prop:flat-contract] must be a @tech{flat contract property} +constructed by @racket[build-flat-contract-property]. } @deftogether[( @@ -1285,32 +1285,32 @@ constructed by @scheme[build-flat-contract-property]. contract-property?] )]{ -These functions build the arguments for @scheme[prop:contract] and -@scheme[prop:flat-contract], respectively. +These functions build the arguments for @racket[prop:contract] and +@racket[prop:flat-contract], respectively. A @deftech{contract property} specifies the behavior of a structure when used as -a contract. It is specified in terms of five accessors: @scheme[get-name], -which produces a description to @scheme[write] as part of a contract violation; -@scheme[get-first-order], which produces a first order predicate to be used by -@scheme[contract-first-order-passes?]; @scheme[get-projection], which +a contract. It is specified in terms of five accessors: @racket[get-name], +which produces a description to @racket[write] as part of a contract violation; +@racket[get-first-order], which produces a first order predicate to be used by +@racket[contract-first-order-passes?]; @racket[get-projection], which produces a blame-tracking projection defining the behavior of the contract; -@scheme[stronger], which is a predicate that determines if one contract this contract +@racket[stronger], which is a predicate that determines if one contract this contract (passed in the first argument) is stronger than some other contract (passed in the second argument); -and @scheme[generator], which makes a random value that matches the contract, +and @racket[generator], which makes a random value that matches the contract, given a size bound and an environment from which to draw interesting values. These accessors are passed as (optional) keyword arguments to -@scheme[build-contract-property], and are applied to instances of the +@racket[build-contract-property], and are applied to instances of the appropriate structure type by the contract system. Their results are used -analogously to the arguments of @scheme[make-contract]. +analogously to the arguments of @racket[make-contract]. A @deftech{flat contract property} specifies the behavior of a structure when used as a flat contract. It is specified using -@scheme[build-flat-contract-property], and accepts exactly the same set of -arguments as @scheme[build-contract-property]. The only difference is that the +@racket[build-flat-contract-property], and accepts exactly the same set of +arguments as @racket[build-contract-property]. The only difference is that the projection accessor is expected not to wrap its argument in a higher order fashion, analogous to the constraint on projections in -@scheme[make-flat-contract]. +@racket[make-flat-contract]. } @@ -1328,18 +1328,18 @@ These predicates detect whether a value is a @tech{contract property} or a @defproc[(contract? [v any/c]) boolean?]{ -Returns @scheme[#t] if its argument is a contract (i.e., constructed +Returns @racket[#t] if its argument is a contract (i.e., constructed with one of the combinators described in this section or a value that -can be used as a contract) and @scheme[#f] otherwise.} +can be used as a contract) and @racket[#f] otherwise.} @defproc[(flat-contract? [v any/c]) boolean?]{ -Returns @scheme[#t] when its argument is a contract that can be +Returns @racket[#t] when its argument is a contract that can be checked immediately (unlike, say, a function contract). For example, -@scheme[flat-contract] constructs flat contracts from predicates, and -symbols, booleans, numbers, and other ordinary Scheme values +@racket[flat-contract] constructs flat contracts from predicates, and +symbols, booleans, numbers, and other ordinary Racket values (that are defined as @tech{contracts}) are also flat contracts.} @@ -1349,12 +1349,12 @@ flat contracts.} Extracts the predicate from a flat contract.} @defproc[(value-contract [v has-contract?]) contract?]{ - Returns the contract attached to @scheme[v], if recorded. - Otherwise it returns @scheme[#f]. + Returns the contract attached to @racket[v], if recorded. + Otherwise it returns @racket[#f]. } @defproc[(has-contract? [v any/c]) boolean?]{ - Returns @scheme[#t] if @scheme[v] is a value that + Returns @racket[#t] if @racket[v] is a value that has a recorded contract attached to it. } @@ -1363,12 +1363,12 @@ Extracts the predicate from a flat contract.} boolean?]{ Returns a boolean indicating if the first-order tests -of @scheme[contract] pass for @scheme[v]. +of @racket[contract] pass for @racket[v]. -If it returns @scheme[#f], the contract is guaranteed not to -hold for that value; if it returns @scheme[#t], the contract +If it returns @racket[#f], the contract is guaranteed not to +hold for that value; if it returns @racket[#t], the contract may or may not hold. If the contract is a first-order -contract, a result of @scheme[#t] guarantees that the +contract, a result of @racket[#t] guarantees that the contract holds.} @defproc[(contract-name [c contract?]) any/c]{ @@ -1376,7 +1376,7 @@ Produces the name used to describe the contract in error messages. } @defproc[(contract-first-order [c contract?]) (-> any/c boolean?)]{ -Produces the first order test used by @scheme[or/c] to match values to higher +Produces the first order test used by @racket[or/c] to match values to higher order contracts. } @@ -1387,7 +1387,7 @@ Produces the projection defining a contract's behavior on protected values. @defproc[(make-none/c [sexp-name any/c]) contract?]{ Makes a contract that accepts no values, and reports the -name @scheme[sexp-name] when signaling a contract violation.} +name @racket[sexp-name] when signaling a contract violation.} @defparam[current-blame-format @@ -1449,14 +1449,14 @@ except faster (due to the less allocation).} This defines a recursive contract and simultaneously optimizes it. Semantically, it behaves just as if -the @scheme[-opt/c] were not present, defining a function on +the @racket[-opt/c] were not present, defining a function on contracts (except that the body expression must return a contract). But, it also optimizes that contract definition, -avoiding extra allocation, much like @scheme[opt/c] does. +avoiding extra allocation, much like @racket[opt/c] does. For example, -@schemeblock[ +@racketblock[ (define-contract-struct bt (val left right)) (define-opt/c (bst-between/c lo hi) @@ -1468,8 +1468,8 @@ For example, (define bst/c (bst-between/c -inf.0 +inf.0)) ] -defines the @scheme[bst/c] contract that checks the binary -search tree invariant. Removing the @scheme[-opt/c] also +defines the @racket[bst/c] contract that checks the binary +search tree invariant. Removing the @racket[-opt/c] also makes a binary search tree contract, but one that is (approximately) 20 times slower.} diff --git a/collects/scribblings/reference/encodings.scrbl b/collects/scribblings/reference/encodings.scrbl index 73141ac6c9..a5bbe48382 100644 --- a/collects/scribblings/reference/encodings.scrbl +++ b/collects/scribblings/reference/encodings.scrbl @@ -5,31 +5,31 @@ @title[#:tag "encodings"]{Encodings and Locales} When a port is provided to a character-based operation, such as -@scheme[read-char] or @scheme[read], the port's bytes are read and +@racket[read-char] or @racket[read], the port's bytes are read and interpreted as a UTF-8 encoding of characters. Thus, reading a single character may require reading multiple bytes, and a procedure like -@scheme[char-ready?] may need to peek several bytes into the stream to +@racket[char-ready?] may need to peek several bytes into the stream to determine whether a character is available. In the case of a byte stream that does not correspond to a valid UTF-8 encoding, functions -such as @scheme[read-char] may need to peek one byte ahead in the +such as @racket[read-char] may need to peek one byte ahead in the stream to discover that the stream is not a valid encoding. When an input port produces a sequence of bytes that is not a valid UTF-8 encoding in a character-reading context, then bytes that constitute an invalid sequence are converted to the character -@schemevalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted -to @schemevalfont{#\uFFFD}, bytes in the range 192 to 253 produce -@schemevalfont{#\uFFFD} when they are not followed by bytes that form a valid +@racketvalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted +to @racketvalfont{#\uFFFD}, bytes in the range 192 to 253 produce +@racketvalfont{#\uFFFD} when they are not followed by bytes that form a valid UTF-8 encoding, and bytes in the range 128 to 191 are converted to -@schemevalfont{#\uFFFD} when they are not part of a valid encoding that was +@racketvalfont{#\uFFFD} when they are not part of a valid encoding that was started by a preceding byte in the range 192 to 253. To put it another way, when reading a sequence of bytes as characters, a minimal set of -bytes are changed to the encoding of @schemevalfont{#\uFFFD} so that the +bytes are changed to the encoding of @racketvalfont{#\uFFFD} so that the entire sequence of bytes is a valid UTF-8 encoding. See @secref["bytestrings"] for procedures that facilitate conversions using UTF-8 or other encodings. See also -@scheme[reencode-input-port] and @scheme[reencode-output-port] for +@racket[reencode-input-port] and @racket[reencode-output-port] for obtaining a UTF-8-based port from one that uses a different encoding of characters. @@ -39,58 +39,58 @@ culture-specific interpretation of character sequences. In particular, a locale determines how strings are ``alphabetized,'' how a lowercase character is converted to an uppercase character, and how strings are compared without regard to case. String operations such as -@scheme[string-ci=?] are @italic{not} sensitive to the current locale, -but operations such as @scheme[string-locale-ci=?] (see +@racket[string-ci=?] are @italic{not} sensitive to the current locale, +but operations such as @racket[string-locale-ci=?] (see @secref["strings"]) produce results consistent with the current locale. A locale also designates a particular encoding of code-point sequences -into byte sequences. Scheme generally ignores this aspect of the +into byte sequences. Racket generally ignores this aspect of the locale, with a few notable exceptions: command-line arguments passed -to Scheme as byte strings are converted to character strings using the +to Racket as byte strings are converted to character strings using the locale's encoding; command-line strings passed as byte strings to -other processes (through @scheme[subprocess]) are converted to byte +other processes (through @racket[subprocess]) are converted to byte strings using the locale's encoding; environment variables are converted to and from strings using the locale's encoding; filesystem paths are converted to and from strings (for display purposes) using -the locale's encoding; and, finally, Scheme provides functions such as -@scheme[string->bytes/locale] to specifically invoke a locale-specific +the locale's encoding; and, finally, Racket provides functions such as +@racket[string->bytes/locale] to specifically invoke a locale-specific encoding. A Unix user selects a locale by setting environment variables, such as @envvar{LC_ALL}. Under Windows and Mac OS X, the operating system -provides other mechanisms for setting the locale. Within Scheme, the -current locale can be changed by setting the @scheme[current-locale] -parameter. The locale name within Scheme is a string, and the +provides other mechanisms for setting the locale. Within Racket, the +current locale can be changed by setting the @racket[current-locale] +parameter. The locale name within Racket is a string, and the available locale names depend on the platform and its configuration, -but the @scheme[""] locale means the current user's default locale; -under Windows and Mac OS X, the encoding for @scheme[""] is always +but the @racket[""] locale means the current user's default locale; +under Windows and Mac OS X, the encoding for @racket[""] is always UTF-8, and locale-sensitive operations use the operating system's native interface. (In particular, setting the @envvar{LC_ALL} and @envvar{LC_CTYPE} environment variables do not affect the locale -@scheme[""] under Mac OS X. Use @scheme[getenv] and -@scheme[current-locale] to explicitly install the +@racket[""] under Mac OS X. Use @racket[getenv] and +@racket[current-locale] to explicitly install the environment-specified locale, if desired.) Setting the current locale -to @scheme[#f] makes locale-sensitive operations locale-insensitive, +to @racket[#f] makes locale-sensitive operations locale-insensitive, which means using the Unicode mapping for case operations and using UTF-8 for encoding. @defparam[current-locale locale (or/c string? #f)]{ A parameter that determines the current @tech{locale} for -procedures such as @scheme[string-locale-ci=?]. +procedures such as @racket[string-locale-ci=?]. When locale sensitivity is disabled by setting the parameter to -@scheme[#f], strings are compared (etc.) in a fully portable manner, +@racket[#f], strings are compared (etc.) in a fully portable manner, which is the same as the standard procedures. Otherwise, strings are interpreted according to a locale setting (in the sense of the C -library's @tt{setlocale}). The @scheme[""] locale is always a synonym +library's @tt{setlocale}). The @racket[""] locale is always a synonym for the current machine's default locale, and it is the default. The -@scheme["C"] locale is also always available; setting the locale to -@scheme["C"] is the same as disabling locale sensitivity with -@scheme[#f] only when string operations are restricted to the first +@racket["C"] locale is also always available; setting the locale to +@racket["C"] is the same as disabling locale sensitivity with +@racket[#f] only when string operations are restricted to the first 128 characters. Other locale names are platform-specific. -String or character printing with @scheme[write] is not affected by +String or character printing with @racket[write] is not affected by the parameter, and neither are symbol case or regular expressions (see @secref["regexp"]).} diff --git a/collects/scribblings/reference/eval.scrbl b/collects/scribblings/reference/eval.scrbl index 23a5713cd1..da32d14f4a 100644 --- a/collects/scribblings/reference/eval.scrbl +++ b/collects/scribblings/reference/eval.scrbl @@ -8,23 +8,23 @@ A parameter that determines the current @deftech{evaluation handler}. The evaluation handler is a procedure that takes a top-level form and evaluates it, returning the resulting values. The @tech{evaluation -handler} is called by @scheme[eval], @scheme[eval-syntax], the default -@tech{load handler}, and @scheme[read-eval-print-loop] to evaluate a +handler} is called by @racket[eval], @racket[eval-syntax], the default +@tech{load handler}, and @racket[read-eval-print-loop] to evaluate a top-level form. The handler should evaluate its argument in tail position. -The @scheme[_top-level-form] provided to the handler can be a +The @racket[_top-level-form] provided to the handler can be a @tech{syntax object}, a compiled form, a compiled form wrapped as a syntax object, or an arbitrary datum. The default handler converts an arbitrary datum to a syntax object -using @scheme[datum->syntax], and then enriches its @tech{lexical -information} in the same way as @scheme[eval]. (If -@scheme[_top-level-form] is a syntax object, then its @tech{lexical +using @racket[datum->syntax], and then enriches its @tech{lexical +information} in the same way as @racket[eval]. (If +@racket[_top-level-form] is a syntax object, then its @tech{lexical information} is not enriched.) The default evaluation handler partially expands the form to splice the body of top-level -@scheme[begin] forms into the top level (see -@scheme[expand-to-top-form]), and then individually compiles and +@racket[begin] forms into the top level (see +@racket[expand-to-top-form]), and then individually compiles and evaluates each spliced form before continuing to expand, compile, and evaluate later forms.} @@ -34,42 +34,42 @@ evaluate later forms.} any]{ Calls the current @tech{evaluation handler} to evaluate -@scheme[top-level-form]. The @tech{evaluation handler} is called in -tail position with respect to the @scheme[eval] call, and -@scheme[parameterize]d to set @scheme[current-namespace] to -@scheme[namespace]. +@racket[top-level-form]. The @tech{evaluation handler} is called in +tail position with respect to the @racket[eval] call, and +@racket[parameterize]d to set @racket[current-namespace] to +@racket[namespace]. -If @scheme[top-level-form] is a syntax object whose datum is not a +If @racket[top-level-form] is a syntax object whose datum is not a compiled form, then its @tech{lexical information} is enriched before it is sent to the @tech{evaluation handler}: @itemize[ - @item{If @scheme[top-level-form] is a pair whose @scheme[car] is a + @item{If @racket[top-level-form] is a pair whose @racket[car] is a symbol or identifier, and if applying - @scheme[namespace-syntax-introduce] to the - (@scheme[datum->syntax]-converted) identifier produces an - identifier bound to @scheme[module] in a @tech{phase level} - that corresponds to @scheme[namespace]'s @tech{base phase}, + @racket[namespace-syntax-introduce] to the + (@racket[datum->syntax]-converted) identifier produces an + identifier bound to @racket[module] in a @tech{phase level} + that corresponds to @racket[namespace]'s @tech{base phase}, then only that identifier is enriched.} - @item{For any other @scheme[top-level-form], - @scheme[namespace-syntax-introduce] is applied to the entire + @item{For any other @racket[top-level-form], + @racket[namespace-syntax-introduce] is applied to the entire syntax object.} ] For interactive evaluation in the style of -@scheme[read-eval-print-loop] and @scheme[load], wrap each expression -with @schemeidfont{#%top-interaction}, which is normally bound to -@scheme[#%top-interaction], before passing it to @scheme[eval].} +@racket[read-eval-print-loop] and @racket[load], wrap each expression +with @racketidfont{#%top-interaction}, which is normally bound to +@racket[#%top-interaction], before passing it to @racket[eval].} @defproc[(eval-syntax [stx syntax?] [namespace namespace? (current-namespace)]) any]{ -Like @scheme[eval], except that @scheme[stx] must be a syntax object, +Like @racket[eval], except that @racket[stx] must be a syntax object, and its lexical context is not enriched before it is passed to the @tech{evaluation handler}.} @@ -78,39 +78,39 @@ and its lexical context is not enriched before it is passed to the A parameter that determines the current @deftech{load handler} to load top-level forms from a file. The @tech{load handler} is called by -@scheme[load], @scheme[load-relative], @scheme[load/cd], and the +@racket[load], @racket[load-relative], @racket[load/cd], and the default @tech{compiled-load handler}. A load handler takes two arguments: a path (see @secref["pathutils"]) and an expected module name. The expected module name is a symbol when the call is to load a module declaration -in response to a @scheme[require] (in which case the file should -contain a module declaration), or @scheme[#f] for any other load. +in response to a @racket[require] (in which case the file should +contain a module declaration), or @racket[#f] for any other load. The default load handler reads forms from the file in -@scheme[read-syntax] mode with line-counting enabled for the file -port, unless the path has a @scheme[".zo"] suffix. It also -@scheme[parameterize]s each read to set both -@scheme[read-accept-compiled] and @scheme[read-accept-reader] to -@scheme[#t]. In addition, if @scheme[load-on-demand-enabled] is -@scheme[#t], then @scheme[read-on-demand-source] is effectively set to -the @tech{cleanse}d, absolute form of @scheme[path] during the -@scheme[read-syntax] call. After reading a single form, the form is +@racket[read-syntax] mode with line-counting enabled for the file +port, unless the path has a @racket[".zo"] suffix. It also +@racket[parameterize]s each read to set both +@racket[read-accept-compiled] and @racket[read-accept-reader] to +@racket[#t]. In addition, if @racket[load-on-demand-enabled] is +@racket[#t], then @racket[read-on-demand-source] is effectively set to +the @tech{cleanse}d, absolute form of @racket[path] during the +@racket[read-syntax] call. After reading a single form, the form is passed to the current @tech{evaluation handler}, wrapping the evaluation in a continuation prompt (see -@scheme[call-with-continuation-prompt]) for the default continuation +@racket[call-with-continuation-prompt]) for the default continuation prompt tag with handler that propagates the abort to the continuation -of the @scheme[load] call. +of the @racket[load] call. If the second argument to the load handler is a symbol, then: @itemize[ - @item{The @scheme[read-syntax] from the file is additionally - @scheme[parameterize]d as follows (to provide consistent reading + @item{The @racket[read-syntax] from the file is additionally + @racket[parameterize]d as follows (to provide consistent reading of module source): - @schemeblock[ + @racketblock[ (current-readtable #f) (read-case-sensitive #t) (read-square-bracket-as-paren #t) @@ -126,59 +126,59 @@ If the second argument to the load handler is a symbol, then: (read-accept-reader #t) ]} - @item{If the read result is not a @schemeidfont{module} form with the - expected name, or if a second @scheme[read-syntax] does not + @item{If the read result is not a @racketidfont{module} form with the + expected name, or if a second @racket[read-syntax] does not produce an end-of-file, then the @exnraise[exn:fail] without evaluating the form that was read from the file.} @item{The @tech{lexical information} of the initial - @schemeidfont{module} identifier is enriched with a binding for - @scheme[module], so that the form corresponds to a module + @racketidfont{module} identifier is enriched with a binding for + @racket[module], so that the form corresponds to a module declaration independent of the current namespace's bindings.} ] -If the second argument to the load handler is @scheme[#f], then each +If the second argument to the load handler is @racket[#f], then each expression read from the file is wrapped with -@schemeidfont{#%top-interaction}, which is normally bound to -@scheme[#%top-interaction], before passing it to the @tech{evaluation +@racketidfont{#%top-interaction}, which is normally bound to +@racket[#%top-interaction], before passing it to the @tech{evaluation handler}. The return value from the default @tech{load handler} is the value of the last form from the loaded file, or @|void-const| if the file contains no forms. If the given path is a relative path, then it is -resolved using the value of @scheme[current-directory].} +resolved using the value of @racket[current-directory].} @defproc[(load [file path-string?]) any]{ Calls the current @tech{load handler} in tail position. The call is -@scheme[parameterized] to set @scheme[current-load-relative-directory] -to the directory of @scheme[file], which is resolved relative to -the value of @scheme[current-directory].} +@racket[parameterized] to set @racket[current-load-relative-directory] +to the directory of @racket[file], which is resolved relative to +the value of @racket[current-directory].} @defproc[(load-relative [file path-string?]) any]{ -Like @scheme[load/use-compiled], but when @scheme[file] is a relative +Like @racket[load/use-compiled], but when @racket[file] is a relative path, it is resolved using the value of -@scheme[current-load-relative-directory] instead of the value of -@scheme[current-directory] if the former is not @scheme[#f], otherwise -@scheme[current-directory] is used.} +@racket[current-load-relative-directory] instead of the value of +@racket[current-directory] if the former is not @racket[#f], otherwise +@racket[current-directory] is used.} @defproc[(load/cd [file path-string?]) any]{ -Like @scheme[load], but @scheme[load/cd] sets both -@scheme[current-directory] and -@scheme[current-load-relative-directory] before calling the @tech{load +Like @racket[load], but @racket[load/cd] sets both +@racket[current-directory] and +@racket[current-load-relative-directory] before calling the @tech{load handler}.} @defparam[current-load-extension proc (path? (or/c symbol? #f) . -> . any)]{ A parameter that determines a @deftech{extension-load handler}, which is -called by @scheme[load-extension] and the default @tech{compiled-load +called by @racket[load-extension] and the default @tech{compiled-load handler}. An @tech{extension-load handler} takes the same arguments as a @@ -193,26 +193,26 @@ primitives. See @other-manual['(lib @defproc[(load-extension [file path-string?]) any]{ -Sets @scheme[current-load-relative-directory] like @scheme[load], and +Sets @racket[current-load-relative-directory] like @racket[load], and calls the @tech{extension-load handler} in tail position.} @defproc[(load-relative-extension [file path-string?]) any]{ -Like @scheme[load-exension], but resolves @scheme[file] using -@scheme[current-load-relative-directory] like @scheme[load-relative].} +Like @racket[load-exension], but resolves @racket[file] using +@racket[current-load-relative-directory] like @racket[load-relative].} @defparam[current-load/use-compiled proc (path? (or/c symbol? #f) . -> . any)]{ A parameter that determines the current @deftech{compiled-load handler} to load from a file that may have a compiled form. The -@tech{compiled-load handler} is called by @scheme[load/use-compiled]. +@tech{compiled-load handler} is called by @racket[load/use-compiled]. The protocol for a @tech{compiled-load handler} is the same as for the -@tech{load handler} (see @scheme[current-load]), except that a +@tech{load handler} (see @racket[current-load]), except that a @tech{compiled-load handler} is expected to set -@scheme[current-load-relative-directory] itself. The default +@racket[current-load-relative-directory] itself. The default @tech{compiled-load handler}, however, checks for a @filepath{.ss} file when the given path ends with @filepath{.rkt}, no @filepath{.rkt} file exists, and when the handler's second argument is a symbol. In @@ -222,39 +222,39 @@ addition, the default @tech{compiled-load handler} checks for X) files. The check for a compiled file occurs whenever the given path -@scheme[_file] ends with any extension (e.g., @filepath{.rkt} or +@racket[_file] ends with any extension (e.g., @filepath{.rkt} or @filepath{.scrbl}), and the check consults the subdirectories -indicated by the @scheme[use-compiled-file-paths] parameter relative -to @scheme[_file]. The subdirectories are checked in order. A +indicated by the @racket[use-compiled-file-paths] parameter relative +to @racket[_file]. The subdirectories are checked in order. A @filepath{.zo} version of the file (whose name is formed by passing -@scheme[_file] and @scheme[#".zo"] to @scheme[path-add-suffix]) is +@racket[_file] and @racket[#".zo"] to @racket[path-add-suffix]) is loaded if it exists directly in one of the indicated subdirectories, or a @filepath{.so}/@filepath{.dll}/@filepath{.dylib} version of the file is loaded if it exists within a @filepath{native} subdirectory of -a @scheme[use-compiled-file-paths] directory, in an even deeper -subdirectory as named by @scheme[system-library-subpath]. A compiled +a @racket[use-compiled-file-paths] directory, in an even deeper +subdirectory as named by @racket[system-library-subpath]. A compiled file is loaded only if its modification date is not older than the -date for @scheme[_file]. If both @filepath{.zo} and +date for @racket[_file]. If both @filepath{.zo} and @filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are available, the @filepath{.so}/@filepath{.dll}/@filepath{.dylib} file is used. If -@scheme[_file] ends with @filepath{.rkt}, no such file exists, the +@racket[_file] ends with @filepath{.rkt}, no such file exists, the handler's second argument is a symbol, and a @filepath{.ss} file exists, then @filepath{.zo} and @filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are used only -with names based on @scheme[_file] with its suffixed replaced by +with names based on @racket[_file] with its suffixed replaced by @filepath{.ss}. While a @filepath{.zo}, @filepath{.so}, @filepath{.dll}, or -@filepath{.dylib} file is loaded, the current @scheme[load-relative] -directory is set to the directory of the original @scheme[_file]. If +@filepath{.dylib} file is loaded, the current @racket[load-relative] +directory is set to the directory of the original @racket[_file]. If the file to be loaded has the suffix @filepath{.ss} while the requested file has the suffix @filepath{.rkt}, then the -@scheme[current-module-declare-source] parameter is set to the full +@racket[current-module-declare-source] parameter is set to the full path of the loaded file, otherwise the -@scheme[current-module-declare-source] parameter is set to -@scheme[#f]. +@racket[current-module-declare-source] parameter is set to +@racket[#f]. -If the original @scheme[_file] is loaded or a @filepath{.zo} variant is +If the original @racket[_file] is loaded or a @filepath{.zo} variant is loaded, the @tech{load handler} is called to load the file. If any other kind of file is loaded, the @tech{extension-load handler} is called.} @@ -268,10 +268,10 @@ Calls the current @tech{compiled-load handler} in tail position.} @defparam[current-load-relative-directory path (or/c (and/c path-string? complete-path?) #f)]{ -A parameter that is set by @scheme[load], @scheme[load-relative], -@scheme[load-extension], @scheme[load-relative-extension], and the +A parameter that is set by @racket[load], @racket[load-relative], +@racket[load-extension], @racket[load-relative-extension], and the default @tech{compiled-load handler}, and used by -@scheme[load-relative], @scheme[load-relative-extension], and the +@racket[load-relative], @racket[load-relative-extension], and the default @tech{compiled-load handler}. When a new path or string is provided as the parameter's value, it is @@ -281,27 +281,27 @@ path. (The directory need not exist.)} @defparam*[use-compiled-file-paths paths (listof path-string?) (listof path?)]{ -A list of relative paths, which defaults to @scheme[(list +A list of relative paths, which defaults to @racket[(list (string->path "compiled"))]. It is used by the @tech{compiled-load -handler} (see @scheme[current-load/use-compiled]).} +handler} (see @racket[current-load/use-compiled]).} @defproc[(read-eval-print-loop) any]{ Starts a new @deftech{REPL} using the current input, output, and error ports. The REPL wraps each expression to evaluate with -@schemeidfont{#%top-interaction}, which is normally bound to -@scheme[#%top-interaction], and it wraps each evaluation with a +@racketidfont{#%top-interaction}, which is normally bound to +@racket[#%top-interaction], and it wraps each evaluation with a continuation prompt using the default continuation prompt tag and -prompt handler (see @scheme[call-with-continuation-prompt]). The REPL +prompt handler (see @racket[call-with-continuation-prompt]). The REPL also wraps the read and print operations with a prompt for the default tag whose handler ignores abort arguments and continues the loop. The -@scheme[read-eval-print-loop] procedure does not return until -@scheme[eof] is read, at which point it returns @|void-const|. +@racket[read-eval-print-loop] procedure does not return until +@racket[eof] is read, at which point it returns @|void-const|. -The @scheme[read-eval-print-loop] procedure can be configured through -the @scheme[current-prompt-read], @scheme[current-eval], and -@scheme[current-print] parameters.} +The @racket[read-eval-print-loop] procedure can be configured through +the @racket[current-prompt-read], @racket[current-eval], and +@racket[current-print] parameters.} @defparam[current-prompt-read proc (-> any)]{ @@ -309,14 +309,14 @@ the @scheme[current-prompt-read], @scheme[current-eval], and A parameter that determines a @deftech{prompt read handler}, which is a procedure that takes no arguments, displays a prompt string, and returns a top-level form to evaluate. The prompt read handler is -called by @scheme[read-eval-print-loop], and the handler typically +called by @racket[read-eval-print-loop], and the handler typically should call the @tech{read interaction handler} (as determined by the -@scheme[current-read-interaction] parameter) after printing a prompt. +@racket[current-read-interaction] parameter) after printing a prompt. The default prompt read handler prints @litchar{> } and returns the result of -@schemeblock[ +@racketblock[ (let ([in (current-input-port)]) ((current-read-interaction) (object-name in) in)) ]} @@ -328,10 +328,10 @@ A parameter that determines the current @deftech{read interaction handler}, which is procedure that takes an arbitrary value and an input port and returns an expression read from the input port. -The default read interaction handler accepts @scheme[_src] and -@scheme[_in] and returns +The default read interaction handler accepts @racket[_src] and +@racket[_in] and returns -@schemeblock[ +@racketblock[ (parameterize ([read-accept-reader #t]) (read-syntax _src _in)) ]} @@ -340,12 +340,12 @@ The default read interaction handler accepts @scheme[_src] and @defparam[current-print proc (any/c -> any)]{ A parameter that determines the @deftech{print handler} that is called - by @scheme[read-eval-print-loop] to print the result of an evaluation + by @racket[read-eval-print-loop] to print the result of an evaluation (and the result is ignored). -The default @tech{print handler} @scheme[print]s the value to the +The default @tech{print handler} @racket[print]s the value to the current output port (as determined by the - @scheme[current-output-port] parameter) and then outputs a newline, + @racket[current-output-port] parameter) and then outputs a newline, except that it prints nothing when the value is @|void-const|.} @@ -356,20 +356,20 @@ The @tech{compilation handler} is a procedure that takes a top-level form and returns a compiled form; see see @secref["compilation-model"] for more information on compilation. -The @tech{compilation handler} is called by @scheme[compile], and +The @tech{compilation handler} is called by @racket[compile], and indirectly by the default @tech{evaluation handler} and the default @tech{load handler}. -The handler's second argument is @scheme[#t] if the compiled form will -be used only for immediate evaluation, or @scheme[#f] if the compiled +The handler's second argument is @racket[#t] if the compiled form will +be used only for immediate evaluation, or @racket[#f] if the compiled form may be saved for later use; the default compilation handler is optimized for the special case of immediate evaluation. When a compiled form is written to an output port, the written form starts with @litchar{#~}. These forms are essentially assembly code -for PLT Scheme, and reading such an form produces a compiled form (as -long as the @scheme[read-accept-compiled] parameter is set to -@scheme[#t]). +for Racket, and reading such an form produces a compiled form (as +long as the @racket[read-accept-compiled] parameter is set to +@racket[#t]). When a compiled form contains syntax object constants, the @litchar{#~}-marshaled form drops source-location information and @@ -378,13 +378,13 @@ properties (@secref["stxprops"]) for the @tech{syntax objects}. Compiled code parsed from @litchar{#~} may contain references to unexported or protected bindings from a module. At read time, such references are associated with the current code inspector (see -@scheme[current-code-inspector]), and the code will only execute if +@racket[current-code-inspector]), and the code will only execute if that inspector controls the relevant module invocation (see @secref["modprotect"]). A compiled-form object may contain @tech{uninterned} symbols (see -@secref["symbols"]) that were created by @scheme[gensym] or -@scheme[string->uninterned-symbol]. When the compiled object is read +@secref["symbols"]) that were created by @racket[gensym] or +@racket[string->uninterned-symbol]. When the compiled object is read via @litchar{#~}, each uninterned symbol in the original form is mapped to a new uninterned symbol, where multiple instances of a single symbol are consistently mapped to the same new symbol. The @@ -394,30 +394,30 @@ generated indirectly during expansion and compilation, are saved and restored consistently through @litchar{#~}. Due to the restrictions on @tech{uninterned} symbols in @litchar{#~}, -do not use @scheme[gensym] or @scheme[string->uninterned-symbol] to +do not use @racket[gensym] or @racket[string->uninterned-symbol] to construct an identifier for a top-level or module binding. Instead, generate distinct identifiers either with -@scheme[generate-temporaries] or by applying the result of -@scheme[make-syntax-introducer] to an existing identifier; those +@racket[generate-temporaries] or by applying the result of +@racket[make-syntax-introducer] to an existing identifier; those functions will lead to top-level and module bindings with @tech{unreadable symbol}ic names.} @defproc[(compile [top-level-form any/c]) compiled-expression?]{ -Like @scheme[eval], but calls the current @tech{compilation handler} in -tail position with @scheme[top-level-form].} +Like @racket[eval], but calls the current @tech{compilation handler} in +tail position with @racket[top-level-form].} @defproc[(compile-syntax [stx syntax?]) compiled-expression?]{ -Like @scheme[eval-syntax], but calls the current @tech{compilation -handler} in tail position with @scheme[stx].} +Like @racket[eval-syntax], but calls the current @tech{compilation +handler} in tail position with @racket[stx].} @defproc[(compiled-expression? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a compiled form, @scheme[#f] +Returns @racket[#t] if @racket[v] is a compiled form, @racket[#f] otherwise.} @@ -426,10 +426,10 @@ otherwise.} A parameter that determines how a module declaration is compiled. When constants are enforced, and when the macro-expanded body of a -module contains no @scheme[set!] assignment to a particular variable +module contains no @racket[set!] assignment to a particular variable defined within the module, then the variable is marked as constant when the definition is evaluated. Afterward, the variable's value -cannot be assigned or undefined through @scheme[module->namespace], +cannot be assigned or undefined through @racket[module->namespace], and it cannot be defined by redeclaring the module. Enforcing constants allows the compiler to inline some variable @@ -439,14 +439,14 @@ generate code that skips certain run-time checks.} @defboolparam[compile-allow-set!-undefined allow?]{ -A parameter that determines how a @scheme[set!] expression is compiled +A parameter that determines how a @racket[set!] expression is compiled when it mutates a global variable. If the value of this parameter is a -true value, @scheme[set!] expressions for global variables are +true value, @racket[set!] expressions for global variables are compiled so that the global variable is set even if it was not -previously defined. Otherwise, @scheme[set!] expressions for global +previously defined. Otherwise, @racket[set!] expressions for global variables are compiled to raise the -@scheme[exn:fail:contract:variable] exception if the global variable -is not defined at the time the @scheme[set!] is performed. Note that +@racket[exn:fail:contract:variable] exception if the global variable +is not defined at the time the @racket[set!] is performed. Note that this parameter is used when an expression is @italic{compiled}, not when it is @italic{evaluated}.} @@ -455,22 +455,22 @@ when it is @italic{evaluated}.} A parameter that determines whether compilation should avoid function-call inlining and other optimizations that may cause information to be lost from stack traces (as reported by -@scheme[continuation-mark-set->context]). The default is @scheme[#f], +@racket[continuation-mark-set->context]). The default is @racket[#f], which allows such optimizations.} @defboolparam[eval-jit-enabled on?]{ A parameter that determines whether the native-code just-in-time compiler (JIT) is enabled for code (compiled or not) that is passed to -the default evaluation handler. The default is @scheme[#t], unless +the default evaluation handler. The default is @racket[#t], unless the JIT is disabled through the @Flag{j}/@DFlag{no-jit} command-line -flag to stand-alone MzScheme (or MrEd), or through the +flag to stand-alone Racket (or GRacket), or through the @as-index{@envvar{PLTNOMZJIT}} environment variable (set to any value).} @defboolparam[load-on-demand-enabled on?]{ A parameter that determines whether the default @tech{load handler} -sets @scheme[read-on-demand-source]. See @scheme[current-load] for -more information. The default is @scheme[#t], unless it is disabled +sets @racket[read-on-demand-source]. See @racket[current-load] for +more information. The default is @racket[#t], unless it is disabled through the @Flag{d}/@DFlag{no-delay} command-line flag.} diff --git a/collects/scribblings/reference/evts.scrbl b/collects/scribblings/reference/evts.scrbl index 590309821d..8513848af3 100644 --- a/collects/scribblings/reference/evts.scrbl +++ b/collects/scribblings/reference/evts.scrbl @@ -13,7 +13,7 @@ @section-index["poll"] A @deftech{synchronizable event} (or just @defterm{event} for short) -works with the @scheme[sync] procedure to coordinate synchronization +works with the @racket[sync] procedure to coordinate synchronization among threads. Certain kinds of objects double as events, including ports and threads. Other kinds of objects exist only for their use as events. @@ -27,156 +27,156 @@ when it is ready, then the event produces a particular Synchronizing an event may affect the state of the event. For example, when synchronizing a semaphore, then the semaphore's internal count is -decremented, just as with @scheme[semaphore-wait]. For most kinds of +decremented, just as with @racket[semaphore-wait]. For most kinds of events, however (such as a port), synchronizing does not modify the event's state. -The following act as events in stand-alone MzScheme. An extension or -embedding application can extend the set of primitive events --- in -particular, an eventspace in MrEd is an event --- and new structure -types can generate events (see @scheme[prop:evt]). +The following act as events in Racket. An extension or embedding +application can extend the set of primitive events --- in particular, +an eventspace in GRacket is an event --- and new structure types can +generate events (see @racket[prop:evt]). @itemize[ - @item{@scheme[_semaphore] --- a semaphore is ready when - @scheme[semaphore-wait] would not block. @ResultItself{semaphore}.} + @item{@racket[_semaphore] --- a semaphore is ready when + @racket[semaphore-wait] would not block. @ResultItself{semaphore}.} - @item{@scheme[_semaphore-peek] --- a semaphore-peek event returned by - @scheme[semaphore-peek-evt] applied to @scheme[_semaphore] is ready - exactly when @scheme[_semaphore] is + @item{@racket[_semaphore-peek] --- a semaphore-peek event returned by + @racket[semaphore-peek-evt] applied to @racket[_semaphore] is ready + exactly when @racket[_semaphore] is ready. @ResultItself{semaphore-peek}.} - @item{@scheme[_channel] --- a channel returned by - @scheme[make-channel] is ready when @scheme[channel-get] would not + @item{@racket[_channel] --- a channel returned by + @racket[make-channel] is ready when @racket[channel-get] would not block. The channel's result as an event is the same as the - @scheme[channel-get] result.} + @racket[channel-get] result.} - @item{@scheme[_channel-put] --- an event returned by - @scheme[channel-put-evt] applied to @scheme[_channel] is ready when - @scheme[channel-put] would not block on - @scheme[_channel]. @ResultItself{channel-put}.} + @item{@racket[_channel-put] --- an event returned by + @racket[channel-put-evt] applied to @racket[_channel] is ready when + @racket[channel-put] would not block on + @racket[_channel]. @ResultItself{channel-put}.} - @item{@scheme[_input-port] --- an input port is ready as an event when - @scheme[read-byte] would not block. @ResultItself{input-port}.} + @item{@racket[_input-port] --- an input port is ready as an event when + @racket[read-byte] would not block. @ResultItself{input-port}.} - @item{@scheme[_output-port] --- an output port is ready when - @scheme[write-bytes-avail] would not block or + @item{@racket[_output-port] --- an output port is ready when + @racket[write-bytes-avail] would not block or when the port contains buffered characters and - @scheme[write-bytes-avail*] can flush part of the buffer (although - @scheme[write-bytes-avail] might block). @ResultItself{output-port}.} + @racket[write-bytes-avail*] can flush part of the buffer (although + @racket[write-bytes-avail] might block). @ResultItself{output-port}.} - @item{@scheme[_progress] --- an event produced by - @scheme[port-progress-evt] applied to @scheme[_input-port] is ready after - any subsequent read from @scheme[_input-port]. @ResultItself{progress}.} + @item{@racket[_progress] --- an event produced by + @racket[port-progress-evt] applied to @racket[_input-port] is ready after + any subsequent read from @racket[_input-port]. @ResultItself{progress}.} - @item{@scheme[_tcp-listener] --- a TCP listener is ready when - @scheme[tcp-accept] would not block. @ResultItself{listener}.} + @item{@racket[_tcp-listener] --- a TCP listener is ready when + @racket[tcp-accept] would not block. @ResultItself{listener}.} - @item{@scheme[_thd] --- a thread is ready when @scheme[thread-wait] + @item{@racket[_thd] --- a thread is ready when @racket[thread-wait] would not block. @ResultItself{thread}.} - @item{@scheme[_thread-dead] --- an event returned by - @scheme[thread-dead-evt] applied to @scheme[thd] is ready when - @scheme[thd] has terminated. @ResultItself{thread-dead}.} + @item{@racket[_thread-dead] --- an event returned by + @racket[thread-dead-evt] applied to @racket[thd] is ready when + @racket[thd] has terminated. @ResultItself{thread-dead}.} - @item{@scheme[_thread-resume] --- an event returned by - @scheme[thread-resume-evt] applied to @scheme[thd] is ready when - @scheme[thd] subsequently resumes execution (if it was not already - running). The event's result is @scheme[thd].} + @item{@racket[_thread-resume] --- an event returned by + @racket[thread-resume-evt] applied to @racket[thd] is ready when + @racket[thd] subsequently resumes execution (if it was not already + running). The event's result is @racket[thd].} - @item{@scheme[_thread-suspend] --- an event returned by - @scheme[thread-suspend-evt] applied to @scheme[thd] is ready when - @scheme[thd] subsequently suspends execution (if it was not already - suspended). The event's result is @scheme[thd].} + @item{@racket[_thread-suspend] --- an event returned by + @racket[thread-suspend-evt] applied to @racket[thd] is ready when + @racket[thd] subsequently suspends execution (if it was not already + suspended). The event's result is @racket[thd].} - @item{@scheme[_alarm] --- an event returned by @scheme[alarm-evt] is + @item{@racket[_alarm] --- an event returned by @racket[alarm-evt] is ready after a particular date and time. @ResultItself{alarm}.} - @item{@scheme[_subprocess] --- a subprocess is ready when - @scheme[subprocess-wait] would not block. + @item{@racket[_subprocess] --- a subprocess is ready when + @racket[subprocess-wait] would not block. @ResultItself{subprocess}.} - @item{@scheme[_will-executor] --- a will executor is ready when - @scheme[will-execute] would not block. + @item{@racket[_will-executor] --- a will executor is ready when + @racket[will-execute] would not block. @ResultItself{will-executor}.} - @item{@scheme[_udp] --- an event returned by @scheme[udp-send-evt] or - @scheme[udp-receive!-evt] is ready when a send or receive on the + @item{@racket[_udp] --- an event returned by @racket[udp-send-evt] or + @racket[udp-receive!-evt] is ready when a send or receive on the original socket would block, respectively. @ResultItself{udp}.} - @item{@scheme[_log-receiver] --- a @tech{log receiver} as produced by - @scheme[make-log-receiver] is ready when a logged message is + @item{@racket[_log-receiver] --- a @tech{log receiver} as produced by + @racket[make-log-receiver] is ready when a logged message is available. The event's result is a vector, as described with - @scheme[make-log-receiver].} + @racket[make-log-receiver].} - @item{@scheme[_choice] --- an event returned by @scheme[choice-evt] is - ready when one or more of the @scheme[_evt]s supplied to - @scheme[choice-evt] are ready. If the choice event is chosen, one of - its ready @scheme[_evt]s is chosen pseudo-randomly, and the result is - the chosen @scheme[_evt]'s result.} + @item{@racket[_choice] --- an event returned by @racket[choice-evt] is + ready when one or more of the @racket[_evt]s supplied to + @racket[choice-evt] are ready. If the choice event is chosen, one of + its ready @racket[_evt]s is chosen pseudo-randomly, and the result is + the chosen @racket[_evt]'s result.} - @item{@scheme[_wrap] --- an event returned by @scheme[wrap-evt] - applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is - ready. The event's result is obtained by a call to @scheme[_proc] (with - breaks disabled) on the result of @scheme[evt].} + @item{@racket[_wrap] --- an event returned by @racket[wrap-evt] + applied to @racket[_evt] and @racket[_proc] is ready when @racket[_evt] is + ready. The event's result is obtained by a call to @racket[_proc] (with + breaks disabled) on the result of @racket[evt].} - @item{@scheme[_handle] --- an event returned by @scheme[handle-evt] - applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is - ready. The event's result is obtained by a tail call to @scheme[_proc] on - the result of @scheme[_evt].} + @item{@racket[_handle] --- an event returned by @racket[handle-evt] + applied to @racket[_evt] and @racket[_proc] is ready when @racket[_evt] is + ready. The event's result is obtained by a tail call to @racket[_proc] on + the result of @racket[_evt].} - @item{@elemtag["guard-evt"]{@scheme[_guard]} --- an event returned by @scheme[guard-evt] applied - to @scheme[_thunk] generates a new event every time that @scheme[_guard] is - used with @scheme[sync] (or whenever it is part of a choice event - used with @scheme[sync], etc.); the generated event is the result of - calling @scheme[_thunk] when the synchronization begins; if @scheme[_thunk] - returns a non-event, then @scheme[_thunk]'s result is replaced with an - event that is ready and whose result is @scheme[_guard].} + @item{@elemtag["guard-evt"]{@racket[_guard]} --- an event returned by @racket[guard-evt] applied + to @racket[_thunk] generates a new event every time that @racket[_guard] is + used with @racket[sync] (or whenever it is part of a choice event + used with @racket[sync], etc.); the generated event is the result of + calling @racket[_thunk] when the synchronization begins; if @racket[_thunk] + returns a non-event, then @racket[_thunk]'s result is replaced with an + event that is ready and whose result is @racket[_guard].} - @item{@elemtag["nack-guard-evt"]{@scheme[_nack-guard]} --- an event - returned by @scheme[nack-guard-evt] applied to @scheme[_proc] - generates a new event every time that @scheme[_nack-guard] is used - with @scheme[sync] (or whenever it is part of a choice event used - with @scheme[sync], etc.); the generated event is the result of - calling @scheme[_proc] with a NACK (``negative acknowledgment'') event - when the synchronization begins; if @scheme[_proc] returns a - non-event, then @scheme[_proc]'s result is replaced with an event that - is ready and whose result is @scheme[_nack-guard]. + @item{@elemtag["nack-guard-evt"]{@racket[_nack-guard]} --- an event + returned by @racket[nack-guard-evt] applied to @racket[_proc] + generates a new event every time that @racket[_nack-guard] is used + with @racket[sync] (or whenever it is part of a choice event used + with @racket[sync], etc.); the generated event is the result of + calling @racket[_proc] with a NACK (``negative acknowledgment'') event + when the synchronization begins; if @racket[_proc] returns a + non-event, then @racket[_proc]'s result is replaced with an event that + is ready and whose result is @racket[_nack-guard]. - If the event from @scheme[_proc] is not ultimately chosen as the - unblocked event, then the NACK event supplied to @scheme[_proc] + If the event from @racket[_proc] is not ultimately chosen as the + unblocked event, then the NACK event supplied to @racket[_proc] becomes ready with a @|void-const| value. This NACK event becomes ready when the event is abandoned because some other event is chosen, because the synchronizing thread is dead, or because control escaped - from the call to @scheme[sync] (even if @scheme[_nack-guard]'s @scheme[_proc] - has not yet returned a value). If the event returned by @scheme[_proc] is + from the call to @racket[sync] (even if @racket[_nack-guard]'s @racket[_proc] + has not yet returned a value). If the event returned by @racket[_proc] is chosen, then the NACK event never becomes ready.} - @item{@elemtag["poll-guard-evt"]{@scheme[_poll-guard]} --- an event - returned by @scheme[poll-guard-evt] applied to @scheme[_proc] - generates a new event every time that @scheme[poll-guard] is used - with @scheme[sync] (or whenever it is part of a choice event used - with @scheme[sync], etc.); the generated event is the result of - calling @scheme[_proc] with a boolean: @scheme[#t] if the event will - be used for a poll, @scheme[#f] for a blocking synchronization. + @item{@elemtag["poll-guard-evt"]{@racket[_poll-guard]} --- an event + returned by @racket[poll-guard-evt] applied to @racket[_proc] + generates a new event every time that @racket[poll-guard] is used + with @racket[sync] (or whenever it is part of a choice event used + with @racket[sync], etc.); the generated event is the result of + calling @racket[_proc] with a boolean: @racket[#t] if the event will + be used for a poll, @racket[#f] for a blocking synchronization. - If @scheme[#t] is supplied to @scheme[_proc], if breaks are disabled, if + If @racket[#t] is supplied to @racket[_proc], if breaks are disabled, if the polling thread is not terminated, and if polling the resulting event produces a result, the event will certainly be chosen for its result.} - @item{@scheme[_struct] --- a structure whose type has the - @scheme[prop:evt] property identifies/generates an event through the + @item{@racket[_struct] --- a structure whose type has the + @racket[prop:evt] property identifies/generates an event through the property.} - @item{@scheme[always-evt] --- a constant event that is always - ready. @ResultItself{@scheme[always-evt]}.} + @item{@racket[always-evt] --- a constant event that is always + ready. @ResultItself{@racket[always-evt]}.} - @item{@scheme[never-evt] --- a constant event that is never ready.} + @item{@racket[never-evt] --- a constant event that is never ready.} - @item{@elemtag["system-idle-evt"]{@scheme[_idle]} --- an event - produced by @scheme[system-idle-evt] is ready when, if this event - were replaced by @scheme[never-evt], no thread in the system would + @item{@elemtag["system-idle-evt"]{@racket[_idle]} --- an event + produced by @racket[system-idle-evt] is ready when, if this event + were replaced by @racket[never-evt], no thread in the system would be available to run. In other words, all threads must be suspended or blocked on events with timeouts that have not yet expired. The event's result is @|void-const|.} @@ -187,20 +187,20 @@ types can generate events (see @scheme[prop:evt]). @defproc[(evt? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{synchronizable event}, -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @tech{synchronizable event}, +@racket[#f] otherwise.} @defproc[(sync [evt evt?] ...+) any]{ Blocks as long as none of the @tech{synchronizable events} -@scheme[evt]s are ready, as defined above. +@racket[evt]s are ready, as defined above. -When at least one @scheme[evt] is ready, its @tech{synchronization -result} (often @scheme[evt] itself) is returned. If multiple -@scheme[evt]s are ready, one of the @scheme[evt]s is chosen +When at least one @racket[evt] is ready, its @tech{synchronization +result} (often @racket[evt] itself) is returned. If multiple +@racket[evt]s are ready, one of the @racket[evt]s is chosen pseudo-randomly for the result; the -@scheme[current-evt-pseudo-random-generator] parameter sets the +@racket[current-evt-pseudo-random-generator] parameter sets the random-number generator that controls this choice.} @@ -208,23 +208,23 @@ random-number generator that controls this choice.} [evt evt?] ...+) any]{ -Like @scheme[sync], but returns @scheme[#f] if @scheme[timeout-secs] -is not @scheme[#f] and if @scheme[timeout-secs] seconds pass without a +Like @racket[sync], but returns @racket[#f] if @racket[timeout-secs] +is not @racket[#f] and if @racket[timeout-secs] seconds pass without a successful synchronization. -If @scheme[timeout-secs] is @scheme[0], each @scheme[evt] is checked -at least once, so a @scheme[timeout-secs] value of @scheme[0] can be +If @racket[timeout-secs] is @racket[0], each @racket[evt] is checked +at least once, so a @racket[timeout-secs] value of @racket[0] can be used for polling. -See also @scheme[alarm-evt] for an alternative timeout mechanism.} +See also @racket[alarm-evt] for an alternative timeout mechanism.} @defproc[(sync/enable-break [evt evt?] ...+) any]{ -Like @scheme[sync], but breaking is enabled (see -@secref["breakhandler"]) while waiting on the @scheme[evt]s. If -breaking is disabled when @scheme[sync/enable-break] is called, then -either all @scheme[evt]s remain unchosen or the @scheme[exn:break] +Like @racket[sync], but breaking is enabled (see +@secref["breakhandler"]) while waiting on the @racket[evt]s. If +breaking is disabled when @racket[sync/enable-break] is called, then +either all @racket[evt]s remain unchosen or the @racket[exn:break] exception is raised, but not both.} @@ -232,34 +232,34 @@ exception is raised, but not both.} [evt evt?] ...+) any]{ -Like @scheme[sync/enable-break], but with a timeout in seconds (or -@scheme[#f]), as for @scheme[sync/timeout].} +Like @racket[sync/enable-break], but with a timeout in seconds (or +@racket[#f]), as for @racket[sync/timeout].} @defproc[(choice-evt [evt evt?] ...) evt?]{ Creates and returns a single event that combines the -@scheme[evt]s. Supplying the result to @scheme[sync] is the same as -supplying each @scheme[evt] to the same call.} +@racket[evt]s. Supplying the result to @racket[sync] is the same as +supplying each @racket[evt] to the same call.} @defproc[(wrap-evt [evt (and/c evt? (not/c handle-evt?))] [wrap (any/c . -> . any)]) evt?]{ -Creates an event that is in a ready when @scheme[evt] is ready, but -whose result is determined by applying @scheme[wrap] to the result of -@scheme[evt]. The call to @scheme[wrap] is -@scheme[parameterize-break]ed to disable breaks initially. The -@scheme[evt] cannot be an event created by @scheme[handle-evt] or any -combination of @scheme[choice-evt] involving an event from -@scheme[handle-evt].} +Creates an event that is in a ready when @racket[evt] is ready, but +whose result is determined by applying @racket[wrap] to the result of +@racket[evt]. The call to @racket[wrap] is +@racket[parameterize-break]ed to disable breaks initially. The +@racket[evt] cannot be an event created by @racket[handle-evt] or any +combination of @racket[choice-evt] involving an event from +@racket[handle-evt].} @defproc[(handle-evt [evt (and/c evt? (not/c handle-evt?))] [handle (any/c . -> . any)]) evt?]{ -Like @scheme[wrap], except that @scheme[handle] is called in tail +Like @racket[wrap], except that @racket[handle] is called in tail position with respect to the synchronization request, and without breaks explicitly disabled.} @@ -293,27 +293,27 @@ itself as its result.} @defproc[(system-idle-evt) evt?]{Returns an event that is ready when the system is otherwise idle; see @elemref["system-idle-evt"]{the overview} for more information. The result of the -@scheme[system-idle-evt] procedure is always the same event.} +@racket[system-idle-evt] procedure is always the same event.} @defproc[(alarm-evt [msecs nonnegative-number?]) evt]{ Returns a synchronizable event that is not ready when -@scheme[(current-inexact-milliseconds)] would return a value that is -less than @scheme[msecs], and it is ready when -@scheme[(current-inexact-milliseconds)] would return a value that is -more than @scheme[msecs].} +@racket[(current-inexact-milliseconds)] would return a value that is +less than @racket[msecs], and it is ready when +@racket[(current-inexact-milliseconds)] would return a value that is +more than @racket[msecs].} @defproc[(handle-evt? [evt evt?]) boolean?]{ -Returns @scheme[#t] if @scheme[evt] was created by @scheme[handle-evt] -or by @scheme[choice-evt] applied to another event for which -@scheme[handle-evt?] produces @scheme[#t]. Such events are illegal as -an argument to @scheme[handle-evt] or @scheme[wrap-evt], because they -cannot be wrapped further. For any other event, @scheme[handle-evt?] -produces @scheme[#f], and the event is a legal argument to -@scheme[handle-evt] or @scheme[wrap-evt] for further wrapping.} +Returns @racket[#t] if @racket[evt] was created by @racket[handle-evt] +or by @racket[choice-evt] applied to another event for which +@racket[handle-evt?] produces @racket[#t]. Such events are illegal as +an argument to @racket[handle-evt] or @racket[wrap-evt], because they +cannot be wrapped further. For any other event, @racket[handle-evt?] +produces @racket[#f], and the event is a legal argument to +@racket[handle-evt] or @racket[wrap-evt] for further wrapping.} @;------------------------------------------------------------------------ @defthing[prop:evt struct-type-property?]{ @@ -324,16 +324,16 @@ A @tech{structure type property} that identifies structure types whose @itemize[ - @item{An event @scheme[_evt]: In this case, using the structure as an - event is equivalent to using @scheme[_evt].} + @item{An event @racket[_evt]: In this case, using the structure as an + event is equivalent to using @racket[_evt].} - @item{A procedure @scheme[_proc] of one argument: In this case, the + @item{A procedure @racket[_proc] of one argument: In this case, the structure is similar to an event generated - by @scheme[guard-evt], except that the would-be guard - procedure @scheme[_proc] receives the structure as an argument, instead + by @racket[guard-evt], except that the would-be guard + procedure @racket[_proc] receives the structure as an argument, instead of no arguments.} - @item{An exact, non-negative integer between @scheme[0] (inclusive) + @item{An exact, non-negative integer between @racket[0] (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields): The integer identifies a field in the structure, and the field must be designated as @@ -344,14 +344,14 @@ A @tech{structure type property} that identifies structure types whose ] -Instances of a structure type with the @scheme[prop:input-port] or -@scheme[prop:output-port] property are also synchronizable by virtue +Instances of a structure type with the @racket[prop:input-port] or +@racket[prop:output-port] property are also synchronizable by virtue of being a port. If the structure type has more than one of -@scheme[prop:evt], @scheme[prop:input-port], and -@scheme[prop:output-port], then the @scheme[prop:evt] value (if any) +@racket[prop:evt], @racket[prop:input-port], and +@racket[prop:output-port], then the @racket[prop:evt] value (if any) takes precedence for determing the instance's behavior as an event, -and the @scheme[prop:input-port] property takes precedence over -@scheme[prop:output-port] for synchronization. +and the @racket[prop:input-port] property takes precedence over +@racket[prop:output-port] for synchronization. @examples[ (define-struct wt (base val) @@ -376,4 +376,4 @@ and the @scheme[prop:input-port] property takes precedence over @defparam[current-evt-pseudo-random-generator generator pseudo-random-generator?]{ A parameter that determines the pseudo-random number generator used by -@scheme[sync] for events created by @scheme[choice-evt].} +@racket[sync] for events created by @racket[choice-evt].} diff --git a/collects/scribblings/reference/exit.scrbl b/collects/scribblings/reference/exit.scrbl index ac0f1d933c..7e17cebd80 100644 --- a/collects/scribblings/reference/exit.scrbl +++ b/collects/scribblings/reference/exit.scrbl @@ -5,7 +5,7 @@ @defproc[(exit [v any/c #t]) any]{ -Passes @scheme[v] to the current @tech{exit handler}. If the exit +Passes @racket[v] to the current @tech{exit handler}. If the exit handler does not escape or terminate the thread, @|void-const| is returned.} @@ -13,11 +13,11 @@ returned.} @defparam[exit-handler proc (any/c . -> . any)]{ A parameter that determines the current @deftech{exit handler}. The -@tech{exit handler} is called by @scheme[exit]. +@tech{exit handler} is called by @racket[exit]. -The default @tech{exit handler} in the @exec{mzscheme} executable -takes any argument and shuts down the OS-level Scheme process. The +The default @tech{exit handler} in the Racket executable +takes any argument and shuts down the OS-level Racket process. The argument is used as the OS-level exit code if it is an exact integer -between @scheme[1] and @scheme[255] (which normally means -``failure''); otherwise, the exit code is @scheme[0], (which normally +between @racket[1] and @racket[255] (which normally means +``failure''); otherwise, the exit code is @racket[0], (which normally means ``success'').} diff --git a/collects/scribblings/reference/exns.scrbl b/collects/scribblings/reference/exns.scrbl index 5e00b7d9af..3571170366 100644 --- a/collects/scribblings/reference/exns.scrbl +++ b/collects/scribblings/reference/exns.scrbl @@ -5,42 +5,42 @@ @title[#:tag "exns"]{Exceptions} -See @secref["exn-model"] for information on the PLT Scheme exception +See @secref["exn-model"] for information on the Racket exception model. It is based on a proposal by Friedman, Haynes, and Dybvig @cite["Friedman95"]. -Whenever a primitive error occurs in PLT Scheme, an exception is +Whenever a primitive error occurs in Racket, an exception is raised. The value that is passed to the current @tech{exception handler} for a primitive error is always an instance of the -@scheme[exn] structure type. Every @scheme[exn] structure value has a -@scheme[message] field that is a string, the primitive error message. +@racket[exn] structure type. Every @racket[exn] structure value has a +@racket[message] field that is a string, the primitive error message. The default exception handler recognizes exception values with the -@scheme[exn?] predicate and passes the error message to the current -@tech{error display handler} (see @scheme[error-display-handler]). +@racket[exn?] predicate and passes the error message to the current +@tech{error display handler} (see @racket[error-display-handler]). Primitive procedures that accept a procedure argument with a -particular required arity (e.g., @scheme[call-with-input-file], -@scheme[call/cc]) check the argument's arity immediately, raising -@scheme[exn:fail:contract] if the arity is incorrect. +particular required arity (e.g., @racket[call-with-input-file], +@racket[call/cc]) check the argument's arity immediately, raising +@racket[exn:fail:contract] if the arity is incorrect. @;------------------------------------------------------------------------ @section[#:tag "errorproc"]{Raising Exceptions} @defproc[(raise [v any/c][barrier? any/c #t]) any]{ -Raises an exception, where @scheme[v] represents the exception being -raised. The @scheme[v] argument can be anything; it is passed to the +Raises an exception, where @racket[v] represents the exception being +raised. The @racket[v] argument can be anything; it is passed to the current @tech{exception handler}. -If @scheme[barrier?] is true, then the call to the @tech{exception +If @racket[barrier?] is true, then the call to the @tech{exception handler} is protected by a @tech{continuation barrier}, so that multiple returns/escapes are impossible. All exceptions raised by -@schememodname[scheme] functions effectively use @scheme[raise] with a -@scheme[#t] value for @scheme[barrier?]. +@racketmodname[racket] functions effectively use @racket[raise] with a +@racket[#t] value for @racket[barrier?]. Breaks are disabled from the time the exception is raised until the exception handler obtains control, and the handler itself is -@scheme[parameterize-break]ed to disable breaks initially; see +@racket[parameterize-break]ed to disable breaks initially; see @secref["breakhandler"] for more information on breaks. @examples[ @@ -60,73 +60,73 @@ exception handler obtains control, and the handler itself is [(error [msg string?][v any/c] ...) any] [(error [src symbol?][frmat string?][v any/c] ...) any])]{ -Raises the exception @scheme[exn:fail], which contains an error +Raises the exception @racket[exn:fail], which contains an error 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].} + @item{@racket[(error sym)] creates a message string by concatenating + @racket["error: "] with the string form of @racket[sym].} - @item{@scheme[(error msg v ...)] creates a message string by - concatenating @scheme[msg] with string versions of the @scheme[v]s + @item{@racket[(error msg v ...)] creates a message string by + concatenating @racket[msg] with string versions of the @racket[v]s (as produced by the current error value conversion handler; see - @scheme[error-value->string-handler]). A space is inserted before - each @scheme[v].} + @racket[error-value->string-handler]). A space is inserted before + each @racket[v].} - @item{@scheme[(error src frmat v ...)] creates a + @item{@racket[(error src frmat v ...)] creates a message string equivalent to the string created by - @schemeblock[ + @racketblock[ (format (string-append "~s: " frmat) src v ...) ]} ] In all cases, the constructed message string is passed to -@scheme[make-exn:fail], and the resulting exception is raised. +@racket[make-exn:fail], and the resulting exception is raised. @examples[ (error 'failed) (error "failed" 23 'pizza (list 1 2 3)) -(error 'failed "~a failed because ~a" 'method-a "no argument supplied") +(error 'method-a "failed because ~a" "no argument supplied") ]} @defproc*[([(raise-user-error [sym symbol?]) any] [(raise-user-error [msg string?][v any/c] ...) any] [(raise-user-error [src symbol?][format string?][v any/c] ...) any])]{ -Like @scheme[error], but constructs an exception with -@scheme[make-exn:fail:user] instead of @scheme[make-exn:fail]. The +Like @racket[error], but constructs an exception with +@racket[make-exn:fail:user] instead of @racket[make-exn:fail]. The default @tech{error display handler} does not show a ``stack trace'' for -@scheme[exn:fail:user] exceptions (see @secref["contmarks"]), so -@scheme[raise-user-error] should be used for errors that are intended +@racket[exn:fail:user] exceptions (see @secref["contmarks"]), so +@racket[raise-user-error] should be used for errors that are intended for end users. @examples[ (raise-user-error 'failed) (raise-user-error "failed" 23 'pizza (list 1 2 3)) -(raise-user-error 'failed "~a failed because ~a" 'method-a "no argument supplied") +(raise-user-error 'method-a "failed because ~a" "no argument supplied") ]} @defproc*[([(raise-type-error [name symbol?][expected string?][v any/c]) any] [(raise-type-error [name symbol?][expected string?][bad-pos exact-nonnegative-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 +Creates an @racket[exn:fail:contract] value and @racket[raise]s it as +an exception. The @racket[name] argument is used as the source +procedure's name in the error message. The @racket[expected] argument is used as a description of the expected type. -In the first form, @scheme[v] is the value received by the procedure +In the first form, @racket[v] is the value received by the procedure that does not have the expected type. In the second form, the bad argument is indicated by an index -@scheme[bad-pos] (counting from @math{0}), and all of the original -arguments @scheme[v] are provided (in order). The resulting error +@racket[bad-pos] (counting from @math{0}), and all of the original +arguments @racket[v] are provided (in order). The resulting error message names the bad argument and also lists the other arguments. If -@scheme[bad-pos] is not less than the number of @scheme[v]s, the +@racket[bad-pos] is not less than the number of @racket[v]s, the @exnraise[exn:fail:contract]. @examples[ @@ -144,13 +144,13 @@ message names the bad argument and also lists the other arguments. If @defproc[(raise-mismatch-error [name symbol?][message string?][v any/c]) any]{ -Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as -an exception. The @scheme[name] is used as the source procedure's -name in the error message. The @scheme[message] is the error -message. The @scheme[v] argument is the improper argument received by -the procedure. The printed form of @scheme[v] is appended to -@scheme[message] (using the error value conversion handler; see -@scheme[error-value->string-handler]).} +Creates an @racket[exn:fail:contract] value and @racket[raise]s it as +an exception. The @racket[name] is used as the source procedure's +name in the error message. The @racket[message] is the error +message. The @racket[v] argument is the improper argument received by +the procedure. The printed form of @racket[v] is appended to +@racket[message] (using the error value conversion handler; see +@racket[error-value->string-handler]).} @defproc[(raise-arity-error [name (or/c symbol? procedure?)] [arity-v (or/c exact-nonnegative-integer? @@ -161,22 +161,22 @@ the procedure. The printed form of @scheme[v] is appended to [arg-v any/c #f] ...) any]{ -Creates an @scheme[exn:fail:contract:arity] value and @scheme[raise]s -it as an exception. The @scheme[name] is used for the source +Creates an @racket[exn:fail:contract:arity] value and @racket[raise]s +it as an exception. The @racket[name] is used for the source procedure's name in the error message. -The @scheme[arity-v] value must -be a possible result from @scheme[procedure-arity], except -that it does not have to be normalized (see @scheme[procedure-arity?] for -the details of normalized arities); @scheme[raise-arity-error] +The @racket[arity-v] value must +be a possible result from @racket[procedure-arity], except +that it does not have to be normalized (see @racket[procedure-arity?] for +the details of normalized arities); @racket[raise-arity-error] will normalize the arity and used the normalized form in the error message. -If @scheme[name-symbol-or-procedure] is a procedure, its actual arity is +If @racket[name-symbol-or-procedure] is a procedure, its actual arity is ignored. -The @scheme[arg-v] arguments are the actual supplied +The @racket[arg-v] arguments are the actual supplied arguments, which are shown in the error message (using the error value -conversion handler; see @scheme[error-value->string-handler]); also, -the number of supplied @scheme[arg-v]s is explicitly mentioned in the +conversion handler; see @racket[error-value->string-handler]); also, +the number of supplied @racket[arg-v]s is explicitly mentioned in the message.} @defproc[(raise-syntax-error [name (or/c symbol? #f)] @@ -186,50 +186,50 @@ message.} [extra-sources (listof syntax?) null]) any]{ -Creates an @scheme[exn:fail:syntax] value and @scheme[raise]s it as an +Creates an @racket[exn:fail:syntax] value and @racket[raise]s it as an exception. Macros use this procedure to report syntax errors. -The @scheme[name] argument is usually @scheme[#f] when @scheme[expr] +The @racket[name] argument is usually @racket[#f] when @racket[expr] is provided; it is described in more detail below. The -@scheme[message] is used as the main body of the error message. +@racket[message] is used as the main body of the error message. -The optional @scheme[expr] argument is the erroneous source syntax -object or S-expression (but the expression @scheme[#f] cannot be +The optional @racket[expr] argument is the erroneous source syntax +object or S-expression (but the expression @racket[#f] cannot be represented by itself; it must be wrapped as a @tech{syntax -object}). The optional @scheme[sub-expr] argument is a syntax object -or S-expression (again, @scheme[#f] cannot represent itself) within -@scheme[expr] that more precisely locates the error. Both may appear +object}). The optional @racket[sub-expr] argument is a syntax object +or S-expression (again, @racket[#f] cannot represent itself) within +@racket[expr] that more precisely locates the error. Both may appear in the generated error-message text if -@scheme[error-print-source-location] is @scheme[#t]. Source location +@racket[error-print-source-location] is @racket[#t]. Source location information in the error-message text is similarly extracted from -@scheme[sub-expr] or @scheme[expr] when at least one is a syntax -object and @scheme[error-print-source-location] is @scheme[#t]. +@racket[sub-expr] or @racket[expr] when at least one is a syntax +object and @racket[error-print-source-location] is @racket[#t]. -If @scheme[sub-expr] is provided and not @scheme[#f], it is used (in -syntax form) for the @scheme[exprs] field of the generated exception -record, else the @scheme[expr] is used if provided and not -@scheme[#f]. In either case, the syntax object is @scheme[cons]ed onto -@scheme[extra-sources] to produce the @scheme[exprs] field, or -@scheme[extra-sources] is used directly for @scheme[exprs] if neither -@scheme[expr] nor @scheme[sub-expr] is provided and not @scheme[#f]. +If @racket[sub-expr] is provided and not @racket[#f], it is used (in +syntax form) for the @racket[exprs] field of the generated exception +record, else the @racket[expr] is used if provided and not +@racket[#f]. In either case, the syntax object is @racket[cons]ed onto +@racket[extra-sources] to produce the @racket[exprs] field, or +@racket[extra-sources] is used directly for @racket[exprs] if neither +@racket[expr] nor @racket[sub-expr] is provided and not @racket[#f]. The form name used in the generated error message is determined -through a combination of the @scheme[name], @scheme[expr], and -@scheme[sub-expr] arguments: +through a combination of the @racket[name], @racket[expr], and +@racket[sub-expr] arguments: @itemize[ - @item{When @scheme[name] is @scheme[#f], and when @scheme[expr] is + @item{When @racket[name] is @racket[#f], and when @racket[expr] is either an identifier or a syntax pair containing an identifier as its first element, then the form name from the error message is the identifier's symbol.} - @item{When @scheme[name] is @scheme[#f] and when @scheme[expr] is not + @item{When @racket[name] is @racket[#f] and when @racket[expr] is not an identifier or a syntax pair containing and identifier as its first element, then the form name in the error message is - @scheme["?"].} + @racket["?"].} - @item{@scheme[symbol]: When @scheme[name] is a symbol, then the symbol + @item{@racket[symbol]: When @racket[name] is a symbol, then the symbol is used as the form name in the generated error message.} ]} @@ -239,48 +239,48 @@ through a combination of the @scheme[name], @scheme[expr], and @defproc[(call-with-exception-handler [f (any/c . -> . any)][thunk (-> any)]) any]{ -Installs @scheme[f] as the @tech{exception handler} for the -@tech{dynamic extent} of the call to @scheme[thunk]. If an exception -is raised during the evaluation of @scheme[thunk] (in an extension of +Installs @racket[f] as the @tech{exception handler} for the +@tech{dynamic extent} of the call to @racket[thunk]. If an exception +is raised during the evaluation of @racket[thunk] (in an 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 normally extended +handler), then @racket[f] is applied to the @racket[raise]d value in +the continuation of the @racket[raise] call (but normally extended with a @tech{continuation barrier}; see @secref["prompt-model"] and -@scheme[raise]). +@racket[raise]). 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 -handler (still in the dynamic extent of the call to @scheme[raise], +the exception handler returns a value when invoked by @racket[raise], +then @racket[raise] propagates the value to the ``previous'' exception +handler (still in the dynamic extent of the call to @racket[raise], and under the same barrier, if any). The previous exception handler is the exception handler associated with the rest of the continuation after the point where the called exception handler was associated with the continuation; if no previous handler is available, the uncaught-exception handler is used (see below). In all cases, a call -to an exception handler is @scheme[parameterize-break]ed to disable -breaks, and it is wrapped with @scheme[call-with-exception-handler] to +to an exception handler is @racket[parameterize-break]ed to disable +breaks, and it is wrapped with @racket[call-with-exception-handler] to install the an exception handler that reports both the original and newly raised exceptions.} @defparam[uncaught-exception-handler f (any/c . -> . any)]{ A @tech{parameter} that determines an exception handler used by -@scheme[raise] when the relevant continuation has no exception handler -installed with @scheme[call-with-exception-handler] or -@scheme[with-handlers]. Unlike exception handlers installed with -@scheme[call-with-exception-handler], the handler for uncaught -exceptions must not return a value when called by @scheme[raise]; if +@racket[raise] when the relevant continuation has no exception handler +installed with @racket[call-with-exception-handler] or +@racket[with-handlers]. Unlike exception handlers installed with +@racket[call-with-exception-handler], the handler for uncaught +exceptions must not return a value when called by @racket[raise]; if it returns, an exception is raised (to be handled by an exception handler that reports both the original and newly raised exception). The default uncaught-exception handler prints an error message using -the current @tech{error display handler} (see @scheme[error-display-handler]) +the current @tech{error display handler} (see @racket[error-display-handler]) and then escapes by calling the current error escape handler (see -@scheme[error-escape-handler]). The call to each handler is -@scheme[parameterize]d to set @scheme[error-display-handler] to the -default @tech{error display handler}, and it is @scheme[parameterize-break]ed +@racket[error-escape-handler]). The call to each handler is +@racket[parameterize]d to set @racket[error-display-handler] to the +default @tech{error display handler}, and it is @racket[parameterize-break]ed to disable breaks. The call to the error escape handler is further -parameterized to set @scheme[error-escape-handler] to the default +parameterized to set @racket[error-escape-handler] to the default error escape handler. When the current @tech{error display handler} is the default handler, then the @@ -291,35 +291,35 @@ fails.} @defform[(with-handlers ([pred-expr handler-expr] ...) body ...+)]{ -Evaluates each @scheme[pred-expr] and and @scheme[handler-expr] in the -order that they are specified, and then evaluates the @scheme[body]s +Evaluates each @racket[pred-expr] and and @racket[handler-expr] in the +order that they are specified, and then evaluates the @racket[body]s with a new exception handler during the its dynamic extent. The new exception handler processes an exception only if one of the -@scheme[pred-expr] procedures returns a true value when applied to the +@racket[pred-expr] procedures returns a true value when applied to the exception, otherwise the exception handler is invoked from the -continuation of the @scheme[with-handlers] expression (by raising the +continuation of the @racket[with-handlers] expression (by raising the exception again). If an exception is handled by one of the -@scheme[handler-expr] procedures, the result of the entire -@scheme[with-handlers] expression is the return value of the handler. +@racket[handler-expr] procedures, the result of the entire +@racket[with-handlers] expression is the return value of the handler. -When an exception is raised during the evaluation of @scheme[body]s, -each predicate procedure @scheme[pred-expr] is applied to the +When an exception is raised during the evaluation of @racket[body]s, +each predicate procedure @racket[pred-expr] is applied to the exception value; if a predicate returns a true value, the -corresponding @scheme[handler-expr] procedure is invoked with the +corresponding @racket[handler-expr] procedure is invoked with the exception as an argument. The predicates are tried in the order that they are specified. Before any predicate or handler procedure is invoked, the continuation -of the entire @scheme[with-handlers] expression is restored, but also -@scheme[parameterize-break]ed to disable breaks. Thus, breaks are +of the entire @racket[with-handlers] expression is restored, but also +@racket[parameterize-break]ed to disable breaks. Thus, breaks are disabled by default during the predicate and handler procedures (see @secref["breakhandler"]), and the exception handler is the one from -the continuation of the @scheme[with-handlers] expression. +the continuation of the @racket[with-handlers] expression. -The @scheme[exn:fail?] procedure is useful as a handler predicate to -catch all error exceptions. Avoid using @scheme[(lambda (x) #t)] as a -predicate, because the @scheme[exn:break] exception typically should +The @racket[exn:fail?] procedure is useful as a handler predicate to +catch all error exceptions. Avoid using @racket[(lambda (x) #t)] as a +predicate, because the @racket[exn:break] exception typically should not be caught (unless it will be re-raised to cooperatively break). Beware, also, of catching and discarding exceptions, because discarding an error message can make debugging unnecessarily @@ -328,9 +328,9 @@ difficult.} @defform[(with-handlers* ([pred-expr handler-expr] ...) body ...+)]{ -Like @scheme[with-handlers], but if a @scheme[handler-expr] procedure +Like @racket[with-handlers], but if a @racket[handler-expr] procedure is called, breaks are not explicitly disabled, and the handler call is -in tail position with respect to the @scheme[with-handlers*] form.} +in tail position with respect to the @racket[with-handlers*] form.} @;------------------------------------------------------------------------ @section{Configuring Default Handling} @@ -340,21 +340,21 @@ in tail position with respect to the @scheme[with-handlers*] form.} A parameter for the @deftech{error escape handler}, which takes no arguments and escapes from the dynamic context of an exception. The default error escape handler escapes using -@scheme[(abort-current-continuation (default-continuation-prompt-tag) +@racket[(abort-current-continuation (default-continuation-prompt-tag) void)]. The error escape handler is normally called directly by an exception handler, in a @tech{parameterization} that sets the @tech{error display handler} and @tech{error escape handler} to the default -handlers, and it is normally @scheme[parameterize-break]ed to disable +handlers, and it is normally @racket[parameterize-break]ed to disable breaks. To escape from a run-time error in a different context, use -@scheme[raise] or @scheme[error]. +@racket[raise] or @racket[error]. Due to a @tech{continuation barrier} around exception-handling calls, an error escape handler cannot invoke a full continuation that was created prior to the exception, but it can abort to a prompt (see -@scheme[call-with-continuation-prompt]) or invoke an escape -continuation (see @scheme[call-with-escape-continuation]).} +@racket[call-with-continuation-prompt]) or invoke an escape +continuation (see @racket[call-with-escape-continuation]).} @defparam[error-display-handler proc (string? any/c . -> . any)]{ @@ -364,24 +364,24 @@ exception value. More generally, the handler's first argument is a string to print as an error message, and the second is a value representing a raised exception. -The default error display handler @scheme[display]s its first argument +The default error display handler @racket[display]s its first argument to the current error port (determined by the -@scheme[current-error-port] parameter) and extracts a stack trace (see -@scheme[continuation-mark-set->context]) to display from the second -argument if it is an @scheme[exn] value but not an -@scheme[exn:fail:user] value. +@racket[current-error-port] parameter) and extracts a stack trace (see +@racket[continuation-mark-set->context]) to display from the second +argument if it is an @racket[exn] value but not an +@racket[exn:fail:user] value. -@margin-note{The default error display handler in DrScheme also uses +@margin-note{The default error display handler in DrRacket also uses the second argument to highlight source locations.} -To report a run-time error, use @scheme[raise] or procedures like -@scheme[error], instead of calling the error display handler +To report a run-time error, use @racket[raise] or procedures like +@racket[error], instead of calling the error display handler directly.} @defparam[error-print-width width (and exact-integer? (>=/c 3))]{ A parameter whose value is used as the maximum number of characters -used to print a Scheme value that is embedded in a primitive error +used to print a Racket value that is embedded in a primitive error message.} @defparam[error-print-context-length cnt exact-nonnegative-integer?]{ @@ -389,35 +389,35 @@ message.} A parameter whose value is used by the default @tech{error display handler} as the maximum number of lines of context (or ``stack trace'') to print; a single ``...'' line is printed if more lines are available -after the first @scheme[cnt] lines. A @scheme[0] value for -@scheme[cnt] disables context printing entirely.} +after the first @racket[cnt] lines. A @racket[0] value for +@racket[cnt] disables context printing entirely.} @defparam[error-value->string-handler proc (any/c exact-nonnegative-integer? . -> . string?)]{ A parameter that determines the @deftech{error value conversion -handler}, which is used to print a Scheme value that is embedded in a +handler}, which is used to print a Racket value that is embedded in a primitive error message. The integer argument to the handler specifies the maximum number of characters that should be used to represent the value in the resulting -string. The default error value conversion handler @scheme[print]s +string. The default error value conversion handler @racket[print]s the value into a string (using the current @tech{global port print -handler}; see @scheme[global-port-print-handler]). If the printed form +handler}; see @racket[global-port-print-handler]). If the printed form is too long, the printed form is truncated and the last three characters of the return string are set to ``...''. If the string returned by an error value conversion handler is longer than requested, the string is destructively ``truncated'' by setting the first extra position in the string to the null character. If a -non-string is returned, then the string @scheme["..."] is used. If a +non-string is returned, then the string @racket["..."] is used. If a primitive error string needs to be generated before the handler has returned, the default error value conversion handler is used. -Call to an error value conversion handler are @scheme[parameterized] +Call to an error value conversion handler are @racket[parameterized] to re-install the default error value conversion handler, and to -enable printing of unreadable values (see @scheme[print-unreadable]).} +enable printing of unreadable values (see @racket[print-unreadable]).} @defboolparam[error-print-source-location include?]{ @@ -426,9 +426,9 @@ include source information, such as the source line and column or the expression. This parameter also controls the error message when a module-defined variable is accessed before its definition is executed; the parameter determines whether the message includes a module -name. Only the message field of an @scheme[exn:fail:read], -@scheme[exn:fail:syntax], or @scheme[exn:fail:contract:variable] -structure is affected by the parameter. The default is @scheme[#t].} +name. Only the message field of an @racket[exn:fail:read], +@racket[exn:fail:syntax], or @racket[exn:fail:contract:variable] +structure is affected by the parameter. The default is @racket[#t].} @;------------------------------------------------------------------------ @section{Built-in Exception Types} @@ -437,16 +437,16 @@ structure is affected by the parameter. The default is @scheme[#t].} [continuation-marks continuation-mark-set?]) #:inspector #f]{ -The base @tech{structure type} for exceptions. The @scheme[message] -field contains an error message, and the @scheme[continuation-marks] -field contains the value produced by @scheme[(current-continuation-marks)] +The base @tech{structure type} for exceptions. The @racket[message] +field contains an error message, and the @racket[continuation-marks] +field contains the value produced by @racket[(current-continuation-marks)] immediately before the exception was raised.} @defstruct[(exn:fail exn) () #:inspector #f]{ Raised for exceptions that represent errors, as opposed to -@scheme[exn:break].} +@racket[exn:break].} @defstruct[(exn:fail:contract exn:fail) () @@ -468,7 +468,7 @@ Raised for division by exact zero.} @defstruct[(exn:fail:contract:non-fixnum-result exn:fail:contract) () #:inspector #f]{ -Raised by functions like @scheme[fx+] when the result would not be a fixnum.} +Raised by functions like @racket[fx+] when the result would not be a fixnum.} @defstruct[(exn:fail:contract:continuation exn:fail:contract) () #:inspector #f]{ @@ -485,27 +485,27 @@ or @tech{module-level variable}.} @defstruct[(exn:fail:syntax exn:fail) ([exprs (listof syntax?)]) #:inspector #f]{ -Raised for a syntax error that is not a @scheme[read] error. The -@scheme[exprs] indicate the relevant source expressions, +Raised for a syntax error that is not a @racket[read] error. The +@racket[exprs] indicate the relevant source expressions, least-specific to most-specific.} @defstruct[(exn:fail:read exn:fail) ([srclocs (listof srcloc?)]) #:inspector #f]{ -Raised for a @scheme[read] error. The @scheme[srclocs] indicate the +Raised for a @racket[read] error. The @racket[srclocs] indicate the relevant source expressions.} @defstruct[(exn:fail:read:eof exn:fail:read) () #:inspector #f]{ -Raised for a @scheme[read] error, specifically when the error is due +Raised for a @racket[read] error, specifically when the error is due to an unexpected end-of-file.} @defstruct[(exn:fail:read:non-char exn:fail:read) () #:inspector #f]{ -Raised for a @scheme[read] error, specifically when the error is due +Raised for a @racket[read] error, specifically when the error is due to an unexpected non-character (i.e., ``special'') element in the input stream.} @@ -556,32 +556,32 @@ context when printing the error message.} #:inspector #f]{ Raised asynchronously (when enabled) in response to a break request. -The @scheme[continuation] field can be used by a handler to resume the +The @racket[continuation] field can be used by a handler to resume the interrupted computation.} @defthing[prop:exn:srclocs struct-type-property?]{ A property that identifies structure types that provide a list of -@scheme[srcloc] values. The property is normally attached to structure +@racket[srcloc] values. The property is normally attached to structure types used to represent exception information. The property value must be a procedure that accepts a single value---the structure type instance from which to extract source -locations---and returns a list of @scheme[srcloc]s. Some @tech{error +locations---and returns a list of @racket[srcloc]s. Some @tech{error display handlers} use only the first returned location.} @defproc[(exn:srclocs? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] has the @scheme[prop:exn:srclocs] -property, @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] has the @racket[prop:exn:srclocs] +property, @racket[#f] otherwise.} @defproc[(exn:srclocs-accessor [v exn:srclocs?]) (exn:srclocs? . -> . (listof srcloc))]{ -Returns the @scheme[srcloc]-getting procedure associated with @scheme[v].} +Returns the @racket[srcloc]-getting procedure associated with @racket[v].} @defstruct[srcloc ([source any/c] @@ -591,23 +591,23 @@ Returns the @scheme[srcloc]-getting procedure associated with @scheme[v].} [span (or/c exact-nonnegative-integer? #f)]) #:inspector #f]{ -The fields of an @scheme[srcloc] instance are as follows: +The fields of an @racket[srcloc] instance are as follows: @itemize[ - @item{@scheme[source] --- An arbitrary value identifying the source, + @item{@racket[source] --- An arbitrary value identifying the source, often a path (see @secref["pathutils"]).} - @item{@scheme[line] --- The line number (counts from 1) or - @scheme[#f] (unknown).} + @item{@racket[line] --- The line number (counts from 1) or + @racket[#f] (unknown).} - @item{@scheme[column] --- The column number (counts from 0) or - @scheme[#f] (unknown).} + @item{@racket[column] --- The column number (counts from 0) or + @racket[#f] (unknown).} - @item{@scheme[position] --- The starting position (counts from 1) or - @scheme[#f] (unknown).} + @item{@racket[position] --- The starting position (counts from 1) or + @racket[#f] (unknown).} - @item{@scheme[span] --- The number of covered positions (counts from - 0) or @scheme[#f] (unknown).} + @item{@racket[span] --- The number of covered positions (counts from + 0) or @racket[#f] (unknown).} ]} diff --git a/collects/scribblings/reference/file-ports.scrbl b/collects/scribblings/reference/file-ports.scrbl index b93002bcfc..eec76b0c28 100644 --- a/collects/scribblings/reference/file-ports.scrbl +++ b/collects/scribblings/reference/file-ports.scrbl @@ -36,11 +36,11 @@ @title[#:tag "file-ports"]{File Ports} -A port created by @scheme[open-input-file], @scheme[open-output-file], -@scheme[subprocess], and related functions is a @deftech{file-stream -port}. The initial input, output, and error ports in stand-alone -MzScheme are also file-stream ports. The @scheme[file-stream-port?] -predicate recognizes file-stream ports. +A port created by @racket[open-input-file], @racket[open-output-file], +@racket[subprocess], and related functions is a @deftech{file-stream +port}. The initial input, output, and error ports in @exec{racket} +are also file-stream ports. The @racket[file-stream-port?] predicate +recognizes file-stream ports. When an input or output file-stream port is created, it is placed into the management of the current custodian (see @@ -50,16 +50,16 @@ the management of the current custodian (see [#:mode mode-flag (or/c 'binary 'text) 'binary]) input-port?]{ -Opens the file specified by @scheme[path] for input. The -@scheme[mode-flag] argument specifies how the file's bytes are +Opens the file specified by @racket[path] for input. The +@racket[mode-flag] argument specifies how the file's bytes are translated on input: @itemize[ - @item{@indexed-scheme['binary] --- bytes are returned from the port + @item{@indexed-racket['binary] --- bytes are returned from the port exactly as they are read from the file.} - @item{@indexed-scheme['text] --- return and linefeed bytes (10 and + @item{@indexed-racket['text] --- return and linefeed bytes (10 and 13) as read from the file are filtered by the port in a platform specific manner: @@ -74,25 +74,25 @@ translated on input: ]} ] -Under Windows, @scheme['text] mode works only with regular files; -attempting to use @scheme['text] with other kinds of files triggers an -@scheme[exn:fail:filesystem] exception. +Under Windows, @racket['text] mode works only with regular files; +attempting to use @racket['text] with other kinds of files triggers an +@racket[exn:fail:filesystem] exception. -Otherwise, the file specified by @scheme[path] need not be a regular +Otherwise, the file specified by @racket[path] need not be a regular file. It might a device that is connected through the filesystem, such as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. In all cases, the port is buffered by default. -The port produced by @scheme[open-input-file] should be explicitly -closed, either though @scheme[close-input-port] or indirectly via -@scheme[custodian-shutdown-all], to release the OS-level file +The port produced by @racket[open-input-file] should be explicitly +closed, either though @racket[close-input-port] or indirectly via +@racket[custodian-shutdown-all], to release the OS-level file handle. The input port will not be closed automatically if it is otherwise available for garbage collection (see @secref["gc-model"]); a @tech{will} could be associated input port to close it more automatically (see @secref["willexecutor"]). A @tech{path} value that is the @tech{cleanse}d version of -@scheme[path] is used as the name of the opened port. +@racket[path] is used as the name of the opened port. @file-examples[ ;; put some text in a file @@ -110,79 +110,79 @@ A @tech{path} value that is the @tech{cleanse}d version of 'must-truncate 'truncate/replace) 'error]) output-port?]{ -Opens the file specified by @scheme[path] for output. The -@scheme[mode-flag] argument specifies how bytes written to the port +Opens the file specified by @racket[path] for output. The +@racket[mode-flag] argument specifies how bytes written to the port are translated when written to the file: @itemize[ - @item{@scheme['binary] --- bytes are written to the file exactly + @item{@racket['binary] --- bytes are written to the file exactly as written to the port.} - @item{@scheme['text] --- under Windows, a linefeed byte (10) written + @item{@racket['text] --- under Windows, a linefeed byte (10) written to the port is translated to a return-linefeed combination in the file; no filtering occurs for returns.} ] -Under Windows, @scheme['text] mode works only with regular files; -attempting to use @scheme['text] with other kinds of files triggers an -@scheme[exn:fail:filesystem] exception. +Under Windows, @racket['text] mode works only with regular files; +attempting to use @racket['text] with other kinds of files triggers an +@racket[exn:fail:filesystem] exception. -The @scheme[exists-flag] argument specifies how to handle/require +The @racket[exists-flag] argument specifies how to handle/require files that already exist: @itemize[ - @item{@indexed-scheme['error] --- raise @scheme[exn:fail:filesystem] + @item{@indexed-racket['error] --- raise @racket[exn:fail:filesystem] if the file exists.} - @item{@indexed-scheme['replace] --- remove the old file, if it + @item{@indexed-racket['replace] --- remove the old file, if it exists, and write a new one.} - @item{@indexed-scheme['truncate] --- remove all old data, if the file + @item{@indexed-racket['truncate] --- remove all old data, if the file exists.} - @item{@indexed-scheme['must-truncate] --- remove all old data in an + @item{@indexed-racket['must-truncate] --- remove all old data in an existing file; if the file does not exist, the @exnraise[exn:fail:filesystem].} - @item{@indexed-scheme['truncate/replace] --- try @scheme['truncate]; + @item{@indexed-racket['truncate/replace] --- try @racket['truncate]; if it fails (perhaps due to file permissions), try - @scheme['replace].} + @racket['replace].} - @item{@indexed-scheme['update] --- open an existing file without + @item{@indexed-racket['update] --- open an existing file without truncating it; if the file does not exist, the - @exnraise[exn:fail:filesystem]. Use @scheme[file-position] + @exnraise[exn:fail:filesystem]. Use @racket[file-position] to change the current read/write position.} - @item{@indexed-scheme['can-update] --- open an existing file without + @item{@indexed-racket['can-update] --- open an existing file without truncating it, or create the file if it does not exist.} - @item{@indexed-scheme['append] --- append to the end of the file, + @item{@indexed-racket['append] --- append to the end of the file, whether it already exists or not; under Windows, - @scheme['append] is equivalent to @scheme['update], except that + @racket['append] is equivalent to @racket['update], except that the file is not required to exist, and the file position is immediately set to the end of the file after opening it.} ] -The file specified by @scheme[path] need not be a regular file. It +The file specified by @racket[path] need not be a regular file. It might a device that is connected through the filesystem, such as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. The output port is block-buffered by default, unless the file corresponds to a terminal, in which case is it line buffered bu default. -The port produced by @scheme[open-output-port] should be explicitly -closed, either though @scheme[close-output-port] or indirectly via -@scheme[custodian-shutdown-all], to release the OS-level file +The port produced by @racket[open-output-port] should be explicitly +closed, either though @racket[close-output-port] or indirectly via +@racket[custodian-shutdown-all], to release the OS-level file handle. The output port will not be closed automatically if it is otherwise available for garbage collection (see @secref["gc-model"]); a @tech{will} could be associated input port to close it more automatically (see @secref["willexecutor"]). A @tech{path} value that is the @tech{cleanse}d version of -@scheme[path] is used as the name of the opened port. +@racket[path] is used as the name of the opened port. @file-examples[ (define out (open-output-file some-file)) @@ -196,7 +196,7 @@ A @tech{path} value that is the @tech{cleanse}d version of 'replace 'truncate 'truncate/replace) 'error]) (values input-port? output-port?)]{ -Like @scheme[open-output-file], but producing two values: an input +Like @racket[open-output-file], but producing two values: an input port and an output port. The two ports are connected in that they share the underlying file device. This procedure is intended for use with special devices that can be opened by only one process, such as @@ -204,18 +204,18 @@ with special devices that can be opened by only one process, such as confusing. For example, using one port does not automatically flush the other port's buffer, and reading or writing in one port moves the file position (if any) for the other port. For regular files, use -separate @scheme[open-input-file] and @scheme[open-output-file] calls +separate @racket[open-input-file] and @racket[open-output-file] calls to avoid confusion.} @defproc[(call-with-input-file [path path-string?] [proc (input-port? . -> . any)] [#:mode mode-flag (or/c 'binary 'text) 'binary]) any]{ -Calls @scheme[open-input-file] with the @scheme[path] and -@scheme[mode-flag] arguments, and passes the resulting port -to @scheme[proc]. The result of @scheme[proc] is the result of the -@scheme[call-with-input-file] call, but the newly opened port is closed -when @scheme[thunk] return. +Calls @racket[open-input-file] with the @racket[path] and +@racket[mode-flag] arguments, and passes the resulting port +to @racket[proc]. The result of @racket[proc] is the result of the +@racket[call-with-input-file] call, but the newly opened port is closed +when @racket[thunk] return. @file-examples[ (with-output-to-file some-file @@ -230,9 +230,9 @@ when @scheme[thunk] return. [#:exists exists-flag (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) any]{ -Analogous to @scheme[call-with-input-file], but passing @scheme[path], -@scheme[mode-flag] and @scheme[exists-flag] to -@scheme[open-output-file]. +Analogous to @racket[call-with-input-file], but passing @racket[path], +@racket[mode-flag] and @racket[exists-flag] to +@racket[open-output-file]. @file-examples[ (call-with-output-file some-file @@ -247,9 +247,9 @@ Analogous to @scheme[call-with-input-file], but passing @scheme[path], [proc (input-port? . -> . any)] [#:mode mode-flag (or/c 'binary 'text) 'binary]) any]{ -Like @scheme[call-with-input-file], but the newly opened port is +Like @racket[call-with-input-file], but the newly opened port is closed whenever control escapes the dynamic extent of the -@scheme[call-with-input-file*] call, whether through @scheme[proc]'s +@racket[call-with-input-file*] call, whether through @racket[proc]'s return, a continuation application, or a prompt-based abort.} @defproc[(call-with-output-file* [path path-string?] @@ -258,19 +258,19 @@ return, a continuation application, or a prompt-based abort.} [#:exists exists-flag (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) any]{ -Like @scheme[call-with-output-file], but the newly opened port is +Like @racket[call-with-output-file], but the newly opened port is closed whenever control escapes the dynamic extent of the -@scheme[call-with-output-file*] call, whether through @scheme[proc]'s +@racket[call-with-output-file*] call, whether through @racket[proc]'s return, a continuation application, or a prompt-based abort.} @defproc[(with-input-from-file [path path-string?] [thunk (-> any)] [#:mode mode-flag (or/c 'binary 'text) 'binary]) any]{ -Like @scheme[call-with-input-file*], but instead of passing the newly +Like @racket[call-with-input-file*], but instead of passing the newly opened port to the given procedure argument, the port is installed as -the current input port (see @scheme[current-input-port]) using -@scheme[parameterize] around the call to @scheme[thunk]. +the current input port (see @racket[current-input-port]) using +@racket[parameterize] around the call to @racket[thunk]. @file-examples[ (with-output-to-file some-file @@ -285,10 +285,10 @@ the current input port (see @scheme[current-input-port]) using [#:exists exists-flag (or/c 'error 'append 'update 'replace 'truncate 'truncate/replace) 'error]) any]{ -Like @scheme[call-with-output-file*], but instead of passing the newly +Like @racket[call-with-output-file*], but instead of passing the newly opened port to the given procedure argument, the port is installed as -the current output port (see @scheme[current-output-port]) using -@scheme[parameterize] around the call to @scheme[thunk]. +the current output port (see @racket[current-output-port]) using +@racket[parameterize] around the call to @racket[thunk]. @file-examples[ (with-output-to-file some-file @@ -301,14 +301,14 @@ the current output port (see @scheme[current-output-port]) using @index['("inode")]{Returns} a number that represents the identity of the device and file read or written by -@scheme[port]. For two ports whose open times overlap, the -result of @scheme[port-file-identity] is the same for both ports if +@racket[port]. For two ports whose open times overlap, the +result of @racket[port-file-identity] is the same for both ports if and only if the ports access the same device and file. For ports whose open times do not overlap, no guarantee can be provided for the port identities (even if the ports actually access the same file)---except as can be inferred through relationships with other ports. If -@scheme[port] is closed, the @exnraise[exn:fail]. Under -Windows 95, 98, and Me, if @scheme[port] is connected to a +@racket[port] is closed, the @exnraise[exn:fail]. Under +Windows 95, 98, and Me, if @racket[port] is connected to a pipe instead of a file, the @exnraise[exn:fail:filesystem]. @file-examples[ diff --git a/collects/scribblings/reference/filesystem.scrbl b/collects/scribblings/reference/filesystem.scrbl index ad259aa6de..42056c0fc8 100644 --- a/collects/scribblings/reference/filesystem.scrbl +++ b/collects/scribblings/reference/filesystem.scrbl @@ -64,19 +64,19 @@ by @racket[kind], which must be one of the following: if it is defined, otherwise it is the current directory.} @item{@indexed-racket['init-dir] --- the directory containing the - initialization file used by stand-alone @exec{mzracket} executable. + initialization file used by the Racket executable. It is the same as the current user's home directory.} @item{@indexed-racket['init-file] --- the file loaded at start-up by - the stand-alone @exec{mzracket} executable. The directory part of the + the Racket executable. The directory part of the path is the same path as returned for @racket['init-dir]. The file name is platform-specific: @itemize[ - @item{@|AllUnix|: @indexed-file{.mzracketrc}} + @item{@|AllUnix|: @indexed-file{.racketrc}} - @item{Windows: @indexed-file{mzracketrc.rkt}} + @item{Windows: @indexed-file{racketrc.rkt}} ]} @@ -109,7 +109,7 @@ by @racket[kind], which must be one of the following: operating system for Windows. Under @|AllUnix|, the result is @racket["/"].} - @item{@indexed-racket['exec-file] --- the path of the @exec{mzracket} + @item{@indexed-racket['exec-file] --- the path of the Racket executable as provided by the operating system for the current invocation. @@ -119,10 +119,10 @@ by @racket[kind], which must be one of the following: @item{@indexed-racket['run-file] --- the path of the current executable; this may be different from result for @racket['exec-file] because an alternate path was provided through a - @DFlag{name} or @Flag{N} command-line flag to the @exec{mzracket} - (or @exec{mred}) executable, or because an embedding executable + @DFlag{name} or @Flag{N} command-line flag to the Racket + (or GRacket) executable, or because an embedding executable installed an alternate path. In particular a ``launcher'' script - created by @racket[make-mzracket-launcher] sets this path to the + created by @racket[make-racket-launcher] sets this path to the script's path.} @item{@indexed-racket['collects-dir] --- a path to the main @@ -132,7 +132,7 @@ by @racket[kind], which must be one of the following: soft-link or relative to the user's executable search path, so that the two results should be combined with @racket[find-executable-path]. The @racket['collects-dir] path is - normally embedded in the @exec{mzracket} executable, but it can be + normally embedded in the Racket executable, but it can be overridden by the @DFlag{collects} or @Flag{X} command-line flag.} @item{@indexed-racket['orig-dir] --- the current directory at @@ -170,7 +170,7 @@ that the file or directory @racket[related-sub] exists in the same directory as the executable. The result is then the full path for the found @racket[related-sub], instead of the path for the executable. -This procedure is used by the @exec{mzracket} executable to find the +This procedure is used by the Racket executable to find the standard library collection directory (see @secref["collects"]). In this case, @racket[program] is the name used to start Racket and @racket[related] is @racket["collects"]. The @racket[related-sub] diff --git a/collects/scribblings/reference/futures.scrbl b/collects/scribblings/reference/futures.scrbl index b327351f0c..cf65a29323 100644 --- a/collects/scribblings/reference/futures.scrbl +++ b/collects/scribblings/reference/futures.scrbl @@ -11,35 +11,35 @@ @note-lib[racket/future] -@margin-note{Currently, parallel support for @scheme[future] is +@margin-note{Currently, parallel support for @racket[future] is enabled by default for Windows, Linux x86/x86_64, and Mac OS X x86/x86_64. To enable support for other platforms, use -@DFlag{enable-futures} with @exec{configure} when building PLT -Scheme.} +@DFlag{enable-futures} with @exec{configure} when building +Racket.} -The @scheme[future] and @scheme[touch] functions from -@schememodname[racket/future] provide access to parallelism as +The @racket[future] and @racket[touch] functions from +@racketmodname[racket/future] provide access to parallelism as supported by the hardware and operation system. -In contrast to @scheme[thread], which provides concurrency for -arbitrary computations without parallelism, @scheme[future] provides +In contrast to @racket[thread], which provides concurrency for +arbitrary computations without parallelism, @racket[future] provides parallelism for limited computations. A future executes its work in parallel (assuming that support for parallelism is available) until it detects an attempt to perform an operation that is too complex for the system to run safely in parallel. Similarly, work in a future is suspended if it depends in some way on the current continuation, such as raising an exception. A suspended computation for a future is -resumed when @scheme[touch] is applied to the future. +resumed when @racket[touch] is applied to the future. ``Safe'' parallel execution of a future means that all operations provided by the system must be able to enforce contracts and produce results as documented. ``Safe'' does not preclude concurrent access to mutable data that is visible in the program. For example, a -computation in a future might use @scheme[set!] to modify a shared +computation in a future might use @racket[set!] to modify a shared variable, in which case concurrent assignment to the variable can be visible in other futures and threads. Furthermore, guarantees about the visibility of effects and ordering are determined by the operating system and hardware---which rarely support, for example, the guarantee -of sequential consistency that is provided for @scheme[thread]-based +of sequential consistency that is provided for @racket[thread]-based concurrency. At the same time, operations that seem obviously safe may have a complex enough implementation internally that they cannot run in parallel. See also @guidesecref["effective-futures"]. @@ -49,16 +49,16 @@ in parallel. See also @guidesecref["effective-futures"]. @defproc[(touch [f future?]) any] )]{ - The @scheme[future] procedure returns a future value that - encapsulates @scheme[thunk]. The @scheme[touch] function forces the - evaluation of the @scheme[thunk] inside the given future, returning - the values produced by @scheme[thunk]. After @scheme[touch] forces - the evaluation of a @scheme[thunk], the resulting values are retained - by the future descriptor in place of @scheme[thunk], and additional - @scheme[touch]es of the future descriptor return those values. + The @racket[future] procedure returns a future value that + encapsulates @racket[thunk]. The @racket[touch] function forces the + evaluation of the @racket[thunk] inside the given future, returning + the values produced by @racket[thunk]. After @racket[touch] forces + the evaluation of a @racket[thunk], the resulting values are retained + by the future descriptor in place of @racket[thunk], and additional + @racket[touch]es of the future descriptor return those values. - Between a call to @scheme[future] and @scheme[touch] for a given - future, the given @scheme[thunk] may run speculatively in parallel to + Between a call to @racket[future] and @racket[touch] for a given + future, the given @racket[thunk] may run speculatively in parallel to other computations, as described above. @interaction[ @@ -69,8 +69,8 @@ in parallel. See also @guidesecref["effective-futures"]. @defproc[(future? [v any/c]) boolean?]{ - Returns @scheme[#t] if @scheme[v] is a future-descriptor value, - @scheme[#f] otherwise. + Returns @racket[#t] if @racket[v] is a future-descriptor value, + @racket[#f] otherwise. } @defproc[(processor-count) exact-positive-integer?]{ diff --git a/collects/scribblings/reference/help.scrbl b/collects/scribblings/reference/help.scrbl index bdd8bc56ab..61af750d31 100644 --- a/collects/scribblings/reference/help.scrbl +++ b/collects/scribblings/reference/help.scrbl @@ -67,8 +67,8 @@ introduces a binding without actually executing the documentation, but cannot or do not want to run the providing module. @schemeblock[ -(require racket/gui) (code:comment @#,t{does not work in @exec{mzscheme}}) -(require (for-label racket/gui)) (code:comment @#,t{ok in @exec{mzscheme}}) +(require racket/gui) (code:comment @#,t{does not work in @exec{racket}}) +(require (for-label racket/gui)) (code:comment @#,t{ok in @exec{racket}}) (help frame%) ] diff --git a/collects/scribblings/reference/init.scrbl b/collects/scribblings/reference/init.scrbl index f03e410ef8..3c178388c2 100644 --- a/collects/scribblings/reference/init.scrbl +++ b/collects/scribblings/reference/init.scrbl @@ -5,14 +5,14 @@ @title{Init Libraries} -@defmodule*/no-declare[(racket/init)]{The @schememodname[racket/init] -library is the default start-up library for MzScheme. It re-exports -the @schememodname[scheme], @schememodname[racket/enter] and -@schememodname[racket/help] libraries, and it sets -@scheme[current-print] to use @scheme[pretty-print].} +@defmodule*/no-declare[(racket/init)]{The @racketmodname[racket/init] +library is the default start-up library for Racket. It re-exports +the @racketmodname[racket], @racketmodname[racket/enter] and +@racketmodname[racket/help] libraries, and it sets +@racket[current-print] to use @racket[pretty-print].} @defmodule*/no-declare[(racket/gui/init)]{The -@schememodname[racket/gui/init] library is the default start-up -library for MrEd. It re-exports the @schememodname[racket/init] and -@schememodname[racket/gui/base] libraries, and it sets -@scheme[current-load] to use @scheme[text-editor-load-handler].} +@racketmodname[racket/gui/init] library is the default start-up +library for GRacket. It re-exports the @racketmodname[racket/init] and +@racketmodname[racket/gui/base] libraries, and it sets +@racket[current-load] to use @racket[text-editor-load-handler].} diff --git a/collects/scribblings/reference/load-lang.scrbl b/collects/scribblings/reference/load-lang.scrbl index 8dee2957d8..b2fdd0bbd9 100644 --- a/collects/scribblings/reference/load-lang.scrbl +++ b/collects/scribblings/reference/load-lang.scrbl @@ -1,30 +1,30 @@ #lang scribble/doc @(require "mz.ss") -@title[#:tag "load-lang"]{The @schememodname[racket/load] Language} +@title[#:tag "load-lang"]{The @racketmodname[racket/load] Language} @defmodulelang[racket/load] -The @schememodname[racket/load] language supports traditional Scheme -evaluation, where each top-level form in the module body is separately -passed to @scheme[eval] in the same way as for @scheme[load]. +The @racketmodname[racket/load] language supports evaluation where +each top-level form in the module body is separately passed to +@racket[eval] in the same way as for @racket[load]. The namespace for evaluation shares the @tech{module registry} with -the @schememodname[racket/load] module instance, but it has a separate +the @racketmodname[racket/load] module instance, but it has a separate top-level environment, and it is initialized with the bindings of -@schememodname[scheme]. A single namespace is created for each -instance of the @schememodname[racket/load] module (i.e., multiple -modules using the @schememodname[racket/load] language share a -namespace). The @scheme[racket/load] library exports only -@schemeidfont{#%module-begin} and @schemeidfont{#%top-interaction} +@racketmodname[racket]. A single namespace is created for each +instance of the @racketmodname[racket/load] module (i.e., multiple +modules using the @racketmodname[racket/load] language share a +namespace). The @racket[racket/load] library exports only +@racketidfont{#%module-begin} and @racketidfont{#%top-interaction} forms that effectively swap in the evaluation namespace and call -@scheme[eval]. +@racket[eval]. -For example, the body of a module using @scheme[racket/load] can -include @scheme[module] forms, so that running the following module -prints @schemeresultfont{5}: +For example, the body of a module using @racket[racket/load] can +include @racket[module] forms, so that running the following module +prints @racketresultfont{5}: -@schememod[ +@racketmod[ racket/load (module m racket/base @@ -38,22 +38,22 @@ racket/load (require 'n) ] -Definitions in a module using @scheme[racket/load] are evaluated in -the current namespace, which means that @scheme[load] and -@scheme[eval] can see the definitions. For example, running the -following module prints @schemeresultfont{6}: +Definitions in a module using @racket[racket/load] are evaluated in +the current namespace, which means that @racket[load] and +@racket[eval] can see the definitions. For example, running the +following module prints @racketresultfont{6}: -@schememod[ +@racketmod[ racket/load (define x 6) (display (eval 'x)) ] -Since all forms within a @schememodname[racket/load] module are +Since all forms within a @racketmodname[racket/load] module are evaluated in the top level, bindings cannot be exported from the -module using @scheme[provide]. Similarly, since evaluation of the +module using @racket[provide]. Similarly, since evaluation of the module-body forms is inherently dynamic, compilation of the module provides essentially no benefit. For these reasons, use -@schememodname[racket/load] for interactive exploration of top-level +@racketmodname[racket/load] for interactive exploration of top-level forms only, and not for constructing larger programs. diff --git a/collects/scribblings/reference/match-grammar.ss b/collects/scribblings/reference/match-grammar.ss index f336c52fa9..bd91127d58 100644 --- a/collects/scribblings/reference/match-grammar.ss +++ b/collects/scribblings/reference/match-grammar.ss @@ -18,6 +18,7 @@ pat ::= id @match anything, bind identifier | (CONS pat pat) @match pair of pats | (MCONS pat pat) @match mutable pair of pats | (BOX pat) @match boxed pat + | (struct-id pat ...) @match struct-id instance | (STRUCT struct-id (pat ...)) @match struct-id instance | (REGEXP rx-expr) @match string | (REGEXP rx-expr pat) @match string, result with pat diff --git a/collects/scribblings/reference/match.scrbl b/collects/scribblings/reference/match.scrbl index c07c85cf1c..316b9cf90e 100644 --- a/collects/scribblings/reference/match.scrbl +++ b/collects/scribblings/reference/match.scrbl @@ -10,8 +10,8 @@ @guideintro["match"]{pattern matching} -The @scheme[match] form and related forms support general pattern -matching on Scheme values. See also @secref["regexp"] for information +The @racket[match] form and related forms support general pattern +matching on Racket values. See also @secref["regexp"] for information on regular-expression matching on strings, bytes, and streams. @note-lib[racket/match #:use-sources (racket/match)] @@ -20,24 +20,24 @@ on regular-expression matching on strings, bytes, and streams. ([clause [pat expr ...+] [pat (=> id) expr ...+]])]{ -Finds the first @scheme[pat] that matches the result of -@scheme[val-expr], and evaluates the corresponding @scheme[expr]s with -bindings introduced by @scheme[pat] (if any). The last @scheme[expr] +Finds the first @racket[pat] that matches the result of +@racket[val-expr], and evaluates the corresponding @racket[expr]s with +bindings introduced by @racket[pat] (if any). The last @racket[expr] in the matching clause is evaluated in tail position with respect to -the @scheme[match] expression. +the @racket[match] expression. -The @scheme[clause]s are tried in order to find a match. If no -@scheme[clause] matches, then the @exnraise[exn:misc:match?]. +The @racket[clause]s are tried in order to find a match. If no +@racket[clause] matches, then the @exnraise[exn:misc:match?]. -An optional @scheme[(=> id)] between a @scheme[pat] and the -@scheme[expr]s is bound to a @defterm{failure procedure} of zero +An optional @racket[(=> id)] between a @racket[pat] and the +@racket[expr]s is bound to a @defterm{failure procedure} of zero arguments. If this procedure is invoked, it escapes back to the pattern matching expression, and resumes the matching process as if -the pattern had failed to match. The @scheme[expr]s must not mutate +the pattern had failed to match. The @racket[expr]s must not mutate the object being matched before calling the failure procedure, otherwise the behavior of matching is unpredictable. -The grammar of @scheme[pat] is as follows, where non-italicized +The grammar of @racket[pat] is as follows, where non-italicized identifiers are recognized symbolically (i.e., not by binding). @|match-grammar| @@ -46,16 +46,16 @@ In more detail, patterns match as follows: @itemize[ - @item{@scheme[_id], excluding the reserved names @schemeidfont{_}, - @schemeidfont{...}, @schemeidfont{.._}, - @schemeidfont{..}@scheme[_k], and - @schemeidfont{..}@scheme[_k] for non-negative integers - @scheme[_k] --- matches anything, and binds @scheme[id] to the - matching values. If an @scheme[_id] is used multiple times + @item{@racket[_id], excluding the reserved names @racketidfont{_}, + @racketidfont{...}, @racketidfont{.._}, + @racketidfont{..}@racket[_k], and + @racketidfont{..}@racket[_k] for non-negative integers + @racket[_k] --- matches anything, and binds @racket[id] to the + matching values. If an @racket[_id] is used multiple times within a pattern, the corresponding matches must be the same - according to @scheme[(match-equality-test)], except that - instances of an @scheme[_id] in different @schemeidfont{or} and - @schemeidfont{not} sub-patterns are independent. + according to @racket[(match-equality-test)], except that + instances of an @racket[_id] in different @racketidfont{or} and + @racketidfont{not} sub-patterns are independent. @examples[ #:eval match-eval @@ -67,7 +67,7 @@ In more detail, patterns match as follows: [(list a b c) (list c b a)]) ]} - @item{@schemeidfont{_} --- matches anything, without binding any + @item{@racketidfont{_} --- matches anything, without binding any identifiers. @examples[ @@ -76,9 +76,9 @@ In more detail, patterns match as follows: [(list _ _ a) a]) ]} - @item{@scheme[#t], @scheme[#f], @scheme[_string], @scheme[_bytes], - @scheme[_number], @scheme[_char], or @scheme[(#,(schemeidfont - "quote") _datum)] --- matches an @scheme[equal?] constant. + @item{@racket[#t], @racket[#f], @racket[_string], @racket[_bytes], + @racket[_number], @racket[_char], or @racket[(#,(racketidfont + "quote") _datum)] --- matches an @racket[equal?] constant. @examples[ #:eval match-eval @@ -87,17 +87,17 @@ In more detail, patterns match as follows: ["yes" #t]) ]} - @item{@scheme[(#,(schemeidfont "list") _lvp ...)] --- matches a list - of elements. In the case of @scheme[(#,(schemeidfont "list") + @item{@racket[(#,(racketidfont "list") _lvp ...)] --- matches a list + of elements. In the case of @racket[(#,(racketidfont "list") _pat ...)], the pattern matches a list with as many element as - @scheme[_pat]s, and each element must match the corresponding - @scheme[_pat]. In the more general case, each @scheme[_lvp] + @racket[_pat]s, and each element must match the corresponding + @racket[_pat]. In the more general case, each @racket[_lvp] corresponds to a ``spliced'' list of greedy matches. - For spliced lists, @schemeidfont{...} and @schemeidfont{___} + For spliced lists, @racketidfont{...} and @racketidfont{___} are synonyms for zero or more matches. The - @schemeidfont{..}@scheme[_k] and @schemeidfont{__}@scheme[_k] - forms are also synonyms, specifying @scheme[_k] or more + @racketidfont{..}@racket[_k] and @racketidfont{__}@racket[_k] + forms are also synonyms, specifying @racket[_k] or more matches. Pattern variables that precede these splicing operators are bound to lists of matching forms. @@ -121,11 +121,11 @@ In more detail, patterns match as follows: [_ 'else]) ]} - @item{@scheme[(#,(schemeidfont "list-rest") _lvp ... _pat)] --- - similar to a @schemeidfont{list} pattern, but the final - @scheme[_pat] matches the ``rest'' of the list after the last - @scheme[_lvp]. In fact, the matched value can be a non-list - chain of pairs (i.e., an ``improper list'') if @scheme[_pat] + @item{@racket[(#,(racketidfont "list-rest") _lvp ... _pat)] --- + similar to a @racketidfont{list} pattern, but the final + @racket[_pat] matches the ``rest'' of the list after the last + @racket[_lvp]. In fact, the matched value can be a non-list + chain of pairs (i.e., an ``improper list'') if @racket[_pat] matches non-list values. @examples[ @@ -136,9 +136,9 @@ In more detail, patterns match as follows: [(list-rest a ... d) (list a d)]) ]} - @item{@scheme[(#,(schemeidfont "list-no-order") _pat ...)] --- - similar to a @schemeidfont{list} pattern, but the elements to - match each @scheme[_pat] can appear in the list in any order. + @item{@racket[(#,(racketidfont "list-no-order") _pat ...)] --- + similar to a @racketidfont{list} pattern, but the elements to + match each @racket[_pat] can appear in the list in any order. @examples[ #:eval match-eval @@ -146,8 +146,8 @@ In more detail, patterns match as follows: [(list-no-order 3 2 x) x]) ]} - @item{@scheme[(#,(schemeidfont "list-no-order") _pat ... _lvp)] --- - generalizes @schemeidfont{list-no-order} to allow a pattern + @item{@racket[(#,(racketidfont "list-no-order") _pat ... _lvp)] --- + generalizes @racketidfont{list-no-order} to allow a pattern that matches multiple list elements that are interspersed in any order with matches for the other patterns. @@ -157,8 +157,8 @@ In more detail, patterns match as follows: [(list-no-order 6 2 y ...) y]) ]} - @item{@scheme[(#,(schemeidfont "vector") _lvp ...)] --- like a - @schemeidfont{list} pattern, but matching a vector. + @item{@racket[(#,(racketidfont "vector") _lvp ...)] --- like a + @racketidfont{list} pattern, but matching a vector. @examples[ #:eval match-eval @@ -166,8 +166,8 @@ In more detail, patterns match as follows: [(vector 1 (list a) ..3 5) a]) ]} - @item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...)] --- - similar to @schemeidfont{list-no-order}, but matching against + @item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...)] --- + similar to @racketidfont{list-no-order}, but matching against hash table's key--value pairs. @examples[ @@ -176,8 +176,8 @@ In more detail, patterns match as follows: [(hash-table ("b" b) ("a" a)) (list b a)]) ]} - @item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...+ _ooo)] - --- Generalizes @schemeidfont{hash-table} to support a final + @item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...+ _ooo)] + --- Generalizes @racketidfont{hash-table} to support a final repeating pattern. @examples[ @@ -186,7 +186,7 @@ In more detail, patterns match as follows: [(hash-table (key val) ...) key]) ]} - @item{@scheme[(#,(schemeidfont "cons") _pat1 _pat2)] --- matches a pair value. + @item{@racket[(#,(racketidfont "cons") _pat1 _pat2)] --- matches a pair value. @examples[ #:eval match-eval @@ -194,7 +194,7 @@ In more detail, patterns match as follows: [(cons a b) (+ a b)]) ]} - @item{@scheme[(#,(schemeidfont "mcons") _pat1 _pat2)] --- matches a mutable pair value. + @item{@racket[(#,(racketidfont "mcons") _pat1 _pat2)] --- matches a mutable pair value. @examples[ #:eval match-eval @@ -203,7 +203,7 @@ In more detail, patterns match as follows: [(mcons a b) 'mutable]) ]} - @item{@scheme[(#,(schemeidfont "box") _pat)] --- matches a boxed value. + @item{@racket[(#,(racketidfont "box") _pat)] --- matches a boxed value. @examples[ #:eval match-eval @@ -211,37 +211,38 @@ In more detail, patterns match as follows: [(box a) a]) ]} - @item{@scheme[(#,(schemeidfont "struct") _struct-id (_pat ...))] --- + @item{@racket[(_struct-id _pat ...)] or + @racket[(#,(racketidfont "struct") _struct-id (_pat ...))] --- matches an instance of a structure type names - @scheme[_struct-id], where each field in the instance matches - the corresponding @scheme[_pat]. + @racket[_struct-id], where each field in the instance matches + the corresponding @racket[_pat]. See also @scheme[struct*]. - Usually, @scheme[_struct-id] is defined with - @scheme[define-struct]. More generally, @scheme[_struct-id] + Usually, @racket[_struct-id] is defined with + @racket[struct]. More generally, @racket[_struct-id] must be bound to expansion-time information for a structure type (see @secref["structinfo"]), where the information includes at least a predicate binding and field accessor bindings corresponding to the number of field - @scheme[_pat]s. In particular, a module import or a - @scheme[unit] import with a signature containing a - @scheme[struct] declaration can provide the structure type + @racket[_pat]s. In particular, a module import or a + @racket[unit] import with a signature containing a + @racket[struct] declaration can provide the structure type information. @defexamples[ #:eval match-eval (define-struct tree (val left right)) (match (make-tree 0 (make-tree 1 #f #f) #f) - [(struct tree (a (struct tree (b _ _)) _)) (list a b)]) + [(tree a (tree b _ _) _) (list a b)]) ]} - @item{@scheme[(#,(schemeidfont "struct") _struct-id _)] --- - matches any instance of @scheme[_struct-id], without regard to + @item{@racket[(#,(racketidfont "struct") _struct-id _)] --- + matches any instance of @racket[_struct-id], without regard to contents of the fields of the instance. } - @item{@scheme[(#,(schemeidfont "regexp") _rx-expr)] --- matches a + @item{@racket[(#,(racketidfont "regexp") _rx-expr)] --- matches a string that matches the regexp pattern produced by - @scheme[_rx-expr]; see @secref["regexp"] for more information + @racket[_rx-expr]; see @secref["regexp"] for more information about regexps. @examples[ @@ -254,10 +255,10 @@ In more detail, patterns match as follows: [_ 'no]) ]} - @item{@scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- extends - the @schemeidfont{regexp} form to further constrain the match - where the result of @scheme[regexp-match] is matched against - @scheme[_pat]. + @item{@racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- extends + the @racketidfont{regexp} form to further constrain the match + where the result of @racket[regexp-match] is matched against + @racket[_pat]. @examples[ #:eval match-eval @@ -269,16 +270,16 @@ In more detail, patterns match as follows: [_ 'no]) ]} - @item{@scheme[(#,(schemeidfont "pregexp") _rx-expr)] or - @scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- like the - @schemeidfont{regexp} patterns, but if @scheme[_rx-expr] + @item{@racket[(#,(racketidfont "pregexp") _rx-expr)] or + @racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- like the + @racketidfont{regexp} patterns, but if @racket[_rx-expr] produces a string, it is converted to a pattern using - @scheme[pregexp] instead of @scheme[regexp].} + @racket[pregexp] instead of @racket[regexp].} - @item{@scheme[(#,(schemeidfont "and") _pat ...)] --- matches if all - of the @scheme[_pat]s match. This pattern is often used as - @scheme[(#,(schemeidfont "and") _id _pat)] to bind @scheme[_id] - to the entire value that matches @scheme[pat]. + @item{@racket[(#,(racketidfont "and") _pat ...)] --- matches if all + of the @racket[_pat]s match. This pattern is often used as + @racket[(#,(racketidfont "and") _id _pat)] to bind @racket[_id] + to the entire value that matches @racket[pat]. @examples[ #:eval match-eval @@ -286,12 +287,12 @@ In more detail, patterns match as follows: [(list _ (and a (list _ ...)) _) a]) ]} - @item{@scheme[(#,(schemeidfont "or") _pat ...)] --- matches if any of - the @scheme[_pat]s match. @bold{Beware}: the result expression - can be duplicated once for each @scheme[_pat]! Identifiers in - @scheme[_pat] are bound only in the corresponding copy of the + @item{@racket[(#,(racketidfont "or") _pat ...)] --- matches if any of + the @racket[_pat]s match. @bold{Beware}: the result expression + can be duplicated once for each @racket[_pat]! Identifiers in + @racket[_pat] are bound only in the corresponding copy of the result expression; in a module context, if the result - expression refers to a binding, then that all @scheme[_pat]s + expression refers to a binding, then that all @racket[_pat]s must include the binding. @examples[ @@ -300,8 +301,8 @@ In more detail, patterns match as follows: [(or (list a 1) (list a 2)) a]) ]} - @item{@scheme[(#,(schemeidfont "not") _pat ...)] --- matches when - none of the @scheme[_pat]s match, and binds no identifiers. + @item{@racket[(#,(racketidfont "not") _pat ...)] --- matches when + none of the @racket[_pat]s match, and binds no identifiers. @examples[ #:eval match-eval @@ -313,9 +314,9 @@ In more detail, patterns match as follows: [_ 'no]) ]} - @item{@scheme[(#,(schemeidfont "app") _expr _pat)] --- applies - @scheme[_expr] to the value to be matched; the result of the - application is matched againt @scheme[_pat]. + @item{@racket[(#,(racketidfont "app") _expr _pat)] --- applies + @racket[_expr] to the value to be matched; the result of the + application is matched againt @racket[_pat]. @examples[ #:eval match-eval @@ -323,11 +324,11 @@ In more detail, patterns match as follows: [(app length 2) 'yes]) ]} - @item{@scheme[(#,(schemeidfont "?") _expr _pat ...)] --- applies - @scheme[_expr] to the value to be matched, and checks whether - the result is a true value; the additional @scheme[_pat]s must - also match (i.e., @schemeidfont{?} combines a predicate - application and an @schemeidfont{and} pattern). + @item{@racket[(#,(racketidfont "?") _expr _pat ...)] --- applies + @racket[_expr] to the value to be matched, and checks whether + the result is a true value; the additional @racket[_pat]s must + also match (i.e., @racketidfont{?} combines a predicate + application and an @racketidfont{and} pattern). @examples[ #:eval match-eval @@ -335,10 +336,10 @@ In more detail, patterns match as follows: [(list (? odd?) ...) 'yes]) ]} - @item{@scheme[(#,(schemeidfont "quasiquote") _qp)] --- introduces a + @item{@racket[(#,(racketidfont "quasiquote") _qp)] --- introduces a quasipattern, in which identifiers match symbols. Like the - @scheme[quasiquote] expression form, @schemeidfont{unquote} - and @schemeidfont{unquote-splicing} escape back to normal + @racket[quasiquote] expression form, @racketidfont{unquote} + and @racketidfont{unquote-splicing} escape back to normal patterns. @examples[ @@ -347,8 +348,8 @@ In more detail, patterns match as follows: [`(1 ,a ,(? odd? b)) (list a b)]) ]} - @item{@scheme[_derived-pattern] --- matches a pattern defined by a - macro extension via @scheme[define-match-expander].} + @item{@racket[_derived-pattern] --- matches a pattern defined by a + macro extension via @racket[define-match-expander].} ]} @@ -358,20 +359,20 @@ In more detail, patterns match as follows: @defform[(match-lambda clause ...)]{ -Equivalent to @scheme[(lambda (id) (match id clause ...))]. +Equivalent to @racket[(lambda (id) (match id clause ...))]. } @defform[(match-lambda* clause ...)]{ -Equivalent to @scheme[(lambda lst (match lst clause ...))]. +Equivalent to @racket[(lambda lst (match lst clause ...))]. } @defform[(match-let ([pat expr] ...) body ...+)]{ -Generalizes @scheme[let] to support pattern bindings. Each -@scheme[expr] is matched against its corresponding @scheme[pat] (the -match must succeed), and the bindings that @scheme[pat] introduces are -visible in the @scheme[body]s. +Generalizes @racket[let] to support pattern bindings. Each +@racket[expr] is matched against its corresponding @racket[pat] (the +match must succeed), and the bindings that @racket[pat] introduces are +visible in the @racket[body]s. @examples[ #:eval match-eval @@ -382,9 +383,9 @@ visible in the @scheme[body]s. @defform[(match-let* ([pat expr] ...) body ...+)]{ -Like @scheme[match-let], but generalizes @scheme[let*], so that the -bindings of each @scheme[pat] are available in each subsequent -@scheme[expr]. +Like @racket[match-let], but generalizes @racket[let*], so that the +bindings of each @racket[pat] are available in each subsequent +@racket[expr]. @examples[ #:eval match-eval @@ -395,13 +396,13 @@ bindings of each @scheme[pat] are available in each subsequent @defform[(match-letrec ([pat expr] ...) body ...+)]{ -Like @scheme[match-let], but generalizes @scheme[letrec].} +Like @racket[match-let], but generalizes @racket[letrec].} @defform[(match-define pat expr)]{ -Defines the names bound by @scheme[pat] to the values produced by -matching against the result of @scheme[expr]. +Defines the names bound by @racket[pat] to the values produced by +matching against the result of @racket[expr]. @examples[ #:eval match-eval @@ -418,39 +419,41 @@ A predicate for the exception raised by in the case of a match failure. @; ---------------------------------------- -@section{Extending @scheme[match]} +@section{Extending @racket[match]} @defform*[((define-match-expander id proc-expr) (define-match-expander id proc-expr proc-expr))]{ -Binds @scheme[id] to a @deftech{match expander}. +Binds @racket[id] to a @deftech{match expander}. -The first @scheme[proc-expr] subexpression must evaluate to a - transformer that produces a @scheme[_pat] for @scheme[match]. - Whenever @scheme[id] appears as the beginning of a pattern, this +The first @racket[proc-expr] subexpression must evaluate to a + transformer that produces a @racket[_pat] for @racket[match]. + Whenever @racket[id] appears as the beginning of a pattern, this transformer is given, at expansion time, a syntax object - corresponding to the entire pattern (including @scheme[id]). The + corresponding to the entire pattern (including @racket[id]). The pattern is the replaced with the result of the transformer. -A transformer produced by a second @scheme[proc-expr] subexpression is - used when @scheme[id] is used in an expression context. Using the - second @scheme[proc-expr], @scheme[id] can be given meaning both +A transformer produced by a second @racket[proc-expr] subexpression is + used when @racket[id] is used in an expression context. Using the + second @racket[proc-expr], @racket[id] can be given meaning both inside and outside patterns.} @defparam[match-equality-test comp-proc (any/c any/c . -> . any)]{ A parameter that determines the comparison procedure used to check whether multiple uses of an identifier match the ``same'' value. The -default is @scheme[equal?].} +default is @racket[equal?].} @; ---------------------------------------------------------------------- @section{Library Extensions} @defform[(struct* struct-id ([field pat] ...))]{ - Matches an instance of a structure type named @scheme[struct-id], where the field @scheme[field] in the instance matches the corresponding @scheme[pat]. + A @scheme[match] pattern form that matches an instance of a structure + type named @racket[struct-id], where the field @racket[field] in the + instance matches the corresponding @racket[pat]. - Any field of @scheme[struct-id] may be omitted and they may occur in any order. + Any field of @racket[struct-id] may be omitted and they may occur in any order. @defexamples[ #:eval match-eval diff --git a/collects/scribblings/reference/memory.scrbl b/collects/scribblings/reference/memory.scrbl index b2fda596bd..98cbe756c4 100644 --- a/collects/scribblings/reference/memory.scrbl +++ b/collects/scribblings/reference/memory.scrbl @@ -11,28 +11,28 @@ A @deftech{weak box} is similar to a normal box (see @secref["boxes"]), but when the garbage collector (see @secref["gc-model"]) can prove that the content value of a weak box is only reachable via weak references, the content of the weak box is -replaced with @scheme[#f]. A @defterm{@tech{weak reference}} is a +replaced with @racket[#f]. A @defterm{@tech{weak reference}} is a reference through a weak box, through a key reference in a weak hash table (see @secref["hashtables"]), through a value in an ephemeron -where the value can be replaced by @scheme[#f] (see +where the value can be replaced by @racket[#f] (see @secref["ephemerons"]), or through a custodian (see @secref["custodians"]). @defproc[(make-weak-box [v any/c]) weak-box?]{ -Returns a new weak box that initially contains @scheme[v].} +Returns a new weak box that initially contains @racket[v].} @defproc[(weak-box-value [weak-box weak-box?]) any]{ -Returns the value contained in @scheme[weak-box]. If the garbage +Returns the value contained in @racket[weak-box]. If the garbage collector has proven that the previous content value of -@scheme[weak-box] was reachable only through a weak reference, then -@scheme[#f] is returned.} +@racket[weak-box] was reachable only through a weak reference, then +@racket[#f] is returned.} @defproc[(weak-box? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a weak box, @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a weak box, @racket[#f] otherwise.} @;------------------------------------------------------------------------ @section[#:tag "ephemerons"]{Ephemerons} @@ -44,7 +44,7 @@ An @deftech{ephemeron} is similar to a weak box (see @item{an ephemeron contains a key and a value; the value can be extracted from the ephemeron, but the value is replaced - by @scheme[#f] when the automatic memory manager can prove that + by @racket[#f] when the automatic memory manager can prove that either the ephemeron or the key is reachable only through weak references (see @secref["weakbox"]); and} @@ -65,20 +65,20 @@ key. @defproc[(make-ephemeron [key any/c][v any/c]) ephemeron?]{ -Returns a new @tech{ephemeron} whose key is @scheme[key] and whose -value is initially @scheme[v].} +Returns a new @tech{ephemeron} whose key is @racket[key] and whose +value is initially @racket[v].} @defproc[(ephemeron-value [ephemeron ephemeron?]) any]{ -Returns the value contained in @scheme[ephemeron]. If the garbage -collector has proven that the key for @scheme[ephemeron] is only -weakly reachable, then the result is @scheme[#f].} +Returns the value contained in @racket[ephemeron]. If the garbage +collector has proven that the key for @racket[ephemeron] is only +weakly reachable, then the result is @racket[#f].} @defproc[(ephemeron? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is an @tech{ephemeron}, @scheme[#f] +Returns @racket[#t] if @racket[v] is an @tech{ephemeron}, @racket[#f] otherwise.} @;------------------------------------------------------------------------ @@ -94,7 +94,7 @@ executors. A @tech{will} is useful for triggering clean-up actions on data associated with an unreachable value, such as closing a port embedded in an object when the object is no longer used. -Calling the @scheme[will-execute] or @scheme[will-try-execute] +Calling the @racket[will-execute] or @racket[will-try-execute] procedure executes a will that is ready in the specified will executor. Wills are not executed automatically, because certain programs need control to avoid race conditions. However, a program can @@ -113,7 +113,7 @@ the values are reachable from each other. A will executor's register is held non-weakly until after the corresponding will procedure is executed. Thus, if the content value of a weak box (see @secref["weakbox"]) is registered with a will -executor, the weak box's content is not changed to @scheme[#f] until +executor, the weak box's content is not changed to @racket[#f] until all wills have been executed for the value and the value has been proven again reachable through only weak references. @@ -125,34 +125,34 @@ Returns a new will executor with no managed values.} @defproc[(will-executor? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a will executor, @scheme[#f] +Returns @racket[#t] if @racket[v] is a will executor, @racket[#f] otherwise.} @defproc[(will-register [executor will-executor?][v any/c][proc (any/c . -> . any)]) void?]{ -Registers the value @scheme[v] with the will procedure @scheme[proc] -in the will executor @scheme[executor]. When @scheme[v] is proven -unreachable, then the procedure @scheme[proc] is ready to be called -with @scheme[v] as its argument via @scheme[will-execute] or -@scheme[will-try-execute]. The @scheme[proc] argument is strongly +Registers the value @racket[v] with the will procedure @racket[proc] +in the will executor @racket[executor]. When @racket[v] is proven +unreachable, then the procedure @racket[proc] is ready to be called +with @racket[v] as its argument via @racket[will-execute] or +@racket[will-try-execute]. The @racket[proc] argument is strongly referenced until the will procedure is executed.} @defproc[(will-execute [executor will-executor?]) any]{ Invokes the will procedure for a single ``unreachable'' value -registered with the executor @scheme[executable]. The values returned -by the will procedure are the result of the @scheme[will-execute] +registered with the executor @racket[executable]. The values returned +by the will procedure are the result of the @racket[will-execute] call. If no will is ready for immediate execution, -@scheme[will-execute] blocks until one is ready.} +@racket[will-execute] blocks until one is ready.} @defproc[(will-try-execute [executor any/c]) any]{ -Like @scheme[will-execute] if a will is ready for immediate -execution. Otherwise, @scheme[#f] is returned.} +Like @racket[will-execute] if a will is ready for immediate +execution. Otherwise, @racket[#f] is returned.} @;------------------------------------------------------------------------ @section[#:tag "garbagecollection"]{Garbage Collection} @@ -163,22 +163,22 @@ Forces an immediate garbage collection. Some effectively unreachable data may remain uncollected, because the collector cannot prove that it is unreachable. -The @scheme[collect-garbage] procedure provides some control over the +The @racket[collect-garbage] procedure provides some control over the timing of collections, but garbage will obviously be collected even if this procedure is never called.} @defproc[(current-memory-use [cust custodian? #f]) exact-nonnegative-integer?]{ Returns an estimate of the number of bytes of memory occupied by -reachable data from @scheme[cust]. (The estimate is calculated +reachable data from @racket[cust]. (The estimate is calculated @italic{without} performing an immediate garbage collection; performing a collection generally decreases the number returned by -@scheme[current-memory-use].) If @scheme[cust] is not provided, the +@racket[current-memory-use].) If @racket[cust] is not provided, the estimate is a total reachable from any custodians. -When PLT Scheme is compiled without support for memory accounting, the +When Racket is compiled without support for memory accounting, the estimate is the same (i.e., all memory) for any individual custodian; -see also @scheme[custodian-memory-accounting-available?].} +see also @racket[custodian-memory-accounting-available?].} @defproc[(dump-memory-stats) any]{ diff --git a/collects/scribblings/reference/mpairs.scrbl b/collects/scribblings/reference/mpairs.scrbl index ccd5631f43..3ccfefbce3 100644 --- a/collects/scribblings/reference/mpairs.scrbl +++ b/collects/scribblings/reference/mpairs.scrbl @@ -1,12 +1,12 @@ #lang scribble/doc @(require "mz.ss" - scribble/scheme + scribble/racket (for-label racket/mpair)) @title[#:tag "mpairs"]{Mutable Pairs and Lists} -A @deftech{mutable pair} is like a pair created by @scheme[cons], but -it supports @scheme[set-mcar!] and @scheme[set-mcdr!] mutation +A @deftech{mutable pair} is like a pair created by @racket[cons], but +it supports @racket[set-mcar!] and @racket[set-mcdr!] mutation operations to change the parts of the mutable pair (like traditional Lisp and Scheme pairs). @@ -23,31 +23,31 @@ always better choices. @; ---------------------------------------- @section{Mutable Pair Constructors and Selectors} -@defproc[(mpair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is -a @tech{mutable pair}, @scheme[#f] otherwise.} +@defproc[(mpair? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] is +a @tech{mutable pair}, @racket[#f] otherwise.} @defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated @tech{mutable pair} whose first -element is @scheme[a] and second element is @scheme[d].} +element is @racket[a] and second element is @racket[d].} @defproc[(mcar [p mpair?]) any/c]{Returns the first element of the -@tech{mutable pair} @scheme[p].} +@tech{mutable pair} @racket[p].} @defproc[(mcdr [p mpair?]) any/c]{Returns the second element of the -@tech{mutable pair} @scheme[p].} +@tech{mutable pair} @racket[p].} @defproc[(set-mcar! [p mpair?] [v any/v]) void?]{ -Changes the @tech{mutable pair} @scheme[p] so that its first element is -@scheme[v].} +Changes the @tech{mutable pair} @racket[p] so that its first element is +@racket[v].} @defproc[(set-mcdr! [p mpair?] [v any/v]) void?]{ -Changes the @tech{mutable pair} @scheme[p] so that its second element is -@scheme[v].} +Changes the @tech{mutable pair} @racket[p] so that its second element is +@racket[v].} @; ---------------------------------------- @section{Mutable List Functions} @@ -58,127 +58,127 @@ For functions described in this section, contracts are not directly enforced. In particular, when a @tech{mutable list} is expected, supplying any other kind of value (or mutating a value that starts as a @tech{mutable list}) tends to produce an exception from -@scheme[mcar] or @scheme[mcdr]. +@racket[mcar] or @racket[mcdr]. -@defproc[(mlist? [v any/c]) boolean?]{Returns @scheme[#t] if - @scheme[v] is a @tech{mutable list}: either the empty list, or a +@defproc[(mlist? [v any/c]) boolean?]{Returns @racket[#t] if + @racket[v] is a @tech{mutable list}: either the empty list, or a @tech{mutable pair} whose second element is a @tech{mutable list}.} @defproc[(mlist [v any/c] ...) mlist?]{Returns a newly allocated -@tech{mutable list} containing the @scheme[v]s as its elements.} +@tech{mutable list} containing the @racket[v]s as its elements.} @defproc[(list->mlist [lst list?]) mlist?]{ Returns a newly allocated @tech{mutable list} with the same elements as -@scheme[lst].} +@racket[lst].} @defproc[(mlist->list [mlst mlist?]) list?]{ Returns a newly allocated @tech{mutable list} with the same elements as -@scheme[nlst].} +@racket[nlst].} @defproc[(mlength [mlst mlist?]) exact-nonnegative-integer?]{ -Returns the number of elements in @scheme[mlst].} +Returns the number of elements in @racket[mlst].} @defproc[(mlist-ref [mlst mlist?][pos exact-nonnegative-integer?]) any/c]{ -Like @scheme[list-ref], but for @tech{mutable lists}.} +Like @racket[list-ref], but for @tech{mutable lists}.} @defproc[(mlist-tail [mlst mlist?][pos exact-nonnegative-integer?]) any/c]{ -Like @scheme[list-tail], but for @tech{mutable lists}.} +Like @racket[list-tail], but for @tech{mutable lists}.} @defproc*[([(mappend [mlst mlist?] ...) mlist?] [(mappend [mlst mlist?] ... [v any/c]) any/c])]{ -Like @scheme[append], but for @tech{mutable lists}.} +Like @racket[append], but for @tech{mutable lists}.} @defproc*[([(mappend! [mlst mlist?] ...) mlist?] [(mappend! [mlst mlist?] ... [v any/c]) any/c])]{ -The @scheme[mappend!] procedure appends the given @tech{mutable lists} by mutating -the tail of each to refer to the next, using @scheme[set-mcdr!]. Empty +The @racket[mappend!] procedure appends the given @tech{mutable lists} by mutating +the tail of each to refer to the next, using @racket[set-mcdr!]. Empty lists are dropped; in particular, the result of calling -@scheme[mappend!] with one or more empty lists is the same as the +@racket[mappend!] with one or more empty lists is the same as the result of the call with the empty lists removed from the set of arguments.} @defproc[(mreverse [mlst mlist?]) mlist?]{ -Like @scheme[reverse], but for @tech{mutable lists}.} +Like @racket[reverse], but for @tech{mutable lists}.} @defproc[(mreverse! [mlst mlist?]) mlist?]{ -Like @scheme[mreverse], but destructively reverses the +Like @racket[mreverse], but destructively reverses the @tech{mutable list} by using -all of the mutable pairs in @scheme[mlst] and changing them with -@scheme[set-mcdr!].} +all of the mutable pairs in @racket[mlst] and changing them with +@racket[set-mcdr!].} @defproc[(mmap [proc procedure?] [mlst mlist?] ...+) mlist?]{ -Like @scheme[map], but for @tech{mutable lists}.} +Like @racket[map], but for @tech{mutable lists}.} @defproc[(mfor-each [proc procedure?] [mlst mlist?] ...+) void?]{ -Like @scheme[for-each], but for @tech{mutable lists}.} +Like @racket[for-each], but for @tech{mutable lists}.} @defproc[(mmember [v any/c] [mlst mlist?]) (or/c mlist? #f)]{ -Like @scheme[member], but for @tech{mutable lists}.} +Like @racket[member], but for @tech{mutable lists}.} @defproc[(mmemv [v any/c] [mlst mlist?]) (or/c mlist? #f)]{ -Like @scheme[memv], but for @tech{mutable lists}.} +Like @racket[memv], but for @tech{mutable lists}.} @defproc[(mmemq [v any/c] [mlst mlist?]) (or/c list? #f)]{ -Like @scheme[memq], but for @tech{mutable lists}.} +Like @racket[memq], but for @tech{mutable lists}.} @defproc[(massoc [v any/c] [mlst (mlistof mpair?)]) (or/c mpair? #f)]{ -Like @scheme[assoc], but for @tech{mutable lists} of @tech{mutable pairs}.} +Like @racket[assoc], but for @tech{mutable lists} of @tech{mutable pairs}.} @defproc[(massv [v any/c] [mlst (mlistof mpair?)]) (or/c mpair? #f)]{ -Like @scheme[assv], but for @tech{mutable lists} of @tech{mutable pairs}.} +Like @racket[assv], but for @tech{mutable lists} of @tech{mutable pairs}.} @defproc[(massq [v any/c] [mlst (mlistof mpair?)]) (or/c mpair? #f)]{ -Like @scheme[assq], but for @tech{mutable lists} of @tech{mutable pairs}.} +Like @racket[assq], but for @tech{mutable lists} of @tech{mutable pairs}.} @defproc[(mlistof [pred (any/c . -> . any/c)]) (any/c . -> . boolean?)]{ -Returns a procedure that returns @scheme[#t] when given a @tech{mutable list} -for which @scheme[pred] returns a true value for all elements.} +Returns a procedure that returns @racket[#t] when given a @tech{mutable list} +for which @racket[pred] returns a true value for all elements.} diff --git a/collects/scribblings/reference/mz.ss b/collects/scribblings/reference/mz.ss index f3114f5d3c..9d33dcd32c 100644 --- a/collects/scribblings/reference/mz.ss +++ b/collects/scribblings/reference/mz.ss @@ -58,7 +58,7 @@ " and " (schememodname racket/init) " libraries, which means that they are available when " - (exec "racket") " is started with no command-line arguments." + " the Racket executable is started with no command-line arguments." " They are not provided by " (schememodname racket/base) " or " (schememodname racket) "." . more)))] diff --git a/collects/scribblings/reference/networking.scrbl b/collects/scribblings/reference/networking.scrbl index 87cfdcd203..9a33da16eb 100644 --- a/collects/scribblings/reference/networking.scrbl +++ b/collects/scribblings/reference/networking.scrbl @@ -21,45 +21,45 @@ For information about TCP in general, see @italic{TCP/IP Illustrated, tcp-listener?]{ Creates a ``listening'' server on the local machine at the port number -specified by @scheme[port-no]. If @scheme[port-no] is 0 the socket binds +specified by @racket[port-no]. If @racket[port-no] is 0 the socket binds to an ephemeral port, which can be determined by calling -@scheme[tcp-addresses]. The @scheme[max-allow-wait] argument +@racket[tcp-addresses]. The @racket[max-allow-wait] argument determines the maximum number of client connections that can be -waiting for acceptance. (When @scheme[max-allow-wait] clients are +waiting for acceptance. (When @racket[max-allow-wait] clients are waiting acceptance, no new client connections can be made.) -If the @scheme[reuse?] argument is true, then @scheme[tcp-listen] will +If the @racket[reuse?] argument is true, then @racket[tcp-listen] will create a listener even if the port is involved in a @tt{TIME_WAIT} -state. Such a use of @scheme[reuse?] defeats certain guarantees of the +state. Such a use of @racket[reuse?] defeats certain guarantees of the TCP protocol; see Stevens's book for details. Furthermore, on many -modern platforms, a true value for @scheme[reuse?] overrides +modern platforms, a true value for @racket[reuse?] overrides @tt{TIME_WAIT} only if the listener was previously created with a true -value for @scheme[reuse?]. +value for @racket[reuse?]. -If @scheme[hostname] is @scheme[#f] (the default), then the listener +If @racket[hostname] is @racket[#f] (the default), then the listener accepts connections to all of the listening machine's addresses. Otherwise, the listener accepts connections only at the interface(s) associated with the given hostname. For example, providing -@scheme["127.0.0.1"] as @scheme[hostname] creates a listener that -accepts only connections to @scheme["127.0.0.1"] (the loopback +@racket["127.0.0.1"] as @racket[hostname] creates a listener that +accepts only connections to @racket["127.0.0.1"] (the loopback interface) from the local machine. -(Scheme implements a listener with multiple sockets, if necessary, to +(Racket implements a listener with multiple sockets, if necessary, to accomodate multiple addresses with different protocol families. Under -Linux, if @scheme[hostname] maps to both IPv4 and IPv6 addresses, then +Linux, if @racket[hostname] maps to both IPv4 and IPv6 addresses, then the behavior depends on whether IPv6 is supported and IPv6 sockets can be configured to listen to only IPv6 connections: if IPv6 is not supported or IPv6 sockets are not configurable, then the IPv6 addresses are ignored; otherwise, each IPv6 listener accepts only IPv6 connections.) -The return value of @scheme[tcp-listen] is a @deftech{TCP +The return value of @racket[tcp-listen] is a @deftech{TCP listener}. This value can be used in future calls to -@scheme[tcp-accept], @scheme[tcp-accept-ready?], and -@scheme[tcp-close]. Each new TCP listener value is placed into the +@racket[tcp-accept], @racket[tcp-accept-ready?], and +@racket[tcp-close]. Each new TCP listener value is placed into the management of the current custodian (see @secref["custodians"]). -If the server cannot be started by @scheme[tcp-listen], the +If the server cannot be started by @racket[tcp-listen], the @exnraise[exn:fail:network].} @@ -74,38 +74,38 @@ If the server cannot be started by @scheme[tcp-listen], the (values input-port? output-port?)]{ Attempts to connect as a client to a listening server. The -@scheme[hostname] argument is the server host's Internet address name, -and @scheme[port-no] is the port number where the server is listening. +@racket[hostname] argument is the server host's Internet address name, +and @racket[port-no] is the port number where the server is listening. -(If @scheme[hostname] is associated with multiple addresses, they are +(If @racket[hostname] is associated with multiple addresses, they are tried one at a time until a connection succeeds. The name -@scheme["localhost"] generally specifies the local machine.) +@racket["localhost"] generally specifies the local machine.) -The optional @scheme[local-hostname] and @scheme[local-port-no] -specify the client's address and port. If both are @scheme[#f] (the +The optional @racket[local-hostname] and @racket[local-port-no] +specify the client's address and port. If both are @racket[#f] (the default), the client's address and port are selected automatically. If -@scheme[local-hostname] is not @scheme[#f], then -@scheme[local-port-no] must be non-@scheme[#f]. If -@scheme[local-port-no] is non-@scheme[#f] and @scheme[local-hostname] -is @scheme[#f], then the given port is used but the address is +@racket[local-hostname] is not @racket[#f], then +@racket[local-port-no] must be non-@racket[#f]. If +@racket[local-port-no] is non-@racket[#f] and @racket[local-hostname] +is @racket[#f], then the given port is used but the address is selected automatically. -Two values are returned by @scheme[tcp-connect]: an input port and an +Two values are returned by @racket[tcp-connect]: an input port and an output port. Data can be received from the server through the input port and sent to the server through the output port. If the server is -a @exec{mzscheme} process, it can obtain ports to communicate to the -client with @scheme[tcp-accept]. These ports are placed into the +a Racket program, it can obtain ports to communicate to the +client with @racket[tcp-accept]. These ports are placed into the management of the current custodian (see @secref["custodians"]). Initially, the returned input port is block-buffered, and the returned output port is block-buffered. Change the buffer mode using -@scheme[file-stream-buffer-mode]. +@racket[file-stream-buffer-mode]. Both of the returned ports must be closed to terminate the TCP connection. When both ports are still open, closing the output port -with @scheme[close-output-port] sends a TCP close to the server (which +with @racket[close-output-port] sends a TCP close to the server (which is seen as an end-of-file if the server reads the connection through a -port). In contrast, @scheme[tcp-abandon-port] (see below) closes the +port). In contrast, @racket[tcp-abandon-port] (see below) closes the output port, but does not send a TCP close until the input port is also closed. @@ -117,7 +117,7 @@ response to sending data; in particular, some number of writes on the still-open end may appear to succeed, though writes will eventually produce an error. -If a connection cannot be established by @scheme[tcp-connect], the +If a connection cannot be established by @racket[tcp-connect], the @exnraise[exn:fail:network].} @defproc[(tcp-connect/enable-break [hostname string?] @@ -129,49 +129,49 @@ If a connection cannot be established by @scheme[tcp-connect], the #f)]) (values input-port? output-port?)]{ -Like @scheme[tcp-connect], but breaking is enabled (see +Like @racket[tcp-connect], but breaking is enabled (see @secref["breakhandler"]) while trying to connect. If breaking is -disabled when @scheme[tcp-connect/enable-break] is called, then either -ports are returned or the @scheme[exn:break] exception is raised, but +disabled when @racket[tcp-connect/enable-break] is called, then either +ports are returned or the @racket[exn:break] exception is raised, but not both.} @defproc[(tcp-accept [listener tcp-listener?]) (values input-port? output-port?)]{ Accepts a client connection for the server associated with -@scheme[listener]. If no client connection is waiting on the -listening port, the call to @scheme[tcp-accept] will block. (See also -@scheme[tcp-accept-ready?].) +@racket[listener]. If no client connection is waiting on the +listening port, the call to @racket[tcp-accept] will block. (See also +@racket[tcp-accept-ready?].) -Two values are returned by @scheme[tcp-accept]: an input port and an +Two values are returned by @racket[tcp-accept]: an input port and an output port. Data can be received from the client through the input port and sent to the client through the output port. These ports are placed into the management of the current custodian (see @secref["custodians"]). In terms of buffering and connection states, the ports act the same as -ports from @scheme[tcp-connect]. +ports from @racket[tcp-connect]. -If a connection cannot be accepted by @scheme[tcp-accept], or if the +If a connection cannot be accepted by @racket[tcp-accept], or if the listener has been closed, the @exnraise[exn:fail:network].} @defproc[(tcp-accept/enable-break [listener tcp-listener?]) (values input-port? output-port?)]{ -Like @scheme[tcp-accept], but breaking is enabled (see +Like @racket[tcp-accept], but breaking is enabled (see @secref["breakhandler"]) while trying to accept a connection. If -breaking is disabled when @scheme[tcp-accept/enable-break] is called, -then either ports are returned or the @scheme[exn:break] exception is +breaking is disabled when @racket[tcp-accept/enable-break] is called, +then either ports are returned or the @racket[exn:break] exception is raised, but not both.} @defproc[(tcp-accept-ready? [listener tcp-listener?]) boolean?]{ Tests whether an unaccepted client has connected to the server -associated with @scheme[listener]. If a client is -waiting, the return value is @scheme[#t], otherwise it is -@scheme[#f]. A client is accepted with the @scheme[tcp-accept] +associated with @racket[listener]. If a client is +waiting, the return value is @racket[#t], otherwise it is +@racket[#f]. A client is accepted with the @racket[tcp-accept] procedure, which returns ports for communicating with the client and removes the client from the list of unaccepted clients. @@ -180,48 +180,48 @@ If the listener has been closed, the @exnraise[exn:fail:network].} @defproc[(tcp-close [listener tcp-listener?]) void?]{ -Shuts down the server associated with @scheme[listener]. All +Shuts down the server associated with @racket[listener]. All unaccepted clients receive an end-of-file from the server; connections to accepted clients are unaffected. If the listener has already been closed, the @exnraise[exn:fail:network]. The listener's port number may not become immediately available for -new listeners (with the default @scheme[reuse?] argument of -@scheme[tcp-listen]). For further information, see Stevens's +new listeners (with the default @racket[reuse?] argument of +@racket[tcp-listen]). For further information, see Stevens's explanation of the @tt{TIME_WAIT} TCP state.} @defproc[(tcp-listener? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{TCP listener} created by -@scheme[tcp-listen], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @tech{TCP listener} created by +@racket[tcp-listen], @racket[#f] otherwise.} @defproc[(tcp-accept-evt [listener tcp-listener?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that is in -a blocking state when @scheme[tcp-accept] on @scheme[listener] would +a blocking state when @racket[tcp-accept] on @racket[listener] would block. If the event is chosen in a synchronization, the result is a list of two items, which correspond to the two results of -@scheme[tcp-accept]. (If the event is not chosen, no connections are +@racket[tcp-accept]. (If the event is not chosen, no connections are accepted.) The ports are placed into the management of the custodian that is the current custodian (see @secref["custodians"]) at the time that -@scheme[tcp-accept-evt] is called.} +@racket[tcp-accept-evt] is called.} @defproc[(tcp-abandon-port [tcp-port tcp-port?]) void?]{ -Like @scheme[close-output-port] or @scheme[close-input-port] -(depending on whether @scheme[tcp-port] is an input or output port), -but if @scheme[tcp-port] is an output port and its associated input +Like @racket[close-output-port] or @racket[close-input-port] +(depending on whether @racket[tcp-port] is an input or output port), +but if @racket[tcp-port] is an output port and its associated input port is not yet closed, then the other end of the TCP connection does not receive a TCP close message until the input port is also closed. The TCP protocol does not include a ``no longer reading'' state on -connections, so @scheme[tcp-abandon-port] is equivalent to -@scheme[close-input-port] on input @tech{TCP ports}.} +connections, so @racket[tcp-abandon-port] is equivalent to +@racket[close-input-port] on input @tech{TCP ports}.} @defproc[(tcp-addresses [tcp-port (or/c tcp-port? tcp-listener?)] @@ -230,7 +230,7 @@ connections, so @scheme[tcp-abandon-port] is equivalent to (values string? (integer-in 1 65535) string? (integer-in 1 65535)))]{ -Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the +Returns two strings when @racket[port-numbers?] is @racket[#f] (the default). The first string is the Internet address for the local machine a viewed by the given @tech{TCP port}'s connection. (For most machines, the answer corresponds to the current machine's only @@ -238,21 +238,21 @@ Internet address, but when a machine serves multiple addresses, the result is connection-specific.) The second string is the Internet address for the other end of the connection. -If @scheme[port-numbers?] is true, then four results are returned: a +If @racket[port-numbers?] is true, then four results are returned: a string for the local machine's address, an exact integer between -@scheme[1] and @scheme[65535] for the local machine's port number, a +@racket[1] and @racket[65535] for the local machine's port number, a string for the remote machine's address, and an exact integer between -@scheme[1] and @scheme[65535] for the remote machine's port number. +@racket[1] and @racket[65535] for the remote machine's port number. If the given port has been closed, the @exnraise[exn:fail:network].} @defproc[(tcp-port? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @deftech{TCP port}---which is a -port returned by @scheme[tcp-accept], @scheme[tcp-connect], -@scheme[tcp-accept/enable-break], or -@scheme[tcp-connect/enable-break]---@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @deftech{TCP port}---which is a +port returned by @racket[tcp-accept], @racket[tcp-connect], +@racket[tcp-accept/enable-break], or +@racket[tcp-connect/enable-break]---@racket[#f] otherwise.} @;------------------------------------------------------------------------ @section[#:tag "udp"]{UDP} @@ -270,17 +270,17 @@ Creates and returns a @deftech{UDP socket} to send and receive datagrams (broadcasting is allowed). Initially, the socket is not bound or connected to any address or port. -If @scheme[family-hostname] or @scheme[family-port-no] is not -@scheme[#f], then the socket's protocol family is determined from +If @racket[family-hostname] or @racket[family-port-no] is not +@racket[#f], then the socket's protocol family is determined from these arguments. The socket is @italic{not} bound to the hostname or port number. For example, the arguments might be the hostname and port to which messages will be sent through the socket, which ensures that the socket's protocol family is consistent with the destination. Alternately, the arguments might be the same as for -a future call to @scheme[udp-bind!], which ensures that the +a future call to @racket[udp-bind!], which ensures that the socket's protocol family is consistent with the binding. If -neither @scheme[family-hostname] nor @scheme[family-port-no] is -non-@scheme[#f], then the socket's protocol family is IPv4.} +neither @racket[family-hostname] nor @racket[family-port-no] is +non-@racket[#f], then the socket's protocol family is IPv4.} @defproc[(udp-bind! [udp-socket udp?] [hostname-string (or/c string? #f)] @@ -288,35 +288,35 @@ non-@scheme[#f], then the socket's protocol family is IPv4.} (integer-in 0 65535))]) void?]{ -Binds an unbound @scheme[udp-socket] to the local port number -@scheme[port-no]. If @scheme[port-no] is 0 the @scheme[udp-socket] is +Binds an unbound @racket[udp-socket] to the local port number +@racket[port-no]. If @racket[port-no] is 0 the @racket[udp-socket] is bound to an ephemeral port, which can be determined by calling -@scheme[udp-addresses]. +@racket[udp-addresses]. -If @scheme[hostname-string] is @scheme[#f], then the socket +If @racket[hostname-string] is @racket[#f], then the socket accepts connections to all of the listening machine's IP -addresses at @scheme[port-no]. Otherwise, the socket accepts +addresses at @racket[port-no]. Otherwise, the socket accepts connections only at the IP address associated with the given -name. For example, providing @scheme["127.0.0.1"] as -@scheme[hostname-string] typically creates a listener that -accepts only connections to @scheme["127.0.0.1"] from the local +name. For example, providing @racket["127.0.0.1"] as +@racket[hostname-string] typically creates a listener that +accepts only connections to @racket["127.0.0.1"] from the local machine. A socket cannot receive datagrams until it is bound to a local address and port. If a socket is not bound before it is used with a sending -procedure @scheme[udp-send], @scheme[udp-send-to], etc., the sending +procedure @racket[udp-send], @racket[udp-send-to], etc., the sending procedure binds the socket to a random local port. Similarly, if an -event from @scheme[udp-send-evt] or @scheme[udp-send-to-evt] is chosen +event from @racket[udp-send-evt] or @racket[udp-send-to-evt] is chosen for a synchronization (see @secref["sync"]), the socket is bound; if the event is not chosen, the socket may or may not become bound. The binding of a bound socket cannot be changed, with one exception: on some systems, if the socket is bound automatically when sending, if -the socket is disconnected via @scheme[udp-connect!], and if the +the socket is disconnected via @racket[udp-connect!], and if the socket is later used again in a send, then the later send may change the socket's automatic binding. -If @scheme[udp-socket] is already bound or closed, the +If @racket[udp-socket] is already bound or closed, the @exnraise[exn:fail:network].} @@ -328,21 +328,21 @@ If @scheme[udp-socket] is already bound or closed, the void?]{ Connects the socket to the indicated remote address and port if -@scheme[hostname-string] is a string and @scheme[port-no] is an exact +@racket[hostname-string] is a string and @racket[port-no] is an exact integer. -If @scheme[hostname-string] is @scheme[#f], then @scheme[port-no] also -must be @scheme[#f], and the port is disconnected (if connected). If -one of @scheme[hostname-string] or @scheme[port-no] is @scheme[#f] and +If @racket[hostname-string] is @racket[#f], then @racket[port-no] also +must be @racket[#f], and the port is disconnected (if connected). If +one of @racket[hostname-string] or @racket[port-no] is @racket[#f] and the other is not, the @exnraise[exn:fail:contract]. -A connected socket can be used with @scheme[udp-send] (not -@scheme[udp-send-to]), and it accepts datagrams only from the +A connected socket can be used with @racket[udp-send] (not +@racket[udp-send-to]), and it accepts datagrams only from the connected address and port. A socket need not be connected to receive datagrams. A socket can be connected, re-connected, and disconnected any number of times. -If @scheme[udp-socket] is closed, the @exnraise[exn:fail:network].} +If @racket[udp-socket] is closed, the @exnraise[exn:fail:network].} @defproc[(udp-send-to [udp-socket udp?] @@ -354,19 +354,19 @@ If @scheme[udp-socket] is closed, the @exnraise[exn:fail:network].} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) void]{ -Sends @scheme[(subbytes bytes start-pos end-pos)] as a datagram from -the unconnected @scheme[udp-socket] to the socket at the remote -machine @scheme[hostname-address] on the port @scheme[port-no]. The -@scheme[udp-socket] need not be bound or connected; if it is not -bound, @scheme[udp-send-to] binds it to a random local port. If the +Sends @racket[(subbytes bytes start-pos end-pos)] as a datagram from +the unconnected @racket[udp-socket] to the socket at the remote +machine @racket[hostname-address] on the port @racket[port-no]. The +@racket[udp-socket] need not be bound or connected; if it is not +bound, @racket[udp-send-to] binds it to a random local port. If the socket's outgoing datagram queue is too full to support the send, -@scheme[udp-send-to] blocks until the datagram can be queued. +@racket[udp-send-to] blocks until the datagram can be queued. -If @scheme[start-pos] is greater than the length of @scheme[bstr], or -if @scheme[end-pos] is less than @scheme[start-pos] or greater than -the length of @scheme[bstr], the @exnraise[exn:fail:contract]. +If @racket[start-pos] is greater than the length of @racket[bstr], or +if @racket[end-pos] is less than @racket[start-pos] or greater than +the length of @racket[bstr], the @exnraise[exn:fail:contract]. -If @scheme[udp-socket] is closed or connected, the +If @racket[udp-socket] is closed or connected, the @exnraise[exn:fail:network].} @defproc[(udp-send [udp-socket udp?] @@ -375,9 +375,9 @@ If @scheme[udp-socket] is closed or connected, the [end-pos exact-nonnegative-integer? (bytes-length bstr)]) void]{ -Like @scheme[udp-send-to], except that @scheme[udp-socket] must be +Like @racket[udp-send-to], except that @racket[udp-socket] must be connected, and the datagram goes to the connection target. If -@scheme[udp-socket] is closed or unconnected, the +@racket[udp-socket] is closed or unconnected, the @exnraise[exn:fail:network].} @defproc[(udp-send-to* [udp-socket udp?] @@ -389,9 +389,9 @@ connected, and the datagram goes to the connection target. If [end-pos exact-nonnegative-integer? (bytes-length bstr)]) boolean?]{ -Like @scheme[udp-send-to], but never blocks; if the socket's outgoing -queue is too full to support the send, @scheme[#f] is returned, -otherwise the datagram is queued and the result is @scheme[#t].} +Like @racket[udp-send-to], but never blocks; if the socket's outgoing +queue is too full to support the send, @racket[#f] is returned, +otherwise the datagram is queued and the result is @racket[#t].} @defproc[(udp-send* [udp-socket udp?] [bstr bytes?] @@ -399,8 +399,8 @@ otherwise the datagram is queued and the result is @scheme[#t].} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) boolean?]{ -Like @scheme[udp-send], except that (like @scheme[udp-send-to]) it -never blocks and returns @scheme[#f] or @scheme[#t].} +Like @racket[udp-send], except that (like @racket[udp-send-to]) it +never blocks and returns @racket[#f] or @racket[#t].} @defproc[(udp-send-to/enable-break [udp-socket udp?] [hostname string?] @@ -411,10 +411,10 @@ never blocks and returns @scheme[#f] or @scheme[#t].} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) void]{ -Like @scheme[udp-send-to], but breaking is enabled (see +Like @racket[udp-send-to], but breaking is enabled (see @secref["breakhandler"]) while trying to send the datagram. If -breaking is disabled when @scheme[udp-send-to/enable-break] is called, -then either the datagram is sent or the @scheme[exn:break] exception +breaking is disabled when @racket[udp-send-to/enable-break] is called, +then either the datagram is sent or the @racket[exn:break] exception is raised, but not both.} @@ -424,8 +424,8 @@ is raised, but not both.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) void]{ -Like @scheme[udp-send], except that breaks are enabled like -@scheme[udp-send-to/enable-break].} +Like @racket[udp-send], except that breaks are enabled like +@racket[udp-send-to/enable-break].} @defproc[(udp-receive! [udp-socket udp?] @@ -436,24 +436,24 @@ Like @scheme[udp-send], except that breaks are enabled like string? (integer-in 1 65535))]{ -Accepts up to @math{@scheme[end-pos]-@scheme[start-pos]} bytes of -@scheme[udp-socket]'s next incoming datagram into @scheme[bstr], -writing the datagram bytes starting at position @scheme[start-pos] -within @scheme[bstr]. The @scheme[udp-socket] must be bound to a local +Accepts up to @math{@racket[end-pos]-@racket[start-pos]} bytes of +@racket[udp-socket]'s next incoming datagram into @racket[bstr], +writing the datagram bytes starting at position @racket[start-pos] +within @racket[bstr]. The @racket[udp-socket] must be bound to a local address and port (but need not be connected). If no incoming datagram -is immediately available, @scheme[udp-receive!] blocks until one is +is immediately available, @racket[udp-receive!] blocks until one is available. Three values are returned: the number of received bytes (between -@scheme[0] and @math{@scheme[end-pos]-@scheme[start-pos]}, a hostname +@racket[0] and @math{@racket[end-pos]-@racket[start-pos]}, a hostname string indicating the source address of the datagram, and an integer indicating the source port of the datagram. If the received datagram -is longer than @math{@scheme[end-pos]-@scheme[start-pos]} bytes, the +is longer than @math{@racket[end-pos]-@racket[start-pos]} bytes, the remainder is discarded. -If @scheme[start-pos] is greater than the length of @scheme[bstr], or -if @scheme[end-pos] is less than @scheme[start-pos] or greater than -the length of @scheme[bstr], the @exnraise[exn:fail:contract].} +If @racket[start-pos] is greater than the length of @racket[bstr], or +if @racket[end-pos] is less than @racket[start-pos] or greater than +the length of @racket[bstr], the @exnraise[exn:fail:contract].} @defproc[(udp-receive!* [udp-socket udp?] [bstr (and/c bytes? (not immutable?))] @@ -463,8 +463,8 @@ the length of @scheme[bstr], the @exnraise[exn:fail:contract].} (or/c string? #f) (or/c (integer-in 1 65535) #f))]{ -Like @scheme[udp-receive!], except that it never blocks. If no -datagram is available, the three result values are all @scheme[#f].} +Like @racket[udp-receive!], except that it never blocks. If no +datagram is available, the three result values are all @racket[#f].} @defproc[(udp-receive!/enable-break [udp-socket udp?] [bstr (and/c bytes? (not immutable?))] @@ -474,48 +474,48 @@ datagram is available, the three result values are all @scheme[#f].} string? (integer-in 1 65535))]{ -Like @scheme[udp-receive!], but breaking is enabled (see +Like @racket[udp-receive!], but breaking is enabled (see @secref["breakhandler"]) while trying to receive the datagram. If -breaking is disabled when @scheme[udp-receive!/enable-break] is -called, then either a datagram is received or the @scheme[exn:break] +breaking is disabled when @racket[udp-receive!/enable-break] is +called, then either a datagram is received or the @racket[exn:break] exception is raised, but not both.} @defproc[(udp-close [udp-socket udp?]) void?]{ -Closes @scheme[udp-socket], discarding unreceived datagrams. If the +Closes @racket[udp-socket], discarding unreceived datagrams. If the socket is already closed, the @exnraise[exn:fail:network].} @defproc[(udp? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a socket created by -@scheme[udp-open-socket], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a socket created by +@racket[udp-open-socket], @racket[#f] otherwise.} @defproc[(udp-bound? [udp-socket udp?]) boolean?]{ -Returns @scheme[#t] if @scheme[udp-socket] is bound to a local address -and port, @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[udp-socket] is bound to a local address +and port, @racket[#f] otherwise.} @defproc[(udp-connected? [udp-socket udp?]) boolean?]{ -Returns @scheme[#t] if @scheme[udp-socket] is connected to a remote -address and port, @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[udp-socket] is connected to a remote +address and port, @racket[#f] otherwise.} @defproc[(udp-send-ready-evt [udp-socket udp?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that is -in a blocking state when @scheme[udp-send-to] on @scheme[udp-socket] +in a blocking state when @racket[udp-send-to] on @racket[udp-socket] would block.} @defproc[(udp-receive-ready-evt [udp-socket udp?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that is -in a blocking state when @scheme[udp-receive!] on @scheme[udp-socket] +in a blocking state when @racket[udp-receive!] on @racket[udp-socket] would block.} @defproc[(udp-send-to-evt [udp-socket udp?] @@ -528,9 +528,9 @@ would block.} evt?]{ Returns a @tech{synchronizable event}. The event is in a blocking -state when @scheme[udp-send-to] on @scheme[udp-socket] would +state when @racket[udp-send-to] on @racket[udp-socket] would block. Otherwise, if the event is chosen in a synchronization, data is -sent as for @scheme[(udp-send-to udp-socket hostname-address port-no +sent as for @racket[(udp-send-to udp-socket hostname-address port-no bstr start-pos end-pos)], and the synchronization result is @|void-const|. (No bytes are sent if the event is not chosen.)} @@ -542,11 +542,11 @@ bstr start-pos end-pos)], and the synchronization result is evt?]{ Returns a @tech{synchronizable event}. The event is in a blocking -state when @scheme[udp-send] on @scheme[udp-socket] would +state when @racket[udp-send] on @racket[udp-socket] would block. Otherwise, if the event is chosen in a synchronization, data is -sent as for @scheme[(udp-send-to udp-socket bstr start-pos end-pos)], +sent as for @racket[(udp-send-to udp-socket bstr start-pos end-pos)], and the synchronization result is @|void-const|. (No bytes are sent if -the event is not chosen.) If @scheme[udp-socket] is closed or +the event is not chosen.) If @racket[udp-socket] is closed or unconnected, the @exnraise[exn:fail:network] during a synchronization attempt.} @@ -557,12 +557,12 @@ attempt.} evt?]{ Returns a @tech{synchronizable event}. The event is in a blocking -state when @scheme[udp-receive] on @scheme[udp-socket] would +state when @racket[udp-receive] on @racket[udp-socket] would block. Otherwise, if the event is chosen in a synchronization, data is -received into @scheme[bstr] as for @scheme[(udp-receive! udp-socket +received into @racket[bstr] as for @racket[(udp-receive! udp-socket bytes start-pos end-pos)], and the synchronization result is a list of three values, corresponding to the three results from -@scheme[udp-receive!]. (No bytes are received and the @scheme[bstr] +@racket[udp-receive!]. (No bytes are received and the @racket[bstr] content is not modified if the event is not chosen.)} @defproc[(udp-addresses [udp-port udp?] @@ -571,7 +571,7 @@ content is not modified if the event is not chosen.)} (values string? (integer-in 1 65535) string? (integer-in 1 65535)))]{ -Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the +Returns two strings when @racket[port-numbers?] is @racket[#f] (the default). The first string is the Internet address for the local machine a viewed by the given @tech{UDP socket}'s connection. (For most machines, the answer corresponds to the current machine's only @@ -579,10 +579,10 @@ Internet address, but when a machine serves multiple addresses, the result is connection-specific.) The second string is the Internet address for the other end of the connection. -If @scheme[port-numbers?] is true, then four results are returned: a +If @racket[port-numbers?] is true, then four results are returned: a string for the local machine's address, an exact integer between -@scheme[1] and @scheme[65535] for the local machine's port number, a +@racket[1] and @racket[65535] for the local machine's port number, a string for the remote machine's address, and an exact integer between -@scheme[1] and @scheme[65535] for the remote machine's port number. +@racket[1] and @racket[65535] for the remote machine's port number. If the given port has been closed, the @exnraise[exn:fail:network].} diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index fb6dcce88b..83309a0ff5 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -18,10 +18,10 @@ All @deftech{numbers} are @deftech{complex numbers}. Some of them are @deftech{real numbers}, and all of the real numbers that can be represented are also @deftech{rational numbers}, except for -@as-index{@scheme[+inf.0]} (positive @as-index{infinity}), -@as-index{@scheme[-inf.0]} (negative infinity), and -@as-index{@scheme[+nan.0]} (@as-index{not-a-number}). Among the -rational numbers, some are @deftech{integers}, because @scheme[round] +@as-index{@racket[+inf.0]} (positive @as-index{infinity}), +@as-index{@racket[-inf.0]} (negative infinity), and +@as-index{@racket[+nan.0]} (@as-index{not-a-number}). Among the +rational numbers, some are @deftech{integers}, because @racket[round] applied to the number produces the same number. Orthogonal to those categories, each number is also either an @@ -29,8 +29,8 @@ Orthogonal to those categories, each number is also either an otherwise specified, computations that involve an inexact number produce inexact results. Certain operations on inexact numbers, however, produce an exact number, such as multiplying an inexact -number with an exact @scheme[0]. Some operations, which can produce an -irrational number for rational arguments (e.g., @scheme[sqrt]), may +number with an exact @racket[0]. Some operations, which can produce an +irrational number for rational arguments (e.g., @racket[sqrt]), may produce inexact results even for exact arguments. In the case of complex numbers, either the real and imaginary parts @@ -51,64 +51,64 @@ numbers). In particular, adding, multiplying, subtracting, and dividing exact numbers always produces an exact result. Inexact numbers can be coerced to exact form, except for the inexact -numbers @scheme[+inf.0], @scheme[-inf.0], and @scheme[+nan.0], which +numbers @racket[+inf.0], @racket[-inf.0], and @racket[+nan.0], which have no exact form. @index["division by inexact zero"]{Dividing} a number by exact zero raises an exception; dividing a non-zero number -other than @scheme[+nan.0] by an inexact zero returns @scheme[+inf.0] -or @scheme[-inf.0], depending on the sign of the dividend. The -@scheme[+nan.0] value is not @scheme[=] to itself, but @scheme[+nan.0] -is @scheme[eqv?] to itself. Conversely, @scheme[(= 0.0 -0.0)] is -@scheme[#t], but @scheme[(eqv? 0.0 -0.0)] is @scheme[#f]. The datum -@schemevalfont{-nan.0} refers to the same constant as @scheme[+nan.0]. +other than @racket[+nan.0] by an inexact zero returns @racket[+inf.0] +or @racket[-inf.0], depending on the sign of the dividend. The +@racket[+nan.0] value is not @racket[=] to itself, but @racket[+nan.0] +is @racket[eqv?] to itself. Conversely, @racket[(= 0.0 -0.0)] is +@racket[#t], but @racket[(eqv? 0.0 -0.0)] is @racket[#f]. The datum +@racketvalfont{-nan.0} refers to the same constant as @racket[+nan.0]. Calculations with infinites produce results consistent with IEEE double-precision floating point where IEEE specifies the result; in -cases where IEEE provides no specification (e.g., @scheme[(angle +cases where IEEE provides no specification (e.g., @racket[(angle +inf.0+inf.0i)]), the result corresponds to the limit approaching -infinity, or @scheme[+nan.0] if no such limit exists. +infinity, or @racket[+nan.0] if no such limit exists. A @deftech{fixnum} is an exact integer whose two's complement representation fit into 31 bits on a 32-bit platform or 63 bits on a 64-bit platform; furthermore, no allocation is required when computing -with fixnums. See also the @schememodname[racket/fixnum] module, below. +with fixnums. See also the @racketmodname[racket/fixnum] module, below. -Two fixnums that are @scheme[=] are also the same -according to @scheme[eq?]. Otherwise, the result of @scheme[eq?] +Two fixnums that are @racket[=] are also the same +according to @racket[eq?]. Otherwise, the result of @racket[eq?] applied to two numbers is undefined. -Two numbers are @scheme[eqv?] when they are both inexact or both -exact, and when they are @scheme[=] (except for @scheme[+nan.0], -@scheme[+0.0], and @scheme[-0.0], as noted above). Two numbers are -@scheme[equal?] when they are @scheme[eqv?]. +Two numbers are @racket[eqv?] when they are both inexact or both +exact, and when they are @racket[=] (except for @racket[+nan.0], +@racket[+0.0], and @racket[-0.0], as noted above). Two numbers are +@racket[equal?] when they are @racket[eqv?]. @; ---------------------------------------- @section{Number Types} -@defproc[(number? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] - is a number, @scheme[#f] otherwise. +@defproc[(number? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] + is a number, @racket[#f] otherwise. @mz-examples[(number? 1) (number? 2+3i) (number? "hello")]} -@defproc[(complex? [v any/c]) boolean?]{ Returns @scheme[(number? v)], +@defproc[(complex? [v any/c]) boolean?]{ Returns @racket[(number? v)], because all numbers are @tech{complex numbers}.} -@defproc[(real? [v any/c]) boolean?]{ Returns @scheme[#t] if @scheme[v] is - a @techlink{real number}, @scheme[#f] otherwise. +@defproc[(real? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v] is + a @techlink{real number}, @racket[#f] otherwise. @mz-examples[(real? 1) (real? +inf.0) (real? 2+3i) (real? 2+0.0i) (real? "hello")]} -@defproc[(rational? [v any/c]) boolean?]{ Returns @scheme[#t] if - @scheme[v] is a @techlink{rational number}, @scheme[#f] otherwise. +@defproc[(rational? [v any/c]) boolean?]{ Returns @racket[#t] if + @racket[v] is a @techlink{rational number}, @racket[#f] otherwise. @mz-examples[(rational? 1) (rational? +inf.0) (real? "hello")]} -@defproc[(integer? [v any/c]) boolean?]{ Returns @scheme[#t] if @scheme[v] - is a number that is an @techlink{integer}, @scheme[#f] otherwise. +@defproc[(integer? [v any/c]) boolean?]{ Returns @racket[#t] if @racket[v] + is a number that is an @techlink{integer}, @racket[#f] otherwise. @mz-examples[(integer? 1) (integer? 2.3) (integer? 4.0) (integer? +inf.0) (integer? 2+3i) (integer? "hello")]} @@ -116,84 +116,84 @@ because all numbers are @tech{complex numbers}.} @defproc[(exact-integer? [v any/c]) boolean?]{ -Returns @scheme[(and (integer? v) (exact? v))]. +Returns @racket[(and (integer? v) (exact? v))]. @mz-examples[(exact-integer? 1) (exact-integer? 4.0)]} @defproc[(exact-nonnegative-integer? [v any/c]) boolean?]{ -Returns @scheme[(and (exact-integer? v) (not (negative? v)))]. +Returns @racket[(and (exact-integer? v) (not (negative? v)))]. @mz-examples[(exact-nonnegative-integer? 0) (exact-nonnegative-integer? -1)]} @defproc[(exact-positive-integer? [v any/c]) boolean?]{ -Returns @scheme[(and (exact-integer? v) (positive? v))]. +Returns @racket[(and (exact-integer? v) (positive? v))]. @mz-examples[(exact-positive-integer? 1) (exact-positive-integer? 0)]} @defproc[(inexact-real? [v any/c]) boolean?]{ -Returns @scheme[(and (real? v) (inexact? v))].} +Returns @racket[(and (real? v) (inexact? v))].} @defproc[(fixnum? [v any/c]) boolean?]{ -Return @scheme[#t] if @scheme[v] is a @techlink{fixnum}, @scheme[#f] +Return @racket[#t] if @racket[v] is a @techlink{fixnum}, @racket[#f] otherwise.} -@defproc[(zero? [z number?]) boolean?]{ Returns @scheme[(= 0 z)]. +@defproc[(zero? [z number?]) boolean?]{ Returns @racket[(= 0 z)]. @mz-examples[(zero? 0) (zero? -0.0)]} -@defproc[(positive? [x real?]) boolean?]{ Returns @scheme[(> x 0)]. +@defproc[(positive? [x real?]) boolean?]{ Returns @racket[(> x 0)]. @mz-examples[(positive? 10) (positive? -10) (positive? 0.0)]} -@defproc[(negative? [x real?]) boolean?]{ Returns @scheme[(< x 0)]. +@defproc[(negative? [x real?]) boolean?]{ Returns @racket[(< x 0)]. @mz-examples[(negative? 10) (negative? -10) (negative? -0.0)]} -@defproc[(even? [n integer?]) boolean?]{ Returns @scheme[(zero? (modulo +@defproc[(even? [n integer?]) boolean?]{ Returns @racket[(zero? (modulo n 2))]. @mz-examples[(even? 10.0) (even? 11) (even? +inf.0)]} -@defproc[(odd? [n integer?]) boolean?]{ Returns @scheme[(not (even? n))]. +@defproc[(odd? [n integer?]) boolean?]{ Returns @racket[(not (even? n))]. @mz-examples[(odd? 10.0) (odd? 11) (odd? +inf.0)]} -@defproc[(exact? [z number?]) boolean?]{ Returns @scheme[#t] if @scheme[z] - is an exact number, @scheme[#f] otherwise. +@defproc[(exact? [z number?]) boolean?]{ Returns @racket[#t] if @racket[z] + is an exact number, @racket[#f] otherwise. @mz-examples[(exact? 1) (exact? 1.0)]} -@defproc[(inexact? [z number?]) boolean?]{ Returns @scheme[#t] if @scheme[z] - is an inexact number, @scheme[#f] otherwise. +@defproc[(inexact? [z number?]) boolean?]{ Returns @racket[#t] if @racket[z] + is an inexact number, @racket[#f] otherwise. @mz-examples[(inexact? 1) (inexact? 1.0)]} -@defproc[(inexact->exact [z number?]) exact?]{ Coerces @scheme[z] to an - exact number. If @scheme[z] is already exact, it is returned. If @scheme[z] - is @scheme[+inf.0], @scheme[-inf.0], or @scheme[+nan.0], then the +@defproc[(inexact->exact [z number?]) exact?]{ Coerces @racket[z] to an + exact number. If @racket[z] is already exact, it is returned. If @racket[z] + is @racket[+inf.0], @racket[-inf.0], or @racket[+nan.0], then the @exnraise[exn:fail:contract]. @mz-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. +@defproc[(exact->inexact [z number?]) inexact?]{ Coerces @racket[z] to an + inexact number. If @racket[z] is already inexact, it is returned. @mz-examples[(exact->inexact 1) (exact->inexact 1.0)]} @@ -202,51 +202,51 @@ otherwise.} @section{Arithmetic} @defproc[(+ [z number?] ...) number?]{ Returns the sum of the - @scheme[z]s, adding pairwise from left to right. If no arguments are - provided, the result is @scheme[0]. + @racket[z]s, adding pairwise from left to right. If no arguments are + provided, the result is @racket[0]. @mz-examples[(+ 1 2) (+ 1.0 2+3i 5) (+)]} @defproc*[([(- [z number?]) number?] [(- [z number?] [w number?] ...+) number?])]{ - When no @scheme[w]s are supplied, returns @scheme[(- 0 z)]. - Otherwise, returns the subtraction of the @scheme[w]s from @scheme[z] + When no @racket[w]s are supplied, returns @racket[(- 0 z)]. + Otherwise, returns the subtraction of the @racket[w]s from @racket[z] working pairwise from left to right.} @mz-examples[(- 5 3.0) (- 1) (- 2+7i 1 3)] @defproc[(* [z number?] ...) number?]{ Returns the product of the - @scheme[z]s, multiplying pairwise from left to right. If no arguments are - provided, the result is @scheme[1].} + @racket[z]s, multiplying pairwise from left to right. If no arguments are + provided, the result is @racket[1].} @mz-examples[(* 2 3) (* 8.0 9) (* 1+2i 3+4i)] @defproc*[([(/ [z number?]) number?] [(/ [z number?] [w number?] ...+) number?])]{ - When no @scheme[w]s are supplied, returns @scheme[(/ 1 z)]. - Otherwise, returns the division @scheme[z] by the var[w]s + When no @racket[w]s are supplied, returns @racket[(/ 1 z)]. + Otherwise, returns the division @racket[z] by the var[w]s working pairwise from left to right.} @mz-examples[(/ 3 4) (/ 81 3 3) (/ 10.0) (/ 1+2i 3+4i)] @defproc[(quotient [n integer?] [m integer?]) integer?]{ Returns - @scheme[(truncate (/ n m))].} + @racket[(truncate (/ n m))].} @mz-examples[(quotient 10 3) (quotient -10.0 3) (quotient +inf.0 3)] @defproc[(remainder [n integer?] [m integer?]) integer?]{ Returns - @scheme[_q] with the same sign as @scheme[n] such that + @racket[_q] with the same sign as @racket[n] such that @itemize[ - @item{@scheme[(abs _q)] is between @scheme[0] (inclusive) and @scheme[(abs m)] (exclusive), and} + @item{@racket[(abs _q)] is between @racket[0] (inclusive) and @racket[(abs m)] (exclusive), and} - @item{@scheme[(+ _q (* m (quotient n m)))] equals @scheme[n].} + @item{@racket[(+ _q (* m (quotient n m)))] equals @racket[n].} ] @@ -254,8 +254,8 @@ otherwise.} @defproc[(quotient/remainder [n integer?] [m integer?]) (values number? number?)]{ Returns - @scheme[(values (quotient n m) (remainder n m))], but the combination is computed - more efficiently than separate calls to @scheme[quotient] and @scheme[remainder]. + @racket[(values (quotient n m) (remainder n m))], but the combination is computed + more efficiently than separate calls to @racket[quotient] and @racket[remainder]. @mz-examples[ (quotient/remainder 10 3) @@ -263,104 +263,104 @@ otherwise.} @defproc[(modulo [n integer?] [m integer?]) number?]{ Returns - @scheme[_q] with the same sign as @scheme[m] where + @racket[_q] with the same sign as @racket[m] where @itemize[ - @item{@scheme[(abs _q)] is between @scheme[0] (inclusive) and @scheme[(abs m)] (exclusive), and} + @item{@racket[(abs _q)] is between @racket[0] (inclusive) and @racket[(abs m)] (exclusive), and} - @item{the difference between @scheme[_q] and @scheme[(- n (* m (quotient n m)))] is a multiple of @scheme[m].} + @item{the difference between @racket[_q] and @racket[(- n (* m (quotient n m)))] is a multiple of @racket[m].} ] @mz-examples[(modulo 10 3) (modulo -10.0 3) (modulo 10.0 -3) (modulo -10 -3) (modulo +inf.0 3)]} -@defproc[(add1 [z number?]) number?]{ Returns @scheme[(+ z 1)].} +@defproc[(add1 [z number?]) number?]{ Returns @racket[(+ z 1)].} -@defproc[(sub1 [z number?]) number?]{ Returns @scheme[(- z 1)].} +@defproc[(sub1 [z number?]) number?]{ Returns @racket[(- z 1)].} @defproc[(abs [x real?]) number?]{ Returns the absolute value of - @scheme[x]. + @racket[x]. @mz-examples[(abs 1.0) (abs -1)]} @defproc[(max [x real?] ...+) real?]{ Returns the largest of the - @scheme[x]s, or @scheme[+nan.0] if any @scheme[x] is @scheme[+nan.0]. - If any @scheme[x] is inexact, the result is coerced to inexact. + @racket[x]s, or @racket[+nan.0] if any @racket[x] is @racket[+nan.0]. + If any @racket[x] is inexact, the result is coerced to inexact. @mz-examples[(max 1 3 2) (max 1 3 2.0)]} @defproc[(min [x real?] ...+) real?]{ Returns the smallest of the - @scheme[x]s, or @scheme[+nan.0] if any @scheme[x] is @scheme[+nan.0]. - If any @scheme[x] is inexact, the result is coerced to inexact. + @racket[x]s, or @racket[+nan.0] if any @racket[x] is @racket[+nan.0]. + If any @racket[x] is inexact, the result is coerced to inexact. @mz-examples[(min 1 3 2) (min 1 3 2.0)]} @defproc[(gcd [n integer?] ...) integer?]{ Returns the @as-index{greatest common divisor} (a non-negative number) of the - @scheme[n]s. If no arguments are provided, the result is - @scheme[0]. If all arguments are zero, the result is zero. + @racket[n]s. If no arguments are provided, the result is + @racket[0]. If all arguments are zero, the result is zero. @mz-examples[(gcd 10) (gcd 12 81.0)]} @defproc[(lcm [n integer?] ...) integer?]{ Returns the @as-index{least - common multiple} (a non-negative number) of the @scheme[n]s. If no - arguments are provided, the result is @scheme[1]. If any argument is + common multiple} (a non-negative number) of the @racket[n]s. If no + arguments are provided, the result is @racket[1]. If any argument is zero, the result is zero. @mz-examples[(lcm 10) (lcm 3 4.0)]} @defproc[(round [x real?]) integer?]{ Returns the integer closest to - @scheme[x], resolving ties in favor of an even number. + @racket[x], resolving ties in favor of an even number. @mz-examples[(round 17/4) (round -17/4) (round 2.5) (round -2.5)]} @defproc[(floor [x real?]) integer?]{ Returns the largest integer is that - is no more than @scheme[x]. + is no more than @racket[x]. @mz-examples[(floor 17/4) (floor -17/4) (floor 2.5) (floor -2.5)]} @defproc[(ceiling [x real?]) integer?]{ Returns the smallest integer is - that is at least as large as @scheme[x]. + that is at least as large as @racket[x]. @mz-examples[(ceiling 17/4) (ceiling -17/4) (ceiling 2.5) (ceiling -2.5)]} @defproc[(truncate [x real?]) integer?]{ Returns the integer farthest - from @scheme[0] that is no closer to @scheme[0] than @scheme[x]. + from @racket[0] that is no closer to @racket[0] than @racket[x]. @mz-examples[(truncate 17/4) (truncate -17/4) (truncate 2.5) (truncate -2.5)]} @defproc[(numerator [q rational?]) integer?]{ - Coreces @scheme[q] to an exact number, finds the numerator of the number + Coreces @racket[q] to an exact number, finds the numerator of the number expressed in its simplest fractional form, and returns this number - coerced to the exactness of @scheme[q]. + coerced to the exactness of @racket[q]. @mz-examples[(numerator 5) (numerator 34/8) (numerator 2.3)]} @defproc[(denominator [q rational?]) integer?]{ - Coreces @scheme[q] to an exact number, finds the numerator of the number + Coreces @racket[q] to an exact number, finds the numerator of the number expressed in its simplest fractional form, and returns this number - coerced to the exactness of @scheme[q]. + coerced to the exactness of @racket[q]. @mz-examples[(denominator 5) (denominator 34/8) (denominator 2.3)]} @defproc[(rationalize [x real?][tolerance real?]) real?]{ -Among the real numbers within @scheme[(abs tolerance)] of @scheme[x], +Among the real numbers within @racket[(abs tolerance)] of @racket[x], returns the one corresponding to an exact number whose -@scheme[denominator] is smallest. If multiple integers are within -@scheme[tolerance] of @scheme[x], the one closest to @scheme[0] is +@racket[denominator] is smallest. If multiple integers are within +@racket[tolerance] of @racket[x], the one closest to @racket[0] is used. @mz-examples[ @@ -374,39 +374,39 @@ used. @section{Number Comparison} @defproc[(= [z number?] [w number?] ...+) boolean?]{ Returns - @scheme[#t] if all of the arguments are numerically equal, - @scheme[#f] otherwise. An inexact number is numerically equal to an + @racket[#t] if all of the arguments are numerically equal, + @racket[#f] otherwise. An inexact number is numerically equal to an exact number when the exact coercion of the inexact number is the - exact number. Also, @scheme[0.0] and @scheme[-0.0] are numerically - equal, but @scheme[+nan.0] is not numerically equal to itself. + exact number. Also, @racket[0.0] and @racket[-0.0] are numerically + equal, but @racket[+nan.0] is not numerically equal to itself. @mz-examples[(= 1 1.0) (= 1 2) (= 2+3i 2+3i 2+3i)]} -@defproc[(< [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if +@defproc[(< [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if the arguments in the given order are in strictly increasing, - @scheme[#f] otherwise. + @racket[#f] otherwise. @mz-examples[(< 1 1) (< 1 2 3) (< 1 +inf.0) (< 1 +nan.0)]} -@defproc[(<= [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] +@defproc[(<= [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if the arguments in the given order are in non-decreasing, - @scheme[#f] otherwise. + @racket[#f] otherwise. @mz-examples[(<= 1 1) (<= 1 2 1)]} -@defproc[(> [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] if +@defproc[(> [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if the arguments in the given order are in strictly decreasing, - @scheme[#f] otherwise. + @racket[#f] otherwise. @mz-examples[(> 1 1) (> 3 2 1) (> +inf.0 1) (< +nan.0 1)]} -@defproc[(>= [x real?] [y real?] ...+) boolean?]{ Returns @scheme[#t] +@defproc[(>= [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] if the arguments in the given order are in non-increasing, - @scheme[#f] otherwise. + @racket[#f] otherwise. @mz-examples[(>= 1 1) (>= 1 2 1)]} @@ -415,45 +415,45 @@ used. @section{Powers and Roots} @defproc[(sqrt [z number?]) number?]{ Returns the principal - @as-index{square root} of @scheme[z]. The result is exact if - @scheme[z] is exact and @scheme[z]'s square root is rational. See - also @scheme[integer-sqrt]. + @as-index{square root} of @racket[z]. The result is exact if + @racket[z] is exact and @racket[z]'s square root is rational. See + also @racket[integer-sqrt]. @mz-examples[(sqrt 4/9) (sqrt 2) (sqrt -1)]} -@defproc[(integer-sqrt [n integer?]) complex?]{ Returns @scheme[(floor - (sqrt n))] for positive @scheme[n]. For negative @scheme[n], the result is - @scheme[(* (integer-sqrt (- n)) 0+i)]. +@defproc[(integer-sqrt [n integer?]) complex?]{ Returns @racket[(floor + (sqrt n))] for positive @racket[n]. For negative @racket[n], the result is + @racket[(* (integer-sqrt (- n)) 0+i)]. @mz-examples[(integer-sqrt 4.0) (integer-sqrt 5)]} @defproc[(integer-sqrt/remainder [n integer?]) (values integer? integer?)]{ - Returns @scheme[(integer-sqrt n)] and @scheme[(- n (expt + Returns @racket[(integer-sqrt n)] and @racket[(- n (expt (integer-sqrt n) 2))]. @mz-examples[(integer-sqrt/remainder 4.0) (integer-sqrt/remainder 5)]} -@defproc[(expt [z number?] [w number?]) number?]{ Returns @scheme[z] - raised to the power of @scheme[w]. If @scheme[w] is exact @scheme[0], - the result is @scheme[1]. If @scheme[z] is exact @scheme[0] and - @scheme[w] is negative, the @exnraise[exn:fail:contract]. +@defproc[(expt [z number?] [w number?]) number?]{ Returns @racket[z] + raised to the power of @racket[w]. If @racket[w] is exact @racket[0], + the result is @racket[1]. If @racket[z] is exact @racket[0] and + @racket[w] is negative, the @exnraise[exn:fail:contract]. @mz-examples[(expt 2 3) (expt 4 0.5) (expt +inf.0 0)]} @defproc[(exp [z number?]) number?]{ Returns Euler's number raised to the - power of @scheme[z]. The result is normally inexact, but it is - @scheme[1] when @scheme[z] is an exact @scheme[0]. + power of @racket[z]. The result is normally inexact, but it is + @racket[1] when @racket[z] is an exact @racket[0]. @mz-examples[(exp 1) (exp 2+3i) (exp 0)]} @defproc[(log [z number?]) number?]{ Returns the natural logarithm of - @scheme[z]. The result is normally inexact, but it is - @scheme[0] when @scheme[z] is an exact @scheme[1]. When @scheme[z] - is exact @scheme[0], @exnraise[exn:fail:contract:divide-by-zero]. + @racket[z]. The result is normally inexact, but it is + @racket[0] when @racket[z] is an exact @racket[1]. When @racket[z] + is exact @racket[0], @exnraise[exn:fail:contract:divide-by-zero]. @mz-examples[(log (exp 1)) (log 2+3i) (log 1)]} @@ -461,31 +461,31 @@ used. @; ------------------------------------------------------------------------ @section{Trignometric Functions} -@defproc[(sin [z number?]) number?]{ Returns the sine of @scheme[z], where - @scheme[z] is in radians. +@defproc[(sin [z number?]) number?]{ Returns the sine of @racket[z], where + @racket[z] is in radians. @mz-examples[(sin 3.14159) (sin 1+05.i)]} -@defproc[(cos [z number?]) number?]{ Returns the cosine of @scheme[z], - where @scheme[z] is in radians. +@defproc[(cos [z number?]) number?]{ Returns the cosine of @racket[z], + where @racket[z] is in radians. @mz-examples[(cos 3.14159) (cos 1+05.i)]} -@defproc[(tan [z number?]) number?]{ Returns the tangent of @scheme[z], - where @scheme[z] is in radians. +@defproc[(tan [z number?]) number?]{ Returns the tangent of @racket[z], + where @racket[z] is in radians. @mz-examples[(tan 0.7854) (tan 1+05.i)]} -@defproc[(asin [z number?]) number?]{ Returns the arcsin in radians of @scheme[z]. +@defproc[(asin [z number?]) number?]{ Returns the arcsin in radians of @racket[z]. @mz-examples[(asin 0.25) (asin 1+05.i)]} @defproc[(acos [z number?]) number?]{ Returns the arccosine in radians - of @scheme[z]. + of @racket[z]. @mz-examples[(acos 0.25) (acos 1+05.i)]} @@ -494,15 +494,15 @@ used. [(atan [y real?] [x real?]) number?])]{ In the one-argument case, returns the arctangent of the inexact -approximation of @scheme[z], except that the result is an exact -@scheme[0] for an exact @scheme[0] argument. +approximation of @racket[z], except that the result is an exact +@racket[0] for an exact @racket[0] argument. -In the two-argument case, the result is roughly the same as @scheme[(/ -(exact->inexact y) (exact->inexact x))], but the signs of @scheme[y] -and @scheme[x] determine the quadrant of the result. Moreover, a -suitable angle is returned when @scheme[y] divided by @scheme[x] -produces @scheme[+nan.0] in the case that neither @scheme[y] nor -@scheme[x] is @scheme[+nan.0]. +In the two-argument case, the result is roughly the same as @racket[(/ +(exact->inexact y) (exact->inexact x))], but the signs of @racket[y] +and @racket[x] determine the quadrant of the result. Moreover, a +suitable angle is returned when @racket[y] divided by @racket[x] +produces @racket[+nan.0] in the case that neither @racket[y] nor +@racket[x] is @racket[+nan.0]. @mz-examples[(atan 0.5) (atan 2 1) (atan -2 -1) (atan 1+05.i) (atan +inf.0 -inf.0)]} @@ -510,13 +510,13 @@ produces @scheme[+nan.0] in the case that neither @scheme[y] nor @section{Complex Numbers} @defproc[(make-rectangular [x real?] [y real?]) number?]{ Returns - @scheme[(+ x (* y 0+1i))]. + @racket[(+ x (* y 0+1i))]. @mz-examples[(make-rectangular 3 4.0)]} @defproc[(make-polar [magnitude real?] [angle real?]) number?]{ Returns - @scheme[(+ (* magnitude (cos angle)) (* magnitude (sin angle) 0+1i))]. + @racket[(+ (* magnitude (cos angle)) (* magnitude (sin angle) 0+1i))]. @mz-examples[#:eval math-eval (make-polar 10 (* pi 1/2)) @@ -524,26 +524,26 @@ produces @scheme[+nan.0] in the case that neither @scheme[y] nor @defproc[(real-part [z number?]) real?]{ Returns the real part of - the complex number @scheme[z] in rectangle coordinates. + the complex number @racket[z] in rectangle coordinates. @mz-examples[(real-part 3+4i) (real-part 5.0)]} @defproc[(imag-part [z number?]) real?]{ Returns the imaginary part of - the complex number @scheme[z] in rectangle coordinates. + the complex number @racket[z] in rectangle coordinates. @mz-examples[(imag-part 3+4i) (imag-part 5.0) (imag-part 5.0+0.0i)]} @defproc[(magnitude [z number?]) (and/c real? (not/c negative?))]{ - Returns the magnitude of the complex number @scheme[z] in polar + Returns the magnitude of the complex number @racket[z] in polar coordinates. @mz-examples[(magnitude -3) (magnitude 3.0) (magnitude 3+4i)]} @defproc[(angle [z number?]) real?]{ Returns the angle of - the complex number @scheme[z] in polar coordinates. + the complex number @racket[z] in polar coordinates. @mz-examples[(angle -3) (angle 3.0) (angle 3+4i) (angle +inf.0+inf.0i)]} @@ -553,31 +553,31 @@ produces @scheme[+nan.0] in the case that neither @scheme[y] nor @section-index{logical operators} @defproc[(bitwise-ior [n exact-integer?] ...) exact-integer?]{ Returns - the bitwise ``inclusive or'' of the @scheme[n]s in their (semi-infinite) + the bitwise ``inclusive or'' of the @racket[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the - result is @scheme[0]. + result is @racket[0]. @mz-examples[(bitwise-ior 1 2) (bitwise-ior -32 1)]} @defproc[(bitwise-and [n exact-integer?] ...) exact-integer?]{ Returns - the bitwise ``and'' of the @scheme[n]s in their (semi-infinite) two's + the bitwise ``and'' of the @racket[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the result - is @scheme[-1]. + is @racket[-1]. @mz-examples[(bitwise-and 1 2) (bitwise-and -32 -1)]} @defproc[(bitwise-xor [n exact-integer?] ...) exact-integer?]{ Returns - the bitwise ``exclusive or'' of the @scheme[n]s in their (semi-infinite) + the bitwise ``exclusive or'' of the @racket[n]s in their (semi-infinite) two's complement representation. If no arguments are provided, the - result is @scheme[0]. + result is @racket[0]. @mz-examples[(bitwise-xor 1 5) (bitwise-xor -32 -1)]} @defproc[(bitwise-not [n exact-integer?]) exact-integer?]{ Returns the - bitwise ``not'' of @scheme[n] in its (semi-infinite) two's complement + bitwise ``not'' of @racket[n] in its (semi-infinite) two's complement representation. @mz-examples[(bitwise-not 5) (bitwise-not -1)]} @@ -586,12 +586,12 @@ produces @scheme[+nan.0] in the case that neither @scheme[y] nor @defproc[(bitwise-bit-set? [n exact-integer?] [m exact-nonnegative-integer?]) boolean?]{ -Returns @scheme[#t] when the @scheme[m]th bit of @scheme[n] is set in @scheme[n]'s +Returns @racket[#t] when the @racket[m]th bit of @racket[n] is set in @racket[n]'s (semi-infinite) two's complement representation. This operation is equivalent to -@scheme[(not (zero? (bitwise-and n (arithmetic-shift 1 m))))], -but it is faster and runs in constant time when @scheme[n] is positive. +@racket[(not (zero? (bitwise-and n (arithmetic-shift 1 m))))], +but it is faster and runs in constant time when @racket[n] is positive. @mz-examples[(bitwise-bit-set? 5 0) (bitwise-bit-set? 5 2) (bitwise-bit-set? -5 (expt 2 700))]} @@ -602,18 +602,18 @@ but it is faster and runs in constant time when @scheme[n] is positive. (start . <= . end))]) exact-integer?]{ -Extracts the bits between position @scheme[start] and @scheme[(- end 1)] (inclusive) -from @scheme[n] and shifts them down to the least significant portion of the number. +Extracts the bits between position @racket[start] and @racket[(- end 1)] (inclusive) +from @racket[n] and shifts them down to the least significant portion of the number. This operation is equivalent to the computation -@schemeblock[ +@racketblock[ (bitwise-and (sub1 (arithmetic-shift 1 (- end start))) (arithmetic-shift n (- start))) ] -but it runs in constant time when @scheme[n] is positive, @scheme[start] and -@scheme[end] are fixnums, and @scheme[(- end start)] is no more than +but it runs in constant time when @racket[n] is positive, @racket[start] and +@racket[end] are fixnums, and @racket[(- end start)] is no more than the maximum width of a fixnum. Each pair of examples below uses the same numbers, showing the result @@ -629,19 +629,19 @@ both in binary and as integers. @defproc[(arithmetic-shift [n exact-integer?] [m exact-integer?]) - exact-integer?]{ Returns the bitwise ``shift'' of @scheme[n] in its - (semi-infinite) two's complement representation. If @scheme[m] is - non-negative, the integer @scheme[n] is shifted left by @scheme[m] bits; - i.e., @scheme[m] new zeros are introduced as rightmost digits. If - @scheme[m] is negative, @scheme[n] is shifted right by @scheme[(- m)] - bits; i.e., the rightmost @scheme[m] digits are dropped. + exact-integer?]{ Returns the bitwise ``shift'' of @racket[n] in its + (semi-infinite) two's complement representation. If @racket[m] is + non-negative, the integer @racket[n] is shifted left by @racket[m] bits; + i.e., @racket[m] new zeros are introduced as rightmost digits. If + @racket[m] is negative, @racket[n] is shifted right by @racket[(- m)] + bits; i.e., the rightmost @racket[m] digits are dropped. @mz-examples[(arithmetic-shift 1 10) (arithmetic-shift 255 -3)]} @defproc[(integer-length [n exact-integer?]) exact-integer?]{ Returns the number of bits in the (semi-infinite) two's complement - representation of @scheme[n] after removing all leading zeros (for - non-negative @scheme[n]) or ones (for negative @scheme[n]). + representation of @racket[n] after removing all leading zeros (for + non-negative @racket[n]) or ones (for negative @racket[n]). @mz-examples[(integer-length 8) (integer-length -8)]} @@ -656,14 +656,14 @@ both in binary and as integers. (current-pseudo-random-generator)]) (and/c real? inexact? (>/c 0) (vector [generator pseudo-random-generator?]) vector?]{ Produces a vector that represents the complete internal state of -@scheme[generator]. The vector is suitable as an argument to -@scheme[vector->pseudo-random-generator] to recreate the generator in +@racket[generator]. The vector is suitable as an argument to +@racket[vector->pseudo-random-generator] to recreate the generator in its current state (across runs and across platforms).} @@ -710,10 +710,10 @@ its current state (across runs and across platforms).} pseudo-random-generator?]{ Produces a pseudo-random number generator whose internal state -corresponds to @scheme[vec]. The vector @scheme[vec] must contain six +corresponds to @racket[vec]. The vector @racket[vec] must contain six exact integers; the first three integers must be in the range -@scheme[0] to @scheme[4294967086], inclusive; the last three integers -must be in the range @scheme[0] to @scheme[4294944442], inclusive; at +@racket[0] to @racket[4294967086], inclusive; the last three integers +must be in the range @racket[0] to @racket[4294944442], inclusive; at least one of the first three integers must be non-zero; and at least one of the last three integers must be non-zero.} @@ -721,8 +721,8 @@ one of the last three integers must be non-zero.} [vec vector?]) void?]{ -Like @scheme[vector->pseudo-random-generator], but changes -@scheme[generator] to the given state, instead of creating a new +Like @racket[vector->pseudo-random-generator], but changes +@racket[generator] to the given state, instead of creating a new generator.} @; ------------------------------------------------------------------------ @@ -736,9 +736,9 @@ generator.} @defproc[(number->string [z number?] [radix (or/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, - @scheme[radix] must be @scheme[10], otherwise the + Returns a string that is the printed form of @racket[z] + in the base specific by @racket[radix]. If @racket[z] is inexact, + @racket[radix] must be @racket[10], otherwise the @exnraise[exn:fail:contract]. @mz-examples[(number->string 3.0) (number->string 255 8)]} @@ -747,10 +747,10 @@ generator.} @defproc[(string->number [s string?] [radix (integer-in 2 16) 10]) (or/c number? #f)]{ -Reads and returns a number datum from @scheme[s] (see -@secref["parse-number"]), returning @scheme[#f] if @scheme[s] does not +Reads and returns a number datum from @racket[s] (see +@secref["parse-number"]), returning @racket[#f] if @racket[s] does not parse exactly as a number datum (with no whitespace). The optional -@scheme[radix] argument specifies the default base for the number, +@racket[radix] argument specifies the default base for the number, which can be overriden by @litchar{#b}, @litchar{#o}, @litchar{#d}, or @litchar{#x} in the string. @@ -761,16 +761,16 @@ which can be overriden by @litchar{#b}, @litchar{#o}, @litchar{#d}, or @defproc[(real->decimal-string [n real?] [decimal-digits exact-nonnegative-integer? 2]) string?]{ -Prints @scheme[n] into a string and returns the string. The printed -form of @scheme[n] shows exactly @scheme[decimal-digits] digits after -the decimal point. The printed for uses a minus sign if @scheme[n] is -negative, and it does not use a plus sign if @scheme[n] is positive. +Prints @racket[n] into a string and returns the string. The printed +form of @racket[n] shows exactly @racket[decimal-digits] digits after +the decimal point. The printed for uses a minus sign if @racket[n] is +negative, and it does not use a plus sign if @racket[n] is positive. -Before printing, @scheme[n] is converted to an exact number, -multiplied by @scheme[(expt 10 decimal-digits)], rounded, and then -divided again by @scheme[(expt 10 decimal-digits)]. The result of ths +Before printing, @racket[n] is converted to an exact number, +multiplied by @racket[(expt 10 decimal-digits)], rounded, and then +divided again by @racket[(expt 10 decimal-digits)]. The result of ths process is an exact number whose decimal representation has no more -than @scheme[decimal-digits] digits after the decimal (and it is +than @racket[decimal-digits] digits after the decimal (and it is padded with trailing zeros if necessary). @mz-examples[ @@ -786,12 +786,12 @@ padded with trailing zeros if necessary). [end exact-nonnegative-integer? (bytes-length bstr)]) exact-integer?]{ -Converts the machine-format number encoded in @scheme[bstr] to an -exact integer. The @scheme[start] and @scheme[end] arguments specify -the substring to decode, where @scheme[(- end start)] must be -@scheme[2], @scheme[4], or @scheme[8]. If @scheme[signed?] is true, +Converts the machine-format number encoded in @racket[bstr] to an +exact integer. The @racket[start] and @racket[end] arguments specify +the substring to decode, where @racket[(- end start)] must be +@racket[2], @racket[4], or @racket[8]. If @racket[signed?] is true, then the bytes are decoded as a two's-complement number, otherwise it -is decoded as an unsigned integer. If @scheme[big-endian?] is true, +is decoded as an unsigned integer. If @racket[big-endian?] is true, then the first character's ASCII value provides the most significant eight bits of the number, otherwise the first character provides the least-significant eight bits, and so on.} @@ -807,23 +807,23 @@ least-significant eight bits, and so on.} [start exact-nonnegative-integer? 0]) bytes?]{ -Converts the exact integer @scheme[n] to a machine-format number -encoded in a byte string of length @scheme[size-n], which must be -@scheme[2], @scheme[4], or @scheme[8]. If @scheme[signed?] is true, +Converts the exact integer @racket[n] to a machine-format number +encoded in a byte string of length @racket[size-n], which must be +@racket[2], @racket[4], or @racket[8]. If @racket[signed?] is true, then the number is encoded as two's complement, otherwise it is -encoded as an unsigned bit stream. If @scheme[big-endian?] is true, +encoded as an unsigned bit stream. If @racket[big-endian?] is true, then the most significant eight bits of the number are encoded in the first character of the resulting byte string, otherwise the least-significant bits are encoded in the first byte, and so on. -The @scheme[dest-bstr] argument must be a mutable byte string of -length @scheme[size-n]. The encoding of @scheme[n] is written into -@scheme[dest-bstr] starting at offset @scheme[start], and -@scheme[dest-bstr] is returned as the result. +The @racket[dest-bstr] argument must be a mutable byte string of +length @racket[size-n]. The encoding of @racket[n] is written into +@racket[dest-bstr] starting at offset @racket[start], and +@racket[dest-bstr] is returned as the result. -If @scheme[n] cannot be encoded in a string of the requested size and -format, the @exnraise[exn:fail:contract]. If @scheme[dest-bstr] is not -of length @scheme[size-n], the @exnraise[exn:fail:contract].} +If @racket[n] cannot be encoded in a string of the requested size and +format, the @exnraise[exn:fail:contract]. If @racket[dest-bstr] is not +of length @racket[size-n], the @exnraise[exn:fail:contract].} @defproc[(floating-point-bytes->real [bstr bytes?] @@ -832,10 +832,10 @@ of length @scheme[size-n], the @exnraise[exn:fail:contract].} [end exact-nonnegative-integer? (bytes-length bstr)]) (and/c real? inexact?)]{ -Converts the IEEE floating-point number encoded in @scheme[bstr] from -position @scheme[start] (inclusive) to @scheme[end] (exclusive) to an -inexact real number. The difference between @scheme[start] an -@scheme[end] must be either 4 or 8 bytes. If @scheme[big-endian?] is +Converts the IEEE floating-point number encoded in @racket[bstr] from +position @racket[start] (inclusive) to @racket[end] (exclusive) to an +inexact real number. The difference between @racket[start] an +@racket[end] must be either 4 or 8 bytes. If @racket[big-endian?] is true, then the first byte's ASCII value provides the most significant eight bits of the IEEE representation, otherwise the first byte provides the least-significant eight bits, and so on.} @@ -850,26 +850,26 @@ provides the least-significant eight bits, and so on.} [start exact-nonnegative-integer? 0]) bytes?]{ -Converts the real number @scheme[x] to its IEEE representation in a -byte string of length @scheme[size-n], which must be @scheme[4] or -@scheme[8]. If @scheme[big-endian?] is true, then the most significant +Converts the real number @racket[x] to its IEEE representation in a +byte string of length @racket[size-n], which must be @racket[4] or +@racket[8]. If @racket[big-endian?] is true, then the most significant eight bits of the number are encoded in the first byte of the resulting byte string, otherwise the least-significant bits are encoded in the first character, and so on. -The @scheme[dest-bstr] argument must be a mutable byte string of -length @scheme[size-n]. The encoding of @scheme[n] is written into -@scheme[dest-bstr] starting with byte @scheme[start], and -@scheme[dest-bstr] is returned as the result. +The @racket[dest-bstr] argument must be a mutable byte string of +length @racket[size-n]. The encoding of @racket[n] is written into +@racket[dest-bstr] starting with byte @racket[start], and +@racket[dest-bstr] is returned as the result. -If @scheme[dest-bstr] is provided and it has less than @scheme[start] -plus @scheme[size-n] bytes, the @exnraise[exn:fail:contract].} +If @racket[dest-bstr] is provided and it has less than @racket[start] +plus @racket[size-n] bytes, the @exnraise[exn:fail:contract].} @defproc[(system-big-endian?) boolean?]{ -Returns @scheme[#t] if the native encoding of numbers is big-endian -for the machine running Scheme, @scheme[#f] if the native encoding +Returns @racket[#t] if the native encoding of numbers is big-endian +for the machine running Racket, @racket[#f] if the native encoding is little-endian.} @; ------------------------------------------------------------------------ @@ -877,11 +877,11 @@ is little-endian.} @defmodule[racket/flonum] -The @schememodname[racket/flonum] library provides operations like -@scheme[fl+] that consume and produce only real @tech{inexact +The @racketmodname[racket/flonum] library provides operations like +@racket[fl+] that consume and produce only real @tech{inexact numbers}, which are also known as @deftech{flonums}. Flonum-specific operations provide can better performance when used consistently, and -they are as safe as generic operations like @scheme[+]. +they are as safe as generic operations like @racket[+]. @guidealso["fixnums+flonums"] @@ -895,7 +895,7 @@ they are as safe as generic operations like @scheme[+]. @defproc[(flabs [a inexact-real?]) inexact-real?] )]{ -Like @scheme[+], @scheme[-], @scheme[*], @scheme[/], and @scheme[abs], +Like @racket[+], @racket[-], @racket[*], @racket[/], and @racket[abs], but constrained to consume @tech{flonums}. The result is always a @tech{flonum}.} @@ -909,8 +909,8 @@ but constrained to consume @tech{flonums}. The result is always a @defproc[(flmax [a inexact-real?][b inexact-real?]) inexact-real?] )]{ -Like @scheme[=], @scheme[<], @scheme[>], @scheme[<=], @scheme[>=], -@scheme[min], and @scheme[max], but constrained to consume +Like @racket[=], @racket[<], @racket[>], @racket[<=], @racket[>=], +@racket[min], and @racket[max], but constrained to consume @tech{flonums}.} @deftogether[( @@ -920,8 +920,8 @@ Like @scheme[=], @scheme[<], @scheme[>], @scheme[<=], @scheme[>=], @defproc[(fltruncate [a inexact-real?]) inexact-real?] )]{ -Like @scheme[round], @scheme[floor], @scheme[ceiling], and -@scheme[truncate], but constrained to consume @tech{flonums}.} +Like @racket[round], @racket[floor], @racket[ceiling], and +@racket[truncate], but constrained to consume @tech{flonums}.} @deftogether[( @defproc[(flsin [a inexact-real?]) inexact-real?] @@ -935,16 +935,16 @@ Like @scheme[round], @scheme[floor], @scheme[ceiling], and @defproc[(flsqrt [a inexact-real?]) inexact-real?] )]{ -Like @scheme[sin], @scheme[cos], @scheme[tan], @scheme[asin], -@scheme[acos], @scheme[atan], @scheme[log], @scheme[exp], and -@scheme[flsqrt], but constrained to consume and produce -@tech{flonums}. The result is @scheme[+nan.0] when a number outside -the range @scheme[-1.0] to @scheme[1.0] is given to @scheme[flasin] or -@scheme[flacos], or when a negative number is given to @scheme[fllog] -or @scheme[flsqrt].} +Like @racket[sin], @racket[cos], @racket[tan], @racket[asin], +@racket[acos], @racket[atan], @racket[log], @racket[exp], and +@racket[flsqrt], but constrained to consume and produce +@tech{flonums}. The result is @racket[+nan.0] when a number outside +the range @racket[-1.0] to @racket[1.0] is given to @racket[flasin] or +@racket[flacos], or when a negative number is given to @racket[fllog] +or @racket[flsqrt].} @defproc[(->fl [a exact-integer?]) inexact-real?]{ -Like @scheme[exact->inexact], but constrained to consume exact integers, +Like @racket[exact->inexact], but constrained to consume exact integers, so the result is always a @tech{flonum}. } @@ -953,22 +953,22 @@ so the result is always a @tech{flonum}. A @deftech{flvector} is like a @tech{vector}, but it holds only inexact real numbers. This representation can be more compact, and unsafe operations on @tech{flvector}s (see -@schememodname[racket/unsafe/ops]) can execute more efficiently than +@racketmodname[racket/unsafe/ops]) can execute more efficiently than unsafe operations on @tech{vectors} of inexact reals. -An f64vector as provided by @schememodname[ffi/vector] stores the +An f64vector as provided by @racketmodname[ffi/vector] stores the same kinds of values as an @tech{flvector}, but with extra indirections that make f64vectors more convenient for working with foreign libraries. The lack of indirections make unsafe @tech{flvector} access more efficient. -Two @tech{flvectors} are @scheme[equal?] if they have the same length, +Two @tech{flvectors} are @racket[equal?] if they have the same length, and if the values in corresponding slots of the @tech{flvectors} are -@scheme[equal?]. +@racket[equal?]. @defproc[(flvector? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{flvector}, @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @tech{flvector}, @racket[#f] otherwise.} @defproc[(flvector [x inexact-real?] ...) flvector?]{ @@ -978,52 +978,52 @@ Creates a @tech{flvector} containing the given inexact real numbers.} [x inexact-real? 0.0]) flvector?]{ -Creates a @tech{flvector} with @scheme[size] elements, where every -slot in the @tech{flvector} is filled with @scheme[x].} +Creates a @tech{flvector} with @racket[size] elements, where every +slot in the @tech{flvector} is filled with @racket[x].} @defproc[(flvector-length [vec flvector?]) exact-nonnegative-integer?]{ -Returns the length of @scheme[vec] (i.e., the number of slots in the +Returns the length of @racket[vec] (i.e., the number of slots in the @tech{flvector}).} @defproc[(flvector-ref [vec flvector?] [pos exact-nonnegative-integer?]) inexact-real?]{ -Returns the inexact real number in slot @scheme[pos] of -@scheme[vec]. The first slot is position @scheme[0], and the last slot -is one less than @scheme[(flvector-length vec)].} +Returns the inexact real number in slot @racket[pos] of +@racket[vec]. The first slot is position @racket[0], and the last slot +is one less than @racket[(flvector-length vec)].} @defproc[(flvector-set! [vec flvector?] [pos exact-nonnegative-integer?] [x inexact-real?]) inexact-real?]{ -Sets the inexact real number in slot @scheme[pos] of @scheme[vec]. The -first slot is position @scheme[0], and the last slot is one less than -@scheme[(flvector-length vec)].} +Sets the inexact real number in slot @racket[pos] of @racket[vec]. The +first slot is position @racket[0], and the last slot is one less than +@racket[(flvector-length vec)].} @section{Fixnum Operations} @defmodule[racket/fixnum] -The @schememodname[racket/fixnum] library provides operations like -@scheme[fx+] that consume and produce only fixnums. The operations in +The @racketmodname[racket/fixnum] library provides operations like +@racket[fx+] that consume and produce only fixnums. The operations in this library are meant to be safe versions of unsafe operations like -@scheme[unsafe-fx+]. These safe operations are generally no faster -than using generic primitives like @scheme[+]. +@racket[unsafe-fx+]. These safe operations are generally no faster +than using generic primitives like @racket[+]. -The expected use of the @schememodname[racket/fixnum] library is for -code where the @scheme[require] of @schememodname[racket/fixnum] is +The expected use of the @racketmodname[racket/fixnum] library is for +code where the @racket[require] of @racketmodname[racket/fixnum] is replaced with -@schemeblock[(require (filtered-in +@racketblock[(require (filtered-in (λ (name) (regexp-replace #rx"unsafe-" name "")) racket/unsafe/ops))] to drop in unsafe versions of the library. Alternately, when encountering crashes with code that uses unsafe fixnum operations, use -the @schememodname[racket/fixnum] library to help debug the problems. +the @racketmodname[racket/fixnum] library to help debug the problems. @deftogether[( @defproc[(fx+ [a fixnum?][b fixnum?]) fixnum?] @@ -1035,10 +1035,10 @@ the @schememodname[racket/fixnum] library to help debug the problems. @defproc[(fxabs [a fixnum?]) fixnum?] )]{ -Safe versions of @scheme[unsafe-fx+], @scheme[unsafe-fx-], -@scheme[unsafe-fx*], @scheme[unsafe-fxquotient], -@scheme[unsafe-fxremainder], @scheme[unsafe-fxmodulo], and -@scheme[unsafe-fxabs]. The +Safe versions of @racket[unsafe-fx+], @racket[unsafe-fx-], +@racket[unsafe-fx*], @racket[unsafe-fxquotient], +@racket[unsafe-fxremainder], @racket[unsafe-fxmodulo], and +@racket[unsafe-fxabs]. The @exnraise[exn:fail:contract:non-fixnum-result] if the arithmetic result would not be a fixnum.} @@ -1052,9 +1052,9 @@ result would not be a fixnum.} @defproc[(fxrshift [a fixnum?][b fixnum?]) fixnum?] )]{ -Safe versions of @scheme[unsafe-fxand], @scheme[unsafe-fxior], -@scheme[unsafe-fxxor], @scheme[unsafe-fxnot], -@scheme[unsafe-fxlshift], and @scheme[unsafe-fxrshift]. The +Safe versions of @racket[unsafe-fxand], @racket[unsafe-fxior], +@racket[unsafe-fxxor], @racket[unsafe-fxnot], +@racket[unsafe-fxlshift], and @racket[unsafe-fxrshift]. The @exnraise[exn:fail:contract:non-fixnum-result] if the arithmetic result would not be a fixnum.} @@ -1069,9 +1069,9 @@ result would not be a fixnum.} @defproc[(fxmax [a fixnum?][b fixnum?]) fixnum?] )]{ -Safe versions of @scheme[unsafe-fx=], @scheme[unsafe-fx<], - @scheme[unsafe-fx>], @scheme[unsafe-fx<=], @scheme[unsafe-fx>=], - @scheme[unsafe-fxmin], and @scheme[unsafe-fxmax].} +Safe versions of @racket[unsafe-fx=], @racket[unsafe-fx<], + @racket[unsafe-fx>], @racket[unsafe-fx<=], @racket[unsafe-fx>=], + @racket[unsafe-fxmin], and @racket[unsafe-fxmax].} @@ -1087,11 +1087,11 @@ diameter: @number->string[pi].} @defproc[(sqr [z number?]) number?]{ -Returns @scheme[(* z z)].} +Returns @racket[(* z z)].} @defproc[(sgn [x real?]) (or/c 1 0 -1 1.0 0.0 -1.0)]{ -Returns the sign of @scheme[x] as either @math{-1}, @math{0}, or +Returns the sign of @racket[x] as either @math{-1}, @math{0}, or @math{1}. @mz-examples[ @@ -1103,7 +1103,7 @@ Returns the sign of @scheme[x] as either @math{-1}, @math{0}, or @defproc[(conjugate [z number?]) number?]{ -Returns the complex conjugate of @scheme[z]. +Returns the complex conjugate of @racket[z]. @mz-examples[ #:eval math-eval @@ -1113,22 +1113,22 @@ Returns the complex conjugate of @scheme[z]. @defproc[(sinh [z number?]) number?]{ -Returns the hyperbolic sine of @scheme[z].} +Returns the hyperbolic sine of @racket[z].} @defproc[(cosh [z number?]) number?]{ -Returns the hyperbolic cosine of @scheme[z].} +Returns the hyperbolic cosine of @racket[z].} @defproc[(tanh [z number?]) number?]{ -Returns the hyperbolic tangent of @scheme[z].} +Returns the hyperbolic tangent of @racket[z].} @defproc[(order-of-magnitude [r (and/c real? positive?)]) (and/c exact? integer?)]{ -Computes the greatest exact integer @scheme[m] such that: -@schemeblock[(<= (expt 10 m) +Computes the greatest exact integer @racket[m] such that: +@racketblock[(<= (expt 10 m) (inexact->exact r))] Hence also: -@schemeblock[(< (inexact->exact r) +@racketblock[(< (inexact->exact r) (expt 10 (add1 m)))] @mz-examples[#:eval math-eval diff --git a/collects/scribblings/reference/package.scrbl b/collects/scribblings/reference/package.scrbl index 3b8324bd15..05a9f2c3bf 100644 --- a/collects/scribblings/reference/package.scrbl +++ b/collects/scribblings/reference/package.scrbl @@ -5,7 +5,7 @@ @(define pack-eval (make-base-eval)) @interaction-eval[#:eval pack-eval (require racket/package)] -@title[#:tag "package"]{Limiting Scope: @scheme[define-package], @scheme[open-package], ...} +@title[#:tag "package"]{Limiting Scope: @racket[define-package], @racket[open-package], ...} @note-lib-only[racket/package] @@ -18,34 +18,34 @@ (code:line #:all-defined-except (id ...))])] )]{ -@margin-note{The @scheme[define-package] form is based on the @schemeidfont{module} +@margin-note{The @racket[define-package] form is based on the @racketidfont{module} form of Chez Scheme @cite["Waddell99"].} -The @scheme[define-package] form is similar to @scheme[module], except -that it can appear in any definition context. The @scheme[form]s -within a @scheme[define-package] form can be definitions or +The @racket[define-package] form is similar to @racket[module], except +that it can appear in any definition context. The @racket[form]s +within a @racket[define-package] form can be definitions or expressions; definitions are not visible outside the -@scheme[define-package] form, but @scheme[exports] determines a subset +@racket[define-package] form, but @racket[exports] determines a subset of the bindings that can be made visible outside the package using -the definition form @scheme[(open-package package-id)]. +the definition form @racket[(open-package package-id)]. -The @scheme[(id ...)] and @scheme[#:only (id ...)] @scheme[exports] -forms are equivalent: exactly the listed @scheme[id]s are -exported. The @scheme[#:all-defined] form exports all definitions from -the package body, and @scheme[#:all-defined-except (id ...)] exports -all definitions except the listed @scheme[id]s. +The @racket[(id ...)] and @racket[#:only (id ...)] @racket[exports] +forms are equivalent: exactly the listed @racket[id]s are +exported. The @racket[#:all-defined] form exports all definitions from +the package body, and @racket[#:all-defined-except (id ...)] exports +all definitions except the listed @racket[id]s. All of the usual definition forms work within a -@scheme[define-package] body, and such definitions are visible to all +@racket[define-package] body, and such definitions are visible to all expressions within the body (and, in particular, the definitions can -refer to each other). However, @scheme[define-package] handles -@scheme[define*], @scheme[define*-syntax], @scheme[define*-values], -@scheme[define*-syntaxes], and -@scheme[open*-package] specially: the bindings introduced by those -forms within a @scheme[define-package] body are visible only to -@scheme[form]s that appear later in the body, and they can shadow any -binding from preceding @scheme[form]s (even if the preceding binding -did not use one of the special @schemeidfont{*} definition forms). If +refer to each other). However, @racket[define-package] handles +@racket[define*], @racket[define*-syntax], @racket[define*-values], +@racket[define*-syntaxes], and +@racket[open*-package] specially: the bindings introduced by those +forms within a @racket[define-package] body are visible only to +@racket[form]s that appear later in the body, and they can shadow any +binding from preceding @racket[form]s (even if the preceding binding +did not use one of the special @racketidfont{*} definition forms). If an exported identifier is defined multiple times, the last definition is the exported one. @@ -70,17 +70,17 @@ little-russian-doll @defform[(package-begin form ...)]{ -Similar to @scheme[define-package], but it only limits the visible of -definitions without binding a package name. If the last @scheme[form] +Similar to @racket[define-package], but it only limits the visible of +definitions without binding a package name. If the last @racket[form] is an expression, then the expression is in @tech{tail position} for -the @scheme[package-begin] form, so that its result is the -@scheme[package-begin] result. +the @racket[package-begin] form, so that its result is the +@racket[package-begin] result. -A @scheme[package-begin] form can be used as an expression, but if it +A @racket[package-begin] form can be used as an expression, but if it is used in a context where definitions are allowed, then the definitions are essentially spliced into the enclosing context (though the defined bindings remain hidden outside the -@scheme[package-begin]). +@racket[package-begin]). @examples[ #:eval pack-eval @@ -98,10 +98,10 @@ secret @defidform[open*-package] )]{ -Equivalent to @scheme[define], @scheme[define-values], -@scheme[define-syntax], @scheme[define-syntaxes], -and @scheme[open-package], except within a -@scheme[define-package] or @scheme[package-begin] form, where they +Equivalent to @racket[define], @racket[define-values], +@racket[define-syntax], @racket[define-syntaxes], +and @racket[open-package], except within a +@racket[define-package] or @racket[package-begin] form, where they create bindings that are visible only to later body forms. @examples[ @@ -127,19 +127,19 @@ cookies @defproc[(package-original-identifiers [id identifier?]) (listof identifier?)] )]{ -The @scheme[package?], @scheme[package-exported-identifiers], and -@scheme[package-original-identifiers] functions are exported -@scheme[for-syntax] by @schememodname[racket/package]. +The @racket[package?], @racket[package-exported-identifiers], and +@racket[package-original-identifiers] functions are exported +@racket[for-syntax] by @racketmodname[racket/package]. -The @scheme[package?] predicate returns @scheme[#t] if @scheme[v] is a -package value as obtained by @scheme[syntax-local-value] on an +The @racket[package?] predicate returns @racket[#t] if @racket[v] is a +package value as obtained by @racket[syntax-local-value] on an identifier that is bound to a package. -Given such an identifier, the @scheme[package-exported-identifiers] +Given such an identifier, the @racket[package-exported-identifiers] function returns a list of identifiers that corresponding to the bindings that would be introduced by opening the package in the lexical context being expanded. The -@scheme[package-original-identifiers] function returns a parallel list +@racket[package-original-identifiers] function returns a parallel list of identifiers for existing bindings of package's exports.} @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/reference/promise.scrbl b/collects/scribblings/reference/promise.scrbl index c71cc43498..6960fd06ff 100644 --- a/collects/scribblings/reference/promise.scrbl +++ b/collects/scribblings/reference/promise.scrbl @@ -10,9 +10,6 @@ A @deftech{promise} encapsulates an expression to be evaluated on demand via @scheme[force]. After a promise has been @scheme[force]d, every later @scheme[force] of the promise produces the same result. -This module provides this functionality, and extends it to additional -kinds of promises with various evaluation strategies. - @defproc[(promise? [v any/c]) boolean?]{ @@ -31,18 +28,18 @@ This includes multiple values and exceptions.} @defform[(lazy body ...+)]{ Like @scheme[delay], if the last @scheme[body] produces a promise when -forced, then this promise is @scheme[force]d too to obtain a value. +forced, then this promise is @scheme[force]d, too, to obtain a value. In other words, this form creates a composable promise, where the computation of its body is ``attached'' to the computation of the -following promise and a single @scheme[force] iterates through the +following promise, and a single @scheme[force] iterates through the whole chain, tail-calling each step. Note that the last @scheme[body] of this form must produce a single -value --- but this value can itself be a @scheme[delay] promise that +value, but the value can itself be a @scheme[delay] promise that returns multiple values. -This form useful for implementing lazy libraries and languages, where -tail-calls can be wrapped in a promise.} +The @scheme[lazy] form useful for implementing lazy libraries and +languages, where tail calls can be wrapped in a promise.} @defproc[(force [v any/c]) any]{ @@ -57,9 +54,6 @@ the promise will raise the same exception every time. If @scheme[v] is @scheme[force]d again before the original call to @scheme[force] returns, then the @exnraise[exn:fail]. -Additional kinds of promises are also forced via @scheme[force]. See -below for further details. - If @scheme[v] is not a promise, then it is returned as the result.} @@ -78,56 +72,74 @@ Returns @scheme[#t] if @scheme[promise] is currently being forced. @defform[(delay/name body ...+)]{ -Creates a ``call by name'' promise, that is similar to +Creates a ``call-by-name'' promise that is similar to @scheme[delay]-promises, except that the resulting value is not -cached. It is essentially a thunk, wrapped in a way that -@scheme[force] recognizes. Note that if a @scheme[delay/name] promise -forces itself, no exception is raised. -@; TODO: clarify that the point is that code that is written using -@; `force', can be used with these promises too. +cached. This kind of promise is essentially a thunk that is wrapped +in a way that @scheme[force] recognizes. -Note that this promise is never considered ``running'' or ``forced'' -in the sense of @scheme[promise-running?] and -@scheme[promise-forced?].} +If a @scheme[delay/name] promise forces itself, no exception is +raised, the promise is never considered ``running'' or ``forced'' in +the sense of @scheme[promise-running?] and @scheme[promise-forced?].} @defform[(delay/sync body ...+)]{ -Conventional promises are not useful when multiple threads attempt to -force them: when a promise is running, any additional threads that -@scheme[force] it will get an exception. @scheme[delay/sync] is -useful for such cases: if a second thread attempts to @scheme[force] -such a promise, it will get blocked until the computation is done and -an answer is available. If @scheme[force] is used with the promise as -it is forced from the same thread, an exception is raised. +Produces a promise where an attempt to @scheme[force] the promise by a +thread other than one currently running the promise causes the +@scheme[force] to block until a result is available. This kind of +promise is also a @tech{synchronizable event} for use with +@racket[sync]; @racket[sync]ing on the promise does not @scheme[force] +it, but merely waits until a value is forced by another thread. -In addition, these promises can be used with @scheme[sync], which -blocks until it has been forced. Note that using @scheme[sync] this -way is passive in the sense that it does not trigger evaluation of the -promise.} +If a promise created by @scheme[delay/sync] is forced on a thread that +is already running the promise, an exception is raised in the same way +as for promises created with @scheme[delay].} -@defform[(delay/thread body ...+)]{ -@; TODO: document #:group keyword +@defform/subs[(delay/thread body/option ...+) + ([body/option body + (code:line #:group thread-group-expr)])]{ -This kind of promise begins the computation immediately, but this -happens on a separate thread. When the computation is done, the result -is cached as usual. Note that exceptions are caught as usual, and will -only be raised when @scheme[force]d. If such a promise is -@scheme[force]d before a value is ready, the calling thread will be -blocked until the computation terminates. These promises can also be -used with @scheme[sync].} +Like @scheme[delay/sync], but begins the computation immediately on a +newly created thread. The thread is created under the @tech{thread +group} specified by @scheme[thread-group-expr], which defaults to +@scheme[(make-thread-group)]. A @racket[#:group] specification can +appear at most once. -@defform[(delay/idle body ...+)]{ -@; TODO: document #:wait-for, #:work-while, #:tick, #:use keywords +Exceptions raised by the @racket[body]s are caught as usual and raised +only when the promise is @scheme[force]d.} -Similar to @scheme[delay/thread], but the computation thread gets to -work only when the process is otherwise idle, as determined by -@scheme[system-idle-evt], and the work is done in small runtime -fragements, making it overall not raise total CPU use or hurt -responsiveness. If the promise is @scheme[forced] before the -computation is done, it will run the rest of the computation immediately -without slicing the runtime. Using @scheme[sync] on these promises -blocks as is the case with @scheme[delay/sync], and this happens in a -passive way too, so the computation continues to work in low-priority. +@defform/subs[(delay/idle body/option ...+) + ([body/option body + (code:line #:wait-for wait-evt-expr) + (code:line #:work-while while-evt-expr) + (code:line #:tick tick-secs-expr) + (code:line #:use use-ratio-expr)])]{ + +Like @scheme[delay/thread], but with the following differences: + +@itemlist[ + + @item{the computation does not start until the event produced by + @scheme[wait-evt-expr] is ready, where the default is + @racket[(system-idle-evt)];} + + @item{the computation thread gets to work only when the process is + otherwise idle as determined by @scheme[while-evt-expr], which + also defaults to @racket[(system-idle-evt)];} + + @item{the thread is allowed to run only periodically: out of every + @scheme[tick-secs-expr] (defaults to @scheme[0.2]) seconds, the + thread is allowed to run @scheme[use-ratio-expr] (defaults to + @scheme[0.12]) of the time proportionally; i.e., the thread + runs for @scheme[(* tick-secs-expr use-ratio-expr)] seconds.} + +] + +If the promise is @scheme[forced] before the computation is done, it +runs the rest of the computation immediately without waiting on events +or periodically restricting evaluation. + +A @racket[#:wait-for], @racket[#:work-while], @racket[#:tick], or +@racket[#:use] specification can appear at most once. @;{ TODO: Say something on: diff --git a/collects/scribblings/reference/sandbox.scrbl b/collects/scribblings/reference/sandbox.scrbl index cab675a9cf..dc8bcf0c9c 100644 --- a/collects/scribblings/reference/sandbox.scrbl +++ b/collects/scribblings/reference/sandbox.scrbl @@ -515,7 +515,7 @@ inspector (see @racket[sandbox-make-code-inspector]) which prevents loading of untrusted bytecode files --- the sandbox is set-up to allow loading bytecode from files that are specified with @racket['read-bytecode]. This specification is given by default to -the PLT collection hierarchy (including user-specific libraries) and +the Racket collection hierarchy (including user-specific libraries) and to libraries that are explicitly specified in an @racket[#:allow-read] argument. (Note that this applies for loading bytecode files only, under a lower code inspector it is still impossible to use protected diff --git a/collects/scribblings/reference/startup.scrbl b/collects/scribblings/reference/startup.scrbl index 72880cda1c..aab4affba5 100644 --- a/collects/scribblings/reference/startup.scrbl +++ b/collects/scribblings/reference/startup.scrbl @@ -399,9 +399,6 @@ language specifies run-time configuration by ] -The @racketmodname[racket/base] and @racketmodname[racket] languages -do not currently specify a run-time configuration action. - A @racket['configure-runtime] query returns a list of vectors, instead of directly configuring the environment, so that the indicated modules to be bundled with a program when creating a stand-alone diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index a9996f0d50..014ed1a04a 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -538,7 +538,7 @@ corresponds to the default @tech{module name resolver}. with a @litchar{.}), then @racket[rel-string] names a file within the @filepath{mzlib} @tech{collection}. A @filepath{.ss} suffix is converted to @filepath{.rkt}. (This convention is for - compatibility with older version of PLT Racket.) + compatibility with older version of Racket.) @examples[ (code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:}) @@ -551,7 +551,7 @@ corresponds to the default @tech{module name resolver}. subcollection, etc., ending with a file name. No suffix is added automatically, but a @filepath{.ss} suffix is converted to @filepath{.rkt}. (This convention is for compatibility with older - version of PLT Racket.) + version of Racket.) @examples[ (code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:}) diff --git a/collects/scribblings/reference/threads.scrbl b/collects/scribblings/reference/threads.scrbl index 539360c227..bf1b331e7c 100644 --- a/collects/scribblings/reference/threads.scrbl +++ b/collects/scribblings/reference/threads.scrbl @@ -3,13 +3,13 @@ @title[#:tag "threads"]{Threads} -See @secref["thread-model"] for basic information on the PLT Racket +See @secref["thread-model"] for basic information on the Racket thread model. See also @secref["futures"]. When a thread is created, it is placed into the management of the -@tech{current custodian} and added to the current thread group (see -@secref["threadgroups"]). A thread can have any number of custodian -managers added through @racket[thread-resume]. +@tech{current custodian} and added to the current @tech{thread +group}. A thread can have any number of custodian managers added +through @racket[thread-resume]. A thread that has not terminated can be garbage collected (see @secref["gc-model"]) if it is unreachable and suspended or if it is diff --git a/collects/scribblings/reference/unsafe.scrbl b/collects/scribblings/reference/unsafe.scrbl index 30ccae242b..9875ae2ec9 100644 --- a/collects/scribblings/reference/unsafe.scrbl +++ b/collects/scribblings/reference/unsafe.scrbl @@ -12,7 +12,7 @@ @defmodule[racket/unsafe/ops] All fuctions and forms provided by @schememodname[racket/base] and -@schememodname[scheme] check their arguments to ensure that the +@schememodname[racket] check their arguments to ensure that the arguments conform to contracts and other constraints. For example, @scheme[vector-ref] checks its arguments to ensure that the first argument is a vector, that the second argument is an exact integer, @@ -26,9 +26,9 @@ faster code. If arguments violate an unsafe function's constraints, the function's behavior and result is unpredictable, and the entire system can crash or become corrupted. -All of the exported bindings of @schememodname[scheme] are protected -in the sense of @scheme[protect-out], so access to unsafe operations -can be prevented by adjusting the code inspector (see +All of the exported bindings of @schememodname[racket/unsafe/ops] are +protected in the sense of @scheme[protect-out], so access to unsafe +operations can be prevented by adjusting the code inspector (see @secref["modprotect"]). @section{Unsafe Numeric Operations}