Author: autrijus Date: Sun Feb 26 01:35:45 2006 New Revision: 7875 Modified: doc/trunk/design/syn/S06.pod
Log: * S06: Explicit importation in q:code// from the :COMPILING scope using the q:code(:COMPILING<$x>)// form. * Also point out we can easily bind symbols at macro-run time, thanks to pseudo-package import in S11: require COMPILING <$x $y $z>; Modified: doc/trunk/design/syn/S06.pod ============================================================================== --- doc/trunk/design/syn/S06.pod (original) +++ doc/trunk/design/syn/S06.pod Sun Feb 26 01:35:45 2006 @@ -1865,7 +1865,7 @@ mechanism using the quote C<q:code>, followed by a block intended to represent an AST: - return q:code { say $a }; + return q:code { say "foo" }; Modifiers to the C<:code> adverb can modify the operation: @@ -1873,11 +1873,42 @@ :lang(Ruby) # Default :lang($?PARSER) :unquote<[: :]> # Default "triple rule" -Within a quasiquote, variable and function names resolve first of -all according to the lexical scope of the macro definition, and if -unrecognized in that scope, are assumed to be bound from the scope -of the macro call each time it is called. If they cannot be bound -from the scope of the macro call, a compile-time exception is thrown. +Within a quasiquote, variable and function names resolve according +to the lexical scope of the macro definition. Unrecognized symbols raise +errors when the macro is being compiled, I<not> when it's being used. + +To make a symbol resolve to the (partially compiled) scope of the macro +call, use the C<COMPILING::> pseudo-package: + + macro moose () { q:code { $COMPILING::x } } + + moose(); # macro-call-time error + my $x; + moose(); # resolves to 'my $x' + +If you want to mention symbols from the scope of the macro call, use the +import syntax as modifiers to C<:code>: + + :COMPILING<$x> # $x always refers to $x in caller's scope + :COMPILING # All free variables fallback to caller's scope + +If those symbols do not exist in the scope of the compiling scope, a +compile-time exception is thrown at macro call time. + +Similarly, in the macro body you may either refer to the C<$x> declared in the +scope of the macro call as C<$COMPILING::x>, or bind to them explicitly: + + my $x := $COMPILING::x; + +You may also use an import list to bind multiple symbols into the +macro's lexical scope: + + require COMPILING <$x $y $z>; + +Note that you need to use the run-time C<:=> and C<require> forms, not C<::=> +and C<use>, because the macro caller's compile-time is the macro's runtime. + +=head2 Splicing Bare AST variables (such as the arguments to the macro) may not be spliced directly into a quasiquote because they would be taken as