DIP50
Title: | AST Macros |
---|---|
DIP: | 50 |
Version: | 1 |
Status: | Draft |
Created: | 2013-11-10 |
Last Modified: | 2013-11-10 |
Author: | Jacob Carlborg |
Contents
Abstract
The basic concept of AST (Abstract Syntax Tree) macros, or just syntax macros, is fairly simple. A macro is just like any other function or method except that it will only run at compile time. When a macro is called, instead of evaluating its argument and then calling the function, an AST is created for each argument passed to the function. The macro will then return a new AST which is injected and type checked at the call site. This means that the call to the macro will be replaced with the AST returned by the macro.
Example
macro myAssert (Context context, Ast!(bool) val, Ast!(string) str = null)
{
auto message = str ? "Assertion failure: " ~ str.eval : val.toString();
auto msgExpr = literal(constant(message));
return <[
if (!$val)
throw new AssertError($msgExpr);
]>;
}
void main ()
{
myAssert(1 + 2 == 4);
}
Compiling and running the above program would result in the following assert error:
core.exception.AssertError@main(13): Assertion failure: 1 + 2 == 4
The interesting part here is that the assert message contains the actual expression that failed.
Rationale
AST macros can be used extend the language with new semantics without changing the actual language. Instead of adding new features to the language AST macros can be a general solution
to implement language changes in library code. Many existing language features could have been
implemented with AST macros, like scope
, foreach
and similar language constructs.
Formal Definition
Declaring a Macro
A macro is always declared with the macro
keyword followed by its name and a parameter list. The first parameter of macro is always of the type Context
, therefore the parameter list cannot be empty. The rest of the parameters are always of the type Ast
. A macro always need to return either void
or a value of the type Ast
.
macro foo (Context context, Ast!(string) str)
{
return str;
}
Calling a Macro
A macro is called just like any other function. The first parameter, which is of
the type Context
, is passed implicitly by the compiler. The rest of the
arguments are passed like in a regular function call. Although you won't pass
arguments of the type Ast
, regular values are passed instead and the compiler
creates an AST of the arguments and pass them as Ast
arguments to the macro.
The Context Parameter
The first parameter of a macro declaration is always of the type Context
. This
parameter is mostly passed implicitly by the compiler. It's also possible to
pass the context parameter manually. This is useful when having helper functions
for a macro and need to retain the context given to the original macro.
The context parameter contains information about the surrounding context where the macro was called. This can be information like the surrounding method and class from which the macro was called.
Bonus
This context parameter also contain information about the complete compilation environment, like:
- The arguments used when the compiler was invoked
- Functions for emitting messages of various verbosity level, like error,
warning and info
- Functions for querying various types of settings/options, like which versions
are defined, is "debug" or "release" defined and so on
- In general providing as much as possible of what the compiler knows about the
compile run
Semantics
Since macros can only be called at compile time the compiler will strip out all macros before the code generating phase.
Quasi-Quoting
Quasi-quoting is basically a form of syntax sugar for creating syntax tree. It could be considered as AST literals. In all examples in this text the following syntax is used for quasi-quoting:
<[ writeln("asd"); ]>
Splicing
Splicing is a syntax used for dynamically inserting a piece of an AST in
quasi-quotes. In all examples in this text a dollar sign, $
, is used for
splicing.
<[ writeln($expr); ]>
The syntax for quasi-quoting and splicing is just an abstraction of what the syntax would actually look like. Regardless of what syntax is used there's always the option to manually create syntax trees using an API.
The AST Macro
The ast
macro is an option to implement quasi-quoting in a library macro. The
ast
macro takes an arbitrary expression and transform it to an AST. It also
supports splicing. The ast
macro has a couple of overloads and their
declarations look as follows:
macro ast (T) (Context context, Ast!(T) expr)
{
// ...
}
macro ast (Context context, Ast!(void delegate ()) block)
{
// ...
}
The first overload takes an arbitrary expression and converts it into an AST. The second overload takes a delegate, this is to be able to convert a whole block of code to an AST.
Bonus
Calling a Macro
Macros are extend to be callable from anywhere it's possible to use a mixin.
Statement Macros
A statement macro is a macro that takes a Statement
as its last parameter.
The difference compared to regular macros is the calling syntax. Statement macros
are called with the same syntax used for statements, like the example below:
macro foo (Context context, Statement block)
{
return block;
}
macro bar (Context context, Ast!(int) arg, Statement block)
{
return block;
}
void main ()
{
foo
{
writeln("foo");
writeln("foo again");
}
foo
writeln("foo2");
bar(3) {
writeln("bar");
writeln("bar again");
}
bar(3)
writeln("bar2");
}
Just like many of the built-in statements the braces are optional when there's
only a single expression in the statement. Since the statement is always the
last parameter in the macro declaration and it's always passed outside the
regular argument list it's legal to have parameters with default arguments or a
variadic parameter list before the statement parameter.
macro foo (Context context, Ast!(string)[] arg ..., Statement block)
{
return block;
}
macro bar (Context context, Ast!(string) fmt = null, Statement block)
{
return block;
}
Attribute macros
An attribute macro is a macro that acts like a user defined attribute. It can be used anywhere a user defined attribute can be used. When an attribute macro is used on a declaration, instead of attaching a value to the declaration the macro is called and the AST of the declaration is passed as the last parameter to the macro. The declaration is replaced with whatever syntax tree the macro returns.
An attribute macro always take a Declaration
as its last parameter. The same
rules about default arguments and variadic parameter that apply to statement
macros apply to attribute macros as well.
macro attr (Context context, Declaration decl)
{
auto attrName = decl.name;
auto type = decl.type;
return <[
private $decl.type _$decl.name;
$decl.type $decl.name ()
{
return _$decl.name;
}
$decl.type $decl.name ($decl.type value)
{
return _$decl.name = value;
}
]>;
}
class Foo
{
@attr int bar;
}