9 Macros

Macros are without a doubt the most advanced feature in Haxe. They are often perceived as dark magic that only a select few are capable of mastering, yet there is nothing magical (and certainly nothing dark) about them.

Define: Abstract Syntax Tree (AST)

The AST is the result of parsing Haxe code into a typed structure. This structure is exposed to macros through the types defined in the file haxe/macro/Expr.hx of the Haxe Standard Library.

The role of macros during compilation.

Figure: The role of macros during compilation.

A basic macro is a syntax-transformation. It receives zero or more expressions and also returns an expression. If a macro is called, it effectively inserts code at the place it was called from. In that respect, it could be compared to a preprocessor like #define in C++, but a Haxe macro is not a textual replacement tool.

We can identify different kinds of macros, which are run at specific compilation stages:

  • Initialization Macros: These are provided by command line using the --macro compiler parameter. They are executed after the compiler arguments were processed and the typer context has been created, but before any typing was done (see Initialization Macros).
  • Build Macros: These are defined for classes, enums and abstracts through the @:build or @:autoBuild metadata. They are executed per-type, after the type has been set up (including its relation to other types, such as inheritance for classes) but before its fields are typed (see Type Building).
  • Expression Macros: These are normal functions which are executed as soon as they are typed.
Related content