From 766308725436fe4eee40d38ec082c6897596468d Mon Sep 17 00:00:00 2001 From: Jon Rafkind Date: Fri, 20 Feb 2009 21:05:08 +0000 Subject: [PATCH] add examples for require forms svn: r13754 --- collects/scribblings/reference/syntax.scrbl | 124 ++++++++++++++++++-- 1 file changed, 111 insertions(+), 13 deletions(-) diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index baf5eda366..a246ed8739 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -14,9 +14,10 @@ scheme/splicing)) @(define syntax-eval - (let ([the-eval (make-base-eval)]) - (the-eval '(require (for-syntax scheme/base))) - the-eval)) + (lambda () + (let ([the-eval (make-base-eval)]) + (the-eval '(require (for-syntax scheme/base))) + the-eval))) @(define cvt (schemefont "CVT")) @(define unquote-id (scheme unquote)) @@ -200,6 +201,14 @@ 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))) +] + @defform[(#%module-begin form ...)]{ Legal only in a @tech{module begin context}, and handled by the @@ -290,33 +299,122 @@ pre-defined forms are as follows. @scheme[_id] or as @scheme[_orig-id] in @scheme[[_orig-id _bind-id]]. If the @scheme[_id] or @scheme[_orig-id] of any @scheme[id-maybe-renamed] is not in the set that @scheme[require-spec] describes, a syntax - error is reported.} + error is reported. + + @defexamples[#:eval (syntax-eval) + (require (only-in scheme/tcp + tcp-listen + (tcp-accept my-accept))) + tcp-listen + my-accept + tcp-accept + ]} @defsubform[(except-in require-spec id ...)]{ Like @scheme[require-spec], but omitting those imports for which @scheme[id]s are the identifiers to bind; if any @scheme[id] is not in the set that @scheme[require-spec] describes, a syntax error is - reported.} + reported. + + @defexamples[#:eval (syntax-eval) + (require (except-in scheme/tcp + tcp-listen)) + tcp-accept + tcp-listen + ]} @defsubform[(prefix-in prefix-id require-spec)]{ Like @scheme[require-spec], but adjusting each identifier to be bound by prefixing it with @scheme[prefix-id]. The lexical context of the @scheme[prefix-id] is ignored, and instead preserved from the - identifiers before prefixing.} + identifiers before prefixing. + + @defexamples[#:eval (syntax-eval) + (require (prefix-in tcp: scheme/tcp)) + tcp:tcp-accept + tcp:tcp-listen + ]} @defsubform[(rename-in require-spec [orig-id bind-id] ...)]{ Like @scheme[require-spec], but replacing the identifier to bind @scheme[orig-id] with @scheme[bind-id]; if any @scheme[orig-id] is not in the set that @scheme[require-spec] - describes, a syntax error is reported.} + describes, a syntax error is reported. + + @defexamples[#:eval (syntax-eval) + (require (rename-in scheme/tcp + (tcp-accept accept) + (tcp-listen listen))) + accept + listen + ]} @defsubform[(combine-in require-spec ...)]{ - The union of the @scheme[require-spec]s.} + The union of the @scheme[require-spec]s. + + @defexamples[#:eval (syntax-eval) + (require (combine-in (only-in scheme/tcp tcp-accept) + (only-in scheme/tcp tcp-listen))) + tcp-accept + tcp-listen + ]} @defsubform[(only-meta-in phase-level require-spec ...)]{ Like the combination of @scheme[require-spec]s, but removing any binding that is not for @scheme[phase-level], where @scheme[#f] for - @scheme[phase-level] corresponds to the @tech{label phase level}.} + @scheme[phase-level] corresponds to the @tech{label phase level}. + + This example only imports bindings at @tech{phase level} 1, the + transform 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 1 'test)) + + (define-syntax bar + (lambda (stx) + (printf "~a\n" meta-1a) + (printf "~a\n" meta-1b) + #'1)) + + (bar) + meta-0 + ] + + This example only imports 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) + ]} @specsubform[#:literals (for-meta) (for-meta phase-level require-spec ...)]{Like the combination of @@ -1607,7 +1705,7 @@ The second form is a shorthand the same as for @scheme[define]; it expands to a definition of the first form where the @scheme[expr] is a @scheme[lambda] form.} -@defexamples[#:eval syntax-eval +@defexamples[#:eval (syntax-eval) (define-syntax foo (syntax-rules () ((_ a ...) @@ -1630,7 +1728,7 @@ for each @scheme[id]. The @scheme[expr] should produce as many values as @scheme[id]s, and each value is bound to the corresponding @scheme[id]. } -@defexamples[#:eval syntax-eval +@defexamples[#:eval (syntax-eval) (define-syntaxes (foo1 foo2 foo3) (let ([transformer1 (lambda (syntax-object) (syntax-case syntax-object () @@ -1659,7 +1757,7 @@ expression for the binding is also at @tech{phase level} 1. (See Evaluation of @scheme[expr] side is @scheme[parameterize]d to set @scheme[current-namespace] as in @scheme[let-syntax].} -@defexamples[#:eval syntax-eval +@defexamples[#:eval (syntax-eval) (define-for-syntax foo 2) (define-syntax bar (lambda (syntax-object) @@ -1678,7 +1776,7 @@ Like @scheme[define-for-syntax], but @scheme[expr] must produce as many values as supplied @scheme[id]s, and all of the @scheme[id]s are bound (at @tech{phase level} 1).} -@defexamples[#:eval syntax-eval +@defexamples[#:eval (syntax-eval) (define-values-for-syntax (foo1 foo2) (values 1 2)) (define-syntax (bar syntax-object) (printf "foo1 is ~a foo2 is ~a\n" foo1 foo2)