AST Transformations

Although at times, it may sound like a good idea to extend the syntax of Groovy to implement new features (like this is the case for instance for multiple assignments), most of the time, we can't just add a new keyword to the grammar, or create some new syntax construct to represent a new concept. However, with the idea of AST (Abstract Syntax Tree) Transformations, we are able to tackle new and innovative ideas without necessary grammar changes.

When the Groovy compiler compiles Groovy scripts and classes, at some point in the process, the source code will end up being represented in memory in the form of a Concrete Syntax Tree, then transformed into an Abstract Syntax Tree. The purpose of AST Transformations is to let developers hook into the compilation process to be able to modify the AST before it is turned into bytecode that will be run by the JVM.

AST Transformations provides Groovy with improved compile-time metaprogramming capabilities allowing powerful flexibility at the language level, without a runtime performance penalty.

There are two kinds of transformations: global and local transformations.

• Global transformations are applied to by the compiler on the code being compiled, wherever the transformation apply. A JAR added to the classpath of the compiler should contain a service locator file at META-INF/services/org.codehaus.groovy.transform.ASTTransformation with a line with the name of the transformation class. The transformation class must have a no-args constructor and implement the org.codehaus.groovy.transform.ASTTransformationinterface. It will be run against every source in the compilation, so be sure to not create transformations which scan all the AST in an expansive and time-consuming manner, to keep the compiler fast.
• Local transformations are transformations applied locally by annotating code elements you want to transform. For this, we reuse the annotation notation, and those annotations should implement org.codehaus.groovy.transform.ASTTransformation. The compiler will discover them and apply the transformation on these code elements.

One hook for accessing this capability is via annotations (for local AST transformations). In your Groovy code you will make use of one of more annotations. Behind the scenes, an AST processor relevant to the annotation you are using is inserted into the compiler phases at the appropriate point. You can explore some of the more popular Annotations below:

• Bindable and Vetoable transformation
• Building AST Guide
• Category and Mixin transformations
• Compiler Phase Guide
• Delegate transformation
• Immutable AST Macro
• Immutable transformation
• Lazy transformation
• Newify transformation
• PackageScope transformation
• Singleton transformation

Grape also provides its own transformation with @Grab.

Implementing your own AST Transformations

There are two kinds of AST Transformations, local and global transformations:

• implementing a Global AST Transformations
• implementing a local AST transformation

When writing an AST Transformation, you may find the following guides helpful:

• Compiler Phase Guide - decide on the compiler phase in which to perform the work
• Building AST Guide - decide how best to create AST