diff --git a/collects/racket/main.rkt b/collects/racket/main.rkt index c7ff6806d3..ab82fbe908 100644 --- a/collects/racket/main.rkt +++ b/collects/racket/main.rkt @@ -24,7 +24,6 @@ racket/promise racket/bool racket/local - racket/nest (for-syntax racket/base)) (provide (all-from-out racket/contract @@ -50,6 +49,5 @@ racket/cmdline racket/promise racket/bool - racket/local - racket/nest) + racket/local) (for-syntax (all-from-out racket/base))) diff --git a/collects/racket/nest.rkt b/collects/racket/nest.rkt deleted file mode 100644 index b17e2b3da4..0000000000 --- a/collects/racket/nest.rkt +++ /dev/null @@ -1,28 +0,0 @@ -#lang scheme/base - -(provide nest) - -;; A form that makes it easy to combine many "right-drifting" nested -;; expressions into a single one, sort of like a generalized version of the `*' -;; from `let*' and similar forms. -(define-syntax nest - (syntax-rules () - [(nest () body0 body ...) - (let () body0 body ...)] - ;; this allows putting definitions in the body - [(nest ([form forms ...]) body0 body ...) - (form forms ... (let () body0 body ...))] - [(nest ([form forms ...] . more) body0 body ...) - (form forms ... (nest more body0 body ...))])) - -;; using this instead will allow splicing body expressions in the last form -;; whatever it happens to be, which can be (ab)used in strange ways -#; -(define-syntax nest - (syntax-rules () - [(nest () body ...) - (begin body ...)] - [(nest ([form forms ...]) body ...) - (form forms ... body ...)] - [(nest ([form forms ...] . more) body ...) - (form forms ... (nest more body ...))])) diff --git a/collects/racket/pretty.rkt b/collects/racket/pretty.rkt index 5682ac6034..b290856004 100644 --- a/collects/racket/pretty.rkt +++ b/collects/racket/pretty.rkt @@ -403,6 +403,7 @@ #t)))) (define-struct unquoted (val)) + (define struct-ellipses (string->uninterned-symbol "...")) (define (generic-write obj display? width pport print-graph? print-struct? print-hash-table? print-vec-length? @@ -737,7 +738,7 @@ obj pport #t #f #f (lambda () - (let* ([v (struct->vector obj)] + (let* ([v (struct->vector obj struct-ellipses)] [pf? (prefab?! obj v)]) (let ([qd (if pf? (to-quoted out qd "`") @@ -796,7 +797,8 @@ (orig-write obj pport)] [(and qd (or (symbol? obj) (keyword? obj))) - (to-quoted out qd "'") + (unless (eq? obj struct-ellipses) + (to-quoted out qd "'")) (orig-write obj pport)] [(unquoted? obj) (let ([qd (to-unquoted out qd)]) @@ -894,7 +896,7 @@ (let ([qd (to-unquoted out qd)]) (write-custom pp* obj pport depth display? width qd))] [(struct? obj) ; print-struct is on if we got here - (let* ([v (struct->vector obj)] + (let* ([v (struct->vector obj struct-ellipses)] [pf? (prefab?! obj v)]) (let ([qd (if pf? (to-quoted out qd "`") diff --git a/collects/scheme/nest.rkt b/collects/scheme/nest.rkt index 6a8caf2fe8..b17e2b3da4 100644 --- a/collects/scheme/nest.rkt +++ b/collects/scheme/nest.rkt @@ -1,2 +1,28 @@ -#lang scheme/private/provider -racket/nest +#lang scheme/base + +(provide nest) + +;; A form that makes it easy to combine many "right-drifting" nested +;; expressions into a single one, sort of like a generalized version of the `*' +;; from `let*' and similar forms. +(define-syntax nest + (syntax-rules () + [(nest () body0 body ...) + (let () body0 body ...)] + ;; this allows putting definitions in the body + [(nest ([form forms ...]) body0 body ...) + (form forms ... (let () body0 body ...))] + [(nest ([form forms ...] . more) body0 body ...) + (form forms ... (nest more body0 body ...))])) + +;; using this instead will allow splicing body expressions in the last form +;; whatever it happens to be, which can be (ab)used in strange ways +#; +(define-syntax nest + (syntax-rules () + [(nest () body ...) + (begin body ...)] + [(nest ([form forms ...]) body ...) + (form forms ... body ...)] + [(nest ([form forms ...] . more) body ...) + (form forms ... (nest more body ...))])) diff --git a/collects/scribble/racket.ss b/collects/scribble/racket.ss index 397f359984..1ab7e03bf1 100644 --- a/collects/scribble/racket.ss +++ b/collects/scribble/racket.ss @@ -118,6 +118,8 @@ (define-struct (cached-delayed-element delayed-element) (cache-key)) (define-struct (cached-element element) (cache-key)) + (define qq-ellipses (string->uninterned-symbol "...")) + (define (make-id-element c s) (let* ([key (and id-element-cache (let ([b (identifier-label-binding c)]) @@ -201,7 +203,7 @@ is-var?))) (values (substring s 1) #t #f) (values s #f #f))))]) - (let ([quote-depth (if (and qq? (identifier? c)) + (let ([quote-depth (if (and qq? (identifier? c) (not (eq? qq-ellipses (syntax-e c)))) (let ([quote-depth (if (and (quote-depth . < . 2) (memq (syntax-e c) '(unquote unquote-splicing))) @@ -956,7 +958,7 @@ (if pf (prefab-struct-key v) (object-name v))) - (cdr (vector->list (struct->vector v))))] + (cdr (vector->list (struct->vector v qq-ellipses))))] [else v])]) (if (null? v) null diff --git a/collects/scribblings/reference/class.scrbl b/collects/scribblings/reference/class.scrbl index 8b458f7b4a..33d34c6ead 100644 --- a/collects/scribblings/reference/class.scrbl +++ b/collects/scribblings/reference/class.scrbl @@ -216,7 +216,7 @@ structure type property's guard, if any). @defexamples[ #:eval class-eval (define i (interface* () ([prop:custom-write - (lambda (obj port write?) (void))]) + (lambda (obj port mode) (void))]) method1 method2 method3)) ]} diff --git a/collects/scribblings/reference/cont.scrbl b/collects/scribblings/reference/cont.scrbl index 5fc03f3f5f..b88ad06ba6 100644 --- a/collects/scribblings/reference/cont.scrbl +++ b/collects/scribblings/reference/cont.scrbl @@ -4,11 +4,11 @@ @title[#:tag "cont"]{Continuations} See @secref["cont-model"] and @secref["prompt-model"] for general -information about continuations. PLT Scheme's support for prompts and +information about continuations. Racket's support for prompts and composable continuations most closely resembles Dorai Sitaram's -@scheme[%] and @scheme[fcontrol] operator @cite["Sitaram93"]. +@racket[%] and @racket[fcontrol] operator @cite["Sitaram93"]. -Scheme installs a @defterm{continuation barrier} around evaluation in +Racket installs a @defterm{continuation barrier} around evaluation in the following contexts, preventing full-continuation jumps across the barrier: @@ -30,15 +30,15 @@ barrier: @item{applying a will procedure (see @secref["willexecutor"]); or} - @item{evaluating or loading code from the stand-alone MzScheme + @item{evaluating or loading code from the stand-alone Racket command line (see @secref["running-sa"]).} ] -In addition, extensions of PLT Scheme may install barriers in -additional contexts. In particular, MrEd installs a continuation +In addition, extensions of Racket may install barriers in +additional contexts. In particular, GRacket installs a continuation barrier around most every callback. Finally, -@scheme[call-with-continuation-barrier] applies a thunk barrier +@racket[call-with-continuation-barrier] applies a thunk barrier between the application and the current continuation. @@ -49,22 +49,22 @@ between the application and the current continuation. [arg any/c] ...) any]{ -Applies @scheme[proc] to the given @scheme[arg]s with the current +Applies @racket[proc] to the given @racket[arg]s with the current continuation extended by a prompt. The prompt is tagged by -@scheme[prompt-tag], which must be a result from either -@scheme[default-continuation-prompt-tag] (the default) or -@scheme[make-continuation-prompt-tag]. The result of @scheme[proc] is -the result of the @scheme[call-with-continuation-prompt] call. +@racket[prompt-tag], which must be a result from either +@racket[default-continuation-prompt-tag] (the default) or +@racket[make-continuation-prompt-tag]. The result of @racket[proc] is +the result of the @racket[call-with-continuation-prompt] call. -The @scheme[handler] argument specifies a handler procedure to be +The @racket[handler] argument specifies a handler procedure to be called in tail position with respect to the -@scheme[call-with-continuation-prompt] call when the installed prompt -is the target of a @scheme[abort-current-continuation] call with -@scheme[prompt-tag]; the remaining arguments of -@scheme[abort-current-continuation] are supplied to the handler -procedure. If @scheme[handler] is @scheme[#f], the default handler -accepts a single @scheme[_abort-thunk] argument and calls -@scheme[(call-with-continuation-prompt _abort-thunk prompt-tag #f)]; +@racket[call-with-continuation-prompt] call when the installed prompt +is the target of a @racket[abort-current-continuation] call with +@racket[prompt-tag]; the remaining arguments of +@racket[abort-current-continuation] are supplied to the handler +procedure. If @racket[handler] is @racket[#f], the default handler +accepts a single @racket[_abort-thunk] argument and calls +@racket[(call-with-continuation-prompt _abort-thunk prompt-tag #f)]; that is, the default handler re-installs the prompt and continues with a given thunk.} @@ -74,24 +74,24 @@ a given thunk.} any]{ Resets the current continuation to that of the nearest prompt tagged -by @scheme[prompt-tag] in the current continuation; if no such prompt exists, -the @exnraise[exn:fail:contract:continuation]. The @scheme[v]s are delivered +by @racket[prompt-tag] in the current continuation; if no such prompt exists, +the @exnraise[exn:fail:contract:continuation]. The @racket[v]s are delivered as arguments to the target prompt's handler procedure. -The protocol for @scheme[v]s supplied to an abort is specific to the -@scheme[prompt-tag]. When @scheme[abort-current-continuation] is used with -@scheme[(default-continuation-prompt-tag)], generally a single thunk +The protocol for @racket[v]s supplied to an abort is specific to the +@racket[prompt-tag]. When @racket[abort-current-continuation] is used with +@racket[(default-continuation-prompt-tag)], generally a single thunk should be supplied that is suitable for use with the default prompt -handler. Similarly, when @scheme[call-with-continuation-prompt] is -used with @scheme[(default-continuation-prompt-tag)], the associated +handler. Similarly, when @racket[call-with-continuation-prompt] is +used with @racket[(default-continuation-prompt-tag)], the associated handler should generally accept a single thunk argument.} @defproc*[([(make-continuation-prompt-tag) continuation-prompt-tag?] [(make-continuation-prompt-tag [sym symbol?]) continuation-prompt-tag?])]{ -Creates a prompt tag that is not @scheme[equal?] to the result of any +Creates a prompt tag that is not @racket[equal?] to the result of any other value (including prior or future results from -@scheme[make-continuation-prompt-tag]). The optional @scheme[sym] +@racket[make-continuation-prompt-tag]). The optional @racket[sym] argument, if supplied, is used when printing the prompt tag.} @defproc[(default-continuation-prompt-tag) continuation-prompt-tag?]{ @@ -99,7 +99,7 @@ argument, if supplied, is used when printing the prompt tag.} Returns a constant prompt tag for which a prompt is installed at the start of every thread's continuation; the handler for each thread's initial prompt accepts any number of values and returns. The result of -@scheme[default-continuation-prompt-tag] is the default tag for more +@racket[default-continuation-prompt-tag] is the default tag for more any procedure that accepts a prompt tag.} @defproc[(call-with-current-continuation @@ -108,25 +108,25 @@ any procedure that accepts a prompt tag.} any]{ Captures the current continuation up to the nearest prompt tagged by -@scheme[prompt-tag]; if no such prompt exists, the +@racket[prompt-tag]; if no such prompt exists, the @exnraise[exn:fail:contract:continuation]. The truncated continuation -includes only continuation marks and @scheme[dynamic-wind] frames +includes only continuation marks and @racket[dynamic-wind] frames installed since the prompt. -The capture continuation is delivered to @scheme[proc], which is +The capture continuation is delivered to @racket[proc], which is called in tail position with respect to the -@scheme[call-with-current-continuation] call. +@racket[call-with-current-continuation] call. -If the continuation argument to @scheme[proc] is ever applied, then it +If the continuation argument to @racket[proc] is ever applied, then it removes the portion of the current continuation up to the nearest -prompt tagged by @scheme[prompt-tag] (not including the prompt; if no +prompt tagged by @racket[prompt-tag] (not including the prompt; if no such prompt exists, the @exnraise[exn:fail:contract:continuation]), or up to the nearest continuation frame (if any) shared by the current and captured continuations---whichever is first. While removing -continuation frames, @scheme[dynamic-wind] @scheme[post-thunk]s are +continuation frames, @racket[dynamic-wind] @racket[post-thunk]s are executed. Finally, the (unshared portion of the) captured continuation is appended to the remaining continuation, applying -@scheme[dynamic-wind] @scheme[pre-thunk]s. +@racket[dynamic-wind] @racket[pre-thunk]s. The arguments supplied to an applied procedure become the result values for the restored continuation. In particular, if multiple @@ -134,7 +134,7 @@ arguments are supplied, then the continuation receives multiple results. If, at application time, a continuation barrier appears between the -current continuation and the prompt tagged with @scheme[prompt-tag], +current continuation and the prompt tagged with @racket[prompt-tag], and if the same barrier is not part of the captured continuation, then the @exnraise[exn:fail:contract:continuation]. @@ -146,7 +146,7 @@ A continuation can be invoked from the thread (see [prompt-tag continuation-prompt-tag? (default-continuation-prompt-tag)]) any]{ -The @scheme[call/cc] binding is an alias for @scheme[call-with-current-continuation]. +The @racket[call/cc] binding is an alias for @racket[call-with-current-continuation]. } @defproc[(call-with-composable-continuation @@ -154,56 +154,56 @@ The @scheme[call/cc] binding is an alias for @scheme[call-with-current-continuat [prompt-tag continuation-prompt-tag? (default-continuation-prompt-tag)]) any]{ -Similar to @scheme[call-with-current-continuation], but applying +Similar to @racket[call-with-current-continuation], but applying the resulting continuation procedure does not remove any portion of the current continuation. Instead, application always extends the current continuation with the captured continuation (without installing any prompts other than those be captured in the -continuation). When @scheme[call-with-composable-continuation] is +continuation). When @racket[call-with-composable-continuation] is called, if a continuation barrier appears in the continuation before -the closest prompt tagged by @scheme[prompt-tag], the +the closest prompt tagged by @racket[prompt-tag], the @exnraise[exn:fail:contract:continuation].} @defproc[(call-with-escape-continuation [proc (continuation? . -> . any)]) any]{ -Like @scheme[call-with-current-continuation], but @scheme[proc] is not +Like @racket[call-with-current-continuation], but @racket[proc] is not called in tail position, and the continuation procedure supplied to -@scheme[proc] can only be called during the dynamic extent of the -@scheme[call-with-escape-continuation] call. A continuation barrier, +@racket[proc] can only be called during the dynamic extent of the +@racket[call-with-escape-continuation] call. A continuation barrier, however, never prevents the application of the continuation. Due to the limited applicability of its continuation, -@scheme[call-with-escape-continuation] can be implemented more efficiently -than @scheme[call-with-current-continuation]. +@racket[call-with-escape-continuation] can be implemented more efficiently +than @racket[call-with-current-continuation]. -A continuation obtained from @scheme[call-with-escape-continuation] is +A continuation obtained from @racket[call-with-escape-continuation] is actually a kind of prompt. Escape continuations are provided mainly for backward compatibility, since they pre-date general prompts in -PLT Scheme, and because @scheme[call/ec] is often an easy replacement -for @scheme[call/cc] to improve performance.} +Racket, and because @racket[call/ec] is often an easy replacement +for @racket[call/cc] to improve performance.} @defproc[(call/ec [proc (continuation? . -> . any)]) any]{ -The @scheme[call/ec] binding is an alias for @scheme[call-with-escape-continuation]. +The @racket[call/ec] binding is an alias for @racket[call-with-escape-continuation]. } @defform[(let/cc k body ...+)]{ -Equivalent to @scheme[(call/cc (lambda (k) body ...))]. +Equivalent to @racket[(call/cc (lambda (k) body ...))]. } @defform[(let/ec k body ...+)]{ -Equivalent to @scheme[(call/ec (lambda (k) body ...))]. +Equivalent to @racket[(call/ec (lambda (k) body ...))]. } @defproc[(call-with-continuation-barrier [thunk (-> any)]) any]{ -Applies @scheme[thunk] with a barrier between the application and the -current continuation. The results of @scheme[thunk] are the results of -the @scheme[call-with-continuation-barrier] call.} +Applies @racket[thunk] with a barrier between the application and the +current continuation. The results of @racket[thunk] are the results of +the @racket[call-with-continuation-barrier] call.} @defproc[(continuation-prompt-available? @@ -211,20 +211,20 @@ the @scheme[call-with-continuation-barrier] call.} [cont continuation? (call/cc values)]) any]{ -Returns @scheme[#t] if @scheme[cont], which must be a continuation, -includes a prompt tagged by @scheme[prompt-tag], @scheme[#f] +Returns @racket[#t] if @racket[cont], which must be a continuation, +includes a prompt tagged by @racket[prompt-tag], @racket[#f] otherwise. } -@defproc[(continuation? [v any/c]) boolean?]{ Return @scheme[#t] if -@scheme[v] is a continuation as produced by -@scheme[call-with-current-continuation], -@scheme[call-with-composable-continuation], or -@scheme[call-with-escape-continuation], @scheme[#f] otherwise.} +@defproc[(continuation? [v any/c]) boolean?]{ Return @racket[#t] if +@racket[v] is a continuation as produced by +@racket[call-with-current-continuation], +@racket[call-with-composable-continuation], or +@racket[call-with-escape-continuation], @racket[#f] otherwise.} @defproc[(continuation-prompt-tag? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a continuation prompt tag as produced by -@scheme[default-continuation-prompt-tag] or @scheme[make-continuation-prompt-tag].} +Returns @racket[#t] if @racket[v] is a continuation prompt tag as produced by +@racket[default-continuation-prompt-tag] or @racket[make-continuation-prompt-tag].} @defproc[(dynamic-wind [pre-thunk (-> any)] [value-thunk (-> any)] @@ -232,72 +232,72 @@ Returns @scheme[#t] if @scheme[v] is a continuation prompt tag as produced by any]{ Applies its three thunk arguments in order. The value of a -@scheme[dynamic-wind] expression is the value returned by -@scheme[value-thunk]. The @scheme[pre-thunk] procedure is invoked -before calling @scheme[value-thunk] and @scheme[post-thunk] is invoked -after @scheme[value-thunk] returns. The special properties of -@scheme[dynamic-wind] are manifest when control jumps into or out of -the @scheme[value-thunk] application (either due to a prompt abort or +@racket[dynamic-wind] expression is the value returned by +@racket[value-thunk]. The @racket[pre-thunk] procedure is invoked +before calling @racket[value-thunk] and @racket[post-thunk] is invoked +after @racket[value-thunk] returns. The special properties of +@racket[dynamic-wind] are manifest when control jumps into or out of +the @racket[value-thunk] application (either due to a prompt abort or a continuation invocation): every time control jumps into the -@scheme[value-thunk] application, @scheme[pre-thunk] is invoked, and -every time control jumps out of @scheme[value-thunk], -@scheme[post-thunk] is invoked. (No special handling is performed for -jumps into or out of the @scheme[pre-thunk] and @scheme[post-thunk] +@racket[value-thunk] application, @racket[pre-thunk] is invoked, and +every time control jumps out of @racket[value-thunk], +@racket[post-thunk] is invoked. (No special handling is performed for +jumps into or out of the @racket[pre-thunk] and @racket[post-thunk] applications.) -When @scheme[dynamic-wind] calls @scheme[pre-thunk] for normal -evaluation of @scheme[value-thunk], the continuation of the -@scheme[pre-thunk] application calls @scheme[value-thunk] (with -@scheme[dynamic-wind]'s special jump handling) and then -@scheme[post-thunk]. Similarly, the continuation of the -@scheme[post-thunk] application returns the value of the preceding -@scheme[value-thunk] application to the continuation of the entire -@scheme[dynamic-wind] application. +When @racket[dynamic-wind] calls @racket[pre-thunk] for normal +evaluation of @racket[value-thunk], the continuation of the +@racket[pre-thunk] application calls @racket[value-thunk] (with +@racket[dynamic-wind]'s special jump handling) and then +@racket[post-thunk]. Similarly, the continuation of the +@racket[post-thunk] application returns the value of the preceding +@racket[value-thunk] application to the continuation of the entire +@racket[dynamic-wind] application. -When @scheme[pre-thunk] is called due to a continuation jump, the -continuation of @scheme[pre-thunk] +When @racket[pre-thunk] is called due to a continuation jump, the +continuation of @racket[pre-thunk] @itemize[ - @item{jumps to a more deeply nested @scheme[pre-thunk], if any, or jumps + @item{jumps to a more deeply nested @racket[pre-thunk], if any, or jumps to the destination continuation; then} - @item{continues with the context of the @scheme[pre-thunk]'s - @scheme[dynamic-wind] call.} + @item{continues with the context of the @racket[pre-thunk]'s + @racket[dynamic-wind] call.} ] Normally, the second part of this continuation is never reached, due to a jump in the first part. However, the second part is relevant because it enables jumps to escape continuations that are contained in -the context of the @scheme[dynamic-wind] call. Furthermore, it means +the context of the @racket[dynamic-wind] call. Furthermore, it means that the continuation marks (see @secref["contmarks"]) and -parameterization (see @secref["parameters"]) for @scheme[pre-thunk] -correspond to those of the @scheme[dynamic-wind] call that installed -@scheme[pre-thunk]. The @scheme[pre-thunk] call, however, is -@scheme[parameterize-break]ed to disable breaks (see also +parameterization (see @secref["parameters"]) for @racket[pre-thunk] +correspond to those of the @racket[dynamic-wind] call that installed +@racket[pre-thunk]. The @racket[pre-thunk] call, however, is +@racket[parameterize-break]ed to disable breaks (see also @secref["breakhandler"]). -Similarly, when @scheme[post-thunk] is called due to a continuation -jump, the continuation of @scheme[post-thunk] jumps to a less deeply -nested @scheme[post-thunk], if any, or jumps to a @scheme[pre-thunk] +Similarly, when @racket[post-thunk] is called due to a continuation +jump, the continuation of @racket[post-thunk] jumps to a less deeply +nested @racket[post-thunk], if any, or jumps to a @racket[pre-thunk] protecting the destination, if any, or jumps to the destination -continuation, then continues from the @scheme[post-thunk]'s -@scheme[dynamic-wind] application. As for @scheme[pre-thunk], the -parameterization of the original @scheme[dynamic-wind] call is -restored for the call, and the call is @scheme[parameterize-break]ed +continuation, then continues from the @racket[post-thunk]'s +@racket[dynamic-wind] application. As for @racket[pre-thunk], the +parameterization of the original @racket[dynamic-wind] call is +restored for the call, and the call is @racket[parameterize-break]ed to disable breaks. In both cases, the target for a jump is recomputed after each -@scheme[pre-thunk] or @scheme[post-thunk] completes. When a +@racket[pre-thunk] or @racket[post-thunk] completes. When a prompt-delimited continuation (see @secref["prompt-model"]) is -captured in a @scheme[post-thunk], it might be delimited and +captured in a @racket[post-thunk], it might be delimited and instantiated in such a way that the target of a jump turns out to be different when the continuation is applied than when the continuation was captured. There may even be no appropriate target, if a relevant prompt or escape continuation is not in the continuation after the -restore; in that case, the first step in a @scheme[pre-thunk] or -@scheme[post-thunk]'s continuation can raise an exception. +restore; in that case, the first step in a @racket[pre-thunk] or +@racket[post-thunk]'s continuation can raise an exception. @examples[ (let ([v (let/ec out diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl index 1195ccf56c..542acdd3b6 100644 --- a/collects/scribblings/reference/contracts.scrbl +++ b/collects/scribblings/reference/contracts.scrbl @@ -647,37 +647,36 @@ As an example, consider the following module: @(begin #reader scribble/comment-reader -[schemeblock -(module product mzscheme - (require mzlib/contract) +[racketmod +racket - (define-contract-struct kons (hd tl)) +(define-contract-struct kons (hd tl)) - ;; @scheme[sorted-list/gt : number -> contract] - ;; produces a contract that accepts - ;; sorted kons-lists whose elements - ;; are all greater than @scheme[num]. - (define (sorted-list/gt num) - (or/c null? - (kons/dc [hd (>=/c num)] - [tl (hd) (sorted-list/gt hd)]))) +;; @scheme[sorted-list/gt : number -> contract] +;; produces a contract that accepts +;; sorted kons-lists whose elements +;; are all greater than @scheme[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] - ;; computes the product of the values - ;; in the list. if the list contains - ;; zero, it avoids traversing the rest - ;; of the list. - (define (product l) - (cond - [(null? l) 1] - [else - (if (zero? (kons-hd l)) - 0 - (* (kons-hd l) - (product (kons-tl l))))])) - - (provide kons? make-kons kons-hd kons-tl) - (provide/contract [product (-> (sorted-list/gt -inf.0) number?)])) +;; @scheme[product : kons-list -> number] +;; computes the product of the values +;; in the list. if the list contains +;; zero, it avoids traversing the rest +;; of the list. +(define (product l) + (cond + [(null? l) 1] + [else + (if (zero? (kons-hd l)) + 0 + (* (kons-hd l) + (product (kons-tl l))))])) + +(provide kons? make-kons kons-hd kons-tl) +(provide/contract [product (-> (sorted-list/gt -inf.0) number?)]) ]) The module provides a single function, @scheme[product] whose contract diff --git a/collects/scribblings/reference/custodians.scrbl b/collects/scribblings/reference/custodians.scrbl index 32d5ecaa1f..00432bd780 100644 --- a/collects/scribblings/reference/custodians.scrbl +++ b/collects/scribblings/reference/custodians.scrbl @@ -5,35 +5,35 @@ @title[#:tag "custodians"]{Custodians} -See @secref["custodian-model"] for basic information on the PLT -Scheme custodian model. +See @secref["custodian-model"] for basic information on the Racket +custodian model. @defproc[(custodian? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{custodian} value, -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @tech{custodian} value, +@racket[#f] otherwise.} @defproc[(make-custodian [cust custodian? (current-custodian)]) custodian?]{ -Creates a new custodian that is subordinate to @scheme[cust]. When -@scheme[cust] is directed (via @scheme[custodian-shutdown-all]) to +Creates a new custodian that is subordinate to @racket[cust]. When +@racket[cust] is directed (via @racket[custodian-shutdown-all]) to shut down all of its managed values, the new subordinate custodian is automatically directed to shut down its managed values as well.} @defproc[(custodian-shutdown-all [cust custodian?]) void?]{ -@margin-note{In MrEd, @|eventspaces| managed by @scheme[cust] are also +@margin-note{In MrEd, @|eventspaces| managed by @racket[cust] are also shut down.} Closes all @tech{file-stream ports}, @tech{TCP ports}, @tech{TCP -listeners}, and @tech{UDP sockets} that are managed by @scheme[cust] +listeners}, and @tech{UDP sockets} that are managed by @racket[cust] (and its subordinates), and empties all @tech{custodian box}es -associated with @scheme[cust] (and its subordinates). It also removes -@scheme[cust] (and its subordinates) as managers of all threads; when +associated with @racket[cust] (and its subordinates). It also removes +@racket[cust] (and its subordinates) as managers of all threads; when a thread has no managers, it is killed (or suspended; see -@scheme[thread/suspend-to-kill]) If the current thread is to be +@racket[thread/suspend-to-kill]) If the current thread is to be killed, all other shut-down actions take place before killing the thread.} @@ -50,45 +50,45 @@ for newly created threads, @tech{file-stream ports}, TCP ports, @defproc[(custodian-managed-list [cust custodian?][super custodian?]) list?]{ Returns a list of immediately managed objects (not including -@tech{custodian box}es) and subordinate custodians for @scheme[cust], -where @scheme[cust] is itself subordinate to @scheme[super] (directly -or indirectly). If @scheme[cust] is not strictly subordinate to -@scheme[super], the @exnraise[exn:fail:contract].} +@tech{custodian box}es) and subordinate custodians for @racket[cust], +where @racket[cust] is itself subordinate to @racket[super] (directly +or indirectly). If @racket[cust] is not strictly subordinate to +@racket[super], the @exnraise[exn:fail:contract].} @defproc[(custodian-memory-accounting-available?) boolean?]{ -@margin-note{Memory accounting is normally available in PLT Scheme 3m, -which is the main variant of PLT Scheme, and not normally available in -PLT Scheme CGC.} +@margin-note{Memory accounting is normally available in Racket 3m, +which is the main variant of Racket, and not normally available in +Racket CGC.} -Returns @scheme[#t] if PLT Scheme is compiled with support for -per-custodian memory accounting, @scheme[#f] otherwise.} +Returns @racket[#t] if Racket is compiled with support for +per-custodian memory accounting, @racket[#f] otherwise.} @defproc[(custodian-require-memory [limit-cust custodian?] [need-amt exact-nonnegative-integer?] [stop-cust custodian?]) void?]{ -Registers a required-memory check if PLT Scheme is compiled with +Registers a required-memory check if Racket is compiled with support for per-custodian memory accounting, otherwise the @exnraise[exn:fail:unsupported]. -If a check is registered, and if PLT Scheme later reaches a state after +If a check is registered, and if Racket later reaches a state after garbage collection (see @secref["gc-model"]) where allocating -@scheme[need-amt] bytes charged to @scheme[limit-cust] would fail or -trigger some shutdown, then @scheme[stop-cust] is shut down.} +@racket[need-amt] bytes charged to @racket[limit-cust] would fail or +trigger some shutdown, then @racket[stop-cust] is shut down.} @defproc[(custodian-limit-memory [limit-cust custodian?] [limit-amt exact-nonnegative-integer?] [stop-cust custodian? limit-cust]) void?]{ -Registers a limited-memory check if PLT Scheme is compiled with +Registers a limited-memory check if Racket is compiled with support for per-custodian memory accounting, otherwise the @exnraise[exn:fail:unsupported]. -If a check is registered, and if PLT Scheme later reaches a state +If a check is registered, and if Racket later reaches a state after garbage collection (see @secref["gc-model"]) where -@scheme[limit-cust] owns more than @scheme[limit-amt] bytes, then -@scheme[stop-cust] is shut down. +@racket[limit-cust] owns more than @racket[limit-amt] bytes, then +@racket[stop-cust] is shut down. @margin-note{A custodian's limit is checked only after a garbage collection, except that it may also be checked during @@ -98,25 +98,25 @@ after garbage collection (see @secref["gc-model"]) where only one of the custodians would have reduced memory use for other custodians.} -For reliable shutdown, @scheme[limit-amt] for -@scheme[custodian-limit-memory] must be much lower than the total +For reliable shutdown, @racket[limit-amt] for +@racket[custodian-limit-memory] must be much lower than the total amount of memory available (minus the size of memory that is -potentially used and not charged to @scheme[limit-cust]). Moreover, if +potentially used and not charged to @racket[limit-cust]). Moreover, if individual allocations that are initially charged to -@scheme[limit-cust] can be arbitrarily large, then @scheme[stop-cust] -must be the same as @scheme[limit-cust], so that excessively large +@racket[limit-cust] can be arbitrarily large, then @racket[stop-cust] +must be the same as @racket[limit-cust], so that excessively large immediate allocations can be rejected with an -@scheme[exn:fail:out-of-memory] exception.} +@racket[exn:fail:out-of-memory] exception.} @defproc[(make-custodian-box [cust custodian?][v any/c]) custodian-box?]{ -Returns a @tech{custodian box} that contains @scheme[v] as long as -@scheme[cust] has not been shut down.} +Returns a @tech{custodian box} that contains @racket[v] as long as +@racket[cust] has not been shut down.} -@defproc[(custodian-box? [v any/c]) boolean?]{Returns @scheme[#t] if - @scheme[v] is a @tech{custodian box} produced by - @scheme[make-custodian-box], @scheme[#f] otherwise.} +@defproc[(custodian-box? [v any/c]) boolean?]{Returns @racket[#t] if + @racket[v] is a @tech{custodian box} produced by + @racket[make-custodian-box], @racket[#f] otherwise.} @defproc[(custodian-box-value [cb custodian-box?]) any]{Returns the - value in the given @tech{custodian box}, or @scheme[#f] if the value + value in the given @tech{custodian box}, or @racket[#f] if the value has been removed.} diff --git a/collects/scribblings/reference/define-struct.scrbl b/collects/scribblings/reference/define-struct.scrbl index 54e54c03e7..2f94aabc15 100644 --- a/collects/scribblings/reference/define-struct.scrbl +++ b/collects/scribblings/reference/define-struct.scrbl @@ -121,12 +121,12 @@ cannot have a guard or properties, so using @racket[#:prefab] with @racket[#:property] is a syntax error. If a supertype is specified, it must also be a @tech{prefab} structure type. -If @racket[constructor-id] is supplied then the @tech{transformer +If @racket[constructor-id] is supplied, then the @tech{transformer binding} of @scheme[id] records @scheme[constructor-id] as the constructor binding; as a result, for example, @scheme[struct-out] includes @racket[constructor-id] as an export. If @racket[constructor-id] is supplied via -@racket[#:extra-constructor-name] and it is not @racket[id], Applying +@racket[#:extra-constructor-name] and it is not @racket[id], applying @racket[object-name] on the constructor produces the symbolic form of @racket[id] rather than @racket[constructor-id]. If @racket[constructor-id] is supplied via @racket[#:constructor-name] diff --git a/collects/scribblings/reference/filesystem.scrbl b/collects/scribblings/reference/filesystem.scrbl index 54019bc9a1..ad259aa6de 100644 --- a/collects/scribblings/reference/filesystem.scrbl +++ b/collects/scribblings/reference/filesystem.scrbl @@ -12,11 +12,11 @@ @defproc[(find-system-path [kind symbol?]) path?]{ Returns a machine-specific path for a standard type of path specified -by @scheme[kind], which must be one of the following: +by @racket[kind], which must be one of the following: @itemize[ - @item{@indexed-scheme['home-dir] --- the current user's home + @item{@indexed-racket['home-dir] --- the current user's home directory. Under Unix and Mac OS X, this directory is determined by expanding @@ -37,24 +37,24 @@ by @scheme[kind], which must be one of the following: indicated directory still does not exist, the directory containing the current executable is used as the home directory.} - @item{@indexed-scheme['pref-dir] --- the standard directory for + @item{@indexed-racket['pref-dir] --- the standard directory for storing the current user's preferences. Under Unix, the directory is - @filepath{.plt-scheme} in the user's home directory. Under Windows, it - is @filepath{PLT Scheme} in the user's application-data folder as + @filepath{.racket} in the user's home directory. Under Windows, it + is @filepath{Racket} in the user's application-data folder as specified by the Windows registry; the application-data folder is usually @filepath{Application Data} in the user's profile directory. Under Mac OS X, it is @filepath{Library/Preferences} in the user's home directory. This directory might not exist.} - @item{@indexed-scheme['pref-file] --- a file that contains a + @item{@indexed-racket['pref-file] --- a file that contains a symbol-keyed association list of preference values. The file's directory path always matches the result returned for - @scheme['pref-dir]. The file name is @filepath{plt-prefs.ss} under Unix - and Windows, and it is @filepath{org.plt-scheme.prefs.ss} under Mac OS + @racket['pref-dir]. The file name is @filepath{racket-prefs.rkt} under Unix + and Windows, and it is @filepath{org.racket-lang.prefs.rkt} under Mac OS X. The file's directory might not exist. See also - @scheme[get-preference].} + @racket[get-preference].} - @item{@indexed-scheme['temp-dir] --- the standard directory for + @item{@indexed-racket['temp-dir] --- the standard directory for storing temporary files. Under @|AllUnix|, this is the directory specified by the @indexed-envvar{TMPDIR} environment variable, if it is defined, otherwise it is the first path that exists among @@ -63,82 +63,82 @@ by @scheme[kind], which must be one of the following: @indexed-envvar{TMP} or @indexed-envvar{TEMP} environment variable, if it is defined, otherwise it is the current directory.} - @item{@indexed-scheme['init-dir] --- the directory containing the - initialization file used by stand-alone @exec{mzscheme} executable. + @item{@indexed-racket['init-dir] --- the directory containing the + initialization file used by stand-alone @exec{mzracket} executable. It is the same as the current user's home directory.} - @item{@indexed-scheme['init-file] --- the file loaded at start-up by - the stand-alone @exec{mzscheme} executable. The directory part of the - path is the same path as returned for @scheme['init-dir]. The file + @item{@indexed-racket['init-file] --- the file loaded at start-up by + the stand-alone @exec{mzracket} 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{.mzschemerc}} + @item{@|AllUnix|: @indexed-file{.mzracketrc}} - @item{Windows: @indexed-file{mzschemerc.ss}} + @item{Windows: @indexed-file{mzracketrc.rkt}} ]} - @item{@indexed-scheme['addon-dir] --- a directory for installing PLT - Scheme extensions. This directory is specified by the + @item{@indexed-racket['addon-dir] --- a directory for installing + Racket extensions. This directory is specified by the @indexed-envvar{PLTADDONDIR} environment variable, and it can be overridden by the @DFlag{addon} or @Flag{A} command-line flag. If no environment variable or flag is specified, or if the value is not a legal path name, then this directory defaults to - @filepath{Library/PLT Scheme} in the user's home directory under Mac - OS X and @scheme['pref-dir] otherwise. This directory might not + @filepath{Library/Racket} in the user's home directory under Mac + OS X and @racket['pref-dir] otherwise. This directory might not exist.} - @item{@indexed-scheme['doc-dir] --- the standard directory for + @item{@indexed-racket['doc-dir] --- the standard directory for storing the current user's documents. Under Unix, it's the same as - @scheme['home-dir]. Under Mac OS X, it's the + @racket['home-dir]. Under Mac OS X, it's the @filepath{Documents} directory in the user's home directory. Under Windows, it is the user's documents folder as specified by the Windows registry; the documents folder is usually @filepath{My Documents} in the user's home directory.} - @item{@indexed-scheme['desk-dir] --- the directory for the current user's - desktop. Under Unix, it's the same as @scheme['home-dir]. Under + @item{@indexed-racket['desk-dir] --- the directory for the current user's + desktop. Under Unix, it's the same as @racket['home-dir]. Under Windows, it is the user's desktop folder as specified by the Windows registry; the documents folder is usually @filepath{Desktop} in the user's home directory. Under Mac OS X, it is the desktop directory, which is specifically @filepath{~/Desktop} under Mac OS X.} - @item{@indexed-scheme['sys-dir] --- the directory containing the + @item{@indexed-racket['sys-dir] --- the directory containing the operating system for Windows. Under @|AllUnix|, the - result is @scheme["/"].} + result is @racket["/"].} - @item{@indexed-scheme['exec-file] --- the path of the @exec{mzscheme} + @item{@indexed-racket['exec-file] --- the path of the @exec{mzracket} executable as provided by the operating system for the current invocation. @margin-note{For MrEd, the executable path is the name of a MrEd executable.}} - @item{@indexed-scheme['run-file] --- the path of the current + @item{@indexed-racket['run-file] --- the path of the current executable; this may be different from result for - @scheme['exec-file] because an alternate path was provided through a - @DFlag{name} or @Flag{N} command-line flag to the @exec{mzscheme} + @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 installed an alternate path. In particular a ``launcher'' script - created by @scheme[make-mzscheme-launcher] sets this path to the + created by @racket[make-mzracket-launcher] sets this path to the script's path.} - @item{@indexed-scheme['collects-dir] --- a path to the main + @item{@indexed-racket['collects-dir] --- a path to the main collection of libraries (see @secref["collects"]). If this path is relative, then it is relative to the executable as reported by - @scheme[(find-system-path 'exec-file)]---though the latter could be a + @racket[(find-system-path 'exec-file)]---though the latter could be a soft-link or relative to the user's executable search path, so that the two results should be combined with - @scheme[find-executable-path]. The @scheme['collects-dir] path is - normally embedded in the @exec{mzscheme} executable, but it can be + @racket[find-executable-path]. The @racket['collects-dir] path is + normally embedded in the @exec{mzracket} executable, but it can be overridden by the @DFlag{collects} or @Flag{X} command-line flag.} - @item{@indexed-scheme['orig-dir] --- the current directory at + @item{@indexed-racket['orig-dir] --- the current directory at start-up, which can be useful in converting a relative-path result - from @scheme[(find-system-path 'exec-file)] or - @scheme[(find-system-path 'run-file)] to a complete path.} + from @racket[(find-system-path 'exec-file)] or + @racket[(find-system-path 'run-file)] to a complete path.} ]} @@ -151,8 +151,8 @@ Parses a string or byte string containing a list of paths, and returns a list of path strings. Under @|AllUnix|, paths in a path list are separated by a @litchar{:}; under Windows, paths are separated by a @litchar{;}. Whenever the path list contains an empty path, the list -@scheme[default-path-list] is spliced into the returned list of -paths. Parts of @scheme[str] that do not form a valid path are not +@racket[default-path-list] is spliced into the returned list of +paths. Parts of @racket[str] that do not form a valid path are not included in the returned list.} @@ -161,45 +161,45 @@ included in the returned list.} [deepest? any/c #f]) (or/c path? #f)]{ -Finds a path for the executable @scheme[program-sub], returning -@scheme[#f] if the path cannot be found. +Finds a path for the executable @racket[program-sub], returning +@racket[#f] if the path cannot be found. -If @scheme[related-sub] is not @scheme[#f], then it must be a relative -path string, and the path found for @scheme[program-sub] must be such -that the file or directory @scheme[related-sub] exists in the same +If @racket[related-sub] is not @racket[#f], then it must be a relative +path string, and the path found for @racket[program-sub] must be such +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 @scheme[related-sub], instead of the path for the executable. +found @racket[related-sub], instead of the path for the executable. -This procedure is used by the @exec{mzscheme} executable to find the +This procedure is used by the @exec{mzracket} executable to find the standard library collection directory (see @secref["collects"]). In -this case, @scheme[program] is the name used to start MzScheme and -@scheme[related] is @scheme["collects"]. The @scheme[related-sub] -argument is used because, under @|AllUnix|, @scheme[program-sub] may +this case, @racket[program] is the name used to start Racket and +@racket[related] is @racket["collects"]. The @racket[related-sub] +argument is used because, under @|AllUnix|, @racket[program-sub] may involve to a sequence of soft links; in this case, -@scheme[related-sub] determines which link in the chain is relevant. +@racket[related-sub] determines which link in the chain is relevant. -If @scheme[related-sub] is not @scheme[#f], then when -@scheme[find-executable-path] does not finds a @scheme[program-sub] +If @racket[related-sub] is not @racket[#f], then when +@racket[find-executable-path] does not finds a @racket[program-sub] that is a link to another file path, the search can continue with the destination of the link. Further links are inspected until -@scheme[related-sub] is found or the end of the chain of links is -reached. If @scheme[deepest?] is @scheme[#f] (the default), then the +@racket[related-sub] is found or the end of the chain of links is +reached. If @racket[deepest?] is @racket[#f] (the default), then the result corresponds to the first path in a chain of links for which -@scheme[related-sub] is found (and further links are not actually +@racket[related-sub] is found (and further links are not actually explored); otherwise, the result corresponds to the last link in the -chain for which @scheme[related-sub] is found. +chain for which @racket[related-sub] is found. -If @scheme[program-sub] is a pathless name, -@scheme[find-executable-path] gets the value of the +If @racket[program-sub] is a pathless name, +@racket[find-executable-path] gets the value of the @indexed-envvar{PATH} environment variable; if this environment -variable is defined, @scheme[find-executable-path] tries each path in -@envvar{PATH} as a prefix for @scheme[program-sub] using the search +variable is defined, @racket[find-executable-path] tries each path in +@envvar{PATH} as a prefix for @racket[program-sub] using the search algorithm described above for path-containing -@scheme[program-sub]s. If the @envvar{PATH} environment variable is -not defined, @scheme[program-sub] is prefixed with the current +@racket[program-sub]s. If the @envvar{PATH} environment variable is +not defined, @racket[program-sub] is prefixed with the current directory and used in the search algorithm above. (Under Windows, the current directory is always implicitly the first item in -@envvar{PATH}, so @scheme[find-executable-path] checks the current +@envvar{PATH}, so @racket[find-executable-path] checks the current directory first under Windows.)} @;------------------------------------------------------------------------ @@ -207,32 +207,32 @@ directory first under Windows.)} @defproc[(file-exists? [path path-string?]) boolean?]{ -Returns @scheme[#t] if a file (not a directory) @scheme[path] exists, -@scheme[#f] otherwise. +Returns @racket[#t] if a file (not a directory) @racket[path] exists, +@racket[#f] otherwise. -Under Windows, @scheme[file-exists?] reports @scheme[#t] for all -variations of the special filenames (e.g., @scheme["LPT1"], -@scheme["x:/baddir/LPT1"]).} +Under Windows, @racket[file-exists?] reports @racket[#t] for all +variations of the special filenames (e.g., @racket["LPT1"], +@racket["x:/baddir/LPT1"]).} @defproc[(link-exists? [path path-string?]) boolean?]{ -Returns @scheme[#t] if a link @scheme[path] exists (@|AllUnix|), -@scheme[#f] otherwise. +Returns @racket[#t] if a link @racket[path] exists (@|AllUnix|), +@racket[#f] otherwise. -The predicates @scheme[file-exists?] or @scheme[directory-exists?] +The predicates @racket[file-exists?] or @racket[directory-exists?] work on the final destination of a link or series of links, while -@scheme[link-exists?] only follows links to resolve the base part of -@scheme[path] (i.e., everything except the last name in the +@racket[link-exists?] only follows links to resolve the base part of +@racket[path] (i.e., everything except the last name in the path). -This procedure never raises the @scheme[exn:fail:filesystem] +This procedure never raises the @racket[exn:fail:filesystem] exception.} @defproc[(delete-file [path path-string?]) void?]{ -Deletes the file with path @scheme[path] if it exists, otherwise the -@exnraise[exn:fail:filesystem]. If @scheme[path] is a link, the link +Deletes the file with path @racket[path] if it exists, otherwise the +@exnraise[exn:fail:filesystem]. If @racket[path] is a link, the link is deleted rather than the destination of the link.} @defproc[(rename-file-or-directory [old path-string?] @@ -240,25 +240,25 @@ is deleted rather than the destination of the link.} [exists-ok? any/c #f]) void?]{ -Renames the file or directory with path @scheme[old]---if it -exists---to the path @scheme[new]. If the file or directory is not +Renames the file or directory with path @racket[old]---if it +exists---to the path @racket[new]. If the file or directory is not renamed successfully, the @exnraise[exn:fail:filesystem]. This procedure can be used to move a file/directory to a different directory (on the same disk) as well as rename a file/directory within -a directory. Unless @scheme[exists-ok?] is provided as a true value, -@scheme[new] cannot refer to an existing file or directory. Even if -@scheme[exists-ok?] is true, @scheme[new] cannot refer to an existing -file when @scheme[old] is a directory, and vice versa. (If -@scheme[new] exists and is replaced, the replacement is atomic in the +a directory. Unless @racket[exists-ok?] is provided as a true value, +@racket[new] cannot refer to an existing file or directory. Even if +@racket[exists-ok?] is true, @racket[new] cannot refer to an existing +file when @racket[old] is a directory, and vice versa. (If +@racket[new] exists and is replaced, the replacement is atomic in the filesystem, except under Windows 95, 98, or Me. However, the check for existence is not included in the atomic action, which means that race -conditions are possible when @scheme[exists-ok?] is false or not +conditions are possible when @racket[exists-ok?] is false or not supplied.) -If @scheme[old] is a link, the link is renamed rather than the +If @racket[old] is a link, the link is renamed rather than the destination of the link, and it counts as a file for replacing any -existing @scheme[new].} +existing @racket[new].} @defproc[(file-or-directory-modify-seconds [path path-string?] @@ -268,23 +268,23 @@ existing @scheme[new].} Returns the file or directory's last modification date as platform-specific seconds (see also @secref["time"]) when -@scheme[secs-n] is not provided or is @scheme[#f]. (For FAT +@racket[secs-n] is not provided or is @racket[#f]. (For FAT filesystems under Windows, directories do not have modification dates. Therefore, the creation date is returned for a directory, but the modification date is returned for a file.) -If @scheme[secs-n] is provided and not @scheme[#f], the access and -modification times of @scheme[path] are set to the given time. +If @racket[secs-n] is provided and not @racket[#f], the access and +modification times of @racket[path] are set to the given time. -On error (e.g., if no such file exists), @scheme[fail-thunk] is -called, and the default @scheme[fail-thunk] raises -@scheme[exn:fail:filesystem].} +On error (e.g., if no such file exists), @racket[fail-thunk] is +called, and the default @racket[fail-thunk] raises +@racket[exn:fail:filesystem].} @defproc[(file-or-directory-permissions [path path-string?]) (listof symbol?)]{ -Returns a list containing @indexed-scheme['read], -@indexed-scheme['write], and/or @indexed-scheme['execute] for the +Returns a list containing @indexed-racket['read], +@indexed-racket['write], and/or @indexed-racket['execute] for the given file or directory path. On error (e.g., if no such file exists), the @exnraise[exn:fail:filesystem]. Under @|AllUnix|, permissions are checked for the current effective user instead of the real user.} @@ -295,12 +295,12 @@ checked for the current effective user instead of the real user.} exact-positive-integer?]{ @index['("inode")]{Returns} a number that represents the identity of -@scheme[path] in terms of the device and file or directory that it +@racket[path] in terms of the device and file or directory that it accesses. This function can be used to check whether two paths correspond to the same filesystem entity under the assumption that the path's entity selection does not change. -If @scheme[as-link?] is a true value, then if @scheme[path] refers to +If @racket[as-link?] is a true value, then if @racket[path] refers to a filesystem link, the identity of the link is returned instead of the identity of the referenced file or directory (if any).} @@ -314,19 +314,19 @@ such file exists), the @exnraise[exn:fail:filesystem].} @defproc[(copy-file [src path-string?][dest path-string?]) void?]{ -Creates the file @scheme[dest] as a copy of @scheme[src]. If the file +Creates the file @racket[dest] as a copy of @racket[src]. If the file is not successfully copied, the @exnraise[exn:fail:filesystem]. If -@scheme[dest] already exists, the copy will fail. File permissions are +@racket[dest] already exists, the copy will fail. File permissions are preserved in the copy. Under Mac OS X, the resource fork is also -preserved in the copy. If @scheme[src] refers to a link, the target of +preserved in the copy. If @racket[src] refers to a link, the target of the link is copied, rather than the link itself.} @defproc[(make-file-or-directory-link [to path-string?][path path-string?]) void?]{ -Creates a link @scheme[path] to @scheme[to] under @|AllUnix|. The -creation will fail if @scheme[path] already exists. The @scheme[to] -need not refer to an existing file or directory, and @scheme[to] is +Creates a link @racket[path] to @racket[to] under @|AllUnix|. The +creation will fail if @racket[path] already exists. The @racket[to] +need not refer to an existing file or directory, and @racket[to] is not expanded before writing the link. If the link is not created successfully,the @exnraise[exn:fail:filesystem]. Under Windows, the @exnraise[exn:fail:unsupported] always.} @@ -334,9 +334,9 @@ successfully,the @exnraise[exn:fail:filesystem]. Under Windows, the @;------------------------------------------------------------------------ @section[#:tag "directories"]{Directories} -See also: @scheme[rename-file-or-directory], -@scheme[file-or-directory-modify-seconds], -@scheme[file-or-directory-permissions]. +See also: @racket[rename-file-or-directory], +@racket[file-or-directory-modify-seconds], +@racket[file-or-directory-permissions]. @defparam[current-directory path path-string?]{ @@ -344,11 +344,11 @@ A parameter that determines the current directory for resolving relative paths. When the parameter procedure is called to set the current directory, -the path argument is @tech{cleanse}d using @scheme[cleanse-path], -simplified using @scheme[simplify-path], and then converted to a -directory path with @scheme[path->directory-path]; cleansing and +the path argument is @tech{cleanse}d using @racket[cleanse-path], +simplified using @racket[simplify-path], and then converted to a +directory path with @racket[path->directory-path]; cleansing and simplification raise an exception if the path is ill-formed. Thus, the -current value of @scheme[current-directory] is always a cleansed, +current value of @racket[current-directory] is always a cleansed, simplified, complete, directory path. The path is not checked for existence when the parameter is set.} @@ -363,18 +363,18 @@ of the current directory.} @defproc[(directory-exists? [path path-string?]) boolean?]{ -Returns @scheme[#t] if @scheme[path] refers to a directory, -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[path] refers to a directory, +@racket[#f] otherwise.} @defproc[(make-directory [path path-string?]) void?]{ -Creates a new directory with the path @scheme[path]. If the directory +Creates a new directory with the path @racket[path]. If the directory is not created successfully, the @exnraise[exn:fail:filesystem].} @defproc[(delete-directory [path path-string?]) void?]{ -Deletes an existing directory with the path @scheme[path]. If the +Deletes an existing directory with the path @racket[path]. If the directory is not deleted successfully, the @exnraise[exn:fail:filesystem].} @@ -383,7 +383,7 @@ directory is not deleted successfully, the (listof path?)]{ Returns a list of all files and directories in the directory specified -by @scheme[path]. If @scheme[path] is omitted, a list of files and +by @racket[path]. If @racket[path] is omitted, a list of files and directories in the current directory is returned. Under @|AllUnix|, an element of the list can start with @litchar{./~} if it would otherwise start with @litchar{~}. Under Windows, an element of the list may @@ -400,108 +400,108 @@ can be particularly slow under Windows.} @note-lib-only[racket/runtime-path] -The @schememodname[racket/runtime-path] library provides forms for +The @racketmodname[racket/runtime-path] library provides forms for accessing files and directories at run time using a path that are usually relative to an enclosing source file. Unlike using -@scheme[collection-path], @scheme[define-runtime-path] exposes each +@racket[collection-path], @racket[define-runtime-path] exposes each run-time path to tools like the executable and distribution creators, so that files and directories needed at run time are carried along in a distribution. In addition to the bindings described below, -@schememodname[racket/runtime-path] provides @scheme[#%datum] in +@racketmodname[racket/runtime-path] provides @racket[#%datum] in @tech{phase level} 1, since string constants are often used as -compile-time expressions with @scheme[define-runtime-path]. +compile-time expressions with @racket[define-runtime-path]. @defform[(define-runtime-path id expr)]{ -Uses @scheme[expr] as both a compile-time (i.e., @tech{phase} 1) +Uses @racket[expr] as both a compile-time (i.e., @tech{phase} 1) expression and a run-time (i.e., @tech{phase} 0) expression. In either -context, @scheme[expr] should produce a path, a string that represents -a path, a list of the form @scheme[(list 'lib _str ...+)], or a list -of the form @scheme[(list 'so _str)]. +context, @racket[expr] should produce a path, a string that represents +a path, a list of the form @racket[(list 'lib _str ...+)], or a list +of the form @racket[(list 'so _str)]. -For run time, @scheme[id] is bound to a path that is based on the -result of @scheme[expr]. The path is normally computed by taking a -relative path result from @scheme[expr] and adding it to a path for +For run time, @racket[id] is bound to a path that is based on the +result of @racket[expr]. The path is normally computed by taking a +relative path result from @racket[expr] and adding it to a path for the enclosing file (which is computed as described below). However, tools like the executable creator can also arrange (by colluding with -@schememodname[racket/runtime-path]) to have a different base path -substituted in a generated executable. If @scheme[expr] produces an +@racketmodname[racket/runtime-path]) to have a different base path +substituted in a generated executable. If @racket[expr] produces an absolute path, it is normally returned directly, but again may be replaced by an executable creator. In all cases, the executable creator preserves the relative locations of all paths. When -@scheme[expr] produces a relative or absolute path, then the path -bound to @scheme[id] is always an absolute path. +@racket[expr] produces a relative or absolute path, then the path +bound to @racket[id] is always an absolute path. -If @scheme[expr] produces a list of the form @scheme[(list 'lib _str -...+)], the value bound to @scheme[id] is an absolute path. The path +If @racket[expr] produces a list of the form @racket[(list 'lib _str +...+)], the value bound to @racket[id] is an absolute path. The path refers to a collection-based file similar to using the value as a @tech{module path}. -If @scheme[expr] produces a list of the form @scheme[(list 'so _str)], -the value bound to @scheme[id] can be either @scheme[_str] or an +If @racket[expr] produces a list of the form @racket[(list 'so _str)], +the value bound to @racket[id] can be either @racket[_str] or an absolute path; it is an absolute path when adding the platform-specific shared-library extension --- as produced by -@scheme[(system-type 'so-suffix)] --- and then searching in the -PLT-specific shared-object library directories (as determined by -@scheme[get-lib-search-dirs]) locates the path. In this way, shared-object -libraries that are installed specifically for PLT Scheme get carried +@racket[(system-type 'so-suffix)] --- and then searching in the +Racket-specific shared-object library directories (as determined by +@racket[get-lib-search-dirs]) locates the path. In this way, shared-object +libraries that are installed specifically for Racket get carried along in distributions. -For compile-time, the @scheme[expr] result is used by an executable +For compile-time, the @racket[expr] result is used by an executable creator---but not the result when the containing module is -compiled. Instead, @scheme[expr] is preserved in the module as a +compiled. Instead, @racket[expr] is preserved in the module as a compile-time expression (in the sense of -@scheme[begin-for-syntax]). Later, at the time that an executable is +@racket[begin-for-syntax]). Later, at the time that an executable is created, the compile-time portion of the module is executed (again), -and the result of @scheme[expr] is the file to be included with the +and the result of @racket[expr] is the file to be included with the executable. The reason for the extra compile-time execution is that -the result of @scheme[expr] might be platform-dependent, so the result +the result of @racket[expr] might be platform-dependent, so the result should not be stored in the (platform-independent) bytecode form of the module; the platform at executable-creation time, however, is the -same as at run time for the executable. Note that @scheme[expr] is +same as at run time for the executable. Note that @racket[expr] is still evaluated at run-time; consequently, avoid procedures like -@scheme[collection-path], which depends on the source installation, -and instead use relative paths and forms like @scheme[(list 'lib _str +@racket[collection-path], which depends on the source installation, +and instead use relative paths and forms like @racket[(list 'lib _str ...+)]. If a path is needed only on some platforms and not on others, use -@scheme[define-runtime-path-list] with an @scheme[expr] that produces an +@racket[define-runtime-path-list] with an @racket[expr] that produces an empty list on platforms where the path is not needed. -The enclosing path for a @scheme[define-runtime-path] is determined as -follows from the @scheme[define-runtime-path] syntactic form: +The enclosing path for a @racket[define-runtime-path] is determined as +follows from the @racket[define-runtime-path] syntactic form: @itemize[ @item{If the form has a source module according to - @scheme[syntax-source-module], then the source location is + @racket[syntax-source-module], then the source location is determined by preserving the original expression as a syntax object, extracting its source module path at run time (again - using @scheme[syntax-source-module]), and then resolving the + using @racket[syntax-source-module]), and then resolving the resulting module path index.} @item{If the expression has no source module, the - @scheme[syntax-source] location associated with the form is + @racket[syntax-source] location associated with the form is used, if is a string or path.} - @item{If no source module is available, and @scheme[syntax-source] - produces no path, then @scheme[current-load-relative-directory] - is used if it is not @scheme[#f]. Finally, - @scheme[current-directory] is used if all else fails.} + @item{If no source module is available, and @racket[syntax-source] + produces no path, then @racket[current-load-relative-directory] + is used if it is not @racket[#f]. Finally, + @racket[current-directory] is used if all else fails.} ] In the latter two cases, the path is normally preserved in (platform-specific) byte form. If it is is within the result of -@scheme[find-collects-dir], however, it the path is recorded relative -to @scheme[(find-collects-dir)], and it is reconstructed using -@scheme[(find-collects-dir)] at run time. +@racket[find-collects-dir], however, it the path is recorded relative +to @racket[(find-collects-dir)], and it is reconstructed using +@racket[(find-collects-dir)] at run time. Examples: -@schemeblock[ +@racketblock[ (code:comment @#,t{Access a file @filepath{data.txt} at run-time that is originally}) (code:comment @#,t{located in the same directory as the module source file:}) (define-runtime-path data-file "data.txt") @@ -510,7 +510,7 @@ Examples: (lambda () (read-bytes (file-size data-file))))) -(code:comment @#,t{Load a platform-specific shared object (using @scheme[ffi-lib])}) +(code:comment @#,t{Load a platform-specific shared object (using @racket[ffi-lib])}) (code:comment @#,t{that is located in a platform-specific sub-directory of the}) (code:comment @#,t{module's source directory:}) (define-runtime-path libfit-path @@ -521,7 +521,7 @@ Examples: (code:comment @#,t{Load a platform-specific shared object that might be installed}) (code:comment @#,t{as part of the operating system, or might be installed}) -(code:comment @#,t{specifically for PLT Scheme:}) +(code:comment @#,t{specifically for Racket:}) (define-runtime-path libssl-so (case (system-type) [(windows) '(so "ssleay32")] @@ -532,49 +532,49 @@ Examples: @defform[(define-runtime-paths (id ...) expr)]{ -Like @scheme[define-runtime-path], but declares and binds multiple -paths at once. The @scheme[expr] should produce as many values as -@scheme[id]s.} +Like @racket[define-runtime-path], but declares and binds multiple +paths at once. The @racket[expr] should produce as many values as +@racket[id]s.} @defform[(define-runtime-path-list id expr)]{ -Like @scheme[define-runtime-path], but @scheme[expr] should produce a +Like @racket[define-runtime-path], but @racket[expr] should produce a list of paths.} @defform[(define-runtime-module-path id module-path)]{ -Similar to @scheme[define-runtime-path], but @scheme[id] is bound to a +Similar to @racket[define-runtime-path], but @racket[id] is bound to a @tech{resolved module path}. The @tech{resolved module path} for -@scheme[id] corresponds to @scheme[module-path] (with the same syntax -as a module path for @scheme[require]), which can be relative to the +@racket[id] corresponds to @racket[module-path] (with the same syntax +as a module path for @racket[require]), which can be relative to the enclosing module. -Use @scheme[define-runtime-module-path] to bind a module path that is -passed to a reflective function like @scheme[dynamic-require] while +Use @racket[define-runtime-module-path] to bind a module path that is +passed to a reflective function like @racket[dynamic-require] while also creating a module dependency for building and distributing executables. -The @scheme[define-runtime-module-path] form creates a -@scheme[for-label] dependency from an enclosing module to -@scheme[module-path]. Since the dependency is merely -@scheme[for-label], @scheme[module-path] is not @tech{instantiate}d or +The @racket[define-runtime-module-path] form creates a +@racket[for-label] dependency from an enclosing module to +@racket[module-path]. Since the dependency is merely +@racket[for-label], @racket[module-path] is not @tech{instantiate}d or @tech{visit}ed when the enclosing module is @tech{instantiate}d or @tech{visit}ed (unless such a dependency is created by other -@scheme[require]s).} +@racket[require]s).} @defform[(runtime-paths module-path)]{ This form is mainly for use by tools such as executable builders. It expands to a quoted list containing the run-time paths declared by -@scheme[module-path], returning the compile-time results of the -declaration @scheme[expr]s, except that paths are converted to byte +@racket[module-path], returning the compile-time results of the +declaration @racket[expr]s, except that paths are converted to byte strings. The enclosing module must require (directly or indirectly) -the module specified by @scheme[module-path], which is an unquoted +the module specified by @racket[module-path], which is an unquoted module path. The resulting list does @emph{not} include module paths -bound through @scheme[define-runtime-module-path].} +bound through @racket[define-runtime-module-path].} @;------------------------------------------------------------------------ @section[#:tag "file-lib"]{More File and Directory Utilities} @@ -585,52 +585,52 @@ bound through @scheme[define-runtime-module-path].} [#:mode mode-flag (or/c 'binary 'text) 'binary]) string?]{ -Reads all characters from @scheme[path] and returns them as a string. -The @scheme[mode-flag] argument is the same as for -@scheme[open-input-file].} +Reads all characters from @racket[path] and returns them as a string. +The @racket[mode-flag] argument is the same as for +@racket[open-input-file].} @defproc[(file->bytes [path path-string?] [#:mode mode-flag (or/c 'binary 'text) 'binary]) bytes?]{ -Reads all characters from @scheme[path] and returns them as a -@tech{byte string}. The @scheme[mode-flag] argument is the same as -for @scheme[open-input-file].} +Reads all characters from @racket[path] and returns them as a +@tech{byte string}. The @racket[mode-flag] argument is the same as +for @racket[open-input-file].} @defproc[(file->value [path path-string?] [#:mode mode-flag (or/c 'binary 'text) 'binary]) bytes?]{ -Reads a single S-expression from @scheme[path] using @scheme[read]. -The @scheme[mode-flag] argument is the same as for -@scheme[open-input-file].} +Reads a single S-expression from @racket[path] using @racket[read]. +The @racket[mode-flag] argument is the same as for +@racket[open-input-file].} @defproc[(file->list [path path-string?] [proc (input-port? . -> . any/c) read] [#:mode mode-flag (or/c 'binary 'text) 'binary]) (listof any/c)]{ -Repeatedly calls @scheme[proc] to consume the contents of -@scheme[path], until @scheme[eof] is produced. The @scheme[mode-flag] -argument is the same as for @scheme[open-input-file]. } +Repeatedly calls @racket[proc] to consume the contents of +@racket[path], until @racket[eof] is produced. The @racket[mode-flag] +argument is the same as for @racket[open-input-file]. } @defproc[(file->lines [path path-string?] [#:mode mode-flag (or/c 'binary 'text) 'binary] [#:line-mode line-mode (or/c 'linefeed 'return 'return-linefeed 'any 'any-one) 'any]) (listof string?)]{ -Read all characters from @scheme[path], breaking them into lines. The -@scheme[line-mode] argument is the same as the second argument to -@scheme[read-line], but the default is @scheme['any] instead of -@scheme['linefeed]. The @scheme[mode-flag] argument is the same as for -@scheme[open-input-file].} +Read all characters from @racket[path], breaking them into lines. The +@racket[line-mode] argument is the same as the second argument to +@racket[read-line], but the default is @racket['any] instead of +@racket['linefeed]. The @racket[mode-flag] argument is the same as for +@racket[open-input-file].} @defproc[(file->bytes-lines [path path-string?] [#:mode mode-flag (or/c 'binary 'text) 'binary] [#:line-mode line-mode (or/c 'linefeed 'return 'return-linefeed 'any 'any-one) 'any]) (listof bytes?)]{ -Like @scheme[file->lines], but reading bytes and collecting them into -lines like @scheme[read-bytes-line].} +Like @racket[file->lines], but reading bytes and collecting them into +lines like @racket[read-bytes-line].} @defproc[(display-to-file [v any/c] [path path-string?] @@ -639,9 +639,9 @@ lines like @scheme[read-bytes-line].} 'replace 'truncate 'truncate/replace) 'error]) void?]{ -Uses @scheme[display] to print @scheme[v] to @scheme[path]. The @scheme[mode-flag] and -@scheme[exists-flag] arguments are the same as for -@scheme[open-output-file].} +Uses @racket[display] to print @racket[v] to @racket[path]. The @racket[mode-flag] and +@racket[exists-flag] arguments are the same as for +@racket[open-output-file].} @defproc[(write-to-file [v any/c] [path path-string?] @@ -650,7 +650,7 @@ Uses @scheme[display] to print @scheme[v] to @scheme[path]. The @scheme[mode-fla 'replace 'truncate 'truncate/replace) 'error]) void?]{ -Like @scheme[display-to-file], but using @scheme[write] instead of @scheme[display].} +Like @racket[display-to-file], but using @racket[write] instead of @racket[display].} @defproc[(display-lines-to-file [lst list?] [path path-string?] @@ -660,17 +660,17 @@ Like @scheme[display-to-file], but using @scheme[write] instead of @scheme[displ 'replace 'truncate 'truncate/replace) 'error]) void?]{ -Displays each element of @scheme[lst] to @scheme[path], adding -@scheme[separator] after each element. The @scheme[mode-flag] and -@scheme[exists-flag] arguments are the same as for -@scheme[open-output-file].} +Displays each element of @racket[lst] to @racket[path], adding +@racket[separator] after each element. The @racket[mode-flag] and +@racket[exists-flag] arguments are the same as for +@racket[open-output-file].} @defproc[(copy-directory/files [src path-string?][dest path-string?]) void?]{ -Copies the file or directory @scheme[src] to @scheme[dest], raising -@scheme[exn:fail:filesystem] if the file or directory cannot be -copied, possibly because @scheme[dest] exists already. If @scheme[src] +Copies the file or directory @racket[src] to @racket[dest], raising +@racket[exn:fail:filesystem] if the file or directory cannot be +copied, possibly because @racket[dest] exists already. If @racket[src] is a directory, the copy applies recursively to the directory's content. If a source is a link, the target of the link is copied rather than the link itself.} @@ -678,42 +678,42 @@ rather than the link itself.} @defproc[(delete-directory/files [path path-string?]) void?]{ -Deletes the file or directory specified by @scheme[path], raising -@scheme[exn:fail:filesystem] if the file or directory cannot be -deleted. If @scheme[path] is a directory, then -@scheme[delete-directory/files] is first applied to each file and -directory in @scheme[path] before the directory is deleted.} +Deletes the file or directory specified by @racket[path], raising +@racket[exn:fail:filesystem] if the file or directory cannot be +deleted. If @racket[path] is a directory, then +@racket[delete-directory/files] is first applied to each file and +directory in @racket[path] before the directory is deleted.} @defproc[(find-files [predicate (path? . -> . any/c)] [start-path (or/c path-string? #f) #f]) (listof path?)]{ -Traverses the filesystem starting at @scheme[start-path] and creates a -list of all files and directories for which @scheme[predicate] returns -true. If @scheme[start-path] is @scheme[#f], then the traversal starts -from @scheme[(current-directory)]. In the resulting list, each +Traverses the filesystem starting at @racket[start-path] and creates a +list of all files and directories for which @racket[predicate] returns +true. If @racket[start-path] is @racket[#f], then the traversal starts +from @racket[(current-directory)]. In the resulting list, each directory precedes its content. -The @scheme[predicate] procedure is called with a single argument for -each file or directory. If @scheme[start-path] is @scheme[#f], the +The @racket[predicate] procedure is called with a single argument for +each file or directory. If @racket[start-path] is @racket[#f], the argument is a pathname string that is relative to the current directory. Otherwise, it is a path building on -@scheme[start-path]. Consequently, supplying -@scheme[(current-directory)] for @scheme[start-path] is different from -supplying @scheme[#f], because @scheme[predicate] receives complete +@racket[start-path]. Consequently, supplying +@racket[(current-directory)] for @racket[start-path] is different from +supplying @racket[#f], because @racket[predicate] receives complete paths in the former case and relative paths in the latter. Another -difference is that @scheme[predicate] is not called for the current -directory when @scheme[start-path] is @scheme[#f]. +difference is that @racket[predicate] is not called for the current +directory when @racket[start-path] is @racket[#f]. -The @scheme[find-files] traversal follows soft links. To avoid -following links, use the more general @scheme[fold-files] procedure. +The @racket[find-files] traversal follows soft links. To avoid +following links, use the more general @racket[fold-files] procedure. -If @scheme[start-path] does not refer to an existing file or -directory, then @scheme[predicate] will be called exactly once with -@scheme[start-path] as the argument. +If @racket[start-path] does not refer to an existing file or +directory, then @racket[predicate] will be called exactly once with +@racket[start-path] as the argument. -The @scheme[find-files] procedure raises and exception if it encounters -a directory for which @scheme[directory-list] fails.} +The @racket[find-files] procedure raises and exception if it encounters +a directory for which @racket[directory-list] fails.} @defproc[(pathlist-closure [path-list (listof path-string?)]) (listof path?)]{ @@ -745,60 +745,60 @@ directory, returns a list such that [follow-links? any/c #t]) any]{ -Traverses the filesystem starting at @scheme[start-path], calling -@scheme[proc] on each discovered file, directory, and link. If -@scheme[start-path] is @scheme[#f], then the traversal starts from -@scheme[(current-directory)]. +Traverses the filesystem starting at @racket[start-path], calling +@racket[proc] on each discovered file, directory, and link. If +@racket[start-path] is @racket[#f], then the traversal starts from +@racket[(current-directory)]. -The @scheme[proc] procedure is called with three arguments for each +The @racket[proc] procedure is called with three arguments for each file, directory, or link: @itemize[ - @item{If @scheme[start-path] is @scheme[#f], the first argument is a + @item{If @racket[start-path] is @racket[#f], the first argument is a pathname string that is relative to the current directory. Otherwise, the first argument is a pathname that starts with - @scheme[start-path]. Consequently, supplying - @scheme[(current-directory)] for @scheme[start-path] is different - from supplying @scheme[#f], because @scheme[proc] receives complete + @racket[start-path]. Consequently, supplying + @racket[(current-directory)] for @racket[start-path] is different + from supplying @racket[#f], because @racket[proc] receives complete paths in the former case and relative paths in the latter. Another - difference is that @scheme[proc] is not called for the current - directory when @scheme[start-path] is @scheme[#f].} + difference is that @racket[proc] is not called for the current + directory when @racket[start-path] is @racket[#f].} - @item{The second argument is a symbol, either @scheme['file], - @scheme['dir], or @scheme['link]. The second argument can be - @scheme['link] when @scheme[follow-links?] is @scheme[#f], + @item{The second argument is a symbol, either @racket['file], + @racket['dir], or @racket['link]. The second argument can be + @racket['link] when @racket[follow-links?] is @racket[#f], in which case the filesystem traversal does not follow links. If - @scheme[follow-links?] is @scheme[#t], then @scheme[proc] - will only get a @scheme['link] as a second argument when it + @racket[follow-links?] is @racket[#t], then @racket[proc] + will only get a @racket['link] as a second argument when it encounters a dangling symbolic link (one that does not resolve to an existing file or directory).} @item{The third argument is the accumulated result. For the first - call to @scheme[proc], the third argument is @scheme[init-val]. For the - second call to @scheme[proc] (if any), the third argument is the result + call to @racket[proc], the third argument is @racket[init-val]. For the + second call to @racket[proc] (if any), the third argument is the result from the first call, and so on. The result of the last call to - @scheme[proc] is the result of @scheme[fold-files].} + @racket[proc] is the result of @racket[fold-files].} ] -The @scheme[proc] argument is used in an analogous way to the -procedure argument of @scheme[foldl], where its result is used as the +The @racket[proc] argument is used in an analogous way to the +procedure argument of @racket[foldl], where its result is used as the new accumulated result. There is an exception for the case of a -directory (when the second argument is @scheme['dir]): in this case +directory (when the second argument is @racket['dir]): in this case the procedure may return two values, the second indicating whether the recursive scan should include the given directory or not. If it returns a single value, the directory is scanned. In the cases of -files or links (when the second argument is @scheme['file] or -@scheme['link]), a second value is permitted but ignored. +files or links (when the second argument is @racket['file] or +@racket['link]), a second value is permitted but ignored. -If the @scheme[start-path] is provided but no such path exists, or if +If the @racket[start-path] is provided but no such path exists, or if paths disappear during the scan, then an exception is raised.} @defproc[(make-directory* [path path-string?]) void?]{ -Creates directory specified by @scheme[path], creating intermediate +Creates directory specified by @racket[path], creating intermediate directories as necessary.} @@ -812,27 +812,27 @@ file. Instead of merely generating a fresh file name, the file is actually created; this prevents other threads or processes from picking the same temporary name. -The @scheme[template] argument must be a format string suitable -for use with @scheme[format] and one additional string argument (where +The @racket[template] argument must be a format string suitable +for use with @racket[format] and one additional string argument (where the string contains only digits). If the resulting string is a relative path, it is combined with the result of -@scheme[(find-system-path 'temp-dir)], unless @scheme[directory] is -provided and non-@scheme[#f], in which case the -file name generated from @scheme[template] is combined with -@scheme[directory] to obtain a full path. +@racket[(find-system-path 'temp-dir)], unless @racket[directory] is +provided and non-@racket[#f], in which case the +file name generated from @racket[template] is combined with +@racket[directory] to obtain a full path. -If @scheme[copy-from-filename] is provided as path, the temporary file -is created as a copy of the named file (using @scheme[copy-file]). If -@scheme[copy-from-filename] is @scheme[#f], the temporary file is -created as empty. If @scheme[copy-from-filename] is -@scheme['directory], then the temporary ``file'' is created as a +If @racket[copy-from-filename] is provided as path, the temporary file +is created as a copy of the named file (using @racket[copy-file]). If +@racket[copy-from-filename] is @racket[#f], the temporary file is +created as empty. If @racket[copy-from-filename] is +@racket['directory], then the temporary ``file'' is created as a directory. When a temporary file is created, it is not opened for reading or writing when the pathname is returned. The client program calling -@scheme[make-temporary-file] is expected to open the file with the -desired access and flags (probably using the @scheme['truncate] flag; -see @scheme[open-output-file]) and to delete it when it is no longer +@racket[make-temporary-file] is expected to open the file with the +desired access and flags (probably using the @racket['truncate] flag; +see @racket[open-output-file]) and to delete it when it is no longer needed.} @defproc[(get-preference [name symbol?] @@ -842,33 +842,34 @@ needed.} any]{ Extracts a preference value from the file designated by -@scheme[(find-system-path 'pref-file)], or by @scheme[filename] if it -is provided and is not @scheme[#f]. In the former case, if the -preference file doesn't exist, @scheme[get-preferences] attempts to -read a @filepath{plt-prefs.ss} file in the @filepath{defaults} +@racket[(find-system-path 'pref-file)], or by @racket[filename] if it +is provided and is not @racket[#f]. In the former case, if the +preference file doesn't exist, @racket[get-preferences] attempts to +read a @filepath{racket-prefs.rkt} file in the @filepath{defaults} collection, instead. If neither file exists, the preference set is empty. The preference file should contain a symbol-keyed association list (written to the file with the default parameter settings). Keys -starting with @scheme[mzscheme:], @scheme[mred:], and @scheme[plt:] in -any letter case are reserved for use by PLT. +starting with @racket[racket:], @racket[mzscheme:], @racket[mred:], +and @racket[plt:] in any letter case are reserved for use by Racket +implementers. -The result of @scheme[get-preference] is the value associated with -@scheme[name] if it exists in the association list, or the result of -calling @scheme[failure-thunk] otherwise. +The result of @racket[get-preference] is the value associated with +@racket[name] if it exists in the association list, or the result of +calling @racket[failure-thunk] otherwise. Preference settings are cached (weakly) across calls to -@scheme[get-preference], using @scheme[(path->complete-path filename)] -as a cache key. If @scheme[flush-mode] is provided as @scheme[#f], the +@racket[get-preference], using @racket[(path->complete-path filename)] +as a cache key. If @racket[flush-mode] is provided as @racket[#f], the cache is used instead of the re-consulting the preferences file. If -@scheme[flush-mode] is provided as @scheme['timestamp] (the default), +@racket[flush-mode] is provided as @racket['timestamp] (the default), then the cache is used only if the file has a timestamp that is the same as the last time the file was read. Otherwise, the file is re-consulted. -See also @scheme[put-preferences]. For a more elaborate preference -system, see @scheme[preferences:get].} +See also @racket[put-preferences]. For a more elaborate preference +system, see @racket[preferences:get].} @@ -879,15 +880,15 @@ system, see @scheme[preferences:get].} void?]{ Installs a set of preference values and writes all current values to -the preference file designated by @scheme[(find-system-path -'pref-file)], or @scheme[filename] if it is supplied and not -@scheme[#f]. +the preference file designated by @racket[(find-system-path +'pref-file)], or @racket[filename] if it is supplied and not +@racket[#f]. -The @scheme[names] argument supplies the preference names, and -@scheme[vals] must have the same length as @scheme[names]. Each -element of @scheme[vals] must be an instance of a built-in data type -whose @scheme[write] output is @scheme[read]able (i.e., the -@scheme[print-unreadable] parameter is set to @scheme[#f] while +The @racket[names] argument supplies the preference names, and +@racket[vals] must have the same length as @racket[names]. Each +element of @racket[vals] must be an instance of a built-in data type +whose @racket[write] output is @racket[read]able (i.e., the +@racket[print-unreadable] parameter is set to @racket[#f] while writing preferences). Current preference values are read from the preference file before @@ -898,14 +899,14 @@ as the preference file. If the directory of the preferences file does not already exist, it is created. If the update lock is already held (i.e., the lock file exists), then -@scheme[locked] is called with a single argument: the path of the lock -file. The default @scheme[locked] reports an error; an alternative +@racket[locked] is called with a single argument: the path of the lock +file. The default @racket[locked] reports an error; an alternative thunk might wait a while and try again, or give the user the choice to delete the lock file (in case a previous update attempt encountered disaster). -If @scheme[filename] is @scheme[#f] or not supplied, and the +If @racket[filename] is @racket[#f] or not supplied, and the preference file does not already exist, then values read from the @filepath{defaults} collection (if any) are written for preferences -that are not mentioned in @scheme[names].} +that are not mentioned in @racket[names].} diff --git a/collects/scribblings/reference/logging.scrbl b/collects/scribblings/reference/logging.scrbl index 261a29ded6..89ab247ae0 100644 --- a/collects/scribblings/reference/logging.scrbl +++ b/collects/scribblings/reference/logging.scrbl @@ -9,9 +9,9 @@ logged for interested parties. A @deftech{log receiver} represents an interested party that receives logged events asynchronously. Each event has a level of importance, and a @tech{log receiver} subscribes to logging events at a certain level of importance and higher. The -levels, in decreasing order of importance, are @scheme['fatal], -@scheme['error], @scheme['warning], @scheme['info], and -@scheme['debug]. +levels, in decreasing order of importance, are @racket['fatal], +@racket['error], @racket['warning], @racket['info], and +@racket['debug]. To help organize logged events, @tech{loggers} can be named and hierarchical. Every event reported to a logger is also propagated to @@ -19,9 +19,9 @@ its parent (if any), but the event message is prefixed with the name (if any) of the logger to which is was originally reported. A logger is not required to have a parent or name. -On start-up, PLT Scheme creates an initial logger that is used to +On start-up, Racket creates an initial logger that is used to record events from the core run-time system. For example, an -@scheme['info] event is reported for each garbage collection (see +@racket['info] event is reported for each garbage collection (see @secref["gc-model"]). For this initial logger, two log receivers are also created: one that writes events to the process's original error output port, and one that writes events to the system log. The level @@ -35,10 +35,10 @@ through environment variables: defined and is not overridden by a command-line flag, it determines the level of the @tech{log receiver} that propagates events to the original error port. The environment variable's value - should be @scheme["none"], @scheme["fatal"], @scheme["error"], - @scheme["warning"], @scheme["info"], or @scheme["debug"]. + should be @racket["none"], @racket["fatal"], @racket["error"], + @racket["warning"], @racket["info"], or @racket["debug"]. - The default is @scheme["error"].} + The default is @racket["error"].} @item{If the @indexed-envvar{PLTSYSLOG} environment variable is defined and is not overridden by a command-line flag, it @@ -46,17 +46,17 @@ through environment variables: events to the system log. The possible values are the same as for @envvar{PLTSYSLOG}. - The default is @scheme["none"] for Unix or @scheme["error"] for + The default is @racket["none"] for Unix or @racket["error"] for Windows and Mac OS X.} ] -The @scheme[current-logger] @tech{parameter} determines the +The @racket[current-logger] @tech{parameter} determines the @deftech{current logger} that is used by forms such as -@scheme[log-warning]. On start-up, the initial value of this parameter +@racket[log-warning]. On start-up, the initial value of this parameter is the initial logger. The run-time system sometimes uses the current logger to report events. For example, the bytecode compiler sometimes -reports @scheme['warning] events when it detects an expression that +reports @racket['warning] events when it detects an expression that would produce a run-time error if evaluated. @; ---------------------------------------- @@ -64,7 +64,7 @@ would produce a run-time error if evaluated. @defproc[(logger? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{logger}, @scheme[#f] +Returns @racket[#t] if @racket[v] is a @tech{logger}, @racket[#f] otherwise.} @@ -77,7 +77,7 @@ Creates a new logger with an optional name and parent.} @defproc[(logger-name [logger logger?]) (or/c symbol? #f)]{ -Reports @scheme[logger]'s name, if any.} +Reports @racket[logger]'s name, if any.} @defparam[current-logger logger logger?]{ @@ -93,13 +93,13 @@ A @tech{parameter} that determines the @tech{current logger}.} [data any/c]) void?]{ -Reports an event to @scheme[logger], which in turn distributes the -information to any @tech{log receivers} attached to @scheme[logger] or -its ancestors that are interested in events at @scheme[level] or +Reports an event to @racket[logger], which in turn distributes the +information to any @tech{log receivers} attached to @racket[logger] or +its ancestors that are interested in events at @racket[level] or higher. -If @scheme[logger] has a name, then @scheme[message] is prefixed with -the logger's name followed by @scheme[": "] before it is sent to +If @racket[logger] has a name, then @racket[message] is prefixed with +the logger's name followed by @racket[": "] before it is sent to receivers.} @@ -107,13 +107,13 @@ receivers.} [level (or/c 'fatal 'error 'warning 'info 'debug)]) boolean?]{ -Reports whether any @tech{log receiver} attached to @scheme[logger] or -one of its ancestors is interested in @scheme[level] events (or +Reports whether any @tech{log receiver} attached to @racket[logger] or +one of its ancestors is interested in @racket[level] events (or potentially lower). Use this function to avoid work generating an -event for @scheme[log-message] if no receiver is interested in the -information; this shortcut is built into @scheme[log-fatal], -@scheme[log-error], @scheme[log-warning], @scheme[log-info], and -@scheme[log-debug], however, so it should not be used with those +event for @racket[log-message] if no receiver is interested in the +information; this shortcut is built into @racket[log-fatal], +@racket[log-error], @racket[log-warning], @racket[log-info], and +@racket[log-debug], however, so it should not be used with those forms. The result of this function can change if a garbage collection @@ -129,23 +129,23 @@ that any event information it receives will never become accessible).} )]{ Log an event with the @tech{current logger}, evaluating -@scheme[string-expr] only if the logger has receivers that are +@racket[string-expr] only if the logger has receivers that are interested in the event. In addition, the current continuation's @tech{continuation marks} are sent to the logger with the message string. -For each @schemekeywordfont{log-}@scheme[_level], +For each @racketkeywordfont{log-}@racket[_level], -@schemeblock[ -(@#,schemekeywordfont{log-}_level string-expr) +@racketblock[ +(@#,racketkeywordfont{log-}_level string-expr) ] is equivalent to -@schemeblock[ +@racketblock[ (let ([l (current-logger)]) - (when (log-level? l '@#,scheme[_level]) - (log-message l '@#,scheme[_level] string-expr + (when (log-level? l '@#,racket[_level]) + (log-message l '@#,racket[_level] string-expr (current-continuation-marks)))) ]} @@ -154,7 +154,7 @@ is equivalent to @defproc[(log-receiver? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{log receiver}, @scheme[#f] +Returns @racket[#t] if @racket[v] is a @tech{log receiver}, @racket[#f] otherwise.} @defproc[(make-log-receiver [logger logger?] @@ -162,13 +162,13 @@ otherwise.} log-receiver?]{ Creates a @tech{log receiver} to receive events of importance -@scheme[level] and higher as reported to @scheme[logger] and its +@racket[level] and higher as reported to @racket[logger] and its descendants. A @tech{log receiver} is a @tech{synchronizable event}. It becomes ready as an @tech{synchronizable event} when a logging event is -received, so use @scheme[sync] to receive an logged event. The +received, so use @racket[sync] to receive an logged event. The @tech{log receiver}'s synchronization value is a vector containing three values: the level of the event as a symbol, an immutable string for the event message, and an arbitrary value that was supplied as the -last argument to @scheme[log-message] when the event was logged.} +last argument to @racket[log-message] when the event was logged.} diff --git a/collects/scribblings/reference/module-reflect.scrbl b/collects/scribblings/reference/module-reflect.scrbl index 3ee439bc7e..4959db1f26 100644 --- a/collects/scribblings/reference/module-reflect.scrbl +++ b/collects/scribblings/reference/module-reflect.scrbl @@ -10,31 +10,31 @@ The name of a declared module is represented by a @deftech{resolved module path}, which encapsulates either a symbol or a complete filesystem path (see @secref["pathutils"]). A symbol normally refers to a predefined module or module declared through reflective -evaluation (e.g., @scheme[eval]). A filesystem path normally refers to -a module declaration that was loaded on demand via @scheme[require] or +evaluation (e.g., @racket[eval]). A filesystem path normally refers to +a module declaration that was loaded on demand via @racket[require] or other forms. A @deftech{module path} is a datum that matches the grammar for -@scheme[_module-path] for @scheme[require]. A module path is relative +@racket[_module-path] for @racket[require]. A module path is relative to another module. @defproc[(resolved-module-path? [v any/c]) boolean?]{ -Returns @scheme[#f] if @scheme[v] is a @tech{resolved module path}, -@scheme[#f] otherwise.} +Returns @racket[#f] if @racket[v] is a @tech{resolved module path}, +@racket[#f] otherwise.} @defproc[(make-resolved-module-path [path (or/c symbol? (and/c path? complete-path?))]) resolved-module-path?]{ -Returns a @tech{resolved module path} that encapsulates @scheme[path]. -If @scheme[path] is not a symbol, it normally should be -@tech{cleanse}d (see @scheme[cleanse-path]) and simplified (see -@scheme[simplify-path]). +Returns a @tech{resolved module path} that encapsulates @racket[path]. +If @racket[path] is not a symbol, it normally should be +@tech{cleanse}d (see @racket[cleanse-path]) and simplified (see +@racket[simplify-path]). A @tech{resolved module path} is interned. That is, if two @tech{resolved module path} values encapsulate paths that are -@scheme[equal?], then the @tech{resolved module path} values are -@scheme[eq?].} +@racket[equal?], then the @tech{resolved module path} values are +@racket[eq?].} @defproc[(resolved-module-path-name [module-path resolved-module-path?]) (or/c path? symbol?)]{ @@ -44,9 +44,9 @@ Returns the path or symbol encapsulated by a @tech{resolved module path}.} @defproc[(module-path? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] corresponds to a datum that matches -the grammar for @scheme[_module-path] for @scheme[require], -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] corresponds to a datum that matches +the grammar for @racket[_module-path] for @racket[require], +@racket[#f] otherwise.} @defparam[current-module-name-resolver proc @@ -62,10 +62,10 @@ the grammar for @scheme[_module-path] for @scheme[require], A parameter that determines the current @deftech{module name resolver}, which manages the conversion from other kinds of module references to a @tech{resolved module path}. For example, -when the expander encounters @scheme[(require _module-path)] where -@scheme[_module-path] is not an identifier, then the expander passes -@scheme['_module-path] to the module name resolver to obtain a symbol -or resolved module path. When such a @scheme[require] appears within a +when the expander encounters @racket[(require _module-path)] where +@racket[_module-path] is not an identifier, then the expander passes +@racket['_module-path] to the module name resolver to obtain a symbol +or resolved module path. When such a @racket[require] appears within a module, the @deftech{module path resolver} is also given the name of the enclosing module, so that a relative reference can be converted to an absolute symbol or @tech{resolved module path}. @@ -81,14 +81,14 @@ A @tech{module name resolver} takes one and four arguments: is ignored.} @item{When given four arguments, the first is a module path, either - equivalent to a quoted @scheme[module-path] for @scheme[require] or + equivalent to a quoted @racket[module-path] for @racket[require] or a file system path. The second is name for the source module, if any, to which the path is relative; if the second argument is - @scheme[#f], the module path is relative to @scheme[(or + @racket[#f], the module path is relative to @racket[(or (current-load-relative-directory) (current-directory))]. The third argument is a @tech{syntax object} that can be used for error - reporting, if it is not @scheme[#f]. If the last argument is - @scheme[#t], then the module declaration should be loaded (if it is + reporting, if it is not @racket[#f]. If the last argument is + @racket[#t], then the module declaration should be loaded (if it is not already), otherwise the module path should be simply resolved to a name. The result is the resolved name.} @@ -96,23 +96,23 @@ A @tech{module name resolver} takes one and four arguments: For the second case, the standard module name resolver keeps a per-registry table of loaded module name. If a resolved module path is -not in the table, and @scheme[#f] is not provided as the third +not in the table, and @racket[#f] is not provided as the third argument to the @tech{module name resolver}, then the name is put into the table and the corresponding file is loaded with a variant of -@scheme[load/use-compiled] that passes the expected module name to the +@racket[load/use-compiled] that passes the expected module name to the @tech{compiled-load handler}. While loading a file, the default @tech{module name resolver} sets the -@scheme[current-module-declare-name] parameter to the resolved module +@racket[current-module-declare-name] parameter to the resolved module name (while the @tech{compiled-load handler} sets -@scheme[current-module-declare-source]). Also, the default +@racket[current-module-declare-source]). Also, the default @tech{module name resolver} records in a private @tech{continuation mark} the module being loaded, and it checks whether such a mark already exists; if such a continuation mark does exist in the current continuation, then the @exnraise[exn:fail] with a message about a dependency cycle. -Module loading is suppressed (i.e., @scheme[#f] is supplied as a third +Module loading is suppressed (i.e., @racket[#f] is supplied as a third argument to the module name resolver) when resolving module paths in @tech{syntax objects} (see @secref["stxobj-model"]). When a @tech{syntax object} is manipulated, the current namespace might not @@ -120,54 +120,54 @@ match the original namespace for the syntax object, and the module should not necessarily be loaded in the current namespace. The current module name resolver is called with a single argument by -@scheme[namespace-attach-module] to notify the resolver that a module +@racket[namespace-attach-module] to notify the resolver that a module was attached to the current namespace (and should not be loaded in the -future for the namespace's registry). No other Scheme operation +future for the namespace's registry). No other Racket operation invokes the module name resolver with a single argument, but other -tools (such as DrScheme) might call this resolver in this mode to +tools (such as DrRacket) might call this resolver in this mode to avoid redundant module loads.} @defparam[current-module-declare-name name (or/c resolved-module-path? #f)]{ A parameter that determines a module name that is used when evaluating -a @scheme[module] declaration (when the parameter value is not -@scheme[#f]). In that case, the @scheme[_id] from the @scheme[module] +a @racket[module] declaration (when the parameter value is not +@racket[#f]). In that case, the @racket[_id] from the @racket[module] declaration is ignored, and the parameter's value is used as the name of the declared module.} @defparam[current-module-declare-source src (or/c symbol? (and/c path? complete-path?) #f)]{ A parameter that determines source information to be associated with a -module when evaluating a @scheme[module] declaration. Source +module when evaluating a @racket[module] declaration. Source information is used in error messages and reflected by -@scheme[variable-reference->module-source]. When the parameter value -is @scheme[#f], the module's name (as determined by -@scheme[current-module-declare-name]) is used as the source name +@racket[variable-reference->module-source]. When the parameter value +is @racket[#f], the module's name (as determined by +@racket[current-module-declare-name]) is used as the source name instead of the parameter value.} @;------------------------------------------------------------------------ @section[#:tag "modpathidx"]{Compiled Modules and References} -While expanding a @scheme[module] declaration, the expander resolves +While expanding a @racket[module] declaration, the expander resolves module paths for imports to load module declarations as necessary and to determine imported bindings, but the compiled form of a -@scheme[module] declaration preserves the original module path. +@racket[module] declaration preserves the original module path. Consequently, a compiled module can be moved to another filesystem, where the module name resolver can resolve inter-module references among compiled code. When a module reference is extracted from compiled form (see -@scheme[module-compiled-imports]) or from syntax objects in macro +@racket[module-compiled-imports]) or from syntax objects in macro expansion (see @secref["stxops"]), the module reference is reported in the form of a @deftech{module path index}. A @tech{module path index} is a semi-interned (multiple references to the same relative module tend to use the same @tech{module path index} value, but not always) -opaque value that encodes a module path (see @scheme[module-path?]) +opaque value that encodes a module path (see @racket[module-path?]) and either a @tech{resolved module path} or another @tech{module path index} to which it is relative. -A @tech{module path index} that uses both @scheme[#f] for its path and +A @tech{module path index} that uses both @racket[#f] for its path and base @tech{module path index} represents ``self''---i.e., the module declaration that was the source of the @tech{module path index}---and such a @tech{module path index} can be used as the root for a chain of @@ -178,7 +178,7 @@ identifier's source module is reported using the ``self'' @tech{module path index}. If the identifier is instead defined in a module that is imported via a module path (as opposed to a literal module name), then the identifier's source module will be reported using a @tech{module -path index} that contains the @scheme[require]d module path and the +path index} that contains the @racket[require]d module path and the ``self'' @tech{module path index}. @@ -194,23 +194,23 @@ name than the name when it was compiled. @defproc[(module-path-index? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a @tech{module path index}, -@scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a @tech{module path index}, +@racket[#f] otherwise.} @defproc[(module-path-index-resolve [mpi module-path-index?]) resolved-module-path?]{ Returns a @tech{resolved module path} for the resolved module name, -computing the resolved name (and storing it in @scheme[mpi]) if it has +computing the resolved name (and storing it in @racket[mpi]) if it has not been computed before. Resolving a @tech{module path index} uses the current @tech{module -name resolver} (see @scheme[current-module-name-resolver]). Depending -on the kind of module paths encapsulated by @scheme[mpi], the computed +name resolver} (see @racket[current-module-name-resolver]). Depending +on the kind of module paths encapsulated by @racket[mpi], the computed resolved name can depend on the value of -@scheme[current-load-relative-directory] or -@scheme[current-directory].} +@racket[current-load-relative-directory] or +@racket[current-directory].} @defproc[(module-path-index-split [mpi module-path-index?]) @@ -218,30 +218,30 @@ resolved name can depend on the value of (or/c module-path-index? resolved-module-path? #f))]{ Returns two values: a module path, and a base @tech{module path index} -or @scheme[#f] to which the module path is relative. +or @racket[#f] to which the module path is relative. -A @scheme[#f] second result means that the path is relative to an +A @racket[#f] second result means that the path is relative to an unspecified directory (i.e., its resolution depends on the value of -@scheme[current-load-relative-directory] and/or -@scheme[current-directory]). +@racket[current-load-relative-directory] and/or +@racket[current-directory]). -A @scheme[#f] for the first result implies a @scheme[#f] for the -second result, and means that @scheme[mpi] represents ``self'' (see +A @racket[#f] for the first result implies a @racket[#f] for the +second result, and means that @racket[mpi] represents ``self'' (see above).} @defproc[(module-path-index-join [path (or/c module-path? #f)] [mpi (or/c module-path-index? resolved-module-path? #f)]) module-path-index?]{ -Combines @scheme[path] and @scheme[mpi] to create a new @tech{module -path index}. The @scheme[path] argument can @scheme[#f] only if -@scheme[mpi] is also @scheme[#f].} +Combines @racket[path] and @racket[mpi] to create a new @tech{module +path index}. The @racket[path] argument can @racket[#f] only if +@racket[mpi] is also @racket[#f].} @defproc[(compiled-module-expression? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a compiled @scheme[module] -declaration, @scheme[#f] otherwise. See also -@scheme[current-compile].} +Returns @racket[#t] if @racket[v] is a compiled @racket[module] +declaration, @racket[#f] otherwise. See also +@racket[current-compile].} @defproc[(module-compiled-name [compiled-module-code compiled-module-expression?]) @@ -256,7 +256,7 @@ the module's declared name.} (listof module-path-index?)))]{ Takes a module declaration in compiled form and returns an association -list mapping @tech{phase level} shifts (where @scheme[#f] corresponds +list mapping @tech{phase level} shifts (where @racket[#f] corresponds to a shift into the @tech{label phase level}) to module references for the module's explicit imports.} @@ -266,16 +266,16 @@ the module's explicit imports.} (listof (cons/c (or/c exact-integer? #f) list?)))] Returns two association lists mapping @tech{phase level} values (where -@scheme[#f] corresponds to the @tech{label phase level}) to exports at +@racket[#f] corresponds to the @tech{label phase level}) to exports at the corresponding phase. The first association list is for exported variables, and the second is for exported syntax. Beware however, that value bindings re-exported though a @tech{rename transformer} are in the syntax list instead of the value list. -Each associated list, which is represented by @scheme[list?] in the +Each associated list, which is represented by @racket[list?] in the result contracts above, more precisely matches the contract -@schemeblock[ +@racketblock[ (listof (list/c symbol? (listof (or/c module-path-index? @@ -290,19 +290,19 @@ export. The second part---the list of @tech{module path index} values, etc.---describes the origin of the exported identifier. If the origin -list is @scheme[null], then the exported identifier is defined in the +list is @racket[null], then the exported identifier is defined in the module. If the exported identifier is re-exported, instead, then the origin list provides information on the import that was re-exported. The origin list has more than one element if the binding was imported multiple times from (possibly) different sources. For each origin, a @tech{module path index} by itself means that the -binding was imported with a @tech{phase level} shift of @scheme[0] -(i.e., a plain @scheme[require] without @scheme[for-meta], -@scheme[for-syntax], etc.), and imported identifier has the same name +binding was imported with a @tech{phase level} shift of @racket[0] +(i.e., a plain @racket[require] without @racket[for-meta], +@racket[for-syntax], etc.), and imported identifier has the same name as the re-exported name. An origin represented with a list indicates explicitly the import, the import @tech{phase level} shift (where -@scheme[#f] corresponds to a @scheme[for-label] import), the import +@racket[#f] corresponds to a @racket[for-label] import), the import name of the re-exported binding, and the @tech{phase level} of the import.} @@ -311,19 +311,19 @@ import.} Returns information intended to reflect the ``language'' of the module's implementation as originally attached to the syntax of the -module's declaration though the @indexed-scheme['module-language] -@tech{syntax property}. See also @scheme[module]. +module's declaration though the @indexed-racket['module-language] +@tech{syntax property}. See also @racket[module]. If no information is available for the module, the result is -@scheme[#f]. Otherwise, the result is @scheme[(vector _mp _name _val)] -such that @scheme[((dynamic-require _mp _name) _val)] should return +@racket[#f]. Otherwise, the result is @racket[(vector _mp _name _val)] +such that @racket[((dynamic-require _mp _name) _val)] should return function that takes two arguments. The function's arguments are a key for reflected information and a default value. Acceptable keys and the interpretation of results is up to external tools, such as -DrScheme. If no information is available for a given key, the result +DrRacket. If no information is available for a given key, the result should be the given default value. -See also @scheme[module->language-info].} +See also @racket[module->language-info].} @;------------------------------------------------------------------------ @@ -334,37 +334,37 @@ See also @scheme[module->language-info].} [fail-thunk (-> any) (lambda () ....)]) any]{ -Dynamically @tech{instantiates} the module specified by @scheme[mod] +Dynamically @tech{instantiates} the module specified by @racket[mod] in the current namespace's registry at the namespace's @tech{base phase}, if it is not yet @tech{instantiate}d. The current @tech{module -name resolver} may load a module declaration to resolve @scheme[mod] -(see @scheme[current-module-name-resolver]); the path is resolved -relative to @scheme[current-load-relative-directory] and/or -@scheme[current-directory]. +name resolver} may load a module declaration to resolve @racket[mod] +(see @racket[current-module-name-resolver]); the path is resolved +relative to @racket[current-load-relative-directory] and/or +@racket[current-directory]. -If @scheme[provided] is @scheme[#f], then the result is @|void-const|, +If @racket[provided] is @racket[#f], then the result is @|void-const|, and the module is not @tech{visit}ed (see @secref["mod-parse"]) or even made @tech{available} (for on-demand @tech{visits}) in phases above the @tech{base phase}. -When @scheme[provided] is a symbol, the value of the module's export +When @racket[provided] is a symbol, the value of the module's export with the given name is returned, and still the module is not @tech{visit}ed or made @tech{available} in higher phases. If the -module exports @scheme[provide] as syntax, then a use of the binding +module exports @racket[provide] as syntax, then a use of the binding is expanded and evaluated in a fresh namespace to which the module is attached, which means that the module is @tech{visit}ed in the fresh namespace. If the module has no such exported variable or syntax, then -@scheme[fail-thunk] is called; the default @scheme[fail-thunk] raises -@scheme[exn:fail:contract]. If the variable named by @scheme[provided] +@racket[fail-thunk] is called; the default @racket[fail-thunk] raises +@racket[exn:fail:contract]. If the variable named by @racket[provided] is exported protected (see @secref["modprotect"]), then the @exnraise[exn:fail:contract]. -If @scheme[provided] is @scheme[0], then the module is +If @racket[provided] is @racket[0], then the module is @tech{instantiate}d but not @tech{visit}ed, the same as when -@scheme[provided] is @scheme[#f]. With @scheme[0], however, the module +@racket[provided] is @racket[#f]. With @racket[0], however, the module is made @tech{available} in higher phases. -If @scheme[provided] is @|void-const|, then the module is +If @racket[provided] is @|void-const|, then the module is @tech{visit}ed but not @tech{instantiate}d (see @secref["mod-parse"]), and the result is @|void-const|.} @@ -374,7 +374,7 @@ and the result is @|void-const|.} [fail-thunk (-> any) (lambda () ....)]) any]{ -Like @scheme[dynamic-require], but in a @tech{phase} that is @math{1} +Like @racket[dynamic-require], but in a @tech{phase} that is @math{1} more than the namespace's @tech{base phase}.} @@ -384,13 +384,13 @@ more than the namespace's @tech{base phase}.} (or/c #f (vector/c module-path? symbol? any/c))]{ Returns information intended to reflect the ``language'' of the -implementation of @scheme[mod]. If @scheme[load?] is @scheme[#f], the -module named by @scheme[mod] must be declared (but not necessarily +implementation of @racket[mod]. If @racket[load?] is @racket[#f], the +module named by @racket[mod] must be declared (but not necessarily @tech{instantiate}d or @tech{visit}ed) in the current namespace; -otherwise, @scheme[mod] may be loaded (as for @scheme[dynamic-require] +otherwise, @racket[mod] may be loaded (as for @racket[dynamic-require] and other functions). The information returned by -@scheme[module->language-info] is the same as would have been returned -by @scheme[module-compiled-language-info] applied to the module's +@racket[module->language-info] is the same as would have been returned +by @racket[module-compiled-language-info] applied to the module's implementation as compiled code.} @@ -399,8 +399,8 @@ implementation as compiled code.} (listof (cons/c (or/c exact-integer? #f) (listof module-path-index?)))]{ -Like @scheme[module-compiled-imports], but produces the imports of -@scheme[mod], which must be declared (but not necessarily +Like @racket[module-compiled-imports], but produces the imports of +@racket[mod], which must be declared (but not necessarily @tech{instantiate}d or @tech{visit}ed) in the current namespace.} @@ -409,6 +409,6 @@ Like @scheme[module-compiled-imports], but produces the imports of (values (listof (cons/c (or/c exact-integer? #f) list?)) (listof (cons/c (or/c exact-integer? #f) list?)))]{ -Like @scheme[module-compiled-exports], but produces the exports of -@scheme[mod], which must be declared (but not necessarily +Like @racket[module-compiled-exports], but produces the exports of +@racket[mod], which must be declared (but not necessarily @tech{instantiate}d or @tech{visit}ed) in the current namespace.} diff --git a/collects/scribblings/reference/paths.scrbl b/collects/scribblings/reference/paths.scrbl index b61a29285b..8b160d0e6b 100644 --- a/collects/scribblings/reference/paths.scrbl +++ b/collects/scribblings/reference/paths.scrbl @@ -3,36 +3,36 @@ @title[#:tag "pathutils" #:style 'toc]{Paths} -When a Scheme procedure takes a filesystem path as an argument, the +When a Racket procedure takes a filesystem path as an argument, the path can be provided either as a string or as an instance of the @deftech{path} datatype. If a string is provided, it is converted to a -path using @scheme[string->path]. A Scheme procedure that generates a +path using @racket[string->path]. A Racket procedure that generates a filesystem path always generates a @tech{path} value. By default, paths are created and manipulated for the current platform, but procedures that merely manipulate paths (without using the filesystem) can manipulate paths using conventions for other -supported platforms. The @scheme[bytes->path] procedure accepts an +supported platforms. The @racket[bytes->path] procedure accepts an optional argument that indicates the platform for the path, either -@scheme['unix] or @scheme['windows]. For other functions, such as -@scheme[build-path] or @scheme[simplify-path], the behavior is +@racket['unix] or @racket['windows]. For other functions, such as +@racket[build-path] or @racket[simplify-path], the behavior is sensitive to the kind of path that is supplied. Unless otherwise specified, a procedure that requires a path accepts only paths for the current platform. -Two @tech{path} values are @scheme[equal?] when they are use the same +Two @tech{path} values are @racket[equal?] when they are use the same convention type and when their byte-string representations are -@scheme[equal?]. A path string (or byte string) cannot be empty, and +@racket[equal?]. A path string (or byte string) cannot be empty, and it cannot contain a nul character or byte. When an empty string or a string containing nul is provided as a path to any procedure except -@scheme[absolute-path?], @scheme[relative-path?], or -@scheme[complete-path?], the @exnraise[exn:fail:contract]. +@racket[absolute-path?], @racket[relative-path?], or +@racket[complete-path?], the @exnraise[exn:fail:contract]. -Most Scheme primitives that accept paths first @deftech{cleanse} the +Most Racket primitives that accept paths first @deftech{cleanse} the path before using it. Procedures that build paths or merely check the form of a path do not cleanse paths, with the exceptions of -@scheme[cleanse-path], @scheme[expand-user-path], and -@scheme[simplify-path]. For more information about path cleansing and +@racket[cleanse-path], @racket[expand-user-path], and +@racket[simplify-path]. For more information about path cleansing and other platform-specific details, see @secref["unixpaths"] for @|AllUnix| paths and @secref["windowspaths"] for Windows paths. @@ -41,149 +41,149 @@ other platform-specific details, see @secref["unixpaths"] for @defproc[(path? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a path value for the current +Returns @racket[#t] if @racket[v] is a path value for the current platform (not a string, and not a path for a different platform), -@scheme[#f] otherwise.} +@racket[#f] otherwise.} @defproc[(path-string? [v any/c]) boolean?]{ -Return @scheme[#t] if @scheme[v] is either a path value for the +Return @racket[#t] if @racket[v] is either a path value for the current platform or a non-empty string without nul characters, -@scheme[#f] otherwise.} +@racket[#f] otherwise.} @defproc[(path-for-some-system? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a path value for some platform -(not a string), @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is a path value for some platform +(not a string), @racket[#f] otherwise.} @defproc[(string->path [str string?]) path?]{ Produces a path whose byte-string name is -@scheme[(string->bytes/locale string (char->integer #\?))]. +@racket[(string->bytes/locale string (char->integer #\?))]. Beware that the current locale might not encode every string, in which -case @scheme[string->path] can produce the same path for different -@scheme[str]s. See also @scheme[string->path-element], which should be -used instead of @scheme[string->path] when a string represents a +case @racket[string->path] can produce the same path for different +@racket[str]s. See also @racket[string->path-element], which should be +used instead of @racket[string->path] when a string represents a single path element. -See also @scheme[string->some-system-path].} +See also @racket[string->some-system-path].} @defproc[(bytes->path [bstr bytes?] [type (or/c 'unix 'windows) (system-path-convention-type)]) path?]{ Produces a path (for some platform) whose byte-string name is -@scheme[bstr]. The optional @scheme[type] specifies the convention to +@racket[bstr]. The optional @racket[type] specifies the convention to use for the path. For converting relative path elements from literals, use instead -@scheme[bytes->path-element], which applies a suitable encoding for +@racket[bytes->path-element], which applies a suitable encoding for individual elements.} @defproc[(path->string [path path?]) string?]{ -Produces a string that represents @scheme[path] by decoding -@scheme[path]'s byte-string name using the current locale's encoding; +Produces a string that represents @racket[path] by decoding +@racket[path]'s byte-string name using the current locale's encoding; @litchar{?} is used in the result string where encoding fails, and if the encoding result is the empty string, then the result is -@scheme["?"]. +@racket["?"]. The resulting string is suitable for displaying to a user, string-ordering comparisons, etc., but it is not suitable for -re-creating a path (possibly modified) via @scheme[string->path], +re-creating a path (possibly modified) via @racket[string->path], since decoding and re-encoding the path's byte string may lose information. Furthermore, for display and sorting based on individual path elements -(such as pathless file names), use @scheme[path-element->string], +(such as pathless file names), use @racket[path-element->string], instead, to avoid special encodings use to represent some relative paths. See @secref["windowspaths"] for specific information about the conversion of Windows paths. -See also @scheme[some-system-path->string].} +See also @racket[some-system-path->string].} @defproc[(path->bytes [path path?]) bytes?]{ -Produces @scheme[path]'s byte string representation. No information is -lost in this translation, so that @scheme[(bytes->path (path->bytes +Produces @racket[path]'s byte string representation. No information is +lost in this translation, so that @racket[(bytes->path (path->bytes path) (path-convention-type path))] always produces a path is that is -@scheme[equal?] to @scheme[path]. The @scheme[path] argument can be a +@racket[equal?] to @racket[path]. The @racket[path] argument can be a path for any platform. Conversion to and from byte values is useful for marshaling and unmarshaling paths, but manipulating the byte form of a path is generally a mistake. In particular, the byte string may start with a @litchar{\\?\REL} encoding for Windows paths. Instead of -@scheme[path->bytes], use @scheme[split-path] and -@scheme[path-element->bytes] to manipulate individual path elements.} +@racket[path->bytes], use @racket[split-path] and +@racket[path-element->bytes] to manipulate individual path elements.} @defproc[(string->path-element [str string?]) path?]{ -Like @scheme[string->path], except that @scheme[str] corresponds to a +Like @racket[string->path], except that @racket[str] corresponds to a single relative element in a path, and it is encoded as necessary to convert it to a path. See @secref["unixpaths"] for more information on the conversion for @|AllUnix| paths, and see @secref["windowspaths"] for more information on the conversion for Windows paths. -If @scheme[str] does not correspond to any path element +If @racket[str] does not correspond to any path element (e.g., it is an absolute path, or it can be split), or if it corresponds to an up-directory or same-directory indicator under @|AllUnix|, then @exnraise[exn:fail:contract]. -As for @scheme[path->string], information can be lost from -@scheme[str] in the locale-specific conversion to a path.} +As for @racket[path->string], information can be lost from +@racket[str] in the locale-specific conversion to a path.} @defproc[(bytes->path-element [bstr bytes?] [type (or/c 'unix 'windows) (system-path-convention-type)]) path?]{ -Like @scheme[bytes->path], except that @scheme[bstr] corresponds to a +Like @racket[bytes->path], except that @racket[bstr] corresponds to a single relative element in a path. In terms of conversions and -restrictions on @scheme[bstr], @scheme[bytes->path-element] is like -@scheme[string->path-element]. +restrictions on @racket[bstr], @racket[bytes->path-element] is like +@racket[string->path-element]. -The @scheme[bytes->path-element] procedure is generally the best +The @racket[bytes->path-element] procedure is generally the best choice for reconstructing a path based on another path (where the -other path is deconstructed with @scheme[split-path] and -@scheme[path-element->bytes]) when ASCII-level manipulation of path +other path is deconstructed with @racket[split-path] and +@racket[path-element->bytes]) when ASCII-level manipulation of path elements is necessary.} @defproc[(path-element->string [path path?]) string?]{ -Like @scheme[path->string], except any encoding prefix is removed. See +Like @racket[path->string], except any encoding prefix is removed. See @secref["unixpaths"] for more information on the conversion for @|AllUnix| paths, and see @secref["windowspaths"] for more information on the conversion for Windows paths. In addition, trailing path separators are removed, as by -@scheme[split-path]. +@racket[split-path]. -The @scheme[path] argument must be such that @scheme[split-path] -applied to @scheme[path] would return @scheme['relative] as its first +The @racket[path] argument must be such that @racket[split-path] +applied to @racket[path] would return @racket['relative] as its first result and a path as its second result, otherwise the @exnraise[exn:fail:contract]. -The @scheme[path-element->string] procedure is generally the best +The @racket[path-element->string] procedure is generally the best choice for presenting a pathless file or directory name to a user.} @defproc[(path-element->bytes [path path-string?]) bytes?]{ -Like @scheme[path->bytes], except that any encoding prefix is removed, -etc., as for @scheme[path-element->string]. +Like @racket[path->bytes], except that any encoding prefix is removed, +etc., as for @racket[path-element->string]. For any reasonable locale, consecutive ASCII characters in the printed -form of @scheme[path] are mapped to consecutive byte values that match +form of @racket[path] are mapped to consecutive byte values that match each character's code-point value, and a leading or trailing ASCII character is mapped to a leading or trailing byte, respectively. The -@scheme[path] argument can be a path for any platform. +@racket[path] argument can be a path for any platform. -The @scheme[path-element->bytes] procedure is generally the right -choice (in combination with @scheme[split-path]) for extracting the +The @racket[path-element->bytes] procedure is generally the right +choice (in combination with @racket[split-path]) for extracting the content of a path to manipulate it at the ASCII level (then -reassembling the result with @scheme[bytes->path-element] and -@scheme[build-path]).} +reassembling the result with @racket[bytes->path-element] and +@racket[build-path]).} @defproc[(path-convention-type [path path?]) @@ -197,7 +197,7 @@ type.} (or/c 'unix 'windows)]{ Returns the path convention type of the current platform: -@indexed-scheme['unix] for @|AllUnix|, @indexed-scheme['windows] for +@indexed-racket['unix] for @|AllUnix|, @indexed-racket['windows] for Windows.} @@ -208,34 +208,34 @@ Windows.} path?]{ Creates a path given a base path and any number of sub-path -extensions. If @scheme[base] is an absolute path, the result is an +extensions. If @racket[base] is an absolute path, the result is an absolute path, otherwise the result is a relative path. -The @scheme[base] and each @scheme[sub] must be either a relative -path, the symbol @indexed-scheme['up] (indicating the relative parent -directory), or the symbol @indexed-scheme['same] (indicating the -relative current directory). For Windows paths, if @scheme[base] is a +The @racket[base] and each @racket[sub] must be either a relative +path, the symbol @indexed-racket['up] (indicating the relative parent +directory), or the symbol @indexed-racket['same] (indicating the +relative current directory). For Windows paths, if @racket[base] is a drive specification (with or without a trailing slash) the first -@scheme[sub] can be an absolute (driveless) path. For all platforms, -the last @scheme[sub] can be a filename. +@racket[sub] can be an absolute (driveless) path. For all platforms, +the last @racket[sub] can be a filename. -The @scheme[base] and @scheme[sub-paths] arguments can be paths for +The @racket[base] and @racket[sub-paths] arguments can be paths for any platform. The platform for the resulting path is inferred from the -@scheme[base] and @scheme[sub] arguments, where string arguments imply +@racket[base] and @racket[sub] arguments, where string arguments imply a path for the current platform. If different arguments are for different platforms, the @exnraise[exn:fail:contract]. If no argument -implies a platform (i.e., all are @scheme['up] or @scheme['same]), the +implies a platform (i.e., all are @racket['up] or @racket['same]), the generated path is for the current platform. -Each @scheme[sub] and @scheme[base] can optionally end in a directory -separator. If the last @scheme[sub] ends in a separator, it is +Each @racket[sub] and @racket[base] can optionally end in a directory +separator. If the last @racket[sub] ends in a separator, it is included in the resulting path. -If @scheme[base] or @scheme[sub] is an illegal path string (because it +If @racket[base] or @racket[sub] is an illegal path string (because it is empty or contains a nul character), the @exnraise[exn:fail:contract]. -The @scheme[build-path] procedure builds a path @italic{without} +The @racket[build-path] procedure builds a path @italic{without} checking the validity of the path or accessing the filesystem. See @secref["unixpaths"] for more information on the construction @@ -246,18 +246,18 @@ The following examples assume that the current directory is @filepath{/home/joeuser} for Unix examples and @filepath{C:\Joe's Files} for Windows examples. -@schemeblock[ -(define p1 (build-path (current-directory) "src" "scheme")) - (code:comment @#,t{Unix: @scheme[p1] is @scheme["/home/joeuser/src/scheme"]}) - (code:comment @#,t{Windows: @scheme[p1] is @scheme["C:\\Joe's Files\\src\\scheme"]}) -(define p2 (build-path 'up 'up "docs" "Scheme")) - (code:comment @#,t{Unix: @scheme[p2] is @scheme["../../docs/Scheme"]}) - (code:comment @#,t{Windows: @scheme[p2] is @scheme["..\\..\\docs\\Scheme"]}) +@racketblock[ +(define p1 (build-path (current-directory) "src" "racket")) + (code:comment @#,t{Unix: @racket[p1] is @racket["/home/joeuser/src/racket"]}) + (code:comment @#,t{Windows: @racket[p1] is @racket["C:\\Joe's Files\\src\\racket"]}) +(define p2 (build-path 'up 'up "docs" "Racket")) + (code:comment @#,t{Unix: @racket[p2] is @racket["../../docs/Racket"]}) + (code:comment @#,t{Windows: @racket[p2] is @racket["..\\..\\docs\\Racket"]}) (build-path p2 p1) - (code:comment @#,t{Unix and Windows: raises @scheme[exn:fail:contract]; @scheme[p1] is absolute}) + (code:comment @#,t{Unix and Windows: raises @racket[exn:fail:contract]; @racket[p1] is absolute}) (build-path p1 p2) - (code:comment @#,t{Unix: is @scheme["/home/joeuser/src/racket/../../docs/Scheme"]}) - (code:comment @#,t{Windows: is @scheme["C:\\Joe's Files\\src\\scheme\\..\\..\\docs\\Scheme"]}) + (code:comment @#,t{Unix: is @racket["/home/joeuser/src/racket/../../docs/Racket"]}) + (code:comment @#,t{Windows: is @racket["C:\\Joe's Files\\src\\racket\\..\\..\\docs\\Racket"]}) ]} @@ -266,36 +266,36 @@ Windows examples. [sub (or/c path-string? 'up 'same)] ...) path?]{ -Like @scheme[build-path], except a path convention type is specified +Like @racket[build-path], except a path convention type is specified explicitly.} @defproc[(absolute-path? [path path-string?]) boolean?]{ -Returns @scheme[#t] if @scheme[path] is an absolute path, @scheme[#f] -otherwise. The @scheme[path] argument can be a path for any -platform. If @scheme[path] is not a legal path string (e.g., it -contains a nul character), @scheme[#f] is returned. This procedure +Returns @racket[#t] if @racket[path] is an absolute path, @racket[#f] +otherwise. The @racket[path] argument can be a path for any +platform. If @racket[path] is not a legal path string (e.g., it +contains a nul character), @racket[#f] is returned. This procedure does not access the filesystem.} @defproc[(relative-path? [path path-string?]) boolean?]{ -Returns @scheme[#t] if @scheme[path] is a relative path, @scheme[#f] -otherwise. The @scheme[path] argument can be a path for any -platform. If @scheme[path] is not a legal path string (e.g., it -contains a nul character), @scheme[#f] is returned. This procedure +Returns @racket[#t] if @racket[path] is a relative path, @racket[#f] +otherwise. The @racket[path] argument can be a path for any +platform. If @racket[path] is not a legal path string (e.g., it +contains a nul character), @racket[#f] is returned. This procedure does not access the filesystem.} @defproc[(complete-path? [path path-string?]) boolean?]{ -Returns @scheme[#t] if @scheme[path] is a completely determined path -(@italic{not} relative to a directory or drive), @scheme[#f] -otherwise. The @scheme[path] argument can be a path for any +Returns @racket[#t] if @racket[path] is a completely determined path +(@italic{not} relative to a directory or drive), @racket[#f] +otherwise. The @racket[path] argument can be a path for any platform. Note that for Windows paths, an absolute path can omit the drive specification, in which case the path is neither relative nor -complete. If @scheme[path] is not a legal path string (e.g., it -contains a nul character), @scheme[#f] is returned. +complete. If @racket[path] is not a legal path string (e.g., it +contains a nul character), @racket[#f] is returned. This procedure does not access the filesystem.} @@ -304,13 +304,13 @@ This procedure does not access the filesystem.} [base path-string? (current-directory)]) path?]{ -Returns @scheme[path] as a complete path. If @scheme[path] is already +Returns @racket[path] as a complete path. If @racket[path] is already a complete path, it is returned as the result. Otherwise, -@scheme[path] is resolved with respect to the complete path -@scheme[base]. If @scheme[base] is not a complete path, the +@racket[path] is resolved with respect to the complete path +@racket[base]. If @racket[base] is not a complete path, the @exnraise[exn:fail:contract]. -The @scheme[path] and @scheme[base] arguments can paths for any +The @racket[path] and @racket[base] arguments can paths for any platform; if they are for different platforms, the @exnraise[exn:fail:contract]. @@ -319,13 +319,13 @@ This procedure does not access the filesystem.} @defproc[(path->directory-path [path path-string?]) path?]{ -Returns @scheme[path] if @scheme[path] syntactically refers to a +Returns @racket[path] if @racket[path] syntactically refers to a directory and ends in a separator, otherwise it returns an extended -version of @scheme[path] that specifies a directory and ends with a +version of @racket[path] that specifies a directory and ends with a separator. For example, under @|AllUnix|, the path @filepath{x/y/} syntactically refers to a directory and ends in a separator, but @filepath{x/y} would be extended to @filepath{x/y/}, and @filepath{x/..} would be -extended to @filepath{x/../}. The @scheme[path] argument can be a path for +extended to @filepath{x/../}. The @racket[path] argument can be a path for any platform, and the result will be for the same platform. This procedure does not access the filesystem.} @@ -333,24 +333,24 @@ This procedure does not access the filesystem.} @defproc[(resolve-path [path path-string?]) path?]{ -@tech{Cleanse}s @scheme[path] and returns a path that references the -same file or directory as @scheme[path]. Under @|AllUnix|, if -@scheme[path] is a soft link to another path, then the referenced path +@tech{Cleanse}s @racket[path] and returns a path that references the +same file or directory as @racket[path]. Under @|AllUnix|, if +@racket[path] is a soft link to another path, then the referenced path is returned (this may be a relative path with respect to the directory -owning @scheme[path]), otherwise @scheme[path] is returned (after +owning @racket[path]), otherwise @racket[path] is returned (after expansion).} @defproc[(cleanse-path [path path-string?]) path]{ -@techlink{Cleanse}s @scheme[path] (as described at the beginning of +@techlink{Cleanse}s @racket[path] (as described at the beginning of this section). The filesystem might be accessed, but the source or expanded path might be a non-existent path.} @defproc[(expand-user-path [path path-string?]) path]{ -@techlink{Cleanse}s @scheme[path]. In addition, under @|AllUnix|, a +@techlink{Cleanse}s @racket[path]. In addition, under @|AllUnix|, a leading @litchar{~} is treated as user's home directory and expanded; the username follows the @litchar{~} (before a @litchar{/} or the end of the path), where @litchar{~} by itself indicates the home directory @@ -361,38 +361,38 @@ of the current user.} Eliminates redundant path separators (except for a single trailing separator), up-directory @litchar{..}, and same-directory @litchar{.} -indicators in @scheme[path], and changes @litchar{/} separators to +indicators in @racket[path], and changes @litchar{/} separators to @litchar{\} separators in Windows paths, such that the result -accesses the same file or directory (if it exists) as @scheme[path]. +accesses the same file or directory (if it exists) as @racket[path]. In general, the pathname is normalized as much as possible --- without -consulting the filesystem if @scheme[use-filesystem?] is @scheme[#f], +consulting the filesystem if @racket[use-filesystem?] is @racket[#f], and (under Windows) without changing the case of letters within the -path. If @scheme[path] syntactically refers to a directory, the +path. If @racket[path] syntactically refers to a directory, the result ends with a directory separator. -When @scheme[path] is simplified and @scheme[use-filesystem?] is true -(the default), a complete path is returned; if @scheme[path] is +When @racket[path] is simplified and @racket[use-filesystem?] is true +(the default), a complete path is returned; if @racket[path] is relative, it is resolved with respect to the current directory, and up-directory indicators are removed taking into account soft links (so that the resulting path refers to the same directory as before). -When @scheme[use-filesystem?] is @scheme[#f], up-directory indicators +When @racket[use-filesystem?] is @racket[#f], up-directory indicators are removed by deleting a preceding path element, and the result can be a relative path with up-directory indicators remaining at the beginning of the path; up-directory indicators are dropped when they refer to the parent of a root directory. Similarly, the result can be -the same as @scheme[(build-path 'same)] (but with a trailing +the same as @racket[(build-path 'same)] (but with a trailing separator) if eliminating up-directory indicators leaves only same-directory indicators. -The @scheme[path] argument can be a path for any platform when -@scheme[use-filesystem?] is @scheme[#f], and the resulting path is for +The @racket[path] argument can be a path for any platform when +@racket[use-filesystem?] is @racket[#f], and the resulting path is for the same platform. -The filesystem might be accessed when @scheme[use-filesystem?] is +The filesystem might be accessed when @racket[use-filesystem?] is true, but the source or simplified path might be a non-existent path. If -@scheme[path] cannot be simplified due to a cycle of links, the +@racket[path] cannot be simplified due to a cycle of links, the @exnraise[exn:fail:filesystem] (but a successfully simplified path may still involve a cycle of links if the cycle did not inhibit the simplification). @@ -404,16 +404,16 @@ information on simplifying Windows paths.} @defproc[(normal-case-path [path path-string?]) path?]{ -Returns @scheme[path] with ``normalized'' case letters. For @|AllUnix| +Returns @racket[path] with ``normalized'' case letters. For @|AllUnix| paths, this procedure always returns the input path, because filesystems for these platforms can be case-sensitive. For Windows -paths, if @scheme[path] does not start @litchar{\\?\}, the +paths, if @racket[path] does not start @litchar{\\?\}, the resulting string uses only lowercase letters, based on the current locale. In addition, for Windows paths when the path does not start @litchar{\\?\}, all @litchar{/}s are converted to @litchar{\}s, and trailing spaces and @litchar{.}s are removed. -The @scheme[path] argument can be a path for any platform, but beware +The @racket[path] argument can be a path for any platform, but beware that local-sensitive decoding and conversion of the path may be different on the current platform than for the path's platform. @@ -425,42 +425,42 @@ This procedure does not access the filesystem.} (or/c path? 'up 'same) boolean?)]{ -Deconstructs @scheme[path] into a smaller path and an immediate +Deconstructs @racket[path] into a smaller path and an immediate directory or file name. Three values are returned: @itemize[ - @item{@scheme[base] is either + @item{@racket[base] is either @itemize[ @item{a path,} - @item{@indexed-scheme['relative] if @scheme[path] is an immediate + @item{@indexed-racket['relative] if @racket[path] is an immediate relative directory or filename, or} - @item{@scheme[#f] if @scheme[path] is a root directory.} + @item{@racket[#f] if @racket[path] is a root directory.} ]} - @item{@scheme[name] is either + @item{@racket[name] is either @itemize[ @item{a directory-name path,} @item{a filename,} - @item{@scheme['up] if the last part of @scheme[path] specifies the parent + @item{@racket['up] if the last part of @racket[path] specifies the parent directory of the preceding path (e.g., @litchar{..} under Unix), or} - @item{@scheme['same] if the last part of @scheme[path] specifies the + @item{@racket['same] if the last part of @racket[path] specifies the same directory as the preceding path (e.g., @litchar{.} under Unix).} ]} - @item{@scheme[must-be-dir?] is @scheme[#t] if @scheme[path] explicitly - specifies a directory (e.g., with a trailing separator), @scheme[#f] - otherwise. Note that @scheme[must-be-dir?] does not specify whether - @scheme[name] is actually a directory or not, but whether @scheme[path] + @item{@racket[must-be-dir?] is @racket[#t] if @racket[path] explicitly + specifies a directory (e.g., with a trailing separator), @racket[#f] + otherwise. Note that @racket[must-be-dir?] does not specify whether + @racket[name] is actually a directory or not, but whether @racket[path] syntactically specifies a directory.} ] -Compared to @scheme[path], redundant separators (if any) are removed -in the result @scheme[base] and @scheme[name]. If @scheme[base] is -@scheme[#f], then @scheme[name] cannot be @scheme['up] or -@scheme['same]. The @scheme[path] argument can be a path for any +Compared to @racket[path], redundant separators (if any) are removed +in the result @racket[base] and @racket[name]. If @racket[base] is +@racket[#f], then @racket[name] cannot be @racket['up] or +@racket['same]. The @racket[path] argument can be a path for any platform, and resulting paths for the same platform. This procedure does not access the filesystem. @@ -474,23 +474,23 @@ information on splitting Windows paths.} [suffix (or/c string? bytes?)]) path?]{ -Returns a path that is the same as @scheme[path], except that the +Returns a path that is the same as @racket[path], except that the suffix for the last element of the path is changed to -@scheme[suffix]. If the last element of @scheme[path] has no suffix, -then @scheme[suffix] is added to the path. A suffix is defined as a +@racket[suffix]. If the last element of @racket[path] has no suffix, +then @racket[suffix] is added to the path. A suffix is defined as a @litchar{.} followed by any number of non-@litchar{.} characters/bytes at the end of the path element, as long as the path element is not -@scheme[".."] or @scheme["."]. The @scheme[path] argument can be a +@racket[".."] or @racket["."]. The @racket[path] argument can be a path for any platform, and the result is for the same platform. If -@scheme[path] represents a root, the @exnraise[exn:fail:contract].} +@racket[path] represents a root, the @exnraise[exn:fail:contract].} @defproc[(path-add-suffix [path path-string?] [suffix (or/c string? bytes?)]) path?]{ -Similar to @scheme[path-replace-suffix], but any existing suffix on -@scheme[path] is preserved by replacing every @litchar{.} in the last -path element with @litchar{_}, and then the @scheme[suffix] is added +Similar to @racket[path-replace-suffix], but any existing suffix on +@racket[path] is preserved by replacing every @litchar{.} in the last +path element with @litchar{_}, and then the @racket[suffix] is added to the end.} @;------------------------------------------------------------------------ @@ -501,73 +501,73 @@ to the end.} @defproc[(explode-path [path (or/c path-string? path-for-some-system?)]) (listof (or/c path-for-some-system? 'up 'same))]{ -Returns the list of path element that constitute @scheme[path]. If -@scheme[path] is simplified in the sense of @scheme[simple-form-path], +Returns the list of path element that constitute @racket[path]. If +@racket[path] is simplified in the sense of @racket[simple-form-path], then the result is always a list of paths, and the first element of the list is a root.} @defproc[(file-name-from-path [path (or/c path-string? path-for-some-system?)]) (or/c path-for-some-system? #f)]{ -Returns the last element of @scheme[path]. If @scheme[path] -syntactically a directory path (see @scheme[split-path]), then then -result is @scheme[#f].} +Returns the last element of @racket[path]. If @racket[path] +syntactically a directory path (see @racket[split-path]), then then +result is @racket[#f].} @defproc[(filename-extension [path (or/c path-string? path-for-some-system?)]) (or/c bytes? #f)]{ Returns a byte string that is the extension part of the filename in -@scheme[path] without the @litchar{.} separator. If @scheme[path] is -syntactically a directory (see @scheme[split-path]) or if the path has -no extension, @scheme[#f] is returned.} +@racket[path] without the @litchar{.} separator. If @racket[path] is +syntactically a directory (see @racket[split-path]) or if the path has +no extension, @racket[#f] is returned.} @defproc[(find-relative-path [base (or/c path-string? path-for-some-system?)] [path (or/c path-string? path-for-some-system?)]) path-for-some-system?]{ -Finds a relative pathname with respect to @scheme[base] that names -the same file or directory as @scheme[path]. Both @scheme[base] -and @scheme[path] must be simplified in the sense of -@scheme[simple-form-path]. If @scheme[path] is not a proper subpath -of @scheme[base] (i.e., a subpath that is strictly longer), -@scheme[path] is returned.} +Finds a relative pathname with respect to @racket[base] that names +the same file or directory as @racket[path]. Both @racket[base] +and @racket[path] must be simplified in the sense of +@racket[simple-form-path]. If @racket[path] is not a proper subpath +of @racket[base] (i.e., a subpath that is strictly longer), +@racket[path] is returned.} @defproc[(normalize-path [path path-string?] [wrt (and/c path-string? complete-path?) (current-directory)]) path?]{ -Returns a normalized, complete version of @scheme[path], expanding the -path and resolving all soft links. If @scheme[path] is relative, then -@scheme[wrt] is used as the base path. +Returns a normalized, complete version of @racket[path], expanding the +path and resolving all soft links. If @racket[path] is relative, then +@racket[wrt] is used as the base path. -Letter case is @italic{not} normalized by @scheme[normalize-path]. For +Letter case is @italic{not} normalized by @racket[normalize-path]. For this and other reasons, such as whether the path is syntactically a -directory, the result of @scheme[normalize-path] is not suitable for +directory, the result of @racket[normalize-path] is not suitable for comparisons that determine whether two paths refer to the same file or directory (i.e., the comparison may produce false negatives). -An error is signaled by @scheme[normalize-path] if the input +An error is signaled by @racket[normalize-path] if the input path contains an embedded path for a non-existent directory, or if an infinite cycle of soft links is detected.} @defproc[(path-only [path (or/c path-string? path-for-some-system?)]) path-for-some-system?]{ -If @scheme[path] is a filename, the file's path is returned. If -@scheme[path] is syntactically a directory, @scheme[path] is returned +If @racket[path] is a filename, the file's path is returned. If +@racket[path] is syntactically a directory, @racket[path] is returned (as a path, if it was a string).} @defproc[(simple-form-path [path path-string?]) path?]{ -Returns @scheme[(simplify-path (path->complete-path path))], which +Returns @racket[(simplify-path (path->complete-path path))], which ensures that the result is a complete path containing no up- or same-directory indicators.} @defproc[(some-system-path->string [path path-for-some-system?]) string?]{ -Converts @scheme[path] to a string using a UTF-8 encoding of the +Converts @racket[path] to a string using a UTF-8 encoding of the path's bytes. Use this function when working with paths for a different system @@ -578,7 +578,7 @@ locale's encoding) and when starting and ending with strings.} [kind (or/c 'unix 'windows)]) path-for-some-system?]{ -Converts @scheme[str] to a @scheme[kind] path using a UTF-8 encoding +Converts @racket[str] to a @racket[kind] path using a UTF-8 encoding of the path's bytes. Use this function when working with paths for a different system diff --git a/collects/scribblings/reference/pipes.scrbl b/collects/scribblings/reference/pipes.scrbl index 4d374d58dd..40c32bd457 100644 --- a/collects/scribblings/reference/pipes.scrbl +++ b/collects/scribblings/reference/pipes.scrbl @@ -3,7 +3,7 @@ @title[#:tag "pipeports"]{Pipes} -A Scheme @deftech{pipe} is internal to Scheme, and not related to +A Racket @deftech{pipe} is internal to Racket, and not related to OS-level pipes (which are @tech{file-stream ports}) for communicating between different processes. @@ -18,21 +18,21 @@ the input port, with no intermediate buffering. Unlike some other kinds of ports, pipe ports do not need to be explicitly closed to be reclaimed by @seclink["gc-model"]{garbage collection}. -If @scheme[limit] is @scheme[#f], the new pipe holds an unlimited +If @racket[limit] is @racket[#f], the new pipe holds an unlimited number of unread bytes (i.e., limited only by the available -memory). If @scheme[limit] is a positive number, then the pipe will -hold at most @scheme[limit] unread/unpeeked bytes; writing to the +memory). If @racket[limit] is a positive number, then the pipe will +hold at most @racket[limit] unread/unpeeked bytes; writing to the pipe's output port thereafter will block until a read or peek from the input port makes more space available. (Peeks effectively extend the port's capacity until the peeked bytes are read.) -The optional @scheme[input-name] and @scheme[output-name] are used +The optional @racket[input-name] and @racket[output-name] are used as the names for the returned input and out ports, respectively.} @defproc[(pipe-content-length [pipe-port port?]) exact-nonnegative-integer?]{ Returns the number of bytes contained in a pipe, where -@scheme[pipe-port] is either of the pipe's ports produced by -@scheme[make-pipe]. The pipe's content length counts all bytes that +@racket[pipe-port] is either of the pipe's ports produced by +@racket[make-pipe]. The pipe's content length counts all bytes that have been written to the pipe and not yet read (though possibly peeked).} diff --git a/collects/scribblings/reference/port-line-counting.scrbl b/collects/scribblings/reference/port-line-counting.scrbl index 2db285e6e5..6111a67987 100644 --- a/collects/scribblings/reference/port-line-counting.scrbl +++ b/collects/scribblings/reference/port-line-counting.scrbl @@ -7,20 +7,20 @@ @section-index["column numbers"] @section-index["port positions"] -By default, Scheme keeps track of the @deftech{position} in a port as +By default, Racket keeps track of the @deftech{position} in a port as the number of bytes that have been read from or written to any port (independent of the read/write position, which is accessed or changed -with @scheme[file-position]). Optionally, however, Scheme can track +with @racket[file-position]). Optionally, however, Racket can track the position in terms of characters (after UTF-8 decoding), instead of bytes, and it can track @deftech{line locations} and @deftech{column locations}; this optional tracking must be specifically enabled for a -port via @scheme[port-count-lines!] or the -@scheme[port-count-lines-enabled] parameter. Position, line, and -column locations for a port are used by @scheme[read-syntax] and -@scheme[read-honu-syntax]. Position and line locations are numbered +port via @racket[port-count-lines!] or the +@racket[port-count-lines-enabled] parameter. Position, line, and +column locations for a port are used by @racket[read-syntax] and +@racket[read-honu-syntax]. Position and line locations are numbered from @math{1}; column locations are numbered from @math{0}. -When counting lines, Scheme treats linefeed, return, and +When counting lines, Racket treats linefeed, return, and return-linefeed combinations as a line terminator and as a single position (on all platforms). Each tab advances the column count to one before the next multiple of @math{8}. When a sequence of bytes in the @@ -45,7 +45,7 @@ position only when line and column counting is enabled. Turns on line and column counting for a port. Counting can be turned on at any time, though generally it is turned on before any data is read from or written to a port. When a port is created, if the value -of the @scheme[port-count-lines-enabled] parameter is true, then line +of the @racket[port-count-lines-enabled] parameter is true, then line counting is automatically enabled for the port. Line counting cannot be disabled for a port after it is enabled.} @@ -54,12 +54,12 @@ be disabled for a port after it is enabled.} (or/c exact-nonnegative-integer? #f) (or/c exact-positive-integer? #f))]{ -Returns three values: an integer or @scheme[#f] for the line number of -the next read/written item, an integer or @scheme[#f] for the next -item's column, and an integer or @scheme[#f] for the next item's +Returns three values: an integer or @racket[#f] for the line number of +the next read/written item, an integer or @racket[#f] for the next +item's column, and an integer or @racket[#f] for the next item's position. The next column and position normally increases as bytes are read from or written to the port, but if line/character counting is -enabled for @scheme[port], the column and position results can +enabled for @racket[port], the column and position results can decrease after reading or writing a byte that ends a UTF-8 encoding sequence.} @@ -67,5 +67,5 @@ sequence.} A parameter that determines whether line counting is enabled automatically for newly created ports. The default value is -@scheme[#f].} +@racket[#f].} diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl index 812e8ba018..07ab524296 100644 --- a/collects/scribblings/reference/read.scrbl +++ b/collects/scribblings/reference/read.scrbl @@ -5,11 +5,11 @@ @defproc[(read [in input-port? (current-input-port)]) any]{ -Reads and returns a single @tech{datum} from @scheme[in]. If -@scheme[in] has a handler associated to it via -@scheme[port-read-handler], then the handler is called. Otherwise, the +Reads and returns a single @tech{datum} from @racket[in]. If +@racket[in] has a handler associated to it via +@racket[port-read-handler], then the handler is called. Otherwise, the default reader is used, as parameterized by the -@scheme[current-readtable] parameter, as well as many other +@racket[current-readtable] parameter, as well as many other parameters. See @secref["reader"] for information on the default reader.} @@ -18,13 +18,13 @@ See @secref["reader"] for information on the default reader.} [in input-port? (current-input-port)]) (or/c syntax? eof-object?)]{ -Like @scheme[read], but produces a @tech{syntax object} with -source-location information. The @scheme[source-name] is used as the +Like @racket[read], but produces a @tech{syntax object} with +source-location information. The @racket[source-name] is used as the source field of the syntax object; it can be an arbitrary value, but it should generally be a path for the source file. See @secref["reader"] for information on the default reader in -@scheme[read-syntax] mode.} +@racket[read-syntax] mode.} @defproc[(read/recursive [in input-port? (current-input-port)] [start (or/c char? #f) #f] @@ -32,46 +32,46 @@ See @secref["reader"] for information on the default reader in [graph? any/c #t]) any]{ -Similar to calling @scheme[read], but normally used during the dynamic -extent of @scheme[read] within a reader-extension procedure (see +Similar to calling @racket[read], but normally used during the dynamic +extent of @racket[read] within a reader-extension procedure (see @secref["reader-procs"]). The main effect of using -@scheme[read/recursive] instead of @scheme[read] is that +@racket[read/recursive] instead of @racket[read] is that graph-structure annotations (see @secref["parse-graph"]) in the nested read are considered part of the overall read, at least when the -@scheme[graph?] argument is true; since the result is wrapped in a +@racket[graph?] argument is true; since the result is wrapped in a placeholder, however, it is not directly inspectable. -If @scheme[start] is provided and not @scheme[#f], it is effectively -prefixed to the beginning of @scheme[in]'s stream for the read. (To -prefix multiple characters, use @scheme[input-port-append].) +If @racket[start] is provided and not @racket[#f], it is effectively +prefixed to the beginning of @racket[in]'s stream for the read. (To +prefix multiple characters, use @racket[input-port-append].) -The @scheme[readtable] argument is used for top-level parsing to +The @racket[readtable] argument is used for top-level parsing to satisfy the read request; recursive parsing within the read (e.g., to read the elements of a list) instead uses the current readtable as -determined by the @scheme[current-readtable] parameter. A reader -macro might call @scheme[read/recursive] with a character and +determined by the @racket[current-readtable] parameter. A reader +macro might call @racket[read/recursive] with a character and readtable to effectively invoke the readtable's behavior for the -character. If @scheme[readtable] is @scheme[#f], the default +character. If @racket[readtable] is @racket[#f], the default readtable is used for top-level parsing. -When @scheme[graph?] is @scheme[#f], graph structure annotations in +When @racket[graph?] is @racket[#f], graph structure annotations in the read datum are local to the datum. -When called within the dynamic extent of @scheme[read], the -@scheme[read/recursive] procedure produces either an opaque +When called within the dynamic extent of @racket[read], the +@racket[read/recursive] procedure produces either an opaque placeholder value, a special-comment value, or an end-of-file. The result is a special-comment value (see @secref["special-comments"]) when the input stream's first non-whitespace content parses as a -comment. The result is end-of-file when @scheme[read/recursive] +comment. The result is end-of-file when @racket[read/recursive] encounters an end-of-file. Otherwise, the result is a placeholder that protects graph references that are not yet resolved. When this placeholder is returned within an S-expression that is produced by any reader-extension procedure (see @secref["reader-procs"]) for the -same outermost @scheme[read], it will be replaced with the actual read -value before the outermost @scheme[read] returns. +same outermost @racket[read], it will be replaced with the actual read +value before the outermost @racket[read] returns. See @secref["readtables"] for an extended example that uses -@scheme[read/recursive].} +@racket[read/recursive].} @defproc[(read-syntax/recursive [source-name any/c (object-name in)] [in input-port? (current-input-port)] @@ -80,105 +80,105 @@ See @secref["readtables"] for an extended example that uses [graph? any/c #t]) any]{ -Analogous to calling @scheme[read/recursive], but the resulting value +Analogous to calling @racket[read/recursive], but the resulting value encapsulates S-expression structure with source-location -information. As with @scheme[read/recursive], when -@scheme[read-syntax/recursive] is used within the dynamic extent of -@scheme[read-syntax], the result of from -@scheme[read-syntax/recursive] is either a special-comment value, +information. As with @racket[read/recursive], when +@racket[read-syntax/recursive] is used within the dynamic extent of +@racket[read-syntax], the result of from +@racket[read-syntax/recursive] is either a special-comment value, end-of-file, or opaque graph-structure placeholder (not a syntax object). The placeholder can be embedded in an S-expression or syntax object returned by a reader macro, etc., and it will be replaced with -the actual syntax object before the outermost @scheme[read-syntax] +the actual syntax object before the outermost @racket[read-syntax] returns. -Using @scheme[read/recursive] within the dynamic extent of -@scheme[read-syntax] does not allow graph structure for reading to be -included in the outer @scheme[read-syntax] parsing, and neither does -using @scheme[read-syntax/recursive] within the dynamic extent of -@scheme[read]. In those cases, @scheme[read/recursive] and -@scheme[read-syntax/recursive] produce results like @scheme[read] and -@scheme[read-syntax], except that a special-comment value is returned +Using @racket[read/recursive] within the dynamic extent of +@racket[read-syntax] does not allow graph structure for reading to be +included in the outer @racket[read-syntax] parsing, and neither does +using @racket[read-syntax/recursive] within the dynamic extent of +@racket[read]. In those cases, @racket[read/recursive] and +@racket[read-syntax/recursive] produce results like @racket[read] and +@racket[read-syntax], except that a special-comment value is returned when the input stream starts with a comment (after whitespace). See @secref["readtables"] for an extended example that uses -@scheme[read-syntax/recursive].} +@racket[read-syntax/recursive].} @defproc[(read-language [in input-port? (current-input-port)] [fail-thunk (-> any) (lambda () (error ...))]) (any/c any/c . -> . any)]{ -Reads @scheme[in] in the same way as @scheme[read], but stopping as +Reads @racket[in] in the same way as @racket[read], but stopping as soon as a @tech{reader language} (or its absence) is determined. A @deftech{reader language} is specified by @litchar{#lang} or @litchar{#!} (see @secref["parse-reader"]) at the beginning of the input, though possibly after comment forms. The default -@tech{readtable} is used by @scheme[read-language] (instead of the -value of @scheme[current-readtable]), and @litchar{#reader} forms +@tech{readtable} is used by @racket[read-language] (instead of the +value of @racket[current-readtable]), and @litchar{#reader} forms (which might produce comments) are not allowed before @litchar{#lang} or @litchar{#!}. When it finds a @litchar{#lang} or @litchar{#!} specification, instead -of dispatching to a @schemeidfont{read} or @schemeidfont{read-syntax} -form as @scheme[read] and @scheme[read-syntax] do, -@scheme[read-language] dispatches to a @schemeidfont{get-info} +of dispatching to a @racketidfont{read} or @racketidfont{read-syntax} +form as @racket[read] and @racket[read-syntax] do, +@racket[read-language] dispatches to a @racketidfont{get-info} function (if any) exported by the same module. The result of the -@schemeidfont{get-info} function is the result of -@scheme[read-language] if it is a function of two arguments; if -@schemeidfont{get-info} produces any other kind of result, the +@racketidfont{get-info} function is the result of +@racket[read-language] if it is a function of two arguments; if +@racketidfont{get-info} produces any other kind of result, the @exnraise[exn:fail:contract]. -The function produced by @schemeidfont{get-info} reflects information +The function produced by @racketidfont{get-info} reflects information about the expected syntax of the input stream. The first argument to the function serves as a key on such information; acceptable keys and the -interpretation of results is up to external tools, such as DrScheme. +interpretation of results is up to external tools, such as DrRacket. If no information is available for a given key, the result should be the second argument. -The @schemeidfont{get-info} function itself is applied to five +The @racketidfont{get-info} function itself is applied to five arguments: the input port being read, the module path from which the -@schemeidfont{get-info} function was extracted, and the source line -(positive exact integer or @scheme[#f]), column (non-negative exact -integer or @scheme[#f]), and position (positive exact integer or -@scheme[#f]) of the start of the @litchar{#lang} or @litchar{#!} -form. The @schemeidfont{get-info} function may further read from the +@racketidfont{get-info} function was extracted, and the source line +(positive exact integer or @racket[#f]), column (non-negative exact +integer or @racket[#f]), and position (positive exact integer or +@racket[#f]) of the start of the @litchar{#lang} or @litchar{#!} +form. The @racketidfont{get-info} function may further read from the given input port to determine its result, but it should read no -further than necessary. The @schemeidfont{get-info} function should +further than necessary. The @racketidfont{get-info} function should not read from the port after returning a function. -If @scheme[in] starts with a @tech{reader language} specification but -the relevant module does not export @schemeidfont{get-info} (but -perhaps does export @schemeidfont{read} and -@schemeidfont{read-syntax}), then the result of @scheme[read-language] -is @scheme[#f]. +If @racket[in] starts with a @tech{reader language} specification but +the relevant module does not export @racketidfont{get-info} (but +perhaps does export @racketidfont{read} and +@racketidfont{read-syntax}), then the result of @racket[read-language] +is @racket[#f]. -If @scheme[in] has a @litchar{#lang} or @litchar{#!} specification, +If @racket[in] has a @litchar{#lang} or @litchar{#!} specification, but parsing and resolving the specification raises an exception, the -exception is propagated by @scheme[read-language]. +exception is propagated by @racket[read-language]. -If @scheme[in] does not specify a @tech{reader language} with -@litchar{#lang} or @litchar{#!}, then @scheme[fail-thunk] is -called. The default @scheme[fail-thunk] raises -@scheme[exn:fail:contract].} +If @racket[in] does not specify a @tech{reader language} with +@litchar{#lang} or @litchar{#!}, then @racket[fail-thunk] is +called. The default @racket[fail-thunk] raises +@racket[exn:fail:contract].} @defboolparam[read-case-sensitive on?]{ A parameter that controls parsing and printing of symbols. When this -parameter's value is @scheme[#f], the reader case-folds symbols (e.g., -producing @scheme['hi] when the input is any one of @litchar{hi}, +parameter's value is @racket[#f], the reader case-folds symbols (e.g., +producing @racket['hi] when the input is any one of @litchar{hi}, @litchar{Hi}, @litchar{HI}, or @litchar{hI}). The parameter also -affects the way that @scheme[write] prints symbols containing -uppercase characters; if the parameter's value is @scheme[#f], then +affects the way that @racket[write] prints symbols containing +uppercase characters; if the parameter's value is @racket[#f], then symbols are printed with uppercase characters quoted by a @litchar{\} or @litchar{|}. The parameter's value is overridden by quoting @litchar{\} or @litchar{|} vertical-bar quotes and the @litchar{#cs} and @litchar{#ci} prefixes; see @secref["parse-symbol"] for more information. While a module is -loaded, the parameter is set to @scheme[#t] (see -@scheme[current-load]).} +loaded, the parameter is set to @racket[#t] (see +@racket[current-load]).} @defboolparam[read-square-bracket-as-paren on?]{ @@ -200,7 +200,7 @@ A parameter that controls parsing @litchar{#&} input. See @defboolparam[read-accept-compiled on?]{ A parameter that controls parsing @litchar{#~} compiled input. See -@secref["reader"] and @scheme[current-compile] for more +@secref["reader"] and @racket[current-compile] for more information.} @defboolparam[read-accept-bar-quote on?]{ @@ -234,8 +234,8 @@ A parameter that controls parsing input with two dots to trigger infix @defboolparam[read-accept-quasiquote on?]{ A parameter that controls parsing input with @litchar{`} or -@litchar{,} which is normally used for @scheme[quasiquote], -@scheme[unquote], and @scheme[unquote-splicing] abbreviations. See +@litchar{,} which is normally used for @racket[quasiquote], +@racket[unquote], and @racket[unquote-splicing] abbreviations. See @secref["parse-quote"] for more information.} @defboolparam[read-accept-reader on?]{ @@ -254,7 +254,7 @@ a module-path datum following @litchar{#reader}. See @defparam[current-readtable readtable (or/c readtable? #f)]{ A parameter whose value determines a readtable that -adjusts the parsing of S-expression input, where @scheme[#f] implies the +adjusts the parsing of S-expression input, where @racket[#f] implies the default behavior. See @secref["readtables"] for more information.} @@ -263,8 +263,8 @@ default behavior. See @secref["readtables"] for more information.} A parameter that enables lazy parsing of compiled code, so that closure bodies and syntax objects are extracted (and validated) from marshaled compiled code on demand. Normally, this parameter is set by -the default @tech{load handler} when @scheme[load-on-demand-enabled] -is @scheme[#t]. +the default @tech{load handler} when @racket[load-on-demand-enabled] +is @racket[#t]. Even when parsing is delayed, compiled code is loaded into memory. If the @as-index{@envvar{PLT_DELAY_FROM_ZO}} environment variable is set @@ -283,11 +283,11 @@ encounter garbage, leading to an exception.} (input-port? any/c . -> . any))]) void?])]{ -Gets or sets the @deftech{port read handler} for @scheme[in]. The -handler called to read from the port when the built-in @scheme[read] -or @scheme[read-syntax] procedure is applied to the port. (The -port read handler is not used for @scheme[read/recursive] or -@scheme[read-syntax/recursive].) +Gets or sets the @deftech{port read handler} for @racket[in]. The +handler called to read from the port when the built-in @racket[read] +or @racket[read-syntax] procedure is applied to the port. (The +port read handler is not used for @racket[read/recursive] or +@racket[read-syntax/recursive].) A port read handler is applied to either one argument or two arguments: @@ -295,20 +295,20 @@ arguments: @itemize[ @item{A single argument is supplied when the port is used - with @scheme[read]; the argument is the port being read. The return + with @racket[read]; the argument is the port being read. The return value is the value that was read from the port (or end-of-file).} @item{Two arguments are supplied when the port is used with - @scheme[read-syntax]; the first argument is the port being read, and + @racket[read-syntax]; the first argument is the port being read, and the second argument is a value indicating the source. The return value is a syntax object that was read from the port (or end-of-file).} ] -The default port read handler reads standard Scheme expressions with -Scheme's built-in parser (see @secref["reader"]). It handles a +The default port read handler reads standard Racket expressions with +Racket's built-in parser (see @secref["reader"]). It handles a special result from a custom input port (see -@scheme[make-custom-input-port]) by treating it as a single expression, +@racket[make-custom-input-port]) by treating it as a single expression, except that special-comment values (see @secref["special-comments"]) are treated as whitespace. @@ -318,13 +318,13 @@ readtable; see @secref["readtables"] for more information.} @defproc[(read-honu [in input-port? (current-input-port)]) any]{ -Like @scheme[read], but for Honu mode (see @secref["parse-honu"]).} +Like @racket[read], but for Honu mode (see @secref["parse-honu"]).} @defproc[(read-honu-syntax [source-name any/c (object-name in)] [in input-port? (current-input-port)]) (or/c syntax? eof-object?)]{ -Like @scheme[read-syntax], but for Honu mode (see +Like @racket[read-syntax], but for Honu mode (see @secref["parse-honu"]).} @defproc[(read-honu/recursive [in input-port? (current-input-port)] @@ -333,7 +333,7 @@ Like @scheme[read-syntax], but for Honu mode (see [graph? any/c #t]) any]{ -Like @scheme[read/recursive], but for Honu mode (see +Like @racket[read/recursive], but for Honu mode (see @secref["parse-honu"]).} @defproc[(read-honu-syntax/recursive [source-name any/c (object-name in)] @@ -343,5 +343,5 @@ Like @scheme[read/recursive], but for Honu mode (see [graph? any/c #f]) any]{ -Like @scheme[read-syntax/recursive], but for Honu mode (see +Like @racket[read-syntax/recursive], but for Honu mode (see @secref["parse-honu"]).} diff --git a/collects/scribblings/reference/reader.scrbl b/collects/scribblings/reference/reader.scrbl index 82b90e3540..406a38dae0 100644 --- a/collects/scribblings/reference/reader.scrbl +++ b/collects/scribblings/reference/reader.scrbl @@ -9,14 +9,14 @@ (nonterm s (subscript "n"))) (define (sub n) (subscript n)) (define (nonalpha) - @elem{; the next character must not be @schemelink[char-alphabetic?]{alphabetic}.}) + @elem{; the next character must not be @racketlink[char-alphabetic?]{alphabetic}.}) (define (graph-tag) @kleenerange[1 8]{@nonterm{digit@sub{10}}}) (define (graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}}) (define (graph-ref) @elem{@litchar{#}@graph-tag[]@litchar{#}})) @title[#:tag "reader" #:style 'quiet]{The Reader} -Scheme's reader is a recursive-descent parser that can be configured +Racket's reader is a recursive-descent parser that can be configured through a @seclink["readtables"]{readtable} and various other @tech{parameters}. This section describes the reader's parsing when using the default readtable. @@ -25,15 +25,15 @@ Reading from a stream produces one @deftech{datum}. If the result datum is a compound value, then reading the datum typically requires the reader to call itself recursively to read the component data. -The reader can be invoked in either of two modes: @scheme[read] mode, -or @scheme[read-syntax] mode. In @scheme[read-syntax] mode, the result +The reader can be invoked in either of two modes: @racket[read] mode, +or @racket[read-syntax] mode. In @racket[read-syntax] mode, the result is always a @techlink{syntax object} that includes source-location and (initially empty) lexical information wrapped -around the sort of datum that @scheme[read] mode would produce. In the +around the sort of datum that @racket[read] mode would produce. In the case of pairs, vectors, and boxes, the content is also wrapped recursively as a syntax object. Unless specified otherwise, -this section describes the reader's behavior in @scheme[read] mode, -and @scheme[read-syntax] mode does the same modulo wrapping the final +this section describes the reader's behavior in @racket[read] mode, +and @racket[read-syntax] mode does the same modulo wrapping the final result. Reading is defined in terms of Unicode characters; see @@ -43,7 +43,7 @@ to a character stream. @;------------------------------------------------------------------------ @section[#:tag "default-readtable-dispatch"]{Delimiters and Dispatch} -Along with @schemelink[char-whitespace?]{whitespace}, the following +Along with @racketlink[char-whitespace?]{whitespace}, the following characters are @defterm{delimiters}: @t{ @@ -122,7 +122,7 @@ on the next character or characters in the input stream as follows: @dispatch[@litchar{#!}]{may start a reader extension; see @secref["parse-reader"]} @dispatch[@litchar{#`}]{starts a syntax quasiquote; see @secref["parse-quote"]} @dispatch[@litchar{#,}]{starts an syntax [splicing] unquote; see @secref["parse-quote"]} - @dispatch[@litchar{#~}]{starts compiled code; see @scheme[current-compile]} + @dispatch[@litchar{#~}]{starts compiled code; see @racket[current-compile]} @dispatch[@cilitchar{#i}]{starts a number; see @secref["parse-number"]} @dispatch[@cilitchar{#e}]{starts a number; see @secref["parse-number"]} @@ -139,7 +139,7 @@ on the next character or characters in the input stream as follows: @dispatch[@cilitchar{#ci}]{switches case sensitivity; see @secref["parse-symbol"]} @dispatch[@cilitchar{#cs}]{switches case sensitivity; see @secref["parse-symbol"]} - @dispatch[@cilitchar["#sx"]]{starts a Scheme expression; see @secref["parse-honu"]} + @dispatch[@cilitchar["#sx"]]{starts a Racket expression; see @secref["parse-honu"]} @dispatch[@litchar{#hx}]{starts a Honu expression; see @secref["parse-honu"]} @@ -167,12 +167,12 @@ A sequence that does not start with a delimiter or @litchar{#} is parsed as either a symbol or a number (see @secref["parse-number"]), except that @litchar{.} by itself is never parsed as a symbol or character (unless the -@scheme[read-accept-dot] parameter is set to @scheme[#f]). A +@racket[read-accept-dot] parameter is set to @racket[#f]). A @as-index{@litchar{#%}} also starts a symbol. A successful number parse takes precedence over a symbol parse. @index["case-sensitivity"]{@index["case-insensitive"]{When}} the -@scheme[read-case-sensitive] @tech{parameter} is set to @scheme[#f], +@racket[read-case-sensitive] @tech{parameter} is set to @racket[#f], characters in the sequence that are not quoted by @litchar{|} or @litchar{\} are first case-normalized. If the reader encounters @as-index{@litchar{#ci}}, @litchar{#CI}, @litchar{#Ci}, or @@ -213,7 +213,7 @@ which specifies its parsing as an exact or inexact number; see non-terminal names suggest, a number that has no exactness specifier and matches only @nunterm{inexact-number} is normally parsed as an inexact number, otherwise it is parsed as an exact number. If the -@scheme[read-decimal-as-inexact] @tech{parameter} is set to @scheme[#f], then +@racket[read-decimal-as-inexact] @tech{parameter} is set to @racket[#f], then all numbers without an exactness specifier are instead parsed as exact. @@ -327,18 +327,18 @@ containing the element surrounded by @litchar{.}s as the first element, followed by the others in the read order. This convention supports a kind of @as-index{infix} notation at the reader level. -In @scheme[read-syntax] mode, the recursive reads for the pair/list -elements are themselves in @scheme[read-syntax] mode, so that the +In @racket[read-syntax] mode, the recursive reads for the pair/list +elements are themselves in @racket[read-syntax] mode, so that the result is list or pair of syntax objects that it itself wrapped as a syntax object. If the reader constructs nested pairs because the input included a single delimited @litchar{.}, then only the innermost pair and outtermost pair are wrapped as syntax objects. Whether wrapping a pair or list, if the pair or list was formed with @litchar{[} and -@litchar{]}, then a @indexed-scheme['paren-shape] property is attached -to the result with the value @scheme[#\[]; if the list or pair was +@litchar{]}, then a @indexed-racket['paren-shape] property is attached +to the result with the value @racket[#\[]; if the list or pair was formed with @litchar["{"] and @litchar["}"], then a -@scheme['paren-shape] property is attached to the result with the -value @scheme[#\{]. +@racket['paren-shape] property is attached to the result with the +value @racket[#\{]. If a delimited @litchar{.} appears in any other configuration, then the @exnraise[exn:fail:read]. Similarly, if the reader encounters a @@ -356,18 +356,18 @@ being parsed, then the @exnraise[exn:fail:read]. "(1 . 2 . 3)" ] -If the @scheme[read-square-bracket-as-paren] @tech{parameter} is set to -@scheme[#f], then when then reader encounters @litchar{[} and +If the @racket[read-square-bracket-as-paren] @tech{parameter} is set to +@racket[#f], then when then reader encounters @litchar{[} and @litchar{]}, the @exnraise{exn:fail:read}. Similarly, If the -@scheme[read-curly-brace-as-paren] @tech{parameter} is set to @scheme[#f], +@racket[read-curly-brace-as-paren] @tech{parameter} is set to @racket[#f], then when then reader encounters @litchar["{"] and @litchar["}"], the @exnraise{exn:fail:read}. -If the @scheme[read-accept-dot] @tech{parameter} is set to -@scheme[#f], then a delimited @litchar{.} triggers an -@scheme[exn:fail:read] exception. If the -@scheme[read-accept-infix-dot] @tech{parameter} is set to @scheme[#f], -then multiple delimited @litchar{.}s trigger an @scheme[exn:fail:read] +If the @racket[read-accept-dot] @tech{parameter} is set to +@racket[#f], then a delimited @litchar{.} triggers an +@racket[exn:fail:read] exception. If the +@racket[read-accept-infix-dot] @tech{parameter} is set to @racket[#f], +then multiple delimited @litchar{.}s trigger an @racket[exn:fail:read] exception, instead of the infix conversion. @section[#:tag "parse-string"]{Reading Strings} @@ -423,14 +423,14 @@ Within a string sequence, the following escape sequences are 4]{@nonterm{digit@sub{16}}}}: like @litchar{\x}, but with up to four hexadecimal digits (longer sequences take precedence). The resulting hexadecimal number must be a valid argument to - @scheme[integer->char], otherwise the + @racket[integer->char], otherwise the @exnraise[exn:fail:read].} @item{@as-index{@litchar{\U}@kleenerange[1 8]{@nonterm{digit@sub{16}}}}: like @litchar{\x}, but with up to eight hexadecimal digits (longer sequences take precedence). The resulting hexadecimal number must be a valid argument to - @scheme[integer->char], otherwise the + @racket[integer->char], otherwise the @exnraise[exn:fail:read].} @item{@as-index{@litchar{\}@nonterm{newline}}: elided, where @@ -480,21 +480,21 @@ encountered before a terminating line, the @exnraise[exn:fail:read]. When the reader enounters @as-index{@litchar{'}}, it recursively reads one datum, and forms a new list containing the symbol -@scheme['quote] and the following datum. This convention is mainly -useful for reading Scheme code, where @scheme['s] can be used as a -shorthand for @scheme[(code:quote s)]. +@racket['quote] and the following datum. This convention is mainly +useful for reading Racket code, where @racket['s] can be used as a +shorthand for @racket[(code:quote s)]. Several other sequences are recognized and transformed in a similar way. Longer prefixes take precedence over short ones: -@read-quote-table[(list @litchar{'} @scheme[quote]) - (list @as-index{@litchar{`}} @scheme[quasiquote]) - (list @as-index{@litchar{,}} @scheme[unquote]) - (list @as-index{@litchar[",@"]} @scheme[unquote-splicing]) - (list @as-index{@litchar{#'}} @scheme[syntax]) - (list @as-index{@litchar{#`}} @scheme[quasisyntax]) - (list @as-index{@litchar{#,}} @scheme[unsyntax]) - (list @as-index{@litchar["#,@"]} @scheme[unsyntax-splicing])] +@read-quote-table[(list @litchar{'} @racket[quote]) + (list @as-index{@litchar{`}} @racket[quasiquote]) + (list @as-index{@litchar{,}} @racket[unquote]) + (list @as-index{@litchar[",@"]} @racket[unquote-splicing]) + (list @as-index{@litchar{#'}} @racket[syntax]) + (list @as-index{@litchar{#`}} @racket[quasisyntax]) + (list @as-index{@litchar{#,}} @racket[unsyntax]) + (list @as-index{@litchar["#,@"]} @racket[unsyntax-splicing])] @reader-examples[ "'apple" @@ -502,16 +502,16 @@ way. Longer prefixes take precedence over short ones: ] The @litchar{`}, @litchar{,}, and @litchar[",@"] forms are disabled when -the @scheme[read-accept-quasiquote] @tech{parameter} is set to -@scheme[#f], in which case the @exnraise[exn:fail:read], instead. +the @racket[read-accept-quasiquote] @tech{parameter} is set to +@racket[#f], in which case the @exnraise[exn:fail:read], instead. @section[#:tag "parse-comment"]{Reading Comments} A @as-index{@litchar{;}} starts a line comment. When the reader encounters @litchar{;}, it skips past all characters until the next linefeed (ASCII 10), carriage return (ASCII 13), next-line -(Unicode @scheme[#x0085]), line-separator (Unicode @scheme[#x2028]), -or line-separator (Unicode @scheme[#x2028]) character. +(Unicode @racket[#x0085]), line-separator (Unicode @racket[#x2028]), +or line-separator (Unicode @racket[#x2028]) character. A @as-index{@litchar{#|}} starts a nestable block comment. When the reader encounters @litchar{#|}, it skips past all characters @@ -543,8 +543,8 @@ file. When the reader encounters a @litchar{#(}, @litchar{#[}, or @litchar["#{"], it starts parsing a vector; see @secref["vectors"] for information on vectors. The @litchar{#[} and @litchar["#{"] forms can -be disabled through the @scheme[read-square-bracket-as-paren] and -@scheme[read-curly-brace-as-paren] @tech{parameters}. +be disabled through the @racket[read-square-bracket-as-paren] and +@racket[read-curly-brace-as-paren] @tech{parameters}. The elements of the vector are recursively read until a matching @litchar{)}, @litchar{]}, or @litchar["}"] is found, just as for @@ -556,11 +556,11 @@ An optional vector length can be specified between the @litchar{#} and using a sequence of decimal digits, and the number of elements provided for the vector must be no more than the specified size. If fewer elements are provided, the last provided element is used for the -remaining vector slots; if no elements are provided, then @scheme[0] +remaining vector slots; if no elements are provided, then @racket[0] is used for all slots. -In @scheme[read-syntax] mode, each recursive read for the vector -elements is also in @scheme[read-syntax] mode, so that the wrapped +In @racket[read-syntax] mode, each recursive read for the vector +elements is also in @racket[read-syntax] mode, so that the wrapped vector's elements are also wraped as syntax objects, and the vector is immutable. @@ -577,8 +577,8 @@ When the reader encounters a @litchar{#s(}, @litchar{#s[}, or @litchar["#s{"], it starts parsing an instance of a @tech{prefab} @tech{structure type}; see @secref["structures"] for information on @tech{structure types}. The @litchar{#s[} and @litchar["#s{"] forms -can be disabled through the @scheme[read-square-bracket-as-paren] and -@scheme[read-curly-brace-as-paren] @tech{parameters}. +can be disabled through the @racket[read-square-bracket-as-paren] and +@racket[read-curly-brace-as-paren] @tech{parameters}. The elements of the structure are recursively read until a matching @litchar{)}, @litchar{]}, or @litchar["}"] is found, just as for lists @@ -588,13 +588,13 @@ list for an infix conversion. The first element is used as the structure descriptor, and it must have the form (when quoted) of a possible argument to -@scheme[make-prefab-struct]; in the simplest case, it can be a +@racket[make-prefab-struct]; in the simplest case, it can be a symbol. The remaining elements correspond to field values within the structure. -In @scheme[read-syntax] mode, the structure type must not have any +In @racket[read-syntax] mode, the structure type must not have any mutable fields. The structure's elements are read in -@scheme[read-syntax] mode, so that the wrapped structure's elements +@racket[read-syntax] mode, so that the wrapped structure's elements are also wraped as syntax objects. If the first structure element is not a valid @tech{prefab} structure @@ -605,7 +605,7 @@ indicated @tech{prefab} structure type, the @exnraise[exn:fail:read]. @section[#:tag "parse-hashtable"]{Reading Hash Tables} A @as-index{@litchar{#hash}} starts an immutable hash-table constant -with key matching based on @scheme[equal?]. The characters after +with key matching based on @racket[equal?]. The characters after @litchar{hash} must parse as a list of pairs (see @secref["parse-pair"]) with a specific use of delimited @litchar{.}: it must appear between the elements of each pair in the list, and @@ -615,18 +615,18 @@ each pair is the associated value. A @as-index{@litchar{#hasheq}} starts a hash table like @litchar{#hash}, except that it constructs a hash table based on -@scheme[eq?] instead of @scheme[equal?]. +@racket[eq?] instead of @racket[equal?]. A @as-index{@litchar{#hasheqv}} starts a hash table like @litchar{#hash}, except that it constructs a hash table based on -@scheme[eqv?] instead of @scheme[equal?]. +@racket[eqv?] instead of @racket[equal?]. In all cases, the table is constructed by adding each mapping to the hash table from left to right, so later mappings can hide earlier mappings if the keys are equivalent. @reader-examples[ -#:example-note @elem{, where @scheme[make-...] stands for @scheme[make-immutable-hash]} +#:example-note @elem{, where @racket[make-...] stands for @racket[make-immutable-hash]} "#hash()" "#hasheq()" "#hash((\"a\" . 5))" @@ -641,8 +641,8 @@ parsing a box; see @secref["boxes"] for information on boxes. The content of the box is determined by recursively reading the next datum. -In @scheme[read-syntax] mode, the recursive read for the box content -is also in @scheme[read-syntax] mode, so that the wrapped box's +In @racket[read-syntax] mode, the recursive read for the box content +is also in @racket[read-syntax] mode, so that the wrapped box's content is also wraped as a syntax object, and the box is immutable. @reader-examples[ @@ -688,7 +688,7 @@ one of the following forms: as @litchar{#\}@nonterm{c} and the characters following it do not match any of the previous cases, and as long as the character after @nonterm{c} is not - @schemelink[char-alphabetic?]{alphabetic}.} + @racketlink[char-alphabetic?]{alphabetic}.} ] @@ -717,10 +717,10 @@ A @as-index{@litchar{#rx}} or @as-index{@litchar{#px}} starts a regular expression. The characters immediately after @litchar{#rx} or @litchar{#px} must parse as a string or byte string (see @secref["parse-string"]). A @litchar{#rx} prefix starts a regular -expression as would be constructed by @scheme[regexp], @litchar{#px} -as constructed by @scheme[pregexp], @litchar{#rx#} as constructed by -@scheme[byte-regexp], and @litchar{#px#} as constructed by -@scheme[byte-pregexp]. +expression as would be constructed by @racket[regexp], @litchar{#px} +as constructed by @racket[pregexp], @litchar{#rx#} as constructed by +@racket[byte-regexp], and @litchar{#px#} as constructed by +@racket[byte-pregexp]. @reader-examples[ "#rx\".*\"" @@ -744,8 +744,8 @@ reference is replaced by the datum read for the corresponding datum after it. A @graph-defn[] definition can appear at most once, and a @graph-defn[] definition must appear before a @graph-ref[] reference appears, otherwise the @exnraise[exn:fail:read]. If the -@scheme[read-accept-graph] parameter is set to @scheme[#f], then -@graph-defn[] or @graph-ref[] triggers a @scheme[exn:fail:read] +@racket[read-accept-graph] parameter is set to @racket[#f], then +@graph-defn[] or @graph-ref[] triggers a @racket[exn:fail:read] exception. Although a comment parsed via @litchar{#;} discards the datum @@ -770,51 +770,51 @@ stream. The reader recursively reads the next datum after @litchar{#reader}, and passes it to the procedure that is the value of the -@scheme[current-reader-guard] @tech{parameter}; the result is used as a -module path. The module path is passed to @scheme[dynamic-require] -with either @scheme['read] or @scheme['read-syntax] (depending on -whether the reader is in @scheme[read] or @scheme[read-syntax] +@racket[current-reader-guard] @tech{parameter}; the result is used as a +module path. The module path is passed to @racket[dynamic-require] +with either @racket['read] or @racket['read-syntax] (depending on +whether the reader is in @racket[read] or @racket[read-syntax] mode). The arity of the resulting procedure determines whether it accepts -extra source-location information: a @schemeidfont{read} procedure +extra source-location information: a @racketidfont{read} procedure accepts either one argument (an input port) or five, and a -@schemeidfont{read-syntax} procedure accepts either two arguments (a +@racketidfont{read-syntax} procedure accepts either two arguments (a name value and an input port) or six. In either case, the four optional arguments are the reader's module path (as a syntax object in -@scheme[read-syntax] mode) followed by the line (positive exact -integer or @scheme[#f]), column (non-negative exact integer or -@scheme[#f]), and position (positive exact integer or @scheme[#f]) of +@racket[read-syntax] mode) followed by the line (positive exact +integer or @racket[#f]), column (non-negative exact integer or +@racket[#f]), and position (positive exact integer or @racket[#f]) of the start of the @litchar{#reader} form. The input port is the one whose stream contained @litchar{#reader}, where the stream position is immediately after the recursively-read module path. The procedure should produce a datum result. If the result is a -syntax object in @scheme[read] mode, then it is converted to a datum -using @scheme[syntax->datum]; if the result is not a syntax object in -@scheme[read-syntax] mode, then it is converted to one using -@scheme[datum->syntax]. See also @secref["reader-procs"] for +syntax object in @racket[read] mode, then it is converted to a datum +using @racket[syntax->datum]; if the result is not a syntax object in +@racket[read-syntax] mode, then it is converted to one using +@racket[datum->syntax]. See also @secref["reader-procs"] for information on the procedure's results. -If the @scheme[read-accept-reader] @tech{parameter} is set to -@scheme[#f], then if the reader encounters @litchar{#reader}, the +If the @racket[read-accept-reader] @tech{parameter} is set to +@racket[#f], then if the reader encounters @litchar{#reader}, the @exnraise[exn:fail:read]. -@guideintro["hash-lang"]{@schememodfont["#lang"]} +@guideintro["hash-lang"]{@racketmodfont["#lang"]} The @as-index{@litchar{#lang}} reader form is similar to @litchar{#reader}, but more constrained: the @litchar{#lang} must be followed by a single space (ASCII 32), and then a non-empty sequence of alphanumeric ASCII, @litchar{+}, @litchar{-}, @litchar{_}, and/or @litchar{/} characters terminated by -@schemelink[char-whitespace?]{whitespace} or an end-of-file. The +@racketlink[char-whitespace?]{whitespace} or an end-of-file. The sequence must not start or end with @litchar{/}. A sequence @litchar{#lang }@nonterm{name} is equivalent to @litchar{#reader }@nonterm{name}@litchar{/lang/reader}. Note that the terminating whitespace (if any) is not consumed before the external reading procedure is called. -@margin-note{The @schememodname[syntax/module-reader] library provides a +@margin-note{The @racketmodname[syntax/module-reader] library provides a domain-specific language for writing language readers.} Finally, @as-index{@litchar{#!}} is a synonym for @litchar{#lang} @@ -831,22 +831,22 @@ file, possibly after comment forms, to specify the syntax of a module. @defmodulelang[s-exp] -The @scheme[s-exp] ``language'' is a kind of meta-language. It -@scheme[read]s the S-expression that follows @litchar{#lang s-exp} and -uses it as the language of a @scheme[module] form. It also reads all +The @racket[s-exp] ``language'' is a kind of meta-language. It +@racket[read]s the S-expression that follows @litchar{#lang s-exp} and +uses it as the language of a @racket[module] form. It also reads all remaining S-expressions until an end-of-file, using them for the body -of the generated @scheme[module]. +of the generated @racket[module]. That is, -@schememod[ +@racketmod[ s-exp _module-path _form ... ] is equivalent to -@schemeblock[ +@racketblock[ (module _name _module-path _form ...) ] @@ -855,11 +855,11 @@ is equivalent to @defmodulelang[reader] -The @scheme[reader] ``language'' is a kind of meta-language. It -@scheme[read]s the S-expression that follows @litchar{#lang reader} +The @racket[reader] ``language'' is a kind of meta-language. It +@racket[read]s the S-expression that follows @litchar{#lang reader} and uses it as a module path (relative to the module being read) that -effectively takes the place of @schememodname[reader]. In other words, -the @schememodname[reader] meta-language generalizes the syntax of the +effectively takes the place of @racketmodname[reader]. In other words, +the @racketmodname[reader] meta-language generalizes the syntax of the module specified after @hash-lang[] to be a module path, and without the implicit addition of @litchar{/lang/reader} to the path. diff --git a/collects/scribblings/reference/readtables.scrbl b/collects/scribblings/reference/readtables.scrbl index 2e90650e99..9d0cc3bc7d 100644 --- a/collects/scribblings/reference/readtables.scrbl +++ b/collects/scribblings/reference/readtables.scrbl @@ -4,15 +4,15 @@ @title[#:style 'toc]{Reader Extension} -Scheme's reader can be extended in three ways: through a reader-macro +Racket's reader can be extended in three ways: through a reader-macro procedure in a @tech{readtable} (see @secref["readtables"]), through a @litchar{#reader} form (see @secref["parse-reader"]), or through a custom-port byte reader that returns a ``special'' result procedure (see @secref["customport"]). All three kinds of @deftech{reader extension procedures} accept similar arguments, and their results are -treated in the same way by @scheme[read] and @scheme[read-syntax] (or, +treated in the same way by @racket[read] and @racket[read-syntax] (or, more precisely, by the default read handler; see -@scheme[port-read-handler]). +@racket[port-read-handler]). @local-table-of-contents[] @@ -21,7 +21,7 @@ more precisely, by the default read handler; see The dispatch table in @secref["default-readtable-dispatch"] corresponds to the default @deftech{readtable}. By creating a new -readtable and installing it via the @scheme[current-readtable] +readtable and installing it via the @racket[current-readtable] parameter, the reader's behavior can be extended. A readtable is consulted at specific times by the reader: @@ -56,14 +56,14 @@ that is closed by any character that is mapped to a close parenthesis the parser is simply using the character that started the quote; it does not consult the readtable. -For many contexts, @scheme[#f] identifies the default readtable. In -particular, @scheme[#f] is the initial value for the -@scheme[current-readtable] parameter, which causes the reader to +For many contexts, @racket[#f] identifies the default readtable. In +particular, @racket[#f] is the initial value for the +@racket[current-readtable] parameter, which causes the reader to behave as described in @secref["reader"]. @defproc[(readtable? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a readtable, @scheme[#f] +Returns @racket[#t] if @racket[v] is a readtable, @racket[#f] otherwise. } @@ -79,43 +79,43 @@ otherwise. ...+) readtable?]{ -Creates a new readtable that is like @scheme[readtable] (which can be -@scheme[#f]), except that the reader's behavior is modified for each -@scheme[key] according to the given @scheme[mode] and -@scheme[action]. The @scheme[...+] for @scheme[make-readtable] applies -to all three of @scheme[key], @scheme[mode], and @scheme[action]; in -other words, the total number of arguments to @scheme[make-readtable] +Creates a new readtable that is like @racket[readtable] (which can be +@racket[#f]), except that the reader's behavior is modified for each +@racket[key] according to the given @racket[mode] and +@racket[action]. The @racket[...+] for @racket[make-readtable] applies +to all three of @racket[key], @racket[mode], and @racket[action]; in +other words, the total number of arguments to @racket[make-readtable] must be @math{1} modulo @math{3}. -The possible combinations for @scheme[key], @scheme[mode], and -@scheme[action] are as follows: +The possible combinations for @racket[key], @racket[mode], and +@racket[action] are as follows: @itemize[ - @item{@scheme[(code:line _char (unsyntax @indexed-scheme['terminating-macro]) _proc)] --- causes - @scheme[_char] to be parsed as a delimiter, and an - unquoted/uncommented @scheme[_char] in the input string triggers a - call to the @deftech{reader macro} @scheme[_proc]; the activity of - @scheme[_proc] is described further below. Conceptually, characters + @item{@racket[(code:line _char (unsyntax @indexed-racket['terminating-macro]) _proc)] --- causes + @racket[_char] to be parsed as a delimiter, and an + unquoted/uncommented @racket[_char] in the input string triggers a + call to the @deftech{reader macro} @racket[_proc]; the activity of + @racket[_proc] is described further below. Conceptually, characters like @litchar{;}, @litchar{(}, and @litchar{)} are mapped to terminating reader macros in the default readtable.} - @item{@scheme[(code:line _char (unsyntax @indexed-scheme['non-terminating-macro]) _proc)] --- like - the @scheme['terminating-macro] variant, but @scheme[_char] is not + @item{@racket[(code:line _char (unsyntax @indexed-racket['non-terminating-macro]) _proc)] --- like + the @racket['terminating-macro] variant, but @racket[_char] is not treated as a delimiter, so it can be used in the middle of an identifier or number. Conceptually, @litchar{#} is mapped to a non-terminating macro in the default readtable.} - @item{@scheme[(code:line _char (unsyntax @indexed-scheme['dispatch-macro]) _proc)] --- like the - @scheme['non-terminating-macro] variant, but for @scheme[_char] only + @item{@racket[(code:line _char (unsyntax @indexed-racket['dispatch-macro]) _proc)] --- like the + @racket['non-terminating-macro] variant, but for @racket[_char] only when it follows a @litchar{#} (or, more precisely, when the character follows one that has been mapped to the behavior of @litchar{#}hash in the default readtable).} - @item{@scheme[(code:line _char _like-char _readtable)] --- causes - @scheme[_char] to be parsed in the same way that @scheme[_like-char] - is parsed in @scheme[_readtable], where @scheme[_readtable] can be - @scheme[#f] to indicate the default readtable. Mapping a character to + @item{@racket[(code:line _char _like-char _readtable)] --- causes + @racket[_char] to be parsed in the same way that @racket[_like-char] + is parsed in @racket[_readtable], where @racket[_readtable] can be + @racket[#f] to indicate the default readtable. Mapping a character to the same actions as @litchar{|} in the default reader means that the character starts quoting for symbols, and the same character terminates the quote; in contrast, mapping a character to the same @@ -126,30 +126,30 @@ The possible combinations for @scheme[key], @scheme[mode], and original character; for example, mapping a character to the same action as a curly brace @litchar["{"] in the default readtable means that the character is disallowed when the - @scheme[read-curly-brace-as-paren] parameter is set to @scheme[#f].} + @racket[read-curly-brace-as-paren] parameter is set to @racket[#f].} - @item{@scheme[(code:line #f (unsyntax @indexed-scheme['non-terminating-macro]) _proc)] --- + @item{@racket[(code:line #f (unsyntax @indexed-racket['non-terminating-macro]) _proc)] --- replaces the macro used to parse characters with no specific mapping: i.e., characters (other than @litchar{#} or @litchar{|}) that can start a symbol or number with the default readtable.} ] -If multiple @scheme['dispatch-macro] mappings are provided for a -single @scheme[_char], all but the last one are ignored. Similarly, if -multiple non-@scheme['dispatch-macro] mappings are provided for a -single @scheme[_char], all but the last one are ignored. +If multiple @racket['dispatch-macro] mappings are provided for a +single @racket[_char], all but the last one are ignored. Similarly, if +multiple non-@racket['dispatch-macro] mappings are provided for a +single @racket[_char], all but the last one are ignored. -A reader macro @scheme[_proc] must accept six arguments, and it can +A reader macro @racket[_proc] must accept six arguments, and it can optionally accept two arguments. The first two arguments are always the character that triggered the reader macro and the input port for -reading. When the reader macro is triggered by @scheme[read-syntax] -(or @scheme[read-syntax/recursive]), the procedure is passed four +reading. When the reader macro is triggered by @racket[read-syntax] +(or @racket[read-syntax/recursive]), the procedure is passed four additional arguments that represent a source location. When the reader -macro is triggered by @scheme[read] (or @scheme[read/recursive]), the +macro is triggered by @racket[read] (or @racket[read/recursive]), the procedure is passed only two arguments if it accepts two arguments, otherwise it is passed six arguments where the last four are all -@scheme[#f]. See @secref["reader-procs"] for information on the +@racket[#f]. See @secref["reader-procs"] for information on the procedure's results. A reader macro normally reads characters from the given input port to @@ -157,7 +157,7 @@ produce a value to be used as the ``reader macro-expansion'' of the consumed characters. The reader macro might produce a special-comment value (see @secref["special-comments"]) to cause the consumed character to be treated as whitespace, and it might use -@scheme[read/recursive] or @scheme[read-syntax/recursive].} +@racket[read/recursive] or @racket[read-syntax/recursive].} @defproc[(readtable-mapping [readtable readtable?][char character?]) (values (or/c character? @@ -166,37 +166,37 @@ character to be treated as whitespace, and it might use (or/c #f procedure?) (or/c #f procedure?))]{ -Produces information about the mappings in @scheme[readtable] for -@scheme[char]. The result is three values: +Produces information about the mappings in @racket[readtable] for +@racket[char]. The result is three values: @itemize[ @item{either a character (mapping is to same behavior as the - character in the default readtable), @scheme['terminating-macro], or - @scheme['non-terminating-macro]; this result reports the main (i.e., - non-@scheme['dispatch-macro]) mapping for @scheme[key]. When the result - is a character, then @scheme[key] is mapped to the same behavior as the + character in the default readtable), @racket['terminating-macro], or + @racket['non-terminating-macro]; this result reports the main (i.e., + non-@racket['dispatch-macro]) mapping for @racket[key]. When the result + is a character, then @racket[key] is mapped to the same behavior as the returned character in the default readtable.} - @item{either @scheme[#f] or a reader-macro procedure; the result is a - procedure when the first result is @scheme['terminating-macro] or - @scheme['non-terminating-macro].} + @item{either @racket[#f] or a reader-macro procedure; the result is a + procedure when the first result is @racket['terminating-macro] or + @racket['non-terminating-macro].} - @item{either @scheme[#f] or a reader-macro procedure; the result is a - procedure when the character has a @scheme['dispatch-macro] mapping in - @scheme[readtable] to override the default dispatch behavior.} + @item{either @racket[#f] or a reader-macro procedure; the result is a + procedure when the character has a @racket['dispatch-macro] mapping in + @racket[readtable] to override the default dispatch behavior.} ] Note that reader-macro procedures for the default readtable are not directly accessible. To invoke default behaviors, use -@scheme[read/recursive] or @scheme[read-syntax/recursive] with a -character and the @scheme[#f] readtable.} +@racket[read/recursive] or @racket[read-syntax/recursive] with a +character and the @racket[#f] readtable.} @(begin #readerscribble/comment-reader [examples -;; Provides @scheme[raise-read-error] and @scheme[raise-read-eof-error] +;; Provides @racket[raise-read-error] and @racket[raise-read-eof-error] (require syntax/readerr) (define (skip-whitespace port) @@ -326,38 +326,38 @@ character and the @scheme[#f] readtable.} @section[#:tag "reader-procs"]{Reader-Extension Procedures} Calls to @techlink{reader extension procedures} can be triggered -through @scheme[read], @scheme[read/recursive], @scheme[read-syntax], -or @scheme[read-honu-syntax]. In addition, a special-read procedure -can be triggered by calls to @scheme[read-honu], -@scheme[read-honu/recursive], @scheme[read-honu-syntax], -@scheme[read-honu-syntax/recursive], @scheme[read-char-or-special], or -by the context of @scheme[read-bytes-avail!], -@scheme[read-bytes-avail!*], @scheme[read-bytes-avail!], and -@scheme[peek-bytes-avail!*]. +through @racket[read], @racket[read/recursive], @racket[read-syntax], +or @racket[read-honu-syntax]. In addition, a special-read procedure +can be triggered by calls to @racket[read-honu], +@racket[read-honu/recursive], @racket[read-honu-syntax], +@racket[read-honu-syntax/recursive], @racket[read-char-or-special], or +by the context of @racket[read-bytes-avail!], +@racket[read-bytes-avail!*], @racket[read-bytes-avail!], and +@racket[peek-bytes-avail!*]. Optional arities for reader-macro and special-result procedures allow -them to distinguish reads via @scheme[read], @|etc| from reads via -@scheme[read-syntax], @|etc| (where the source value is @scheme[#f] and +them to distinguish reads via @racket[read], @|etc| from reads via +@racket[read-syntax], @|etc| (where the source value is @racket[#f] and no other location information is available). When a reader-extension procedure is called in syntax-reading mode -(via @scheme[read-syntax], @|etc|), it should generally return a syntax +(via @racket[read-syntax], @|etc|), it should generally return a syntax object that has no lexical context (e.g., a syntax object created -using @scheme[datum->syntax] with @scheme[#f] as the first +using @racket[datum->syntax] with @racket[#f] as the first argument and with the given location information as the third argument). Another possible result is a special-comment value (see @secref["special-comments"]). If the procedure's result is not a syntax object and not a special-comment value, it is converted to one -using @scheme[datum->syntax]. +using @racket[datum->syntax]. When a reader-extension procedure is called in non-syntax-reading modes, it should generally not return a syntax object. If a syntax object is returned, it is converted to a plain value using -@scheme[syntax-object->datum]. +@racket[syntax-object->datum]. In either context, when the result from a reader-extension procedure is a special-comment value (see @secref["special-comments"]), then -@scheme[read], @scheme[read-syntax], @|etc| treat the value as a +@racket[read], @racket[read-syntax], @|etc| treat the value as a delimiting comment and otherwise ignore it. Also, in either context, the result may be copied to prevent mutation @@ -366,7 +366,7 @@ support the construction of graphs with cycles. Mutable boxes, vectors, and @tech{prefab} structures are copied, along with any pairs, boxes, vectors, pre prefab structures that lead to such mutable values, to placeholders produced by a recursive read (see -@scheme[read/recursive]), or to references of a shared value. Graph +@racket[read/recursive]), or to references of a shared value. Graph structure (including cycles) is preserved in the copy. @;------------------------------------------------------------------------ @@ -374,20 +374,20 @@ structure (including cycles) is preserved in the copy. @defproc[(make-special-comment [v any/c]) special-comment?]{ -Creates a special-comment value that encapsulates @scheme[v]. The -@scheme[read], @scheme[read-syntax], @|etc| procedures treat values -constructed with @scheme[make-special-comment] as delimiting +Creates a special-comment value that encapsulates @racket[v]. The +@racket[read], @racket[read-syntax], @|etc| procedures treat values +constructed with @racket[make-special-comment] as delimiting whitespace when returned by a reader-extension procedure (see @secref["reader-procs"]).} @defproc[(special-comment? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is the result of -@scheme[make-special-comment], @scheme[#f] otherwise.} +Returns @racket[#t] if @racket[v] is the result of +@racket[make-special-comment], @racket[#f] otherwise.} @defproc[(special-comment-value [sc special-comment?]) any]{ Returns the value encapsulated by the special-comment value -@scheme[sc]. This value is never used directly by a reader, but it -might be used by the context of a @scheme[read-char-or-special], @|etc| +@racket[sc]. This value is never used directly by a reader, but it +might be used by the context of a @racket[read-char-or-special], @|etc| call that detects a special comment.} diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index b59d76cb47..5bd3cdfcb9 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/collects/scribblings/reference/reference.scrbl @@ -6,7 +6,7 @@ scribble/core racket/list) -@(define (scheme-extra-libs) +@(define (racket-extra-libs) (make-delayed-element (lambda (renderer p ri) (let ([mods (append-map @@ -35,7 +35,7 @@ friendlier (though less precise and less complete) overview of the language. @defmodulelang*[(racket/base racket) - ;; Use sources for overlap with `mzscheme': + ;; Use sources for overlap with `scheme' and `mzscheme': #:use-sources ('#%kernel racket/private/more-scheme racket/private/misc @@ -48,11 +48,11 @@ language. racket/private/base)]{ Unless otherwise noted, the bindings defined in this manual are -exported by the @schememodname[racket/base] and @schememodname[racket] +exported by the @racketmodname[racket/base] and @racketmodname[racket] languages.} -@margin-note{The @schememodname[racket] library combines -@schememodname[racket/base]@scheme-extra-libs[].} +@margin-note{The @racketmodname[racket] library combines +@racketmodname[racket/base]@racket-extra-libs[].} @table-of-contents[] diff --git a/collects/scribblings/reference/running.scrbl b/collects/scribblings/reference/running.scrbl index 034765888a..b799c913f0 100644 --- a/collects/scribblings/reference/running.scrbl +++ b/collects/scribblings/reference/running.scrbl @@ -1,7 +1,7 @@ #lang scribble/doc @(require "mz.ss") -@title[#:tag "running" #:style 'toc]{Running PLT Scheme} +@title[#:tag "running" #:style 'toc]{Running Racket} @local-table-of-contents[] diff --git a/collects/scribblings/reference/runtime.scrbl b/collects/scribblings/reference/runtime.scrbl index 180dfe3ea4..cd00b4733a 100644 --- a/collects/scribblings/reference/runtime.scrbl +++ b/collects/scribblings/reference/runtime.scrbl @@ -6,60 +6,60 @@ @defproc[(getenv [name string?]) (or/c string? #f)]{ Gets the value of an operating system environment variable. The -@scheme[name] argument cannot contain a null character; if an -environment variable named by @scheme[name] exists, its value is -returned (as a string); otherwise, @scheme[#f] is returned.} +@racket[name] argument cannot contain a null character; if an +environment variable named by @racket[name] exists, its value is +returned (as a string); otherwise, @racket[#f] is returned.} @defproc[(putenv [name string?][value string?]) boolean?]{ Sets the value of an operating system environment variable. The -@scheme[name] and @scheme[value] arguments are strings that cannot +@racket[name] and @racket[value] arguments are strings that cannot contain a null character; the environment variable named by -@scheme[name] is set to @scheme[value]. The return value is -@scheme[#t] if the assignment succeeds, @scheme[#f] otherwise.} +@racket[name] is set to @racket[value]. The return value is +@racket[#t] if the assignment succeeds, @racket[#f] otherwise.} @defproc[(system-type [mode (or/c 'os 'gc 'link 'so-suffix 'machine) 'os]) (or/c symbol? string? bytes?)]{ Returns information about the operating system, build mode, or machine -for a running Scheme. +for a running Racket. -In @indexed-scheme['os] mode, +In @indexed-racket['os] mode, the possible symbol results are: @itemize[ -@item{@indexed-scheme['unix]} -@item{@indexed-scheme['windows]} -@item{@indexed-scheme['macosx]} +@item{@indexed-racket['unix]} +@item{@indexed-racket['windows]} +@item{@indexed-racket['macosx]} ] -In @indexed-scheme['gc] mode, +In @indexed-racket['gc] mode, the possible symbol results are: @itemize[ -@item{@indexed-scheme['cgc]} -@item{@indexed-scheme['3m]} +@item{@indexed-racket['cgc]} +@item{@indexed-racket['3m]} ] -In @indexed-scheme['link] mode, the possible symbol results are: +In @indexed-racket['link] mode, the possible symbol results are: @itemize[ -@item{@indexed-scheme['static] (Unix)} -@item{@indexed-scheme['shared] (Unix)} -@item{@indexed-scheme['dll] (Windows)} -@item{@indexed-scheme['framework] (Mac OS X)} +@item{@indexed-racket['static] (Unix)} +@item{@indexed-racket['shared] (Unix)} +@item{@indexed-racket['dll] (Windows)} +@item{@indexed-racket['framework] (Mac OS X)} ] -Future ports of Scheme may expand the list of @scheme['os], -@scheme['gc], and @scheme['link] results. +Future ports of Racket may expand the list of @racket['os], +@racket['gc], and @racket['link] results. -In @indexed-scheme['so-suffix] mode, then the result is a byte string +In @indexed-racket['so-suffix] mode, then the result is a byte string that represents the file extension used for shared objects on the current platform. The byte string starts with a period, so it is -suitable as a second argument to @scheme[path-replace-suffix]. +suitable as a second argument to @racket[path-replace-suffix]. -In @indexed-scheme['machine] mode, then the result is a string, which +In @indexed-racket['machine] mode, then the result is a string, which contains further details about the current machine in a platform-specific format.} @@ -89,27 +89,27 @@ Mac OS X, the result is determined by system calls.} path?]{ Returns a relative directory path. This string can be used to build -paths to system-specific files. For example, when Scheme is running +paths to system-specific files. For example, when Racket is running under Solaris on a Sparc architecture, the subpath starts -@scheme["sparc-solaris"], while the subpath for Windows on an i386 -architecture starts @scheme["win32\\i386"]. +@racket["sparc-solaris"], while the subpath for Windows on an i386 +architecture starts @racket["win32\\i386"]. -The optional @scheme[mode] argument specifies the relevant +The optional @racket[mode] argument specifies the relevant garbage-collection variant, which one of the possible results of -@scheme[(system-type 'gc)]: @scheme['cgc] or @scheme['3m]. It can also -be @scheme[#f], in which case the result is independent of the +@racket[(system-type 'gc)]: @racket['cgc] or @racket['3m]. It can also +be @racket[#f], in which case the result is independent of the garbage-collection variant.} @defproc[(version) (and/c string? immutable?)]{ Returns an string indicating the currently executing version of -Scheme.} +Racket.} @defproc[(banner) (and/c string? immutable?)]{ -Returns an immutable string for Scheme's start-up banner text (or the +Returns an immutable string for Racket's start-up banner text (or the banner text for an embedding program, such as MrEd). The banner string ends with a newline.} @@ -117,7 +117,7 @@ ends with a newline.} @defparam[current-command-line-arguments argv (vectorof (and/c string? immutable?))]{ A parameter that is initialized with command-line arguments when -Scheme starts (not including any command-line arguments that were +Racket starts (not including any command-line arguments that were treated as flags for the system).} @@ -134,56 +134,56 @@ otherwise platform-independent.} [thd (or/c thread? #f) #f]) void?]{ -Sets elements in @scheme[results] to report current performance -statistics. If @scheme[thd] is not @scheme[#f], a particular set of +Sets elements in @racket[results] to report current performance +statistics. If @racket[thd] is not @racket[#f], a particular set of thread-specific statistics are reported, otherwise a different set of global statics are reported. For global statistics, up to @math{10} elements are set in the vector, -starting from the beginning. (In future versions of Scheme, additional -elements will be set.) If @scheme[results] has @math{n} elements where +starting from the beginning. (In future versions of Racket, additional +elements will be set.) If @racket[results] has @math{n} elements where @math{n < 8}, then the @math{n} elements are set to the first @math{n} performance-statistics values. The reported statistics values are as -follows, in the order that they are set within @scheme[results]: +follows, in the order that they are set within @racket[results]: @itemize[ - @item{@scheme[0]: The same value as returned by - @scheme[current-process-milliseconds].} + @item{@racket[0]: The same value as returned by + @racket[current-process-milliseconds].} - @item{@scheme[1]: The same value as returned - by @scheme[current-milliseconds].} + @item{@racket[1]: The same value as returned + by @racket[current-milliseconds].} - @item{@scheme[2]: The same value as returned - by @scheme[current-gc-milliseconds].} + @item{@racket[2]: The same value as returned + by @racket[current-gc-milliseconds].} - @item{@scheme[3]: The number of garbage collections performed since + @item{@racket[3]: The number of garbage collections performed since start-up.} - @item{@scheme[4]: The number of thread context switches performed since + @item{@racket[4]: The number of thread context switches performed since start-up.} - @item{@scheme[5]: The number of internal stack overflows handled since + @item{@racket[5]: The number of internal stack overflows handled since start-up.} - @item{@scheme[6]: The number of threads currently scheduled for + @item{@racket[6]: The number of threads currently scheduled for execution (i.e., threads that are running, not suspended, and not unscheduled due to a synchronization).} - @item{@scheme[7]: The number of syntax objects read from compiled code + @item{@racket[7]: The number of syntax objects read from compiled code since start-up.} - @item{@scheme[8]: The number of hash-table searches performed. When + @item{@racket[8]: The number of hash-table searches performed. When this counter reaches the maximum value of a @tech{fixnum}, it overflows to the most negative @tech{fixnum}.} - @item{@scheme[9]: The number of additional hash slots searched to + @item{@racket[9]: The number of additional hash slots searched to complete hash searches (using double hashing). When this counter reaches the maximum value of a @tech{fixnum}, it overflows to the most negative @tech{fixnum}.} - @item{@scheme[10]: The number of bytes allocated for machine code - that is not reported by @scheme[current-memory-use].} + @item{@racket[10]: The number of bytes allocated for machine code + that is not reported by @racket[current-memory-use].} ] @@ -192,17 +192,17 @@ vector: @itemize[ - @item{@scheme[0]: @scheme[#t] if the thread is running, @scheme[#f] - otherwise (same result as @scheme[thread-running?]).} + @item{@racket[0]: @racket[#t] if the thread is running, @racket[#f] + otherwise (same result as @racket[thread-running?]).} - @item{@scheme[1]: @scheme[#t] if the thread has terminated, - @scheme[#f] otherwise (same result as @scheme[thread-dead?]).} + @item{@racket[1]: @racket[#t] if the thread has terminated, + @racket[#f] otherwise (same result as @racket[thread-dead?]).} - @item{@scheme[2]: @scheme[#t] if the thread is currently blocked on a + @item{@racket[2]: @racket[#t] if the thread is currently blocked on a synchronizable event (or sleeping for some number of milliseconds), - @scheme[#f] otherwise.} + @racket[#f] otherwise.} - @item{@scheme[3]: The number of bytes currently in use for the + @item{@racket[3]: The number of bytes currently in use for the thread's continuation.} ] diff --git a/collects/scribblings/reference/sandbox.scrbl b/collects/scribblings/reference/sandbox.scrbl index 9db038dbdc..cab675a9cf 100644 --- a/collects/scribblings/reference/sandbox.scrbl +++ b/collects/scribblings/reference/sandbox.scrbl @@ -1,19 +1,19 @@ #lang scribble/doc @(require "mz.ss" - scheme/sandbox - (for-label scheme/sandbox + racket/sandbox + (for-label racket/sandbox racket/port (only-in racket/gui make-gui-namespace) racket/gui/dynamic)) @(define box-eval (make-base-eval)) -@(interaction-eval #:eval box-eval (require scheme/sandbox)) +@(interaction-eval #:eval box-eval (require racket/sandbox)) @title{Sandboxed Evaluation} -@note-lib-only[scheme/sandbox] +@note-lib-only[racket/sandbox] -The @schememodname[scheme/sandbox] module provides utilities for +The @racketmodname[racket/sandbox] module provides utilities for creating ``sandboxed'' evaluators, which are configured in a particular way and can have restricted resources (memory and time), filesystem and network access, and much more. Sandboxed evaluators can be @@ -32,22 +32,22 @@ for the common use case where sandboxes are very limited. [#:allow-read allow (listof (or/c module-path? path?))]) (any/c . -> . any)])]{ -The @scheme[make-evaluator] function creates an evaluator with a -@scheme[language] and @scheme[requires] specification, and starts -evaluating the given @scheme[input-program]s. The -@scheme[make-module-evaluator] function creates an evaluator that +The @racket[make-evaluator] function creates an evaluator with a +@racket[language] and @racket[requires] specification, and starts +evaluating the given @racket[input-program]s. The +@racket[make-module-evaluator] function creates an evaluator that works in the context of a given module. The result in either case is a function for further evaluation. The returned evaluator operates in an isolated and limited environment. In particular, filesystem access is restricted. The -@scheme[allow] argument extends the set of files that are readable by +@racket[allow] argument extends the set of files that are readable by the evaluator to include the specified modules and their imports -(transitively). When @scheme[language] is a module path and when -@scheme[requires] is provided, the indicated modules are implicitly -included in the @scheme[allow] list. +(transitively). When @racket[language] is a module path and when +@racket[requires] is provided, the indicated modules are implicitly +included in the @racket[allow] list. -Each @scheme[input-program] or @scheme[module-decl] argument provides +Each @racket[input-program] or @racket[module-decl] argument provides a program in one of the following forms: @itemize[ @@ -59,76 +59,76 @@ a program in one of the following forms: @item{a path that names a file holding the input; or} @item{an S-expression or a @tech{syntax object}, which is evaluated - as with @scheme[eval] (see also - @scheme[get-uncovered-expressions]).} + as with @racket[eval] (see also + @racket[get-uncovered-expressions]).} ] In the first three cases above, the program is read using -@scheme[sandbox-reader], with line-counting enabled for sensible error -messages, and with @scheme['program] as the source (used for testing +@racket[sandbox-reader], with line-counting enabled for sensible error +messages, and with @racket['program] as the source (used for testing coverage). In the last case, the input is expected to be the complete program, and is converted to a @tech{syntax object} (using -@scheme['program] as the source), unless it already is a @tech{syntax +@racket['program] as the source), unless it already is a @tech{syntax object}. The returned evaluator function accepts additional expressions (each time it is called) in essentially the same form: a string or byte string holding a sequence of expressions, a path for a file holding expressions, an S-expression, or a @tech{syntax object}. If -the evaluator receives an @scheme[eof] value, it is terminated and -raises errors thereafter. See also @scheme[kill-evaluator], which +the evaluator receives an @racket[eof] value, it is terminated and +raises errors thereafter. See also @racket[kill-evaluator], which terminates the evaluator without raising an exception. -For @scheme[make-evaluator], multiple @scheme[input-program]s are +For @racket[make-evaluator], multiple @racket[input-program]s are effectively concatenated to form a single program. The way that the -@scheme[input-program]s are evaluated depends on the @scheme[language] +@racket[input-program]s are evaluated depends on the @racket[language] argument: @itemize[ - @item{The @scheme[language] argument can be a module path (i.e., a - datum that matches the grammar for @scheme[_module-path] of - @scheme[require]). + @item{The @racket[language] argument can be a module path (i.e., a + datum that matches the grammar for @racket[_module-path] of + @racket[require]). - In this case, the @scheme[input-program]s are automatically - wrapped in a @scheme[module], and the resulting evaluator works + In this case, the @racket[input-program]s are automatically + wrapped in a @racket[module], and the resulting evaluator works within the resulting module's namespace.} - @item{The @scheme[language] argument can be a list starting with - @scheme['special], which indicates a built-in language with + @item{The @racket[language] argument can be a list starting with + @racket['special], which indicates a built-in language with special input configuration. The possible values are - @scheme['(special r5rs)] or a value indicating a teaching - language: @scheme['(special beginner)], @scheme['(special - beginner-abbr)], @scheme['(special intermediate)], - @scheme['(special intermediate-lambda)], or @scheme['(special + @racket['(special r5rs)] or a value indicating a teaching + language: @racket['(special beginner)], @racket['(special + beginner-abbr)], @racket['(special intermediate)], + @racket['(special intermediate-lambda)], or @racket['(special advanced)]. - In this case, the @scheme[input-program]s are automatically - wrapped in a @scheme[module], and the resulting evaluator works + In this case, the @racket[input-program]s are automatically + wrapped in a @racket[module], and the resulting evaluator works within the resulting module's namespace. In addition, certain - parameters (such as such as @scheme[read-accept-infix-dot]) are + parameters (such as such as @racket[read-accept-infix-dot]) are set to customize reading programs from strings and ports. This option is provided mainly for older test systems. Using - @scheme[make-module-evaluator] with input starting with - @schememodfont{#lang} is generally better.} + @racket[make-module-evaluator] with input starting with + @racketmodfont{#lang} is generally better.} - @item{Finally, @scheme[language] can be a list whose first element is - @scheme['begin]. + @item{Finally, @racket[language] can be a list whose first element is + @racket['begin]. In this case, a new namespace is created using - @scheme[sandbox-namespace-specs], which by default creates a - new namespace using @scheme[make-base-namespace] or - @scheme[make-gui-namespace] (depending on @scheme[gui?]). + @racket[sandbox-namespace-specs], which by default creates a + new namespace using @racket[make-base-namespace] or + @racket[make-gui-namespace] (depending on @racket[gui?]). - In the new namespace, @scheme[language] is evaluated as an + In the new namespace, @racket[language] is evaluated as an expression to further initialize the namespace.} ] -The @scheme[requires] list adds additional imports to the module or -namespace for the @scheme[input-program]s, even in the case that -@scheme[require] is not made available through the @scheme[language]. +The @racket[requires] list adds additional imports to the module or +namespace for the @racket[input-program]s, even in the case that +@racket[require] is not made available through the @racket[language]. The following examples illustrate the difference between an evaluator that puts the program in a module and one that merely initializes a @@ -152,23 +152,23 @@ top-level namespace: (base-top-eval '(f)) ] -The @scheme[make-module-evaluator] function is essentially a -restriction of @scheme[make-evaluator], where the program must be a +The @racket[make-module-evaluator] function is essentially a +restriction of @racket[make-evaluator], where the program must be a module, and all imports are part of the program. In some cases it is useful to restrict the program to be a module using a spcific module -in its language position --- use the optional @scheme[lang] argument -to specify such a restriction (the default, @scheme[#f], means no +in its language position --- use the optional @racket[lang] argument +to specify such a restriction (the default, @racket[#f], means no restriction is enforced). -@schemeblock[ +@racketblock[ (define base-module-eval2 - (code:comment @#,t{equivalent to @scheme[base-module-eval]:}) + (code:comment @#,t{equivalent to @racket[base-module-eval]:}) (make-module-evaluator '(module m racket/base (define (f) later) (define later 5)))) ] -@scheme[make-module-evaluator] can be very convenient for testing +@racket[make-module-evaluator] can be very convenient for testing module files: all you need to do is pass in a path value for the file name, and you get back an evaluator in the module's context which you can use with your favorite test facility. @@ -177,22 +177,22 @@ In all cases, the evaluator operates in an isolated and limited environment: @itemize[ - @item{It uses a new custodian and namespace. When @scheme[gui?] is + @item{It uses a new custodian and namespace. When @racket[gui?] is true, it is also runs in its own eventspace.} - @item{The evaluator works under the @scheme[sandbox-security-guard], + @item{The evaluator works under the @racket[sandbox-security-guard], which restricts file system and network access.} @item{The evaluator is contained in a memory-restricted environment, - and each evaluation is wrapped in a @scheme[call-with-limits] + and each evaluation is wrapped in a @racket[call-with-limits] (when memory accounting is available); see also - @scheme[sandbox-memory-limit], @scheme[sandbox-eval-limits] and - @scheme[set-eval-limits].} + @racket[sandbox-memory-limit], @racket[sandbox-eval-limits] and + @racket[set-eval-limits].} ] Note that these limits apply to the creation of the sandbox environment too --- so, for example, if the memory that is required to create the sandbox is higher than the limit, then -@scheme[make-evaluator] will fail with a memory limit exception. +@racket[make-evaluator] will fail with a memory limit exception. The sandboxed evironment is well isolated, and the evaluator function essentially sends it an expression and waits for a result. This form @@ -200,26 +200,26 @@ of communication makes it impossible to have nested (or concurrent) calls to a single evaluator. Usually this is not a problem, but in some cases you can get the evaluator function available inside the sandboxed code, for example: -@schemeblock[ +@racketblock[ (let ([e (make-evaluator 'racket/base)]) (e (,e 1))) ] An error will be signalled in such cases. Evaluation can also be instrumented to track coverage information when -@scheme[sandbox-coverage-enabled] is set. Exceptions (both syntax and +@racket[sandbox-coverage-enabled] is set. Exceptions (both syntax and run-time) are propagated as usual to the caller of the evaluation -function (i.e., catch it with @scheme[with-handlers]). However, note +function (i.e., catch it with @racket[with-handlers]). However, note that a sandboxed evaluator is convenient for testing, since all exceptions happen in the same way, so you don't need special code to catch syntax errors. Finally, the fact that a sandboxed evaluator accept syntax objects -makes it usable as the value for @scheme[current-eval], which means +makes it usable as the value for @racket[current-eval], which means that you can easily start a sandboxed read-eval-print-loop. For example, here is a quick implementation of a networked REPL: -@schemeblock[ +@racketblock[ (define e (make-evaluator 'racket/base)) (let-values ([(i o) (tcp-accept (tcp-listen 9999))]) (parameterize ([current-input-port i] @@ -235,12 +235,12 @@ Note that in this code it is only the REPL interactions that are going over the network connection; using I/O operations inside the REPL will still use the usual sandbox parameters (defaulting to no I/O). In addition, the code works only from an existing toplevel REPL --- -specifically, @scheme[read-eval-print-loop] reads a syntax value and +specifically, @racket[read-eval-print-loop] reads a syntax value and gives it the lexical context of the current namespace. Here is a variation that uses the networked ports for user I/O, and works when used from a module (by using a new namespace): -@schemeblock[ +@racketblock[ (let-values ([(i o) (tcp-accept (tcp-listen 9999))]) (parameterize ([current-input-port i] [current-output-port o] @@ -267,15 +267,15 @@ A predicate and accessor for exceptions that are raised when a sandbox is terminated. Once a sandbox raises such an exception, it will continue to raise it on further evaluation attempts. -@scheme[call-with-limits]. The @scheme[resource] field holds a symbol, -either @scheme['time] or @scheme['memory].} +@racket[call-with-limits]. The @racket[resource] field holds a symbol, +either @racket['time] or @racket['memory].} @; ---------------------------------------------------------------------- @section{Customizing Evaluators} -The sandboxed evaluators that @scheme[make-evaluator] creates can be +The sandboxed evaluators that @racket[make-evaluator] creates can be customized via many parameters. Most of the configuration parameters affect newly created evaluators; changing them has no effect on already-running evaluators. @@ -286,13 +286,13 @@ Further customizations might be needed in case more privileges are needed, or if you want tighter restrictions. Another useful approach for customizing an evaluator is to begin with a relatively unrestricted configuration and add the desired restrictions. This is -possible by the @scheme[call-with-trusted-sandbox-configuration] +possible by the @racket[call-with-trusted-sandbox-configuration] function. @defproc[(call-with-trusted-sandbox-configuration [thunk (-> any)]) any]{ -Invokes the @scheme[thunk] in a context where sandbox configuration +Invokes the @racket[thunk] in a context where sandbox configuration parameters are set for minimal restrictions. More specifically, there are no memory or time limits, and the existing existing inspectors, security guard, exit handler, and logger are used. (Note that the I/O @@ -305,7 +305,7 @@ A parameter that determines a thunk to be called for initializing a new evaluator. The hook is called just before the program is evaluated in a newly-created evaluator context. It can be used to setup environment parameters related to reading, writing, evaluation, -and so on. Certain languages (@scheme['(special r5rs)] and the +and so on. Certain languages (@racket['(special r5rs)] and the teaching languages) have initializations specific to the language; the hook is used after that initialization, so it can override settings.} @@ -313,13 +313,13 @@ hook is used after that initialization, so it can override settings.} @defparam[sandbox-reader proc (any/c . -> . any)]{ A parameter that specifies a function that reads all expressions from -@scheme[(current-input-port)]. The function is used to read program +@racket[(current-input-port)]. The function is used to read program source for an evaluator when a string, byte string, or port is supplied. The reader function receives a value to be used as input -source (i.e., the first argument to @scheme[read-syntax]), and it +source (i.e., the first argument to @racket[read-syntax]), and it should return a list of @tech{syntax objects}. The default reader -calls @scheme[read-syntax], accumulating results in a list until it -receives @scheme[eof].} +calls @racket[read-syntax], accumulating results in a list until it +receives @racket[eof].} @defparam[sandbox-input in (or/c #f @@ -328,23 +328,23 @@ receives @scheme[eof].} 'pipe (-> input-port?))]{ -A parameter that determines the initial @scheme[current-input-port] -setting for a newly created evaluator. It defaults to @scheme[#f], +A parameter that determines the initial @racket[current-input-port] +setting for a newly created evaluator. It defaults to @racket[#f], which creates an empty port. The following other values are allowed: @itemize[ @item{a string or byte string, which is converted to a port using - @scheme[open-input-string] or @scheme[open-input-bytes];} + @racket[open-input-string] or @racket[open-input-bytes];} @item{an input port;} - @item{the symbol @scheme['pipe], which triggers the creation of a - pipe, where @scheme[put-input] can return the output end of the + @item{the symbol @racket['pipe], which triggers the creation of a + pipe, where @racket[put-input] can return the output end of the pipe or write directly to it;} @item{a thunk, which is called to obtain a port (e.g., using - @scheme[current-input-port] means that the evaluator input is + @racket[current-input-port] means that the evaluator input is the same as the calling context's input).} ]} @@ -357,8 +357,8 @@ which creates an empty port. The following other values are allowed: 'string (-> output-port?))]{ -A parameter that determines the initial @scheme[current-output-port] -setting for a newly created evaluator. It defaults to @scheme[#f], +A parameter that determines the initial @racket[current-output-port] +setting for a newly created evaluator. It defaults to @racket[#f], which creates a port that discrds all data. The following other values are allowed: @@ -366,19 +366,19 @@ values are allowed: @item{an output port, which is used as-is;} - @item{the symbol @scheme['bytes], which causes @scheme[get-output] + @item{the symbol @racket['bytes], which causes @racket[get-output] to return the complete output as a byte string;} - @item{the symbol @scheme['string], which is similar to - @scheme['bytes], but makes @scheme[get-output] produce a + @item{the symbol @racket['string], which is similar to + @racket['bytes], but makes @racket[get-output] produce a string;} - @item{the symbol @scheme['pipe], which triggers the creation of a - pipe, where @scheme[get-output] returns the input end of the + @item{the symbol @racket['pipe], which triggers the creation of a + pipe, where @racket[get-output] returns the input end of the pipe;} @item{a thunk, which is called to obtain a port (e.g., using - @scheme[current-output-port] means that the evaluator output is + @racket[current-output-port] means that the evaluator output is not diverted).} ]} @@ -391,13 +391,13 @@ values are allowed: 'string (-> output-port?))]{ -Like @scheme[sandbox-output], but for the initial -@scheme[current-error-port] value. An evaluator's error output is set -after its output, so using @scheme[current-output-port] (the parameter +Like @racket[sandbox-output], but for the initial +@racket[current-error-port] value. An evaluator's error output is set +after its output, so using @racket[current-output-port] (the parameter itself, not its value) for this parameter value means that the error port is the same as the evaluator's initial output port. -The default is @scheme[(lambda () (dup-output-port +The default is @racket[(lambda () (dup-output-port (current-error-port)))], which means that the error output of the generated evaluator goes to the calling context's error port.} @@ -406,12 +406,12 @@ generated evaluator goes to the calling context's error port.} A parameter that controls whether syntactic coverage information is collected by sandbox evaluators. Use -@scheme[get-uncovered-expressions] to retrieve coverage information.} +@racket[get-uncovered-expressions] to retrieve coverage information.} @defboolparam[sandbox-propagate-breaks propagate?]{ -When both this boolean parameter and @scheme[(break-enabled)] are true, +When both this boolean parameter and @racket[(break-enabled)] are true, breaking while an evaluator is running propagates the break signal to the sandboxed context. This makes the sandboxed evaluator break, typically, but @@ -422,35 +422,35 @@ evaluator's result, in which case the evaluation result is lost. Finally, beware that a break may be propagated after an evaluator has produced a result, so that the break is visible on the next interaction with the evaluator (or the break is lost if the evaluator is not used -further). The default is @scheme[#t].} +further). The default is @racket[#t].} @defparam[sandbox-namespace-specs spec (cons/c (-> namespace?) (listof module-path?))]{ A parameter that holds a list of values that specify how to create a -namespace for evaluation in @scheme[make-evaluator] or -@scheme[make-module-evaluator]. The first item in the list is a thunk +namespace for evaluation in @racket[make-evaluator] or +@racket[make-module-evaluator]. The first item in the list is a thunk that creates the namespace, and the rest are module paths for modules to be attached to the created namespace using -@scheme[namespace-attach-module]. +@racket[namespace-attach-module]. -The default is @scheme[(list make-base-namespace)] if @scheme[gui?] is -@scheme[#f], @scheme[(list make-gui-namespace)] if @scheme[gui?] is -@scheme[#t]. +The default is @racket[(list make-base-namespace)] if @racket[gui?] is +@racket[#f], @racket[(list make-gui-namespace)] if @racket[gui?] is +@racket[#t]. The module paths are needed for sharing module instantiations between the sandbox and the caller. For example, sandbox code that returns -@scheme[posn] values (from the @schemeidfont{lang/posn} module) will +@racket[posn] values (from the @racketidfont{lang/posn} module) will not be recognized as such by your own code by default, since the -sandbox will have its own instance of @schemeidfont{lang/posn} and -thus its own struct type for @scheme[posn]s. To be able to use such -values, include @scheme['lang/posn] in the list of module paths. +sandbox will have its own instance of @racketidfont{lang/posn} and +thus its own struct type for @racket[posn]s. To be able to use such +values, include @racket['lang/posn] in the list of module paths. When testing code that uses a teaching language, the following piece of code can be helpful: -@schemeblock[ +@racketblock[ (sandbox-namespace-specs (let ([specs (sandbox-namespace-specs)]) `(,(car specs) @@ -463,24 +463,24 @@ of code can be helpful: @defparam[sandbox-override-collection-paths paths (listof path-string?)]{ A parameter that determines a list of collection directories to prefix -@scheme[current-library-collection-paths] in an evaluator. This +@racket[current-library-collection-paths] in an evaluator. This parameter is useful for cases when you want to test code using an alternate, test-friendly version of a collection, for example, testing -code that uses a GUI (like the @scheme[htdp/world] teachpack) can be +code that uses a GUI (like the @racket[htdp/world] teachpack) can be done using a fake library that provides the same interface but no -actual interaction. The default is @scheme[null].} +actual interaction. The default is @racket[null].} @defparam[sandbox-security-guard guard (or/c security-guard? (-> security-guard?))]{ A parameter that determines the initial -@scheme[(current-security-guard)] for sandboxed evaluations. It can +@racket[(current-security-guard)] for sandboxed evaluations. It can be either a security guard, or a function to construct one. The default is a function that restricts the access of the current security guard by forbidding all filesystem I/O except for -specifications in @scheme[sandbox-path-permissions], and it uses -@scheme[sandbox-network-guard] for network connections.} +specifications in @racket[sandbox-path-permissions], and it uses +@racket[sandbox-network-guard] for network connections.} @defparam[sandbox-path-permissions perms @@ -494,38 +494,38 @@ them. The contents of this parameter is a list of specifications, each is an access mode and a byte-regexp for paths that are granted this access. -The access mode symbol is one of: @scheme['execute], @scheme['write], -@scheme['delete], @scheme['read], or @scheme['exists]. These symbols +The access mode symbol is one of: @racket['execute], @racket['write], +@racket['delete], @racket['read], or @racket['exists]. These symbols are in decreasing order: each implies access for the following modes -too (e.g., @scheme['read] allows reading or checking for existence). +too (e.g., @racket['read] allows reading or checking for existence). The path regexp is used to identify paths that are granted access. It can also be given as a path (or a string or a byte string), which is (made into a complete path, cleansed, simplified, and then) converted to a regexp that allows the path and sub-directories; e.g., -@scheme["/foo/bar"] applies to @scheme["/foo/bar/baz"]. +@racket["/foo/bar"] applies to @racket["/foo/bar/baz"]. -An additional mode symbol, @scheme['read-bytecode], is not part of the +An additional mode symbol, @racket['read-bytecode], is not part of the linear order of these modes. Specifying this mode is similar to -specifying @scheme['read], but it is not implied by any other mode. -(For example, even if you specify @scheme['write] for a certain path, -you need to also specify @scheme['read-bytecode] to grant this +specifying @racket['read], but it is not implied by any other mode. +(For example, even if you specify @racket['write] for a certain path, +you need to also specify @racket['read-bytecode] to grant this permission.) The sandbox usually works in the context of a lower code -inspector (see @scheme[sandbox-make-code-inspector]) which prevents +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 -@scheme['read-bytecode]. This specification is given by default to +@racket['read-bytecode]. This specification is given by default to the PLT collection hierarchy (including user-specific libraries) and -to libraries that are explicitly specified in an @scheme[#:allow-read] +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 module bindings (see @secref["modprotect"]).) The default value is null, but when an evaluator is created, it is -augmented by @scheme['read-bytecode] permissions that make it possible +augmented by @racket['read-bytecode] permissions that make it possible to use collection libraries (including -@scheme[sandbox-override-collection-paths]). See -@scheme[make-evalautor] for more information.} +@racket[sandbox-override-collection-paths]). See +@racket[make-evalautor] for more information.} @defparam[sandbox-network-guard proc @@ -536,16 +536,16 @@ to use collection libraries (including . -> . any)]{ A parameter that specifieds a procedure to be used (as is) by the -default @scheme[sandbox-security-guard]. The default forbids all +default @racket[sandbox-security-guard]. The default forbids all network connection.} @defparam[sandbox-exit-handler handler (any/c . -> . any)]{ -A parameter that determines the initial @scheme[(exit-handler)] for +A parameter that determines the initial @racket[(exit-handler)] for sandboxed evaluations. The default kills the evaluator with an appropriate error message (see -@scheme[exn:fail:sandbox-terminated-reason]).} +@racket[exn:fail:sandbox-terminated-reason]).} @defparam[sandbox-memory-limit limit (or/c nonnegative-number? #f)]{ @@ -554,7 +554,7 @@ A parameter that determines the total memory limit on the sandbox in megabytes (it can hold a rational or a floating point number). When this limit is exceeded, the sandbox is terminated. This value is used when the sandbox is created and the limit cannot be changed -afterwards. It defaults to 30mb. See @scheme[sandbox-eval-limits] +afterwards. It defaults to 30mb. See @racket[sandbox-eval-limits] for per-evaluation limits and a description of how the two limits work together. @@ -567,10 +567,10 @@ values when the code is done inspecting it. This policy has an impact on how the sandbox memory limit interacts with the per-expression limit specified by -@scheme[sandbox-eval-limits]: values that are reachable from the +@racket[sandbox-eval-limits]: values that are reachable from the sandbox, as well as from the interaction will count against the sandbox limit. For example, in the last interaction of this code, -@schemeblock[ +@racketblock[ (define e (make-evaluator 'racket/base)) (e '(define a 1)) (e '(for ([i (in-range 20)]) (set! a (cons (make-bytes 500000) a)))) @@ -588,19 +588,19 @@ than one block counts against the interaction limit).} #f)]{ A parameter that determines the default limits on @italic{each} use of -a @scheme[make-evaluator] function, including the initial evaluation +a @racket[make-evaluator] function, including the initial evaluation of the input program. Its value should be a list of two numbers; where the first is a timeout value in seconds, and the second is a memory limit in megabytes (note that they don't have to be integers). -Either one can be @scheme[#f] for disabling the corresponding limit; -alternately, the parameter can be set to @scheme[#f] to disable all +Either one can be @racket[#f] for disabling the corresponding limit; +alternately, the parameter can be set to @racket[#f] to disable all per-evaluation limits (useful in case more limit kinds are available -in future versions). The default is @scheme[(list 30 20)]. +in future versions). The default is @racket[(list 30 20)]. Note that these limits apply to the creation of the sandbox -environment too --- even @scheme[(make-evaluator 'racket/base)] can +environment too --- even @racket[(make-evaluator 'racket/base)] can fail if the limits are strict enough. For example, -@schemeblock[ +@racketblock[ (parameterize ([sandbox-eval-limits '(0.25 5)]) (make-evaluator 'racket/base '(sleep 2))) ] @@ -608,10 +608,10 @@ will throw an error instead of creating an evaluator. Therefore, to avoid surprises you need to catch errors that happen when the sandbox is created. -When limits are set, @scheme[call-with-limits] (see below) is wrapped +When limits are set, @racket[call-with-limits] (see below) is wrapped around each use of the evaluator, so consuming too much time or memory results in an exception. Change the limits of a running evaluator -using @scheme[set-eval-limits]. +using @racket[set-eval-limits]. @margin-note{A custodian's limit is checked only after a garbage collection, except that it may also be checked during @@ -620,11 +620,11 @@ using @scheme[set-eval-limits]. The memory limit that is specified by this parameter applies to each individual evaluation, but not to the whole sandbox --- that limit is -specified via @scheme[sandbox-memory-limit]. When the global limit is +specified via @racket[sandbox-memory-limit]. When the global limit is exceeded, the sandbox is terminated, but when the per-evaluation limit is exceeded the @exnraise[exn:fail:resource]. For example, say that you evaluate an expression like -@schemeblock[ +@racketblock[ (for ([i (in-range 1000)]) (set! a (cons (make-bytes 1000000) a)) (collect-garbage)) @@ -638,7 +638,7 @@ then, assuming sufficiently small limits, @item{if there is a per-evaluation limit, but no global limit, the evaluation will abort with an error and it can be used again - --- specifically, @scheme[a] will still hold a number of + --- specifically, @racket[a] will still hold a number of blocks, and you can evaluate the same expression again which will add more blocks to it;} @@ -646,7 +646,7 @@ then, assuming sufficiently small limits, per-evaluation limit, then the evaluation will abort and you will be able to repeat it, but doing so several times will eventually terminate the sandbox (this will be indicated by - the error message, and by the @scheme[evaluator-alive?] + the error message, and by the @racket[evaluator-alive?] predicate).} ]} @@ -662,11 +662,11 @@ initial program when the sandbox is being set-up, and the second is used for each interaction. Each of these handlers should expect a thunk as an argument, and they should execute these thunks --- possibly imposing further restrictions. The default values are -@scheme[#f] and @scheme[call-with-custodian-shutdown], meaning no +@racket[#f] and @racket[call-with-custodian-shutdown], meaning no additional restrictions on initial sandbox code (e.g., it can start background threads), and a custodian-shutdown around each interaction that follows. Another useful function for this is -@scheme[call-with-killing-threads] which kills all threads, but leaves +@racket[call-with-killing-threads] which kills all threads, but leaves other resources intact.} @@ -675,7 +675,7 @@ other resources intact.} A parameter that determines the procedure used to create the inspector for sandboxed evaluation. The procedure is called when initializing an evaluator, and the default parameter value is -@scheme[make-inspector].} +@racket[make-inspector].} @defparam[sandbox-make-code-inspector make (-> inspector?)]{ @@ -683,10 +683,10 @@ an evaluator, and the default parameter value is A parameter that determines the procedure used to create the code inspector for sandboxed evaluation. The procedure is called when initializing an evaluator, and the default parameter value is -@scheme[make-inspector]. The @scheme[current-load/use-compiled] +@racket[make-inspector]. The @racket[current-load/use-compiled] handler is setup to still allow loading of bytecode files under the -original code inspector when @scheme[sandbox-path-permissions] allows -it through a @scheme['read-bytecode] mode symbol, to make it possible +original code inspector when @racket[sandbox-path-permissions] allows +it through a @racket['read-bytecode] mode symbol, to make it possible to load libraries.} @@ -695,7 +695,7 @@ to load libraries.} A parameter that determines the procedure used to create the logger for sandboxed evaluation. The procedure is called when initializing an evaluator, and the default parameter value is -@scheme[current-logger]. This means that it is not creating a new +@racket[current-logger]. This means that it is not creating a new logger (this might change in the future).} @; ---------------------------------------------------------------------- @@ -713,13 +713,13 @@ Determines whether the evaluator is still alive.} @defproc[(kill-evaluator [evaluator (any/c . -> . any)]) void?]{ -Releases the resources that are held by @scheme[evaluator] by shutting +Releases the resources that are held by @racket[evaluator] by shutting down the evaluator's custodian. Attempting to use an evaluator after killing raises an exception, and attempts to kill a dead evaluator are ignored. -Killing an evaluator is similar to sending an @scheme[eof] value to -the evaluator, except that an @scheme[eof] value will raise an error +Killing an evaluator is similar to sending an @racket[eof] value to +the evaluator, except that an @racket[eof] value will raise an error immediately.} @@ -735,28 +735,28 @@ propagates the break to the evaluator's context.} [mb (or/c exact-nonnegative-integer? #f)]) void?]{ -Changes the per-expression limits that @scheme[evaluator] uses to -@scheme[sec] seconds and @scheme[mb] megabytes (either one can be -@scheme[#f], indicating no limit). +Changes the per-expression limits that @racket[evaluator] uses to +@racket[sec] seconds and @racket[mb] megabytes (either one can be +@racket[#f], indicating no limit). This procedure should be used to modify an existing evaluator limits, -because changing the @scheme[sandbox-eval-limits] parameter does not -affect existing evaluators. See also @scheme[call-with-limits].} +because changing the @racket[sandbox-eval-limits] parameter does not +affect existing evaluators. See also @racket[call-with-limits].} @defproc[(set-eval-handler [evaluator (any/c . -> . any)] [handler (or/c #f ((-> any) . -> . any))]) void?]{ -Changes the per-expression handler that the @scheme[evaluator] uses -around each interaction. A @scheme[#f] value means no handler is +Changes the per-expression handler that the @racket[evaluator] uses +around each interaction. A @racket[#f] value means no handler is used. This procedure should be used to modify an existing evaluator handler, -because changing the @scheme[sandbox-eval-handlers] parameter does not +because changing the @racket[sandbox-eval-handlers] parameter does not affect existing evaluators. See also -@scheme[call-with-custodian-shutdown] and -@scheme[call-with-killing-threads] for two useful handlers that are +@racket[call-with-custodian-shutdown] and +@racket[call-with-killing-threads] for two useful handlers that are provided.} @@ -764,10 +764,10 @@ provided.} [(call-with-killing-threads [thunk (-> any)]) any])]{ These functions are useful for use as an evaluation handler. -@scheme[call-with-custodian-shutdown] will execute the @scheme[thunk] +@racket[call-with-custodian-shutdown] will execute the @racket[thunk] in a fresh custodian, then shutdown that custodian, making sure that -@scheme[thunk] could not have left behind any resources. -@scheme[call-with-killing-threads] is similar, except that it kills +@racket[thunk] could not have left behind any resources. +@racket[call-with-killing-threads] is similar, except that it kills threads that were left, but leaves other resources as is.} @@ -775,32 +775,32 @@ threads that were left, but leaves other resources as is.} [(put-input [evaluator (any/c . -> . any)] [i/o (or/c bytes? string? eof-object?)]) void?])]{ -If @scheme[(sandbox-input)] is @scheme['pipe] when an evaluator is +If @racket[(sandbox-input)] is @racket['pipe] when an evaluator is created, then this procedure can be used to retrieve the output port end of the pipe (when used with no arguments), or to add a string or a -byte string into the pipe. It can also be used with @scheme[eof], +byte string into the pipe. It can also be used with @racket[eof], which closes the pipe.} @defproc*[([(get-output [evaluator (any/c . -> . any)]) (or/c #f input-port? bytes? string?)] [(get-error-output [evaluator (any/c . -> . any)]) (or/c #f input-port? bytes? string?)])]{ -Returns the output or error-output of the @scheme[evaluator], -in a way that depends on the setting of @scheme[(sandbox-output)] or -@scheme[(sandbox-error-output)] when the evaluator was created: +Returns the output or error-output of the @racket[evaluator], +in a way that depends on the setting of @racket[(sandbox-output)] or +@racket[(sandbox-error-output)] when the evaluator was created: @itemize[ - @item{if it was @scheme['pipe], then @scheme[get-output] returns the + @item{if it was @racket['pipe], then @racket[get-output] returns the input port end of the created pipe;} - @item{if it was @scheme['bytes] or @scheme['string], then the result + @item{if it was @racket['bytes] or @racket['string], then the result is the accumulated output, and the output port is reset so each call returns a different piece of the evaluator's output (note that any allocations of such output are still subject to the sandbox memory limit);} - @item{otherwise, it returns @scheme[#f].} + @item{otherwise, it returns @racket[#f].} ]} @@ -810,39 +810,39 @@ in a way that depends on the setting of @scheme[(sandbox-output)] or (listof syntax?)]{ Retrieves uncovered expression from an evaluator, as longs as the -@scheme[sandbox-coverage-enabled] parameter had a true value when the +@racket[sandbox-coverage-enabled] parameter had a true value when the evaluator was created. Otherwise, an exception is raised to indicate that no coverage information is available. -The @scheme[prog?] argument specifies whether to obtain expressions that +The @racket[prog?] argument specifies whether to obtain expressions that were uncovered after only the original input program was evaluated -(@scheme[#t]) or after all later uses of the evaluator (@scheme[#f]). -Using @scheme[#t] retrieves a list that is saved after the input +(@racket[#t]) or after all later uses of the evaluator (@racket[#f]). +Using @racket[#t] retrieves a list that is saved after the input program is evaluated, and before the evaluator is used, so the result is always the same. -A @scheme[#t] value of @scheme[prog?] is useful for testing student +A @racket[#t] value of @racket[prog?] is useful for testing student programs to find out whether a submission has sufficient test coverage -built in. A @scheme[#f] value is useful for writing test suites for a +built in. A @racket[#f] value is useful for writing test suites for a program to ensure that your tests cover the whole code. -The second optional argument, @scheme[src], specifies that the result +The second optional argument, @racket[src], specifies that the result should be filtered to hold only @tech{syntax objects} whose source -matches @scheme[src]. The default, @scheme['program], is the source +matches @racket[src]. The default, @racket['program], is the source associated with the input program by the default -@scheme[sandbox-reader]---which provides only @tech{syntax objects} +@racket[sandbox-reader]---which provides only @tech{syntax objects} from the input program (and not from required modules or expressions -that were passed to the evaluator). A @scheme[#f] avoids filtering. +that were passed to the evaluator). A @racket[#f] avoids filtering. The resulting list of @tech{syntax objects} has at most one expression for each position and span. Thus, the contents may be unreliable, but the position information is reliable (i.e., it always indicates source -code that would be painted red in DrScheme when coverage information +code that would be painted red in DrRacket when coverage information is used). Note that if the input program is a sequence of syntax values, either -make sure that they have @scheme['program] as the source field, or use -the @scheme[src] argument. Using a sequence of S-expressions (not +make sure that they have @racket['program] as the source field, or use +the @racket[src] argument. Using a sequence of S-expressions (not @tech{syntax objects}) for an input program leads to unreliable coverage results, since each expression may be assigned a single source location.} @@ -852,18 +852,18 @@ source location.} [unrestricted? boolean? #f]) any]{ -Calls the given @scheme[thunk] in the context of a sandboxed +Calls the given @racket[thunk] in the context of a sandboxed evaluator. The call is performed under the resource limits and evaluation handler that are used for evaluating expressions, unless -@scheme[unrestricted?] is specified as true. +@racket[unrestricted?] is specified as true. -This is usually similar to @scheme[(evaluator (list thunk))], except -that this relies on the common meaning of list expressions as function +This process is usually similar to @racket[(evaluator (list thunk))], except +that it relies on the common meaning of list expressions as function application (which is not true in all languages), and it relies on -MzScheme's @scheme[eval] forgiving a non-S-expression input. In +@racket[eval] allowing non-S-expression input. In addition, you can avoid some of the sandboxed restrictions by using your own permissions, for example, -@schemeblock[ +@racketblock[ (let ([guard (current-security-guard)]) (call-in-sandbox-context (lambda () @@ -878,10 +878,10 @@ your own permissions, for example, @defthing[gui? boolean?]{ -True if the @schememodname[racket/gui] module can be used, @scheme[#f] -otherwise; see @scheme[gui-available?]. +True if the @racketmodname[racket/gui] module can be used, @racket[#f] +otherwise; see @racket[gui-available?]. -Various aspects of the @schememodname[scheme/sandbox] library change +Various aspects of the @racketmodname[racket/sandbox] library change when the GUI library is available, such as using a new eventspace for each evaluator.} @@ -891,25 +891,25 @@ each evaluator.} [thunk (-> any)]) any]{ -Executes the given @scheme[thunk] with memory and time restrictions: -if execution consumes more than @scheme[mb] megabytes or more than -@scheme[sec] seconds, then the computation is aborted and the +Executes the given @racket[thunk] with memory and time restrictions: +if execution consumes more than @racket[mb] megabytes or more than +@racket[sec] seconds, then the computation is aborted and the @exnraise[exn:fail:resource]. Otherwise the result of the thunk is returned as usual (a value, multiple values, or an exception). Each -of the two limits can be @scheme[#f] to indicate the absence of a -limit. See also @scheme[custodian-limit-memory] for information on +of the two limits can be @racket[#f] to indicate the absence of a +limit. See also @racket[custodian-limit-memory] for information on memory limits. -Sandboxed evaluators use @scheme[call-with-limits], according to the -@scheme[sandbox-eval-limits] setting and uses of -@scheme[set-eval-limits]: each expression evaluation is protected from -timeouts and memory problems. Use @scheme[call-with-limits] directly +Sandboxed evaluators use @racket[call-with-limits], according to the +@racket[sandbox-eval-limits] setting and uses of +@racket[set-eval-limits]: each expression evaluation is protected from +timeouts and memory problems. Use @racket[call-with-limits] directly only to limit a whole testing session, instead of each expression.} @defform[(with-limits sec-expr mb-expr body ...)]{ -A macro version of @scheme[call-with-limits].} +A macro version of @racket[call-with-limits].} @defproc*[([(exn:fail:resource? [v any/c]) boolean?] @@ -917,8 +917,8 @@ A macro version of @scheme[call-with-limits].} (or/c 'time 'memory)])]{ A predicate and accessor for exceptions that are raised by -@scheme[call-with-limits]. The @scheme[resource] field holds a symbol, -either @scheme['time] or @scheme['memory].} +@racket[call-with-limits]. The @racket[resource] field holds a symbol, +either @racket['time] or @racket['memory].} @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/reference/startup.scrbl b/collects/scribblings/reference/startup.scrbl index b4c0091186..72880cda1c 100644 --- a/collects/scribblings/reference/startup.scrbl +++ b/collects/scribblings/reference/startup.scrbl @@ -9,29 +9,29 @@ @(define (PFlagFirst n) (as-index (PFlag n))) @(define (nontermstr s) - @elem{@schemevalfont{"}@nonterm[s]@schemevalfont{"}}) + @elem{@racketvalfont{"}@nonterm[s]@racketvalfont{"}}) @(define eventspace @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspace}) -@title[#:tag "running-sa"]{Running MzScheme or MrEd} +@title[#:tag "running-sa"]{Running Racket or GRacket} -The core PLT Scheme run-time system is available in two main variants: +The core Racket run-time system is available in two main variants: @itemize[ - @item{MzScheme, which provides the primitives libraries on which - @schememodname[racket/base] is implemented. Under Unix and Mac + @item{Racket, which provides the primitives libraries on which + @racketmodname[racket/base] is implemented. Under Unix and Mac OS X, the executable is called - @as-index{@exec{mzscheme}}. Under Windows, the executable is - called @as-index{@exec{MzScheme.exe}}.} + @as-index{@exec{racket}}. Under Windows, the executable is + called @as-index{@exec{Racket.exe}}.} - @item{MrEd, which extends @exec{mzscheme} with GUI primitives on - which @schememodname[racket/gui/base] is implemented. Under - Unix, the executable is called @as-index{@exec{mred}}. Under + @item{GRacket, which extends @exec{racket} with GUI primitives on + which @racketmodname[racket/gui/base] is implemented. Under + Unix, the executable is called @as-index{@exec{gracket}}. Under Windows, the executable is called - @as-index{@exec{MrEd.exe}}. Under Mac OS X, the @exec{mred} - script launches @as-index{@exec{MrEd.app}}.} + @as-index{@exec{GRacket.exe}}. Under Mac OS X, the @exec{gracket} + script launches @as-index{@exec{GRacket.app}}.} ] @@ -40,75 +40,75 @@ The core PLT Scheme run-time system is available in two main variants: @section[#:tag "init-actions"]{Initialization} On startup, the top-level environment contains no bindings---not even -@scheme[#%app] for function application. Primitive modules with names -that start with @schemeidfont{#%} are defined, but they are not meant +@racket[#%app] for function application. Primitive modules with names +that start with @racketidfont{#%} are defined, but they are not meant for direct use, and the set of such modules can change. For example, -the @indexed-scheme['#%kernel] module is eventually used to bootstrap -the implemetation of @schememodname[racket/base], and -@scheme['#%mred-kernel] is used for @schememodname[racket/gui/base]. +the @indexed-racket['#%kernel] module is eventually used to bootstrap +the implemetation of @racketmodname[racket/base], and +@racket['#%mred-kernel] is used for @racketmodname[racket/gui/base]. -The first action of MzScheme or MrEd is to initialize -@scheme[current-library-collection-paths] to the result of -@scheme[(find-library-collection-paths _pre-extras _extras)], where -@scheme[_pre-extras] is normally @scheme[null] and @scheme[_extras] +The first action of Racket or GRacket is to initialize +@racket[current-library-collection-paths] to the result of +@racket[(find-library-collection-paths _pre-extras _extras)], where +@racket[_pre-extras] is normally @racket[null] and @racket[_extras] are extra directory paths provided in order in the command line with -@Flag{S}/@DFlag{search}. An executable created from the MzScheme or -MrEd executable can embed paths used as @scheme[_pre-extras]. +@Flag{S}/@DFlag{search}. An executable created from the Racket or +GRacket executable can embed paths used as @racket[_pre-extras]. -MzScheme and MrEd next @scheme[require] @schememodname[racket/init] -and @schememodname[racket/gui/init], respectively, but only if the -command line does not specify a @scheme[require] flag +Racket and GRacket next @racket[require] @racketmodname[racket/init] +and @racketmodname[racket/gui/init], respectively, but only if the +command line does not specify a @racket[require] flag (@Flag{t}/@DFlag{require}, @Flag{l}/@DFlag{lib}, or -@Flag{u}/@DFlag{require-script}) before any @scheme[eval], -@scheme[load], or read-eval-print-loop flag (@Flag{e}/@DFlag{eval}, +@Flag{u}/@DFlag{require-script}) before any @racket[eval], +@racket[load], or read-eval-print-loop flag (@Flag{e}/@DFlag{eval}, @Flag{f}/@DFlag{load}, @Flag{r}/@DFlag{script}, @Flag{m}/@DFlag{main}, or @Flag{i}/@DFlag{repl}). The initialization library can be changed with the @Flag{I} @tech{configuration option}. The -@scheme['configure-runtime] property of the initialization library's +@racket['configure-runtime] property of the initialization library's language is used before the library is instantiated; see @secref["configure-runtime"]. After potentially loading the initialization module, expression -@scheme[eval]s, files @scheme[load]s, and module @scheme[require]s are +@racket[eval]s, files @racket[load]s, and module @racket[require]s are executed in the order that they are provided on the command line. If -any raises an uncaught exception, then the remaining @scheme[eval]s, -@scheme[load]s, and @scheme[require]s are skipped. If the first -@scheme[require] precedes any @scheme[eval] or @scheme[load] so that +any raises an uncaught exception, then the remaining @racket[eval]s, +@racket[load]s, and @racket[require]s are skipped. If the first +@racket[require] precedes any @racket[eval] or @racket[load] so that the initialization library is skipped, then the -@scheme['configure-runtime] property of the required module's library +@racket['configure-runtime] property of the required module's library language is used before the module is instantiated; see @secref["configure-runtime"]. After running all command-line expressions, files, and modules, -MzScheme or MrEd then starts a read-eval-print loop for interactive +Racket or GRacket then starts a read-eval-print loop for interactive evaluation if no command line flags are provided other than @tech{configuration options}. If any command-line argument is provided that is not a @tech{configuration option}, then the read-eval-print-loop is not started, unless the @Flag{i}/@DFlag{repl} flag is provided on the command line to specifically re-enable it. In addition, just before the command line -is started, MzScheme loads the file @scheme[(find-system-path -'init-file)] and MrEd loads the file -@scheme[(find-graphical-system-path 'init-file)] is loaded, unless the +is started, Racket loads the file @racket[(find-system-path +'init-file)] and GRacket loads the file +@racket[(find-graphical-system-path 'init-file)] is loaded, unless the @Flag{q}/@DFlag{no-init-file} flag is specified on the command line. -Finally, before MrEd exists, it waits for all frames to class, all +Finally, before GRacket exists, it waits for all frames to class, all timers to stop, @|etc| in the main @|eventspace| by evaluating -@scheme[(scheme 'yield)]. This waiting step can be suppressed with the +@racket[(racket 'yield)]. This waiting step can be suppressed with the @Flag{V}/@DFlag{no-yield} command-line flag. @; ---------------------------------------------------------------------- @section[#:tag "exit-status"]{Exit Status} -The default exit status for a MzScheme or MrEd process is non-zero if -an error occurs during a command-line @scheme[eval] (via @Flag{e}, -etc.), @scheme[load] (via @Flag{f}, @Flag{r}, etc.), or -@scheme[require] (via @Flag{-l}, @Flag{t}, etc.), but only when no +The default exit status for a Racket or GRacket process is non-zero if +an error occurs during a command-line @racket[eval] (via @Flag{e}, +etc.), @racket[load] (via @Flag{f}, @Flag{r}, etc.), or +@racket[require] (via @Flag{-l}, @Flag{t}, etc.), but only when no read-eval-print loop is started. Otherwise, the default exit status is -@scheme[0]. +@racket[0]. -In all cases, a call to @scheme[exit] (when the default @tech{exit +In all cases, a call to @racket[exit] (when the default @tech{exit handler} is in place) can end the process with a specific status value. @@ -120,7 +120,7 @@ value. @section[#:tag "mz-cmdline"]{Command Line} -The MzScheme and MrEd executables recognize the following command-line +The Racket and GRacket executables recognize the following command-line flags: @itemize[ @@ -130,35 +130,35 @@ flags: @itemize[ @item{@FlagFirst{e} @nonterm{expr} or @DFlagFirst{eval} - @nonterm{expr} : @scheme[eval]s @nonterm{expr}. The results of - the evaluation are printed via @scheme[current-print].} + @nonterm{expr} : @racket[eval]s @nonterm{expr}. The results of + the evaluation are printed via @racket[current-print].} @item{@FlagFirst{f} @nonterm{file} or @DFlagFirst{load} - @nonterm{file} : @scheme[load]s @nonterm{file}.} + @nonterm{file} : @racket[load]s @nonterm{file}.} @item{@FlagFirst{t} @nonterm{file} or @DFlagFirst{require} - @nonterm{file} : @scheme[require]s @nonterm{file}.} + @nonterm{file} : @racket[require]s @nonterm{file}.} @item{@FlagFirst{l} @nonterm{path} or @DFlagFirst{lib} - @nonterm{path} : @scheme[require]s @scheme[(lib + @nonterm{path} : @racket[require]s @racket[(lib @#,nontermstr{path})].} @item{@FlagFirst{p} @nonterm{package} : - @scheme[require]s @scheme[(planet @#,nontermstr{package})]. + @racket[require]s @racket[(planet @#,nontermstr{package})]. @margin-note{Despite its name, @DFlag{script} is not usually used for Unix scripts. See @guidesecref["scripts"] for more information on scripts.}} @item{@FlagFirst{r} @nonterm{file} or @DFlagFirst{script} - @nonterm{file} : @scheme[load]s @nonterm{file} as a + @nonterm{file} : @racket[load]s @nonterm{file} as a script. This flag is like @Flag{t} @nonterm{file} plus @Flag{N} @nonterm{file} to set the program name and @Flag{-} to cause all further command-line elements to be treated as non-flag arguments.} @item{@FlagFirst{u} @nonterm{file} or @DFlagFirst{require-script} - @nonterm{file} : @scheme[require]s @nonterm{file} as a script; + @nonterm{file} : @racket[require]s @nonterm{file} as a script; This flag is like @Flag{t} @nonterm{file} plus @Flag{N} @nonterm{file} to set the program name and @Flag{-} to cause all further command-line elements to be treated as non-flag @@ -167,22 +167,22 @@ flags: @item{@FlagFirst{k} @nonterm{n} @nonterm{m} : Loads code embedded in the executable from file position @nonterm{n} to @nonterm{m}. This option is normally embedded in a stand-alone - binary that also embeds Scheme code.} + binary that also embeds Racket code.} @item{@FlagFirst{m} or @DFlagFirst{main} : Evaluates a call to - @schemeidfont{main} as bound in the top-level environment. All + @racketidfont{main} as bound in the top-level environment. All of the command-line arguments that are not processed as options (i.e., the arguments put into - @scheme[current-command-line-arguments]) are passed as - arguments to @schemeidfont{main}. The results of the call are - printed via @scheme[current-print]. + @racket[current-command-line-arguments]) are passed as + arguments to @racketidfont{main}. The results of the call are + printed via @racket[current-print]. - The call to @schemeidfont{main} is constructed as an - expression @scheme[((unsyntax @schemeidfont{main}) _arg-str + The call to @racketidfont{main} is constructed as an + expression @racket[((unsyntax @racketidfont{main}) _arg-str ...)] where the lexical context of the expression gives - @schemeidfont{#%app} and @schemeidfont{#%datum} bindings as - @scheme[#%plain-app] and @scheme[#%datum], but the lexical - context of @schemeidfont{main} is the top-level environment.} + @racketidfont{#%app} and @racketidfont{#%datum} bindings as + @racket[#%plain-app] and @racket[#%datum], but the lexical + context of @racketidfont{main} is the top-level environment.} ]} @@ -191,26 +191,26 @@ flags: @itemize[ @item{@FlagFirst{i} or @DFlagFirst{repl} : Runs interactive read-eval-print - loop, using either @scheme[read-eval-print-loop] (MzScheme) or - @scheme[graphical-read-eval-print-loop] (MrEd) after showing - @scheme[(banner)] and loading @scheme[(find-system-path - 'init-file)]. For MrEd, supply the @Flag{z}/@DFlag{text-repl} - configuration option to use @scheme[read-eval-print-loop] - instead of @scheme[graphical-read-eval-print-loop].} + loop, using either @racket[read-eval-print-loop] (Racket) or + @racket[graphical-read-eval-print-loop] (GRacket) after showing + @racket[(banner)] and loading @racket[(find-system-path + 'init-file)]. For GRacket, supply the @Flag{z}/@DFlag{text-repl} + configuration option to use @racket[read-eval-print-loop] + instead of @racket[graphical-read-eval-print-loop].} @item{@FlagFirst{n} or @DFlagFirst{no-lib} : Skips requiring the - initialization library (i.e., @schememodname[racket/init] or - @schememodname[racket/gui/init], unless it is changed with the + initialization library (i.e., @racketmodname[racket/init] or + @racketmodname[racket/gui/init], unless it is changed with the @Flag{I} flag) when not otherwise disabled.} @item{@FlagFirst{v} or @DFlagFirst{version} : Shows - @scheme[(banner)].} + @racket[(banner)].} - @item{@FlagFirst{K} or @DFlagFirst{back} : MrEd, Mac OS X only; + @item{@FlagFirst{K} or @DFlagFirst{back} : GRacket, Mac OS X only; leave application in the background.} @item{@FlagFirst{V} @DFlagFirst{no-yield} : Skips final - @scheme[(yield 'wait)] action, which normally waits until all + @racket[(yield 'wait)] action, which normally waits until all frames are closed, @|etc| in the main @|eventspace| before exiting.} @@ -222,24 +222,24 @@ flags: @item{@FlagFirst{c} or @DFlagFirst{no-compiled} : Disables loading of compiled byte-code @filepath{.zo} files, by initializing - @scheme[current-compiled-file-paths] to @scheme[null].} + @racket[current-compiled-file-paths] to @racket[null].} @item{@FlagFirst{q} or @DFlagFirst{no-init-file} : Skips loading - @scheme[(find-system-path 'init-file)] for + @racket[(find-system-path 'init-file)] for @Flag{i}/@DFlag{repl}.} - @item{@FlagFirst{z} or @DFlagFirst{text-repl} : MrEd only; changes + @item{@FlagFirst{z} or @DFlagFirst{text-repl} : GRacket only; changes @Flag{i}/@DFlag{repl} to use - @scheme[textual-read-eval-print-loop] instead of - @scheme[graphical-read-eval-print-loop].} + @racket[textual-read-eval-print-loop] instead of + @racket[graphical-read-eval-print-loop].} - @item{@FlagFirst{I} @nonterm{path} : Sets @scheme[(lib - @#,nontermstr{path})] as the path to @scheme[require] to initialize + @item{@FlagFirst{I} @nonterm{path} : Sets @racket[(lib + @#,nontermstr{path})] as the path to @racket[require] to initialize the namespace, unless namespace initialization is disabled.} @item{@FlagFirst{X} @nonterm{dir} or @DFlagFirst{collects} @nonterm{dir} : Sets @nonterm{dir} as the path to the main - collection of libraries by making @scheme[(find-system-path + collection of libraries by making @racket[(find-system-path 'collects-dir)] produce @nonterm{dir}.} @item{@FlagFirst{S} @nonterm{dir} or @DFlagFirst{search} @@ -251,21 +251,21 @@ flags: @item{@FlagFirst{U} or @DFlagFirst{no-user-path} : Omits user-specific paths in the search for collections, C libraries, etc. by initializing the - @scheme[use-user-specific-search-paths] parameter to - @scheme[#f].} + @racket[use-user-specific-search-paths] parameter to + @racket[#f].} @item{@FlagFirst{N} @nonterm{file} or @DFlagFirst{name} @nonterm{file} : sets the name of the executable as reported - by @scheme[(find-system-path 'run-file)] to + by @racket[(find-system-path 'run-file)] to @nonterm{file}.} @item{@FlagFirst{j} or @DFlagFirst{no-jit} : Disables the native-code just-in-time compiler by setting the - @scheme[eval-jit-enabled] parameter to @scheme[#f].} + @racket[eval-jit-enabled] parameter to @racket[#f].} @item{@FlagFirst{d} or @DFlagFirst{no-delay} : Disables on-demand parsing of compiled code and syntax objects by setting the - @scheme[read-on-demand-source] parameter to @scheme[#f].} + @racket[read-on-demand-source] parameter to @racket[#f].} @item{@FlagFirst{b} or @DFlagFirst{binary} : Requests binary mode, instead of text mode, for the process's input, out, and error @@ -310,7 +310,7 @@ If no command-line arguments are supplied other than @tech{configuration options}, then the @Flag{i}/@DFlag{repl} flag is effectively added. -For MrEd under X11, the follow flags are recognized when they appear +For GRacket under X11, the follow flags are recognized when they appear at the beginning of the command line, and they count as configuration options (i.e., they do not disable the read-eval-print loop or prevent the insertion of @Flag{u}/@DFlag{require-script}): @@ -334,15 +334,15 @@ the insertion of @Flag{u}/@DFlag{require-script}): @Flag{synchronous} and @Flag{xrm} flags behave in the usual way.} - @item{@FlagFirst{singleInstance} : If an existing MrEd is already + @item{@FlagFirst{singleInstance} : If an existing GRacket is already running on the same X11 display, if it was started on a machine with the same hostname, and if it was started with the - same name as reported by @scheme[(find-system-path + same name as reported by @racket[(find-system-path 'run-file)]---possibly set with the @Flag{N}/@DFlag{name} command-line argument---then all non-option command-line arguments are treated as filenames and sent to the existing - MrEd instance via the application file handler (see - @scheme[application-file-handler]).} + GRacket instance via the application file handler (see + @racket[application-file-handler]).} ] @@ -368,7 +368,7 @@ switches in the same collapsed set, it is implicitly moved to the end of the collapsed set. Extra arguments following the last option are available from the -@indexed-scheme[current-command-line-arguments] parameter. +@indexed-racket[current-command-line-arguments] parameter. @; ---------------------------------------------------------------------- @@ -381,31 +381,31 @@ language specifies run-time configuration by @itemlist[ - @item{attaching a @scheme['module-language] @tech{syntax property} to - the module as read from its source (see @scheme[module] and - @scheme[module-compiled-language-info]);} + @item{attaching a @racket['module-language] @tech{syntax property} to + the module as read from its source (see @racket[module] and + @racket[module-compiled-language-info]);} - @item{having the function indicated by the @scheme['module-language] + @item{having the function indicated by the @racket['module-language] @tech{syntax property} recognize the - @scheme['configure-runtime] key, for which it returns a list of - vectors; each vector must have the form @scheme[(vector _mp - _name _val)] where @scheme[_mp] is a @tech{module path}, - @scheme[_name] is a symbol, and @scheme[_val] is an arbitrary + @racket['configure-runtime] key, for which it returns a list of + vectors; each vector must have the form @racket[(vector _mp + _name _val)] where @racket[_mp] is a @tech{module path}, + @racket[_name] is a symbol, and @racket[_val] is an arbitrary value; and} - @item{having each function called as @scheme[((dynamic-require _mp + @item{having each function called as @racket[((dynamic-require _mp _name) _val)] configure the run-time environment, typically by - setting parameters such as @scheme[current-print].} + setting parameters such as @racket[current-print].} ] -The @schememodname[racket/base] and @schememodname[scheme] languages +The @racketmodname[racket/base] and @racketmodname[racket] languages do not currently specify a run-time configuration action. -A @scheme['configure-runtime] query returns a list of vectors, instead +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 executable; see @secref[#:doc '(lib "scribblings/mzc/mzc.scrbl") "exe"]. For information on defining a new @hash-lang[] language, see -@schememodname[syntax/module-reader]. +@racketmodname[syntax/module-reader]. diff --git a/collects/scribblings/reference/string-output.scrbl b/collects/scribblings/reference/string-output.scrbl index 4cf4c7e2a8..b69599725b 100644 --- a/collects/scribblings/reference/string-output.scrbl +++ b/collects/scribblings/reference/string-output.scrbl @@ -6,19 +6,19 @@ @defproc[(write-char [char character?][out output-port? (current-output-port)]) void?]{ -Writes a single character to @scheme[out]; more precisely, the bytes -that are the UTF-8 encoding of @scheme[char] are written to -@scheme[out].} +Writes a single character to @racket[out]; more precisely, the bytes +that are the UTF-8 encoding of @racket[char] are written to +@racket[out].} @defproc[(write-byte [byte any/c][out output-port? (current-output-port)]) void?]{ -Writes a single byte to @scheme[out].} +Writes a single byte to @racket[out].} @defproc[(newline [out output-port? (current-output-port)]) void?]{ -The same as @scheme[(write-char #\newline out)].} +The same as @racket[(write-char #\newline out)].} @defproc[(write-string [str string?] [out output-port? (current-output-port)] @@ -26,14 +26,14 @@ The same as @scheme[(write-char #\newline out)].} [end-pos exact-nonnegative-integer? (string-length str)]) exact-nonnegative-integer?]{ -Writes characters to @scheme[out] from @scheme[str] starting from -index @scheme[start-pos] (inclusive) up to @scheme[end-pos] -(exclusive). Like @scheme[substring], the @exnraise[exn:fail:contract] -if @scheme[start-pos] or @scheme[end-pos] is out-of-range for -@scheme[str]. +Writes characters to @racket[out] from @racket[str] starting from +index @racket[start-pos] (inclusive) up to @racket[end-pos] +(exclusive). Like @racket[substring], the @exnraise[exn:fail:contract] +if @racket[start-pos] or @racket[end-pos] is out-of-range for +@racket[str]. -The result is the number of characters written to @scheme[out], which -is always @scheme[(- end-pos start-pos)].} +The result is the number of characters written to @racket[out], which +is always @racket[(- end-pos start-pos)].} @defproc[(write-bytes [bstr bytes?] [out output-port? (current-output-port)] @@ -41,7 +41,7 @@ is always @scheme[(- end-pos start-pos)].} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) exact-nonnegative-integer?]{ -Like @scheme[write-string], but writes bytes instead of characters.} +Like @racket[write-string], but writes bytes instead of characters.} @defproc[(write-bytes-avail [bstr bytes?] [out output-port? (current-output-port)] @@ -49,17 +49,17 @@ Like @scheme[write-string], but writes bytes instead of characters.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) exact-nonnegative-integer?]{ -Like @scheme[write-bytes], but returns without blocking after writing +Like @racket[write-bytes], but returns without blocking after writing as many bytes as it can immediately flush. It blocks only if no bytes can be flushed immediately. The result is the number of bytes written -and flushed to @scheme[out]; if @scheme[start-pos] is the same as -@scheme[end-pos], then the result can be @scheme[0] (indicating a +and flushed to @racket[out]; if @racket[start-pos] is the same as +@racket[end-pos], then the result can be @racket[0] (indicating a successful flush of any buffered data), otherwise the result is at -least @scheme[1] but possibly less than @scheme[(- end-pos +least @racket[1] but possibly less than @racket[(- end-pos start-pos)]. -The @scheme[write-bytes-avail] procedure never drops bytes; if -@scheme[write-bytes-avail] successfully writes some bytes and then +The @racket[write-bytes-avail] procedure never drops bytes; if +@racket[write-bytes-avail] successfully writes some bytes and then encounters an error, it suppresses the error and returns the number of written bytes. (The error will be triggered by future writes.) If an error is encountered before any bytes have been written, an exception @@ -71,9 +71,9 @@ is raised.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) (or/c exact-nonnegative-integer? #f)]{ -Like @scheme[write-bytes-avail], but never blocks, returns @scheme[#f] +Like @racket[write-bytes-avail], but never blocks, returns @racket[#f] if the port contains buffered data that cannot be written immediately, -and returns @scheme[0] if the port's internal buffer (if any) is +and returns @racket[0] if the port's internal buffer (if any) is flushed but no additional bytes can be written immediately.} @defproc[(write-bytes-avail/enable-break [bstr bytes?] @@ -82,26 +82,26 @@ flushed but no additional bytes can be written immediately.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) exact-nonnegative-integer?]{ -Like @scheme[write-bytes-avail], except that breaks are enabled during +Like @racket[write-bytes-avail], except that breaks are enabled during the write. The procedure provides a guarantee about the interaction of writing and breaks: if breaking is disabled when -@scheme[write-bytes-avail/enable-break] is called, and if the -@scheme[exn:break] exception is raised as a result of the call, then -no bytes will have been written to @scheme[out]. See also +@racket[write-bytes-avail/enable-break] is called, and if the +@racket[exn:break] exception is raised as a result of the call, then +no bytes will have been written to @racket[out]. See also @secref["breakhandler"].} @defproc[(write-special [v any/c][out output-port? (current-output-port)]) boolean?]{ -Writes @scheme[v] directly to @scheme[out] if the port supports -special writes, or raises @scheme[exn:fail:contract] if the port does -not support special write. The result is always @scheme[#t], +Writes @racket[v] directly to @racket[out] if the port supports +special writes, or raises @racket[exn:fail:contract] if the port does +not support special write. The result is always @racket[#t], indicating that the write succeeded.} @defproc[(write-special-avail* [v any/c][out output-port? (current-output-port)]) boolean?]{ -Like @scheme[write-special], but without blocking. If @scheme[v] -cannot be written immediately, the result is @scheme[#f] without -writing @scheme[v], otherwise the result is @scheme[#t] and @scheme[v] +Like @racket[write-special], but without blocking. If @racket[v] +cannot be written immediately, the result is @racket[#f] without +writing @racket[v], otherwise the result is @racket[#t] and @racket[v] is written.} @defproc[(write-bytes-avail-evt [bstr bytes?] @@ -110,45 +110,45 @@ is written.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) evt?]{ -Similar to @scheme[write-bytes-avail], but instead of writing bytes +Similar to @racket[write-bytes-avail], but instead of writing bytes immediately, it returns a synchronizable event (see -@secref["sync"]). The @scheme[out] must support atomic writes, as -indicated by @scheme[port-writes-atomic?]. +@secref["sync"]). The @racket[out] must support atomic writes, as +indicated by @racket[port-writes-atomic?]. -Synchronizing on the object starts a write from @scheme[bstr], and the +Synchronizing on the object starts a write from @racket[bstr], and the event becomes ready when bytes are written (unbuffered) to the -port. If @scheme[start-pos] and @scheme[end-pos] are the same, then -the synchronization result is @scheme[0] when the port's internal +port. If @racket[start-pos] and @racket[end-pos] are the same, then +the synchronization result is @racket[0] when the port's internal buffer (if any) is flushed, otherwise the result is a positive exact integer. If the event is not selected in a synchronization, then no -bytes will have been written to @scheme[out].} +bytes will have been written to @racket[out].} @defproc[(write-special-evt [v any/c][out output-port? (current-output-port)]) evt?]{ -Similar to @scheme[write-special], but instead of writing the special +Similar to @racket[write-special], but instead of writing the special value immediately, it returns a synchronizable event (see -@secref["sync"]). The @scheme[out] must support atomic writes, as -indicated by @scheme[port-writes-atomic?]. +@secref["sync"]). The @racket[out] must support atomic writes, as +indicated by @racket[port-writes-atomic?]. Synchronizing on the object starts a write of the special value, and the event becomes ready when the value is written (unbuffered) to the port. If the event is not selected in a synchronization, then no value -will have been written to @scheme[out].} +will have been written to @racket[out].} @defproc[(port-writes-atomic? [out output-port?]) boolean?]{ -Returns @scheme[#t] if @scheme[write-bytes-avail/enable-break] can +Returns @racket[#t] if @racket[write-bytes-avail/enable-break] can provide an exclusive-or guarantee (break or write, but not both) for -@scheme[out], and if the port can be used with procedures like -@scheme[write-bytes-avail-evt]. Scheme's file-stream ports, pipes, +@racket[out], and if the port can be used with procedures like +@racket[write-bytes-avail-evt]. Racket's file-stream ports, pipes, string ports, and TCP ports all support atomic writes; ports created -with @scheme[make-output-port] (see @secref["customport"]) may +with @racket[make-output-port] (see @secref["customport"]) may support atomic writes.} @defproc[(port-writes-special? [out output-port?]) boolean?]{ -Returns @scheme[#t] if procedures like @scheme[write-special] can -write arbitrary values to the port. Scheme's file-stream ports, +Returns @racket[#t] if procedures like @racket[write-special] can +write arbitrary values to the port. Racket's file-stream ports, pipes, string ports, and TCP ports all reject special values, but -ports created with @scheme[make-output-port] (see +ports created with @racket[make-output-port] (see @secref["customport"]) may support them.} diff --git a/collects/scribblings/reference/stx-props.scrbl b/collects/scribblings/reference/stx-props.scrbl index d2dbc68450..a3b239db4c 100644 --- a/collects/scribblings/reference/stx-props.scrbl +++ b/collects/scribblings/reference/stx-props.scrbl @@ -5,95 +5,95 @@ Every syntax object has an associated @deftech{syntax property} list, which can be queried or extended with -@scheme[syntax-property]. Properties are not preserved for a -@scheme[syntax-quoted] syntax object in a compiled form that is +@racket[syntax-property]. Properties are not preserved for a +@racket[syntax-quoted] syntax object in a compiled form that is marshaled to a byte string. -In @scheme[read-syntax], the reader attaches a @scheme['paren-shape] +In @racket[read-syntax], the reader attaches a @racket['paren-shape] property to any pair or vector syntax object generated from parsing a pair @litchar{[} and @litchar{]} or @litchar["{"] and -@litchar["}"]; the property value is @scheme[#\[] in the former case, -and @scheme[#\{] in the latter case. The @scheme[syntax] form copies -any @scheme['paren-shape] property from the source of a template to +@litchar["}"]; the property value is @racket[#\[] in the former case, +and @racket[#\{] in the latter case. The @racket[syntax] form copies +any @racket['paren-shape] property from the source of a template to corresponding generated syntax. Both the syntax input to a transformer and the syntax result of a transformer may have associated properties. The two sets of properties are merged by the syntax expander: each property in the original and not present in the result is copied to the result, and the values of -properties present in both are combined with @scheme[cons] (result +properties present in both are combined with @racket[cons] (result value first, original value second). Before performing the merge, however, the syntax expander automatically adds a property to the original syntax object using the -key @indexed-scheme['origin]. If the source syntax has no -@scheme['origin] property, it is set to the empty list. Then, still +key @indexed-racket['origin]. If the source syntax has no +@racket['origin] property, it is set to the empty list. Then, still before the merge, the identifier that triggered the macro expansion -(as syntax) is @scheme[cons]ed onto the @scheme['origin] -property so far. The @scheme['origin] property thus records (in +(as syntax) is @racket[cons]ed onto the @racket['origin] +property so far. The @racket['origin] property thus records (in reverse order) the sequence of macro expansions that produced an -expanded expression. Usually, the @scheme['origin] value is an +expanded expression. Usually, the @racket['origin] value is an immutable list of identifiers. However, a transformer might return syntax that has already been expanded, in which case an -@scheme['origin] list can contain other lists after a merge. The -@scheme[syntax-track-origin] procedure implements this tracking. +@racket['origin] list can contain other lists after a merge. The +@racket[syntax-track-origin] procedure implements this tracking. -Besides @scheme['origin] tracking for general macro expansion, -MzScheme adds properties to expanded syntax (often using -@scheme[syntax-track-origin]) to record additional expansion details: +Besides @racket['origin] tracking for general macro expansion, +Racket adds properties to expanded syntax (often using +@racket[syntax-track-origin]) to record additional expansion details: @itemize[ - @item{When a @scheme[begin] form is spliced into a sequence with + @item{When a @racket[begin] form is spliced into a sequence with internal definitions (see @secref["intdef-body"]), - @scheme[syntax-track-origin] is applied to every spliced element from - the @scheme[begin] body. The second argument to - @scheme[syntax-track-origin] is the @scheme[begin] form, and the - third argument is the @scheme[begin] keyword (extracted from the + @racket[syntax-track-origin] is applied to every spliced element from + the @racket[begin] body. The second argument to + @racket[syntax-track-origin] is the @racket[begin] form, and the + third argument is the @racket[begin] keyword (extracted from the spliced form).} - @item{When an internal @scheme[define-values] or - @scheme[define-syntaxes] form is converted into a - @scheme[letrec-syntaxes+values] form (see @secref["intdef-body"]), - @scheme[syntax-track-origin] is applied to each generated binding - clause. The second argument to @scheme[syntax-track-origin] is the - converted form, and the third argument is the @scheme[define-values] - or @scheme[define-syntaxes] keyword form the converted form.} + @item{When an internal @racket[define-values] or + @racket[define-syntaxes] form is converted into a + @racket[letrec-syntaxes+values] form (see @secref["intdef-body"]), + @racket[syntax-track-origin] is applied to each generated binding + clause. The second argument to @racket[syntax-track-origin] is the + converted form, and the third argument is the @racket[define-values] + or @racket[define-syntaxes] keyword form the converted form.} - @item{When a @scheme[letrec-syntaxes+values] expression is fully + @item{When a @racket[letrec-syntaxes+values] expression is fully expanded, syntax bindings disappear, and the result is either a - @scheme[letrec-values] form (if the unexpanded form contained + @racket[letrec-values] form (if the unexpanded form contained non-syntax bindings), or only the body of the - @scheme[letrec-syntaxes+values] form (wrapped with @scheme[begin] if + @racket[letrec-syntaxes+values] form (wrapped with @racket[begin] if the body contained multiple expressions). To record the disappeared syntax bindings, a property is added to the expansion result: an immutable list of identifiers from the disappeared bindings, as a - @indexed-scheme['disappeared-binding] property.} + @indexed-racket['disappeared-binding] property.} - @item{When a subtyping @scheme[define-struct] form is expanded, the + @item{When a subtyping @racket[define-struct] form is expanded, the identifier used to reference the base type does not appear in the - expansion. Therefore, the @scheme[define-struct] transformer adds the + expansion. Therefore, the @racket[define-struct] transformer adds the identifier to the expansion result as a - @indexed-scheme['disappeared-use] property.} + @indexed-racket['disappeared-use] property.} @item{When a reference to an unexported or protected identifier from a module is discovered (and the reference is certified; see - @secref["stxcerts"]), the @indexed-scheme['protected] property is - added to the identifier with a @scheme[#t] value.} + @secref["stxcerts"]), the @indexed-racket['protected] property is + added to the identifier with a @racket[#t] value.} - @item{When or @scheme[read-syntax] or @scheme[read-honu-syntax] + @item{When or @racket[read-syntax] or @racket[read-honu-syntax] generates a syntax object, it attaches a property to the object (using a private key) to mark the object as originating from a - read. The @scheme[syntax-original?] predicate looks for the property + read. The @racket[syntax-original?] predicate looks for the property to recognize such syntax objects. (See @secref["stxops"] for more information.)} ] See @secref["modinfo"] for information about properties generated -by the expansion of a module declaration. See @scheme[lambda] and +by the expansion of a module declaration. See @racket[lambda] and @secref["infernames"] for information about properties recognized -when compiling a procedure. See @scheme[current-compile] for +when compiling a procedure. See @racket[current-compile] for information on properties and byte codes. @;------------------------------------------------------------------------ @@ -102,56 +102,56 @@ information on properties and byte codes. syntax?] [(syntax-property [stx syntax?][key any/c]) any])]{ -The three-argument form extends @scheme[stx] by associating an -arbitrary property value @scheme[v] with the key @scheme[key]; the -result is a new syntax object with the association (while @scheme[stx] +The three-argument form extends @racket[stx] by associating an +arbitrary property value @racket[v] with the key @racket[key]; the +result is a new syntax object with the association (while @racket[stx] itself is unchanged). The two-argument form returns an arbitrary property value associated -to @scheme[stx] with the key @scheme[key], or @scheme[#f] if no value -is associated to @scheme[stx] for @scheme[key].} +to @racket[stx] with the key @racket[key], or @racket[#f] if no value +is associated to @racket[stx] for @racket[key].} @defproc[(syntax-property-symbol-keys [stx syntax?]) list?]{ Returns a list of all symbols that as keys have associated properties -in @scheme[stx]. @tech{Uninterned} symbols (see @secref["symbols"]) +in @racket[stx]. @tech{Uninterned} symbols (see @secref["symbols"]) are not included in the result list.} @defproc[(syntax-track-origin [new-stx syntax?][orig-stx syntax?][id-stx syntax?]) any]{ -Adds properties to @scheme[new-stx] in the same way that macro +Adds properties to @racket[new-stx] in the same way that macro expansion adds properties to a transformer result. In particular, it -merges the properties of @scheme[orig-stx] into @scheme[new-stx], -first adding @scheme[id-stx] as an @scheme['origin] property, and it +merges the properties of @racket[orig-stx] into @racket[new-stx], +first adding @racket[id-stx] as an @racket['origin] property, and it returns the property-extended syntax object. Use the -@scheme[syntax-track-origin] procedure in a macro transformer that -discards syntax (corresponding to @scheme[orig-stx] with a keyword -@scheme[id-stx]) leaving some other syntax in its place (corresponding -to @scheme[new-stx]). +@racket[syntax-track-origin] procedure in a macro transformer that +discards syntax (corresponding to @racket[orig-stx] with a keyword +@racket[id-stx]) leaving some other syntax in its place (corresponding +to @racket[new-stx]). For example, the expression -@schemeblock[ +@racketblock[ (or x y) ] expands to -@schemeblock[ +@racketblock[ (let ((or-part x)) (if or-part or-part (or y))) ] which, in turn, expands to -@schemeblock[ +@racketblock[ (let-values ([(or-part) x]) (if or-part or-part y)) ] The syntax object for the final expression will have an -@scheme['origin] property whose value is @scheme[(list (quote-syntax +@racket['origin] property whose value is @racket[(list (quote-syntax let) (quote-syntax or))].} diff --git a/collects/scribblings/reference/subprocess.scrbl b/collects/scribblings/reference/subprocess.scrbl index b8b083ad3e..7b3f17b874 100644 --- a/collects/scribblings/reference/subprocess.scrbl +++ b/collects/scribblings/reference/subprocess.scrbl @@ -25,55 +25,55 @@ (or/c (and/c input-port? file-stream-port?) #f))])]{ Creates a new process in the underlying operating system to execute -@scheme[command] asynchronously. See also @scheme[system] and -@scheme[process] from @schememodname[racket/system]. +@racket[command] asynchronously. See also @racket[system] and +@racket[process] from @racketmodname[racket/system]. -The @scheme[command] argument is a path to a program executable, and -the @scheme[arg]s are command-line arguments for the program. Under +The @racket[command] argument is a path to a program executable, and +the @racket[arg]s are command-line arguments for the program. Under Unix and Mac OS X, command-line arguments are passed as byte strings using the current locale's encoding (see @secref["encodings"]). -Under Windows, the first @scheme[arg] can be replaced with -@indexed-scheme['exact], which triggers a Windows-specific behavior: -the sole @scheme[arg] is used exactly as the command-line for the +Under Windows, the first @racket[arg] can be replaced with +@indexed-racket['exact], which triggers a Windows-specific behavior: +the sole @racket[arg] is used exactly as the command-line for the subprocess. Otherwise, under Windows, a command-line string is -constructed from @scheme[command] and @scheme[arg] so that a typical +constructed from @racket[command] and @racket[arg] so that a typical Windows console application can parse it back to an array of -arguments. If @scheme['exact] is provided on a non-Windows platform, +arguments. If @racket['exact] is provided on a non-Windows platform, the @exnraise[exn:fail:contract]. @margin-note{For information on the Windows command-line conventions, search for ``command line parsing'' at @tt{http://msdn.microsoft.com/}.} -Unless it is @scheme[#f], @scheme[stdout] is used for the launched -process's standard output, @scheme[stdin] is used for the process's -standard input, and @scheme[stderr] is used for the process's standard +Unless it is @racket[#f], @racket[stdout] is used for the launched +process's standard output, @racket[stdin] is used for the process's +standard input, and @racket[stderr] is used for the process's standard error. All provided ports must be file-stream ports. Any of the ports -can be @scheme[#f], in which case a system pipe is created and -returned by @scheme[subprocess]. For each port that is provided, no -pipe is created and the corresponding returned value is @scheme[#f]. +can be @racket[#f], in which case a system pipe is created and +returned by @racket[subprocess]. For each port that is provided, no +pipe is created and the corresponding returned value is @racket[#f]. -The @scheme[subprocess] procedure returns four values: +The @racket[subprocess] procedure returns four values: @itemize[ @item{a subprocess value representing the created process;} @item{an input port piped from the process's standard output, or - @scheme[#f] if @scheme[stdout-output-port] was a port;} + @racket[#f] if @racket[stdout-output-port] was a port;} @item{an output port piped to the process standard input, or - @scheme[#f] if @scheme[stdin-input-port] was a port;} + @racket[#f] if @racket[stdin-input-port] was a port;} @item{an input port piped from the process's standard error, or - @scheme[#f] if @scheme[stderr-output-port] was a port.} + @racket[#f] if @racket[stderr-output-port] was a port.} ] -@bold{Important:} All ports returned from @scheme[subprocess] must be -explicitly closed with @scheme[close-input-port] or -@scheme[close-output-port]. +@bold{Important:} All ports returned from @racket[subprocess] must be +explicitly closed with @racket[close-input-port] or +@racket[close-output-port]. The returned ports are @tech{file-stream ports} (see @secref["file-ports"]), and they are placed into the management of @@ -85,44 +85,44 @@ communication.} @defproc[(subprocess-wait [subproc subprocess?]) void?]{ -Blocks until the process represented by @scheme[subproc] -terminates. The @scheme[subproc] value also can be used with -@scheme[sync] and @scheme[sync/timeout].} +Blocks until the process represented by @racket[subproc] +terminates. The @racket[subproc] value also can be used with +@racket[sync] and @racket[sync/timeout].} @defproc[(subprocess-status [subproc subprocess?]) (or/c 'running exact-nonnegative-integer?)]{ -Returns @indexed-scheme['running] if the process represented by -@scheme[subproc] is still running, or its exit code otherwise. The -exit code is an exact integer, and @scheme[0] typically indicates +Returns @indexed-racket['running] if the process represented by +@racket[subproc] is still running, or its exit code otherwise. The +exit code is an exact integer, and @racket[0] typically indicates success. If the process terminated due to a fault or signal, the exit code is non-zero.} @defproc[(subprocess-kill [subproc subprocess?][force? any/c]) void?]{ -Terminates the subprocess represented by @scheme[subproc] if -@scheme[force?] is true and if the process still running. If an error +Terminates the subprocess represented by @racket[subproc] if +@racket[force?] is true and if the process still running. If an error occurs during termination, the @exnraise[exn:fail]. -If @scheme[force?] is @scheme[#f] under @|AllUnix|, the subprocess is +If @racket[force?] is @racket[#f] under @|AllUnix|, the subprocess is sent an interrupt signal instead of a kill signal (and the subprocess might handle the signal without terminating). Under Windows, no action -is taken when @scheme[force?] is @scheme[#f].} +is taken when @racket[force?] is @racket[#f].} @defproc[(subprocess-pid [subproce subprocess?]) exact-nonnegative-integer?]{ Returns the operating system's numerical ID (if any) for the process -represented by @scheme[subproc], valid only as long as the process is +represented by @racket[subproc], valid only as long as the process is running.} @defproc[(subprocess? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a subprocess value, @scheme[#f] +Returns @racket[#t] if @racket[v] is a subprocess value, @racket[#f] otherwise.} @@ -130,96 +130,96 @@ otherwise.} [target string?][parameters string?][dir path-string?][show-mode symbol?]) #f] -@index['("ShellExecute")]{Performs} the action specified by @scheme[verb] -on @scheme[target] in Windows. For platforms other than Windows, the +@index['("ShellExecute")]{Performs} the action specified by @racket[verb] +on @racket[target] in Windows. For platforms other than Windows, the @exnraise[exn:fail:unsupported]. For example, -@schemeblock[ -(shell-execute #f "http://www.plt-scheme.org" "" +@racketblock[ +(shell-execute #f "http://www.racket-lang.org" "" (current-directory) 'sw_shownormal) ] -Opens the PLT Scheme home page in a browser window. +Opens the Racket home page in a browser window. -The @scheme[verb] can be @scheme[#f], in which case the operating -system will use a default verb. Common verbs include @scheme["open"], -@scheme["edit"], @scheme["find"], @scheme["explore"], and -@scheme["print"]. +The @racket[verb] can be @racket[#f], in which case the operating +system will use a default verb. Common verbs include @racket["open"], +@racket["edit"], @racket["find"], @racket["explore"], and +@racket["print"]. -The @scheme[target] is the target for the action, usually a filename +The @racket[target] is the target for the action, usually a filename path. The file could be executable, or it could be a file with a recognized extension that can be handled by an installed application. -The @scheme[parameters] argument is passed on to the system to perform +The @racket[parameters] argument is passed on to the system to perform the action. For example, in the case of opening an executable, the -@scheme[parameters] is used as the command line (after the executable +@racket[parameters] is used as the command line (after the executable name). -The @scheme[dir] is used as the current directory when performing the +The @racket[dir] is used as the current directory when performing the action. -The @scheme[show-mode] sets the display mode for a Window affected by +The @racket[show-mode] sets the display mode for a Window affected by the action. It must be one of the following symbols; the description of each symbol's meaning is taken from the Windows API documentation. @itemize[ - @item{@indexed-scheme['sw_hide] or @indexed-scheme['SW_HIDE] --- + @item{@indexed-racket['sw_hide] or @indexed-racket['SW_HIDE] --- Hides the window and activates another window.} - @item{@indexed-scheme['sw_maximize] or @indexed-scheme['SW_MAXIMIZE] + @item{@indexed-racket['sw_maximize] or @indexed-racket['SW_MAXIMIZE] --- Maximizes the window.} - @item{@indexed-scheme['sw_minimize] or @indexed-scheme['SW_MINIMIZE] + @item{@indexed-racket['sw_minimize] or @indexed-racket['SW_MINIMIZE] --- Minimizes the window and activates the next top-level window in the z-order.} - @item{@indexed-scheme['sw_restore] or @indexed-scheme['SW_RESTORE] + @item{@indexed-racket['sw_restore] or @indexed-racket['SW_RESTORE] --- Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position.} - @item{@indexed-scheme['sw_show] or @indexed-scheme['SW_SHOW] --- + @item{@indexed-racket['sw_show] or @indexed-racket['SW_SHOW] --- Activates the window and displays it in its current size and position.} - @item{@indexed-scheme['sw_showdefault] or - @indexed-scheme['SW_SHOWDEFAULT] --- Uses a default.} + @item{@indexed-racket['sw_showdefault] or + @indexed-racket['SW_SHOWDEFAULT] --- Uses a default.} - @item{@indexed-scheme['sw_showmaximized] or - @indexed-scheme['SW_SHOWMAXIMIZED] --- Activates the window and + @item{@indexed-racket['sw_showmaximized] or + @indexed-racket['SW_SHOWMAXIMIZED] --- Activates the window and displays it as a maximized window.} - @item{@indexed-scheme['sw_showminimized] or - @indexed-scheme['SW_SHOWMINIMIZED] --- Activates the window and + @item{@indexed-racket['sw_showminimized] or + @indexed-racket['SW_SHOWMINIMIZED] --- Activates the window and displays it as a minimized window.} - @item{@indexed-scheme['sw_showminnoactive] or - @indexed-scheme['SW_SHOWMINNOACTIVE] --- Displays the window as a + @item{@indexed-racket['sw_showminnoactive] or + @indexed-racket['SW_SHOWMINNOACTIVE] --- Displays the window as a minimized window. The active window remains active.} - @item{@indexed-scheme['sw_showna] or @indexed-scheme['SW_SHOWNA] --- + @item{@indexed-racket['sw_showna] or @indexed-racket['SW_SHOWNA] --- Displays the window in its current state. The active window remains active.} - @item{@indexed-scheme['sw_shownoactivate] or - @indexed-scheme['SW_SHOWNOACTIVATE] --- Displays a window in its most + @item{@indexed-racket['sw_shownoactivate] or + @indexed-racket['SW_SHOWNOACTIVATE] --- Displays a window in its most recent size and position. The active window remains active.} - @item{@indexed-scheme['sw_shownormal] or - @indexed-scheme['SW_SHOWNORMAL] --- Activates and displays a + @item{@indexed-racket['sw_shownormal] or + @indexed-racket['SW_SHOWNORMAL] --- Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position.} ] If the action fails, the @exnraise[exn:fail]. If the action succeeds, -the result is @scheme[#f]. +the result is @racket[#f]. -In future versions of Scheme, the result may be a subprocess value if +In future versions of Racket, the result may be a subprocess value if the operating system did returns a process handle (but if a subprocess -value is returned, its process ID will be @scheme[0] instead of the +value is returned, its process ID will be @racket[0] instead of the real process ID). @; ---------------------------------------------------------------------- @@ -231,37 +231,37 @@ real process ID). @defproc[(system [command string?]) boolean?]{ Executes a Unix, Mac OS X, or Windows shell command synchronously -(i.e., the call to @scheme[system] does not return until the -subprocess has ended). The @scheme[command] argument is a string +(i.e., the call to @racket[system] does not return until the +subprocess has ended). The @racket[command] argument is a string containing no nul characters. If the command succeeds, the return -value is @scheme[#t], @scheme[#f] otherwise.} +value is @racket[#t], @racket[#f] otherwise.} @defproc*[([(system* [command path-string?][arg string?] ...) boolean?] [(system* [command path-string?][exact 'exact][arg string?]) boolean?])]{ -Like @scheme[system], except that @scheme[command] is a filename that +Like @racket[system], except that @racket[command] is a filename that is executed directly (instead of through a shell command), and the -@scheme[arg]s are the arguments. The executed file is passed the +@racket[arg]s are the arguments. The executed file is passed the specified string arguments (which must contain no nul characters). -Under Windows, the first argument after @scheme[command] can be -@scheme['exact], and the final @scheme[arg] is a complete command -line. See @scheme[subprocess] for details.} +Under Windows, the first argument after @racket[command] can be +@racket['exact], and the final @racket[arg] is a complete command +line. See @racket[subprocess] for details.} @defproc[(system/exit-code [command string?]) (integer-in 0 255)]{ -Like @scheme[system], except that the result is the exit code returned -by the subprocess. A @scheme[0] result normally indicates success.} +Like @racket[system], except that the result is the exit code returned +by the subprocess. A @racket[0] result normally indicates success.} @defproc*[([(system*/exit-code [command path-string?][arg string?] ...) (integer-in 0 255)] [(system*/exit-code [command path-string?][exact 'exact][arg string?]) (integer-in 0 255)])]{ -Like @scheme[system*], but returns the exit code like -@scheme[system/exit-code].} +Like @racket[system*], but returns the exit code like +@racket[system/exit-code].} @defproc[(process [command string?]) @@ -284,28 +284,28 @@ Executes a shell command asynchronously. The result is a list of five values: @item{an input port piped from the subprocess's standard error, and} - @item{a procedure of one argument, either @scheme['status], - @scheme['wait], @scheme['interrupt], or @scheme['kill]: + @item{a procedure of one argument, either @racket['status], + @racket['wait], @racket['interrupt], or @racket['kill]: @itemize[ - @item{@scheme['status] returns the status of the subprocess as one - of @scheme['running], @scheme['done-ok], or - @scheme['done-error].} + @item{@racket['status] returns the status of the subprocess as one + of @racket['running], @racket['done-ok], or + @racket['done-error].} - @item{@scheme['exit-code] returns the integer exit code of the - subprocess or @scheme[#f] if it is still running.} + @item{@racket['exit-code] returns the integer exit code of the + subprocess or @racket[#f] if it is still running.} - @item{@scheme['wait] blocks execution in the current thread until + @item{@racket['wait] blocks execution in the current thread until the subprocess has completed.} - @item{@scheme['interrupt] sends the subprocess an interrupt signal + @item{@racket['interrupt] sends the subprocess an interrupt signal under @|AllUnix|, and takes no action under Windows. The result is @|void-const|.} - @item{@scheme['kill] terminates the subprocess and returns + @item{@racket['kill] terminates the subprocess and returns @|void-const|. Note that the immediate process created by - @scheme[process] is a shell process that may run another program; + @racket[process] is a shell process that may run another program; terminating the shell process may not terminate processes that the shell starts, particularly under Windows.} @@ -313,18 +313,18 @@ Executes a shell command asynchronously. The result is a list of five values: ] -@bold{Important:} All three ports returned from @scheme[process] must -be explicitly closed with @scheme[close-input-port] or -@scheme[close-output-port].} +@bold{Important:} All three ports returned from @racket[process] must +be explicitly closed with @racket[close-input-port] or +@racket[close-output-port].} @defproc*[([(process* [command path-string?][arg string?] ...) list?] [(process* [command path-string?][exact 'exact][arg string?]) list?])]{ -Like @scheme[process], except that @scheme[command] is a filename that -is executed directly, and the @scheme[arg]s are the arguments. Under -Windows, as for @scheme[system*], the first @scheme[arg] can be -replaced with @scheme['exact].} +Like @racket[process], except that @racket[command] is a filename that +is executed directly, and the @racket[arg]s are the arguments. Under +Windows, as for @racket[system*], the first @racket[arg] can be +replaced with @racket['exact].} @defproc[(process/ports [out (or/c #f output-port?)] @@ -333,13 +333,13 @@ replaced with @scheme['exact].} [command string?]) list?]{ -Like @scheme[process], except that @scheme[out] is used for the -process's standard output, @scheme[in] is used for the process's -standard input, and @scheme[error-out] is used for the process's -standard error. Any of the ports can be @scheme[#f], in which case a -system pipe is created and returned, as in @scheme[process]. For each +Like @racket[process], except that @racket[out] is used for the +process's standard output, @racket[in] is used for the process's +standard input, and @racket[error-out] is used for the process's +standard error. Any of the ports can be @racket[#f], in which case a +system pipe is created and returned, as in @racket[process]. For each port that is provided, no pipe is created, and the corresponding value -in the returned list is @scheme[#f].} +in the returned list is @racket[#f].} @defproc*[([(process*/ports [out (or/c #f output-port?)] [in (or/c #f input-port?)] @@ -355,6 +355,6 @@ in the returned list is @scheme[#f].} [arg string?]) list?])]{ -Like @scheme[process*], but with the port handling of -@scheme[process/ports].} +Like @racket[process*], but with the port handling of +@racket[process/ports].} diff --git a/collects/scribblings/reference/sync.scrbl b/collects/scribblings/reference/sync.scrbl index 8dd2dfb0c0..28a08808c2 100644 --- a/collects/scribblings/reference/sync.scrbl +++ b/collects/scribblings/reference/sync.scrbl @@ -3,7 +3,7 @@ @title[#:tag "all-sync" #:style 'toc]{Synchronization} -Scheme's synchronization toolbox spans three layers: +Racket's synchronization toolbox spans three layers: @itemize[ diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 26e4eb4f64..a9996f0d50 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -9,7 +9,6 @@ make-provide-transformer) racket/provide-syntax racket/provide - racket/nest racket/package racket/splicing racket/runtime-path)) @@ -2414,54 +2413,6 @@ provides a hook to control interactive evaluation through @;------------------------------------------------------------------------ @include-section["package.scrbl"] -@;------------------------------------------------------------------------ -@section[#:tag "nest"]{Flattening Syntactic Sequences: @racket[nest]} - -@note-lib[racket/nest] - -@defform[(nest ([datum ...+] ...) body ...+)]{ - -Combines nested expressions that syntactically drift to the right into -a more linear textual format, much in the same way that @racket[let*] -linearizes a sequence of nested @racket[let] expressions. - -For example, - -@racketblock[ -(nest ([let ([x 10] - [y 6])] - [with-handlers ([exn:fail? (lambda (x) 15)])] - [parameterize ([current-output-port (current-error-port)])] - [let-values ([(d r) (quotient/remainder x y)])]) - (display (+ d r))) -] - -is equivalent to - -@racketblock[ -(let ([x 10] - [y 6]) - (with-handlers ([exn:fail? (lambda (x) 15)]) - (parameterize ([current-output-port (current-error-port)]) - (let-values ([(d r) (quotient/remainder x y)]) - (display (+ d r)))))) -] - -The @racket[nest] form is unusual in that it has no semantics apart -from its expansion, and its implementation is easier to understand -than a precise prose description: - -@racketblock[ -(define-syntax nest - (syntax-rules () - [(nest () body0 body ...) - (let () body0 body ...)] - [(nest ([form forms ...]) body0 body ...) - (form forms ... (let () body0 body ...))] - [(nest ([form forms ...] . more) body0 body ...) - (form forms ... (nest more body0 body ...))])) -]} - @close-eval[require-eval] @close-eval[meta-in-eval] diff --git a/collects/scribblings/reference/thread-groups.scrbl b/collects/scribblings/reference/thread-groups.scrbl index f16f029fb7..2fec5b10e5 100644 --- a/collects/scribblings/reference/thread-groups.scrbl +++ b/collects/scribblings/reference/thread-groups.scrbl @@ -8,12 +8,12 @@ groups that have equal claim to the CPU. By nesting thread groups and by creating certain threads within certain groups, a programmer can control the amount of CPU allocated to a set of threads. Every thread belongs to a thread group, which is determined by the -@scheme[current-thread-group] parameter when the thread is +@racket[current-thread-group] parameter when the thread is created. Thread groups and custodians (see @secref["custodians"]) are independent. The root thread group receives all of the CPU that the operating -system gives Scheme. Every thread or nested group in a particular +system gives Racket. Every thread or nested group in a particular thread group receives equal allocation of the CPU (a portion of the group's access), although a thread may relinquish part of its allocation by sleeping or synchronizing with other processes. @@ -21,12 +21,12 @@ allocation by sleeping or synchronizing with other processes. @defproc[(make-thread-group [group thread-group? (current-thread-group)]) thread-group?]{ -Creates a new thread group that belongs to @scheme[group].} +Creates a new thread group that belongs to @racket[group].} @defproc[(thread-group? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a thread group value, @scheme[#f] +Returns @racket[#t] if @racket[v] is a thread group value, @racket[#f] otherwise.} diff --git a/collects/scribblings/reference/threads.scrbl b/collects/scribblings/reference/threads.scrbl index 00b51c959d..539360c227 100644 --- a/collects/scribblings/reference/threads.scrbl +++ b/collects/scribblings/reference/threads.scrbl @@ -3,37 +3,37 @@ @title[#:tag "threads"]{Threads} -See @secref["thread-model"] for basic information on the PLT Scheme +See @secref["thread-model"] for basic information on the PLT 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 @scheme[thread-resume]. +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 unreachable and blocked on only unreachable events through -@scheme[semaphore-wait], @scheme[semaphore-wait/enable-break], -@scheme[channel-put], @scheme[channel-get], @scheme[sync], -@scheme[sync/enable-break], or @scheme[thread-wait]. +@racket[semaphore-wait], @racket[semaphore-wait/enable-break], +@racket[channel-put], @racket[channel-get], @racket[sync], +@racket[sync/enable-break], or @racket[thread-wait]. -@margin-note{In MrEd, a handler thread for an eventspace is blocked on +@margin-note{In GRacket, a handler thread for an eventspace is blocked on an internal semaphore when its event queue is empty. Thus, the handler thread is collectible when the eventspace is unreachable and contains no visible windows or running timers.} -All constant-time procedures and operations provided by MzScheme are +All constant-time procedures and operations provided by Racket are thread-safe because they are @defterm{atomic}. For example, -@scheme[set!] assigns to a variable as an atomic action with respect +@racket[set!] assigns to a variable as an atomic action with respect to all threads, so that no thread can see a ``half-assigned'' -variable. Similarly, @scheme[vector-set!] assigns to a vector -atomically. The @scheme[hash-set!] procedure is not atomic, but +variable. Similarly, @racket[vector-set!] assigns to a vector +atomically. The @racket[hash-set!] procedure is not atomic, but the table is protected by a lock; see @secref["hashtables"] for more information. Port operations are generally not atomic, but they are thread-safe in the sense that a byte consumed by one thread from an input port will not be returned also to another thread, and procedures -like @scheme[port-commit-peeked] and @scheme[write-bytes-avail] offer +like @racket[port-commit-peeked] and @racket[write-bytes-avail] offer specific concurrency guarantees. @;------------------------------------------------------------------------ @@ -41,48 +41,48 @@ specific concurrency guarantees. @defproc[(thread [thunk (-> any)]) thread?]{ -Calls @scheme[thunk] with no arguments in a new thread of control. The -@scheme[thread] procedure returns immediately with a @deftech{thread -descriptor} value. When the invocation of @scheme[thunk] returns, the -thread created to invoke @scheme[thunk] terminates. +Calls @racket[thunk] with no arguments in a new thread of control. The +@racket[thread] procedure returns immediately with a @deftech{thread +descriptor} value. When the invocation of @racket[thunk] returns, the +thread created to invoke @racket[thunk] terminates. } -@defproc[(thread? [v any/c]) thread?]{Returns @scheme[#t] if -@scheme[v] is a @tech{thread descriptor}, @scheme[#f] otherwise.} +@defproc[(thread? [v any/c]) thread?]{Returns @racket[#t] if +@racket[v] is a @tech{thread descriptor}, @racket[#f] otherwise.} @defproc[(current-thread) thread?]{Returns the @tech{thread descriptor} for the currently executing thread.} @defproc[(thread/suspend-to-kill [thunk (-> any)]) thread]{ -Like @scheme[thread], except that ``killing'' the thread through -@scheme[kill-thread] or @scheme[custodian-shutdown-all] merely +Like @racket[thread], except that ``killing'' the thread through +@racket[kill-thread] or @racket[custodian-shutdown-all] merely suspends the thread instead of terminating it. } @defproc[(call-in-nested-thread [thunk (->any)] [cust custodian? (current-custodian)]) any]{ -Creates a nested thread managed by @scheme[cust] to execute -@scheme[thunk]. (The nested thread's current custodian is inherited -from the creating thread, independent of the @scheme[cust] argument.) -The current thread blocks until @scheme[thunk] returns, and the result -of the @scheme[call-in-nested-thread] call is the result returned by -@scheme[thunk]. +Creates a nested thread managed by @racket[cust] to execute +@racket[thunk]. (The nested thread's current custodian is inherited +from the creating thread, independent of the @racket[cust] argument.) +The current thread blocks until @racket[thunk] returns, and the result +of the @racket[call-in-nested-thread] call is the result returned by +@racket[thunk]. The nested thread's exception handler is initialized to a procedure that jumps to the beginning of the thread and transfers the exception to the original thread. The handler thus terminates the nested thread and re-raises the exception in the original thread. -If the thread created by @scheme[call-in-nested-thread] dies before -@scheme[thunk] returns, the @exnraise[exn:fail] in the original -thread. If the original thread is killed before @scheme[thunk] +If the thread created by @racket[call-in-nested-thread] dies before +@racket[thunk] returns, the @exnraise[exn:fail] in the original +thread. If the original thread is killed before @racket[thunk] returns, a break is queued for the nested thread. If a break is queued for the original thread (with -@scheme[break-thread]) while the nested thread is running, the break +@racket[break-thread]) while the nested thread is running, the break is redirected to the nested thread. If a break is already queued on the original thread when the nested thread is created, the break is moved to the nested thread. If a break remains queued on the nested @@ -93,49 +93,49 @@ thread when it completes, the break is moved to the original thread.} @defproc[(thread-suspend [thd thread?]) void?]{ -Immediately suspends the execution of @scheme[thd] if it is +Immediately suspends the execution of @racket[thd] if it is running. If the thread has terminated or is already suspended, -@scheme[thread-suspend] has no effect. The thread remains suspended +@racket[thread-suspend] has no effect. The thread remains suspended (i.e., it does not execute) until it is resumed with -@scheme[thread-resume]. If the @tech{current custodian} does not -manage @scheme[thd] (and none of its subordinates manages -@scheme[thd]), the @exnraise[exn:fail:contract], and the thread is not +@racket[thread-resume]. If the @tech{current custodian} does not +manage @racket[thd] (and none of its subordinates manages +@racket[thd]), the @exnraise[exn:fail:contract], and the thread is not suspended.} @defproc[(thread-resume [thd thread?][benefactor (or/c thread? custodian? #f) #f]) void?]{ -Resumes the execution of @scheme[thd] if it is suspended and has at -least one custodian (possibly added through @scheme[benefactor], as +Resumes the execution of @racket[thd] if it is suspended and has at +least one custodian (possibly added through @racket[benefactor], as described below). If the thread has terminated, or if the thread is -already running and @scheme[benefactor] is not supplied, or if the -thread has no custodian and @scheme[benefactor] is not supplied, then -@scheme[thread-resume] has no effect. Otherwise, if -@scheme[benefactor] is supplied, it triggers up to three +already running and @racket[benefactor] is not supplied, or if the +thread has no custodian and @racket[benefactor] is not supplied, then +@racket[thread-resume] has no effect. Otherwise, if +@racket[benefactor] is supplied, it triggers up to three additional actions: @itemize[ - @item{If @scheme[benefactor] is a thread, whenever it is resumed - from a suspended state in the future, then @scheme[thd] is also - resumed. (Resuming @scheme[thd] may trigger the resumption of other - threads that were previously attached to @scheme[thd] through - @scheme[thread-resume].)} + @item{If @racket[benefactor] is a thread, whenever it is resumed + from a suspended state in the future, then @racket[thd] is also + resumed. (Resuming @racket[thd] may trigger the resumption of other + threads that were previously attached to @racket[thd] through + @racket[thread-resume].)} - @item{New custodians may be added to @scheme[thd]'s set of - managers. If @scheme[benefactor] is a thread, then all of the - thread's custodians are added to @scheme[thd]. Otherwise, - @scheme[benefactor] is a custodian, and it is added to @scheme[thd] - (unless the custodian is already shut down). If @scheme[thd] + @item{New custodians may be added to @racket[thd]'s set of + managers. If @racket[benefactor] is a thread, then all of the + thread's custodians are added to @racket[thd]. Otherwise, + @racket[benefactor] is a custodian, and it is added to @racket[thd] + (unless the custodian is already shut down). If @racket[thd] becomes managed by both a custodian and one or more of its subordinates, the redundant subordinates are removed from - @scheme[thd]. If @scheme[thd] is suspended and a custodian is - added, then @scheme[thd] is resumed only after the addition.} + @racket[thd]. If @racket[thd] is suspended and a custodian is + added, then @racket[thd] is resumed only after the addition.} - @item{If @scheme[benefactor] is a thread, whenever it receives a - new managing custodian in the future, then @scheme[thd] also - receives the custodian. (Adding custodians to @scheme[thd] may + @item{If @racket[benefactor] is a thread, whenever it receives a + new managing custodian in the future, then @racket[thd] also + receives the custodian. (Adding custodians to @racket[thd] may trigger adding the custodians to other threads that were previously - attached to @scheme[thd] through @scheme[thread-resume].)} + attached to @racket[thd] through @racket[thread-resume].)} ]} @@ -143,15 +143,15 @@ additional actions: @defproc[(kill-thread [thd thread?]) void?]{ Terminates the specified thread immediately, or suspends the thread if -@scheme[thd] was created with -@scheme[thread/suspend-to-kill]. Terminating the main thread exits the -application. If @scheme[thd] has already terminated, -@scheme[kill-thread] does nothing. If the @tech{current custodian} -does not manage @scheme[thd] (and none of its subordinates manages -@scheme[thd]), the @exnraise[exn:fail:contract], and the thread is not +@racket[thd] was created with +@racket[thread/suspend-to-kill]. Terminating the main thread exits the +application. If @racket[thd] has already terminated, +@racket[kill-thread] does nothing. If the @tech{current custodian} +does not manage @racket[thd] (and none of its subordinates manages +@racket[thd]), the @exnraise[exn:fail:contract], and the thread is not killed or suspended. -Unless otherwise noted, procedures provided by MzScheme (and MrEd) are +Unless otherwise noted, procedures provided by Racket (and GRacket) are kill-safe and suspend-safe; that is, killing or suspending a thread never interferes with the application of procedures in other threads. For example, if a thread is killed while extracting a @@ -161,26 +161,26 @@ consumed or not consumed, and other threads can safely use the port.} @defproc[(break-thread [thd thread?]) void?]{ @index['("threads" "breaking")]{Registers} a break with the specified -thread. If breaking is disabled in @scheme[thd], the break will be +thread. If breaking is disabled in @racket[thd], the break will be ignored until breaks are re-enabled (see @secref["breakhandler"]).} @defproc[(sleep [secs nonnegative-number? 0]) void?]{ -Causes the current thread to sleep until at least @scheme[secs] +Causes the current thread to sleep until at least @racket[secs] seconds have passed after it starts sleeping. A zero value for -@scheme[secs] simply acts as a hint to allow other threads to -execute. The value of @scheme[secs] can be non-integral to request a +@racket[secs] simply acts as a hint to allow other threads to +execute. The value of @racket[secs] can be non-integral to request a sleep duration to any precision; the precision of the actual sleep time is unspecified.} @defproc[(thread-running? [thd thread?]) any]{ -@index['("threads" "run state")]{Returns} @scheme[#t] if @scheme[thd] -has not terminated and is not suspended, @scheme[#f] otherwise.} +@index['("threads" "run state")]{Returns} @racket[#t] if @racket[thd] +has not terminated and is not suspended, @racket[#f] otherwise.} @defproc[(thread-dead? [thd thread?]) any]{ -Returns @scheme[#t] if @scheme[thd] has terminated, @scheme[#f] +Returns @racket[#t] if @racket[thd] has terminated, @racket[#f] otherwise.} @;------------------------------------------------------------------------ @@ -188,42 +188,42 @@ otherwise.} @defproc[(thread-wait [thd thread?]) void?]{ -Blocks execution of the current thread until @scheme[thd] has -terminated. Note that @scheme[(thread-wait (current-thread))] +Blocks execution of the current thread until @racket[thd] has +terminated. Note that @racket[(thread-wait (current-thread))] deadlocks the current thread, but a break can end the deadlock (if breaking is enabled; see @secref["breakhandler"]).} @defproc[(thread-dead-evt [thd thread?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that is -ready if and only if @scheme[thd] has terminated. Unlike using -@scheme[thd] directly, however, a reference to the event does not -prevent @scheme[thd] from being garbage collected (see -@secref["gc-model"]). For a given @scheme[thd], -@scheme[thread-dead-evt] always returns the same (i.e., @scheme[eq?]) +ready if and only if @racket[thd] has terminated. Unlike using +@racket[thd] directly, however, a reference to the event does not +prevent @racket[thd] from being garbage collected (see +@secref["gc-model"]). For a given @racket[thd], +@racket[thread-dead-evt] always returns the same (i.e., @racket[eq?]) result.} @defproc[(thread-resume-evt [thd thread?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that -becomes ready when @scheme[thd] is running. (If @scheme[thd] has -terminated, the event never becomes ready.) If @scheme[thd] runs and -is then suspended after a call to @scheme[thread-resume-evt], the -result event remains ready; after each suspend of @scheme[thd] a fresh -event is generated to be returned by @scheme[thread-resume-evt]. The -result of the event is @scheme[thd], but if @scheme[thd] is never -resumed, then reference to the event does not prevent @scheme[thd] +becomes ready when @racket[thd] is running. (If @racket[thd] has +terminated, the event never becomes ready.) If @racket[thd] runs and +is then suspended after a call to @racket[thread-resume-evt], the +result event remains ready; after each suspend of @racket[thd] a fresh +event is generated to be returned by @racket[thread-resume-evt]. The +result of the event is @racket[thd], but if @racket[thd] is never +resumed, then reference to the event does not prevent @racket[thd] from being garbage collected (see @secref["gc-model"]).} @defproc[(thread-suspend-evt [thd thread?]) evt?]{ Returns a @tech{synchronizable event} (see @secref["sync"]) that -becomes ready when @scheme[thd] is suspended. (If @scheme[thd] has -terminated, the event will never unblock.) If @scheme[thd] is +becomes ready when @racket[thd] is suspended. (If @racket[thd] has +terminated, the event will never unblock.) If @racket[thd] is suspended and then resumes after a call to -@scheme[thread-suspend-evt], the result event remains ready; after -each resume of @scheme[thd] created a fresh event to be returned by -@scheme[thread-suspend-evt].} +@racket[thread-suspend-evt], the result event remains ready; after +each resume of @racket[thd] created a fresh event to be returned by +@racket[thread-suspend-evt].} @;------------------------------------------------------------------------ @section[#:tag "threadmbox"]{Thread Mailboxes} @@ -239,23 +239,23 @@ asynchronous channel. (lambda () (raise-mismatch-error ....))]) any]{ -Queues @scheme[v] as a message to @scheme[thd] without blocking. If -the message is queued, the result is @|void-const|. If @scheme[thd] -stops running---as in @scheme[thread-running?]---before the message is -queued, then @scheme[fail-thunk] is called (through a tail call) if is -a procedure to produce the result, or @scheme[#f] is returned if -@scheme[fail-thunk] is @scheme[#f].} +Queues @racket[v] as a message to @racket[thd] without blocking. If +the message is queued, the result is @|void-const|. If @racket[thd] +stops running---as in @racket[thread-running?]---before the message is +queued, then @racket[fail-thunk] is called (through a tail call) if is +a procedure to produce the result, or @racket[#f] is returned if +@racket[fail-thunk] is @racket[#f].} @defproc[(thread-receive) any/c]{ Receives and dequeues a message queued for the current thread, if -any. If no message is available, @scheme[thread-receive] blocks until +any. If no message is available, @racket[thread-receive] blocks until one is available.} @defproc[(thread-try-receive) any/c]{ Receives and dequeues a message queued for the current thread, if any, -or returns @scheme[#f] immediately if no message is available.} +or returns @racket[#f] immediately if no message is available.} @defproc[(thread-receive-evt) evt?]{ @@ -265,6 +265,6 @@ receive. The event result is itself.} @defproc[(thread-rewind-receive [lst list?]) void?]{ -Pushes the elements of @scheme[lst] back onto the front of the current +Pushes the elements of @racket[lst] back onto the front of the current thread's queue. The elements are pushed one by one, so that the first -available message is the last element of @scheme[lst].} +available message is the last element of @racket[lst].} diff --git a/collects/scribblings/reference/time.scrbl b/collects/scribblings/reference/time.scrbl index 83434579e5..ccbf24ddd6 100644 --- a/collects/scribblings/reference/time.scrbl +++ b/collects/scribblings/reference/time.scrbl @@ -10,22 +10,22 @@ Returns the current time in seconds. This time is always an exact integer based on a platform-specific starting date (with a platform-specific minimum and maximum value). -The value of @scheme[(current-seconds)] increases as time passes +The value of @racket[(current-seconds)] increases as time passes (increasing by 1 for each second that passes). The current time in seconds can be compared with a time returned by -@scheme[file-or-directory-modify-seconds].} +@racket[file-or-directory-modify-seconds].} @defproc[(seconds->date [secs-n exact-integer?]) date?]{ -Takes @scheme[secs-n], a platform-specific time in seconds returned by -@scheme[current-seconds] or @scheme[file-or-directory-modify-seconds], -and returns an instance of the @scheme[date] structure type. If -@scheme[secs-n] is too small or large, the @exnraise[exn:fail]. +Takes @racket[secs-n], a platform-specific time in seconds returned by +@racket[current-seconds] or @racket[file-or-directory-modify-seconds], +and returns an instance of the @racket[date] structure type. If +@racket[secs-n] is too small or large, the @exnraise[exn:fail]. -The value returned by @scheme[current-seconds] or -@scheme[file-or-directory-modify-seconds] is not portable among -platforms. Convert a time in seconds using @scheme[seconds->date] when +The value returned by @racket[current-seconds] or +@racket[file-or-directory-modify-seconds] is not portable among +platforms. Convert a time in seconds using @racket[seconds->date] when portability is needed.} @defstruct[date ([second (integer-in 0 61)] @@ -40,21 +40,21 @@ portability is needed.} [time-zone-offset exact-integer?]) #:inspector #f]{ -Represents a date. For the @scheme[second] field, values of -@scheme[60] and @scheme[61] are for unusual, but possible for -leap-seconds. The @scheme[year-day] field reaches @scheme[365] only in +Represents a date. For the @racket[second] field, values of +@racket[60] and @racket[61] are for unusual, but possible for +leap-seconds. The @racket[year-day] field reaches @racket[365] only in leap years. -The @scheme[time-zone-offset] field reports the number of seconds east +The @racket[time-zone-offset] field reports the number of seconds east of GMT for the current time zone (e.g., Pacific Standard Time is -@scheme[-28800]), an exact integer. +@racket[-28800]), an exact integer. -The value produced for the @scheme[time-zone-offset] field tends to be +The value produced for the @racket[time-zone-offset] field tends to be sensitive to the value of the @envvar{TZ} environment variable, especially on Unix platforms; consult the system documentation (usually under @tt{tzset}) for details. -See also the @schememodname[racket/date] library.} +See also the @racketmodname[racket/date] library.} @defproc[(current-milliseconds) exact-integer?]{ @@ -76,11 +76,11 @@ Returns the current time in milliseconds since midnight UTC, January exact-integer?]{ Returns an amount of processor time in @tech{fixnum} milliseconds -that has been consumed by the Scheme process on the underlying +that has been consumed by the Racket process on the underlying operating system. (Under @|AllUnix|, this includes both user and -system time.) If @scheme[thread] is @scheme[#f], the reported time -is for all Scheme threads, otherwise the result is specific to the -time while @scheme[thread] ran. +system time.) If @racket[thread] is @racket[#f], the reported time +is for all Racket threads, otherwise the result is specific to the +time while @racket[thread] ran. The precision of the result is platform-specific, and since the result is a @tech{fixnum}, the value increases only over a limited (though reasonably long) time.} @@ -89,9 +89,9 @@ limited (though reasonably long) time.} @defproc[(current-gc-milliseconds) exact-integer?]{ Returns the amount of processor time in @tech{fixnum} milliseconds -that has been consumed by Scheme's garbage collection so far. This +that has been consumed by Racket's garbage collection so far. This time is a portion of the time reported by -@scheme[(current-process-milliseconds)], and is similarly limited.} +@racket[(current-process-milliseconds)], and is similarly limited.} @defproc[(time-apply [proc procedure?] @@ -104,20 +104,20 @@ time is a portion of the time reported by Collects timing information for a procedure application. Four values are returned: a list containing the result(s) of applying -@scheme[proc] to the arguments in @scheme[lst], the number of milliseconds of +@racket[proc] to the arguments in @racket[lst], the number of milliseconds of CPU time required to obtain this result, the number of ``real'' milliseconds required for the result, and the number of milliseconds of CPU time (included in the first result) spent on garbage collection. The reliability of the timing numbers depends on the platform. If -multiple MzScheme threads are running, then the reported time may +multiple Racket threads are running, then the reported time may include work performed by other threads.} @defform[(time expr)]{ -Reports @scheme[time-apply]-style timing information for the -evaluation of @scheme[expr] directly to the current output port. The -result is the result of @scheme[expr].} +Reports @racket[time-apply]-style timing information for the +evaluation of @racket[expr] directly to the current output port. The +result is the result of @racket[expr].} @; ---------------------------------------------------------------------- @@ -128,7 +128,7 @@ result is the result of @scheme[expr].} @defproc[(date->string [date date?][time? any/c #f]) string?]{ Converts a date to a string. The returned string contains the time of -day only if @scheme[time?]. See also @scheme[date-display-format].} +day only if @racket[time?]. See also @racket[date-display-format].} @defparam[date-display-format format (or/c 'american @@ -141,7 +141,7 @@ day only if @scheme[time?]. See also @scheme[date-display-format].} 'julian)]{ Parameter that determines the date string format. The initial format -is @scheme['american].} +is @racket['american].} @defproc[(find-seconds [second (integer-in 0 61)] @@ -153,7 +153,7 @@ is @scheme['american].} exact-integer?]{ Finds the representation of a date in platform-specific seconds. The -arguments correspond to the fields of the @scheme[date] structure. If +arguments correspond to the fields of the @racket[date] structure. If the platform cannot represent the specified date, an error is signaled, otherwise an integer is returned.} diff --git a/collects/scribblings/reference/unix-paths.scrbl b/collects/scribblings/reference/unix-paths.scrbl index f4176defa0..da2e403488 100644 --- a/collects/scribblings/reference/unix-paths.scrbl +++ b/collects/scribblings/reference/unix-paths.scrbl @@ -9,7 +9,7 @@ In @|AllUnix| paths, a @litchar{/} separates elements of the path, preceding path, and @litchar{..} as a path element always means the parent of the directory indicated by the preceding path. A leading @litchar{~} in a path is not treated specially, but -@scheme[expand-user-path] can be used to convert a leading @litchar{~} +@racket[expand-user-path] can be used to convert a leading @litchar{~} element to a user-specific directory. No other character or byte has a special meaning within a path. Multiple adjacent @litchar{/} are equivalent to a single @litchar{/} (i.e., they act as a single path @@ -26,13 +26,13 @@ directory, as does any path whose last element is @litchar{.} or A @|AllUnix| path is @techlink{cleanse}d by replacing multiple adjacent @litchar{/}s with a single @litchar{/}. -For @scheme[(bytes->path-element _bstr)], @scheme[bstr] must not +For @racket[(bytes->path-element _bstr)], @racket[bstr] must not contain any @litchar{/}, otherwise the @exnraise[exn:fail:contract]. -The result of @scheme[(path-element->bytes _path)] or -@scheme[(path-element->string _path)] is always the same as the result -of @scheme[(path->bytes _path)] and @scheme[(path->string +The result of @racket[(path-element->bytes _path)] or +@racket[(path-element->string _path)] is always the same as the result +of @racket[(path->bytes _path)] and @racket[(path->string _path)]. Since that is not the case for other platforms, however, -@scheme[path-element->bytes] and @scheme[path-element->string] should +@racket[path-element->bytes] and @racket[path-element->string] should be used when converting individual path elements. Under Mac OS X, Finder aliases are zero-length files. diff --git a/collects/scribblings/reference/windows-paths.scrbl b/collects/scribblings/reference/windows-paths.scrbl index 8619433a05..d8c636b68d 100644 --- a/collects/scribblings/reference/windows-paths.scrbl +++ b/collects/scribblings/reference/windows-paths.scrbl @@ -2,7 +2,7 @@ @(require scribble/bnf "mz.ss") -@(define MzAdd (italic "Scheme-specific:")) +@(define MzAdd (italic "Racket-specific:")) @title[#:tag "windowspaths"]{Windows Path Conventions} @@ -21,14 +21,14 @@ colon, a UNC path of the form @litchar{RED\}@nonterm{element}. (Variants of @litchar{\\?\} paths are described further below.) -Scheme fails to implement the usual Windows path syntax in one -way. Outside of Scheme, a pathname @filepath{C:rant.txt} can be a +Racket fails to implement the usual Windows path syntax in one +way. Outside of Racket, a pathname @filepath{C:rant.txt} can be a drive-specific relative path. That is, it names a file @filepath{rant.txt} on drive @filepath{C:}, but the complete path to the file is determined by -the current working directory for drive @filepath{C:}. Scheme does not +the current working directory for drive @filepath{C:}. Racket does not support drive-specific working directories (only a working directory -across all drives, as reflected by the @scheme[current-directory] -parameter). Consequently, Scheme implicitly converts a path like +across all drives, as reflected by the @racket[current-directory] +parameter). Consequently, Racket implicitly converts a path like @filepath{C:rant.txt} into @filepath["C:\\rant.txt"]. @itemize[ @@ -40,7 +40,7 @@ parameter). Consequently, Scheme implicitly converts a path like ] -Otherwise, Scheme follows standard Windows path conventions, but also +Otherwise, Racket follows standard Windows path conventions, but also adds @litchar{\\?\REL} and @litchar{\\?\RED} conventions to deal with paths inexpressible in the standard convention, plus conventions to deal with excessive @litchar{\}s in @litchar{\\?\} @@ -145,7 +145,7 @@ include @litchar{\}. @litchar{\\?\REL\\}@nonterm{element} is a relative path, as long as the path does not end with two consecutive @litchar{\}s, and as long as the path contains no sequence of - three or more @litchar{\}s. This Scheme-specific path form + three or more @litchar{\}s. This Racket-specific path form supports relative paths with elements that are not normally expressible in Windows paths (e.g., a final element that ends in a space). The @litchar{REL} part must be exactly the three @@ -171,7 +171,7 @@ include @litchar{\}. drive-relative path, as long as the path does not end with two consecutive @litchar{\}s, and as long as the path contains no sequence of three or more @litchar{\}s. This - Scheme-specific path form supports drive-relative paths (i.e., + Racket-specific path form supports drive-relative paths (i.e., absolute given a drive) with elements that are not normally expressible in Windows paths. The @litchar{RED} part must be exactly the three uppercase letters, and @litchar{/}s cannot @@ -186,7 +186,7 @@ include @litchar{\}. ] -Three additional Scheme-specific rules provide meanings to character +Three additional Racket-specific rules provide meanings to character sequences that are otherwise ill-formed as Windows paths: @itemize[ @@ -214,8 +214,8 @@ sequences that are otherwise ill-formed as Windows paths: ] -Outside of Scheme, except for @litchar{\\?\} paths, pathnames are - typically limited to 259 characters. Scheme internally converts +Outside of Racket, except for @litchar{\\?\} paths, pathnames are + typically limited to 259 characters. Racket internally converts pathnames to @litchar{\\?\} form as needed to avoid this limit. The operating system cannot access files through @litchar{\\?\} paths that are longer than 32,000 characters or @@ -227,8 +227,8 @@ into bytes preserves ASCII characters, and all special characters mentioned above are ASCII, so all of the rules are the same. Beware that the @litchar{\} path separator is an escape character -in Scheme strings. Thus, the path @litchar{\\?\REL\..\\..} as -a string must be written @scheme["\\\\?\\REL\\..\\\\.."]. +in Racket strings. Thus, the path @litchar{\\?\REL\..\\..} as +a string must be written @racket["\\\\?\\REL\\..\\\\.."]. A path that ends with a directory separator syntactically refers to a directory. In addition, a path syntactcially refers to a directory if @@ -248,54 +248,54 @@ converted to single @litchar{/}s (except at the beginning of a shared folder name), a @litchar{/} is inserted after the colon in a drive specification if it is missing. -For @scheme[(bytes->path-element _bstr)], @litchar{/}s, colons, +For @racket[(bytes->path-element _bstr)], @litchar{/}s, colons, trailing dots, trailing whitespace, and special device names (e.g., -``aux'') in @scheme[_bstr] are encoded as a literal part of the path -element by using a @litchar{\\?\REL} prefix. The @scheme[bstr] +``aux'') in @racket[_bstr] are encoded as a literal part of the path +element by using a @litchar{\\?\REL} prefix. The @racket[bstr] argument must not contain a @litchar{\}, otherwise the @exnraise[exn:fail:contract]. -For @scheme[(path-element->bytes _path)] or -@scheme[(path-element->string _path)], if the byte-string form of -@scheme[_path] starts with a @litchar{\\?\REL}, the prefix is not +For @racket[(path-element->bytes _path)] or +@racket[(path-element->string _path)], if the byte-string form of +@racket[_path] starts with a @litchar{\\?\REL}, the prefix is not included in the result. -For @scheme[(build-path _base-path _sub-path ...)], trailing spaces -and periods are removed from the last element of @scheme[_base-path] -and all but the last @scheme[_sub-path] (unless the element consists of +For @racket[(build-path _base-path _sub-path ...)], trailing spaces +and periods are removed from the last element of @racket[_base-path] +and all but the last @racket[_sub-path] (unless the element consists of only spaces and peroids), except for those that start with -@litchar{\\?\}. If @scheme[_base-path] starts @litchar{\\?\}, +@litchar{\\?\}. If @racket[_base-path] starts @litchar{\\?\}, then after each non-@litchar{\\?\REL\} and -non-@litchar{\\?\RED\} @scheme[_sub-path] is added, all +non-@litchar{\\?\RED\} @racket[_sub-path] is added, all @litchar{/}s in the addition are converted to @litchar{\}s, multiple consecutive @litchar{\}s are converted to a single @litchar{\}, added @litchar{.} elements are removed, and added @litchar{..} elements are removed along with the preceding element; -these conversions are not performed on the original @scheme[_base-path] +these conversions are not performed on the original @racket[_base-path] part of the result or on any @litchar{\\?\REL\} or -@litchar{\\?\RED\} or @scheme[_sub-path]. If a +@litchar{\\?\RED\} or @racket[_sub-path]. If a @litchar{\\?\REL\} or @litchar{\\?\RED\} -@scheme[_sub-path] is added to a non-@litchar{\\?\} -@scheme[_base-path], the @scheme[_base-path] (with any additions up +@racket[_sub-path] is added to a non-@litchar{\\?\} +@racket[_base-path], the @racket[_base-path] (with any additions up to the @litchar{\\?\REL\} or @litchar{\\?\RED\} -@scheme[_sub-path]) is simplified and converted to a +@racket[_sub-path]) is simplified and converted to a @litchar{\\?\} path. In other cases, a @litchar{\} may be added or removed before combining paths to avoid changing the root meaning of the path (e.g., combining @litchar{//x} and @litchar{y} produces @litchar{/x/y}, because @litchar{//x/y} would be a UNC path instead of a drive-relative path). -For @scheme[(simplify-path _path _use-filesystem?)], @scheme[_path] is -expanded, and if @scheme[_path] does not start with +For @racket[(simplify-path _path _use-filesystem?)], @racket[_path] is +expanded, and if @racket[_path] does not start with @litchar{\\?\}, trailing spaces and periods are removed, a @litchar{/} is inserted after the colon in a drive specification if it is missing, and a @litchar{\} is inserted after @litchar{\\?\} as a root if there are elements and no extra @litchar{\} already. Otherwise, if no indicators or redundant separators are in -@scheme[_path], then @scheme[_path] is returned. +@racket[_path], then @racket[_path] is returned. -For @scheme[(split-path _path)] producing @scheme[_base], -@scheme[_name], and @scheme[_must-be-dir?], splitting a path that does +For @racket[(split-path _path)] producing @racket[_base], +@racket[_name], and @racket[_must-be-dir?], splitting a path that does not start with @litchar{\\?\} can produce parts that start with @litchar{\\?\}. For example, splitting @litchar{C:/x~/aux/} produces @litchar{\\?\C:\x~\} and @litchar{\\?\REL\\aux}; diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl index 87d47d5bfe..3909c0f2e6 100644 --- a/collects/scribblings/reference/write.scrbl +++ b/collects/scribblings/reference/write.scrbl @@ -9,14 +9,14 @@ @defproc[(write [datum any/c][out output-port? (current-output-port)]) void?]{ -Writes @scheme[datum] to @scheme[out], normally in such a way that -instances of core datatypes can be read back in. If @scheme[out] has a -handler associated to it via @scheme[port-write-handler], then the +Writes @racket[datum] to @racket[out], normally in such a way that +instances of core datatypes can be read back in. If @racket[out] has a +handler associated to it via @racket[port-write-handler], then the handler is called. Otherwise, the default printer is used (in -@scheme[write] mode), as configured by various parameters. +@racket[write] mode), as configured by various parameters. See @secref["printing"] for more information about the default -printer. In particular, note that @scheme[write] may require memory +printer. In particular, note that @racket[write] may require memory proportional to the depth of the value being printed, due to the initial cycle check. @@ -31,15 +31,15 @@ initial cycle check. @defproc[(display [datum any/c][out output-port? (current-output-port)]) void?]{ -Displays @scheme[datum] to @scheme[out], similar to @scheme[write], +Displays @racket[datum] to @racket[out], similar to @racket[write], but usually in such a way that byte- and character-based datatypes are -written as raw bytes or characters. If @scheme[out] has a handler -associated to it via @scheme[port-display-handler], then the handler -is called. Otherwise, the default printer is used (in @scheme[display] +written as raw bytes or characters. If @racket[out] has a handler +associated to it via @racket[port-display-handler], then the handler +is called. Otherwise, the default printer is used (in @racket[display] mode), as configured by various parameters. See @secref["printing"] for more information about the default -printer. In particular, note that @scheme[display] may require memory +printer. In particular, note that @racket[display] may require memory proportional to the depth of the value being printed, due to the initial cycle check.} @@ -47,29 +47,29 @@ initial cycle check.} [exact-nonnegative-integer? qq-depth 0]) void?]{ -Writes @scheme[datum] to @scheme[out], normally the same way as -@scheme[write]. If @scheme[out] has a handler associated to it via -@scheme[port-print-handler], then the handler is called. Otherwise, -the handler specified by @scheme[global-port-print-handler] is called; -the default handler uses the default printer in @scheme[write] mode. +Writes @racket[datum] to @racket[out], normally the same way as +@racket[write]. If @racket[out] has a handler associated to it via +@racket[port-print-handler], then the handler is called. Otherwise, +the handler specified by @racket[global-port-print-handler] is called; +the default handler uses the default printer in @racket[write] mode. -The optional @scheme[qq-depth] argument adjust printing when the -@scheme[print-as-quasiquote] parameter is set to @scheme[#t]. In that -case, @scheme[qq-depth] specifies the starting @scheme[quasiquote] -depth for printing @scheme[datum]. +The optional @racket[qq-depth] argument adjust printing when the +@racket[print-as-quasiquote] parameter is set to @racket[#t]. In that +case, @racket[qq-depth] specifies the starting @racket[quasiquote] +depth for printing @racket[datum]. -The rationale for providing @scheme[print] is that @scheme[display] -and @scheme[write] both have specific output conventions, and those +The rationale for providing @racket[print] is that @racket[display] +and @racket[write] both have specific output conventions, and those conventions restrict the ways that an environment can change the -behavior of @scheme[display] and @scheme[write] procedures. No output -conventions should be assumed for @scheme[print], so that environments -are free to modify the actual output generated by @scheme[print] in +behavior of @racket[display] and @racket[write] procedures. No output +conventions should be assumed for @racket[print], so that environments +are free to modify the actual output generated by @racket[print] in any way.} @defproc[(fprintf [out output-port?][form string?][v any/c] ...) void?]{ -Prints formatted output to @scheme[out], where @scheme[form] is a string +Prints formatted output to @racket[out], where @racket[form] is a string that is printed directly, except for special formatting escapes: @@ -77,51 +77,51 @@ escapes: @item{@FmtMark{n} or @FmtMark{%} prints a newline, the same as @litchar{\n}} - @item{@FmtMark{a} or @FmtMark{A} @scheme[display]s the next argument - among the @scheme[v]s} + @item{@FmtMark{a} or @FmtMark{A} @racket[display]s the next argument + among the @racket[v]s} - @item{@FmtMark{s} or @FmtMark{S} @scheme[write]s the next argument - among the @scheme[v]s} + @item{@FmtMark{s} or @FmtMark{S} @racket[write]s the next argument + among the @racket[v]s} - @item{@FmtMark{v} or @FmtMark{V} @scheme[print]s the next argument - among the @scheme[v]s} + @item{@FmtMark{v} or @FmtMark{V} @racket[print]s the next argument + among the @racket[v]s} @item{@FmtMark{e} or @FmtMark{E} outputs the next argument among the - @scheme[v]s using the current error value conversion handler (see - @scheme[error-value->string-handler]) and current error printing - width} @item{@FmtMark{c} or @FmtMark{C} @scheme[write-char]s the - next argument in @scheme[v]s; if the next argument is not a + @racket[v]s using the current error value conversion handler (see + @racket[error-value->string-handler]) and current error printing + width} @item{@FmtMark{c} or @FmtMark{C} @racket[write-char]s the + next argument in @racket[v]s; if the next argument is not a character, the @exnraise[exn:fail:contract]} @item{@FmtMark{b} or @FmtMark{B} prints the next argument among the - @scheme[v]s in binary; if the next argument is not an exact number, the + @racket[v]s in binary; if the next argument is not an exact number, the @exnraise[exn:fail:contract]} @item{@FmtMark{o} or @FmtMark{O} prints the next argument among the - @scheme[v]s in octal; if the next argument is not an exact number, the + @racket[v]s in octal; if the next argument is not an exact number, the @exnraise[exn:fail:contract]} @item{@FmtMark{x} or @FmtMark{X} prints the next argument among the - @scheme[v]s in hexadecimal; if the next argument is not an exact + @racket[v]s in hexadecimal; if the next argument is not an exact number, the @exnraise[exn:fail:contract]} @item{@FmtMark{~} prints a tilde.} @item{@FmtMark{}@nonterm{w}, where @nonterm{w} is a whitespace - character (see @scheme[char-whitespace?]), skips characters in - @scheme[form] until a non-whitespace character is encountered or + character (see @racket[char-whitespace?]), skips characters in + @racket[form] until a non-whitespace character is encountered or until a second end-of-line is encountered (whichever happens - first). On all platforms, an end-of-line can be @scheme[#\return], - @scheme[#\newline], or @scheme[#\return] followed immediately by - @scheme[#\newline].} + first). On all platforms, an end-of-line can be @racket[#\return], + @racket[#\newline], or @racket[#\return] followed immediately by + @racket[#\newline].} ] -The @scheme[form] string must not contain any @litchar{~} that is +The @racket[form] string must not contain any @litchar{~} that is not one of the above escapes, otherwise the @exnraise[exn:fail:contract]. When the format string requires more -@scheme[v]s than are supplied, the -@exnraise[exn:fail:contract]. Similarly, when more @scheme[v]s are +@racket[v]s than are supplied, the +@exnraise[exn:fail:contract]. Similarly, when more @racket[v]s are supplied than are used by the format string, the @exnraise[exn:fail:contract]. @@ -133,12 +133,12 @@ supplied than are used by the format string, the ]} @defproc[(printf [form string?][v any/c] ...) void?]{ -The same as @scheme[(fprintf (current-output-port) form v ...)].} +The same as @racket[(fprintf (current-output-port) form v ...)].} @defproc[(format [form string?][v any/c] ...) string?]{ Formats to a string. The result is the same as -@schemeblock[ +@racketblock[ (let ([o (open-output-string)]) (fprintf o form v ...) (get-output-string o)) @@ -152,65 +152,65 @@ Formats to a string. The result is the same as A parameter that control pair printing. If the value is true, then pairs print using @litchar["{"] and @litchar["}"] instead of -@litchar{(} and @litchar{)}. The default is @scheme[#f].} +@litchar{(} and @litchar{)}. The default is @racket[#f].} @defboolparam[print-mpair-curly-braces on?]{ A parameter that control pair printing. If the value is true, then mutable pairs print using @litchar["{"] and @litchar["}"] instead of -@litchar{(} and @litchar{)}. The default is @scheme[#t].} +@litchar{(} and @litchar{)}. The default is @racket[#t].} @defboolparam[print-unreadable on?]{ A parameter that controls printing values that have no -@scheme[read]able form (using the default reader), including +@racket[read]able form (using the default reader), including structures that have a custom-write procedure (see -@scheme[prop:custom-write]), but not including @tech{uninterned} +@racket[prop:custom-write]), but not including @tech{uninterned} symbols and @tech{unreadable symbols} (which print the same as -@tech{interned} symbols); defaults to @scheme[#t]. See +@tech{interned} symbols); defaults to @racket[#t]. See @secref["printing"] for more information.} @defboolparam[print-graph on?]{ A parameter that controls printing data with sharing; defaults to -@scheme[#f]. See @secref["printing"] for more information.} +@racket[#f]. See @secref["printing"] for more information.} @defboolparam[print-struct on?]{ A parameter that controls printing structure values in vector or -@tech{prefab} form; defaults to @scheme[#t]. See @secref["printing"] +@tech{prefab} form; defaults to @racket[#t]. See @secref["printing"] for more information. This parameter has no effect on the printing of structures that have a custom-write procedure (see -@scheme[prop:custom-write]).} +@racket[prop:custom-write]).} @defboolparam[print-box on?]{ A parameter that controls printing box values; defaults to -@scheme[#t]. See @secref["print-box"] for more information.} +@racket[#t]. See @secref["print-box"] for more information.} @defboolparam[print-vector-length on?]{ A parameter that controls printing vectors; defaults to -@scheme[#f]. See @secref["print-vectors"] for more information.} +@racket[#f]. See @secref["print-vectors"] for more information.} @defboolparam[print-hash-table on?]{ A parameter that controls printing hash tables; defaults to -@scheme[#f]. See @secref["print-hashtable"] for more information.} +@racket[#f]. See @secref["print-hashtable"] for more information.} @defboolparam[print-reader-abbreviations on?]{ A parameter that controls printing of two-element lists that start -with @scheme[quote], @scheme['quasiquote], @scheme['unquote], -@scheme['unquote-splicing], @scheme['syntax], @scheme['quasisyntax], -@scheme['unsyntax], or @scheme['unsyntax-splicing]; defaults to -@scheme[#f]. See @secref["print-pairs"] for more information.} +with @racket[quote], @racket['quasiquote], @racket['unquote], +@racket['unquote-splicing], @racket['syntax], @racket['quasisyntax], +@racket['unsyntax], or @racket['unsyntax-splicing]; defaults to +@racket[#f]. See @secref["print-pairs"] for more information.} @defboolparam[print-as-quasiquote on?]{ -A parameter that controls printing in @scheme[print] mode (as opposed -to @scheme[write] or @scheme[display]); defaults to @scheme[#f]. See +A parameter that controls printing in @racket[print] mode (as opposed +to @racket[write] or @racket[display]); defaults to @racket[#f]. See @secref["printing"] for more information.} @defboolparam[print-honu on?]{ @@ -222,7 +222,7 @@ A parameter that controls printing values in an alternate syntax. See @defparam[print-syntax-width width (or/c +inf.0 0 (and/c exact-integer? (>/c 3)))]{ A parameter that controls printing of @tech{syntax objects}. Up to -@scheme[width] characters are used to show the datum form of a syntax +@racket[width] characters are used to show the datum form of a syntax object within @litchar{#} (after the @tech{syntax object}'s source location, if any).} @@ -233,11 +233,11 @@ object within @litchar{#} (after the A parameter that is used when writing compiled code that contains pathname literals, including source-location pathnames for procedure -names. When not @scheme[#f], paths that syntactically extend the +names. When not @racket[#f], paths that syntactically extend the parameter's value are converted to relative paths; when the resulting compiled code is read, relative paths are converted back to complete -paths using the @scheme[current-load-relative-directory] parameter (if -it is not @scheme[#f], otherwise the path is left relative).} +paths using the @racket[current-load-relative-directory] parameter (if +it is not @racket[#f], otherwise the path is left relative).} @@ -257,22 +257,22 @@ it is not @scheme[#f], otherwise the path is left relative).} void?])]{ Gets or sets the @deftech{port write handler}, @deftech{port display -handler}, or @deftech{port print handler} for @scheme[out]. This -handler is call to output to the port when @scheme[write], -@scheme[display], or @scheme[print] (respectively) is applied to the +handler}, or @deftech{port print handler} for @racket[out]. This +handler is call to output to the port when @racket[write], +@racket[display], or @racket[print] (respectively) is applied to the port. Each handler must accept two arguments: the value to be printed and the destination port. The handler's return value is ignored. A @tech{port print handler} optionally accepts a third argument, which -corresponds to the optional third argument to @scheme[print]; if a -procedure given to @scheme[port-print-handler] does not accept a third +corresponds to the optional third argument to @racket[print]; if a +procedure given to @racket[port-print-handler] does not accept a third argument, it is wrapped with a procedure that discards the optional third argument. -The default port display and write handlers print Scheme expressions -with Scheme's built-in printer (see @secref["printing"]). The +The default port display and write handlers print Racket expressions +with Racket's built-in printer (see @secref["printing"]). The default print handler calls the global port print handler (the value -of the @scheme[global-port-print-handler] parameter); the default +of the @racket[global-port-print-handler] parameter); the default global port print handler is the same as the default write handler.} @defproc*[([(global-port-print-handler) ((any/c output-port?) (exact-nonnegative-integer?) . ->* . any)] @@ -280,13 +280,13 @@ global port print handler is the same as the default write handler.} A parameter that determines @deftech{global port print handler}, which is called by the default port print handler (see -@scheme[port-print-handler]) to @scheme[print] values into a port. +@racket[port-print-handler]) to @racket[print] values into a port. The default value uses the built-in printer (see -@secref["printing"]) in @scheme[print] mode. +@secref["printing"]) in @racket[print] mode. A @tech{global port print handler} optionally accepts a third argument, which corresponds to the optional third argument to -@scheme[print]. If a procedure given to -@scheme[global-port-print-handler] does not accept a third argument, +@racket[print]. If a procedure given to +@racket[global-port-print-handler] does not accept a third argument, it is wrapped with a procedure that discards the optional third argument.} diff --git a/collects/scribblings/scheme/scheme.scrbl b/collects/scribblings/scheme/scheme.scrbl index 0fff806222..d66316d24a 100644 --- a/collects/scribblings/scheme/scheme.scrbl +++ b/collects/scribblings/scheme/scheme.scrbl @@ -34,8 +34,9 @@ old name. @table-of-contents[] @compat-except[scheme racket]{, except that @schememodname[racket]'s -@scheme[struct] is not exported, and a @|unit-struct| from -@schememodname[scheme/unit] is exported, instead} +@scheme[struct] is not exported, the @|unit-struct| from +@schememodname[scheme/unit] is exported, @schememodname[scheme/set] +is not re-exported, and @schememodname[scheme/nest] is re-exported} @compat-except[scheme/base racket/base]{, except that @schememodname[racket]'s @scheme[struct] is not exported, and @@ -111,7 +112,57 @@ must occur after all the @scheme[provide*] forms to which it refers.} @compat[scheme/match racket/match] @compat[scheme/math racket/math] @compat[scheme/mpair racket/mpair] -@compat[scheme/nest racket/nest] + +@;------------------------------------------------------------------------ +@section[#:tag "nest"]{schememodname[scheme/nest]} + +@defmodule[scheme/nest] + +@defform[(nest ([datum ...+] ...) body ...+)]{ + +Combines nested expressions that syntactically drift to the right into +a more linear textual format, much in the same way that @racket[let*] +linearizes a sequence of nested @racket[let] expressions. + +For example, + +@racketblock[ +(nest ([let ([x 10] + [y 6])] + [with-handlers ([exn:fail? (lambda (x) 15)])] + [parameterize ([current-output-port (current-error-port)])] + [let-values ([(d r) (quotient/remainder x y)])]) + (display (+ d r))) +] + +is equivalent to + +@racketblock[ +(let ([x 10] + [y 6]) + (with-handlers ([exn:fail? (lambda (x) 15)]) + (parameterize ([current-output-port (current-error-port)]) + (let-values ([(d r) (quotient/remainder x y)]) + (display (+ d r)))))) +] + +The @racket[nest] form is unusual in that it has no semantics apart +from its expansion, and its implementation is easier to understand +than a precise prose description: + +@racketblock[ +(define-syntax nest + (syntax-rules () + [(nest () body0 body ...) + (let () body0 body ...)] + [(nest ([form forms ...]) body0 body ...) + (form forms ... (let () body0 body ...))] + [(nest ([form forms ...] . more) body0 body ...) + (form forms ... (nest more body0 body ...))])) +]} + +@; ---------------------------------------- + @compat[scheme/package racket/package] @compat[scheme/path racket/path] @compat[scheme/port racket/port] diff --git a/src/gracket/wxs/wxscheme.cxx b/src/gracket/wxs/wxscheme.cxx index 824ea2878e..9cfea49053 100644 --- a/src/gracket/wxs/wxscheme.cxx +++ b/src/gracket/wxs/wxscheme.cxx @@ -2514,10 +2514,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv) if (which == id_init_file) return append_path(home, - scheme_make_path("/.mredrc" + ends_in_slash)); + scheme_make_path("/.gracketrc" + ends_in_slash)); if (which == id_setup_file) return append_path(home, - scheme_make_path("/.mred.resources" + ends_in_slash)); + scheme_make_path("/.gracket.resources" + ends_in_slash)); if (which == id_x_display) { # if defined(wx_x) @@ -2541,10 +2541,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv) if (which == id_init_file) return append_path(home, - scheme_make_path("\\mredrc.ss" + ends_in_slash)); + scheme_make_path("\\gracketrc" + ends_in_slash)); if (which == id_setup_file) return append_path(home, - scheme_make_path("\\mred.ini" + ends_in_slash)); + scheme_make_path("\\gracket.ini" + ends_in_slash)); if (which == id_x_display) return scheme_false; @@ -2584,10 +2584,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv) if (which == id_init_file) return append_path(home, - scheme_make_path(":mredrc.ss" + ends_in_colon)); + scheme_make_path(":gracketrc" + ends_in_colon)); if (which == id_setup_file) return append_path(home, - scheme_make_path(":mred.fnt" + ends_in_colon)); + scheme_make_path(":gracket.fnt" + ends_in_colon)); #endif return scheme_void; @@ -2778,9 +2778,9 @@ int wxGetPreference(const char *name, char *res, long len) if (!ends_in_slash) s[l++] = '/'; # ifdef wx_mac - memcpy(s + l, "org.plt-scheme.prefs.ss", 24); + memcpy(s + l, "org.racket-lang.prefs", 24); # else - memcpy(s + l, "plt-prefs.ss", 13); + memcpy(s + l, "racket-prefs", 13); # endif #endif @@ -2796,7 +2796,7 @@ int wxGetPreference(const char *name, char *res, long len) memcpy(s, home, l); if (!ends_in_slash) s[l++] = '\\'; - memcpy(s + l, "plt-prefs.ss", 13); + memcpy(s + l, "racket-prefs", 13); #endif /*************** Mac OS Classic ***************/ @@ -2825,7 +2825,7 @@ int wxGetPreference(const char *name, char *res, long len) memcpy(s, home, l); if (!ends_in_slash) s[l++] = ':'; - memcpy(s + l, "org.plt-scheme.prefs.ss", 24); + memcpy(s + l, "org.racket-lang.prefs", 24); } #endif diff --git a/src/racket/src/file.c b/src/racket/src/file.c index 366da757bb..704897f40c 100644 --- a/src/racket/src/file.c +++ b/src/racket/src/file.c @@ -5708,7 +5708,7 @@ enum { Scheme_Object *scheme_get_run_cmd(void) { if (!run_cmd) { - return scheme_make_path("mzscheme"); + return scheme_make_path("racket"); } return run_cmd; } @@ -5738,7 +5738,7 @@ find_system_path(int argc, Scheme_Object **argv) which = id_sys_dir; else if (argv[0] == exec_file_symbol) { if (!exec_cmd) { - return scheme_make_path("mzscheme"); + return scheme_make_path("racket"); } return exec_cmd; } else if (argv[0] == run_file_symbol) { @@ -5798,11 +5798,11 @@ find_system_path(int argc, Scheme_Object **argv) || (which == id_addon_dir)) { #if defined(OS_X) && !defined(XONX) if (which == id_addon_dir) - home_str = "~/Library/PLT Scheme/"; + home_str = "~/Library/Racket/"; else home_str = "~/Library/Preferences/"; #else - home_str = "~/.plt-scheme/"; + home_str = "~/.racket/"; #endif } else { #if defined(OS_X) && !defined(XONX) @@ -5836,12 +5836,12 @@ find_system_path(int argc, Scheme_Object **argv) ends_in_slash = (SCHEME_PATH_VAL(home))[SCHEME_PATH_LEN(home) - 1] == '/'; if (which == id_init_file) - return append_path(home, scheme_make_path("/.mzschemerc" + ends_in_slash)); + return append_path(home, scheme_make_path("/.racketrc" + ends_in_slash)); if (which == id_pref_file) { #if defined(OS_X) && !defined(XONX) - return append_path(home, scheme_make_path("/org.plt-scheme.prefs.ss" + ends_in_slash)); + return append_path(home, scheme_make_path("/org.racket-lang.prefs" + ends_in_slash)); #else - return append_path(home, scheme_make_path("/plt-prefs.ss" + ends_in_slash)); + return append_path(home, scheme_make_path("/racket-prefs" + ends_in_slash)); #endif } } @@ -5977,14 +5977,14 @@ find_system_path(int argc, Scheme_Object **argv) if ((which == id_addon_dir) || (which == id_pref_dir) || (which == id_pref_file)) { - home = append_path(home, scheme_make_path("\\PLT Scheme" + ends_in_slash)); + home = append_path(home, scheme_make_path("\\Racket" + ends_in_slash)); ends_in_slash = 0; } if (which == id_init_file) - return append_path(home, scheme_make_path("\\mzschemerc.ss" + ends_in_slash)); + return append_path(home, scheme_make_path("\\racketrc" + ends_in_slash)); if (which == id_pref_file) - return append_path(home, scheme_make_path("\\plt-prefs.ss" + ends_in_slash)); + return append_path(home, scheme_make_path("\\racket-prefs" + ends_in_slash)); return home; } #endif diff --git a/src/racket/src/print.c b/src/racket/src/print.c index 2ff5f6e69d..d452d64dfd 100644 --- a/src/racket/src/print.c +++ b/src/racket/src/print.c @@ -57,6 +57,7 @@ ROSYM Scheme_Object *syntax_symbol; ROSYM Scheme_Object *quasisyntax_symbol; ROSYM Scheme_Object *unsyntax_symbol; ROSYM Scheme_Object *unsyntax_splicing_symbol; +ROSYM Scheme_Object *qq_ellipses; /* Flag for debugging compiled code in printed form: */ #define NO_COMPACT 0 @@ -175,6 +176,7 @@ void scheme_init_print(Scheme_Env *env) REGISTER_SO(quasisyntax_symbol); REGISTER_SO(unsyntax_symbol); REGISTER_SO(unsyntax_splicing_symbol); + REGISTER_SO(qq_ellipses); quote_symbol = scheme_intern_symbol("quote"); quasiquote_symbol = scheme_intern_symbol("quasiquote"); unquote_symbol = scheme_intern_symbol("unquote"); @@ -183,6 +185,7 @@ void scheme_init_print(Scheme_Env *env) quasisyntax_symbol = scheme_intern_symbol("quasisyntax"); unsyntax_symbol = scheme_intern_symbol("unsyntax"); unsyntax_splicing_symbol = scheme_intern_symbol("unsyntax-splicing"); + qq_ellipses = scheme_make_symbol("..."); /* uninterned */ #ifdef MZ_PRECISE_GC register_traversers(); @@ -1836,7 +1839,9 @@ print(Scheme_Object *obj, int notdisplay, int compact, Scheme_Hash_Table *ht, const char *s; if (notdisplay >= 3) { - if (notdisplay == 4) { + if (SAME_OBJ(qq_ellipses, obj)) { + /* no quoting */ + } else if (notdisplay == 4) { if (SAME_OBJ(obj, unquote_symbol) || SAME_OBJ(obj, unquote_splicing_symbol)) print_utf8_string(pp, ",'", 0, 2); @@ -2156,7 +2161,7 @@ print(Scheme_Object *obj, int notdisplay, int compact, Scheme_Hash_Table *ht, Scheme_Object *vec, *prefab; print_compact(pp, CPT_PREFAB); prefab = ((Scheme_Structure *)obj)->stype->prefab_key; - vec = scheme_struct_to_vector(obj, NULL, pp->inspector); + vec = scheme_struct_to_vector(obj, (notdisplay >= 3) ? qq_ellipses : NULL, pp->inspector); SCHEME_VEC_ELS(vec)[0] = SCHEME_CDR(prefab); print_vector(vec, notdisplay, compact, ht, mt, pp, 1); } else if (compact || !pp->print_unreadable) { @@ -2171,7 +2176,7 @@ print(Scheme_Object *obj, int notdisplay, int compact, Scheme_Hash_Table *ht, if (pb) { Scheme_Object *vec, *prefab; prefab = ((Scheme_Structure *)obj)->stype->prefab_key; - vec = scheme_struct_to_vector(obj, NULL, pp->inspector); + vec = scheme_struct_to_vector(obj, (notdisplay >= 3) ? qq_ellipses : NULL, pp->inspector); if ((notdisplay >= 3) && !prefab) { notdisplay = to_unquoted(pp, notdisplay); vec = scheme_vector_to_list(vec);