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/bool
racket/local
racket/nest
(for-syntax racket/base))
(provide (all-from-out racket/contract
@ -50,6 +49,5 @@
racket/cmdline
racket/promise
racket/bool
racket/local
racket/nest)
racket/local)
(for-syntax (all-from-out racket/base)))

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

30
collects/scheme/nest.rkt
View File

@ -1,2 +1,28 @@
#lang scheme/private/provider
racket/nest
#lang scheme/base
(provide nest)
;; A form that makes it easy to combine many "right-drifting" nested
;; expressions into a single one, sort of like a generalized version of the `*'
;; from `let*' and similar forms.
(define-syntax nest
(syntax-rules ()
[(nest () body0 body ...)
(let () body0 body ...)]
;; this allows putting definitions in the body
[(nest ([form forms ...]) body0 body ...)
(form forms ... (let () body0 body ...))]
[(nest ([form forms ...] . more) body0 body ...)
(form forms ... (nest more body0 body ...))]))
;; using this instead will allow splicing body expressions in the last form
;; whatever it happens to be, which can be (ab)used in strange ways
#;
(define-syntax nest
(syntax-rules ()
[(nest () body ...)
(begin body ...)]
[(nest ([form forms ...]) body ...)
(form forms ... body ...)]
[(nest ([form forms ...] . more) body ...)
(form forms ... (nest more body ...))]))

