1#lang scribble/doc
2@(require "mz.rkt" (for-label racket/splicing racket/stxparam racket/local))
3
4@(define splice-eval (make-base-eval))
5@examples[#:hidden #:eval splice-eval (require racket/splicing
6                                               racket/stxparam
7                                               (for-syntax racket/base))]
8
9@title[#:tag "splicing"]{Local Binding with Splicing Body}
10
11@note-lib-only[racket/splicing]
12
13@deftogether[(
14@defidform[splicing-let]
15@defidform[splicing-letrec]
16@defidform[splicing-let-values]
17@defidform[splicing-letrec-values]
18@defidform[splicing-let-syntax]
19@defidform[splicing-letrec-syntax]
20@defidform[splicing-let-syntaxes]
21@defidform[splicing-letrec-syntaxes]
22@defidform[splicing-letrec-syntaxes+values]
23@defidform[splicing-local]
24@defidform[splicing-parameterize]
25)]{
26
27Like @racket[let], @racket[letrec], @racket[let-values],
28@racket[letrec-values], @racket[let-syntax], @racket[letrec-syntax],
29@racket[let-syntaxes], @racket[letrec-syntaxes],
30@racket[letrec-syntaxes+values], @racket[local], and
31@racket[parameterize], except that in a definition context, the body
32forms are spliced into the enclosing definition context (in the same
33way as for @racket[begin]).
34
35@examples[
36#:eval splice-eval
37(splicing-let-syntax ([one (lambda (stx) #'1)])
38  (define o one))
39o
40(eval:error one)
41]
42
43When a splicing binding form occurs in a @tech{top-level context} or
44@tech{module context}, its local bindings are treated similarly to
45definitions. In particular, syntax bindings are
46evaluated every time the module is @tech{visit}ed, instead of only
47once during compilation as in @racket[let-syntax], etc.
48
49@examples[
50#:eval splice-eval
51(eval:error
52 (splicing-letrec ([x bad]
53                   [bad 1])
54   x))]
55
56If a definition within a splicing form is intended to be local to the
57splicing body, then the identifier should have a true value for the
58@racket['definition-intended-as-local] @tech{syntax property}. For
59example, @racket[splicing-let] itself adds the property to
60locally-bound identifiers as it expands to a sequence of definitions,
61so that nesting @racket[splicing-let] within a splicing form works as
62expected (without any ambiguous bindings).
63
64@history[
65 #:changed "6.12.0.2" @elem{Added @racket[splicing-parameterize].}]}
66
67
68@defidform[splicing-syntax-parameterize]{
69
70Like @racket[syntax-parameterize], except that in a definition context, the body
71forms are spliced into the enclosing definition context (in the same way as for
72@racket[begin]). In a definition context, the body of
73@racket[splicing-syntax-parameterize] can be empty.
74
75Note that @tech{require transformers} and @tech{provide transformers} are not
76affected by syntax parameterization.  While all uses of @racket[require] and
77@racket[provide] will be spliced into the enclosing context, derived import or
78export specifications will expand as if they had not been inside of the
79@racket[splicing-syntax-parameterize].
80
81Additionally, @tech{submodules} defined with @racket[module*] that specify
82@racket[#f] in place of a @tech{module path} @emph{are} affected by syntax
83parameterization, but other submodules (those defined with @racket[module] or
84@racket[module*] with a @tech{module path}) are @emph{not}.
85
86@examples[
87#:eval splice-eval
88(define-syntax-parameter place (lambda (stx) #'"Kansas"))
89(define-syntax-rule (where) `(at ,(place)))
90(where)
91(splicing-syntax-parameterize ([place (lambda (stx) #'"Oz")])
92  (define here (where)))
93here
94]
95
96@history[
97 #:changed "6.11.0.1"
98 @elem{Modified to syntax parameterize @racket[module*] submodules that
99       specify @racket[#f] in place of a @tech{module path}.}]}
100
101@; ----------------------------------------------------------------------
102
103@close-eval[splice-eval]
104