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

refine examples for require & provide

Browse Source 
svn: r14237
This commit is contained in:
Matthew Flatt 2009-03-23 16:30:29 +00:00
parent 29aa214cfe
commit 59988f5ca5
1 changed files with 125 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -13,11 +13,13 @@
scheme/package
scheme/splicing))
@(define require-eval (make-base-eval))
@(define syntax-eval
(lambda ()
(let ([the-eval (make-base-eval)])
(the-eval '(require (for-syntax scheme/base)))
the-eval)))
@(define meta-in-eval (syntax-eval))
@(define cvt (schemefont "CVT"))
@(define unquote-id (scheme unquote))
@ -202,11 +204,13 @@ be preserved in marshaled bytecode. See also
See also @secref["module-eval-model"] and @secref["mod-parse"].
@defexamples[#:eval (syntax-eval)
(module example-module scheme
(provide foo bar)
(define foo 2)
(define (bar x)
(+ x 1)))
(module duck scheme/base
(provide num-eggs quack)
(define num-eggs 2)
(define (quack n)
(unless (zero? n)
(printf "quack\n")
(quack (sub1 n)))))
]
@defform[(#%module-begin form ...)]{
@ -284,12 +288,6 @@ be different from the symbolic name of the originally exported
identifier. Each identifier also binds at a particular @tech{phase
level}.
A @scheme[require] scopes over all subsequent forms in @tech{top-level
contexts}, and all subsequent module top-level forms in a @tech{module
context} as well as all expression forms in a module. In both cases,
each @scheme[require-spec] scopes over all subsequent
@scheme[require-spec]s in them same @scheme[require] form.
The syntax of @scheme[require-spec] can be extended via
@scheme[define-require-syntax], but the
pre-defined forms are as follows.
@ -371,56 +369,34 @@ pre-defined forms are as follows.
binding that is not for @scheme[phase-level], where @scheme[#f] for
@scheme[phase-level] corresponds to the @tech{label phase level}.
This example only imports bindings at @tech{phase level} 1, the
transform phase.
The following example imports bindings only at @tech{phase level} 1,
the transform phase:
@defexamples[#:eval (syntax-eval)
(module test scheme
@interaction[#:eval meta-in-eval
(module nest scheme
(provide (for-syntax meta-eggs)
(for-meta 1 meta-chicks)
num-eggs)
(define-for-syntax meta-eggs 2)
(define-for-syntax meta-chicks 3)
(define num-eggs 2))
(provide (for-syntax meta-1a)
(for-meta 1 meta-1b)
meta-0)
(require (only-meta-in 1 'nest))
(define-for-syntax meta-1a 'a)
(define-for-syntax meta-1b 'b)
(define meta-0 2))
(define-syntax (desc stx)
(printf "~s ~s\n" meta-eggs meta-chicks)
#'(void))
(require (only-meta-in 1 'test))
(define-syntax bar
(lambda (stx)
(printf "~a\n" meta-1a)
(printf "~a\n" meta-1b)
#'1))
(bar)
meta-0
(desc)
num-eggs
]
This example only imports bindings at @tech{phase level} 0, the
The following example imports only bindings at @tech{phase level} 0, the
normal phase.
@defexamples[#:eval (syntax-eval)
(module test scheme
(provide (for-syntax meta-1a)
(for-meta 1 meta-1b)
meta-0)
(define-for-syntax meta-1a 'a)
(define-for-syntax meta-1b 'b)
(define meta-0 2))
(require (only-meta-in 0 'test))
(define-syntax bar
(lambda (stx)
(printf "~a\n" meta-1a)
(printf "~a\n" meta-1b)
#'1))
meta-0
(bar)
@interaction[#:eval meta-in-eval
(require (only-meta-in 0 'nest))
num-eggs
]}
@specsubform[#:literals (for-meta)
@ -431,23 +407,15 @@ pre-defined forms are as follows.
combination that involves @scheme[#f] produces @scheme[#f].
@defexamples[#:eval (syntax-eval)
(module test scheme
(provide foo)
(define foo 2))
(require (for-meta 0 'test))
foo
]}
@defexamples[#:eval (syntax-eval)
(module test scheme
(provide foo)
(define foo 2))
(require (for-meta 1 'test))
(define-syntax bar
(lambda (stx)
(printf "~a\n" foo)
#'1))
(bar)
(module nest scheme
(provide num-eggs)
(define num-eggs 2))
(require (for-meta 0 'nest))
num-eggs
(require (for-meta 1 'nest))
(define-syntax (roost stx)
(datum->syntax stx num-eggs))
(roost)
]}
@specsubform[#:literals (for-syntax)
@ -463,7 +431,10 @@ pre-defined forms are as follows.
@scheme[(for-meta #f require-spec ...)].}
@specsubform[derived-require-spec]{See @scheme[define-require-syntax]
for information on expanding the set of @scheme[require-spec] forms.}
for information on expanding the set of @scheme[require-spec]
forms. When multiple @scheme[require-spec]s are specified in a
@scheme[require], the bindings of each @scheme[require-spec] are
vsible for expanding later @scheme[require-spec]s.}
@guideintro["module-paths"]{module paths}
@ -530,8 +501,8 @@ corresponds to the default @tech{module name resolver}.
@tech{collection}, and @filepath{main.ss} is the library file name.
Example: require swindle
@defexamples[#:eval (syntax-eval)
(require (lib "swindle"))]}
@defexamples[#:eval require-eval
(eval:alts (require (lib "swindle")) (void))]}
@item{If a single @scheme[rel-string] is provided, and if it
consists of multiple @litchar{/}-separated elements, then each
@ -540,8 +511,8 @@ corresponds to the default @tech{module name resolver}.
no file suffix, @filepath{.ss} is added.
Example: require a file within the swindle collection
@defexamples[#:eval (syntax-eval)
(require (lib "swindle/turbo"))]}
@defexamples[#:eval require-eval
(eval:alts (require (lib "swindle/turbo")) (void))]}
@item{If a single @scheme[rel-string] is provided, and if it
consists of a single element @italic{with} a file suffix (i.e,
@ -550,8 +521,8 @@ corresponds to the default @tech{module name resolver}.
compatibility with older version of PLT Scheme.)
Example: require the tar module from mzlib
@defexamples[#:eval (syntax-eval)
(require (lib "tar.ss"))]}
@defexamples[#:eval require-eval
(eval:alts (require (lib "tar.ss")) (void))]}
@item{Otherwise, when multiple @scheme[rel-string]s are provided,
the first @scheme[rel-string] is effectively moved after the
@ -562,8 +533,8 @@ corresponds to the default @tech{module name resolver}.
with older version of PLT Scheme.)
Example: require the tar module from mzlib
@defexamples[#:eval (syntax-eval)
(require (lib "tar.ss" "mzlib"))]}
@defexamples[#:eval require-eval
(eval:alts (require (lib "tar.ss" "mzlib")) (void))]}
}}
@specsubform[id]{A shorthand for a @scheme[lib] form with a single
@ -571,14 +542,14 @@ corresponds to the default @tech{module name resolver}.
form of @scheme[id]. In addition to the constraints of a @scheme[lib]
@scheme[_rel-string], @scheme[id] must not contain @litchar{.}.
@defexamples[#:eval (syntax-eval)
(require scheme/tcp)]}
@examples[#:eval require-eval
(eval:alts (require scheme/tcp) (void))]}
@defsubform[(file string)]{Similar to the plain @scheme[rel-string]
case, but @scheme[string] is a path---possibly absolute---using the
current platform's path conventions and @scheme[expand-user-path].
@scheme[(require (file "~/tmp/x.ss"))]}
@examples[(eval:alts (require (file "~/tmp/x.ss")) (void))]}
@defsubform*[((planet id)
(planet string)
@ -638,27 +609,22 @@ corresponds to the default @tech{module name resolver}.
identifiers in a minor-version constraint are recognized
symbolically.
Example: Load main.ss file package foo owned by bar.
@scheme[(require (planet bar/foo))]
Example: Load major version 2 of main.ss file package foo owned by bar.
@scheme[(require (planet bar/foo:2))]
Example: Load major version 2 and minor version 5 of main.ss file package foo owned by bar.
@scheme[(require (planet bar/foo:2:5))]
Example: Load major version 2 and minor version 5 of buz.ss file package foo owned by bar.
@scheme[(require (planet bar/foo:2:5/buz))]}
@examples[
(code:comment #, @t{@filepath{main.ss} in package @filepath{farm} by @filepath{mcdonald}:})
(eval:alts (require (planet mcdonald/farm)) (void))
(code:comment #, @t{@filepath{main.ss} in version >= 2.0 of package @filepath{farm} by @filepath{mcdonald}:})
(eval:alts (require (planet mcdonald/farm:2)) (void))
(code:comment #, @t{@filepath{main.ss} in version >= 2.5 of package @filepath{farm} by @filepath{mcdonald}:})
(eval:alts (require (planet mcdonald/farm:2:5)) (void))
(code:comment #, @t{@filepath{duck.ss} in version >= 2.5 of package @filepath{farm} by @filepath{mcdonald}:})
(eval:alts (require (planet mcdonald/farm:2:5/duck)) (void))
]}
No identifier can be bound multiple times in a given @tech{phase
level} by an import, unless all of the bindings refer to the same
original definition in the same module. In a @tech{module context},
an identifier can be either imported or defined for a given
@tech{phase level}, but not both.}
@tech{phase level}, but not both.}}
@guideintro["module-provide"]{@scheme[provide]}
@ -704,11 +670,11 @@ follows.
ambiguous).
@defexamples[#:eval (syntax-eval)
(module test scheme
(provide foo)
(define foo 2))
(require 'test)
foo
(module nest scheme
(provide num-eggs)
(define num-eggs 2))
(require 'nest)
num-eggs
]
If @scheme[id] has a transformer binding to a @tech{rename
@ -730,11 +696,11 @@ follows.
@scheme[(all-defined-out)] form was introduced at the same time.
@defexamples[#:eval (syntax-eval)
(module test scheme
(module nest scheme
(provide (all-defined-out))
(define foo 2))
(require 'test)
foo
(define num-eggs 2))
(require 'nest)
num-eggs
]}
@defsubform[(all-from-out module-path ...)]{ Exports all identifiers
@ -749,14 +715,14 @@ follows.
@scheme[module-path] was introduced at the same time.
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide foo)
(define foo 2))
(module b scheme
(require 'a)
(provide (all-from-out 'a)))
(require 'b)
foo
(module nest scheme
(provide num-eggs)
(define num-eggs 2))
(module hen-house scheme
(require 'nest)
(provide (all-from-out 'nest)))
(require 'hen-house)
num-eggs
]}
@defsubform[(rename-out [orig-id export-id] ...)]{ Exports each
@ -765,12 +731,12 @@ follows.
@scheme[export-id] instead @scheme[orig-d].
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (rename-out (foo myfoo)))
(define foo 2))
(require 'a)
foo
myfoo
(module nest scheme
(provide (rename-out [count num-eggs]))
(define count 2))
(require 'nest)
num-eggs
count
]}
@defsubform[(except-out provide-spec provide-spec ...)]{ Like the
@ -781,14 +747,14 @@ follows.
@scheme[provide-spec]s is ignored; only the bindings are used.
@defexamples[#:eval (syntax-eval)
(module a scheme
(module nest scheme
(provide (except-out (all-defined-out)
bar))
(define foo 2)
(define bar 3))
(require 'a)
foo
bar
num-chicks))
(define num-eggs 2)
(define num-chicks 3))
(require 'nest)
num-eggs
num-chicks
]}
@defsubform[(prefix-out prefix-id provide-spec)]{
@ -796,11 +762,11 @@ follows.
@scheme[provide-spec] prefixed with @scheme[prefix-id].
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (prefix-out f: foo))
(define foo 2))
(require 'a)
f:foo
(module nest scheme
(provide (prefix-out chicken: num-eggs))
(define num-eggs 2))
(require 'nest)
chicken:num-eggs
]}
@defsubform[(struct-out id)]{Exports the bindings associated with a
@ -818,28 +784,24 @@ follows.
included by @scheme[struct-out] for export.
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (struct-out foo))
(define-struct foo (a b c)))
(require 'a)
make-foo
foo-a
foo-b
foo-c
foo?
(module nest scheme
(provide (struct-out egg))
(define-struct egg (color wt)))
(require 'nest)
(egg-color (make-egg 'blue 10))
]}
@defsubform[(combine-out provide-spec ...)]{ The union of the
@scheme[provide-spec]s.
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (combine-out foo bar))
(define foo 2)
(define bar 1))
(require 'a)
foo
bar
(module nest scheme
(provide (combine-out num-eggs num-chicks))
(define num-eggs 2)
(define num-chicks 1))
(require 'nest)
num-eggs
num-chicks
]}
@defsubform[(protect-out provide-spec ...)]{ Like the union of the
@ -847,31 +809,19 @@ follows.
@secref["modprotect"]. The @scheme[provide-spec] must specify only
bindings that are defined within the exporting module.
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (protect-out foo))
(define foo 1))
@examples[#:eval (syntax-eval)
(module nest scheme
(provide num-eggs (protect-out num-chicks))
(define num-eggs 2)
(define num-chicks 3))
(define weak-inspector (make-inspector (current-code-inspector)))
(define (weak-eval x)
(parameterize ([current-code-inspector weak-inspector])
(eval x)))
(require 'a)
foo
(weak-eval 'foo)
]
Note that @scheme[require] works within eval as well.
@defexamples[#:eval (syntax-eval)
(module a scheme
(provide (protect-out foo))
(define foo 1))
(define weak-inspector (make-inspector (current-code-inspector)))
(define (weak-eval x)
(parameterize ([current-code-inspector weak-inspector])
(eval x)))
(weak-eval '(require 'a))
foo
(weak-eval 'foo)
(require 'nest)
(list num-eggs num-chicks)
(weak-eval 'num-eggs)
(weak-eval 'num-chicks)
]}
@specsubform[#:literals (for-meta)
@ -1020,21 +970,7 @@ context of the @scheme[phaseless-spec] form.}
@note-lib-only[scheme/require]
The following forms support more complex selection and manipulation of
sets of imported identifiers. Note that a @scheme[require] form is
expanded before it is used, which means that requiring the library
itself should be a separate form. For example, use
@schemeblock[
(require scheme/require)
(require (matching-identifiers-in #rx"foo" "foo.ss"))
]
instead of
@schemeblock[
(require scheme/require
(matching-identifiers-in #rx"foo" "foo.ss"))
]
sets of imported identifiers.
@defform[(matching-identifiers-in regexp require-spec)]{ Like
@scheme[require-spec], but including only imports whose names match
@ -2364,3 +2300,7 @@ than a precise prose description:
[(nest ([form forms ...] . more) body0 body ...)
(form forms ... (nest more body0 body ...))]))
]}
@close-eval[require-eval]
@close-eval[meta-in-eval]