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

Merge branch 'master' of git.racket-lang.org:plt

Browse Source
This commit is contained in:
Jay McCarthy 2010-04-26 16:04:51 -06:00
commit 9e96937027
39 changed files with 2051 additions and 2044 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/racket/main.rkt
View File

@ -24,7 +24,6 @@
racket/promise racket/promise
racket/bool racket/bool
racket/local racket/local
racket/nest
(for-syntax racket/base)) (for-syntax racket/base))
(provide (all-from-out racket/contract (provide (all-from-out racket/contract
@ -50,6 +49,5 @@
racket/cmdline racket/cmdline
racket/promise racket/promise
racket/bool racket/bool
racket/local racket/local)
racket/nest)
(for-syntax (all-from-out racket/base))) (for-syntax (all-from-out racket/base)))

28
collects/racket/nest.rkt
View File

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

8
collects/racket/pretty.rkt
View File

@ -403,6 +403,7 @@
#t)))) #t))))
(define-struct unquoted (val)) (define-struct unquoted (val))
(define struct-ellipses (string->uninterned-symbol "..."))
(define (generic-write obj display? width pport (define (generic-write obj display? width pport
print-graph? print-struct? print-hash-table? print-vec-length? print-graph? print-struct? print-hash-table? print-vec-length?
@ -737,7 +738,7 @@
obj pport #t obj pport #t
#f #f #f #f
(lambda () (lambda ()
(let* ([v (struct->vector obj)] (let* ([v (struct->vector obj struct-ellipses)]
[pf? (prefab?! obj v)]) [pf? (prefab?! obj v)])
(let ([qd (if pf? (let ([qd (if pf?
(to-quoted out qd "`") (to-quoted out qd "`")
@ -796,7 +797,8 @@
(orig-write obj pport)] (orig-write obj pport)]
[(and qd (or (symbol? obj) [(and qd (or (symbol? obj)
(keyword? obj))) (keyword? obj)))
(to-quoted out qd "'") (unless (eq? obj struct-ellipses)
(to-quoted out qd "'"))
(orig-write obj pport)] (orig-write obj pport)]
[(unquoted? obj) [(unquoted? obj)
(let ([qd (to-unquoted out qd)]) (let ([qd (to-unquoted out qd)])
@ -894,7 +896,7 @@
(let ([qd (to-unquoted out qd)]) (let ([qd (to-unquoted out qd)])
(write-custom pp* obj pport depth display? width qd))] (write-custom pp* obj pport depth display? width qd))]
[(struct? obj) ; print-struct is on if we got here [(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)]) [pf? (prefab?! obj v)])
(let ([qd (if pf? (let ([qd (if pf?
(to-quoted out qd "`") (to-quoted out qd "`")

30
collects/scheme/nest.rkt
View File

@ -1,2 +1,28 @@
#lang scheme/private/provider #lang scheme/base
racket/nest
(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 ...))]))

6
collects/scribble/racket.ss
View File

@ -118,6 +118,8 @@
(define-struct (cached-delayed-element delayed-element) (cache-key)) (define-struct (cached-delayed-element delayed-element) (cache-key))
(define-struct (cached-element element) (cache-key)) (define-struct (cached-element element) (cache-key))
(define qq-ellipses (string->uninterned-symbol "..."))
(define (make-id-element c s) (define (make-id-element c s)
(let* ([key (and id-element-cache (let* ([key (and id-element-cache
(let ([b (identifier-label-binding c)]) (let ([b (identifier-label-binding c)])
@ -201,7 +203,7 @@
is-var?))) is-var?)))
(values (substring s 1) #t #f) (values (substring s 1) #t #f)
(values s #f #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 (let ([quote-depth
(if (and (quote-depth . < . 2) (if (and (quote-depth . < . 2)
(memq (syntax-e c) '(unquote unquote-splicing))) (memq (syntax-e c) '(unquote unquote-splicing)))
@ -956,7 +958,7 @@
(if pf (if pf
(prefab-struct-key v) (prefab-struct-key v)
(object-name v))) (object-name v)))
(cdr (vector->list (struct->vector v))))] (cdr (vector->list (struct->vector v qq-ellipses))))]
[else v])]) [else v])])
(if (null? v) (if (null? v)
null null

2
collects/scribblings/reference/class.scrbl
View File

@ -216,7 +216,7 @@ structure type property's guard, if any).
@defexamples[ @defexamples[
#:eval class-eval #:eval class-eval
(define i (interface* () ([prop:custom-write (define i (interface* () ([prop:custom-write
(lambda (obj port write?) (void))]) (lambda (obj port mode) (void))])
method1 method2 method3)) method1 method2 method3))
]} ]}

210
collects/scribblings/reference/cont.scrbl
View File

@ -4,11 +4,11 @@
@title[#:tag "cont"]{Continuations} @title[#:tag "cont"]{Continuations}
See @secref["cont-model"] and @secref["prompt-model"] for general 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 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 the following contexts, preventing full-continuation jumps across the
barrier: barrier:
@ -30,15 +30,15 @@ barrier:
@item{applying a will procedure (see @secref["willexecutor"]); or} @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"]).} command line (see @secref["running-sa"]).}
] ]
In addition, extensions of PLT Scheme may install barriers in In addition, extensions of Racket may install barriers in
additional contexts. In particular, MrEd installs a continuation additional contexts. In particular, GRacket installs a continuation
barrier around most every callback. Finally, 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. between the application and the current continuation.
@ -49,22 +49,22 @@ between the application and the current continuation.
[arg any/c] ...) [arg any/c] ...)
any]{ 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 continuation extended by a prompt. The prompt is tagged by
@scheme[prompt-tag], which must be a result from either @racket[prompt-tag], which must be a result from either
@scheme[default-continuation-prompt-tag] (the default) or @racket[default-continuation-prompt-tag] (the default) or
@scheme[make-continuation-prompt-tag]. The result of @scheme[proc] is @racket[make-continuation-prompt-tag]. The result of @racket[proc] is
the result of the @scheme[call-with-continuation-prompt] call. 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 called in tail position with respect to the
@scheme[call-with-continuation-prompt] call when the installed prompt @racket[call-with-continuation-prompt] call when the installed prompt
is the target of a @scheme[abort-current-continuation] call with is the target of a @racket[abort-current-continuation] call with
@scheme[prompt-tag]; the remaining arguments of @racket[prompt-tag]; the remaining arguments of
@scheme[abort-current-continuation] are supplied to the handler @racket[abort-current-continuation] are supplied to the handler
procedure. If @scheme[handler] is @scheme[#f], the default handler procedure. If @racket[handler] is @racket[#f], the default handler
accepts a single @scheme[_abort-thunk] argument and calls accepts a single @racket[_abort-thunk] argument and calls
@scheme[(call-with-continuation-prompt _abort-thunk prompt-tag #f)]; @racket[(call-with-continuation-prompt _abort-thunk prompt-tag #f)];
that is, the default handler re-installs the prompt and continues with that is, the default handler re-installs the prompt and continues with
a given thunk.} a given thunk.}
@ -74,24 +74,24 @@ a given thunk.}
any]{ any]{
Resets the current continuation to that of the nearest prompt tagged Resets the current continuation to that of the nearest prompt tagged
by @scheme[prompt-tag] in the current continuation; if no such prompt exists, by @racket[prompt-tag] in the current continuation; if no such prompt exists,
the @exnraise[exn:fail:contract:continuation]. The @scheme[v]s are delivered the @exnraise[exn:fail:contract:continuation]. The @racket[v]s are delivered
as arguments to the target prompt's handler procedure. as arguments to the target prompt's handler procedure.
The protocol for @scheme[v]s supplied to an abort is specific to the The protocol for @racket[v]s supplied to an abort is specific to the
@scheme[prompt-tag]. When @scheme[abort-current-continuation] is used with @racket[prompt-tag]. When @racket[abort-current-continuation] is used with
@scheme[(default-continuation-prompt-tag)], generally a single thunk @racket[(default-continuation-prompt-tag)], generally a single thunk
should be supplied that is suitable for use with the default prompt should be supplied that is suitable for use with the default prompt
handler. Similarly, when @scheme[call-with-continuation-prompt] is handler. Similarly, when @racket[call-with-continuation-prompt] is
used with @scheme[(default-continuation-prompt-tag)], the associated used with @racket[(default-continuation-prompt-tag)], the associated
handler should generally accept a single thunk argument.} handler should generally accept a single thunk argument.}
@defproc*[([(make-continuation-prompt-tag) continuation-prompt-tag?] @defproc*[([(make-continuation-prompt-tag) continuation-prompt-tag?]
[(make-continuation-prompt-tag [sym symbol?]) 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 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.} argument, if supplied, is used when printing the prompt tag.}
@defproc[(default-continuation-prompt-tag) continuation-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 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 start of every thread's continuation; the handler for each thread's
initial prompt accepts any number of values and returns. The result of 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.} any procedure that accepts a prompt tag.}
@defproc[(call-with-current-continuation @defproc[(call-with-current-continuation
@ -108,25 +108,25 @@ any procedure that accepts a prompt tag.}
any]{ any]{
Captures the current continuation up to the nearest prompt tagged by 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 @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. 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 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 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 such prompt exists, the @exnraise[exn:fail:contract:continuation]), or
up to the nearest continuation frame (if any) shared by the current up to the nearest continuation frame (if any) shared by the current
and captured continuations---whichever is first. While removing 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 executed. Finally, the (unshared portion of the) captured continuation
is appended to the remaining continuation, applying 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 The arguments supplied to an applied procedure become the result
values for the restored continuation. In particular, if multiple values for the restored continuation. In particular, if multiple
@ -134,7 +134,7 @@ arguments are supplied, then the continuation receives multiple
results. results.
If, at application time, a continuation barrier appears between the 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 and if the same barrier is not part of the captured continuation, then
the @exnraise[exn:fail:contract:continuation]. 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)]) [prompt-tag continuation-prompt-tag? (default-continuation-prompt-tag)])
any]{ 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 @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)]) [prompt-tag continuation-prompt-tag? (default-continuation-prompt-tag)])
any]{ 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 resulting continuation procedure does not remove any portion of
the current continuation. Instead, application always extends the the current continuation. Instead, application always extends the
current continuation with the captured continuation (without current continuation with the captured continuation (without
installing any prompts other than those be captured in the 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 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].} @exnraise[exn:fail:contract:continuation].}
@defproc[(call-with-escape-continuation @defproc[(call-with-escape-continuation
[proc (continuation? . -> . any)]) [proc (continuation? . -> . any)])
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 called in tail position, and the continuation procedure supplied to
@scheme[proc] can only be called during the dynamic extent of the @racket[proc] can only be called during the dynamic extent of the
@scheme[call-with-escape-continuation] call. A continuation barrier, @racket[call-with-escape-continuation] call. A continuation barrier,
however, never prevents the application of the continuation. however, never prevents the application of the continuation.
Due to the limited applicability of its continuation, Due to the limited applicability of its continuation,
@scheme[call-with-escape-continuation] can be implemented more efficiently @racket[call-with-escape-continuation] can be implemented more efficiently
than @scheme[call-with-current-continuation]. 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 actually a kind of prompt. Escape continuations are provided mainly
for backward compatibility, since they pre-date general prompts in for backward compatibility, since they pre-date general prompts in
PLT Scheme, and because @scheme[call/ec] is often an easy replacement Racket, and because @racket[call/ec] is often an easy replacement
for @scheme[call/cc] to improve performance.} for @racket[call/cc] to improve performance.}
@defproc[(call/ec @defproc[(call/ec
[proc (continuation? . -> . any)]) [proc (continuation? . -> . any)])
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 ...+)]{ @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 ...+)]{ @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]{ @defproc[(call-with-continuation-barrier [thunk (-> any)]) any]{
Applies @scheme[thunk] with a barrier between the application and the Applies @racket[thunk] with a barrier between the application and the
current continuation. The results of @scheme[thunk] are the results of current continuation. The results of @racket[thunk] are the results of
the @scheme[call-with-continuation-barrier] call.} the @racket[call-with-continuation-barrier] call.}
@defproc[(continuation-prompt-available? @defproc[(continuation-prompt-available?
@ -211,20 +211,20 @@ the @scheme[call-with-continuation-barrier] call.}
[cont continuation? (call/cc values)]) [cont continuation? (call/cc values)])
any]{ any]{
Returns @scheme[#t] if @scheme[cont], which must be a continuation, Returns @racket[#t] if @racket[cont], which must be a continuation,
includes a prompt tagged by @scheme[prompt-tag], @scheme[#f] includes a prompt tagged by @racket[prompt-tag], @racket[#f]
otherwise. otherwise.
} }
@defproc[(continuation? [v any/c]) boolean?]{ Return @scheme[#t] if @defproc[(continuation? [v any/c]) boolean?]{ Return @racket[#t] if
@scheme[v] is a continuation as produced by @racket[v] is a continuation as produced by
@scheme[call-with-current-continuation], @racket[call-with-current-continuation],
@scheme[call-with-composable-continuation], or @racket[call-with-composable-continuation], or
@scheme[call-with-escape-continuation], @scheme[#f] otherwise.} @racket[call-with-escape-continuation], @racket[#f] otherwise.}
@defproc[(continuation-prompt-tag? [v any/c]) boolean?]{ @defproc[(continuation-prompt-tag? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a continuation prompt tag as produced by Returns @racket[#t] if @racket[v] is a continuation prompt tag as produced by
@scheme[default-continuation-prompt-tag] or @scheme[make-continuation-prompt-tag].} @racket[default-continuation-prompt-tag] or @racket[make-continuation-prompt-tag].}
@defproc[(dynamic-wind [pre-thunk (-> any)] @defproc[(dynamic-wind [pre-thunk (-> any)]
[value-thunk (-> any)] [value-thunk (-> any)]
@ -232,72 +232,72 @@ Returns @scheme[#t] if @scheme[v] is a continuation prompt tag as produced by
any]{ any]{
Applies its three thunk arguments in order. The value of a Applies its three thunk arguments in order. The value of a
@scheme[dynamic-wind] expression is the value returned by @racket[dynamic-wind] expression is the value returned by
@scheme[value-thunk]. The @scheme[pre-thunk] procedure is invoked @racket[value-thunk]. The @racket[pre-thunk] procedure is invoked
before calling @scheme[value-thunk] and @scheme[post-thunk] is invoked before calling @racket[value-thunk] and @racket[post-thunk] is invoked
after @scheme[value-thunk] returns. The special properties of after @racket[value-thunk] returns. The special properties of
@scheme[dynamic-wind] are manifest when control jumps into or out of @racket[dynamic-wind] are manifest when control jumps into or out of
the @scheme[value-thunk] application (either due to a prompt abort or the @racket[value-thunk] application (either due to a prompt abort or
a continuation invocation): every time control jumps into the a continuation invocation): every time control jumps into the
@scheme[value-thunk] application, @scheme[pre-thunk] is invoked, and @racket[value-thunk] application, @racket[pre-thunk] is invoked, and
every time control jumps out of @scheme[value-thunk], every time control jumps out of @racket[value-thunk],
@scheme[post-thunk] is invoked. (No special handling is performed for @racket[post-thunk] is invoked. (No special handling is performed for
jumps into or out of the @scheme[pre-thunk] and @scheme[post-thunk] jumps into or out of the @racket[pre-thunk] and @racket[post-thunk]
applications.) applications.)
When @scheme[dynamic-wind] calls @scheme[pre-thunk] for normal When @racket[dynamic-wind] calls @racket[pre-thunk] for normal
evaluation of @scheme[value-thunk], the continuation of the evaluation of @racket[value-thunk], the continuation of the
@scheme[pre-thunk] application calls @scheme[value-thunk] (with @racket[pre-thunk] application calls @racket[value-thunk] (with
@scheme[dynamic-wind]'s special jump handling) and then @racket[dynamic-wind]'s special jump handling) and then
@scheme[post-thunk]. Similarly, the continuation of the @racket[post-thunk]. Similarly, the continuation of the
@scheme[post-thunk] application returns the value of the preceding @racket[post-thunk] application returns the value of the preceding
@scheme[value-thunk] application to the continuation of the entire @racket[value-thunk] application to the continuation of the entire
@scheme[dynamic-wind] application. @racket[dynamic-wind] application.
When @scheme[pre-thunk] is called due to a continuation jump, the When @racket[pre-thunk] is called due to a continuation jump, the
continuation of @scheme[pre-thunk] continuation of @racket[pre-thunk]
@itemize[ @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} to the destination continuation; then}
@item{continues with the context of the @scheme[pre-thunk]'s @item{continues with the context of the @racket[pre-thunk]'s
@scheme[dynamic-wind] call.} @racket[dynamic-wind] call.}
] ]
Normally, the second part of this continuation is never reached, due Normally, the second part of this continuation is never reached, due
to a jump in the first part. However, the second part is relevant to a jump in the first part. However, the second part is relevant
because it enables jumps to escape continuations that are contained in 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 that the continuation marks (see @secref["contmarks"]) and
parameterization (see @secref["parameters"]) for @scheme[pre-thunk] parameterization (see @secref["parameters"]) for @racket[pre-thunk]
correspond to those of the @scheme[dynamic-wind] call that installed correspond to those of the @racket[dynamic-wind] call that installed
@scheme[pre-thunk]. The @scheme[pre-thunk] call, however, is @racket[pre-thunk]. The @racket[pre-thunk] call, however, is
@scheme[parameterize-break]ed to disable breaks (see also @racket[parameterize-break]ed to disable breaks (see also
@secref["breakhandler"]). @secref["breakhandler"]).
Similarly, when @scheme[post-thunk] is called due to a continuation Similarly, when @racket[post-thunk] is called due to a continuation
jump, the continuation of @scheme[post-thunk] jumps to a less deeply jump, the continuation of @racket[post-thunk] jumps to a less deeply
nested @scheme[post-thunk], if any, or jumps to a @scheme[pre-thunk] nested @racket[post-thunk], if any, or jumps to a @racket[pre-thunk]
protecting the destination, if any, or jumps to the destination protecting the destination, if any, or jumps to the destination
continuation, then continues from the @scheme[post-thunk]'s continuation, then continues from the @racket[post-thunk]'s
@scheme[dynamic-wind] application. As for @scheme[pre-thunk], the @racket[dynamic-wind] application. As for @racket[pre-thunk], the
parameterization of the original @scheme[dynamic-wind] call is parameterization of the original @racket[dynamic-wind] call is
restored for the call, and the call is @scheme[parameterize-break]ed restored for the call, and the call is @racket[parameterize-break]ed
to disable breaks. to disable breaks.
In both cases, the target for a jump is recomputed after each 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 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 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 different when the continuation is applied than when the continuation
was captured. There may even be no appropriate target, if a relevant was captured. There may even be no appropriate target, if a relevant
prompt or escape continuation is not in the continuation after the prompt or escape continuation is not in the continuation after the
restore; in that case, the first step in a @scheme[pre-thunk] or restore; in that case, the first step in a @racket[pre-thunk] or
@scheme[post-thunk]'s continuation can raise an exception. @racket[post-thunk]'s continuation can raise an exception.
@examples[ @examples[
(let ([v (let/ec out (let ([v (let/ec out

55
collects/scribblings/reference/contracts.scrbl
View File

@ -647,37 +647,36 @@ As an example, consider the following module:
@(begin @(begin
#reader scribble/comment-reader #reader scribble/comment-reader
[schemeblock [racketmod
(module product mzscheme racket
(require mzlib/contract)
(define-contract-struct kons (hd tl)) (define-contract-struct kons (hd tl))
;; @scheme[sorted-list/gt : number -> contract] ;; @scheme[sorted-list/gt : number -> contract]
;; produces a contract that accepts ;; produces a contract that accepts
;; sorted kons-lists whose elements ;; sorted kons-lists whose elements
;; are all greater than @scheme[num]. ;; are all greater than @scheme[num].
(define (sorted-list/gt num) (define (sorted-list/gt num)
(or/c null? (or/c null?
(kons/dc [hd (>=/c num)] (kons/dc [hd (>=/c num)]
[tl (hd) (sorted-list/gt hd)]))) [tl (hd) (sorted-list/gt hd)])))
;; @scheme[product : kons-list -> number] ;; @scheme[product : kons-list -> number]
;; computes the product of the values ;; computes the product of the values
;; in the list. if the list contains ;; in the list. if the list contains
;; zero, it avoids traversing the rest ;; zero, it avoids traversing the rest
;; of the list. ;; of the list.
(define (product l) (define (product l)
(cond (cond
[(null? l) 1] [(null? l) 1]
[else [else
(if (zero? (kons-hd l)) (if (zero? (kons-hd l))
0 0
(* (kons-hd l) (* (kons-hd l)
(product (kons-tl l))))])) (product (kons-tl l))))]))
(provide kons? make-kons kons-hd kons-tl) (provide kons? make-kons kons-hd kons-tl)
(provide/contract [product (-> (sorted-list/gt -inf.0) number?)])) (provide/contract [product (-> (sorted-list/gt -inf.0) number?)])
]) ])
The module provides a single function, @scheme[product] whose contract The module provides a single function, @scheme[product] whose contract

80
collects/scribblings/reference/custodians.scrbl
View File

@ -5,35 +5,35 @@
@title[#:tag "custodians"]{Custodians} @title[#:tag "custodians"]{Custodians}
See @secref["custodian-model"] for basic information on the PLT See @secref["custodian-model"] for basic information on the Racket
Scheme custodian model. custodian model.
@defproc[(custodian? [v any/c]) boolean?]{ @defproc[(custodian? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{custodian} value, Returns @racket[#t] if @racket[v] is a @tech{custodian} value,
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defproc[(make-custodian [cust custodian? (current-custodian)]) custodian?]{ @defproc[(make-custodian [cust custodian? (current-custodian)]) custodian?]{
Creates a new custodian that is subordinate to @scheme[cust]. When Creates a new custodian that is subordinate to @racket[cust]. When
@scheme[cust] is directed (via @scheme[custodian-shutdown-all]) to @racket[cust] is directed (via @racket[custodian-shutdown-all]) to
shut down all of its managed values, the new subordinate custodian is shut down all of its managed values, the new subordinate custodian is
automatically directed to shut down its managed values as well.} automatically directed to shut down its managed values as well.}
@defproc[(custodian-shutdown-all [cust custodian?]) void?]{ @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.} shut down.}
Closes all @tech{file-stream ports}, @tech{TCP ports}, @tech{TCP 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 (and its subordinates), and empties all @tech{custodian box}es
associated with @scheme[cust] (and its subordinates). It also removes associated with @racket[cust] (and its subordinates). It also removes
@scheme[cust] (and its subordinates) as managers of all threads; when @racket[cust] (and its subordinates) as managers of all threads; when
a thread has no managers, it is killed (or suspended; see 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 killed, all other shut-down actions take place before killing the
thread.} thread.}
@ -50,45 +50,45 @@ for newly created threads, @tech{file-stream ports}, TCP ports,
@defproc[(custodian-managed-list [cust custodian?][super custodian?]) list?]{ @defproc[(custodian-managed-list [cust custodian?][super custodian?]) list?]{
Returns a list of immediately managed objects (not including Returns a list of immediately managed objects (not including
@tech{custodian box}es) and subordinate custodians for @scheme[cust], @tech{custodian box}es) and subordinate custodians for @racket[cust],
where @scheme[cust] is itself subordinate to @scheme[super] (directly where @racket[cust] is itself subordinate to @racket[super] (directly
or indirectly). If @scheme[cust] is not strictly subordinate to or indirectly). If @racket[cust] is not strictly subordinate to
@scheme[super], the @exnraise[exn:fail:contract].} @racket[super], the @exnraise[exn:fail:contract].}
@defproc[(custodian-memory-accounting-available?) boolean?]{ @defproc[(custodian-memory-accounting-available?) boolean?]{
@margin-note{Memory accounting is normally available in PLT Scheme 3m, @margin-note{Memory accounting is normally available in Racket 3m,
which is the main variant of PLT Scheme, and not normally available in which is the main variant of Racket, and not normally available in
PLT Scheme CGC.} Racket CGC.}
Returns @scheme[#t] if PLT Scheme is compiled with support for Returns @racket[#t] if Racket is compiled with support for
per-custodian memory accounting, @scheme[#f] otherwise.} per-custodian memory accounting, @racket[#f] otherwise.}
@defproc[(custodian-require-memory [limit-cust custodian?] @defproc[(custodian-require-memory [limit-cust custodian?]
[need-amt exact-nonnegative-integer?] [need-amt exact-nonnegative-integer?]
[stop-cust custodian?]) void?]{ [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 support for per-custodian memory accounting, otherwise the
@exnraise[exn:fail:unsupported]. @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 garbage collection (see @secref["gc-model"]) where allocating
@scheme[need-amt] bytes charged to @scheme[limit-cust] would fail or @racket[need-amt] bytes charged to @racket[limit-cust] would fail or
trigger some shutdown, then @scheme[stop-cust] is shut down.} trigger some shutdown, then @racket[stop-cust] is shut down.}
@defproc[(custodian-limit-memory [limit-cust custodian?] @defproc[(custodian-limit-memory [limit-cust custodian?]
[limit-amt exact-nonnegative-integer?] [limit-amt exact-nonnegative-integer?]
[stop-cust custodian? limit-cust]) void?]{ [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 support for per-custodian memory accounting, otherwise the
@exnraise[exn:fail:unsupported]. @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 after garbage collection (see @secref["gc-model"]) where
@scheme[limit-cust] owns more than @scheme[limit-amt] bytes, then @racket[limit-cust] owns more than @racket[limit-amt] bytes, then
@scheme[stop-cust] is shut down. @racket[stop-cust] is shut down.
@margin-note{A custodian's limit is checked only after a garbage @margin-note{A custodian's limit is checked only after a garbage
collection, except that it may also be checked during 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 only one of the custodians would have reduced memory use
for other custodians.} for other custodians.}
For reliable shutdown, @scheme[limit-amt] for For reliable shutdown, @racket[limit-amt] for
@scheme[custodian-limit-memory] must be much lower than the total @racket[custodian-limit-memory] must be much lower than the total
amount of memory available (minus the size of memory that is 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 individual allocations that are initially charged to
@scheme[limit-cust] can be arbitrarily large, then @scheme[stop-cust] @racket[limit-cust] can be arbitrarily large, then @racket[stop-cust]
must be the same as @scheme[limit-cust], so that excessively large must be the same as @racket[limit-cust], so that excessively large
immediate allocations can be rejected with an 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?]{ @defproc[(make-custodian-box [cust custodian?][v any/c]) custodian-box?]{
Returns a @tech{custodian box} that contains @scheme[v] as long as Returns a @tech{custodian box} that contains @racket[v] as long as
@scheme[cust] has not been shut down.} @racket[cust] has not been shut down.}
@defproc[(custodian-box? [v any/c]) boolean?]{Returns @scheme[#t] if @defproc[(custodian-box? [v any/c]) boolean?]{Returns @racket[#t] if
@scheme[v] is a @tech{custodian box} produced by @racket[v] is a @tech{custodian box} produced by
@scheme[make-custodian-box], @scheme[#f] otherwise.} @racket[make-custodian-box], @racket[#f] otherwise.}
@defproc[(custodian-box-value [cb custodian-box?]) any]{Returns the @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.} has been removed.}

4
collects/scribblings/reference/define-struct.scrbl
View File

@ -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 @racket[#:property] is a syntax error. If a supertype is specified, it
must also be a @tech{prefab} structure type. 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 binding} of @scheme[id] records @scheme[constructor-id] as the
constructor binding; as a result, for example, @scheme[struct-out] constructor binding; as a result, for example, @scheme[struct-out]
includes @racket[constructor-id] as an export. If includes @racket[constructor-id] as an export. If
@racket[constructor-id] is supplied via @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[object-name] on the constructor produces the symbolic form of
@racket[id] rather than @racket[constructor-id]. If @racket[id] rather than @racket[constructor-id]. If
@racket[constructor-id] is supplied via @racket[#:constructor-name] @racket[constructor-id] is supplied via @racket[#:constructor-name]

601
collects/scribblings/reference/filesystem.scrbl
View File

File diff suppressed because it is too large Load Diff

72
collects/scribblings/reference/logging.scrbl
View File

@ -9,9 +9,9 @@ logged for interested parties. A @deftech{log receiver} represents an
interested party that receives logged events asynchronously. Each interested party that receives logged events asynchronously. Each
event has a level of importance, and a @tech{log receiver} subscribes to event has a level of importance, and a @tech{log receiver} subscribes to
logging events at a certain level of importance and higher. The logging events at a certain level of importance and higher. The
levels, in decreasing order of importance, are @scheme['fatal], levels, in decreasing order of importance, are @racket['fatal],
@scheme['error], @scheme['warning], @scheme['info], and @racket['error], @racket['warning], @racket['info], and
@scheme['debug]. @racket['debug].
To help organize logged events, @tech{loggers} can be named and To help organize logged events, @tech{loggers} can be named and
hierarchical. Every event reported to a logger is also propagated to 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 (if any) of the logger to which is was originally reported. A logger
is not required to have a parent or name. 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 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 @secref["gc-model"]). For this initial logger, two log receivers are
also created: one that writes events to the process's original error 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 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 defined and is not overridden by a command-line flag, it
determines the level of the @tech{log receiver} that propagates determines the level of the @tech{log receiver} that propagates
events to the original error port. The environment variable's value events to the original error port. The environment variable's value
should be @scheme["none"], @scheme["fatal"], @scheme["error"], should be @racket["none"], @racket["fatal"], @racket["error"],
@scheme["warning"], @scheme["info"], or @scheme["debug"]. @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 @item{If the @indexed-envvar{PLTSYSLOG} environment variable is
defined and is not overridden by a command-line flag, it 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 events to the system log. The possible values are the
same as for @envvar{PLTSYSLOG}. 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.} 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 @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 is the initial logger. The run-time system sometimes uses the current
logger to report events. For example, the bytecode compiler sometimes 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. 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?]{ @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.} otherwise.}
@ -77,7 +77,7 @@ Creates a new logger with an optional name and parent.}
@defproc[(logger-name [logger logger?]) (or/c symbol? #f)]{ @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?]{ @defparam[current-logger logger logger?]{
@ -93,13 +93,13 @@ A @tech{parameter} that determines the @tech{current logger}.}
[data any/c]) [data any/c])
void?]{ void?]{
Reports an event to @scheme[logger], which in turn distributes the Reports an event to @racket[logger], which in turn distributes the
information to any @tech{log receivers} attached to @scheme[logger] or information to any @tech{log receivers} attached to @racket[logger] or
its ancestors that are interested in events at @scheme[level] or its ancestors that are interested in events at @racket[level] or
higher. higher.
If @scheme[logger] has a name, then @scheme[message] is prefixed with If @racket[logger] has a name, then @racket[message] is prefixed with
the logger's name followed by @scheme[": "] before it is sent to the logger's name followed by @racket[": "] before it is sent to
receivers.} receivers.}
@ -107,13 +107,13 @@ receivers.}
[level (or/c 'fatal 'error 'warning 'info 'debug)]) [level (or/c 'fatal 'error 'warning 'info 'debug)])
boolean?]{ boolean?]{
Reports whether any @tech{log receiver} attached to @scheme[logger] or Reports whether any @tech{log receiver} attached to @racket[logger] or
one of its ancestors is interested in @scheme[level] events (or one of its ancestors is interested in @racket[level] events (or
potentially lower). Use this function to avoid work generating an potentially lower). Use this function to avoid work generating an
event for @scheme[log-message] if no receiver is interested in the event for @racket[log-message] if no receiver is interested in the
information; this shortcut is built into @scheme[log-fatal], information; this shortcut is built into @racket[log-fatal],
@scheme[log-error], @scheme[log-warning], @scheme[log-info], and @racket[log-error], @racket[log-warning], @racket[log-info], and
@scheme[log-debug], however, so it should not be used with those @racket[log-debug], however, so it should not be used with those
forms. forms.
The result of this function can change if a garbage collection 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 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 interested in the event. In addition, the current continuation's
@tech{continuation marks} are sent to the logger with the message @tech{continuation marks} are sent to the logger with the message
string. string.
For each @schemekeywordfont{log-}@scheme[_level], For each @racketkeywordfont{log-}@racket[_level],
@schemeblock[ @racketblock[
(@#,schemekeywordfont{log-}_level string-expr) (@#,racketkeywordfont{log-}_level string-expr)
] ]
is equivalent to is equivalent to
@schemeblock[ @racketblock[
(let ([l (current-logger)]) (let ([l (current-logger)])
(when (log-level? l '@#,scheme[_level]) (when (log-level? l '@#,racket[_level])
(log-message l '@#,scheme[_level] string-expr (log-message l '@#,racket[_level] string-expr
(current-continuation-marks)))) (current-continuation-marks))))
]} ]}
@ -154,7 +154,7 @@ is equivalent to
@defproc[(log-receiver? [v any/c]) boolean?]{ @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.} otherwise.}
@defproc[(make-log-receiver [logger logger?] @defproc[(make-log-receiver [logger logger?]
@ -162,13 +162,13 @@ otherwise.}
log-receiver?]{ log-receiver?]{
Creates a @tech{log receiver} to receive events of importance 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. descendants.
A @tech{log receiver} is a @tech{synchronizable event}. It becomes A @tech{log receiver} is a @tech{synchronizable event}. It becomes
ready as an @tech{synchronizable event} when a logging event is 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 @tech{log receiver}'s synchronization value is a vector containing
three values: the level of the event as a symbol, an immutable string 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 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.}

198
collects/scribblings/reference/module-reflect.scrbl
View File

@ -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 module path}, which encapsulates either a symbol or a complete
filesystem path (see @secref["pathutils"]). A symbol normally refers filesystem path (see @secref["pathutils"]). A symbol normally refers
to a predefined module or module declared through reflective to a predefined module or module declared through reflective
evaluation (e.g., @scheme[eval]). A filesystem path normally refers to evaluation (e.g., @racket[eval]). A filesystem path normally refers to
a module declaration that was loaded on demand via @scheme[require] or a module declaration that was loaded on demand via @racket[require] or
other forms. other forms.
A @deftech{module path} is a datum that matches the grammar for 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. to another module.
@defproc[(resolved-module-path? [v any/c]) boolean?]{ @defproc[(resolved-module-path? [v any/c]) boolean?]{
Returns @scheme[#f] if @scheme[v] is a @tech{resolved module path}, Returns @racket[#f] if @racket[v] is a @tech{resolved module path},
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defproc[(make-resolved-module-path [path (or/c symbol? (and/c path? complete-path?))]) @defproc[(make-resolved-module-path [path (or/c symbol? (and/c path? complete-path?))])
resolved-module-path?]{ resolved-module-path?]{
Returns a @tech{resolved module path} that encapsulates @scheme[path]. Returns a @tech{resolved module path} that encapsulates @racket[path].
If @scheme[path] is not a symbol, it normally should be If @racket[path] is not a symbol, it normally should be
@tech{cleanse}d (see @scheme[cleanse-path]) and simplified (see @tech{cleanse}d (see @racket[cleanse-path]) and simplified (see
@scheme[simplify-path]). @racket[simplify-path]).
A @tech{resolved module path} is interned. That is, if two A @tech{resolved module path} is interned. That is, if two
@tech{resolved module path} values encapsulate paths that are @tech{resolved module path} values encapsulate paths that are
@scheme[equal?], then the @tech{resolved module path} values are @racket[equal?], then the @tech{resolved module path} values are
@scheme[eq?].} @racket[eq?].}
@defproc[(resolved-module-path-name [module-path resolved-module-path?]) @defproc[(resolved-module-path-name [module-path resolved-module-path?])
(or/c path? symbol?)]{ (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?]{ @defproc[(module-path? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] corresponds to a datum that matches Returns @racket[#t] if @racket[v] corresponds to a datum that matches
the grammar for @scheme[_module-path] for @scheme[require], the grammar for @racket[_module-path] for @racket[require],
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defparam[current-module-name-resolver proc @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 A parameter that determines the current @deftech{module name
resolver}, which manages the conversion from other kinds of module resolver}, which manages the conversion from other kinds of module
references to a @tech{resolved module path}. For example, references to a @tech{resolved module path}. For example,
when the expander encounters @scheme[(require _module-path)] where when the expander encounters @racket[(require _module-path)] where
@scheme[_module-path] is not an identifier, then the expander passes @racket[_module-path] is not an identifier, then the expander passes
@scheme['_module-path] to the module name resolver to obtain a symbol @racket['_module-path] to the module name resolver to obtain a symbol
or resolved module path. When such a @scheme[require] appears within a or resolved module path. When such a @racket[require] appears within a
module, the @deftech{module path resolver} is also given the name of module, the @deftech{module path resolver} is also given the name of
the enclosing module, so that a relative reference can be converted to the enclosing module, so that a relative reference can be converted to
an absolute symbol or @tech{resolved module path}. an absolute symbol or @tech{resolved module path}.
@ -81,14 +81,14 @@ A @tech{module name resolver} takes one and four arguments:
is ignored.} is ignored.}
@item{When given four arguments, the first is a module path, either @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 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 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 (current-load-relative-directory) (current-directory))]. The third
argument is a @tech{syntax object} that can be used for error argument is a @tech{syntax object} that can be used for error
reporting, if it is not @scheme[#f]. If the last argument is reporting, if it is not @racket[#f]. If the last argument is
@scheme[#t], then the module declaration should be loaded (if it is @racket[#t], then the module declaration should be loaded (if it is
not already), otherwise the module path should be simply resolved to not already), otherwise the module path should be simply resolved to
a name. The result is the resolved name.} 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 For the second case, the standard module name resolver keeps a
per-registry table of loaded module name. If a resolved module path is 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 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 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}. @tech{compiled-load handler}.
While loading a file, the default @tech{module name resolver} sets the 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 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 @tech{module name resolver} records in a private @tech{continuation
mark} the module being loaded, and it checks whether such a mark mark} the module being loaded, and it checks whether such a mark
already exists; if such a continuation mark does exist in the current already exists; if such a continuation mark does exist in the current
continuation, then the @exnraise[exn:fail] with a message about a continuation, then the @exnraise[exn:fail] with a message about a
dependency cycle. 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 argument to the module name resolver) when resolving module paths in
@tech{syntax objects} (see @secref["stxobj-model"]). When a @tech{syntax objects} (see @secref["stxobj-model"]). When a
@tech{syntax object} is manipulated, the current namespace might not @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. should not necessarily be loaded in the current namespace.
The current module name resolver is called with a single argument by 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 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 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.} avoid redundant module loads.}
@defparam[current-module-declare-name name (or/c resolved-module-path? #f)]{ @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 parameter that determines a module name that is used when evaluating
a @scheme[module] declaration (when the parameter value is not a @racket[module] declaration (when the parameter value is not
@scheme[#f]). In that case, the @scheme[_id] from the @scheme[module] @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 declaration is ignored, and the parameter's value is used as the name
of the declared module.} of the declared module.}
@defparam[current-module-declare-source src (or/c symbol? (and/c path? complete-path?) #f)]{ @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 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 information is used in error messages and reflected by
@scheme[variable-reference->module-source]. When the parameter value @racket[variable-reference->module-source]. When the parameter value
is @scheme[#f], the module's name (as determined by is @racket[#f], the module's name (as determined by
@scheme[current-module-declare-name]) is used as the source name @racket[current-module-declare-name]) is used as the source name
instead of the parameter value.} instead of the parameter value.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "modpathidx"]{Compiled Modules and References} @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 module paths for imports to load module declarations as necessary and
to determine imported bindings, but the compiled form of a 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, Consequently, a compiled module can be moved to another filesystem,
where the module name resolver can resolve inter-module references where the module name resolver can resolve inter-module references
among compiled code. among compiled code.
When a module reference is extracted from compiled form (see 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 expansion (see @secref["stxops"]), the module reference is reported in
the form of a @deftech{module path index}. A @tech{module path index} the form of a @deftech{module path index}. A @tech{module path index}
is a semi-interned (multiple references to the same relative module is a semi-interned (multiple references to the same relative module
tend to use the same @tech{module path index} value, but not always) 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 and either a @tech{resolved module path} or another @tech{module path
index} to which it is relative. 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 base @tech{module path index} represents ``self''---i.e., the module
declaration that was the source of the @tech{module path index}---and 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 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 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 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 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}. ``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?]{ @defproc[(module-path-index? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{module path index}, Returns @racket[#t] if @racket[v] is a @tech{module path index},
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defproc[(module-path-index-resolve [mpi module-path-index?]) @defproc[(module-path-index-resolve [mpi module-path-index?])
resolved-module-path?]{ resolved-module-path?]{
Returns a @tech{resolved module path} for the resolved module name, 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. not been computed before.
Resolving a @tech{module path index} uses the current @tech{module Resolving a @tech{module path index} uses the current @tech{module
name resolver} (see @scheme[current-module-name-resolver]). Depending name resolver} (see @racket[current-module-name-resolver]). Depending
on the kind of module paths encapsulated by @scheme[mpi], the computed on the kind of module paths encapsulated by @racket[mpi], the computed
resolved name can depend on the value of resolved name can depend on the value of
@scheme[current-load-relative-directory] or @racket[current-load-relative-directory] or
@scheme[current-directory].} @racket[current-directory].}
@defproc[(module-path-index-split [mpi module-path-index?]) @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))]{ (or/c module-path-index? resolved-module-path? #f))]{
Returns two values: a module path, and a base @tech{module path index} 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 unspecified directory (i.e., its resolution depends on the value of
@scheme[current-load-relative-directory] and/or @racket[current-load-relative-directory] and/or
@scheme[current-directory]). @racket[current-directory]).
A @scheme[#f] for the first result implies a @scheme[#f] for the A @racket[#f] for the first result implies a @racket[#f] for the
second result, and means that @scheme[mpi] represents ``self'' (see second result, and means that @racket[mpi] represents ``self'' (see
above).} above).}
@defproc[(module-path-index-join [path (or/c module-path? #f)] @defproc[(module-path-index-join [path (or/c module-path? #f)]
[mpi (or/c module-path-index? resolved-module-path? #f)]) [mpi (or/c module-path-index? resolved-module-path? #f)])
module-path-index?]{ module-path-index?]{
Combines @scheme[path] and @scheme[mpi] to create a new @tech{module Combines @racket[path] and @racket[mpi] to create a new @tech{module
path index}. The @scheme[path] argument can @scheme[#f] only if path index}. The @racket[path] argument can @racket[#f] only if
@scheme[mpi] is also @scheme[#f].} @racket[mpi] is also @racket[#f].}
@defproc[(compiled-module-expression? [v any/c]) boolean?]{ @defproc[(compiled-module-expression? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a compiled @scheme[module] Returns @racket[#t] if @racket[v] is a compiled @racket[module]
declaration, @scheme[#f] otherwise. See also declaration, @racket[#f] otherwise. See also
@scheme[current-compile].} @racket[current-compile].}
@defproc[(module-compiled-name [compiled-module-code compiled-module-expression?]) @defproc[(module-compiled-name [compiled-module-code compiled-module-expression?])
@ -256,7 +256,7 @@ the module's declared name.}
(listof module-path-index?)))]{ (listof module-path-index?)))]{
Takes a module declaration in compiled form and returns an association 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 to a shift into the @tech{label phase level}) to module references for
the module's explicit imports.} the module's explicit imports.}
@ -266,16 +266,16 @@ the module's explicit imports.}
(listof (cons/c (or/c exact-integer? #f) list?)))] (listof (cons/c (or/c exact-integer? #f) list?)))]
Returns two association lists mapping @tech{phase level} values (where 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 the corresponding phase. The first association list is for exported
variables, and the second is for exported syntax. Beware however, that variables, and the second is for exported syntax. Beware however, that
value bindings re-exported though a @tech{rename transformer} are in value bindings re-exported though a @tech{rename transformer} are in
the syntax list instead of the value list. 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 result contracts above, more precisely matches the contract
@schemeblock[ @racketblock[
(listof (list/c symbol? (listof (list/c symbol?
(listof (listof
(or/c module-path-index? (or/c module-path-index?
@ -290,19 +290,19 @@ export.
The second part---the list of @tech{module path index} values, The second part---the list of @tech{module path index} values,
etc.---describes the origin of the exported identifier. If the origin 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 module. If the exported identifier is re-exported, instead, then the
origin list provides information on the import that was re-exported. origin list provides information on the import that was re-exported.
The origin list has more than one element if the binding was imported The origin list has more than one element if the binding was imported
multiple times from (possibly) different sources. multiple times from (possibly) different sources.
For each origin, a @tech{module path index} by itself means that the 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] binding was imported with a @tech{phase level} shift of @racket[0]
(i.e., a plain @scheme[require] without @scheme[for-meta], (i.e., a plain @racket[require] without @racket[for-meta],
@scheme[for-syntax], etc.), and imported identifier has the same name @racket[for-syntax], etc.), and imported identifier has the same name
as the re-exported name. An origin represented with a list indicates as the re-exported name. An origin represented with a list indicates
explicitly the import, the import @tech{phase level} shift (where 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 name of the re-exported binding, and the @tech{phase level} of the
import.} import.}
@ -311,19 +311,19 @@ import.}
Returns information intended to reflect the ``language'' of the Returns information intended to reflect the ``language'' of the
module's implementation as originally attached to the syntax of the module's implementation as originally attached to the syntax of the
module's declaration though the @indexed-scheme['module-language] module's declaration though the @indexed-racket['module-language]
@tech{syntax property}. See also @scheme[module]. @tech{syntax property}. See also @racket[module].
If no information is available for the module, the result is If no information is available for the module, the result is
@scheme[#f]. Otherwise, the result is @scheme[(vector _mp _name _val)] @racket[#f]. Otherwise, the result is @racket[(vector _mp _name _val)]
such that @scheme[((dynamic-require _mp _name) _val)] should return such that @racket[((dynamic-require _mp _name) _val)] should return
function that takes two arguments. The function's arguments are a key function that takes two arguments. The function's arguments are a key
for reflected information and a default value. Acceptable keys and for reflected information and a default value. Acceptable keys and
the interpretation of results is up to external tools, such as 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. 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 () ....)]) [fail-thunk (-> any) (lambda () ....)])
any]{ 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 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 phase}, if it is not yet @tech{instantiate}d. The current @tech{module
name resolver} may load a module declaration to resolve @scheme[mod] name resolver} may load a module declaration to resolve @racket[mod]
(see @scheme[current-module-name-resolver]); the path is resolved (see @racket[current-module-name-resolver]); the path is resolved
relative to @scheme[current-load-relative-directory] and/or relative to @racket[current-load-relative-directory] and/or
@scheme[current-directory]. @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 and the module is not @tech{visit}ed (see @secref["mod-parse"]) or
even made @tech{available} (for on-demand @tech{visits}) in phases even made @tech{available} (for on-demand @tech{visits}) in phases
above the @tech{base phase}. 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 with the given name is returned, and still the module is not
@tech{visit}ed or made @tech{available} in higher phases. If the @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 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 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 namespace. If the module has no such exported variable or syntax, then
@scheme[fail-thunk] is called; the default @scheme[fail-thunk] raises @racket[fail-thunk] is called; the default @racket[fail-thunk] raises
@scheme[exn:fail:contract]. If the variable named by @scheme[provided] @racket[exn:fail:contract]. If the variable named by @racket[provided]
is exported protected (see @secref["modprotect"]), then the is exported protected (see @secref["modprotect"]), then the
@exnraise[exn:fail:contract]. @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 @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. 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"]), @tech{visit}ed but not @tech{instantiate}d (see @secref["mod-parse"]),
and the result is @|void-const|.} and the result is @|void-const|.}
@ -374,7 +374,7 @@ and the result is @|void-const|.}
[fail-thunk (-> any) (lambda () ....)]) [fail-thunk (-> any) (lambda () ....)])
any]{ 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}.} 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))]{ (or/c #f (vector/c module-path? symbol? any/c))]{
Returns information intended to reflect the ``language'' of the Returns information intended to reflect the ``language'' of the
implementation of @scheme[mod]. If @scheme[load?] is @scheme[#f], the implementation of @racket[mod]. If @racket[load?] is @racket[#f], the
module named by @scheme[mod] must be declared (but not necessarily module named by @racket[mod] must be declared (but not necessarily
@tech{instantiate}d or @tech{visit}ed) in the current namespace; @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 and other functions). The information returned by
@scheme[module->language-info] is the same as would have been returned @racket[module->language-info] is the same as would have been returned
by @scheme[module-compiled-language-info] applied to the module's by @racket[module-compiled-language-info] applied to the module's
implementation as compiled code.} implementation as compiled code.}
@ -399,8 +399,8 @@ implementation as compiled code.}
(listof (cons/c (or/c exact-integer? #f) (listof (cons/c (or/c exact-integer? #f)
(listof module-path-index?)))]{ (listof module-path-index?)))]{
Like @scheme[module-compiled-imports], but produces the imports of Like @racket[module-compiled-imports], but produces the imports of
@scheme[mod], which must be declared (but not necessarily @racket[mod], which must be declared (but not necessarily
@tech{instantiate}d or @tech{visit}ed) in the current namespace.} @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?)) (values (listof (cons/c (or/c exact-integer? #f) list?))
(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 Like @racket[module-compiled-exports], but produces the exports of
@scheme[mod], which must be declared (but not necessarily @racket[mod], which must be declared (but not necessarily
@tech{instantiate}d or @tech{visit}ed) in the current namespace.} @tech{instantiate}d or @tech{visit}ed) in the current namespace.}

348
collects/scribblings/reference/paths.scrbl
View File

@ -3,36 +3,36 @@
@title[#:tag "pathutils" #:style 'toc]{Paths} @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 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 @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. filesystem path always generates a @tech{path} value.
By default, paths are created and manipulated for the current By default, paths are created and manipulated for the current
platform, but procedures that merely manipulate paths (without using platform, but procedures that merely manipulate paths (without using
the filesystem) can manipulate paths using conventions for other 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 optional argument that indicates the platform for the path, either
@scheme['unix] or @scheme['windows]. For other functions, such as @racket['unix] or @racket['windows]. For other functions, such as
@scheme[build-path] or @scheme[simplify-path], the behavior is @racket[build-path] or @racket[simplify-path], the behavior is
sensitive to the kind of path that is supplied. Unless otherwise sensitive to the kind of path that is supplied. Unless otherwise
specified, a procedure that requires a path accepts only paths for the specified, a procedure that requires a path accepts only paths for the
current platform. 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 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 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 string containing nul is provided as a path to any procedure except
@scheme[absolute-path?], @scheme[relative-path?], or @racket[absolute-path?], @racket[relative-path?], or
@scheme[complete-path?], the @exnraise[exn:fail:contract]. @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 path before using it. Procedures that build paths or merely check the
form of a path do not cleanse paths, with the exceptions of form of a path do not cleanse paths, with the exceptions of
@scheme[cleanse-path], @scheme[expand-user-path], and @racket[cleanse-path], @racket[expand-user-path], and
@scheme[simplify-path]. For more information about path cleansing and @racket[simplify-path]. For more information about path cleansing and
other platform-specific details, see @secref["unixpaths"] for other platform-specific details, see @secref["unixpaths"] for
@|AllUnix| paths and @secref["windowspaths"] for Windows paths. @|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?]{ @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), 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?]{ @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, 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?]{ @defproc[(path-for-some-system? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a path value for some platform Returns @racket[#t] if @racket[v] is a path value for some platform
(not a string), @scheme[#f] otherwise.} (not a string), @racket[#f] otherwise.}
@defproc[(string->path [str string?]) path?]{ @defproc[(string->path [str string?]) path?]{
Produces a path whose byte-string name is 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 Beware that the current locale might not encode every string, in which
case @scheme[string->path] can produce the same path for different case @racket[string->path] can produce the same path for different
@scheme[str]s. See also @scheme[string->path-element], which should be @racket[str]s. See also @racket[string->path-element], which should be
used instead of @scheme[string->path] when a string represents a used instead of @racket[string->path] when a string represents a
single path element. single path element.
See also @scheme[string->some-system-path].} See also @racket[string->some-system-path].}
@defproc[(bytes->path [bstr bytes?] @defproc[(bytes->path [bstr bytes?]
[type (or/c 'unix 'windows) (system-path-convention-type)]) [type (or/c 'unix 'windows) (system-path-convention-type)])
path?]{ path?]{
Produces a path (for some platform) whose byte-string name is 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. use for the path.
For converting relative path elements from literals, use instead 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.} individual elements.}
@defproc[(path->string [path path?]) string?]{ @defproc[(path->string [path path?]) string?]{
Produces a string that represents @scheme[path] by decoding Produces a string that represents @racket[path] by decoding
@scheme[path]'s byte-string name using the current locale's encoding; @racket[path]'s byte-string name using the current locale's encoding;
@litchar{?} is used in the result string where encoding fails, and if @litchar{?} is used in the result string where encoding fails, and if
the encoding result is the empty string, then the result is the encoding result is the empty string, then the result is
@scheme["?"]. @racket["?"].
The resulting string is suitable for displaying to a user, The resulting string is suitable for displaying to a user,
string-ordering comparisons, etc., but it is not suitable for 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 since decoding and re-encoding the path's byte string may lose
information. information.
Furthermore, for display and sorting based on individual path elements 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 instead, to avoid special encodings use to represent some relative
paths. See @secref["windowspaths"] for specific information about paths. See @secref["windowspaths"] for specific information about
the conversion of Windows paths. 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?]{ @defproc[(path->bytes [path path?]) bytes?]{
Produces @scheme[path]'s byte string representation. No information is Produces @racket[path]'s byte string representation. No information is
lost in this translation, so that @scheme[(bytes->path (path->bytes lost in this translation, so that @racket[(bytes->path (path->bytes
path) (path-convention-type path))] always produces a path is that is 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. path for any platform.
Conversion to and from byte values is useful for marshaling and Conversion to and from byte values is useful for marshaling and
unmarshaling paths, but manipulating the byte form of a path is unmarshaling paths, but manipulating the byte form of a path is
generally a mistake. In particular, the byte string may start with a generally a mistake. In particular, the byte string may start with a
@litchar{\\?\REL} encoding for Windows paths. Instead of @litchar{\\?\REL} encoding for Windows paths. Instead of
@scheme[path->bytes], use @scheme[split-path] and @racket[path->bytes], use @racket[split-path] and
@scheme[path-element->bytes] to manipulate individual path elements.} @racket[path-element->bytes] to manipulate individual path elements.}
@defproc[(string->path-element [str string?]) path?]{ @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 single relative element in a path, and it is encoded as necessary to
convert it to a path. See @secref["unixpaths"] for more information convert it to a path. See @secref["unixpaths"] for more information
on the conversion for @|AllUnix| paths, and see on the conversion for @|AllUnix| paths, and see
@secref["windowspaths"] for more information on the conversion for @secref["windowspaths"] for more information on the conversion for
Windows paths. 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 (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 corresponds to an up-directory or same-directory indicator under
@|AllUnix|, then @exnraise[exn:fail:contract]. @|AllUnix|, then @exnraise[exn:fail:contract].
As for @scheme[path->string], information can be lost from As for @racket[path->string], information can be lost from
@scheme[str] in the locale-specific conversion to a path.} @racket[str] in the locale-specific conversion to a path.}
@defproc[(bytes->path-element [bstr bytes?] @defproc[(bytes->path-element [bstr bytes?]
[type (or/c 'unix 'windows) (system-path-convention-type)]) [type (or/c 'unix 'windows) (system-path-convention-type)])
path?]{ 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 single relative element in a path. In terms of conversions and
restrictions on @scheme[bstr], @scheme[bytes->path-element] is like restrictions on @racket[bstr], @racket[bytes->path-element] is like
@scheme[string->path-element]. @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 choice for reconstructing a path based on another path (where the
other path is deconstructed with @scheme[split-path] and other path is deconstructed with @racket[split-path] and
@scheme[path-element->bytes]) when ASCII-level manipulation of path @racket[path-element->bytes]) when ASCII-level manipulation of path
elements is necessary.} elements is necessary.}
@defproc[(path-element->string [path path?]) string?]{ @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 @secref["unixpaths"] for more information on the conversion for
@|AllUnix| paths, and see @secref["windowspaths"] for more @|AllUnix| paths, and see @secref["windowspaths"] for more
information on the conversion for Windows paths. information on the conversion for Windows paths.
In addition, trailing path separators are removed, as by 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] The @racket[path] argument must be such that @racket[split-path]
applied to @scheme[path] would return @scheme['relative] as its first applied to @racket[path] would return @racket['relative] as its first
result and a path as its second result, otherwise the result and a path as its second result, otherwise the
@exnraise[exn:fail:contract]. @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.} choice for presenting a pathless file or directory name to a user.}
@defproc[(path-element->bytes [path path-string?]) bytes?]{ @defproc[(path-element->bytes [path path-string?]) bytes?]{
Like @scheme[path->bytes], except that any encoding prefix is removed, Like @racket[path->bytes], except that any encoding prefix is removed,
etc., as for @scheme[path-element->string]. etc., as for @racket[path-element->string].
For any reasonable locale, consecutive ASCII characters in the printed 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 each character's code-point value, and a leading or trailing ASCII
character is mapped to a leading or trailing byte, respectively. The 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 The @racket[path-element->bytes] procedure is generally the right
choice (in combination with @scheme[split-path]) for extracting the choice (in combination with @racket[split-path]) for extracting the
content of a path to manipulate it at the ASCII level (then content of a path to manipulate it at the ASCII level (then
reassembling the result with @scheme[bytes->path-element] and reassembling the result with @racket[bytes->path-element] and
@scheme[build-path]).} @racket[build-path]).}
@defproc[(path-convention-type [path path?]) @defproc[(path-convention-type [path path?])
@ -197,7 +197,7 @@ type.}
(or/c 'unix 'windows)]{ (or/c 'unix 'windows)]{
Returns the path convention type of the current platform: 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.} Windows.}
@ -208,34 +208,34 @@ Windows.}
path?]{ path?]{
Creates a path given a base path and any number of sub-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. absolute path, otherwise the result is a relative path.
The @scheme[base] and each @scheme[sub] must be either a relative The @racket[base] and each @racket[sub] must be either a relative
path, the symbol @indexed-scheme['up] (indicating the relative parent path, the symbol @indexed-racket['up] (indicating the relative parent
directory), or the symbol @indexed-scheme['same] (indicating the directory), or the symbol @indexed-racket['same] (indicating the
relative current directory). For Windows paths, if @scheme[base] is a relative current directory). For Windows paths, if @racket[base] is a
drive specification (with or without a trailing slash) the first drive specification (with or without a trailing slash) the first
@scheme[sub] can be an absolute (driveless) path. For all platforms, @racket[sub] can be an absolute (driveless) path. For all platforms,
the last @scheme[sub] can be a filename. 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 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 a path for the current platform. If different arguments are for
different platforms, the @exnraise[exn:fail:contract]. If no argument 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. generated path is for the current platform.
Each @scheme[sub] and @scheme[base] can optionally end in a directory Each @racket[sub] and @racket[base] can optionally end in a directory
separator. If the last @scheme[sub] ends in a separator, it is separator. If the last @racket[sub] ends in a separator, it is
included in the resulting path. 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 is empty or contains a nul character), the
@exnraise[exn:fail:contract]. @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. checking the validity of the path or accessing the filesystem.
See @secref["unixpaths"] for more information on the construction 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 @filepath{/home/joeuser} for Unix examples and @filepath{C:\Joe's Files} for
Windows examples. Windows examples.
@schemeblock[ @racketblock[
(define p1 (build-path (current-directory) "src" "scheme")) (define p1 (build-path (current-directory) "src" "racket"))
(code:comment @#,t{Unix: @scheme[p1] is @scheme["/home/joeuser/src/scheme"]}) (code:comment @#,t{Unix: @racket[p1] is @racket["/home/joeuser/src/racket"]})
(code:comment @#,t{Windows: @scheme[p1] is @scheme["C:\\Joe's Files\\src\\scheme"]}) (code:comment @#,t{Windows: @racket[p1] is @racket["C:\\Joe's Files\\src\\racket"]})
(define p2 (build-path 'up 'up "docs" "Scheme")) (define p2 (build-path 'up 'up "docs" "Racket"))
(code:comment @#,t{Unix: @scheme[p2] is @scheme["../../docs/Scheme"]}) (code:comment @#,t{Unix: @racket[p2] is @racket["../../docs/Racket"]})
(code:comment @#,t{Windows: @scheme[p2] is @scheme["..\\..\\docs\\Scheme"]}) (code:comment @#,t{Windows: @racket[p2] is @racket["..\\..\\docs\\Racket"]})
(build-path p2 p1) (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) (build-path p1 p2)
(code:comment @#,t{Unix: is @scheme["/home/joeuser/src/racket/../../docs/Scheme"]}) (code:comment @#,t{Unix: is @racket["/home/joeuser/src/racket/../../docs/Racket"]})
(code:comment @#,t{Windows: is @scheme["C:\\Joe's Files\\src\\scheme\\..\\..\\docs\\Scheme"]}) (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)] ...) [sub (or/c path-string? 'up 'same)] ...)
path?]{ path?]{
Like @scheme[build-path], except a path convention type is specified Like @racket[build-path], except a path convention type is specified
explicitly.} explicitly.}
@defproc[(absolute-path? [path path-string?]) boolean?]{ @defproc[(absolute-path? [path path-string?]) boolean?]{
Returns @scheme[#t] if @scheme[path] is an absolute path, @scheme[#f] Returns @racket[#t] if @racket[path] is an absolute path, @racket[#f]
otherwise. The @scheme[path] argument can be a path for any otherwise. The @racket[path] argument can be a path for any
platform. If @scheme[path] is not a legal path string (e.g., it platform. If @racket[path] is not a legal path string (e.g., it
contains a nul character), @scheme[#f] is returned. This procedure contains a nul character), @racket[#f] is returned. This procedure
does not access the filesystem.} does not access the filesystem.}
@defproc[(relative-path? [path path-string?]) boolean?]{ @defproc[(relative-path? [path path-string?]) boolean?]{
Returns @scheme[#t] if @scheme[path] is a relative path, @scheme[#f] Returns @racket[#t] if @racket[path] is a relative path, @racket[#f]
otherwise. The @scheme[path] argument can be a path for any otherwise. The @racket[path] argument can be a path for any
platform. If @scheme[path] is not a legal path string (e.g., it platform. If @racket[path] is not a legal path string (e.g., it
contains a nul character), @scheme[#f] is returned. This procedure contains a nul character), @racket[#f] is returned. This procedure
does not access the filesystem.} does not access the filesystem.}
@defproc[(complete-path? [path path-string?]) boolean?]{ @defproc[(complete-path? [path path-string?]) boolean?]{
Returns @scheme[#t] if @scheme[path] is a completely determined path Returns @racket[#t] if @racket[path] is a completely determined path
(@italic{not} relative to a directory or drive), @scheme[#f] (@italic{not} relative to a directory or drive), @racket[#f]
otherwise. The @scheme[path] argument can be a path for any otherwise. The @racket[path] argument can be a path for any
platform. Note that for Windows paths, an absolute path can omit the platform. Note that for Windows paths, an absolute path can omit the
drive specification, in which case the path is neither relative nor drive specification, in which case the path is neither relative nor
complete. If @scheme[path] is not a legal path string (e.g., it complete. If @racket[path] is not a legal path string (e.g., it
contains a nul character), @scheme[#f] is returned. contains a nul character), @racket[#f] is returned.
This procedure does not access the filesystem.} This procedure does not access the filesystem.}
@ -304,13 +304,13 @@ This procedure does not access the filesystem.}
[base path-string? (current-directory)]) [base path-string? (current-directory)])
path?]{ 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, a complete path, it is returned as the result. Otherwise,
@scheme[path] is resolved with respect to the complete path @racket[path] is resolved with respect to the complete path
@scheme[base]. If @scheme[base] is not a complete path, the @racket[base]. If @racket[base] is not a complete path, the
@exnraise[exn:fail:contract]. @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 platform; if they are for different
platforms, the @exnraise[exn:fail:contract]. 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?]{ @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 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/} separator. For example, under @|AllUnix|, the path @filepath{x/y/}
syntactically refers to a directory and ends in a separator, but 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 @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. any platform, and the result will be for the same platform.
This procedure does not access the filesystem.} 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?]{ @defproc[(resolve-path [path path-string?]) path?]{
@tech{Cleanse}s @scheme[path] and returns a path that references the @tech{Cleanse}s @racket[path] and returns a path that references the
same file or directory as @scheme[path]. Under @|AllUnix|, if same file or directory as @racket[path]. Under @|AllUnix|, if
@scheme[path] is a soft link to another path, then the referenced path @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 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).} expansion).}
@defproc[(cleanse-path [path path-string?]) path]{ @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 this section). The filesystem might be accessed, but the source or
expanded path might be a non-existent path.} expanded path might be a non-existent path.}
@defproc[(expand-user-path [path path-string?]) 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; leading @litchar{~} is treated as user's home directory and expanded;
the username follows the @litchar{~} (before a @litchar{/} or the end the username follows the @litchar{~} (before a @litchar{/} or the end
of the path), where @litchar{~} by itself indicates the home directory 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 Eliminates redundant path separators (except for a single trailing
separator), up-directory @litchar{..}, and same-directory @litchar{.} 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 @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 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 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. result ends with a directory separator.
When @scheme[path] is simplified and @scheme[use-filesystem?] is true When @racket[path] is simplified and @racket[use-filesystem?] is true
(the default), a complete path is returned; if @scheme[path] is (the default), a complete path is returned; if @racket[path] is
relative, it is resolved with respect to the current directory, and relative, it is resolved with respect to the current directory, and
up-directory indicators are removed taking into account soft links (so up-directory indicators are removed taking into account soft links (so
that the resulting path refers to the same directory as before). 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 are removed by deleting a preceding path element, and the result can
be a relative path with up-directory indicators remaining at the be a relative path with up-directory indicators remaining at the
beginning of the path; up-directory indicators are dropped when they beginning of the path; up-directory indicators are dropped when they
refer to the parent of a root directory. Similarly, the result can be 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 separator) if eliminating up-directory indicators leaves only
same-directory indicators. same-directory indicators.
The @scheme[path] argument can be a path for any platform when The @racket[path] argument can be a path for any platform when
@scheme[use-filesystem?] is @scheme[#f], and the resulting path is for @racket[use-filesystem?] is @racket[#f], and the resulting path is for
the same platform. 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 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 @exnraise[exn:fail:filesystem] (but a successfully simplified path may
still involve a cycle of links if the cycle did not inhibit the still involve a cycle of links if the cycle did not inhibit the
simplification). simplification).
@ -404,16 +404,16 @@ information on simplifying Windows paths.}
@defproc[(normal-case-path [path path-string?]) path?]{ @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 paths, this procedure always returns the input path, because
filesystems for these platforms can be case-sensitive. For Windows 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 resulting string uses only lowercase letters, based on the current
locale. In addition, for Windows paths when the path does not start locale. In addition, for Windows paths when the path does not start
@litchar{\\?\}, all @litchar{/}s are converted to @litchar{\\?\}, all @litchar{/}s are converted to
@litchar{\}s, and trailing spaces and @litchar{.}s are removed. @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 that local-sensitive decoding and conversion of the path may be
different on the current platform than for the path's platform. 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) (or/c path? 'up 'same)
boolean?)]{ 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: directory or file name. Three values are returned:
@itemize[ @itemize[
@item{@scheme[base] is either @item{@racket[base] is either
@itemize[ @itemize[
@item{a path,} @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} 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[ @itemize[
@item{a directory-name path,} @item{a directory-name path,}
@item{a filename,} @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} 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).} same directory as the preceding path (e.g., @litchar{.} under Unix).}
]} ]}
@item{@scheme[must-be-dir?] is @scheme[#t] if @scheme[path] explicitly @item{@racket[must-be-dir?] is @racket[#t] if @racket[path] explicitly
specifies a directory (e.g., with a trailing separator), @scheme[#f] specifies a directory (e.g., with a trailing separator), @racket[#f]
otherwise. Note that @scheme[must-be-dir?] does not specify whether otherwise. Note that @racket[must-be-dir?] does not specify whether
@scheme[name] is actually a directory or not, but whether @scheme[path] @racket[name] is actually a directory or not, but whether @racket[path]
syntactically specifies a directory.} syntactically specifies a directory.}
] ]
Compared to @scheme[path], redundant separators (if any) are removed Compared to @racket[path], redundant separators (if any) are removed
in the result @scheme[base] and @scheme[name]. If @scheme[base] is in the result @racket[base] and @racket[name]. If @racket[base] is
@scheme[#f], then @scheme[name] cannot be @scheme['up] or @racket[#f], then @racket[name] cannot be @racket['up] or
@scheme['same]. The @scheme[path] argument can be a path for any @racket['same]. The @racket[path] argument can be a path for any
platform, and resulting paths for the same platform. platform, and resulting paths for the same platform.
This procedure does not access the filesystem. This procedure does not access the filesystem.
@ -474,23 +474,23 @@ information on splitting Windows paths.}
[suffix (or/c string? bytes?)]) [suffix (or/c string? bytes?)])
path?]{ 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 suffix for the last element of the path is changed to
@scheme[suffix]. If the last element of @scheme[path] has no suffix, @racket[suffix]. If the last element of @racket[path] has no suffix,
then @scheme[suffix] is added to the path. A suffix is defined as a then @racket[suffix] is added to the path. A suffix is defined as a
@litchar{.} followed by any number of non-@litchar{.} characters/bytes @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 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 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?] @defproc[(path-add-suffix [path path-string?]
[suffix (or/c string? bytes?)]) [suffix (or/c string? bytes?)])
path?]{ path?]{
Similar to @scheme[path-replace-suffix], but any existing suffix on Similar to @racket[path-replace-suffix], but any existing suffix on
@scheme[path] is preserved by replacing every @litchar{.} in the last @racket[path] is preserved by replacing every @litchar{.} in the last
path element with @litchar{_}, and then the @scheme[suffix] is added path element with @litchar{_}, and then the @racket[suffix] is added
to the end.} to the end.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -501,73 +501,73 @@ to the end.}
@defproc[(explode-path [path (or/c path-string? path-for-some-system?)]) @defproc[(explode-path [path (or/c path-string? path-for-some-system?)])
(listof (or/c path-for-some-system? 'up 'same))]{ (listof (or/c path-for-some-system? 'up 'same))]{
Returns the list of path element that constitute @scheme[path]. If Returns the list of path element that constitute @racket[path]. If
@scheme[path] is simplified in the sense of @scheme[simple-form-path], @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 then the result is always a list of paths, and the first element of
the list is a root.} the list is a root.}
@defproc[(file-name-from-path [path (or/c path-string? path-for-some-system?)]) @defproc[(file-name-from-path [path (or/c path-string? path-for-some-system?)])
(or/c path-for-some-system? #f)]{ (or/c path-for-some-system? #f)]{
Returns the last element of @scheme[path]. If @scheme[path] Returns the last element of @racket[path]. If @racket[path]
syntactically a directory path (see @scheme[split-path]), then then syntactically a directory path (see @racket[split-path]), then then
result is @scheme[#f].} result is @racket[#f].}
@defproc[(filename-extension [path (or/c path-string? path-for-some-system?)]) @defproc[(filename-extension [path (or/c path-string? path-for-some-system?)])
(or/c bytes? #f)]{ (or/c bytes? #f)]{
Returns a byte string that is the extension part of the filename in Returns a byte string that is the extension part of the filename in
@scheme[path] without the @litchar{.} separator. If @scheme[path] is @racket[path] without the @litchar{.} separator. If @racket[path] is
syntactically a directory (see @scheme[split-path]) or if the path has syntactically a directory (see @racket[split-path]) or if the path has
no extension, @scheme[#f] is returned.} no extension, @racket[#f] is returned.}
@defproc[(find-relative-path [base (or/c path-string? path-for-some-system?)] @defproc[(find-relative-path [base (or/c path-string? path-for-some-system?)]
[path (or/c path-string? path-for-some-system?)]) [path (or/c path-string? path-for-some-system?)])
path-for-some-system?]{ path-for-some-system?]{
Finds a relative pathname with respect to @scheme[base] that names Finds a relative pathname with respect to @racket[base] that names
the same file or directory as @scheme[path]. Both @scheme[base] the same file or directory as @racket[path]. Both @racket[base]
and @scheme[path] must be simplified in the sense of and @racket[path] must be simplified in the sense of
@scheme[simple-form-path]. If @scheme[path] is not a proper subpath @racket[simple-form-path]. If @racket[path] is not a proper subpath
of @scheme[base] (i.e., a subpath that is strictly longer), of @racket[base] (i.e., a subpath that is strictly longer),
@scheme[path] is returned.} @racket[path] is returned.}
@defproc[(normalize-path [path path-string?] @defproc[(normalize-path [path path-string?]
[wrt (and/c path-string? complete-path?) [wrt (and/c path-string? complete-path?)
(current-directory)]) (current-directory)])
path?]{ path?]{
Returns a normalized, complete version of @scheme[path], expanding the Returns a normalized, complete version of @racket[path], expanding the
path and resolving all soft links. If @scheme[path] is relative, then path and resolving all soft links. If @racket[path] is relative, then
@scheme[wrt] is used as the base path. @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 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 comparisons that determine whether two paths refer to the same file or
directory (i.e., the comparison may produce false negatives). 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, path contains an embedded path for a non-existent directory,
or if an infinite cycle of soft links is detected.} or if an infinite cycle of soft links is detected.}
@defproc[(path-only [path (or/c path-string? path-for-some-system?)]) @defproc[(path-only [path (or/c path-string? path-for-some-system?)])
path-for-some-system?]{ path-for-some-system?]{
If @scheme[path] is a filename, the file's path is returned. If If @racket[path] is a filename, the file's path is returned. If
@scheme[path] is syntactically a directory, @scheme[path] is returned @racket[path] is syntactically a directory, @racket[path] is returned
(as a path, if it was a string).} (as a path, if it was a string).}
@defproc[(simple-form-path [path path-string?]) path?]{ @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 ensures that the result is a complete path containing no up- or
same-directory indicators.} same-directory indicators.}
@defproc[(some-system-path->string [path path-for-some-system?]) @defproc[(some-system-path->string [path path-for-some-system?])
string?]{ 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. path's bytes.
Use this function when working with paths for a different system 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)]) [kind (or/c 'unix 'windows)])
path-for-some-system?]{ 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. of the path's bytes.
Use this function when working with paths for a different system Use this function when working with paths for a different system

14
collects/scribblings/reference/pipes.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "pipeports"]{Pipes} @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 OS-level pipes (which are @tech{file-stream ports}) for communicating
between different processes. 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 kinds of ports, pipe ports do not need to be explicitly closed to be
reclaimed by @seclink["gc-model"]{garbage collection}. 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 number of unread bytes (i.e., limited only by the available
memory). If @scheme[limit] is a positive number, then the pipe will memory). If @racket[limit] is a positive number, then the pipe will
hold at most @scheme[limit] unread/unpeeked bytes; writing to the 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 pipe's output port thereafter will block until a read or peek from the
input port makes more space available. (Peeks effectively extend the input port makes more space available. (Peeks effectively extend the
port's capacity until the peeked bytes are read.) 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.} as the names for the returned input and out ports, respectively.}
@defproc[(pipe-content-length [pipe-port port?]) exact-nonnegative-integer?]{ @defproc[(pipe-content-length [pipe-port port?]) exact-nonnegative-integer?]{
Returns the number of bytes contained in a pipe, where Returns the number of bytes contained in a pipe, where
@scheme[pipe-port] is either of the pipe's ports produced by @racket[pipe-port] is either of the pipe's ports produced by
@scheme[make-pipe]. The pipe's content length counts all bytes that @racket[make-pipe]. The pipe's content length counts all bytes that
have been written to the pipe and not yet read (though possibly have been written to the pipe and not yet read (though possibly
peeked).} peeked).}

26
collects/scribblings/reference/port-line-counting.scrbl
View File

@ -7,20 +7,20 @@
@section-index["column numbers"] @section-index["column numbers"]
@section-index["port positions"] @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 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 (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 the position in terms of characters (after UTF-8 decoding), instead of
bytes, and it can track @deftech{line locations} and @deftech{column bytes, and it can track @deftech{line locations} and @deftech{column
locations}; this optional tracking must be specifically enabled for a locations}; this optional tracking must be specifically enabled for a
port via @scheme[port-count-lines!] or the port via @racket[port-count-lines!] or the
@scheme[port-count-lines-enabled] parameter. Position, line, and @racket[port-count-lines-enabled] parameter. Position, line, and
column locations for a port are used by @scheme[read-syntax] and column locations for a port are used by @racket[read-syntax] and
@scheme[read-honu-syntax]. Position and line locations are numbered @racket[read-honu-syntax]. Position and line locations are numbered
from @math{1}; column locations are numbered from @math{0}. 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 return-linefeed combinations as a line terminator and as a single
position (on all platforms). Each tab advances the column count to one 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 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 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 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 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 counting is automatically enabled for the port. Line counting cannot
be disabled for a port after it is enabled.} 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-nonnegative-integer? #f)
(or/c exact-positive-integer? #f))]{ (or/c exact-positive-integer? #f))]{
Returns three values: an integer or @scheme[#f] for the line number of Returns three values: an integer or @racket[#f] for the line number of
the next read/written item, an integer or @scheme[#f] for the next the next read/written item, an integer or @racket[#f] for the next
item's column, and an integer or @scheme[#f] for the next item's 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 position. The next column and position normally increases as bytes are
read from or written to the port, but if line/character counting is 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 decrease after reading or writing a byte that ends a UTF-8 encoding
sequence.} sequence.}
@ -67,5 +67,5 @@ sequence.}
A parameter that determines whether line counting is enabled A parameter that determines whether line counting is enabled
automatically for newly created ports. The default value is automatically for newly created ports. The default value is
@scheme[#f].} @racket[#f].}

188
collects/scribblings/reference/read.scrbl
View File

@ -5,11 +5,11 @@
@defproc[(read [in input-port? (current-input-port)]) any]{ @defproc[(read [in input-port? (current-input-port)]) any]{
Reads and returns a single @tech{datum} from @scheme[in]. If Reads and returns a single @tech{datum} from @racket[in]. If
@scheme[in] has a handler associated to it via @racket[in] has a handler associated to it via
@scheme[port-read-handler], then the handler is called. Otherwise, the @racket[port-read-handler], then the handler is called. Otherwise, the
default reader is used, as parameterized by 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. parameters.
See @secref["reader"] for information on the default reader.} 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)]) [in input-port? (current-input-port)])
(or/c syntax? eof-object?)]{ (or/c syntax? eof-object?)]{
Like @scheme[read], but produces a @tech{syntax object} with Like @racket[read], but produces a @tech{syntax object} with
source-location information. The @scheme[source-name] is used as the source-location information. The @racket[source-name] is used as the
source field of the syntax object; it can be an arbitrary value, but source field of the syntax object; it can be an arbitrary value, but
it should generally be a path for the source file. it should generally be a path for the source file.
See @secref["reader"] for information on the default reader in 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)] @defproc[(read/recursive [in input-port? (current-input-port)]
[start (or/c char? #f) #f] [start (or/c char? #f) #f]
@ -32,46 +32,46 @@ See @secref["reader"] for information on the default reader in
[graph? any/c #t]) [graph? any/c #t])
any]{ any]{
Similar to calling @scheme[read], but normally used during the dynamic Similar to calling @racket[read], but normally used during the dynamic
extent of @scheme[read] within a reader-extension procedure (see extent of @racket[read] within a reader-extension procedure (see
@secref["reader-procs"]). The main effect of using @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 graph-structure annotations (see @secref["parse-graph"]) in the
nested read are considered part of the overall read, at least when 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. placeholder, however, it is not directly inspectable.
If @scheme[start] is provided and not @scheme[#f], it is effectively If @racket[start] is provided and not @racket[#f], it is effectively
prefixed to the beginning of @scheme[in]'s stream for the read. (To prefixed to the beginning of @racket[in]'s stream for the read. (To
prefix multiple characters, use @scheme[input-port-append].) 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 satisfy the read request; recursive parsing within the read (e.g., to
read the elements of a list) instead uses the current readtable as read the elements of a list) instead uses the current readtable as
determined by the @scheme[current-readtable] parameter. A reader determined by the @racket[current-readtable] parameter. A reader
macro might call @scheme[read/recursive] with a character and macro might call @racket[read/recursive] with a character and
readtable to effectively invoke the readtable's behavior for the 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. 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. the read datum are local to the datum.
When called within the dynamic extent of @scheme[read], the When called within the dynamic extent of @racket[read], the
@scheme[read/recursive] procedure produces either an opaque @racket[read/recursive] procedure produces either an opaque
placeholder value, a special-comment value, or an end-of-file. The placeholder value, a special-comment value, or an end-of-file. The
result is a special-comment value (see @secref["special-comments"]) result is a special-comment value (see @secref["special-comments"])
when the input stream's first non-whitespace content parses as a 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 encounters an end-of-file. Otherwise, the result is a placeholder that
protects graph references that are not yet resolved. When this protects graph references that are not yet resolved. When this
placeholder is returned within an S-expression that is produced by any placeholder is returned within an S-expression that is produced by any
reader-extension procedure (see @secref["reader-procs"]) for the reader-extension procedure (see @secref["reader-procs"]) for the
same outermost @scheme[read], it will be replaced with the actual read same outermost @racket[read], it will be replaced with the actual read
value before the outermost @scheme[read] returns. value before the outermost @racket[read] returns.
See @secref["readtables"] for an extended example that uses 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)] @defproc[(read-syntax/recursive [source-name any/c (object-name in)]
[in input-port? (current-input-port)] [in input-port? (current-input-port)]
@ -80,105 +80,105 @@ See @secref["readtables"] for an extended example that uses
[graph? any/c #t]) [graph? any/c #t])
any]{ 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 encapsulates S-expression structure with source-location
information. As with @scheme[read/recursive], when information. As with @racket[read/recursive], when
@scheme[read-syntax/recursive] is used within the dynamic extent of @racket[read-syntax/recursive] is used within the dynamic extent of
@scheme[read-syntax], the result of from @racket[read-syntax], the result of from
@scheme[read-syntax/recursive] is either a special-comment value, @racket[read-syntax/recursive] is either a special-comment value,
end-of-file, or opaque graph-structure placeholder (not a syntax end-of-file, or opaque graph-structure placeholder (not a syntax
object). The placeholder can be embedded in an S-expression or 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 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. returns.
Using @scheme[read/recursive] within the dynamic extent of Using @racket[read/recursive] within the dynamic extent of
@scheme[read-syntax] does not allow graph structure for reading to be @racket[read-syntax] does not allow graph structure for reading to be
included in the outer @scheme[read-syntax] parsing, and neither does included in the outer @racket[read-syntax] parsing, and neither does
using @scheme[read-syntax/recursive] within the dynamic extent of using @racket[read-syntax/recursive] within the dynamic extent of
@scheme[read]. In those cases, @scheme[read/recursive] and @racket[read]. In those cases, @racket[read/recursive] and
@scheme[read-syntax/recursive] produce results like @scheme[read] and @racket[read-syntax/recursive] produce results like @racket[read] and
@scheme[read-syntax], except that a special-comment value is returned @racket[read-syntax], except that a special-comment value is returned
when the input stream starts with a comment (after whitespace). when the input stream starts with a comment (after whitespace).
See @secref["readtables"] for an extended example that uses 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)] @defproc[(read-language [in input-port? (current-input-port)]
[fail-thunk (-> any) (lambda () (error ...))]) [fail-thunk (-> any) (lambda () (error ...))])
(any/c any/c . -> . any)]{ (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. soon as a @tech{reader language} (or its absence) is determined.
A @deftech{reader language} is specified by @litchar{#lang} or A @deftech{reader language} is specified by @litchar{#lang} or
@litchar{#!} (see @secref["parse-reader"]) at the beginning of the @litchar{#!} (see @secref["parse-reader"]) at the beginning of the
input, though possibly after comment forms. The default input, though possibly after comment forms. The default
@tech{readtable} is used by @scheme[read-language] (instead of the @tech{readtable} is used by @racket[read-language] (instead of the
value of @scheme[current-readtable]), and @litchar{#reader} forms value of @racket[current-readtable]), and @litchar{#reader} forms
(which might produce comments) are not allowed before @litchar{#lang} (which might produce comments) are not allowed before @litchar{#lang}
or @litchar{#!}. or @litchar{#!}.
When it finds a @litchar{#lang} or @litchar{#!} specification, instead When it finds a @litchar{#lang} or @litchar{#!} specification, instead
of dispatching to a @schemeidfont{read} or @schemeidfont{read-syntax} of dispatching to a @racketidfont{read} or @racketidfont{read-syntax}
form as @scheme[read] and @scheme[read-syntax] do, form as @racket[read] and @racket[read-syntax] do,
@scheme[read-language] dispatches to a @schemeidfont{get-info} @racket[read-language] dispatches to a @racketidfont{get-info}
function (if any) exported by the same module. The result of the function (if any) exported by the same module. The result of the
@schemeidfont{get-info} function is the result of @racketidfont{get-info} function is the result of
@scheme[read-language] if it is a function of two arguments; if @racket[read-language] if it is a function of two arguments; if
@schemeidfont{get-info} produces any other kind of result, the @racketidfont{get-info} produces any other kind of result, the
@exnraise[exn:fail:contract]. @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 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 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 If no information is available for a given key, the result should be
the second argument. 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 arguments: the input port being read, the module path from which the
@schemeidfont{get-info} function was extracted, and the source line @racketidfont{get-info} function was extracted, and the source line
(positive exact integer or @scheme[#f]), column (non-negative exact (positive exact integer or @racket[#f]), column (non-negative exact
integer or @scheme[#f]), and position (positive exact integer or integer or @racket[#f]), and position (positive exact integer or
@scheme[#f]) of the start of the @litchar{#lang} or @litchar{#!} @racket[#f]) of the start of the @litchar{#lang} or @litchar{#!}
form. The @schemeidfont{get-info} function may further read from the form. The @racketidfont{get-info} function may further read from the
given input port to determine its result, but it should read no 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. not read from the port after returning a function.
If @scheme[in] starts with a @tech{reader language} specification but If @racket[in] starts with a @tech{reader language} specification but
the relevant module does not export @schemeidfont{get-info} (but the relevant module does not export @racketidfont{get-info} (but
perhaps does export @schemeidfont{read} and perhaps does export @racketidfont{read} and
@schemeidfont{read-syntax}), then the result of @scheme[read-language] @racketidfont{read-syntax}), then the result of @racket[read-language]
is @scheme[#f]. 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 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 If @racket[in] does not specify a @tech{reader language} with
@litchar{#lang} or @litchar{#!}, then @scheme[fail-thunk] is @litchar{#lang} or @litchar{#!}, then @racket[fail-thunk] is
called. The default @scheme[fail-thunk] raises called. The default @racket[fail-thunk] raises
@scheme[exn:fail:contract].} @racket[exn:fail:contract].}
@defboolparam[read-case-sensitive on?]{ @defboolparam[read-case-sensitive on?]{
A parameter that controls parsing and printing of symbols. When this A parameter that controls parsing and printing of symbols. When this
parameter's value is @scheme[#f], the reader case-folds symbols (e.g., parameter's value is @racket[#f], the reader case-folds symbols (e.g.,
producing @scheme['hi] when the input is any one of @litchar{hi}, producing @racket['hi] when the input is any one of @litchar{hi},
@litchar{Hi}, @litchar{HI}, or @litchar{hI}). The parameter also @litchar{Hi}, @litchar{HI}, or @litchar{hI}). The parameter also
affects the way that @scheme[write] prints symbols containing affects the way that @racket[write] prints symbols containing
uppercase characters; if the parameter's value is @scheme[#f], then uppercase characters; if the parameter's value is @racket[#f], then
symbols are printed with uppercase characters quoted by a symbols are printed with uppercase characters quoted by a
@litchar{\} or @litchar{|}. The parameter's value is overridden by @litchar{\} or @litchar{|}. The parameter's value is overridden by
quoting @litchar{\} or @litchar{|} vertical-bar quotes and the quoting @litchar{\} or @litchar{|} vertical-bar quotes and the
@litchar{#cs} and @litchar{#ci} prefixes; see @litchar{#cs} and @litchar{#ci} prefixes; see
@secref["parse-symbol"] for more information. While a module is @secref["parse-symbol"] for more information. While a module is
loaded, the parameter is set to @scheme[#t] (see loaded, the parameter is set to @racket[#t] (see
@scheme[current-load]).} @racket[current-load]).}
@defboolparam[read-square-bracket-as-paren on?]{ @defboolparam[read-square-bracket-as-paren on?]{
@ -200,7 +200,7 @@ A parameter that controls parsing @litchar{#&} input. See
@defboolparam[read-accept-compiled on?]{ @defboolparam[read-accept-compiled on?]{
A parameter that controls parsing @litchar{#~} compiled input. See 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.} information.}
@defboolparam[read-accept-bar-quote on?]{ @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?]{ @defboolparam[read-accept-quasiquote on?]{
A parameter that controls parsing input with @litchar{`} or A parameter that controls parsing input with @litchar{`} or
@litchar{,} which is normally used for @scheme[quasiquote], @litchar{,} which is normally used for @racket[quasiquote],
@scheme[unquote], and @scheme[unquote-splicing] abbreviations. See @racket[unquote], and @racket[unquote-splicing] abbreviations. See
@secref["parse-quote"] for more information.} @secref["parse-quote"] for more information.}
@defboolparam[read-accept-reader on?]{ @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)]{ @defparam[current-readtable readtable (or/c readtable? #f)]{
A parameter whose value determines a readtable that 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.} 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 A parameter that enables lazy parsing of compiled code, so that
closure bodies and syntax objects are extracted (and validated) from closure bodies and syntax objects are extracted (and validated) from
marshaled compiled code on demand. Normally, this parameter is set by marshaled compiled code on demand. Normally, this parameter is set by
the default @tech{load handler} when @scheme[load-on-demand-enabled] the default @tech{load handler} when @racket[load-on-demand-enabled]
is @scheme[#t]. is @racket[#t].
Even when parsing is delayed, compiled code is loaded into memory. If Even when parsing is delayed, compiled code is loaded into memory. If
the @as-index{@envvar{PLT_DELAY_FROM_ZO}} environment variable is set 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))]) (input-port? any/c . -> . any))])
void?])]{ void?])]{
Gets or sets the @deftech{port read handler} for @scheme[in]. The Gets or sets the @deftech{port read handler} for @racket[in]. The
handler called to read from the port when the built-in @scheme[read] handler called to read from the port when the built-in @racket[read]
or @scheme[read-syntax] procedure is applied to the port. (The or @racket[read-syntax] procedure is applied to the port. (The
port read handler is not used for @scheme[read/recursive] or port read handler is not used for @racket[read/recursive] or
@scheme[read-syntax/recursive].) @racket[read-syntax/recursive].)
A port read handler is applied to either one argument or two A port read handler is applied to either one argument or two
arguments: arguments:
@ -295,20 +295,20 @@ arguments:
@itemize[ @itemize[
@item{A single argument is supplied when the port is used @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).} 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 @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 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).} 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 The default port read handler reads standard Racket expressions with
Scheme's built-in parser (see @secref["reader"]). It handles a Racket's built-in parser (see @secref["reader"]). It handles a
special result from a custom input port (see 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 except that special-comment values (see
@secref["special-comments"]) are treated as whitespace. @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]{ @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)] @defproc[(read-honu-syntax [source-name any/c (object-name in)]
[in input-port? (current-input-port)]) [in input-port? (current-input-port)])
(or/c syntax? eof-object?)]{ (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"]).} @secref["parse-honu"]).}
@defproc[(read-honu/recursive [in input-port? (current-input-port)] @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]) [graph? any/c #t])
any]{ any]{
Like @scheme[read/recursive], but for Honu mode (see Like @racket[read/recursive], but for Honu mode (see
@secref["parse-honu"]).} @secref["parse-honu"]).}
@defproc[(read-honu-syntax/recursive [source-name any/c (object-name in)] @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]) [graph? any/c #f])
any]{ any]{
Like @scheme[read-syntax/recursive], but for Honu mode (see Like @racket[read-syntax/recursive], but for Honu mode (see
@secref["parse-honu"]).} @secref["parse-honu"]).}

190
collects/scribblings/reference/reader.scrbl
View File

@ -9,14 +9,14 @@
(nonterm s (subscript "n"))) (nonterm s (subscript "n")))
(define (sub n) (subscript n)) (define (sub n) (subscript n))
(define (nonalpha) (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-tag) @kleenerange[1 8]{@nonterm{digit@sub{10}}})
(define (graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}}) (define (graph-defn) @elem{@litchar{#}@graph-tag[]@litchar{=}})
(define (graph-ref) @elem{@litchar{#}@graph-tag[]@litchar{#}})) (define (graph-ref) @elem{@litchar{#}@graph-tag[]@litchar{#}}))
@title[#:tag "reader" #:style 'quiet]{The Reader} @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 through a @seclink["readtables"]{readtable} and various other
@tech{parameters}. This section describes the reader's parsing when @tech{parameters}. This section describes the reader's parsing when
using the default readtable. 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 datum is a compound value, then reading the datum typically requires
the reader to call itself recursively to read the component data. the reader to call itself recursively to read the component data.
The reader can be invoked in either of two modes: @scheme[read] mode, The reader can be invoked in either of two modes: @racket[read] mode,
or @scheme[read-syntax] mode. In @scheme[read-syntax] mode, the result or @racket[read-syntax] mode. In @racket[read-syntax] mode, the result
is always a @techlink{syntax object} that includes is always a @techlink{syntax object} that includes
source-location and (initially empty) lexical information wrapped 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 case of pairs, vectors, and boxes, the content is also
wrapped recursively as a syntax object. Unless specified otherwise, wrapped recursively as a syntax object. Unless specified otherwise,
this section describes the reader's behavior in @scheme[read] mode, this section describes the reader's behavior in @racket[read] mode,
and @scheme[read-syntax] mode does the same modulo wrapping the final and @racket[read-syntax] mode does the same modulo wrapping the final
result. result.
Reading is defined in terms of Unicode characters; see 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} @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}: characters are @defterm{delimiters}:
@t{ @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{#!}]{may start a reader extension; see @secref["parse-reader"]}
@dispatch[@litchar{#`}]{starts a syntax quasiquote; see @secref["parse-quote"]} @dispatch[@litchar{#`}]{starts a syntax quasiquote; see @secref["parse-quote"]}
@dispatch[@litchar{#,}]{starts an syntax [splicing] unquote; 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{#i}]{starts a number; see @secref["parse-number"]}
@dispatch[@cilitchar{#e}]{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{#ci}]{switches case sensitivity; see @secref["parse-symbol"]}
@dispatch[@cilitchar{#cs}]{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"]} @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 parsed as either a symbol or a number (see
@secref["parse-number"]), except that @litchar{.} by itself is @secref["parse-number"]), except that @litchar{.} by itself is
never parsed as a symbol or character (unless the 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 @as-index{@litchar{#%}} also starts a symbol. A successful number
parse takes precedence over a symbol parse. parse takes precedence over a symbol parse.
@index["case-sensitivity"]{@index["case-insensitive"]{When}} the @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 characters in the sequence that are not quoted by @litchar{|} or
@litchar{\} are first case-normalized. If the reader encounters @litchar{\} are first case-normalized. If the reader encounters
@as-index{@litchar{#ci}}, @litchar{#CI}, @litchar{#Ci}, or @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 non-terminal names suggest, a number that has no exactness specifier
and matches only @nunterm{inexact-number} is normally parsed as an and matches only @nunterm{inexact-number} is normally parsed as an
inexact number, otherwise it is parsed as an exact number. If the 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 all numbers without an exactness specifier are instead parsed as
exact. 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 element, followed by the others in the read order. This convention
supports a kind of @as-index{infix} notation at the reader level. supports a kind of @as-index{infix} notation at the reader level.
In @scheme[read-syntax] mode, the recursive reads for the pair/list In @racket[read-syntax] mode, the recursive reads for the pair/list
elements are themselves in @scheme[read-syntax] mode, so that the 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 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 syntax object. If the reader constructs nested pairs because the input
included a single delimited @litchar{.}, then only the innermost pair included a single delimited @litchar{.}, then only the innermost pair
and outtermost pair are wrapped as syntax objects. Whether wrapping a and outtermost pair are wrapped as syntax objects. Whether wrapping a
pair or list, if the pair or list was formed with @litchar{[} and pair or list, if the pair or list was formed with @litchar{[} and
@litchar{]}, then a @indexed-scheme['paren-shape] property is attached @litchar{]}, then a @indexed-racket['paren-shape] property is attached
to the result with the value @scheme[#\[]; if the list or pair was to the result with the value @racket[#\[]; if the list or pair was
formed with @litchar["{"] and @litchar["}"], then a formed with @litchar["{"] and @litchar["}"], then a
@scheme['paren-shape] property is attached to the result with the @racket['paren-shape] property is attached to the result with the
value @scheme[#\{]. value @racket[#\{].
If a delimited @litchar{.} appears in any other configuration, then If a delimited @litchar{.} appears in any other configuration, then
the @exnraise[exn:fail:read]. Similarly, if the reader encounters a 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)" "(1 . 2 . 3)"
] ]
If the @scheme[read-square-bracket-as-paren] @tech{parameter} is set to If the @racket[read-square-bracket-as-paren] @tech{parameter} is set to
@scheme[#f], then when then reader encounters @litchar{[} and @racket[#f], then when then reader encounters @litchar{[} and
@litchar{]}, the @exnraise{exn:fail:read}. Similarly, If the @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 then when then reader encounters @litchar["{"] and @litchar["}"], the
@exnraise{exn:fail:read}. @exnraise{exn:fail:read}.
If the @scheme[read-accept-dot] @tech{parameter} is set to If the @racket[read-accept-dot] @tech{parameter} is set to
@scheme[#f], then a delimited @litchar{.} triggers an @racket[#f], then a delimited @litchar{.} triggers an
@scheme[exn:fail:read] exception. If the @racket[exn:fail:read] exception. If the
@scheme[read-accept-infix-dot] @tech{parameter} is set to @scheme[#f], @racket[read-accept-infix-dot] @tech{parameter} is set to @racket[#f],
then multiple delimited @litchar{.}s trigger an @scheme[exn:fail:read] then multiple delimited @litchar{.}s trigger an @racket[exn:fail:read]
exception, instead of the infix conversion. exception, instead of the infix conversion.
@section[#:tag "parse-string"]{Reading Strings} @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 4]{@nonterm{digit@sub{16}}}}: like @litchar{\x}, but with up
to four hexadecimal digits (longer sequences take precedence). to four hexadecimal digits (longer sequences take precedence).
The resulting hexadecimal number must be a valid argument to The resulting hexadecimal number must be a valid argument to
@scheme[integer->char], otherwise the @racket[integer->char], otherwise the
@exnraise[exn:fail:read].} @exnraise[exn:fail:read].}
@item{@as-index{@litchar{\U}@kleenerange[1 @item{@as-index{@litchar{\U}@kleenerange[1
8]{@nonterm{digit@sub{16}}}}: like @litchar{\x}, but with up 8]{@nonterm{digit@sub{16}}}}: like @litchar{\x}, but with up
to eight hexadecimal digits (longer sequences take precedence). to eight hexadecimal digits (longer sequences take precedence).
The resulting hexadecimal number must be a valid argument to The resulting hexadecimal number must be a valid argument to
@scheme[integer->char], otherwise the @racket[integer->char], otherwise the
@exnraise[exn:fail:read].} @exnraise[exn:fail:read].}
@item{@as-index{@litchar{\}@nonterm{newline}}: elided, where @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 When the reader enounters @as-index{@litchar{'}}, it recursively
reads one datum, and forms a new list containing the symbol reads one datum, and forms a new list containing the symbol
@scheme['quote] and the following datum. This convention is mainly @racket['quote] and the following datum. This convention is mainly
useful for reading Scheme code, where @scheme['s] can be used as a useful for reading Racket code, where @racket['s] can be used as a
shorthand for @scheme[(code:quote s)]. shorthand for @racket[(code:quote s)].
Several other sequences are recognized and transformed in a similar Several other sequences are recognized and transformed in a similar
way. Longer prefixes take precedence over short ones: way. Longer prefixes take precedence over short ones:
@read-quote-table[(list @litchar{'} @scheme[quote]) @read-quote-table[(list @litchar{'} @racket[quote])
(list @as-index{@litchar{`}} @scheme[quasiquote]) (list @as-index{@litchar{`}} @racket[quasiquote])
(list @as-index{@litchar{,}} @scheme[unquote]) (list @as-index{@litchar{,}} @racket[unquote])
(list @as-index{@litchar[",@"]} @scheme[unquote-splicing]) (list @as-index{@litchar[",@"]} @racket[unquote-splicing])
(list @as-index{@litchar{#'}} @scheme[syntax]) (list @as-index{@litchar{#'}} @racket[syntax])
(list @as-index{@litchar{#`}} @scheme[quasisyntax]) (list @as-index{@litchar{#`}} @racket[quasisyntax])
(list @as-index{@litchar{#,}} @scheme[unsyntax]) (list @as-index{@litchar{#,}} @racket[unsyntax])
(list @as-index{@litchar["#,@"]} @scheme[unsyntax-splicing])] (list @as-index{@litchar["#,@"]} @racket[unsyntax-splicing])]
@reader-examples[ @reader-examples[
"'apple" "'apple"
@ -502,16 +502,16 @@ way. Longer prefixes take precedence over short ones:
] ]
The @litchar{`}, @litchar{,}, and @litchar[",@"] forms are disabled when The @litchar{`}, @litchar{,}, and @litchar[",@"] forms are disabled when
the @scheme[read-accept-quasiquote] @tech{parameter} is set to the @racket[read-accept-quasiquote] @tech{parameter} is set to
@scheme[#f], in which case the @exnraise[exn:fail:read], instead. @racket[#f], in which case the @exnraise[exn:fail:read], instead.
@section[#:tag "parse-comment"]{Reading Comments} @section[#:tag "parse-comment"]{Reading Comments}
A @as-index{@litchar{;}} starts a line comment. When the reader A @as-index{@litchar{;}} starts a line comment. When the reader
encounters @litchar{;}, it skips past all characters until the encounters @litchar{;}, it skips past all characters until the
next linefeed (ASCII 10), carriage return (ASCII 13), next-line next linefeed (ASCII 10), carriage return (ASCII 13), next-line
(Unicode @scheme[#x0085]), line-separator (Unicode @scheme[#x2028]), (Unicode @racket[#x0085]), line-separator (Unicode @racket[#x2028]),
or line-separator (Unicode @scheme[#x2028]) character. or line-separator (Unicode @racket[#x2028]) character.
A @as-index{@litchar{#|}} starts a nestable block comment. When the A @as-index{@litchar{#|}} starts a nestable block comment. When the
reader encounters @litchar{#|}, it skips past all characters reader encounters @litchar{#|}, it skips past all characters
@ -543,8 +543,8 @@ file.
When the reader encounters a @litchar{#(}, @litchar{#[}, or When the reader encounters a @litchar{#(}, @litchar{#[}, or
@litchar["#{"], it starts parsing a vector; see @secref["vectors"] for @litchar["#{"], it starts parsing a vector; see @secref["vectors"] for
information on vectors. The @litchar{#[} and @litchar["#{"] forms can information on vectors. The @litchar{#[} and @litchar["#{"] forms can
be disabled through the @scheme[read-square-bracket-as-paren] and be disabled through the @racket[read-square-bracket-as-paren] and
@scheme[read-curly-brace-as-paren] @tech{parameters}. @racket[read-curly-brace-as-paren] @tech{parameters}.
The elements of the vector are recursively read until a matching The elements of the vector are recursively read until a matching
@litchar{)}, @litchar{]}, or @litchar["}"] is found, just as for @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 using a sequence of decimal digits, and the number of elements
provided for the vector must be no more than the specified size. If 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 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. is used for all slots.
In @scheme[read-syntax] mode, each recursive read for the vector In @racket[read-syntax] mode, each recursive read for the vector
elements is also in @scheme[read-syntax] mode, so that the wrapped 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 vector's elements are also wraped as syntax objects, and the vector is
immutable. 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} @litchar["#s{"], it starts parsing an instance of a @tech{prefab}
@tech{structure type}; see @secref["structures"] for information on @tech{structure type}; see @secref["structures"] for information on
@tech{structure types}. The @litchar{#s[} and @litchar["#s{"] forms @tech{structure types}. The @litchar{#s[} and @litchar["#s{"] forms
can be disabled through the @scheme[read-square-bracket-as-paren] and can be disabled through the @racket[read-square-bracket-as-paren] and
@scheme[read-curly-brace-as-paren] @tech{parameters}. @racket[read-curly-brace-as-paren] @tech{parameters}.
The elements of the structure are recursively read until a matching The elements of the structure are recursively read until a matching
@litchar{)}, @litchar{]}, or @litchar["}"] is found, just as for lists @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 The first element is used as the structure descriptor, and it must
have the form (when quoted) of a possible argument to 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 symbol. The remaining elements correspond to field values within the
structure. 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 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. are also wraped as syntax objects.
If the first structure element is not a valid @tech{prefab} structure 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} @section[#:tag "parse-hashtable"]{Reading Hash Tables}
A @as-index{@litchar{#hash}} starts an immutable hash-table constant 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 @litchar{hash} must parse as a list of pairs (see
@secref["parse-pair"]) with a specific use of delimited @litchar{.}: @secref["parse-pair"]) with a specific use of delimited @litchar{.}:
it must appear between the elements of each pair in the list, and 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 A @as-index{@litchar{#hasheq}} starts a hash table like
@litchar{#hash}, except that it constructs a hash table based on @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 A @as-index{@litchar{#hasheqv}} starts a hash table like
@litchar{#hash}, except that it constructs a hash table based on @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 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 hash table from left to right, so later mappings can hide earlier
mappings if the keys are equivalent. mappings if the keys are equivalent.
@reader-examples[ @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()" "#hash()"
"#hasheq()" "#hasheq()"
"#hash((\"a\" . 5))" "#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 content of the box is determined by recursively reading the next
datum. datum.
In @scheme[read-syntax] mode, the recursive read for the box content In @racket[read-syntax] mode, the recursive read for the box content
is also in @scheme[read-syntax] mode, so that the wrapped box's 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. content is also wraped as a syntax object, and the box is immutable.
@reader-examples[ @reader-examples[
@ -688,7 +688,7 @@ one of the following forms:
as @litchar{#\}@nonterm{c} and the characters following it as @litchar{#\}@nonterm{c} and the characters following it
do not match any of the previous cases, and as long as the do not match any of the previous cases, and as long as the
character after @nonterm{c} is not 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 regular expression. The characters immediately after @litchar{#rx} or
@litchar{#px} must parse as a string or byte string (see @litchar{#px} must parse as a string or byte string (see
@secref["parse-string"]). A @litchar{#rx} prefix starts a regular @secref["parse-string"]). A @litchar{#rx} prefix starts a regular
expression as would be constructed by @scheme[regexp], @litchar{#px} expression as would be constructed by @racket[regexp], @litchar{#px}
as constructed by @scheme[pregexp], @litchar{#rx#} as constructed by as constructed by @racket[pregexp], @litchar{#rx#} as constructed by
@scheme[byte-regexp], and @litchar{#px#} as constructed by @racket[byte-regexp], and @litchar{#px#} as constructed by
@scheme[byte-pregexp]. @racket[byte-pregexp].
@reader-examples[ @reader-examples[
"#rx\".*\"" "#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, datum after it. A @graph-defn[] definition can appear at most once,
and a @graph-defn[] definition must appear before a @graph-ref[] and a @graph-defn[] definition must appear before a @graph-ref[]
reference appears, otherwise the @exnraise[exn:fail:read]. If the reference appears, otherwise the @exnraise[exn:fail:read]. If the
@scheme[read-accept-graph] parameter is set to @scheme[#f], then @racket[read-accept-graph] parameter is set to @racket[#f], then
@graph-defn[] or @graph-ref[] triggers a @scheme[exn:fail:read] @graph-defn[] or @graph-ref[] triggers a @racket[exn:fail:read]
exception. exception.
Although a comment parsed via @litchar{#;} discards the datum Although a comment parsed via @litchar{#;} discards the datum
@ -770,51 +770,51 @@ stream.
The reader recursively reads the next datum after @litchar{#reader}, The reader recursively reads the next datum after @litchar{#reader},
and passes it to the procedure that is the value of the and passes it to the procedure that is the value of the
@scheme[current-reader-guard] @tech{parameter}; the result is used as a @racket[current-reader-guard] @tech{parameter}; the result is used as a
module path. The module path is passed to @scheme[dynamic-require] module path. The module path is passed to @racket[dynamic-require]
with either @scheme['read] or @scheme['read-syntax] (depending on with either @racket['read] or @racket['read-syntax] (depending on
whether the reader is in @scheme[read] or @scheme[read-syntax] whether the reader is in @racket[read] or @racket[read-syntax]
mode). mode).
The arity of the resulting procedure determines whether it accepts 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 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 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 optional arguments are the reader's module path (as a syntax object in
@scheme[read-syntax] mode) followed by the line (positive exact @racket[read-syntax] mode) followed by the line (positive exact
integer or @scheme[#f]), column (non-negative exact integer or integer or @racket[#f]), column (non-negative exact integer or
@scheme[#f]), and position (positive exact integer or @scheme[#f]) of @racket[#f]), and position (positive exact integer or @racket[#f]) of
the start of the @litchar{#reader} form. The input port is the one the start of the @litchar{#reader} form. The input port is the one
whose stream contained @litchar{#reader}, where the stream position is whose stream contained @litchar{#reader}, where the stream position is
immediately after the recursively-read module path. immediately after the recursively-read module path.
The procedure should produce a datum result. If the result is a 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 syntax object in @racket[read] mode, then it is converted to a datum
using @scheme[syntax->datum]; if the result is not a syntax object in using @racket[syntax->datum]; if the result is not a syntax object in
@scheme[read-syntax] mode, then it is converted to one using @racket[read-syntax] mode, then it is converted to one using
@scheme[datum->syntax]. See also @secref["reader-procs"] for @racket[datum->syntax]. See also @secref["reader-procs"] for
information on the procedure's results. information on the procedure's results.
If the @scheme[read-accept-reader] @tech{parameter} is set to If the @racket[read-accept-reader] @tech{parameter} is set to
@scheme[#f], then if the reader encounters @litchar{#reader}, the @racket[#f], then if the reader encounters @litchar{#reader}, the
@exnraise[exn:fail:read]. @exnraise[exn:fail:read].
@guideintro["hash-lang"]{@schememodfont["#lang"]} @guideintro["hash-lang"]{@racketmodfont["#lang"]}
The @as-index{@litchar{#lang}} reader form is similar to The @as-index{@litchar{#lang}} reader form is similar to
@litchar{#reader}, but more constrained: the @litchar{#lang} must be @litchar{#reader}, but more constrained: the @litchar{#lang} must be
followed by a single space (ASCII 32), and then a non-empty sequence followed by a single space (ASCII 32), and then a non-empty sequence
of alphanumeric ASCII, @litchar{+}, @litchar{-}, @litchar{_}, and/or of alphanumeric ASCII, @litchar{+}, @litchar{-}, @litchar{_}, and/or
@litchar{/} characters terminated by @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 sequence must not start or end with @litchar{/}. A sequence
@litchar{#lang }@nonterm{name} is equivalent to @litchar{#lang }@nonterm{name} is equivalent to
@litchar{#reader }@nonterm{name}@litchar{/lang/reader}. Note @litchar{#reader }@nonterm{name}@litchar{/lang/reader}. Note
that the terminating whitespace (if any) is not consumed before the that the terminating whitespace (if any) is not consumed before the
external reading procedure is called. 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.} domain-specific language for writing language readers.}
Finally, @as-index{@litchar{#!}} is a synonym for @litchar{#lang} 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] @defmodulelang[s-exp]
The @scheme[s-exp] ``language'' is a kind of meta-language. It The @racket[s-exp] ``language'' is a kind of meta-language. It
@scheme[read]s the S-expression that follows @litchar{#lang s-exp} and @racket[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 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 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, That is,
@schememod[ @racketmod[
s-exp _module-path s-exp _module-path
_form ... _form ...
] ]
is equivalent to is equivalent to
@schemeblock[ @racketblock[
(module _name _module-path (module _name _module-path
_form ...) _form ...)
] ]
@ -855,11 +855,11 @@ is equivalent to
@defmodulelang[reader] @defmodulelang[reader]
The @scheme[reader] ``language'' is a kind of meta-language. It The @racket[reader] ``language'' is a kind of meta-language. It
@scheme[read]s the S-expression that follows @litchar{#lang reader} @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 and uses it as a module path (relative to the module being read) that
effectively takes the place of @schememodname[reader]. In other words, effectively takes the place of @racketmodname[reader]. In other words,
the @schememodname[reader] meta-language generalizes the syntax of the the @racketmodname[reader] meta-language generalizes the syntax of the
module specified after @hash-lang[] to be a module path, and without module specified after @hash-lang[] to be a module path, and without
the implicit addition of @litchar{/lang/reader} to the path. the implicit addition of @litchar{/lang/reader} to the path.

158
collects/scribblings/reference/readtables.scrbl
View File

@ -4,15 +4,15 @@
@title[#:style 'toc]{Reader Extension} @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 procedure in a @tech{readtable} (see @secref["readtables"]), through a
@litchar{#reader} form (see @secref["parse-reader"]), or through a @litchar{#reader} form (see @secref["parse-reader"]), or through a
custom-port byte reader that returns a ``special'' result procedure custom-port byte reader that returns a ``special'' result procedure
(see @secref["customport"]). All three kinds of @deftech{reader (see @secref["customport"]). All three kinds of @deftech{reader
extension procedures} accept similar arguments, and their results are 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 more precisely, by the default read handler; see
@scheme[port-read-handler]). @racket[port-read-handler]).
@local-table-of-contents[] @local-table-of-contents[]
@ -21,7 +21,7 @@ more precisely, by the default read handler; see
The dispatch table in @secref["default-readtable-dispatch"] The dispatch table in @secref["default-readtable-dispatch"]
corresponds to the default @deftech{readtable}. By creating a new 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. parameter, the reader's behavior can be extended.
A readtable is consulted at specific times by the reader: 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 the parser is simply using the character that started the quote; it
does not consult the readtable. does not consult the readtable.
For many contexts, @scheme[#f] identifies the default readtable. In For many contexts, @racket[#f] identifies the default readtable. In
particular, @scheme[#f] is the initial value for the particular, @racket[#f] is the initial value for the
@scheme[current-readtable] parameter, which causes the reader to @racket[current-readtable] parameter, which causes the reader to
behave as described in @secref["reader"]. behave as described in @secref["reader"].
@defproc[(readtable? [v any/c]) boolean?]{ @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. otherwise.
} }
@ -79,43 +79,43 @@ otherwise.
...+) ...+)
readtable?]{ readtable?]{
Creates a new readtable that is like @scheme[readtable] (which can be Creates a new readtable that is like @racket[readtable] (which can be
@scheme[#f]), except that the reader's behavior is modified for each @racket[#f]), except that the reader's behavior is modified for each
@scheme[key] according to the given @scheme[mode] and @racket[key] according to the given @racket[mode] and
@scheme[action]. The @scheme[...+] for @scheme[make-readtable] applies @racket[action]. The @racket[...+] for @racket[make-readtable] applies
to all three of @scheme[key], @scheme[mode], and @scheme[action]; in to all three of @racket[key], @racket[mode], and @racket[action]; in
other words, the total number of arguments to @scheme[make-readtable] other words, the total number of arguments to @racket[make-readtable]
must be @math{1} modulo @math{3}. must be @math{1} modulo @math{3}.
The possible combinations for @scheme[key], @scheme[mode], and The possible combinations for @racket[key], @racket[mode], and
@scheme[action] are as follows: @racket[action] are as follows:
@itemize[ @itemize[
@item{@scheme[(code:line _char (unsyntax @indexed-scheme['terminating-macro]) _proc)] --- causes @item{@racket[(code:line _char (unsyntax @indexed-racket['terminating-macro]) _proc)] --- causes
@scheme[_char] to be parsed as a delimiter, and an @racket[_char] to be parsed as a delimiter, and an
unquoted/uncommented @scheme[_char] in the input string triggers a unquoted/uncommented @racket[_char] in the input string triggers a
call to the @deftech{reader macro} @scheme[_proc]; the activity of call to the @deftech{reader macro} @racket[_proc]; the activity of
@scheme[_proc] is described further below. Conceptually, characters @racket[_proc] is described further below. Conceptually, characters
like @litchar{;}, @litchar{(}, and @litchar{)} are mapped to like @litchar{;}, @litchar{(}, and @litchar{)} are mapped to
terminating reader macros in the default readtable.} terminating reader macros in the default readtable.}
@item{@scheme[(code:line _char (unsyntax @indexed-scheme['non-terminating-macro]) _proc)] --- like @item{@racket[(code:line _char (unsyntax @indexed-racket['non-terminating-macro]) _proc)] --- like
the @scheme['terminating-macro] variant, but @scheme[_char] is not the @racket['terminating-macro] variant, but @racket[_char] is not
treated as a delimiter, so it can be used in the middle of an treated as a delimiter, so it can be used in the middle of an
identifier or number. Conceptually, @litchar{#} is mapped to a identifier or number. Conceptually, @litchar{#} is mapped to a
non-terminating macro in the default readtable.} non-terminating macro in the default readtable.}
@item{@scheme[(code:line _char (unsyntax @indexed-scheme['dispatch-macro]) _proc)] --- like the @item{@racket[(code:line _char (unsyntax @indexed-racket['dispatch-macro]) _proc)] --- like the
@scheme['non-terminating-macro] variant, but for @scheme[_char] only @racket['non-terminating-macro] variant, but for @racket[_char] only
when it follows a @litchar{#} (or, more precisely, when the character when it follows a @litchar{#} (or, more precisely, when the character
follows one that has been mapped to the behavior of @litchar{#}hash follows one that has been mapped to the behavior of @litchar{#}hash
in the default readtable).} in the default readtable).}
@item{@scheme[(code:line _char _like-char _readtable)] --- causes @item{@racket[(code:line _char _like-char _readtable)] --- causes
@scheme[_char] to be parsed in the same way that @scheme[_like-char] @racket[_char] to be parsed in the same way that @racket[_like-char]
is parsed in @scheme[_readtable], where @scheme[_readtable] can be is parsed in @racket[_readtable], where @racket[_readtable] can be
@scheme[#f] to indicate the default readtable. Mapping a character to @racket[#f] to indicate the default readtable. Mapping a character to
the same actions as @litchar{|} in the default reader means that the the same actions as @litchar{|} in the default reader means that the
character starts quoting for symbols, and the same character character starts quoting for symbols, and the same character
terminates the quote; in contrast, mapping a character to the same 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 original character; for example, mapping a character to the same
action as a curly brace @litchar["{"] in the default readtable means action as a curly brace @litchar["{"] in the default readtable means
that the character is disallowed when the 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: replaces the macro used to parse characters with no specific mapping:
i.e., characters (other than @litchar{#} or @litchar{|}) that can i.e., characters (other than @litchar{#} or @litchar{|}) that can
start a symbol or number with the default readtable.} start a symbol or number with the default readtable.}
] ]
If multiple @scheme['dispatch-macro] mappings are provided for a If multiple @racket['dispatch-macro] mappings are provided for a
single @scheme[_char], all but the last one are ignored. Similarly, if single @racket[_char], all but the last one are ignored. Similarly, if
multiple non-@scheme['dispatch-macro] mappings are provided for a multiple non-@racket['dispatch-macro] mappings are provided for a
single @scheme[_char], all but the last one are ignored. 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 optionally accept two arguments. The first two arguments are always
the character that triggered the reader macro and the input port for the character that triggered the reader macro and the input port for
reading. When the reader macro is triggered by @scheme[read-syntax] reading. When the reader macro is triggered by @racket[read-syntax]
(or @scheme[read-syntax/recursive]), the procedure is passed four (or @racket[read-syntax/recursive]), the procedure is passed four
additional arguments that represent a source location. When the reader 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, procedure is passed only two arguments if it accepts two arguments,
otherwise it is passed six arguments where the last four are all 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. procedure's results.
A reader macro normally reads characters from the given input port to 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 consumed characters. The reader macro might produce a special-comment
value (see @secref["special-comments"]) to cause the consumed value (see @secref["special-comments"]) to cause the consumed
character to be treated as whitespace, and it might use 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?]) @defproc[(readtable-mapping [readtable readtable?][char character?])
(values (or/c 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?)
(or/c #f procedure?))]{ (or/c #f procedure?))]{
Produces information about the mappings in @scheme[readtable] for Produces information about the mappings in @racket[readtable] for
@scheme[char]. The result is three values: @racket[char]. The result is three values:
@itemize[ @itemize[
@item{either a character (mapping is to same behavior as the @item{either a character (mapping is to same behavior as the
character in the default readtable), @scheme['terminating-macro], or character in the default readtable), @racket['terminating-macro], or
@scheme['non-terminating-macro]; this result reports the main (i.e., @racket['non-terminating-macro]; this result reports the main (i.e.,
non-@scheme['dispatch-macro]) mapping for @scheme[key]. When the result non-@racket['dispatch-macro]) mapping for @racket[key]. When the result
is a character, then @scheme[key] is mapped to the same behavior as the is a character, then @racket[key] is mapped to the same behavior as the
returned character in the default readtable.} returned character in the default readtable.}
@item{either @scheme[#f] or a reader-macro procedure; the result is a @item{either @racket[#f] or a reader-macro procedure; the result is a
procedure when the first result is @scheme['terminating-macro] or procedure when the first result is @racket['terminating-macro] or
@scheme['non-terminating-macro].} @racket['non-terminating-macro].}
@item{either @scheme[#f] or a reader-macro procedure; the result is a @item{either @racket[#f] or a reader-macro procedure; the result is a
procedure when the character has a @scheme['dispatch-macro] mapping in procedure when the character has a @racket['dispatch-macro] mapping in
@scheme[readtable] to override the default dispatch behavior.} @racket[readtable] to override the default dispatch behavior.}
] ]
Note that reader-macro procedures for the default readtable are not Note that reader-macro procedures for the default readtable are not
directly accessible. To invoke default behaviors, use directly accessible. To invoke default behaviors, use
@scheme[read/recursive] or @scheme[read-syntax/recursive] with a @racket[read/recursive] or @racket[read-syntax/recursive] with a
character and the @scheme[#f] readtable.} character and the @racket[#f] readtable.}
@(begin @(begin
#readerscribble/comment-reader #readerscribble/comment-reader
[examples [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) (require syntax/readerr)
(define (skip-whitespace port) (define (skip-whitespace port)
@ -326,38 +326,38 @@ character and the @scheme[#f] readtable.}
@section[#:tag "reader-procs"]{Reader-Extension Procedures} @section[#:tag "reader-procs"]{Reader-Extension Procedures}
Calls to @techlink{reader extension procedures} can be triggered Calls to @techlink{reader extension procedures} can be triggered
through @scheme[read], @scheme[read/recursive], @scheme[read-syntax], through @racket[read], @racket[read/recursive], @racket[read-syntax],
or @scheme[read-honu-syntax]. In addition, a special-read procedure or @racket[read-honu-syntax]. In addition, a special-read procedure
can be triggered by calls to @scheme[read-honu], can be triggered by calls to @racket[read-honu],
@scheme[read-honu/recursive], @scheme[read-honu-syntax], @racket[read-honu/recursive], @racket[read-honu-syntax],
@scheme[read-honu-syntax/recursive], @scheme[read-char-or-special], or @racket[read-honu-syntax/recursive], @racket[read-char-or-special], or
by the context of @scheme[read-bytes-avail!], by the context of @racket[read-bytes-avail!],
@scheme[read-bytes-avail!*], @scheme[read-bytes-avail!], and @racket[read-bytes-avail!*], @racket[read-bytes-avail!], and
@scheme[peek-bytes-avail!*]. @racket[peek-bytes-avail!*].
Optional arities for reader-macro and special-result procedures allow Optional arities for reader-macro and special-result procedures allow
them to distinguish reads via @scheme[read], @|etc| from reads via them to distinguish reads via @racket[read], @|etc| from reads via
@scheme[read-syntax], @|etc| (where the source value is @scheme[#f] and @racket[read-syntax], @|etc| (where the source value is @racket[#f] and
no other location information is available). no other location information is available).
When a reader-extension procedure is called in syntax-reading mode 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 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 and with the given location information as the third
argument). Another possible result is a special-comment value (see argument). Another possible result is a special-comment value (see
@secref["special-comments"]). If the procedure's result is not a @secref["special-comments"]). If the procedure's result is not a
syntax object and not a special-comment value, it is converted to one 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 When a reader-extension procedure is called in non-syntax-reading
modes, it should generally not return a syntax object. If a syntax modes, it should generally not return a syntax object. If a syntax
object is returned, it is converted to a plain value using 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 In either context, when the result from a reader-extension procedure
is a special-comment value (see @secref["special-comments"]), then 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. delimiting comment and otherwise ignore it.
Also, in either context, the result may be copied to prevent mutation 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 vectors, and @tech{prefab} structures are copied, along with any
pairs, boxes, vectors, pre prefab structures that lead to such mutable pairs, boxes, vectors, pre prefab structures that lead to such mutable
values, to placeholders produced by a recursive read (see 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. 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?]{ @defproc[(make-special-comment [v any/c]) special-comment?]{
Creates a special-comment value that encapsulates @scheme[v]. The Creates a special-comment value that encapsulates @racket[v]. The
@scheme[read], @scheme[read-syntax], @|etc| procedures treat values @racket[read], @racket[read-syntax], @|etc| procedures treat values
constructed with @scheme[make-special-comment] as delimiting constructed with @racket[make-special-comment] as delimiting
whitespace when returned by a reader-extension procedure (see whitespace when returned by a reader-extension procedure (see
@secref["reader-procs"]).} @secref["reader-procs"]).}
@defproc[(special-comment? [v any/c]) boolean?]{ @defproc[(special-comment? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is the result of Returns @racket[#t] if @racket[v] is the result of
@scheme[make-special-comment], @scheme[#f] otherwise.} @racket[make-special-comment], @racket[#f] otherwise.}
@defproc[(special-comment-value [sc special-comment?]) any]{ @defproc[(special-comment-value [sc special-comment?]) any]{
Returns the value encapsulated by the special-comment value Returns the value encapsulated by the special-comment value
@scheme[sc]. This value is never used directly by a reader, but it @racket[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| might be used by the context of a @racket[read-char-or-special], @|etc|
call that detects a special comment.} call that detects a special comment.}

10
collects/scribblings/reference/reference.scrbl
View File

@ -6,7 +6,7 @@
scribble/core scribble/core
racket/list) racket/list)
@(define (scheme-extra-libs) @(define (racket-extra-libs)
(make-delayed-element (make-delayed-element
(lambda (renderer p ri) (lambda (renderer p ri)
(let ([mods (append-map (let ([mods (append-map
@ -35,7 +35,7 @@ friendlier (though less precise and less complete) overview of the
language. language.
@defmodulelang*[(racket/base racket) @defmodulelang*[(racket/base racket)
;; Use sources for overlap with `mzscheme': ;; Use sources for overlap with `scheme' and `mzscheme':
#:use-sources ('#%kernel #:use-sources ('#%kernel
racket/private/more-scheme racket/private/more-scheme
racket/private/misc racket/private/misc
@ -48,11 +48,11 @@ language.
racket/private/base)]{ racket/private/base)]{
Unless otherwise noted, the bindings defined in this manual are 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.} languages.}
@margin-note{The @schememodname[racket] library combines @margin-note{The @racketmodname[racket] library combines
@schememodname[racket/base]@scheme-extra-libs[].} @racketmodname[racket/base]@racket-extra-libs[].}
@table-of-contents[] @table-of-contents[]

2
collects/scribblings/reference/running.scrbl
View File

@ -1,7 +1,7 @@
#lang scribble/doc #lang scribble/doc
@(require "mz.ss") @(require "mz.ss")
@title[#:tag "running" #:style 'toc]{Running PLT Scheme} @title[#:tag "running" #:style 'toc]{Running Racket}
@local-table-of-contents[] @local-table-of-contents[]

120
collects/scribblings/reference/runtime.scrbl
View File

@ -6,60 +6,60 @@
@defproc[(getenv [name string?]) (or/c string? #f)]{ @defproc[(getenv [name string?]) (or/c string? #f)]{
Gets the value of an operating system environment variable. The Gets the value of an operating system environment variable. The
@scheme[name] argument cannot contain a null character; if an @racket[name] argument cannot contain a null character; if an
environment variable named by @scheme[name] exists, its value is environment variable named by @racket[name] exists, its value is
returned (as a string); otherwise, @scheme[#f] is returned.} returned (as a string); otherwise, @racket[#f] is returned.}
@defproc[(putenv [name string?][value string?]) boolean?]{ @defproc[(putenv [name string?][value string?]) boolean?]{
Sets the value of an operating system environment variable. The 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 contain a null character; the environment variable named by
@scheme[name] is set to @scheme[value]. The return value is @racket[name] is set to @racket[value]. The return value is
@scheme[#t] if the assignment succeeds, @scheme[#f] otherwise.} @racket[#t] if the assignment succeeds, @racket[#f] otherwise.}
@defproc[(system-type [mode (or/c 'os 'gc 'link 'so-suffix 'machine) @defproc[(system-type [mode (or/c 'os 'gc 'link 'so-suffix 'machine)
'os]) 'os])
(or/c symbol? string? bytes?)]{ (or/c symbol? string? bytes?)]{
Returns information about the operating system, build mode, or machine 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: the possible symbol results are:
@itemize[ @itemize[
@item{@indexed-scheme['unix]} @item{@indexed-racket['unix]}
@item{@indexed-scheme['windows]} @item{@indexed-racket['windows]}
@item{@indexed-scheme['macosx]} @item{@indexed-racket['macosx]}
] ]
In @indexed-scheme['gc] mode, In @indexed-racket['gc] mode,
the possible symbol results are: the possible symbol results are:
@itemize[ @itemize[
@item{@indexed-scheme['cgc]} @item{@indexed-racket['cgc]}
@item{@indexed-scheme['3m]} @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[ @itemize[
@item{@indexed-scheme['static] (Unix)} @item{@indexed-racket['static] (Unix)}
@item{@indexed-scheme['shared] (Unix)} @item{@indexed-racket['shared] (Unix)}
@item{@indexed-scheme['dll] (Windows)} @item{@indexed-racket['dll] (Windows)}
@item{@indexed-scheme['framework] (Mac OS X)} @item{@indexed-racket['framework] (Mac OS X)}
] ]
Future ports of Scheme may expand the list of @scheme['os], Future ports of Racket may expand the list of @racket['os],
@scheme['gc], and @scheme['link] results. @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 that represents the file extension used for shared objects on the
current platform. The byte string starts with a period, so it is 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 contains further details about the current machine in a
platform-specific format.} platform-specific format.}
@ -89,27 +89,27 @@ Mac OS X, the result is determined by system calls.}
path?]{ path?]{
Returns a relative directory path. This string can be used to build 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 under Solaris on a Sparc architecture, the subpath starts
@scheme["sparc-solaris"], while the subpath for Windows on an i386 @racket["sparc-solaris"], while the subpath for Windows on an i386
architecture starts @scheme["win32\\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 garbage-collection variant, which one of the possible results of
@scheme[(system-type 'gc)]: @scheme['cgc] or @scheme['3m]. It can also @racket[(system-type 'gc)]: @racket['cgc] or @racket['3m]. It can also
be @scheme[#f], in which case the result is independent of the be @racket[#f], in which case the result is independent of the
garbage-collection variant.} garbage-collection variant.}
@defproc[(version) (and/c string? immutable?)]{ @defproc[(version) (and/c string? immutable?)]{
Returns an string indicating the currently executing version of Returns an string indicating the currently executing version of
Scheme.} Racket.}
@defproc[(banner) (and/c string? immutable?)]{ @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 banner text for an embedding program, such as MrEd). The banner string
ends with a newline.} ends with a newline.}
@ -117,7 +117,7 @@ ends with a newline.}
@defparam[current-command-line-arguments argv (vectorof (and/c string? immutable?))]{ @defparam[current-command-line-arguments argv (vectorof (and/c string? immutable?))]{
A parameter that is initialized with command-line arguments when 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).} treated as flags for the system).}
@ -134,56 +134,56 @@ otherwise platform-independent.}
[thd (or/c thread? #f) #f]) [thd (or/c thread? #f) #f])
void?]{ void?]{
Sets elements in @scheme[results] to report current performance Sets elements in @racket[results] to report current performance
statistics. If @scheme[thd] is not @scheme[#f], a particular set of statistics. If @racket[thd] is not @racket[#f], a particular set of
thread-specific statistics are reported, otherwise a different set of thread-specific statistics are reported, otherwise a different set of
global statics are reported. global statics are reported.
For global statistics, up to @math{10} elements are set in the vector, For global statistics, up to @math{10} elements are set in the vector,
starting from the beginning. (In future versions of Scheme, additional starting from the beginning. (In future versions of Racket, additional
elements will be set.) If @scheme[results] has @math{n} elements where 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} @math{n < 8}, then the @math{n} elements are set to the first @math{n}
performance-statistics values. The reported statistics values are as 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[ @itemize[
@item{@scheme[0]: The same value as returned by @item{@racket[0]: The same value as returned by
@scheme[current-process-milliseconds].} @racket[current-process-milliseconds].}
@item{@scheme[1]: The same value as returned @item{@racket[1]: The same value as returned
by @scheme[current-milliseconds].} by @racket[current-milliseconds].}
@item{@scheme[2]: The same value as returned @item{@racket[2]: The same value as returned
by @scheme[current-gc-milliseconds].} 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.} 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.} 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.} 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 execution (i.e., threads that are running, not suspended, and not
unscheduled due to a synchronization).} 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.} 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 this counter reaches the maximum value of a @tech{fixnum}, it
overflows to the most negative @tech{fixnum}.} 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 complete hash searches (using double hashing). When this counter
reaches the maximum value of a @tech{fixnum}, it overflows to the reaches the maximum value of a @tech{fixnum}, it overflows to the
most negative @tech{fixnum}.} most negative @tech{fixnum}.}
@item{@scheme[10]: The number of bytes allocated for machine code @item{@racket[10]: The number of bytes allocated for machine code
that is not reported by @scheme[current-memory-use].} that is not reported by @racket[current-memory-use].}
] ]
@ -192,17 +192,17 @@ vector:
@itemize[ @itemize[
@item{@scheme[0]: @scheme[#t] if the thread is running, @scheme[#f] @item{@racket[0]: @racket[#t] if the thread is running, @racket[#f]
otherwise (same result as @scheme[thread-running?]).} otherwise (same result as @racket[thread-running?]).}
@item{@scheme[1]: @scheme[#t] if the thread has terminated, @item{@racket[1]: @racket[#t] if the thread has terminated,
@scheme[#f] otherwise (same result as @scheme[thread-dead?]).} @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), 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.} thread's continuation.}
] ]

426
collects/scribblings/reference/sandbox.scrbl
View File

@ -1,19 +1,19 @@
#lang scribble/doc #lang scribble/doc
@(require "mz.ss" @(require "mz.ss"
scheme/sandbox racket/sandbox
(for-label scheme/sandbox (for-label racket/sandbox
racket/port racket/port
(only-in racket/gui make-gui-namespace) (only-in racket/gui make-gui-namespace)
racket/gui/dynamic)) racket/gui/dynamic))
@(define box-eval (make-base-eval)) @(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} @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 creating ``sandboxed'' evaluators, which are configured in a
particular way and can have restricted resources (memory and time), particular way and can have restricted resources (memory and time),
filesystem and network access, and much more. Sandboxed evaluators can be 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?))]) [#:allow-read allow (listof (or/c module-path? path?))])
(any/c . -> . any)])]{ (any/c . -> . any)])]{
The @scheme[make-evaluator] function creates an evaluator with a The @racket[make-evaluator] function creates an evaluator with a
@scheme[language] and @scheme[requires] specification, and starts @racket[language] and @racket[requires] specification, and starts
evaluating the given @scheme[input-program]s. The evaluating the given @racket[input-program]s. The
@scheme[make-module-evaluator] function creates an evaluator that @racket[make-module-evaluator] function creates an evaluator that
works in the context of a given module. The result in either case is a works in the context of a given module. The result in either case is a
function for further evaluation. function for further evaluation.
The returned evaluator operates in an isolated and limited The returned evaluator operates in an isolated and limited
environment. In particular, filesystem access is restricted. The 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 the evaluator to include the specified modules and their imports
(transitively). When @scheme[language] is a module path and when (transitively). When @racket[language] is a module path and when
@scheme[requires] is provided, the indicated modules are implicitly @racket[requires] is provided, the indicated modules are implicitly
included in the @scheme[allow] list. 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: a program in one of the following forms:
@itemize[ @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{a path that names a file holding the input; or}
@item{an S-expression or a @tech{syntax object}, which is evaluated @item{an S-expression or a @tech{syntax object}, which is evaluated
as with @scheme[eval] (see also as with @racket[eval] (see also
@scheme[get-uncovered-expressions]).} @racket[get-uncovered-expressions]).}
] ]
In the first three cases above, the program is read using In the first three cases above, the program is read using
@scheme[sandbox-reader], with line-counting enabled for sensible error @racket[sandbox-reader], with line-counting enabled for sensible error
messages, and with @scheme['program] as the source (used for testing messages, and with @racket['program] as the source (used for testing
coverage). In the last case, the input is expected to be the complete coverage). In the last case, the input is expected to be the complete
program, and is converted to a @tech{syntax object} (using 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}. object}.
The returned evaluator function accepts additional expressions The returned evaluator function accepts additional expressions
(each time it is called) in essentially the same form: a string or (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 byte string holding a sequence of expressions, a path for a file
holding expressions, an S-expression, or a @tech{syntax object}. If holding expressions, an S-expression, or a @tech{syntax object}. If
the evaluator receives an @scheme[eof] value, it is terminated and the evaluator receives an @racket[eof] value, it is terminated and
raises errors thereafter. See also @scheme[kill-evaluator], which raises errors thereafter. See also @racket[kill-evaluator], which
terminates the evaluator without raising an exception. 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 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: argument:
@itemize[ @itemize[
@item{The @scheme[language] argument can be a module path (i.e., a @item{The @racket[language] argument can be a module path (i.e., a
datum that matches the grammar for @scheme[_module-path] of datum that matches the grammar for @racket[_module-path] of
@scheme[require]). @racket[require]).
In this case, the @scheme[input-program]s are automatically In this case, the @racket[input-program]s are automatically
wrapped in a @scheme[module], and the resulting evaluator works wrapped in a @racket[module], and the resulting evaluator works
within the resulting module's namespace.} within the resulting module's namespace.}
@item{The @scheme[language] argument can be a list starting with @item{The @racket[language] argument can be a list starting with
@scheme['special], which indicates a built-in language with @racket['special], which indicates a built-in language with
special input configuration. The possible values are special input configuration. The possible values are
@scheme['(special r5rs)] or a value indicating a teaching @racket['(special r5rs)] or a value indicating a teaching
language: @scheme['(special beginner)], @scheme['(special language: @racket['(special beginner)], @racket['(special
beginner-abbr)], @scheme['(special intermediate)], beginner-abbr)], @racket['(special intermediate)],
@scheme['(special intermediate-lambda)], or @scheme['(special @racket['(special intermediate-lambda)], or @racket['(special
advanced)]. advanced)].
In this case, the @scheme[input-program]s are automatically In this case, the @racket[input-program]s are automatically
wrapped in a @scheme[module], and the resulting evaluator works wrapped in a @racket[module], and the resulting evaluator works
within the resulting module's namespace. In addition, certain 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. set to customize reading programs from strings and ports.
This option is provided mainly for older test systems. Using This option is provided mainly for older test systems. Using
@scheme[make-module-evaluator] with input starting with @racket[make-module-evaluator] with input starting with
@schememodfont{#lang} is generally better.} @racketmodfont{#lang} is generally better.}
@item{Finally, @scheme[language] can be a list whose first element is @item{Finally, @racket[language] can be a list whose first element is
@scheme['begin]. @racket['begin].
In this case, a new namespace is created using In this case, a new namespace is created using
@scheme[sandbox-namespace-specs], which by default creates a @racket[sandbox-namespace-specs], which by default creates a
new namespace using @scheme[make-base-namespace] or new namespace using @racket[make-base-namespace] or
@scheme[make-gui-namespace] (depending on @scheme[gui?]). @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.} expression to further initialize the namespace.}
] ]
The @scheme[requires] list adds additional imports to the module or The @racket[requires] list adds additional imports to the module or
namespace for the @scheme[input-program]s, even in the case that namespace for the @racket[input-program]s, even in the case that
@scheme[require] is not made available through the @scheme[language]. @racket[require] is not made available through the @racket[language].
The following examples illustrate the difference between an evaluator The following examples illustrate the difference between an evaluator
that puts the program in a module and one that merely initializes a that puts the program in a module and one that merely initializes a
@ -152,23 +152,23 @@ top-level namespace:
(base-top-eval '(f)) (base-top-eval '(f))
] ]
The @scheme[make-module-evaluator] function is essentially a The @racket[make-module-evaluator] function is essentially a
restriction of @scheme[make-evaluator], where the program must be 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 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 useful to restrict the program to be a module using a spcific module
in its language position --- use the optional @scheme[lang] argument in its language position --- use the optional @racket[lang] argument
to specify such a restriction (the default, @scheme[#f], means no to specify such a restriction (the default, @racket[#f], means no
restriction is enforced). restriction is enforced).
@schemeblock[ @racketblock[
(define base-module-eval2 (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 (make-module-evaluator '(module m racket/base
(define (f) later) (define (f) later)
(define later 5)))) (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 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 name, and you get back an evaluator in the module's context which you
can use with your favorite test facility. can use with your favorite test facility.
@ -177,22 +177,22 @@ In all cases, the evaluator operates in an isolated and limited
environment: environment:
@itemize[ @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.} 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.} which restricts file system and network access.}
@item{The evaluator is contained in a memory-restricted environment, @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 (when memory accounting is available); see also
@scheme[sandbox-memory-limit], @scheme[sandbox-eval-limits] and @racket[sandbox-memory-limit], @racket[sandbox-eval-limits] and
@scheme[set-eval-limits].} @racket[set-eval-limits].}
] ]
Note that these limits apply to the creation of the sandbox Note that these limits apply to the creation of the sandbox
environment too --- so, for example, if the memory that is required to environment too --- so, for example, if the memory that is required to
create the sandbox is higher than the limit, then 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 The sandboxed evironment is well isolated, and the evaluator function
essentially sends it an expression and waits for a result. This form 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 calls to a single evaluator. Usually this is not a problem, but in
some cases you can get the evaluator function available inside the some cases you can get the evaluator function available inside the
sandboxed code, for example: sandboxed code, for example:
@schemeblock[ @racketblock[
(let ([e (make-evaluator 'racket/base)]) (let ([e (make-evaluator 'racket/base)])
(e (,e 1))) (e (,e 1)))
] ]
An error will be signalled in such cases. An error will be signalled in such cases.
Evaluation can also be instrumented to track coverage information when 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 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 that a sandboxed evaluator is convenient for testing, since all
exceptions happen in the same way, so you don't need special code to exceptions happen in the same way, so you don't need special code to
catch syntax errors. catch syntax errors.
Finally, the fact that a sandboxed evaluator accept syntax objects 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 that you can easily start a sandboxed read-eval-print-loop. For
example, here is a quick implementation of a networked REPL: example, here is a quick implementation of a networked REPL:
@schemeblock[ @racketblock[
(define e (make-evaluator 'racket/base)) (define e (make-evaluator 'racket/base))
(let-values ([(i o) (tcp-accept (tcp-listen 9999))]) (let-values ([(i o) (tcp-accept (tcp-listen 9999))])
(parameterize ([current-input-port i] (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 over the network connection; using I/O operations inside the REPL will
still use the usual sandbox parameters (defaulting to no I/O). In still use the usual sandbox parameters (defaulting to no I/O). In
addition, the code works only from an existing toplevel REPL --- 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 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 variation that uses the networked ports for user I/O, and works when
used from a module (by using a new namespace): used from a module (by using a new namespace):
@schemeblock[ @racketblock[
(let-values ([(i o) (tcp-accept (tcp-listen 9999))]) (let-values ([(i o) (tcp-accept (tcp-listen 9999))])
(parameterize ([current-input-port i] (parameterize ([current-input-port i]
[current-output-port o] [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 is terminated. Once a sandbox raises such an exception, it will
continue to raise it on further evaluation attempts. continue to raise it on further evaluation attempts.
@scheme[call-with-limits]. The @scheme[resource] field holds a symbol, @racket[call-with-limits]. The @racket[resource] field holds a symbol,
either @scheme['time] or @scheme['memory].} either @racket['time] or @racket['memory].}
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@section{Customizing Evaluators} @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 customized via many parameters. Most of the configuration parameters
affect newly created evaluators; changing them has no effect on affect newly created evaluators; changing them has no effect on
already-running evaluators. 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 needed, or if you want tighter restrictions. Another useful approach
for customizing an evaluator is to begin with a relatively for customizing an evaluator is to begin with a relatively
unrestricted configuration and add the desired restrictions. This is 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. function.
@defproc[(call-with-trusted-sandbox-configuration [thunk (-> any)]) @defproc[(call-with-trusted-sandbox-configuration [thunk (-> any)])
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 parameters are set for minimal restrictions. More specifically, there
are no memory or time limits, and the existing existing inspectors, are no memory or time limits, and the existing existing inspectors,
security guard, exit handler, and logger are used. (Note that the I/O 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 new evaluator. The hook is called just before the program is
evaluated in a newly-created evaluator context. It can be used to evaluated in a newly-created evaluator context. It can be used to
setup environment parameters related to reading, writing, evaluation, 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 teaching languages) have initializations specific to the language; the
hook is used after that initialization, so it can override settings.} 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)]{ @defparam[sandbox-reader proc (any/c . -> . any)]{
A parameter that specifies a function that reads all expressions from 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 source for an evaluator when a string, byte string, or port is
supplied. The reader function receives a value to be used as input 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 should return a list of @tech{syntax objects}. The default reader
calls @scheme[read-syntax], accumulating results in a list until it calls @racket[read-syntax], accumulating results in a list until it
receives @scheme[eof].} receives @racket[eof].}
@defparam[sandbox-input in (or/c #f @defparam[sandbox-input in (or/c #f
@ -328,23 +328,23 @@ receives @scheme[eof].}
'pipe 'pipe
(-> input-port?))]{ (-> input-port?))]{
A parameter that determines the initial @scheme[current-input-port] A parameter that determines the initial @racket[current-input-port]
setting for a newly created evaluator. It defaults to @scheme[#f], setting for a newly created evaluator. It defaults to @racket[#f],
which creates an empty port. The following other values are allowed: which creates an empty port. The following other values are allowed:
@itemize[ @itemize[
@item{a string or byte string, which is converted to a port using @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{an input port;}
@item{the symbol @scheme['pipe], which triggers the creation of a @item{the symbol @racket['pipe], which triggers the creation of a
pipe, where @scheme[put-input] can return the output end of the pipe, where @racket[put-input] can return the output end of the
pipe or write directly to it;} pipe or write directly to it;}
@item{a thunk, which is called to obtain a port (e.g., using @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).} the same as the calling context's input).}
]} ]}
@ -357,8 +357,8 @@ which creates an empty port. The following other values are allowed:
'string 'string
(-> output-port?))]{ (-> output-port?))]{
A parameter that determines the initial @scheme[current-output-port] A parameter that determines the initial @racket[current-output-port]
setting for a newly created evaluator. It defaults to @scheme[#f], setting for a newly created evaluator. It defaults to @racket[#f],
which creates a port that discrds all data. The following other which creates a port that discrds all data. The following other
values are allowed: values are allowed:
@ -366,19 +366,19 @@ values are allowed:
@item{an output port, which is used as-is;} @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;} to return the complete output as a byte string;}
@item{the symbol @scheme['string], which is similar to @item{the symbol @racket['string], which is similar to
@scheme['bytes], but makes @scheme[get-output] produce a @racket['bytes], but makes @racket[get-output] produce a
string;} string;}
@item{the symbol @scheme['pipe], which triggers the creation of a @item{the symbol @racket['pipe], which triggers the creation of a
pipe, where @scheme[get-output] returns the input end of the pipe, where @racket[get-output] returns the input end of the
pipe;} pipe;}
@item{a thunk, which is called to obtain a port (e.g., using @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).} not diverted).}
]} ]}
@ -391,13 +391,13 @@ values are allowed:
'string 'string
(-> output-port?))]{ (-> output-port?))]{
Like @scheme[sandbox-output], but for the initial Like @racket[sandbox-output], but for the initial
@scheme[current-error-port] value. An evaluator's error output is set @racket[current-error-port] value. An evaluator's error output is set
after its output, so using @scheme[current-output-port] (the parameter after its output, so using @racket[current-output-port] (the parameter
itself, not its value) for this parameter value means that the error itself, not its value) for this parameter value means that the error
port is the same as the evaluator's initial output port. 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 (current-error-port)))], which means that the error output of the
generated evaluator goes to the calling context's error port.} 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 A parameter that controls whether syntactic coverage information is
collected by sandbox evaluators. Use 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?]{ @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 breaking while an evaluator is
running propagates the break signal to the sandboxed running propagates the break signal to the sandboxed
context. This makes the sandboxed evaluator break, typically, but 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 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 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 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?) @defparam[sandbox-namespace-specs spec (cons/c (-> namespace?)
(listof module-path?))]{ (listof module-path?))]{
A parameter that holds a list of values that specify how to create a A parameter that holds a list of values that specify how to create a
namespace for evaluation in @scheme[make-evaluator] or namespace for evaluation in @racket[make-evaluator] or
@scheme[make-module-evaluator]. The first item in the list is a thunk @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 that creates the namespace, and the rest are module paths for modules
to be attached to the created namespace using 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 The default is @racket[(list make-base-namespace)] if @racket[gui?] is
@scheme[#f], @scheme[(list make-gui-namespace)] if @scheme[gui?] is @racket[#f], @racket[(list make-gui-namespace)] if @racket[gui?] is
@scheme[#t]. @racket[#t].
The module paths are needed for sharing module instantiations between The module paths are needed for sharing module instantiations between
the sandbox and the caller. For example, sandbox code that returns 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 not be recognized as such by your own code by default, since the
sandbox will have its own instance of @schemeidfont{lang/posn} and sandbox will have its own instance of @racketidfont{lang/posn} and
thus its own struct type for @scheme[posn]s. To be able to use such thus its own struct type for @racket[posn]s. To be able to use such
values, include @scheme['lang/posn] in the list of module paths. values, include @racket['lang/posn] in the list of module paths.
When testing code that uses a teaching language, the following piece When testing code that uses a teaching language, the following piece
of code can be helpful: of code can be helpful:
@schemeblock[ @racketblock[
(sandbox-namespace-specs (sandbox-namespace-specs
(let ([specs (sandbox-namespace-specs)]) (let ([specs (sandbox-namespace-specs)])
`(,(car specs) `(,(car specs)
@ -463,24 +463,24 @@ of code can be helpful:
@defparam[sandbox-override-collection-paths paths (listof path-string?)]{ @defparam[sandbox-override-collection-paths paths (listof path-string?)]{
A parameter that determines a list of collection directories to prefix 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 parameter is useful for cases when you want to test code using an
alternate, test-friendly version of a collection, for example, testing 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 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 @defparam[sandbox-security-guard guard
(or/c security-guard? (-> security-guard?))]{ (or/c security-guard? (-> security-guard?))]{
A parameter that determines the initial 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 be either a security guard, or a function to construct one. The
default is a function that restricts the access of the current default is a function that restricts the access of the current
security guard by forbidding all filesystem I/O except for security guard by forbidding all filesystem I/O except for
specifications in @scheme[sandbox-path-permissions], and it uses specifications in @racket[sandbox-path-permissions], and it uses
@scheme[sandbox-network-guard] for network connections.} @racket[sandbox-network-guard] for network connections.}
@defparam[sandbox-path-permissions perms @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 each is an access mode and a byte-regexp for paths that are granted this
access. access.
The access mode symbol is one of: @scheme['execute], @scheme['write], The access mode symbol is one of: @racket['execute], @racket['write],
@scheme['delete], @scheme['read], or @scheme['exists]. These symbols @racket['delete], @racket['read], or @racket['exists]. These symbols
are in decreasing order: each implies access for the following modes 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 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 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 (made into a complete path, cleansed, simplified, and then) converted
to a regexp that allows the path and sub-directories; e.g., 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 linear order of these modes. Specifying this mode is similar to
specifying @scheme['read], but it is not implied by any other mode. specifying @racket['read], but it is not implied by any other mode.
(For example, even if you specify @scheme['write] for a certain path, (For example, even if you specify @racket['write] for a certain path,
you need to also specify @scheme['read-bytecode] to grant this you need to also specify @racket['read-bytecode] to grant this
permission.) The sandbox usually works in the context of a lower code 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 of untrusted bytecode files --- the sandbox is set-up to allow
loading bytecode from files that are specified with 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 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, argument. (Note that this applies for loading bytecode files only,
under a lower code inspector it is still impossible to use protected under a lower code inspector it is still impossible to use protected
module bindings (see @secref["modprotect"]).) module bindings (see @secref["modprotect"]).)
The default value is null, but when an evaluator is created, it is 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 to use collection libraries (including
@scheme[sandbox-override-collection-paths]). See @racket[sandbox-override-collection-paths]). See
@scheme[make-evalautor] for more information.} @racket[make-evalautor] for more information.}
@defparam[sandbox-network-guard proc @defparam[sandbox-network-guard proc
@ -536,16 +536,16 @@ to use collection libraries (including
. -> . any)]{ . -> . any)]{
A parameter that specifieds a procedure to be used (as is) by the 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.} network connection.}
@defparam[sandbox-exit-handler handler (any/c . -> . any)]{ @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 sandboxed evaluations. The default kills the evaluator with an
appropriate error message (see 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)]{ @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 megabytes (it can hold a rational or a floating point number). When
this limit is exceeded, the sandbox is terminated. This value is used this limit is exceeded, the sandbox is terminated. This value is used
when the sandbox is created and the limit cannot be changed 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 for per-evaluation limits and a description of how the two limits work
together. 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 This policy has an impact on how the sandbox memory limit interacts
with the per-expression limit specified by 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, as well as from the interaction will count against the
sandbox limit. For example, in the last interaction of this code, sandbox limit. For example, in the last interaction of this code,
@schemeblock[ @racketblock[
(define e (make-evaluator 'racket/base)) (define e (make-evaluator 'racket/base))
(e '(define a 1)) (e '(define a 1))
(e '(for ([i (in-range 20)]) (set! a (cons (make-bytes 500000) a)))) (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)]{ #f)]{
A parameter that determines the default limits on @italic{each} use of 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; 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 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). memory limit in megabytes (note that they don't have to be integers).
Either one can be @scheme[#f] for disabling the corresponding limit; Either one can be @racket[#f] for disabling the corresponding limit;
alternately, the parameter can be set to @scheme[#f] to disable all alternately, the parameter can be set to @racket[#f] to disable all
per-evaluation limits (useful in case more limit kinds are available 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 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, fail if the limits are strict enough. For example,
@schemeblock[ @racketblock[
(parameterize ([sandbox-eval-limits '(0.25 5)]) (parameterize ([sandbox-eval-limits '(0.25 5)])
(make-evaluator 'racket/base '(sleep 2))) (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 avoid surprises you need to catch errors that happen when the sandbox
is created. 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 around each use of the evaluator, so consuming too much time or memory
results in an exception. Change the limits of a running evaluator 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 @margin-note{A custodian's limit is checked only after a garbage
collection, except that it may also be checked during 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 The memory limit that is specified by this parameter applies to each
individual evaluation, but not to the whole sandbox --- that limit is 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 exceeded, the sandbox is terminated, but when the per-evaluation limit
is exceeded the @exnraise[exn:fail:resource]. For example, say that is exceeded the @exnraise[exn:fail:resource]. For example, say that
you evaluate an expression like you evaluate an expression like
@schemeblock[ @racketblock[
(for ([i (in-range 1000)]) (for ([i (in-range 1000)])
(set! a (cons (make-bytes 1000000) a)) (set! a (cons (make-bytes 1000000) a))
(collect-garbage)) (collect-garbage))
@ -638,7 +638,7 @@ then, assuming sufficiently small limits,
@item{if there is a per-evaluation limit, but no global limit, the @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 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 blocks, and you can evaluate the same expression again which
will add more blocks to it;} 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 per-evaluation limit, then the evaluation will abort and you
will be able to repeat it, but doing so several times will will be able to repeat it, but doing so several times will
eventually terminate the sandbox (this will be indicated by 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).} 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 used for each interaction. Each of these handlers should expect a
thunk as an argument, and they should execute these thunks --- thunk as an argument, and they should execute these thunks ---
possibly imposing further restrictions. The default values are 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 additional restrictions on initial sandbox code (e.g., it can start
background threads), and a custodian-shutdown around each interaction background threads), and a custodian-shutdown around each interaction
that follows. Another useful function for this is 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.} other resources intact.}
@ -675,7 +675,7 @@ other resources intact.}
A parameter that determines the procedure used to create the inspector A parameter that determines the procedure used to create the inspector
for sandboxed evaluation. The procedure is called when initializing for sandboxed evaluation. The procedure is called when initializing
an evaluator, and the default parameter value is an evaluator, and the default parameter value is
@scheme[make-inspector].} @racket[make-inspector].}
@defparam[sandbox-make-code-inspector 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 A parameter that determines the procedure used to create the code
inspector for sandboxed evaluation. The procedure is called when inspector for sandboxed evaluation. The procedure is called when
initializing an evaluator, and the default parameter value is 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 handler is setup to still allow loading of bytecode files under the
original code inspector when @scheme[sandbox-path-permissions] allows original code inspector when @racket[sandbox-path-permissions] allows
it through a @scheme['read-bytecode] mode symbol, to make it possible it through a @racket['read-bytecode] mode symbol, to make it possible
to load libraries.} to load libraries.}
@ -695,7 +695,7 @@ to load libraries.}
A parameter that determines the procedure used to create the logger A parameter that determines the procedure used to create the logger
for sandboxed evaluation. The procedure is called when initializing for sandboxed evaluation. The procedure is called when initializing
an evaluator, and the default parameter value is 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).} 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?]{ @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 down the evaluator's custodian. Attempting to use an evaluator after
killing raises an exception, and attempts to kill a dead evaluator are killing raises an exception, and attempts to kill a dead evaluator are
ignored. ignored.
Killing an evaluator is similar to sending an @scheme[eof] value to Killing an evaluator is similar to sending an @racket[eof] value to
the evaluator, except that an @scheme[eof] value will raise an error the evaluator, except that an @racket[eof] value will raise an error
immediately.} immediately.}
@ -735,28 +735,28 @@ propagates the break to the evaluator's context.}
[mb (or/c exact-nonnegative-integer? #f)]) [mb (or/c exact-nonnegative-integer? #f)])
void?]{ void?]{
Changes the per-expression limits that @scheme[evaluator] uses to Changes the per-expression limits that @racket[evaluator] uses to
@scheme[sec] seconds and @scheme[mb] megabytes (either one can be @racket[sec] seconds and @racket[mb] megabytes (either one can be
@scheme[#f], indicating no limit). @racket[#f], indicating no limit).
This procedure should be used to modify an existing evaluator limits, This procedure should be used to modify an existing evaluator limits,
because changing the @scheme[sandbox-eval-limits] parameter does not because changing the @racket[sandbox-eval-limits] parameter does not
affect existing evaluators. See also @scheme[call-with-limits].} affect existing evaluators. See also @racket[call-with-limits].}
@defproc[(set-eval-handler [evaluator (any/c . -> . any)] @defproc[(set-eval-handler [evaluator (any/c . -> . any)]
[handler (or/c #f ((-> any) . -> . any))]) [handler (or/c #f ((-> any) . -> . any))])
void?]{ void?]{
Changes the per-expression handler that the @scheme[evaluator] uses Changes the per-expression handler that the @racket[evaluator] uses
around each interaction. A @scheme[#f] value means no handler is around each interaction. A @racket[#f] value means no handler is
used. used.
This procedure should be used to modify an existing evaluator handler, 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 affect existing evaluators. See also
@scheme[call-with-custodian-shutdown] and @racket[call-with-custodian-shutdown] and
@scheme[call-with-killing-threads] for two useful handlers that are @racket[call-with-killing-threads] for two useful handlers that are
provided.} provided.}
@ -764,10 +764,10 @@ provided.}
[(call-with-killing-threads [thunk (-> any)]) any])]{ [(call-with-killing-threads [thunk (-> any)]) any])]{
These functions are useful for use as an evaluation handler. 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 in a fresh custodian, then shutdown that custodian, making sure that
@scheme[thunk] could not have left behind any resources. @racket[thunk] could not have left behind any resources.
@scheme[call-with-killing-threads] is similar, except that it kills @racket[call-with-killing-threads] is similar, except that it kills
threads that were left, but leaves other resources as is.} 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)] [(put-input [evaluator (any/c . -> . any)]
[i/o (or/c bytes? string? eof-object?)]) void?])]{ [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 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 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.} which closes the pipe.}
@defproc*[([(get-output [evaluator (any/c . -> . any)]) (or/c #f input-port? bytes? string?)] @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?)])]{ [(get-error-output [evaluator (any/c . -> . any)]) (or/c #f input-port? bytes? string?)])]{
Returns the output or error-output of the @scheme[evaluator], Returns the output or error-output of the @racket[evaluator],
in a way that depends on the setting of @scheme[(sandbox-output)] or in a way that depends on the setting of @racket[(sandbox-output)] or
@scheme[(sandbox-error-output)] when the evaluator was created: @racket[(sandbox-error-output)] when the evaluator was created:
@itemize[ @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;} 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 is the accumulated output, and the output port is reset so each
call returns a different piece of the evaluator's output (note call returns a different piece of the evaluator's output (note
that any allocations of such output are still subject to the that any allocations of such output are still subject to the
sandbox memory limit);} 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?)]{ (listof syntax?)]{
Retrieves uncovered expression from an evaluator, as longs as the 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 evaluator was created. Otherwise, an exception is raised to indicate
that no coverage information is available. 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 were uncovered after only the original input program was evaluated
(@scheme[#t]) or after all later uses of the evaluator (@scheme[#f]). (@racket[#t]) or after all later uses of the evaluator (@racket[#f]).
Using @scheme[#t] retrieves a list that is saved after the input 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 program is evaluated, and before the evaluator is used, so the result is
always the same. 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 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. 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 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 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 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 The resulting list of @tech{syntax objects} has at most one expression
for each position and span. Thus, the contents may be unreliable, but for each position and span. Thus, the contents may be unreliable, but
the position information is reliable (i.e., it always indicates source 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). is used).
Note that if the input program is a sequence of syntax values, either 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 make sure that they have @racket['program] as the source field, or use
the @scheme[src] argument. Using a sequence of S-expressions (not the @racket[src] argument. Using a sequence of S-expressions (not
@tech{syntax objects}) for an input program leads to unreliable @tech{syntax objects}) for an input program leads to unreliable
coverage results, since each expression may be assigned a single coverage results, since each expression may be assigned a single
source location.} source location.}
@ -852,18 +852,18 @@ source location.}
[unrestricted? boolean? #f]) [unrestricted? boolean? #f])
any]{ 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 evaluator. The call is performed under the resource limits and
evaluation handler that are used for evaluating expressions, unless 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 This process is usually similar to @racket[(evaluator (list thunk))], except
that this relies on the common meaning of list expressions as function that it relies on the common meaning of list expressions as function
application (which is not true in all languages), and it relies on 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 addition, you can avoid some of the sandboxed restrictions by using
your own permissions, for example, your own permissions, for example,
@schemeblock[ @racketblock[
(let ([guard (current-security-guard)]) (let ([guard (current-security-guard)])
(call-in-sandbox-context (call-in-sandbox-context
(lambda () (lambda ()
@ -878,10 +878,10 @@ your own permissions, for example,
@defthing[gui? boolean?]{ @defthing[gui? boolean?]{
True if the @schememodname[racket/gui] module can be used, @scheme[#f] True if the @racketmodname[racket/gui] module can be used, @racket[#f]
otherwise; see @scheme[gui-available?]. 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 when the GUI library is available, such as using a new eventspace for
each evaluator.} each evaluator.}
@ -891,25 +891,25 @@ each evaluator.}
[thunk (-> any)]) [thunk (-> any)])
any]{ any]{
Executes the given @scheme[thunk] with memory and time restrictions: Executes the given @racket[thunk] with memory and time restrictions:
if execution consumes more than @scheme[mb] megabytes or more than if execution consumes more than @racket[mb] megabytes or more than
@scheme[sec] seconds, then the computation is aborted and the @racket[sec] seconds, then the computation is aborted and the
@exnraise[exn:fail:resource]. Otherwise the result of the thunk is @exnraise[exn:fail:resource]. Otherwise the result of the thunk is
returned as usual (a value, multiple values, or an exception). Each 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 of the two limits can be @racket[#f] to indicate the absence of a
limit. See also @scheme[custodian-limit-memory] for information on limit. See also @racket[custodian-limit-memory] for information on
memory limits. memory limits.
Sandboxed evaluators use @scheme[call-with-limits], according to the Sandboxed evaluators use @racket[call-with-limits], according to the
@scheme[sandbox-eval-limits] setting and uses of @racket[sandbox-eval-limits] setting and uses of
@scheme[set-eval-limits]: each expression evaluation is protected from @racket[set-eval-limits]: each expression evaluation is protected from
timeouts and memory problems. Use @scheme[call-with-limits] directly timeouts and memory problems. Use @racket[call-with-limits] directly
only to limit a whole testing session, instead of each expression.} only to limit a whole testing session, instead of each expression.}
@defform[(with-limits sec-expr mb-expr body ...)]{ @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?] @defproc*[([(exn:fail:resource? [v any/c]) boolean?]
@ -917,8 +917,8 @@ A macro version of @scheme[call-with-limits].}
(or/c 'time 'memory)])]{ (or/c 'time 'memory)])]{
A predicate and accessor for exceptions that are raised by A predicate and accessor for exceptions that are raised by
@scheme[call-with-limits]. The @scheme[resource] field holds a symbol, @racket[call-with-limits]. The @racket[resource] field holds a symbol,
either @scheme['time] or @scheme['memory].} either @racket['time] or @racket['memory].}
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------

216
collects/scribblings/reference/startup.scrbl
View File

@ -9,29 +9,29 @@
@(define (PFlagFirst n) (as-index (PFlag n))) @(define (PFlagFirst n) (as-index (PFlag n)))
@(define (nontermstr s) @(define (nontermstr s)
@elem{@schemevalfont{"}@nonterm[s]@schemevalfont{"}}) @elem{@racketvalfont{"}@nonterm[s]@racketvalfont{"}})
@(define eventspace @(define eventspace
@tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{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[ @itemize[
@item{MzScheme, which provides the primitives libraries on which @item{Racket, which provides the primitives libraries on which
@schememodname[racket/base] is implemented. Under Unix and Mac @racketmodname[racket/base] is implemented. Under Unix and Mac
OS X, the executable is called OS X, the executable is called
@as-index{@exec{mzscheme}}. Under Windows, the executable is @as-index{@exec{racket}}. Under Windows, the executable is
called @as-index{@exec{MzScheme.exe}}.} called @as-index{@exec{Racket.exe}}.}
@item{MrEd, which extends @exec{mzscheme} with GUI primitives on @item{GRacket, which extends @exec{racket} with GUI primitives on
which @schememodname[racket/gui/base] is implemented. Under which @racketmodname[racket/gui/base] is implemented. Under
Unix, the executable is called @as-index{@exec{mred}}. Under Unix, the executable is called @as-index{@exec{gracket}}. Under
Windows, the executable is called Windows, the executable is called
@as-index{@exec{MrEd.exe}}. Under Mac OS X, the @exec{mred} @as-index{@exec{GRacket.exe}}. Under Mac OS X, the @exec{gracket}
script launches @as-index{@exec{MrEd.app}}.} 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} @section[#:tag "init-actions"]{Initialization}
On startup, the top-level environment contains no bindings---not even On startup, the top-level environment contains no bindings---not even
@scheme[#%app] for function application. Primitive modules with names @racket[#%app] for function application. Primitive modules with names
that start with @schemeidfont{#%} are defined, but they are not meant that start with @racketidfont{#%} are defined, but they are not meant
for direct use, and the set of such modules can change. For example, for direct use, and the set of such modules can change. For example,
the @indexed-scheme['#%kernel] module is eventually used to bootstrap the @indexed-racket['#%kernel] module is eventually used to bootstrap
the implemetation of @schememodname[racket/base], and the implemetation of @racketmodname[racket/base], and
@scheme['#%mred-kernel] is used for @schememodname[racket/gui/base]. @racket['#%mred-kernel] is used for @racketmodname[racket/gui/base].
The first action of MzScheme or MrEd is to initialize The first action of Racket or GRacket is to initialize
@scheme[current-library-collection-paths] to the result of @racket[current-library-collection-paths] to the result of
@scheme[(find-library-collection-paths _pre-extras _extras)], where @racket[(find-library-collection-paths _pre-extras _extras)], where
@scheme[_pre-extras] is normally @scheme[null] and @scheme[_extras] @racket[_pre-extras] is normally @racket[null] and @racket[_extras]
are extra directory paths provided in order in the command line with are extra directory paths provided in order in the command line with
@Flag{S}/@DFlag{search}. An executable created from the MzScheme or @Flag{S}/@DFlag{search}. An executable created from the Racket or
MrEd executable can embed paths used as @scheme[_pre-extras]. GRacket executable can embed paths used as @racket[_pre-extras].
MzScheme and MrEd next @scheme[require] @schememodname[racket/init] Racket and GRacket next @racket[require] @racketmodname[racket/init]
and @schememodname[racket/gui/init], respectively, but only if the and @racketmodname[racket/gui/init], respectively, but only if the
command line does not specify a @scheme[require] flag command line does not specify a @racket[require] flag
(@Flag{t}/@DFlag{require}, @Flag{l}/@DFlag{lib}, or (@Flag{t}/@DFlag{require}, @Flag{l}/@DFlag{lib}, or
@Flag{u}/@DFlag{require-script}) before any @scheme[eval], @Flag{u}/@DFlag{require-script}) before any @racket[eval],
@scheme[load], or read-eval-print-loop flag (@Flag{e}/@DFlag{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}, @Flag{f}/@DFlag{load}, @Flag{r}/@DFlag{script}, @Flag{m}/@DFlag{main},
or @Flag{i}/@DFlag{repl}). The initialization library can be changed or @Flag{i}/@DFlag{repl}). The initialization library can be changed
with the @Flag{I} @tech{configuration option}. The 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 language is used before the library is instantiated; see
@secref["configure-runtime"]. @secref["configure-runtime"].
After potentially loading the initialization module, expression 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 executed in the order that they are provided on the command line. If
any raises an uncaught exception, then the remaining @scheme[eval]s, any raises an uncaught exception, then the remaining @racket[eval]s,
@scheme[load]s, and @scheme[require]s are skipped. If the first @racket[load]s, and @racket[require]s are skipped. If the first
@scheme[require] precedes any @scheme[eval] or @scheme[load] so that @racket[require] precedes any @racket[eval] or @racket[load] so that
the initialization library is skipped, then the 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 language is used before the module is instantiated; see
@secref["configure-runtime"]. @secref["configure-runtime"].
After running all command-line expressions, files, and modules, 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 evaluation if no command line flags are provided other than
@tech{configuration options}. If any command-line argument is @tech{configuration options}. If any command-line argument is
provided that is not a @tech{configuration option}, then the provided that is not a @tech{configuration option}, then the
read-eval-print-loop is not started, unless the @Flag{i}/@DFlag{repl} read-eval-print-loop is not started, unless the @Flag{i}/@DFlag{repl}
flag is provided on the command line to flag is provided on the command line to
specifically re-enable it. In addition, just before the command line specifically re-enable it. In addition, just before the command line
is started, MzScheme loads the file @scheme[(find-system-path is started, Racket loads the file @racket[(find-system-path
'init-file)] and MrEd loads the file 'init-file)] and GRacket loads the file
@scheme[(find-graphical-system-path 'init-file)] is loaded, unless the @racket[(find-graphical-system-path 'init-file)] is loaded, unless the
@Flag{q}/@DFlag{no-init-file} flag is specified on the command line. @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 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. @Flag{V}/@DFlag{no-yield} command-line flag.
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@section[#:tag "exit-status"]{Exit Status} @section[#:tag "exit-status"]{Exit Status}
The default exit status for a MzScheme or MrEd process is non-zero if The default exit status for a Racket or GRacket process is non-zero if
an error occurs during a command-line @scheme[eval] (via @Flag{e}, an error occurs during a command-line @racket[eval] (via @Flag{e},
etc.), @scheme[load] (via @Flag{f}, @Flag{r}, etc.), or etc.), @racket[load] (via @Flag{f}, @Flag{r}, etc.), or
@scheme[require] (via @Flag{-l}, @Flag{t}, etc.), but only when no @racket[require] (via @Flag{-l}, @Flag{t}, etc.), but only when no
read-eval-print loop is started. Otherwise, the default exit status is 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 handler} is in place) can end the process with a specific status
value. value.
@ -120,7 +120,7 @@ value.
@section[#:tag "mz-cmdline"]{Command Line} @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: flags:
@itemize[ @itemize[
@ -130,35 +130,35 @@ flags:
@itemize[ @itemize[
@item{@FlagFirst{e} @nonterm{expr} or @DFlagFirst{eval} @item{@FlagFirst{e} @nonterm{expr} or @DFlagFirst{eval}
@nonterm{expr} : @scheme[eval]s @nonterm{expr}. The results of @nonterm{expr} : @racket[eval]s @nonterm{expr}. The results of
the evaluation are printed via @scheme[current-print].} the evaluation are printed via @racket[current-print].}
@item{@FlagFirst{f} @nonterm{file} or @DFlagFirst{load} @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} @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} @item{@FlagFirst{l} @nonterm{path} or @DFlagFirst{lib}
@nonterm{path} : @scheme[require]s @scheme[(lib @nonterm{path} : @racket[require]s @racket[(lib
@#,nontermstr{path})].} @#,nontermstr{path})].}
@item{@FlagFirst{p} @nonterm{package} : @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 @margin-note{Despite its name, @DFlag{script} is not usually
used for Unix scripts. See @guidesecref["scripts"] for more used for Unix scripts. See @guidesecref["scripts"] for more
information on scripts.}} information on scripts.}}
@item{@FlagFirst{r} @nonterm{file} or @DFlagFirst{script} @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 script. This flag is like @Flag{t} @nonterm{file} plus
@Flag{N} @nonterm{file} to set the program name and @Flag{-} @Flag{N} @nonterm{file} to set the program name and @Flag{-}
to cause all further command-line elements to be treated as to cause all further command-line elements to be treated as
non-flag arguments.} non-flag arguments.}
@item{@FlagFirst{u} @nonterm{file} or @DFlagFirst{require-script} @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} This flag is like @Flag{t} @nonterm{file} plus @Flag{N}
@nonterm{file} to set the program name and @Flag{-} to cause @nonterm{file} to set the program name and @Flag{-} to cause
all further command-line elements to be treated as non-flag 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 @item{@FlagFirst{k} @nonterm{n} @nonterm{m} : Loads code embedded in
the executable from file position @nonterm{n} to the executable from file position @nonterm{n} to
@nonterm{m}. This option is normally embedded in a stand-alone @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 @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 of the command-line arguments that are not processed as
options (i.e., the arguments put into options (i.e., the arguments put into
@scheme[current-command-line-arguments]) are passed as @racket[current-command-line-arguments]) are passed as
arguments to @schemeidfont{main}. The results of the call are arguments to @racketidfont{main}. The results of the call are
printed via @scheme[current-print]. printed via @racket[current-print].
The call to @schemeidfont{main} is constructed as an The call to @racketidfont{main} is constructed as an
expression @scheme[((unsyntax @schemeidfont{main}) _arg-str expression @racket[((unsyntax @racketidfont{main}) _arg-str
...)] where the lexical context of the expression gives ...)] where the lexical context of the expression gives
@schemeidfont{#%app} and @schemeidfont{#%datum} bindings as @racketidfont{#%app} and @racketidfont{#%datum} bindings as
@scheme[#%plain-app] and @scheme[#%datum], but the lexical @racket[#%plain-app] and @racket[#%datum], but the lexical
context of @schemeidfont{main} is the top-level environment.} context of @racketidfont{main} is the top-level environment.}
]} ]}
@ -191,26 +191,26 @@ flags:
@itemize[ @itemize[
@item{@FlagFirst{i} or @DFlagFirst{repl} : Runs interactive read-eval-print @item{@FlagFirst{i} or @DFlagFirst{repl} : Runs interactive read-eval-print
loop, using either @scheme[read-eval-print-loop] (MzScheme) or loop, using either @racket[read-eval-print-loop] (Racket) or
@scheme[graphical-read-eval-print-loop] (MrEd) after showing @racket[graphical-read-eval-print-loop] (GRacket) after showing
@scheme[(banner)] and loading @scheme[(find-system-path @racket[(banner)] and loading @racket[(find-system-path
'init-file)]. For MrEd, supply the @Flag{z}/@DFlag{text-repl} 'init-file)]. For GRacket, supply the @Flag{z}/@DFlag{text-repl}
configuration option to use @scheme[read-eval-print-loop] configuration option to use @racket[read-eval-print-loop]
instead of @scheme[graphical-read-eval-print-loop].} instead of @racket[graphical-read-eval-print-loop].}
@item{@FlagFirst{n} or @DFlagFirst{no-lib} : Skips requiring the @item{@FlagFirst{n} or @DFlagFirst{no-lib} : Skips requiring the
initialization library (i.e., @schememodname[racket/init] or initialization library (i.e., @racketmodname[racket/init] or
@schememodname[racket/gui/init], unless it is changed with the @racketmodname[racket/gui/init], unless it is changed with the
@Flag{I} flag) when not otherwise disabled.} @Flag{I} flag) when not otherwise disabled.}
@item{@FlagFirst{v} or @DFlagFirst{version} : Shows @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.} leave application in the background.}
@item{@FlagFirst{V} @DFlagFirst{no-yield} : Skips final @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 frames are closed, @|etc| in the main @|eventspace| before
exiting.} exiting.}
@ -222,24 +222,24 @@ flags:
@item{@FlagFirst{c} or @DFlagFirst{no-compiled} : Disables loading @item{@FlagFirst{c} or @DFlagFirst{no-compiled} : Disables loading
of compiled byte-code @filepath{.zo} files, by initializing 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 @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}.} @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 @Flag{i}/@DFlag{repl} to use
@scheme[textual-read-eval-print-loop] instead of @racket[textual-read-eval-print-loop] instead of
@scheme[graphical-read-eval-print-loop].} @racket[graphical-read-eval-print-loop].}
@item{@FlagFirst{I} @nonterm{path} : Sets @scheme[(lib @item{@FlagFirst{I} @nonterm{path} : Sets @racket[(lib
@#,nontermstr{path})] as the path to @scheme[require] to initialize @#,nontermstr{path})] as the path to @racket[require] to initialize
the namespace, unless namespace initialization is disabled.} the namespace, unless namespace initialization is disabled.}
@item{@FlagFirst{X} @nonterm{dir} or @DFlagFirst{collects} @item{@FlagFirst{X} @nonterm{dir} or @DFlagFirst{collects}
@nonterm{dir} : Sets @nonterm{dir} as the path to the main @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}.} 'collects-dir)] produce @nonterm{dir}.}
@item{@FlagFirst{S} @nonterm{dir} or @DFlagFirst{search} @item{@FlagFirst{S} @nonterm{dir} or @DFlagFirst{search}
@ -251,21 +251,21 @@ flags:
@item{@FlagFirst{U} or @DFlagFirst{no-user-path} : Omits @item{@FlagFirst{U} or @DFlagFirst{no-user-path} : Omits
user-specific paths in the search for collections, C user-specific paths in the search for collections, C
libraries, etc. by initializing the libraries, etc. by initializing the
@scheme[use-user-specific-search-paths] parameter to @racket[use-user-specific-search-paths] parameter to
@scheme[#f].} @racket[#f].}
@item{@FlagFirst{N} @nonterm{file} or @DFlagFirst{name} @item{@FlagFirst{N} @nonterm{file} or @DFlagFirst{name}
@nonterm{file} : sets the name of the executable as reported @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}.} @nonterm{file}.}
@item{@FlagFirst{j} or @DFlagFirst{no-jit} : Disables the @item{@FlagFirst{j} or @DFlagFirst{no-jit} : Disables the
native-code just-in-time compiler by setting 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 @item{@FlagFirst{d} or @DFlagFirst{no-delay} : Disables on-demand
parsing of compiled code and syntax objects by setting the 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, @item{@FlagFirst{b} or @DFlagFirst{binary} : Requests binary mode,
instead of text mode, for the process's input, out, and error 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 @tech{configuration options}, then the @Flag{i}/@DFlag{repl} flag is
effectively added. 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 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 options (i.e., they do not disable the read-eval-print loop or prevent
the insertion of @Flag{u}/@DFlag{require-script}): 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 @Flag{synchronous} and @Flag{xrm} flags behave in the usual
way.} 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 running on the same X11 display, if it was started on a
machine with the same hostname, and if it was started with the 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} 'run-file)]---possibly set with the @Flag{N}/@DFlag{name}
command-line argument---then all non-option command-line command-line argument---then all non-option command-line
arguments are treated as filenames and sent to the existing arguments are treated as filenames and sent to the existing
MrEd instance via the application file handler (see GRacket instance via the application file handler (see
@scheme[application-file-handler]).} @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. of the collapsed set.
Extra arguments following the last option are available from the 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[ @itemlist[
@item{attaching a @scheme['module-language] @tech{syntax property} to @item{attaching a @racket['module-language] @tech{syntax property} to
the module as read from its source (see @scheme[module] and the module as read from its source (see @racket[module] and
@scheme[module-compiled-language-info]);} @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 @tech{syntax property} recognize the
@scheme['configure-runtime] key, for which it returns a list of @racket['configure-runtime] key, for which it returns a list of
vectors; each vector must have the form @scheme[(vector _mp vectors; each vector must have the form @racket[(vector _mp
_name _val)] where @scheme[_mp] is a @tech{module path}, _name _val)] where @racket[_mp] is a @tech{module path},
@scheme[_name] is a symbol, and @scheme[_val] is an arbitrary @racket[_name] is a symbol, and @racket[_val] is an arbitrary
value; and} 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 _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. 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 of directly configuring the environment, so that the indicated modules
to be bundled with a program when creating a stand-alone to be bundled with a program when creating a stand-alone
executable; see @secref[#:doc '(lib "scribblings/mzc/mzc.scrbl") "exe"]. executable; see @secref[#:doc '(lib "scribblings/mzc/mzc.scrbl") "exe"].
For information on defining a new @hash-lang[] language, see For information on defining a new @hash-lang[] language, see
@schememodname[syntax/module-reader]. @racketmodname[syntax/module-reader].

98
collects/scribblings/reference/string-output.scrbl
View File

@ -6,19 +6,19 @@
@defproc[(write-char [char character?][out output-port? (current-output-port)]) @defproc[(write-char [char character?][out output-port? (current-output-port)])
void?]{ void?]{
Writes a single character to @scheme[out]; more precisely, the bytes Writes a single character to @racket[out]; more precisely, the bytes
that are the UTF-8 encoding of @scheme[char] are written to that are the UTF-8 encoding of @racket[char] are written to
@scheme[out].} @racket[out].}
@defproc[(write-byte [byte any/c][out output-port? (current-output-port)]) @defproc[(write-byte [byte any/c][out output-port? (current-output-port)])
void?]{ void?]{
Writes a single byte to @scheme[out].} Writes a single byte to @racket[out].}
@defproc[(newline [out output-port? (current-output-port)]) @defproc[(newline [out output-port? (current-output-port)])
void?]{ void?]{
The same as @scheme[(write-char #\newline out)].} The same as @racket[(write-char #\newline out)].}
@defproc[(write-string [str string?] @defproc[(write-string [str string?]
[out output-port? (current-output-port)] [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)]) [end-pos exact-nonnegative-integer? (string-length str)])
exact-nonnegative-integer?]{ exact-nonnegative-integer?]{
Writes characters to @scheme[out] from @scheme[str] starting from Writes characters to @racket[out] from @racket[str] starting from
index @scheme[start-pos] (inclusive) up to @scheme[end-pos] index @racket[start-pos] (inclusive) up to @racket[end-pos]
(exclusive). Like @scheme[substring], the @exnraise[exn:fail:contract] (exclusive). Like @racket[substring], the @exnraise[exn:fail:contract]
if @scheme[start-pos] or @scheme[end-pos] is out-of-range for if @racket[start-pos] or @racket[end-pos] is out-of-range for
@scheme[str]. @racket[str].
The result is the number of characters written to @scheme[out], which The result is the number of characters written to @racket[out], which
is always @scheme[(- end-pos start-pos)].} is always @racket[(- end-pos start-pos)].}
@defproc[(write-bytes [bstr bytes?] @defproc[(write-bytes [bstr bytes?]
[out output-port? (current-output-port)] [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)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
exact-nonnegative-integer?]{ 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?] @defproc[(write-bytes-avail [bstr bytes?]
[out output-port? (current-output-port)] [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)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
exact-nonnegative-integer?]{ 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 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 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 and flushed to @racket[out]; if @racket[start-pos] is the same as
@scheme[end-pos], then the result can be @scheme[0] (indicating a @racket[end-pos], then the result can be @racket[0] (indicating a
successful flush of any buffered data), otherwise the result is at 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)]. start-pos)].
The @scheme[write-bytes-avail] procedure never drops bytes; if The @racket[write-bytes-avail] procedure never drops bytes; if
@scheme[write-bytes-avail] successfully writes some bytes and then @racket[write-bytes-avail] successfully writes some bytes and then
encounters an error, it suppresses the error and returns the number of encounters an error, it suppresses the error and returns the number of
written bytes. (The error will be triggered by future writes.) If an written bytes. (The error will be triggered by future writes.) If an
error is encountered before any bytes have been written, an exception 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)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
(or/c exact-nonnegative-integer? #f)]{ (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, 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.} flushed but no additional bytes can be written immediately.}
@defproc[(write-bytes-avail/enable-break [bstr bytes?] @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)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
exact-nonnegative-integer?]{ 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 the write. The procedure provides a guarantee about the interaction of
writing and breaks: if breaking is disabled when writing and breaks: if breaking is disabled when
@scheme[write-bytes-avail/enable-break] is called, and if the @racket[write-bytes-avail/enable-break] is called, and if the
@scheme[exn:break] exception is raised as a result of the call, then @racket[exn:break] exception is raised as a result of the call, then
no bytes will have been written to @scheme[out]. See also no bytes will have been written to @racket[out]. See also
@secref["breakhandler"].} @secref["breakhandler"].}
@defproc[(write-special [v any/c][out output-port? (current-output-port)]) boolean?]{ @defproc[(write-special [v any/c][out output-port? (current-output-port)]) boolean?]{
Writes @scheme[v] directly to @scheme[out] if the port supports Writes @racket[v] directly to @racket[out] if the port supports
special writes, or raises @scheme[exn:fail:contract] if the port does special writes, or raises @racket[exn:fail:contract] if the port does
not support special write. The result is always @scheme[#t], not support special write. The result is always @racket[#t],
indicating that the write succeeded.} indicating that the write succeeded.}
@defproc[(write-special-avail* [v any/c][out output-port? (current-output-port)]) boolean?]{ @defproc[(write-special-avail* [v any/c][out output-port? (current-output-port)]) boolean?]{
Like @scheme[write-special], but without blocking. If @scheme[v] Like @racket[write-special], but without blocking. If @racket[v]
cannot be written immediately, the result is @scheme[#f] without cannot be written immediately, the result is @racket[#f] without
writing @scheme[v], otherwise the result is @scheme[#t] and @scheme[v] writing @racket[v], otherwise the result is @racket[#t] and @racket[v]
is written.} is written.}
@defproc[(write-bytes-avail-evt [bstr bytes?] @defproc[(write-bytes-avail-evt [bstr bytes?]
@ -110,45 +110,45 @@ is written.}
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
evt?]{ 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 immediately, it returns a synchronizable event (see
@secref["sync"]). The @scheme[out] must support atomic writes, as @secref["sync"]). The @racket[out] must support atomic writes, as
indicated by @scheme[port-writes-atomic?]. 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 event becomes ready when bytes are written (unbuffered) to the
port. If @scheme[start-pos] and @scheme[end-pos] are the same, then port. If @racket[start-pos] and @racket[end-pos] are the same, then
the synchronization result is @scheme[0] when the port's internal the synchronization result is @racket[0] when the port's internal
buffer (if any) is flushed, otherwise the result is a positive exact buffer (if any) is flushed, otherwise the result is a positive exact
integer. If the event is not selected in a synchronization, then no 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?]{ @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 value immediately, it returns a synchronizable event (see
@secref["sync"]). The @scheme[out] must support atomic writes, as @secref["sync"]). The @racket[out] must support atomic writes, as
indicated by @scheme[port-writes-atomic?]. indicated by @racket[port-writes-atomic?].
Synchronizing on the object starts a write of the special value, and Synchronizing on the object starts a write of the special value, and
the event becomes ready when the value is written (unbuffered) to the 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 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?]{ @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 provide an exclusive-or guarantee (break or write, but not both) for
@scheme[out], and if the port can be used with procedures like @racket[out], and if the port can be used with procedures like
@scheme[write-bytes-avail-evt]. Scheme's file-stream ports, pipes, @racket[write-bytes-avail-evt]. Racket's file-stream ports, pipes,
string ports, and TCP ports all support atomic writes; ports created 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.} support atomic writes.}
@defproc[(port-writes-special? [out output-port?]) boolean?]{ @defproc[(port-writes-special? [out output-port?]) boolean?]{
Returns @scheme[#t] if procedures like @scheme[write-special] can Returns @racket[#t] if procedures like @racket[write-special] can
write arbitrary values to the port. Scheme's file-stream ports, write arbitrary values to the port. Racket's file-stream ports,
pipes, string ports, and TCP ports all reject special values, but 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.} @secref["customport"]) may support them.}

118
collects/scribblings/reference/stx-props.scrbl
View File

@ -5,95 +5,95 @@
Every syntax object has an associated @deftech{syntax property} list, Every syntax object has an associated @deftech{syntax property} list,
which can be queried or extended with which can be queried or extended with
@scheme[syntax-property]. Properties are not preserved for a @racket[syntax-property]. Properties are not preserved for a
@scheme[syntax-quoted] syntax object in a compiled form that is @racket[syntax-quoted] syntax object in a compiled form that is
marshaled to a byte string. 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 property to any pair or vector syntax object generated from parsing a
pair @litchar{[} and @litchar{]} or @litchar["{"] and pair @litchar{[} and @litchar{]} or @litchar["{"] and
@litchar["}"]; the property value is @scheme[#\[] in the former case, @litchar["}"]; the property value is @racket[#\[] in the former case,
and @scheme[#\{] in the latter case. The @scheme[syntax] form copies and @racket[#\{] in the latter case. The @racket[syntax] form copies
any @scheme['paren-shape] property from the source of a template to any @racket['paren-shape] property from the source of a template to
corresponding generated syntax. corresponding generated syntax.
Both the syntax input to a transformer and the syntax result of a Both the syntax input to a transformer and the syntax result of a
transformer may have associated properties. The two sets of properties transformer may have associated properties. The two sets of properties
are merged by the syntax expander: each property in the original and 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 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). value first, original value second).
Before performing the merge, however, the syntax expander Before performing the merge, however, the syntax expander
automatically adds a property to the original syntax object using the automatically adds a property to the original syntax object using the
key @indexed-scheme['origin]. If the source syntax has no key @indexed-racket['origin]. If the source syntax has no
@scheme['origin] property, it is set to the empty list. Then, still @racket['origin] property, it is set to the empty list. Then, still
before the merge, the identifier that triggered the macro expansion before the merge, the identifier that triggered the macro expansion
(as syntax) is @scheme[cons]ed onto the @scheme['origin] (as syntax) is @racket[cons]ed onto the @racket['origin]
property so far. The @scheme['origin] property thus records (in property so far. The @racket['origin] property thus records (in
reverse order) the sequence of macro expansions that produced an 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 immutable list of identifiers. However, a transformer might return
syntax that has already been expanded, in which case an syntax that has already been expanded, in which case an
@scheme['origin] list can contain other lists after a merge. The @racket['origin] list can contain other lists after a merge. The
@scheme[syntax-track-origin] procedure implements this tracking. @racket[syntax-track-origin] procedure implements this tracking.
Besides @scheme['origin] tracking for general macro expansion, Besides @racket['origin] tracking for general macro expansion,
MzScheme adds properties to expanded syntax (often using Racket adds properties to expanded syntax (often using
@scheme[syntax-track-origin]) to record additional expansion details: @racket[syntax-track-origin]) to record additional expansion details:
@itemize[ @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"]), internal definitions (see @secref["intdef-body"]),
@scheme[syntax-track-origin] is applied to every spliced element from @racket[syntax-track-origin] is applied to every spliced element from
the @scheme[begin] body. The second argument to the @racket[begin] body. The second argument to
@scheme[syntax-track-origin] is the @scheme[begin] form, and the @racket[syntax-track-origin] is the @racket[begin] form, and the
third argument is the @scheme[begin] keyword (extracted from the third argument is the @racket[begin] keyword (extracted from the
spliced form).} spliced form).}
@item{When an internal @scheme[define-values] or @item{When an internal @racket[define-values] or
@scheme[define-syntaxes] form is converted into a @racket[define-syntaxes] form is converted into a
@scheme[letrec-syntaxes+values] form (see @secref["intdef-body"]), @racket[letrec-syntaxes+values] form (see @secref["intdef-body"]),
@scheme[syntax-track-origin] is applied to each generated binding @racket[syntax-track-origin] is applied to each generated binding
clause. The second argument to @scheme[syntax-track-origin] is the clause. The second argument to @racket[syntax-track-origin] is the
converted form, and the third argument is the @scheme[define-values] converted form, and the third argument is the @racket[define-values]
or @scheme[define-syntaxes] keyword form the converted form.} 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 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 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 the body contained multiple expressions). To record the disappeared
syntax bindings, a property is added to the expansion result: an syntax bindings, a property is added to the expansion result: an
immutable list of identifiers from the disappeared bindings, as a 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 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 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 @item{When a reference to an unexported or protected identifier from
a module is discovered (and the reference is certified; see a module is discovered (and the reference is certified; see
@secref["stxcerts"]), the @indexed-scheme['protected] property is @secref["stxcerts"]), the @indexed-racket['protected] property is
added to the identifier with a @scheme[#t] value.} 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 generates a syntax object, it attaches a property to the object
(using a private key) to mark the object as originating from a (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 to recognize such syntax objects. (See @secref["stxops"] for more
information.)} information.)}
] ]
See @secref["modinfo"] for information about properties generated 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 @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. information on properties and byte codes.
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -102,56 +102,56 @@ information on properties and byte codes.
syntax?] syntax?]
[(syntax-property [stx syntax?][key any/c]) any])]{ [(syntax-property [stx syntax?][key any/c]) any])]{
The three-argument form extends @scheme[stx] by associating an The three-argument form extends @racket[stx] by associating an
arbitrary property value @scheme[v] with the key @scheme[key]; the arbitrary property value @racket[v] with the key @racket[key]; the
result is a new syntax object with the association (while @scheme[stx] result is a new syntax object with the association (while @racket[stx]
itself is unchanged). itself is unchanged).
The two-argument form returns an arbitrary property value associated The two-argument form returns an arbitrary property value associated
to @scheme[stx] with the key @scheme[key], or @scheme[#f] if no value to @racket[stx] with the key @racket[key], or @racket[#f] if no value
is associated to @scheme[stx] for @scheme[key].} is associated to @racket[stx] for @racket[key].}
@defproc[(syntax-property-symbol-keys [stx syntax?]) list?]{ @defproc[(syntax-property-symbol-keys [stx syntax?]) list?]{
Returns a list of all symbols that as keys have associated properties 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.} are not included in the result list.}
@defproc[(syntax-track-origin [new-stx syntax?][orig-stx syntax?][id-stx syntax?]) @defproc[(syntax-track-origin [new-stx syntax?][orig-stx syntax?][id-stx syntax?])
any]{ 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 expansion adds properties to a transformer result. In particular, it
merges the properties of @scheme[orig-stx] into @scheme[new-stx], merges the properties of @racket[orig-stx] into @racket[new-stx],
first adding @scheme[id-stx] as an @scheme['origin] property, and it first adding @racket[id-stx] as an @racket['origin] property, and it
returns the property-extended syntax object. Use the returns the property-extended syntax object. Use the
@scheme[syntax-track-origin] procedure in a macro transformer that @racket[syntax-track-origin] procedure in a macro transformer that
discards syntax (corresponding to @scheme[orig-stx] with a keyword discards syntax (corresponding to @racket[orig-stx] with a keyword
@scheme[id-stx]) leaving some other syntax in its place (corresponding @racket[id-stx]) leaving some other syntax in its place (corresponding
to @scheme[new-stx]). to @racket[new-stx]).
For example, the expression For example, the expression
@schemeblock[ @racketblock[
(or x y) (or x y)
] ]
expands to expands to
@schemeblock[ @racketblock[
(let ((or-part x)) (if or-part or-part (or y))) (let ((or-part x)) (if or-part or-part (or y)))
] ]
which, in turn, expands to which, in turn, expands to
@schemeblock[ @racketblock[
(let-values ([(or-part) x]) (if or-part or-part y)) (let-values ([(or-part) x]) (if or-part or-part y))
] ]
The syntax object for the final expression will have an 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))].} let) (quote-syntax or))].}

214
collects/scribblings/reference/subprocess.scrbl
View File

@ -25,55 +25,55 @@
(or/c (and/c input-port? file-stream-port?) #f))])]{ (or/c (and/c input-port? file-stream-port?) #f))])]{
Creates a new process in the underlying operating system to execute Creates a new process in the underlying operating system to execute
@scheme[command] asynchronously. See also @scheme[system] and @racket[command] asynchronously. See also @racket[system] and
@scheme[process] from @schememodname[racket/system]. @racket[process] from @racketmodname[racket/system].
The @scheme[command] argument is a path to a program executable, and The @racket[command] argument is a path to a program executable, and
the @scheme[arg]s are command-line arguments for the program. Under 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 Unix and Mac OS X, command-line arguments are passed as byte strings
using the current locale's encoding (see @secref["encodings"]). using the current locale's encoding (see @secref["encodings"]).
Under Windows, the first @scheme[arg] can be replaced with Under Windows, the first @racket[arg] can be replaced with
@indexed-scheme['exact], which triggers a Windows-specific behavior: @indexed-racket['exact], which triggers a Windows-specific behavior:
the sole @scheme[arg] is used exactly as the command-line for the the sole @racket[arg] is used exactly as the command-line for the
subprocess. Otherwise, under Windows, a command-line string is 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 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]. the @exnraise[exn:fail:contract].
@margin-note{For information on the Windows command-line conventions, @margin-note{For information on the Windows command-line conventions,
search for ``command line parsing'' at search for ``command line parsing'' at
@tt{http://msdn.microsoft.com/}.} @tt{http://msdn.microsoft.com/}.}
Unless it is @scheme[#f], @scheme[stdout] is used for the launched Unless it is @racket[#f], @racket[stdout] is used for the launched
process's standard output, @scheme[stdin] is used for the process's process's standard output, @racket[stdin] is used for the process's
standard input, and @scheme[stderr] is used for the process's standard 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 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 can be @racket[#f], in which case a system pipe is created and
returned by @scheme[subprocess]. For each port that is provided, no returned by @racket[subprocess]. For each port that is provided, no
pipe is created and the corresponding returned value is @scheme[#f]. 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[ @itemize[
@item{a subprocess value representing the created process;} @item{a subprocess value representing the created process;}
@item{an input port piped from the process's standard output, or @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 @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 @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 @bold{Important:} All ports returned from @racket[subprocess] must be
explicitly closed with @scheme[close-input-port] or explicitly closed with @racket[close-input-port] or
@scheme[close-output-port]. @racket[close-output-port].
The returned ports are @tech{file-stream ports} (see The returned ports are @tech{file-stream ports} (see
@secref["file-ports"]), and they are placed into the management of @secref["file-ports"]), and they are placed into the management of
@ -85,44 +85,44 @@ communication.}
@defproc[(subprocess-wait [subproc subprocess?]) void?]{ @defproc[(subprocess-wait [subproc subprocess?]) void?]{
Blocks until the process represented by @scheme[subproc] Blocks until the process represented by @racket[subproc]
terminates. The @scheme[subproc] value also can be used with terminates. The @racket[subproc] value also can be used with
@scheme[sync] and @scheme[sync/timeout].} @racket[sync] and @racket[sync/timeout].}
@defproc[(subprocess-status [subproc subprocess?]) @defproc[(subprocess-status [subproc subprocess?])
(or/c 'running (or/c 'running
exact-nonnegative-integer?)]{ exact-nonnegative-integer?)]{
Returns @indexed-scheme['running] if the process represented by Returns @indexed-racket['running] if the process represented by
@scheme[subproc] is still running, or its exit code otherwise. The @racket[subproc] is still running, or its exit code otherwise. The
exit code is an exact integer, and @scheme[0] typically indicates exit code is an exact integer, and @racket[0] typically indicates
success. If the process terminated due to a fault or signal, the exit success. If the process terminated due to a fault or signal, the exit
code is non-zero.} code is non-zero.}
@defproc[(subprocess-kill [subproc subprocess?][force? any/c]) void?]{ @defproc[(subprocess-kill [subproc subprocess?][force? any/c]) void?]{
Terminates the subprocess represented by @scheme[subproc] if Terminates the subprocess represented by @racket[subproc] if
@scheme[force?] is true and if the process still running. If an error @racket[force?] is true and if the process still running. If an error
occurs during termination, the @exnraise[exn:fail]. 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 sent an interrupt signal instead of a kill signal (and the subprocess
might handle the signal without terminating). Under Windows, no action 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?]{ @defproc[(subprocess-pid [subproce subprocess?]) exact-nonnegative-integer?]{
Returns the operating system's numerical ID (if any) for the process 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.} running.}
@defproc[(subprocess? [v any/c]) boolean?]{ @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.} otherwise.}
@ -130,96 +130,96 @@ otherwise.}
[target string?][parameters string?][dir path-string?][show-mode symbol?]) [target string?][parameters string?][dir path-string?][show-mode symbol?])
#f] #f]
@index['("ShellExecute")]{Performs} the action specified by @scheme[verb] @index['("ShellExecute")]{Performs} the action specified by @racket[verb]
on @scheme[target] in Windows. For platforms other than Windows, the on @racket[target] in Windows. For platforms other than Windows, the
@exnraise[exn:fail:unsupported]. @exnraise[exn:fail:unsupported].
For example, For example,
@schemeblock[ @racketblock[
(shell-execute #f "http://www.plt-scheme.org" "" (shell-execute #f "http://www.racket-lang.org" ""
(current-directory) 'sw_shownormal) (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 The @racket[verb] can be @racket[#f], in which case the operating
system will use a default verb. Common verbs include @scheme["open"], system will use a default verb. Common verbs include @racket["open"],
@scheme["edit"], @scheme["find"], @scheme["explore"], and @racket["edit"], @racket["find"], @racket["explore"], and
@scheme["print"]. @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 path. The file could be executable, or it could be a file with a
recognized extension that can be handled by an installed application. 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 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). 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. 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 the action. It must be one of the following symbols; the description
of each symbol's meaning is taken from the Windows API documentation. of each symbol's meaning is taken from the Windows API documentation.
@itemize[ @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.} 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.} --- 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 --- Minimizes the window and activates the next top-level window in
the z-order.} 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 --- Activates and displays the window. If the window is minimized or
maximized, Windows restores it to its original size and position.} 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 Activates the window and displays it in its current size and
position.} position.}
@item{@indexed-scheme['sw_showdefault] or @item{@indexed-racket['sw_showdefault] or
@indexed-scheme['SW_SHOWDEFAULT] --- Uses a default.} @indexed-racket['SW_SHOWDEFAULT] --- Uses a default.}
@item{@indexed-scheme['sw_showmaximized] or @item{@indexed-racket['sw_showmaximized] or
@indexed-scheme['SW_SHOWMAXIMIZED] --- Activates the window and @indexed-racket['SW_SHOWMAXIMIZED] --- Activates the window and
displays it as a maximized window.} displays it as a maximized window.}
@item{@indexed-scheme['sw_showminimized] or @item{@indexed-racket['sw_showminimized] or
@indexed-scheme['SW_SHOWMINIMIZED] --- Activates the window and @indexed-racket['SW_SHOWMINIMIZED] --- Activates the window and
displays it as a minimized window.} displays it as a minimized window.}
@item{@indexed-scheme['sw_showminnoactive] or @item{@indexed-racket['sw_showminnoactive] or
@indexed-scheme['SW_SHOWMINNOACTIVE] --- Displays the window as a @indexed-racket['SW_SHOWMINNOACTIVE] --- Displays the window as a
minimized window. The active window remains active.} 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 Displays the window in its current state. The active window remains
active.} active.}
@item{@indexed-scheme['sw_shownoactivate] or @item{@indexed-racket['sw_shownoactivate] or
@indexed-scheme['SW_SHOWNOACTIVATE] --- Displays a window in its most @indexed-racket['SW_SHOWNOACTIVATE] --- Displays a window in its most
recent size and position. The active window remains active.} recent size and position. The active window remains active.}
@item{@indexed-scheme['sw_shownormal] or @item{@indexed-racket['sw_shownormal] or
@indexed-scheme['SW_SHOWNORMAL] --- Activates and displays a @indexed-racket['SW_SHOWNORMAL] --- Activates and displays a
window. If the window is minimized or maximized, Windows restores it window. If the window is minimized or maximized, Windows restores it
to its original size and position.} to its original size and position.}
] ]
If the action fails, the @exnraise[exn:fail]. If the action succeeds, 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 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). real process ID).
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@ -231,37 +231,37 @@ real process ID).
@defproc[(system [command string?]) boolean?]{ @defproc[(system [command string?]) boolean?]{
Executes a Unix, Mac OS X, or Windows shell command synchronously Executes a Unix, Mac OS X, or Windows shell command synchronously
(i.e., the call to @scheme[system] does not return until the (i.e., the call to @racket[system] does not return until the
subprocess has ended). The @scheme[command] argument is a string subprocess has ended). The @racket[command] argument is a string
containing no nul characters. If the command succeeds, the return 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?] @defproc*[([(system* [command path-string?][arg string?] ...) boolean?]
[(system* [command path-string?][exact 'exact][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 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 specified string arguments (which must contain no nul
characters). characters).
Under Windows, the first argument after @scheme[command] can be Under Windows, the first argument after @racket[command] can be
@scheme['exact], and the final @scheme[arg] is a complete command @racket['exact], and the final @racket[arg] is a complete command
line. See @scheme[subprocess] for details.} line. See @racket[subprocess] for details.}
@defproc[(system/exit-code [command string?]) (integer-in 0 255)]{ @defproc[(system/exit-code [command string?]) (integer-in 0 255)]{
Like @scheme[system], except that the result is the exit code returned Like @racket[system], except that the result is the exit code returned
by the subprocess. A @scheme[0] result normally indicates success.} by the subprocess. A @racket[0] result normally indicates success.}
@defproc*[([(system*/exit-code [command path-string?][arg string?] ...) (integer-in 0 255)] @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)])]{ [(system*/exit-code [command path-string?][exact 'exact][arg string?]) (integer-in 0 255)])]{
Like @scheme[system*], but returns the exit code like Like @racket[system*], but returns the exit code like
@scheme[system/exit-code].} @racket[system/exit-code].}
@defproc[(process [command string?]) @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 @item{an input port piped from the subprocess's standard
error, and} error, and}
@item{a procedure of one argument, either @scheme['status], @item{a procedure of one argument, either @racket['status],
@scheme['wait], @scheme['interrupt], or @scheme['kill]: @racket['wait], @racket['interrupt], or @racket['kill]:
@itemize[ @itemize[
@item{@scheme['status] returns the status of the subprocess as one @item{@racket['status] returns the status of the subprocess as one
of @scheme['running], @scheme['done-ok], or of @racket['running], @racket['done-ok], or
@scheme['done-error].} @racket['done-error].}
@item{@scheme['exit-code] returns the integer exit code of the @item{@racket['exit-code] returns the integer exit code of the
subprocess or @scheme[#f] if it is still running.} 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.} 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 under @|AllUnix|, and takes no action under Windows. The result is
@|void-const|.} @|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 @|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 terminating the shell process may not terminate processes that
the shell starts, particularly under Windows.} 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 @bold{Important:} All three ports returned from @racket[process] must
be explicitly closed with @scheme[close-input-port] or be explicitly closed with @racket[close-input-port] or
@scheme[close-output-port].} @racket[close-output-port].}
@defproc*[([(process* [command path-string?][arg string?] ...) list?] @defproc*[([(process* [command path-string?][arg string?] ...) list?]
[(process* [command path-string?][exact 'exact][arg string?]) list?])]{ [(process* [command path-string?][exact 'exact][arg string?]) list?])]{
Like @scheme[process], except that @scheme[command] is a filename that Like @racket[process], except that @racket[command] is a filename that
is executed directly, and the @scheme[arg]s are the arguments. Under is executed directly, and the @racket[arg]s are the arguments. Under
Windows, as for @scheme[system*], the first @scheme[arg] can be Windows, as for @racket[system*], the first @racket[arg] can be
replaced with @scheme['exact].} replaced with @racket['exact].}
@defproc[(process/ports [out (or/c #f output-port?)] @defproc[(process/ports [out (or/c #f output-port?)]
@ -333,13 +333,13 @@ replaced with @scheme['exact].}
[command string?]) [command string?])
list?]{ list?]{
Like @scheme[process], except that @scheme[out] is used for the Like @racket[process], except that @racket[out] is used for the
process's standard output, @scheme[in] is used for the process's process's standard output, @racket[in] is used for the process's
standard input, and @scheme[error-out] 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 @scheme[#f], in which case a standard error. Any of the ports can be @racket[#f], in which case a
system pipe is created and returned, as in @scheme[process]. For each system pipe is created and returned, as in @racket[process]. For each
port that is provided, no pipe is created, and the corresponding value 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?)] @defproc*[([(process*/ports [out (or/c #f output-port?)]
[in (or/c #f input-port?)] [in (or/c #f input-port?)]
@ -355,6 +355,6 @@ in the returned list is @scheme[#f].}
[arg string?]) [arg string?])
list?])]{ list?])]{
Like @scheme[process*], but with the port handling of Like @racket[process*], but with the port handling of
@scheme[process/ports].} @racket[process/ports].}

2
collects/scribblings/reference/sync.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "all-sync" #:style 'toc]{Synchronization} @title[#:tag "all-sync" #:style 'toc]{Synchronization}
Scheme's synchronization toolbox spans three layers: Racket's synchronization toolbox spans three layers:
@itemize[ @itemize[

49
collects/scribblings/reference/syntax.scrbl
View File

@ -9,7 +9,6 @@
make-provide-transformer) make-provide-transformer)
racket/provide-syntax racket/provide-syntax
racket/provide racket/provide
racket/nest
racket/package racket/package
racket/splicing racket/splicing
racket/runtime-path)) racket/runtime-path))
@ -2414,54 +2413,6 @@ provides a hook to control interactive evaluation through
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@include-section["package.scrbl"] @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[require-eval]
@close-eval[meta-in-eval] @close-eval[meta-in-eval]

8
collects/scribblings/reference/thread-groups.scrbl
View File

@ -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 by creating certain threads within certain groups, a programmer can
control the amount of CPU allocated to a set of threads. Every thread control the amount of CPU allocated to a set of threads. Every thread
belongs to a thread group, which is determined by the 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"]) created. Thread groups and custodians (see @secref["custodians"])
are independent. are independent.
The root thread group receives all of the CPU that the operating 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 thread group receives equal allocation of the CPU (a portion of the
group's access), although a thread may relinquish part of its group's access), although a thread may relinquish part of its
allocation by sleeping or synchronizing with other processes. 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)]) @defproc[(make-thread-group [group thread-group? (current-thread-group)])
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?]{ @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.} otherwise.}

198
collects/scribblings/reference/threads.scrbl
View File

@ -3,37 +3,37 @@
@title[#:tag "threads"]{Threads} @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"]. thread model. See also @secref["futures"].
When a thread is created, it is placed into the management of the When a thread is created, it is placed into the management of the
@tech{current custodian} and added to the current thread group (see @tech{current custodian} and added to the current thread group (see
@secref["threadgroups"]). A thread can have any number of custodian @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 A thread that has not terminated can be garbage collected (see
@secref["gc-model"]) if it is unreachable and suspended or if it is @secref["gc-model"]) if it is unreachable and suspended or if it is
unreachable and blocked on only unreachable events through unreachable and blocked on only unreachable events through
@scheme[semaphore-wait], @scheme[semaphore-wait/enable-break], @racket[semaphore-wait], @racket[semaphore-wait/enable-break],
@scheme[channel-put], @scheme[channel-get], @scheme[sync], @racket[channel-put], @racket[channel-get], @racket[sync],
@scheme[sync/enable-break], or @scheme[thread-wait]. @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 an internal semaphore when its event queue is empty. Thus, the handler
thread is collectible when the eventspace is unreachable and contains thread is collectible when the eventspace is unreachable and contains
no visible windows or running timers.} 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, 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'' to all threads, so that no thread can see a ``half-assigned''
variable. Similarly, @scheme[vector-set!] assigns to a vector variable. Similarly, @racket[vector-set!] assigns to a vector
atomically. The @scheme[hash-set!] procedure is not atomic, but atomically. The @racket[hash-set!] procedure is not atomic, but
the table is protected by a lock; see @secref["hashtables"] for more the table is protected by a lock; see @secref["hashtables"] for more
information. Port operations are generally not atomic, but they are information. Port operations are generally not atomic, but they are
thread-safe in the sense that a byte consumed by one thread from an 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 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. specific concurrency guarantees.
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -41,48 +41,48 @@ specific concurrency guarantees.
@defproc[(thread [thunk (-> any)]) thread?]{ @defproc[(thread [thunk (-> any)]) thread?]{
Calls @scheme[thunk] with no arguments in a new thread of control. The Calls @racket[thunk] with no arguments in a new thread of control. The
@scheme[thread] procedure returns immediately with a @deftech{thread @racket[thread] procedure returns immediately with a @deftech{thread
descriptor} value. When the invocation of @scheme[thunk] returns, the descriptor} value. When the invocation of @racket[thunk] returns, the
thread created to invoke @scheme[thunk] terminates. thread created to invoke @racket[thunk] terminates.
} }
@defproc[(thread? [v any/c]) thread?]{Returns @scheme[#t] if @defproc[(thread? [v any/c]) thread?]{Returns @racket[#t] if
@scheme[v] is a @tech{thread descriptor}, @scheme[#f] otherwise.} @racket[v] is a @tech{thread descriptor}, @racket[#f] otherwise.}
@defproc[(current-thread) thread?]{Returns the @tech{thread @defproc[(current-thread) thread?]{Returns the @tech{thread
descriptor} for the currently executing thread.} descriptor} for the currently executing thread.}
@defproc[(thread/suspend-to-kill [thunk (-> any)]) thread]{ @defproc[(thread/suspend-to-kill [thunk (-> any)]) thread]{
Like @scheme[thread], except that ``killing'' the thread through Like @racket[thread], except that ``killing'' the thread through
@scheme[kill-thread] or @scheme[custodian-shutdown-all] merely @racket[kill-thread] or @racket[custodian-shutdown-all] merely
suspends the thread instead of terminating it. } suspends the thread instead of terminating it. }
@defproc[(call-in-nested-thread [thunk (->any)] @defproc[(call-in-nested-thread [thunk (->any)]
[cust custodian? (current-custodian)]) [cust custodian? (current-custodian)])
any]{ any]{
Creates a nested thread managed by @scheme[cust] to execute Creates a nested thread managed by @racket[cust] to execute
@scheme[thunk]. (The nested thread's current custodian is inherited @racket[thunk]. (The nested thread's current custodian is inherited
from the creating thread, independent of the @scheme[cust] argument.) from the creating thread, independent of the @racket[cust] argument.)
The current thread blocks until @scheme[thunk] returns, and the result The current thread blocks until @racket[thunk] returns, and the result
of the @scheme[call-in-nested-thread] call is the result returned by of the @racket[call-in-nested-thread] call is the result returned by
@scheme[thunk]. @racket[thunk].
The nested thread's exception handler is initialized to a procedure The nested thread's exception handler is initialized to a procedure
that jumps to the beginning of the thread and transfers the exception that jumps to the beginning of the thread and transfers the exception
to the original thread. The handler thus terminates the nested thread to the original thread. The handler thus terminates the nested thread
and re-raises the exception in the original thread. and re-raises the exception in the original thread.
If the thread created by @scheme[call-in-nested-thread] dies before If the thread created by @racket[call-in-nested-thread] dies before
@scheme[thunk] returns, the @exnraise[exn:fail] in the original @racket[thunk] returns, the @exnraise[exn:fail] in the original
thread. If the original thread is killed before @scheme[thunk] thread. If the original thread is killed before @racket[thunk]
returns, a break is queued for the nested thread. returns, a break is queued for the nested thread.
If a break is queued for the original thread (with 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 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 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 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?]{ @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, 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 (i.e., it does not execute) until it is resumed with
@scheme[thread-resume]. If the @tech{current custodian} does not @racket[thread-resume]. If the @tech{current custodian} does not
manage @scheme[thd] (and none of its subordinates manages manage @racket[thd] (and none of its subordinates manages
@scheme[thd]), the @exnraise[exn:fail:contract], and the thread is not @racket[thd]), the @exnraise[exn:fail:contract], and the thread is not
suspended.} suspended.}
@defproc[(thread-resume [thd thread?][benefactor (or/c thread? custodian? #f) #f]) void?]{ @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 Resumes the execution of @racket[thd] if it is suspended and has at
least one custodian (possibly added through @scheme[benefactor], as least one custodian (possibly added through @racket[benefactor], as
described below). If the thread has terminated, or if the thread is described below). If the thread has terminated, or if the thread is
already running and @scheme[benefactor] is not supplied, or if the already running and @racket[benefactor] is not supplied, or if the
thread has no custodian and @scheme[benefactor] is not supplied, then thread has no custodian and @racket[benefactor] is not supplied, then
@scheme[thread-resume] has no effect. Otherwise, if @racket[thread-resume] has no effect. Otherwise, if
@scheme[benefactor] is supplied, it triggers up to three @racket[benefactor] is supplied, it triggers up to three
additional actions: additional actions:
@itemize[ @itemize[
@item{If @scheme[benefactor] is a thread, whenever it is resumed @item{If @racket[benefactor] is a thread, whenever it is resumed
from a suspended state in the future, then @scheme[thd] is also from a suspended state in the future, then @racket[thd] is also
resumed. (Resuming @scheme[thd] may trigger the resumption of other resumed. (Resuming @racket[thd] may trigger the resumption of other
threads that were previously attached to @scheme[thd] through threads that were previously attached to @racket[thd] through
@scheme[thread-resume].)} @racket[thread-resume].)}
@item{New custodians may be added to @scheme[thd]'s set of @item{New custodians may be added to @racket[thd]'s set of
managers. If @scheme[benefactor] is a thread, then all of the managers. If @racket[benefactor] is a thread, then all of the
thread's custodians are added to @scheme[thd]. Otherwise, thread's custodians are added to @racket[thd]. Otherwise,
@scheme[benefactor] is a custodian, and it is added to @scheme[thd] @racket[benefactor] is a custodian, and it is added to @racket[thd]
(unless the custodian is already shut down). If @scheme[thd] (unless the custodian is already shut down). If @racket[thd]
becomes managed by both a custodian and one or more of its becomes managed by both a custodian and one or more of its
subordinates, the redundant subordinates are removed from subordinates, the redundant subordinates are removed from
@scheme[thd]. If @scheme[thd] is suspended and a custodian is @racket[thd]. If @racket[thd] is suspended and a custodian is
added, then @scheme[thd] is resumed only after the addition.} added, then @racket[thd] is resumed only after the addition.}
@item{If @scheme[benefactor] is a thread, whenever it receives a @item{If @racket[benefactor] is a thread, whenever it receives a
new managing custodian in the future, then @scheme[thd] also new managing custodian in the future, then @racket[thd] also
receives the custodian. (Adding custodians to @scheme[thd] may receives the custodian. (Adding custodians to @racket[thd] may
trigger adding the custodians to other threads that were previously 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?]{ @defproc[(kill-thread [thd thread?]) void?]{
Terminates the specified thread immediately, or suspends the thread if Terminates the specified thread immediately, or suspends the thread if
@scheme[thd] was created with @racket[thd] was created with
@scheme[thread/suspend-to-kill]. Terminating the main thread exits the @racket[thread/suspend-to-kill]. Terminating the main thread exits the
application. If @scheme[thd] has already terminated, application. If @racket[thd] has already terminated,
@scheme[kill-thread] does nothing. If the @tech{current custodian} @racket[kill-thread] does nothing. If the @tech{current custodian}
does not manage @scheme[thd] (and none of its subordinates manages does not manage @racket[thd] (and none of its subordinates manages
@scheme[thd]), the @exnraise[exn:fail:contract], and the thread is not @racket[thd]), the @exnraise[exn:fail:contract], and the thread is not
killed or suspended. 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 kill-safe and suspend-safe; that is, killing or suspending a thread
never interferes with the application of procedures in other never interferes with the application of procedures in other
threads. For example, if a thread is killed while extracting a 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?]{ @defproc[(break-thread [thd thread?]) void?]{
@index['("threads" "breaking")]{Registers} a break with the specified @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"]).} ignored until breaks are re-enabled (see @secref["breakhandler"]).}
@defproc[(sleep [secs nonnegative-number? 0]) void?]{ @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 seconds have passed after it starts sleeping. A zero value for
@scheme[secs] simply acts as a hint to allow other threads to @racket[secs] simply acts as a hint to allow other threads to
execute. The value of @scheme[secs] can be non-integral to request a execute. The value of @racket[secs] can be non-integral to request a
sleep duration to any precision; the precision of the actual sleep sleep duration to any precision; the precision of the actual sleep
time is unspecified.} time is unspecified.}
@defproc[(thread-running? [thd thread?]) any]{ @defproc[(thread-running? [thd thread?]) any]{
@index['("threads" "run state")]{Returns} @scheme[#t] if @scheme[thd] @index['("threads" "run state")]{Returns} @racket[#t] if @racket[thd]
has not terminated and is not suspended, @scheme[#f] otherwise.} has not terminated and is not suspended, @racket[#f] otherwise.}
@defproc[(thread-dead? [thd thread?]) any]{ @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.} otherwise.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -188,42 +188,42 @@ otherwise.}
@defproc[(thread-wait [thd thread?]) void?]{ @defproc[(thread-wait [thd thread?]) void?]{
Blocks execution of the current thread until @scheme[thd] has Blocks execution of the current thread until @racket[thd] has
terminated. Note that @scheme[(thread-wait (current-thread))] terminated. Note that @racket[(thread-wait (current-thread))]
deadlocks the current thread, but a break can end the deadlock (if deadlocks the current thread, but a break can end the deadlock (if
breaking is enabled; see @secref["breakhandler"]).} breaking is enabled; see @secref["breakhandler"]).}
@defproc[(thread-dead-evt [thd thread?]) evt?]{ @defproc[(thread-dead-evt [thd thread?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that is Returns a @tech{synchronizable event} (see @secref["sync"]) that is
ready if and only if @scheme[thd] has terminated. Unlike using ready if and only if @racket[thd] has terminated. Unlike using
@scheme[thd] directly, however, a reference to the event does not @racket[thd] directly, however, a reference to the event does not
prevent @scheme[thd] from being garbage collected (see prevent @racket[thd] from being garbage collected (see
@secref["gc-model"]). For a given @scheme[thd], @secref["gc-model"]). For a given @racket[thd],
@scheme[thread-dead-evt] always returns the same (i.e., @scheme[eq?]) @racket[thread-dead-evt] always returns the same (i.e., @racket[eq?])
result.} result.}
@defproc[(thread-resume-evt [thd thread?]) evt?]{ @defproc[(thread-resume-evt [thd thread?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that Returns a @tech{synchronizable event} (see @secref["sync"]) that
becomes ready when @scheme[thd] is running. (If @scheme[thd] has becomes ready when @racket[thd] is running. (If @racket[thd] has
terminated, the event never becomes ready.) If @scheme[thd] runs and terminated, the event never becomes ready.) If @racket[thd] runs and
is then suspended after a call to @scheme[thread-resume-evt], the is then suspended after a call to @racket[thread-resume-evt], the
result event remains ready; after each suspend of @scheme[thd] a fresh result event remains ready; after each suspend of @racket[thd] a fresh
event is generated to be returned by @scheme[thread-resume-evt]. The event is generated to be returned by @racket[thread-resume-evt]. The
result of the event is @scheme[thd], but if @scheme[thd] is never result of the event is @racket[thd], but if @racket[thd] is never
resumed, then reference to the event does not prevent @scheme[thd] resumed, then reference to the event does not prevent @racket[thd]
from being garbage collected (see @secref["gc-model"]).} from being garbage collected (see @secref["gc-model"]).}
@defproc[(thread-suspend-evt [thd thread?]) evt?]{ @defproc[(thread-suspend-evt [thd thread?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that Returns a @tech{synchronizable event} (see @secref["sync"]) that
becomes ready when @scheme[thd] is suspended. (If @scheme[thd] has becomes ready when @racket[thd] is suspended. (If @racket[thd] has
terminated, the event will never unblock.) If @scheme[thd] is terminated, the event will never unblock.) If @racket[thd] is
suspended and then resumes after a call to suspended and then resumes after a call to
@scheme[thread-suspend-evt], the result event remains ready; after @racket[thread-suspend-evt], the result event remains ready; after
each resume of @scheme[thd] created a fresh event to be returned by each resume of @racket[thd] created a fresh event to be returned by
@scheme[thread-suspend-evt].} @racket[thread-suspend-evt].}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "threadmbox"]{Thread Mailboxes} @section[#:tag "threadmbox"]{Thread Mailboxes}
@ -239,23 +239,23 @@ asynchronous channel.
(lambda () (raise-mismatch-error ....))]) (lambda () (raise-mismatch-error ....))])
any]{ any]{
Queues @scheme[v] as a message to @scheme[thd] without blocking. If Queues @racket[v] as a message to @racket[thd] without blocking. If
the message is queued, the result is @|void-const|. If @scheme[thd] the message is queued, the result is @|void-const|. If @racket[thd]
stops running---as in @scheme[thread-running?]---before the message is stops running---as in @racket[thread-running?]---before the message is
queued, then @scheme[fail-thunk] is called (through a tail call) if is queued, then @racket[fail-thunk] is called (through a tail call) if is
a procedure to produce the result, or @scheme[#f] is returned if a procedure to produce the result, or @racket[#f] is returned if
@scheme[fail-thunk] is @scheme[#f].} @racket[fail-thunk] is @racket[#f].}
@defproc[(thread-receive) any/c]{ @defproc[(thread-receive) any/c]{
Receives and dequeues a message queued for the current thread, if 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.} one is available.}
@defproc[(thread-try-receive) any/c]{ @defproc[(thread-try-receive) any/c]{
Receives and dequeues a message queued for the current thread, if any, 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?]{ @defproc[(thread-receive-evt) evt?]{
@ -265,6 +265,6 @@ receive. The event result is itself.}
@defproc[(thread-rewind-receive [lst list?]) void?]{ @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 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].}

60
collects/scribblings/reference/time.scrbl
View File

@ -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 integer based on a platform-specific starting date (with a
platform-specific minimum and maximum value). 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 (increasing by 1 for each second that passes). The current time in
seconds can be compared with a time returned by 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?]{ @defproc[(seconds->date [secs-n exact-integer?]) date?]{
Takes @scheme[secs-n], a platform-specific time in seconds returned by Takes @racket[secs-n], a platform-specific time in seconds returned by
@scheme[current-seconds] or @scheme[file-or-directory-modify-seconds], @racket[current-seconds] or @racket[file-or-directory-modify-seconds],
and returns an instance of the @scheme[date] structure type. If and returns an instance of the @racket[date] structure type. If
@scheme[secs-n] is too small or large, the @exnraise[exn:fail]. @racket[secs-n] is too small or large, the @exnraise[exn:fail].
The value returned by @scheme[current-seconds] or The value returned by @racket[current-seconds] or
@scheme[file-or-directory-modify-seconds] is not portable among @racket[file-or-directory-modify-seconds] is not portable among
platforms. Convert a time in seconds using @scheme[seconds->date] when platforms. Convert a time in seconds using @racket[seconds->date] when
portability is needed.} portability is needed.}
@defstruct[date ([second (integer-in 0 61)] @defstruct[date ([second (integer-in 0 61)]
@ -40,21 +40,21 @@ portability is needed.}
[time-zone-offset exact-integer?]) [time-zone-offset exact-integer?])
#:inspector #f]{ #:inspector #f]{
Represents a date. For the @scheme[second] field, values of Represents a date. For the @racket[second] field, values of
@scheme[60] and @scheme[61] are for unusual, but possible for @racket[60] and @racket[61] are for unusual, but possible for
leap-seconds. The @scheme[year-day] field reaches @scheme[365] only in leap-seconds. The @racket[year-day] field reaches @racket[365] only in
leap years. 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 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, sensitive to the value of the @envvar{TZ} environment variable,
especially on Unix platforms; consult the system documentation especially on Unix platforms; consult the system documentation
(usually under @tt{tzset}) for details. (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?]{ @defproc[(current-milliseconds) exact-integer?]{
@ -76,11 +76,11 @@ Returns the current time in milliseconds since midnight UTC, January
exact-integer?]{ exact-integer?]{
Returns an amount of processor time in @tech{fixnum} milliseconds 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 operating system. (Under @|AllUnix|, this includes both user and
system time.) If @scheme[thread] is @scheme[#f], the reported time system time.) If @racket[thread] is @racket[#f], the reported time
is for all Scheme threads, otherwise the result is specific to the is for all Racket threads, otherwise the result is specific to the
time while @scheme[thread] ran. time while @racket[thread] ran.
The precision of the result is platform-specific, and The precision of the result is platform-specific, and
since the result is a @tech{fixnum}, the value increases only over a since the result is a @tech{fixnum}, the value increases only over a
limited (though reasonably long) time.} limited (though reasonably long) time.}
@ -89,9 +89,9 @@ limited (though reasonably long) time.}
@defproc[(current-gc-milliseconds) exact-integer?]{ @defproc[(current-gc-milliseconds) exact-integer?]{
Returns the amount of processor time in @tech{fixnum} milliseconds 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 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?] @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. Collects timing information for a procedure application.
Four values are returned: a list containing the result(s) of applying 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 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 required for the result, and the number of milliseconds of CPU time (included
in the first result) spent on garbage collection. in the first result) spent on garbage collection.
The reliability of the timing numbers depends on the platform. If 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.} include work performed by other threads.}
@defform[(time expr)]{ @defform[(time expr)]{
Reports @scheme[time-apply]-style timing information for the Reports @racket[time-apply]-style timing information for the
evaluation of @scheme[expr] directly to the current output port. The evaluation of @racket[expr] directly to the current output port. The
result is the result of @scheme[expr].} 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?]{ @defproc[(date->string [date date?][time? any/c #f]) string?]{
Converts a date to a string. The returned string contains the time of 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 @defparam[date-display-format format (or/c 'american
@ -141,7 +141,7 @@ day only if @scheme[time?]. See also @scheme[date-display-format].}
'julian)]{ 'julian)]{
Parameter that determines the date string format. The initial format Parameter that determines the date string format. The initial format
is @scheme['american].} is @racket['american].}
@defproc[(find-seconds [second (integer-in 0 61)] @defproc[(find-seconds [second (integer-in 0 61)]
@ -153,7 +153,7 @@ is @scheme['american].}
exact-integer?]{ exact-integer?]{
Finds the representation of a date in platform-specific seconds. The 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 the platform cannot represent the specified date, an error is
signaled, otherwise an integer is returned.} signaled, otherwise an integer is returned.}

12
collects/scribblings/reference/unix-paths.scrbl
View File

@ -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 preceding path, and @litchar{..} as a path element always means the
parent of the directory indicated by the preceding path. A leading parent of the directory indicated by the preceding path. A leading
@litchar{~} in a path is not treated specially, but @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 element to a user-specific directory. No other character or byte has a
special meaning within a path. Multiple adjacent @litchar{/} are special meaning within a path. Multiple adjacent @litchar{/} are
equivalent to a single @litchar{/} (i.e., they act as a single path 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 A @|AllUnix| path is @techlink{cleanse}d by replacing multiple adjacent
@litchar{/}s with a single @litchar{/}. @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]. contain any @litchar{/}, otherwise the @exnraise[exn:fail:contract].
The result of @scheme[(path-element->bytes _path)] or The result of @racket[(path-element->bytes _path)] or
@scheme[(path-element->string _path)] is always the same as the result @racket[(path-element->string _path)] is always the same as the result
of @scheme[(path->bytes _path)] and @scheme[(path->string of @racket[(path->bytes _path)] and @racket[(path->string
_path)]. Since that is not the case for other platforms, however, _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. be used when converting individual path elements.
Under Mac OS X, Finder aliases are zero-length files. Under Mac OS X, Finder aliases are zero-length files.

70
collects/scribblings/reference/windows-paths.scrbl
View File

@ -2,7 +2,7 @@
@(require scribble/bnf @(require scribble/bnf
"mz.ss") "mz.ss")
@(define MzAdd (italic "Scheme-specific:")) @(define MzAdd (italic "Racket-specific:"))
@title[#:tag "windowspaths"]{Windows Path Conventions} @title[#:tag "windowspaths"]{Windows Path Conventions}
@ -21,14 +21,14 @@ colon, a UNC path of the form
@litchar{RED\}@nonterm{element}. (Variants of @litchar{\\?\} @litchar{RED\}@nonterm{element}. (Variants of @litchar{\\?\}
paths are described further below.) paths are described further below.)
Scheme fails to implement the usual Windows path syntax in one Racket fails to implement the usual Windows path syntax in one
way. Outside of Scheme, a pathname @filepath{C:rant.txt} can be a 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} 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 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 support drive-specific working directories (only a working directory
across all drives, as reflected by the @scheme[current-directory] across all drives, as reflected by the @racket[current-directory]
parameter). Consequently, Scheme implicitly converts a path like parameter). Consequently, Racket implicitly converts a path like
@filepath{C:rant.txt} into @filepath["C:\\rant.txt"]. @filepath{C:rant.txt} into @filepath["C:\\rant.txt"].
@itemize[ @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 adds @litchar{\\?\REL} and @litchar{\\?\RED} conventions to
deal with paths inexpressible in the standard convention, plus deal with paths inexpressible in the standard convention, plus
conventions to deal with excessive @litchar{\}s in @litchar{\\?\} conventions to deal with excessive @litchar{\}s in @litchar{\\?\}
@ -145,7 +145,7 @@ include @litchar{\}.
@litchar{\\?\REL\\}@nonterm{element} is a relative @litchar{\\?\REL\\}@nonterm{element} is a relative
path, as long as the path does not end with two consecutive path, as long as the path does not end with two consecutive
@litchar{\}s, and as long as the path contains no sequence of @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 supports relative paths with elements that are not normally
expressible in Windows paths (e.g., a final element that ends expressible in Windows paths (e.g., a final element that ends
in a space). The @litchar{REL} part must be exactly the three 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 drive-relative path, as long as the path does not end with two
consecutive @litchar{\}s, and as long as the path contains consecutive @litchar{\}s, and as long as the path contains
no sequence of three or more @litchar{\}s. This 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 absolute given a drive) with elements that are not normally
expressible in Windows paths. The @litchar{RED} part must be expressible in Windows paths. The @litchar{RED} part must be
exactly the three uppercase letters, and @litchar{/}s cannot 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: sequences that are otherwise ill-formed as Windows paths:
@itemize[ @itemize[
@ -214,8 +214,8 @@ sequences that are otherwise ill-formed as Windows paths:
] ]
Outside of Scheme, except for @litchar{\\?\} paths, pathnames are Outside of Racket, except for @litchar{\\?\} paths, pathnames are
typically limited to 259 characters. Scheme internally converts typically limited to 259 characters. Racket internally converts
pathnames to @litchar{\\?\} form as needed to avoid this pathnames to @litchar{\\?\} form as needed to avoid this
limit. The operating system cannot access files through limit. The operating system cannot access files through
@litchar{\\?\} paths that are longer than 32,000 characters or @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. mentioned above are ASCII, so all of the rules are the same.
Beware that the @litchar{\} path separator is an escape character Beware that the @litchar{\} path separator is an escape character
in Scheme strings. Thus, the path @litchar{\\?\REL\..\\..} as in Racket strings. Thus, the path @litchar{\\?\REL\..\\..} as
a string must be written @scheme["\\\\?\\REL\\..\\\\.."]. a string must be written @racket["\\\\?\\REL\\..\\\\.."].
A path that ends with a directory separator syntactically refers to a A path that ends with a directory separator syntactically refers to a
directory. In addition, a path syntactcially refers to a directory if 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 folder name), a @litchar{/} is inserted after the colon in a drive
specification if it is missing. 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., trailing dots, trailing whitespace, and special device names (e.g.,
``aux'') in @scheme[_bstr] are encoded as a literal part of the path ``aux'') in @racket[_bstr] are encoded as a literal part of the path
element by using a @litchar{\\?\REL} prefix. The @scheme[bstr] element by using a @litchar{\\?\REL} prefix. The @racket[bstr]
argument must not contain a @litchar{\}, otherwise the argument must not contain a @litchar{\}, otherwise the
@exnraise[exn:fail:contract]. @exnraise[exn:fail:contract].
For @scheme[(path-element->bytes _path)] or For @racket[(path-element->bytes _path)] or
@scheme[(path-element->string _path)], if the byte-string form of @racket[(path-element->string _path)], if the byte-string form of
@scheme[_path] starts with a @litchar{\\?\REL}, the prefix is not @racket[_path] starts with a @litchar{\\?\REL}, the prefix is not
included in the result. included in the result.
For @scheme[(build-path _base-path _sub-path ...)], trailing spaces For @racket[(build-path _base-path _sub-path ...)], trailing spaces
and periods are removed from the last element of @scheme[_base-path] and periods are removed from the last element of @racket[_base-path]
and all but the last @scheme[_sub-path] (unless the element consists of and all but the last @racket[_sub-path] (unless the element consists of
only spaces and peroids), except for those that start with 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 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, @litchar{/}s in the addition are converted to @litchar{\}s,
multiple consecutive @litchar{\}s are converted to a single multiple consecutive @litchar{\}s are converted to a single
@litchar{\}, added @litchar{.} elements are removed, and added @litchar{\}, added @litchar{.} elements are removed, and added
@litchar{..} elements are removed along with the preceding element; @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 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\} @litchar{\\?\REL\} or @litchar{\\?\RED\}
@scheme[_sub-path] is added to a non-@litchar{\\?\} @racket[_sub-path] is added to a non-@litchar{\\?\}
@scheme[_base-path], the @scheme[_base-path] (with any additions up @racket[_base-path], the @racket[_base-path] (with any additions up
to the @litchar{\\?\REL\} or @litchar{\\?\RED\} 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 @litchar{\\?\} path. In other cases, a @litchar{\} may be
added or removed before combining paths to avoid changing the root added or removed before combining paths to avoid changing the root
meaning of the path (e.g., combining @litchar{//x} and @litchar{y} 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 produces @litchar{/x/y}, because @litchar{//x/y} would be a UNC path
instead of a drive-relative path). instead of a drive-relative path).
For @scheme[(simplify-path _path _use-filesystem?)], @scheme[_path] is For @racket[(simplify-path _path _use-filesystem?)], @racket[_path] is
expanded, and if @scheme[_path] does not start with expanded, and if @racket[_path] does not start with
@litchar{\\?\}, trailing spaces and periods are removed, a @litchar{\\?\}, trailing spaces and periods are removed, a
@litchar{/} is inserted after the colon in a drive specification if it @litchar{/} is inserted after the colon in a drive specification if it
is missing, and a @litchar{\} is inserted after @litchar{\\?\} is missing, and a @litchar{\} is inserted after @litchar{\\?\}
as a root if there are elements and no extra @litchar{\} as a root if there are elements and no extra @litchar{\}
already. Otherwise, if no indicators or redundant separators are in 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], For @racket[(split-path _path)] producing @racket[_base],
@scheme[_name], and @scheme[_must-be-dir?], splitting a path that does @racket[_name], and @racket[_must-be-dir?], splitting a path that does
not start with @litchar{\\?\} can produce parts that start with not start with @litchar{\\?\} can produce parts that start with
@litchar{\\?\}. For example, splitting @litchar{C:/x~/aux/} @litchar{\\?\}. For example, splitting @litchar{C:/x~/aux/}
produces @litchar{\\?\C:\x~\} and @litchar{\\?\REL\\aux}; produces @litchar{\\?\C:\x~\} and @litchar{\\?\REL\\aux};

162
collects/scribblings/reference/write.scrbl
View File

@ -9,14 +9,14 @@
@defproc[(write [datum any/c][out output-port? (current-output-port)]) @defproc[(write [datum any/c][out output-port? (current-output-port)])
void?]{ void?]{
Writes @scheme[datum] to @scheme[out], normally in such a way that Writes @racket[datum] to @racket[out], normally in such a way that
instances of core datatypes can be read back in. If @scheme[out] has a instances of core datatypes can be read back in. If @racket[out] has a
handler associated to it via @scheme[port-write-handler], then the handler associated to it via @racket[port-write-handler], then the
handler is called. Otherwise, the default printer is used (in 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 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 proportional to the depth of the value being printed, due to the
initial cycle check. initial cycle check.
@ -31,15 +31,15 @@ initial cycle check.
@defproc[(display [datum any/c][out output-port? (current-output-port)]) @defproc[(display [datum any/c][out output-port? (current-output-port)])
void?]{ 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 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 written as raw bytes or characters. If @racket[out] has a handler
associated to it via @scheme[port-display-handler], then the handler associated to it via @racket[port-display-handler], then the handler
is called. Otherwise, the default printer is used (in @scheme[display] is called. Otherwise, the default printer is used (in @racket[display]
mode), as configured by various parameters. mode), as configured by various parameters.
See @secref["printing"] for more information about the default 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 proportional to the depth of the value being printed, due to the
initial cycle check.} initial cycle check.}
@ -47,29 +47,29 @@ initial cycle check.}
[exact-nonnegative-integer? qq-depth 0]) [exact-nonnegative-integer? qq-depth 0])
void?]{ void?]{
Writes @scheme[datum] to @scheme[out], normally the same way as Writes @racket[datum] to @racket[out], normally the same way as
@scheme[write]. If @scheme[out] has a handler associated to it via @racket[write]. If @racket[out] has a handler associated to it via
@scheme[port-print-handler], then the handler is called. Otherwise, @racket[port-print-handler], then the handler is called. Otherwise,
the handler specified by @scheme[global-port-print-handler] is called; the handler specified by @racket[global-port-print-handler] is called;
the default handler uses the default printer in @scheme[write] mode. the default handler uses the default printer in @racket[write] mode.
The optional @scheme[qq-depth] argument adjust printing when the The optional @racket[qq-depth] argument adjust printing when the
@scheme[print-as-quasiquote] parameter is set to @scheme[#t]. In that @racket[print-as-quasiquote] parameter is set to @racket[#t]. In that
case, @scheme[qq-depth] specifies the starting @scheme[quasiquote] case, @racket[qq-depth] specifies the starting @racket[quasiquote]
depth for printing @scheme[datum]. depth for printing @racket[datum].
The rationale for providing @scheme[print] is that @scheme[display] The rationale for providing @racket[print] is that @racket[display]
and @scheme[write] both have specific output conventions, and those and @racket[write] both have specific output conventions, and those
conventions restrict the ways that an environment can change the conventions restrict the ways that an environment can change the
behavior of @scheme[display] and @scheme[write] procedures. No output behavior of @racket[display] and @racket[write] procedures. No output
conventions should be assumed for @scheme[print], so that environments conventions should be assumed for @racket[print], so that environments
are free to modify the actual output generated by @scheme[print] in are free to modify the actual output generated by @racket[print] in
any way.} any way.}
@defproc[(fprintf [out output-port?][form string?][v any/c] ...) void?]{ @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 that is printed directly, except for special formatting
escapes: escapes:
@ -77,51 +77,51 @@ escapes:
@item{@FmtMark{n} or @FmtMark{%} prints a newline, the same as @litchar{\n}} @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 @item{@FmtMark{a} or @FmtMark{A} @racket[display]s the next argument
among the @scheme[v]s} among the @racket[v]s}
@item{@FmtMark{s} or @FmtMark{S} @scheme[write]s the next argument @item{@FmtMark{s} or @FmtMark{S} @racket[write]s the next argument
among the @scheme[v]s} among the @racket[v]s}
@item{@FmtMark{v} or @FmtMark{V} @scheme[print]s the next argument @item{@FmtMark{v} or @FmtMark{V} @racket[print]s the next argument
among the @scheme[v]s} among the @racket[v]s}
@item{@FmtMark{e} or @FmtMark{E} outputs the next argument among the @item{@FmtMark{e} or @FmtMark{E} outputs the next argument among the
@scheme[v]s using the current error value conversion handler (see @racket[v]s using the current error value conversion handler (see
@scheme[error-value->string-handler]) and current error printing @racket[error-value->string-handler]) and current error printing
width} @item{@FmtMark{c} or @FmtMark{C} @scheme[write-char]s the width} @item{@FmtMark{c} or @FmtMark{C} @racket[write-char]s the
next argument in @scheme[v]s; if the next argument is not a next argument in @racket[v]s; if the next argument is not a
character, the @exnraise[exn:fail:contract]} character, the @exnraise[exn:fail:contract]}
@item{@FmtMark{b} or @FmtMark{B} prints the next argument among the @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]} @exnraise[exn:fail:contract]}
@item{@FmtMark{o} or @FmtMark{O} prints the next argument among the @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]} @exnraise[exn:fail:contract]}
@item{@FmtMark{x} or @FmtMark{X} prints the next argument among the @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]} number, the @exnraise[exn:fail:contract]}
@item{@FmtMark{~} prints a tilde.} @item{@FmtMark{~} prints a tilde.}
@item{@FmtMark{}@nonterm{w}, where @nonterm{w} is a whitespace @item{@FmtMark{}@nonterm{w}, where @nonterm{w} is a whitespace
character (see @scheme[char-whitespace?]), skips characters in character (see @racket[char-whitespace?]), skips characters in
@scheme[form] until a non-whitespace character is encountered or @racket[form] until a non-whitespace character is encountered or
until a second end-of-line is encountered (whichever happens until a second end-of-line is encountered (whichever happens
first). On all platforms, an end-of-line can be @scheme[#\return], first). On all platforms, an end-of-line can be @racket[#\return],
@scheme[#\newline], or @scheme[#\return] followed immediately by @racket[#\newline], or @racket[#\return] followed immediately by
@scheme[#\newline].} @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 not one of the above escapes, otherwise the
@exnraise[exn:fail:contract]. When the format string requires more @exnraise[exn:fail:contract]. When the format string requires more
@scheme[v]s than are supplied, the @racket[v]s than are supplied, the
@exnraise[exn:fail:contract]. Similarly, when more @scheme[v]s are @exnraise[exn:fail:contract]. Similarly, when more @racket[v]s are
supplied than are used by the format string, the supplied than are used by the format string, the
@exnraise[exn:fail:contract]. @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?]{ @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?]{ @defproc[(format [form string?][v any/c] ...) string?]{
Formats to a string. The result is the same as Formats to a string. The result is the same as
@schemeblock[ @racketblock[
(let ([o (open-output-string)]) (let ([o (open-output-string)])
(fprintf o form v ...) (fprintf o form v ...)
(get-output-string o)) (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 A parameter that control pair printing. If the value is true, then
pairs print using @litchar["{"] and @litchar["}"] instead of 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?]{ @defboolparam[print-mpair-curly-braces on?]{
A parameter that control pair printing. If the value is true, then A parameter that control pair printing. If the value is true, then
mutable pairs print using @litchar["{"] and @litchar["}"] instead of 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?]{ @defboolparam[print-unreadable on?]{
A parameter that controls printing values that have no 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 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 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.} @secref["printing"] for more information.}
@defboolparam[print-graph on?]{ @defboolparam[print-graph on?]{
A parameter that controls printing data with sharing; defaults to 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?]{ @defboolparam[print-struct on?]{
A parameter that controls printing structure values in vector or 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 for more information. This parameter has no effect on the printing of
structures that have a custom-write procedure (see structures that have a custom-write procedure (see
@scheme[prop:custom-write]).} @racket[prop:custom-write]).}
@defboolparam[print-box on?]{ @defboolparam[print-box on?]{
A parameter that controls printing box values; defaults to 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?]{ @defboolparam[print-vector-length on?]{
A parameter that controls printing vectors; defaults to 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?]{ @defboolparam[print-hash-table on?]{
A parameter that controls printing hash tables; defaults to 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?]{ @defboolparam[print-reader-abbreviations on?]{
A parameter that controls printing of two-element lists that start A parameter that controls printing of two-element lists that start
with @scheme[quote], @scheme['quasiquote], @scheme['unquote], with @racket[quote], @racket['quasiquote], @racket['unquote],
@scheme['unquote-splicing], @scheme['syntax], @scheme['quasisyntax], @racket['unquote-splicing], @racket['syntax], @racket['quasisyntax],
@scheme['unsyntax], or @scheme['unsyntax-splicing]; defaults to @racket['unsyntax], or @racket['unsyntax-splicing]; defaults to
@scheme[#f]. See @secref["print-pairs"] for more information.} @racket[#f]. See @secref["print-pairs"] for more information.}
@defboolparam[print-as-quasiquote on?]{ @defboolparam[print-as-quasiquote on?]{
A parameter that controls printing in @scheme[print] mode (as opposed A parameter that controls printing in @racket[print] mode (as opposed
to @scheme[write] or @scheme[display]); defaults to @scheme[#f]. See to @racket[write] or @racket[display]); defaults to @racket[#f]. See
@secref["printing"] for more information.} @secref["printing"] for more information.}
@defboolparam[print-honu on?]{ @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)))]{ @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 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{#<syntax}...@litchar{>} (after the object within @litchar{#<syntax}...@litchar{>} (after the
@tech{syntax object}'s source location, if any).} @tech{syntax object}'s source location, if any).}
@ -233,11 +233,11 @@ object within @litchar{#<syntax}...@litchar{>} (after the
A parameter that is used when writing compiled code that contains A parameter that is used when writing compiled code that contains
pathname literals, including source-location pathnames for procedure 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 parameter's value are converted to relative paths; when the resulting
compiled code is read, relative paths are converted back to complete compiled code is read, relative paths are converted back to complete
paths using the @scheme[current-load-relative-directory] parameter (if paths using the @racket[current-load-relative-directory] parameter (if
it is not @scheme[#f], otherwise the path is left relative).} 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?])]{ void?])]{
Gets or sets the @deftech{port write handler}, @deftech{port display Gets or sets the @deftech{port write handler}, @deftech{port display
handler}, or @deftech{port print handler} for @scheme[out]. This handler}, or @deftech{port print handler} for @racket[out]. This
handler is call to output to the port when @scheme[write], handler is call to output to the port when @racket[write],
@scheme[display], or @scheme[print] (respectively) is applied to the @racket[display], or @racket[print] (respectively) is applied to the
port. Each handler must accept two arguments: the value to be printed and port. Each handler must accept two arguments: the value to be printed and
the destination port. The handler's return value is ignored. the destination port. The handler's return value is ignored.
A @tech{port print handler} optionally accepts a third argument, which A @tech{port print handler} optionally accepts a third argument, which
corresponds to the optional third argument to @scheme[print]; if a corresponds to the optional third argument to @racket[print]; if a
procedure given to @scheme[port-print-handler] does not accept a third procedure given to @racket[port-print-handler] does not accept a third
argument, it is wrapped with a procedure that discards the optional argument, it is wrapped with a procedure that discards the optional
third argument. third argument.
The default port display and write handlers print Scheme expressions The default port display and write handlers print Racket expressions
with Scheme's built-in printer (see @secref["printing"]). The with Racket's built-in printer (see @secref["printing"]). The
default print handler calls the global port print handler (the value 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.} 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)] @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}, A parameter that determines @deftech{global port print handler},
which is called by the default port print handler (see 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 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 A @tech{global port print handler} optionally accepts a third
argument, which corresponds to the optional third argument to argument, which corresponds to the optional third argument to
@scheme[print]. If a procedure given to @racket[print]. If a procedure given to
@scheme[global-port-print-handler] does not accept a third argument, @racket[global-port-print-handler] does not accept a third argument,
it is wrapped with a procedure that discards the optional third it is wrapped with a procedure that discards the optional third
argument.} argument.}

57
collects/scribblings/scheme/scheme.scrbl
View File

@ -34,8 +34,9 @@ old name.
@table-of-contents[] @table-of-contents[]
@compat-except[scheme racket]{, except that @schememodname[racket]'s @compat-except[scheme racket]{, except that @schememodname[racket]'s
@scheme[struct] is not exported, and a @|unit-struct| from @scheme[struct] is not exported, the @|unit-struct| from
@schememodname[scheme/unit] is exported, instead} @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 @compat-except[scheme/base racket/base]{, except that
@schememodname[racket]'s @scheme[struct] is not exported, and @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/match racket/match]
@compat[scheme/math racket/math] @compat[scheme/math racket/math]
@compat[scheme/mpair racket/mpair] @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/package racket/package]
@compat[scheme/path racket/path] @compat[scheme/path racket/path]
@compat[scheme/port racket/port] @compat[scheme/port racket/port]

20
src/gracket/wxs/wxscheme.cxx
View File

@ -2514,10 +2514,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv)
if (which == id_init_file) if (which == id_init_file)
return append_path(home, return append_path(home,
scheme_make_path("/.mredrc" + ends_in_slash)); scheme_make_path("/.gracketrc" + ends_in_slash));
if (which == id_setup_file) if (which == id_setup_file)
return append_path(home, 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 (which == id_x_display) {
# if defined(wx_x) # if defined(wx_x)
@ -2541,10 +2541,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv)
if (which == id_init_file) if (which == id_init_file)
return append_path(home, return append_path(home,
scheme_make_path("\\mredrc.ss" + ends_in_slash)); scheme_make_path("\\gracketrc" + ends_in_slash));
if (which == id_setup_file) if (which == id_setup_file)
return append_path(home, 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) if (which == id_x_display)
return scheme_false; return scheme_false;
@ -2584,10 +2584,10 @@ Scheme_Object *wxSchemeFindDirectory(int argc, Scheme_Object **argv)
if (which == id_init_file) if (which == id_init_file)
return append_path(home, return append_path(home,
scheme_make_path(":mredrc.ss" + ends_in_colon)); scheme_make_path(":gracketrc" + ends_in_colon));
if (which == id_setup_file) if (which == id_setup_file)
return append_path(home, return append_path(home,
scheme_make_path(":mred.fnt" + ends_in_colon)); scheme_make_path(":gracket.fnt" + ends_in_colon));
#endif #endif
return scheme_void; return scheme_void;
@ -2778,9 +2778,9 @@ int wxGetPreference(const char *name, char *res, long len)
if (!ends_in_slash) if (!ends_in_slash)
s[l++] = '/'; s[l++] = '/';
# ifdef wx_mac # ifdef wx_mac
memcpy(s + l, "org.plt-scheme.prefs.ss", 24); memcpy(s + l, "org.racket-lang.prefs", 24);
# else # else
memcpy(s + l, "plt-prefs.ss", 13); memcpy(s + l, "racket-prefs", 13);
# endif # endif
#endif #endif
@ -2796,7 +2796,7 @@ int wxGetPreference(const char *name, char *res, long len)
memcpy(s, home, l); memcpy(s, home, l);
if (!ends_in_slash) if (!ends_in_slash)
s[l++] = '\\'; s[l++] = '\\';
memcpy(s + l, "plt-prefs.ss", 13); memcpy(s + l, "racket-prefs", 13);
#endif #endif
/*************** Mac OS Classic ***************/ /*************** Mac OS Classic ***************/
@ -2825,7 +2825,7 @@ int wxGetPreference(const char *name, char *res, long len)
memcpy(s, home, l); memcpy(s, home, l);
if (!ends_in_slash) if (!ends_in_slash)
s[l++] = ':'; s[l++] = ':';
memcpy(s + l, "org.plt-scheme.prefs.ss", 24); memcpy(s + l, "org.racket-lang.prefs", 24);
} }
#endif #endif

20
src/racket/src/file.c
View File

@ -5708,7 +5708,7 @@ enum {
Scheme_Object *scheme_get_run_cmd(void) Scheme_Object *scheme_get_run_cmd(void)
{ {
if (!run_cmd) { if (!run_cmd) {
return scheme_make_path("mzscheme"); return scheme_make_path("racket");
} }
return run_cmd; return run_cmd;
} }
@ -5738,7 +5738,7 @@ find_system_path(int argc, Scheme_Object **argv)
which = id_sys_dir; which = id_sys_dir;
else if (argv[0] == exec_file_symbol) { else if (argv[0] == exec_file_symbol) {
if (!exec_cmd) { if (!exec_cmd) {
return scheme_make_path("mzscheme"); return scheme_make_path("racket");
} }
return exec_cmd; return exec_cmd;
} else if (argv[0] == run_file_symbol) { } else if (argv[0] == run_file_symbol) {
@ -5798,11 +5798,11 @@ find_system_path(int argc, Scheme_Object **argv)
|| (which == id_addon_dir)) { || (which == id_addon_dir)) {
#if defined(OS_X) && !defined(XONX) #if defined(OS_X) && !defined(XONX)
if (which == id_addon_dir) if (which == id_addon_dir)
home_str = "~/Library/PLT Scheme/"; home_str = "~/Library/Racket/";
else else
home_str = "~/Library/Preferences/"; home_str = "~/Library/Preferences/";
#else #else
home_str = "~/.plt-scheme/"; home_str = "~/.racket/";
#endif #endif
} else { } else {
#if defined(OS_X) && !defined(XONX) #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] == '/'; ends_in_slash = (SCHEME_PATH_VAL(home))[SCHEME_PATH_LEN(home) - 1] == '/';
if (which == id_init_file) 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 (which == id_pref_file) {
#if defined(OS_X) && !defined(XONX) #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 #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 #endif
} }
} }
@ -5977,14 +5977,14 @@ find_system_path(int argc, Scheme_Object **argv)
if ((which == id_addon_dir) if ((which == id_addon_dir)
|| (which == id_pref_dir) || (which == id_pref_dir)
|| (which == id_pref_file)) { || (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; ends_in_slash = 0;
} }
if (which == id_init_file) 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) 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; return home;
} }
#endif #endif

11
src/racket/src/print.c
View File

@ -57,6 +57,7 @@ ROSYM Scheme_Object *syntax_symbol;
ROSYM Scheme_Object *quasisyntax_symbol; ROSYM Scheme_Object *quasisyntax_symbol;
ROSYM Scheme_Object *unsyntax_symbol; ROSYM Scheme_Object *unsyntax_symbol;
ROSYM Scheme_Object *unsyntax_splicing_symbol; ROSYM Scheme_Object *unsyntax_splicing_symbol;
ROSYM Scheme_Object *qq_ellipses;
/* Flag for debugging compiled code in printed form: */ /* Flag for debugging compiled code in printed form: */
#define NO_COMPACT 0 #define NO_COMPACT 0
@ -175,6 +176,7 @@ void scheme_init_print(Scheme_Env *env)
REGISTER_SO(quasisyntax_symbol); REGISTER_SO(quasisyntax_symbol);
REGISTER_SO(unsyntax_symbol); REGISTER_SO(unsyntax_symbol);
REGISTER_SO(unsyntax_splicing_symbol); REGISTER_SO(unsyntax_splicing_symbol);
REGISTER_SO(qq_ellipses);
quote_symbol = scheme_intern_symbol("quote"); quote_symbol = scheme_intern_symbol("quote");
quasiquote_symbol = scheme_intern_symbol("quasiquote"); quasiquote_symbol = scheme_intern_symbol("quasiquote");
unquote_symbol = scheme_intern_symbol("unquote"); unquote_symbol = scheme_intern_symbol("unquote");
@ -183,6 +185,7 @@ void scheme_init_print(Scheme_Env *env)
quasisyntax_symbol = scheme_intern_symbol("quasisyntax"); quasisyntax_symbol = scheme_intern_symbol("quasisyntax");
unsyntax_symbol = scheme_intern_symbol("unsyntax"); unsyntax_symbol = scheme_intern_symbol("unsyntax");
unsyntax_splicing_symbol = scheme_intern_symbol("unsyntax-splicing"); unsyntax_splicing_symbol = scheme_intern_symbol("unsyntax-splicing");
qq_ellipses = scheme_make_symbol("..."); /* uninterned */
#ifdef MZ_PRECISE_GC #ifdef MZ_PRECISE_GC
register_traversers(); register_traversers();
@ -1836,7 +1839,9 @@ print(Scheme_Object *obj, int notdisplay, int compact, Scheme_Hash_Table *ht,
const char *s; const char *s;
if (notdisplay >= 3) { if (notdisplay >= 3) {
if (notdisplay == 4) { if (SAME_OBJ(qq_ellipses, obj)) {
/* no quoting */
} else if (notdisplay == 4) {
if (SAME_OBJ(obj, unquote_symbol) if (SAME_OBJ(obj, unquote_symbol)
|| SAME_OBJ(obj, unquote_splicing_symbol)) || SAME_OBJ(obj, unquote_splicing_symbol))
print_utf8_string(pp, ",'", 0, 2); 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; Scheme_Object *vec, *prefab;
print_compact(pp, CPT_PREFAB); print_compact(pp, CPT_PREFAB);
prefab = ((Scheme_Structure *)obj)->stype->prefab_key; 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); SCHEME_VEC_ELS(vec)[0] = SCHEME_CDR(prefab);
print_vector(vec, notdisplay, compact, ht, mt, pp, 1); print_vector(vec, notdisplay, compact, ht, mt, pp, 1);
} else if (compact || !pp->print_unreadable) { } else if (compact || !pp->print_unreadable) {
@ -2171,7 +2176,7 @@ print(Scheme_Object *obj, int notdisplay, int compact, Scheme_Hash_Table *ht,
if (pb) { if (pb) {
Scheme_Object *vec, *prefab; Scheme_Object *vec, *prefab;
prefab = ((Scheme_Structure *)obj)->stype->prefab_key; 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) { if ((notdisplay >= 3) && !prefab) {
notdisplay = to_unquoted(pp, notdisplay); notdisplay = to_unquoted(pp, notdisplay);
vec = scheme_vector_to_list(vec); vec = scheme_vector_to_list(vec);