diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 6d9bc39c3e..ad02549294 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -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]