6
collects/scribble/racket.ss
View File

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

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

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

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

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

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

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

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

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

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

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
event has a level of importance, and a @tech{log receiver} subscribes to
logging events at a certain level of importance and higher. The
levels, in decreasing order of importance, are @scheme['fatal],
@scheme['error], @scheme['warning], @scheme['info], and
@scheme['debug].
levels, in decreasing order of importance, are @racket['fatal],
@racket['error], @racket['warning], @racket['info], and
@racket['debug].
To help organize logged events, @tech{loggers} can be named and
hierarchical. Every event reported to a logger is also propagated to
@ -19,9 +19,9 @@ its parent (if any), but the event message is prefixed with the name
(if any) of the logger to which is was originally reported. A logger
is not required to have a parent or name.
On start-up, PLT Scheme creates an initial logger that is used to
On start-up, Racket creates an initial logger that is used to
record events from the core run-time system. For example, an
@scheme['info] event is reported for each garbage collection (see
@racket['info] event is reported for each garbage collection (see
@secref["gc-model"]). For this initial logger, two log receivers are
also created: one that writes events to the process's original error
output port, and one that writes events to the system log. The level
@ -35,10 +35,10 @@ through environment variables:
defined and is not overridden by a command-line flag, it
determines the level of the @tech{log receiver} that propagates
events to the original error port. The environment variable's value
should be @scheme["none"], @scheme["fatal"], @scheme["error"],
@scheme["warning"], @scheme["info"], or @scheme["debug"].
should be @racket["none"], @racket["fatal"], @racket["error"],
@racket["warning"], @racket["info"], or @racket["debug"].
The default is @scheme["error"].}
The default is @racket["error"].}
@item{If the @indexed-envvar{PLTSYSLOG} environment variable is
defined and is not overridden by a command-line flag, it
@ -46,17 +46,17 @@ through environment variables:
events to the system log. The possible values are the
same as for @envvar{PLTSYSLOG}.
The default is @scheme["none"] for Unix or @scheme["error"] for
The default is @racket["none"] for Unix or @racket["error"] for
Windows and Mac OS X.}
]
The @scheme[current-logger] @tech{parameter} determines the
The @racket[current-logger] @tech{parameter} determines the
@deftech{current logger} that is used by forms such as
@scheme[log-warning]. On start-up, the initial value of this parameter
@racket[log-warning]. On start-up, the initial value of this parameter
is the initial logger. The run-time system sometimes uses the current
logger to report events. For example, the bytecode compiler sometimes
reports @scheme['warning] events when it detects an expression that
reports @racket['warning] events when it detects an expression that
would produce a run-time error if evaluated.
@; ----------------------------------------
@ -64,7 +64,7 @@ would produce a run-time error if evaluated.
@defproc[(logger? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{logger}, @scheme[#f]
Returns @racket[#t] if @racket[v] is a @tech{logger}, @racket[#f]
otherwise.}
@ -77,7 +77,7 @@ Creates a new logger with an optional name and parent.}
@defproc[(logger-name [logger logger?]) (or/c symbol? #f)]{
Reports @scheme[logger]'s name, if any.}
Reports @racket[logger]'s name, if any.}
@defparam[current-logger logger logger?]{
@ -93,13 +93,13 @@ A @tech{parameter} that determines the @tech{current logger}.}
[data any/c])
void?]{
Reports an event to @scheme[logger], which in turn distributes the
information to any @tech{log receivers} attached to @scheme[logger] or
its ancestors that are interested in events at @scheme[level] or
Reports an event to @racket[logger], which in turn distributes the
information to any @tech{log receivers} attached to @racket[logger] or
its ancestors that are interested in events at @racket[level] or
higher.
If @scheme[logger] has a name, then @scheme[message] is prefixed with
the logger's name followed by @scheme[": "] before it is sent to
If @racket[logger] has a name, then @racket[message] is prefixed with
the logger's name followed by @racket[": "] before it is sent to
receivers.}
@ -107,13 +107,13 @@ receivers.}
[level (or/c 'fatal 'error 'warning 'info 'debug)])
boolean?]{
Reports whether any @tech{log receiver} attached to @scheme[logger] or
one of its ancestors is interested in @scheme[level] events (or
Reports whether any @tech{log receiver} attached to @racket[logger] or
one of its ancestors is interested in @racket[level] events (or
potentially lower). Use this function to avoid work generating an
event for @scheme[log-message] if no receiver is interested in the
information; this shortcut is built into @scheme[log-fatal],
@scheme[log-error], @scheme[log-warning], @scheme[log-info], and
@scheme[log-debug], however, so it should not be used with those
event for @racket[log-message] if no receiver is interested in the
information; this shortcut is built into @racket[log-fatal],
@racket[log-error], @racket[log-warning], @racket[log-info], and
@racket[log-debug], however, so it should not be used with those
forms.
The result of this function can change if a garbage collection
@ -129,23 +129,23 @@ that any event information it receives will never become accessible).}
)]{
Log an event with the @tech{current logger}, evaluating
@scheme[string-expr] only if the logger has receivers that are
@racket[string-expr] only if the logger has receivers that are
interested in the event. In addition, the current continuation's
@tech{continuation marks} are sent to the logger with the message
string.
For each @schemekeywordfont{log-}@scheme[_level],
For each @racketkeywordfont{log-}@racket[_level],
@schemeblock[
(@#,schemekeywordfont{log-}_level string-expr)
@racketblock[
(@#,racketkeywordfont{log-}_level string-expr)
]
is equivalent to
@schemeblock[
@racketblock[
(let ([l (current-logger)])
(when (log-level? l '@#,scheme[_level])
(log-message l '@#,scheme[_level] string-expr
(when (log-level? l '@#,racket[_level])
(log-message l '@#,racket[_level] string-expr
(current-continuation-marks))))
]}
@ -154,7 +154,7 @@ is equivalent to
@defproc[(log-receiver? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{log receiver}, @scheme[#f]
Returns @racket[#t] if @racket[v] is a @tech{log receiver}, @racket[#f]
otherwise.}
@defproc[(make-log-receiver [logger logger?]
@ -162,13 +162,13 @@ otherwise.}
log-receiver?]{
Creates a @tech{log receiver} to receive events of importance
@scheme[level] and higher as reported to @scheme[logger] and its
@racket[level] and higher as reported to @racket[logger] and its
descendants.
A @tech{log receiver} is a @tech{synchronizable event}. It becomes
ready as an @tech{synchronizable event} when a logging event is
received, so use @scheme[sync] to receive an logged event. The
received, so use @racket[sync] to receive an logged event. The
@tech{log receiver}'s synchronization value is a vector containing
three values: the level of the event as a symbol, an immutable string
for the event message, and an arbitrary value that was supplied as the
last argument to @scheme[log-message] when the event was logged.}
last argument to @racket[log-message] when the event was logged.}

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

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

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

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

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

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

@ -7,20 +7,20 @@
@section-index["column numbers"]
@section-index["port positions"]
By default, Scheme keeps track of the @deftech{position} in a port as
By default, Racket keeps track of the @deftech{position} in a port as
the number of bytes that have been read from or written to any port
(independent of the read/write position, which is accessed or changed
with @scheme[file-position]). Optionally, however, Scheme can track
with @racket[file-position]). Optionally, however, Racket can track
the position in terms of characters (after UTF-8 decoding), instead of
bytes, and it can track @deftech{line locations} and @deftech{column
locations}; this optional tracking must be specifically enabled for a
port via @scheme[port-count-lines!] or the
@scheme[port-count-lines-enabled] parameter. Position, line, and
column locations for a port are used by @scheme[read-syntax] and
@scheme[read-honu-syntax]. Position and line locations are numbered
port via @racket[port-count-lines!] or the
@racket[port-count-lines-enabled] parameter. Position, line, and
column locations for a port are used by @racket[read-syntax] and
@racket[read-honu-syntax]. Position and line locations are numbered
from @math{1}; column locations are numbered from @math{0}.
When counting lines, Scheme treats linefeed, return, and
When counting lines, Racket treats linefeed, return, and
return-linefeed combinations as a line terminator and as a single
position (on all platforms). Each tab advances the column count to one
before the next multiple of @math{8}. When a sequence of bytes in the
@ -45,7 +45,7 @@ position only when line and column counting is enabled.
Turns on line and column counting for a port. Counting can be turned
on at any time, though generally it is turned on before any data is
read from or written to a port. When a port is created, if the value
of the @scheme[port-count-lines-enabled] parameter is true, then line
of the @racket[port-count-lines-enabled] parameter is true, then line
counting is automatically enabled for the port. Line counting cannot
be disabled for a port after it is enabled.}
@ -54,12 +54,12 @@ be disabled for a port after it is enabled.}
(or/c exact-nonnegative-integer? #f)
(or/c exact-positive-integer? #f))]{
Returns three values: an integer or @scheme[#f] for the line number of
the next read/written item, an integer or @scheme[#f] for the next
item's column, and an integer or @scheme[#f] for the next item's
Returns three values: an integer or @racket[#f] for the line number of
the next read/written item, an integer or @racket[#f] for the next
item's column, and an integer or @racket[#f] for the next item's
position. The next column and position normally increases as bytes are
read from or written to the port, but if line/character counting is
enabled for @scheme[port], the column and position results can
enabled for @racket[port], the column and position results can
decrease after reading or writing a byte that ends a UTF-8 encoding
sequence.}
@ -67,5 +67,5 @@ sequence.}
A parameter that determines whether line counting is enabled
automatically for newly created ports. The default value is
@scheme[#f].}
@racket[#f].}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@ -9,7 +9,6 @@
make-provide-transformer)
racket/provide-syntax
racket/provide
racket/nest
racket/package
racket/splicing
racket/runtime-path))
@ -2414,54 +2413,6 @@ provides a hook to control interactive evaluation through
@;------------------------------------------------------------------------
@include-section["package.scrbl"]
@;------------------------------------------------------------------------
@section[#:tag "nest"]{Flattening Syntactic Sequences: @racket[nest]}
@note-lib[racket/nest]
@defform[(nest ([datum ...+] ...) body ...+)]{
Combines nested expressions that syntactically drift to the right into
a more linear textual format, much in the same way that @racket[let*]
linearizes a sequence of nested @racket[let] expressions.
For example,
@racketblock[
(nest ([let ([x 10]
[y 6])]
[with-handlers ([exn:fail? (lambda (x) 15)])]
[parameterize ([current-output-port (current-error-port)])]
[let-values ([(d r) (quotient/remainder x y)])])
(display (+ d r)))
]
is equivalent to
@racketblock[
(let ([x 10]
[y 6])
(with-handlers ([exn:fail? (lambda (x) 15)])
(parameterize ([current-output-port (current-error-port)])
(let-values ([(d r) (quotient/remainder x y)])
(display (+ d r))))))
]
The @racket[nest] form is unusual in that it has no semantics apart
from its expansion, and its implementation is easier to understand
than a precise prose description:
@racketblock[
(define-syntax nest
(syntax-rules ()
[(nest () body0 body ...)
(let () body0 body ...)]
[(nest ([form forms ...]) body0 body ...)
(form forms ... (let () body0 body ...))]
[(nest ([form forms ...] . more) body0 body ...)
(form forms ... (nest more body0 body ...))]))
]}
@close-eval[require-eval]
@close-eval[meta-in-eval]

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
control the amount of CPU allocated to a set of threads. Every thread
belongs to a thread group, which is determined by the
@scheme[current-thread-group] parameter when the thread is
@racket[current-thread-group] parameter when the thread is
created. Thread groups and custodians (see @secref["custodians"])
are independent.
The root thread group receives all of the CPU that the operating
system gives Scheme. Every thread or nested group in a particular
system gives Racket. Every thread or nested group in a particular
thread group receives equal allocation of the CPU (a portion of the
group's access), although a thread may relinquish part of its
allocation by sleeping or synchronizing with other processes.
@ -21,12 +21,12 @@ allocation by sleeping or synchronizing with other processes.
@defproc[(make-thread-group [group thread-group? (current-thread-group)])
thread-group?]{
Creates a new thread group that belongs to @scheme[group].}
Creates a new thread group that belongs to @racket[group].}
@defproc[(thread-group? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a thread group value, @scheme[#f]
Returns @racket[#t] if @racket[v] is a thread group value, @racket[#f]
otherwise.}

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

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

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

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

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

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

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

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

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

@ -34,8 +34,9 @@ old name.
@table-of-contents[]
@compat-except[scheme racket]{, except that @schememodname[racket]'s
@scheme[struct] is not exported, and a @|unit-struct| from
@schememodname[scheme/unit] is exported, instead}
@scheme[struct] is not exported, the @|unit-struct| from
@schememodname[scheme/unit] is exported, @schememodname[scheme/set]
is not re-exported, and @schememodname[scheme/nest] is re-exported}
@compat-except[scheme/base racket/base]{, except that
@schememodname[racket]'s @scheme[struct] is not exported, and
@ -111,7 +112,57 @@ must occur after all the @scheme[provide*] forms to which it refers.}
@compat[scheme/match racket/match]
@compat[scheme/math racket/math]
@compat[scheme/mpair racket/mpair]
@compat[scheme/nest racket/nest]
@;------------------------------------------------------------------------
@section[#:tag "nest"]{schememodname[scheme/nest]}
@defmodule[scheme/nest]
@defform[(nest ([datum ...+] ...) body ...+)]{
Combines nested expressions that syntactically drift to the right into
a more linear textual format, much in the same way that @racket[let*]
linearizes a sequence of nested @racket[let] expressions.
For example,
@racketblock[
(nest ([let ([x 10]
[y 6])]
[with-handlers ([exn:fail? (lambda (x) 15)])]
[parameterize ([current-output-port (current-error-port)])]
[let-values ([(d r) (quotient/remainder x y)])])
(display (+ d r)))
]
is equivalent to
@racketblock[
(let ([x 10]
[y 6])
(with-handlers ([exn:fail? (lambda (x) 15)])
(parameterize ([current-output-port (current-error-port)])
(let-values ([(d r) (quotient/remainder x y)])
(display (+ d r))))))
]
The @racket[nest] form is unusual in that it has no semantics apart
from its expansion, and its implementation is easier to understand
than a precise prose description:
@racketblock[
(define-syntax nest
(syntax-rules ()
[(nest () body0 body ...)
(let () body0 body ...)]
[(nest ([form forms ...]) body0 body ...)
(form forms ... (let () body0 body ...))]
[(nest ([form forms ...] . more) body0 body ...)
(form forms ... (nest more body0 body ...))]))
]}
@; ----------------------------------------
@compat[scheme/package racket/package]
@compat[scheme/path racket/path]
@compat[scheme/port racket/port]

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

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

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

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