This file was automatically generated from http://svn.pugscode.org/pugs/docs/Perl6/API/macros.pod on Wed Jun 6 22:16:47 2007 GMT, revision 16639.
Macros in Perl have access to the raw, just-parsed representation of
the program through their parameters. This representation is called
the AST. The AST is documented in full elsewhere, but this document
is written from the perspective of the macro itself, and demonstrates
the major components of the AST that must be in place for typical
macros to function.
A macro definition looks like this:
macro fizzle(...) { ... }
Within the parameter list, any parameters can be defined, but they will
always be of type AST, some sub-type of AST or plain scalars.
An invocant may be declared. If so, it will be the $/ object that
contains the macro invocation itself, and thus contains all state
relevant to the macro.
A macro can have an operator type:
macro quote:<q> (...) { ... }
If it does, the operator type will constrain the parameters (if any) that are available to the macro, and a mis-match between the operator type and the parameter count will generate a compile-time error.
Macros can be defined for each of the following operator types:
Expression node.
[ Note: notice camel-casing of LiteralString. Is that what was intended? -ajs ]
Quote macros take a single LiteralString node. Backslash escaping
is performed only for the balancing quote terminator. Should some other
sort of parsing be required, use the "is parsed" trait.
Expression parameter.
Expression parameters.
Expression node) is found before the macro name in the
program text.
Expression as a parameter.
Value. The
second is an Expression that comes inside of the circumfix delimeters.
Pad node which contains the information
about the variable being declared.
Statement_controls are like if or while, and take an Expression
and a Block.
[ Question: How is elsif/else handled? Are they named as part of the macro somehow, or must any elsif block ever be called "elsif"? -ajs ]
Statement and
a expression.
All of these macro types take three paramters: a Expression for
the LHS, an InfixOperator node for the operator that it is modifying,
and an Expression for the RHS.
[ Question: infix_postfix_meta_operator is designed for defining '=' which will take an LValue for its first parameter, but not all such operators will be for assignment, potentially. Again, this brings up the question of multi dispatch on AST node types. Is that what's intended, or should macro operator types be richer? -ajs ]
LValue and a
PostfixOperator as parameters.
PrefixOperator
and an LValue as parameters.
Infix_circumfix_meta_operator macros take an InfixOperator and
an Expression as parameters.
[ Question: What about sub, is that a statement_control? What about use? Is that just a list op that does its thing at run-time? -ajs ]
ASTs can be treated much the same as any rule state object. They
can be indexed like a hash to extract their match terms (in this case,
subrule names that match AST nodes). However, they also carry state
information about the file being parsed.
[ Question: how is that state information extracted? Is there a method that can be called to get line number for example? -ajs ]
Expressions are the most often-seen element of a macro's parameter list. Expressions
An Expression is either a Literal, a LValue (Variable/Apply/Call), or one of the special forms (Binding/Assignment). It can be tested like so:
macro debug(*@exprs) {
for @exprs -> $expr {
if exists $expr<Literal> {
...
} elsif exists $expr<LValue> {
...
} elsif exists $expr<Binding> or exists $expr<Assignment> {
...
} else {
die "Unknown Expression type '$expr'\n";
}
}
}
But in many cases, such a test is not required, as Expressions are so universally useful:
use AST::Tools :all;
macro debug(*@exprs) {
q:code{ say {{{ astlist(@exprs) }}} };
}
[ Question: we need some tools for constructing AST nodes from other AST nodes. One of the most obvious to me is the above, but my name for it ("astlist") is just a suggestion. It's probably exported by something like AST::Tools -ajs ]
[ Question: Another way to do that would be to have a generic AST initializer so that this worked: q:code{ say {{{ AST.new('List',@exprs) }}} }; which might make more sense, as you could do arbitrarily complex things with the combination of high-level tools and initializers like: macro curry($subroutine, *@args) { my $body = call_as_block($subroutine,\(=@args)); return AST.new('Closure', :$body); } -ajs ]
... More to come once we work out the questions above ...