Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>Groovy 1.6 offers offers several approaches to transforming the AST of code within the compiler. You can write a <a href="http://hamletdarcy.blogspot.com/2009/01/groovy-compile-time-meta-magic.html">custom AST visitor</a>, you can use annotations and a <a class="confluence-link" href="/display/GROOVY/Local+AST+Transformations" data-linked-resource-id="117900504" data-linked-resource-type="page" data-linked-resource-default-alias="Local AST Transformations" data-base-url="http://docs.codehaus.org">local AST transformation</a>, or you can use a global AST transformation.</p>

<p>This page explains how to write and debug a global AST transformation.</p>

<p>Sticking with the naive and simple example from the <a class="confluence-link" href="/display/GROOVY/Local+AST+Transformations" data-linked-resource-id="117900504" data-linked-resource-type="page" data-linked-resource-default-alias="Local AST Transformations" data-base-url="http://docs.codehaus.org">local transformation</a> page, consider wanting to provide console output at the start and stop of method calls within your code. The following &quot;Hello World&quot; example would actually print &quot;Hello World&quot; along with a start and stop message:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
def greet() {
    println "Hello World"
}

greet()
</pre></td></tr></table>
<p>Not a great use case, but it is useful to explain the mechanics of global transformations.</p>

<p>A global transformation requires four steps: 1) write an ASTTransformation subclass, 2) create a Jar metadata file containing the name of your ASTTransformation, 3) create a Jar containing the class and metadata, and 4) invoke groovyc with that Jar on your classpath.</p>

<h2>Writing an ASTTransformation</h2>

<p>This is almost exactly the same step you'll need if writing a local transformation. You must define an <a href="http://groovy.codehaus.org/gapi/org/codehaus/groovy/transform/ASTTransformation.html">ASTTransformation</a> subclass that reads, and possibly rewrites, the syntax tree of the compiling code. Here is the transformation that will add a console start message and end message to all method invocations:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
@GroovyASTTransformation(phase=CompilePhase.CONVERSION)
public class LoggingASTTransformation implements ASTTransformation {

static final def TARGET = WithLogging.getName()

public void visit(ASTNode[] astNodes, SourceUnit sourceUnit) {
        List methods = sourceUnit.getAST()?.getMethods()
        methods?.each { MethodNode method ->
            Statement startMessage = createPrintlnAst("Starting $method.name")
            Statement endMessage = createPrintlnAst("Ending $method.name")

List existingStatements = method.getCode().getStatements()
            existingStatements.add(0, startMessage)
            existingStatements.add(endMessage)
        }
    }

private Statement createPrintlnAst(String message) {
        return new ExpressionStatement(
            new MethodCallExpression(
                new VariableExpression("this"),
                new ConstantExpression("println"),
                new ArgumentListExpression(
                    new ConstantExpression(message)
                )
            )
        )
    }
}
</pre></td></tr></table>
<p>The first line (<a href="http://groovy.codehaus.org/api/org/codehaus/groovy/transform/GroovyASTTransformation.html">@GroovyASTTransformation</a>) line tells the Groovy compiler that this is an AST transformation that should occur in the conversion <a href="http://groovy.codehaus.org/gapi/org/codehaus/groovy/control/CompilePhase.html">CompilePhase</a>. Unlike local transformations, global transformations can occur in any phase.</p>

<p>The public<a href="http://groovy.codehaus.org/gapi/org/codehaus/groovy/transform/ASTTransformation.html#visit%28ASTNode%5B%5D,%20org.codehaus.groovy.control.SourceUnit%29">visit(ASTNode[], SourceUnit)</a> method is invoked for each source unit compiled. In this example, I'm just pulling out all the methods defined in the source. A method to the compiler is simply a list of <a href="http://groovy.codehaus.org/gapi/org/codehaus/groovy/ast/stmt/Statement.html">Statement</a> objects, so I'm adding a statement zero logging the start message and appending a statement to the end of the list with the end message.</p>

<p>Notice the complexity in creating a simple println Statement in the createPrintlnAst method. A method call has a target(this), a name(println), and an argument list(the message). An easy way to create AST is to write the Groovy code you expect to create, then observe what AST the compiler generates within the IDE's debugger. This requires a test harness with a custom GroovyClassLoader and an <a href="http://groovy.codehaus.org/gapi/org/codehaus/groovy/ast/CodeVisitorSupport.html">AST Visitor</a>.</p>

<h2>Writing Jar Metadata</h2>

<p>The Groovy compiler discovers your ASTTransformation through a file named &quot;org.codehaus.groovy.transform.ASTTransformation&quot;. This file must contain the fully qualified package and name of your transformation. In my example, the file simply has one line:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
gep.LoggingASTTransformation
</pre></td></tr></table>

<h2>Creating the Jar</h2>

<p>The ASTtransformation and the metadata must be packaged into a single Jar file. The org.codehaus.groovy.transform.ASTTransformation file must be in the META-INF/services directory. The Jar layout for this example follows:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
LogMethodTransform.jar
--gep
----LoggingASTTransformation.class
----LoggingASTTransformation$_visit_closure1.class
--META-INF
----services
------org.codehaus.groovy.transform.ASTTransformation
</pre></td></tr></table>

<h2>Compiling the Example</h2>

<p>The new Jar must be put on the groovyc classpath for the transformation to be invoked. If the sample script at the top of the post is in a file named &quot;LoggingExample.groovy&quot;, then the command line to compile this is:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
groovyc -cp LogMethodTransform.jar LoggingExample.groovy
</pre></td></tr></table>
<p>This generates a LoggingExample.class that, when run with Java, produces:</p>
<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
Starting greet
Hello World
Ending greet
</pre></td></tr></table>

<h2>Debugging Global Transformations</h2>

<p>Local transformations are simple to debug: the IDE (at least IDEA) supports it with no extra effort. Global transformations are not so easy. To test this you might write a test harness that invoked LoggingASTTransformation on a file explicitly. The test harness source is <a href="http://svn.assembla.com/svn/SampleCode/gep/src/gep/transform/global/TestHarness.groovy">available</a> and could easily be modified to fit your needs. Let me know if you know an easier way to debug this!</p>

<h2>Applying your transformation on custom file extensions</h2>

<p>Since Groovy 1.7.5, you are allowed to add your own file types to the groovy compiler. This can be especially useful when you have written a DSL which requires extensive AST transformations and that you want to avoid your transformation to be applied on regular groovy files. For example, imagine your DSL specifies user stories :</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
story "user enters invalid postcode" {

given ....

expect ...

}
</pre></td></tr></table>
<p>Then you could allow this syntax in .story files only. To do this, you must first have registered your global AST transformation into the '<em>META-INF/services/org.codehaus.groovy.transform.ASTTransformation</em>' file like explained before. The second step is to register your custom file extension into the '<em>META-INF/services/org.codehaus.groovy.source.Extensions</em>' file :</p>

}
</pre></td></tr></table>
<p>Now you have a global AST transformation that will only apply on .story files.</p>