Github user mariogarcia commented on a diff in the pull request:
https://github.com/apache/groovy/pull/439#discussion_r82523102
--- Diff: src/spec/doc/core-metaprogramming.adoc ---
@@ -2829,6 +2829,153 @@ to use the Groovy Console, in particular the AST
browser tool, to gain knowledge
resource for learning is the
https://github.com/apache/groovy/tree/master/src/test/org/codehaus/groovy/ast/builder[AST
Builder]
test suite.
+==== Macros
+
+===== Introduction
+
+Until version 2.5.0, when developing AST transformations, developers
should have a deep knowledge about how the AST
+(Abstract source tree) was built by the compiler in order to know how to
add new expressions or statements during
+compile time.
+
+Although the use of `org.codehaus.groovy.ast.tool.GeneralUtils` static
methods could mitigate the burden of creating
+expressions and statements, it's still a low-level way of writing those
AST nodes directly.
+We needed something to abstract us from writing the AST directly and
that's exactly what Groovy macros were made for.
+They allow you to add code during compile time directly, without having
translate the code you had in mind to the
+`org.codehaus.groovy.ast.*` node related classes.
+
+===== Statements and expressions
+
+Lets see an example, lets create a local AST transformation.
`@AddMessageMethod`. When applied to a given class it
+will add a new method called `getMessage` to that class. The method will
return "42". The annotation it's pretty
+straight forward:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroStatementTest.groovy[tags=addmethodannotation,indent=0]
+----
+
+How would look like the AST transformation without the use of a macro:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroStatementTest.groovy[tags=addmethodtransformationwithoutmacro,indent=0]
+----
+
+<1> Create a return statement
+<2> Create a constant expression "42"
+<3> Adding the code to the new method
+<4> Adding the new method to the annotated class
+
+If you're not used to the AST API, that definitely doesn't look like the
code you had in mind. Now look how the
+previous code looks like with the use of macros.
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroStatementTest.groovy[tags=basicWithMacro,indent=0]
+----
+
+<1> Much simpler. You wanted to add a return statement that returned "42"
and that's exactly what you can read inside
+the `macro` utility method. Your plain code will be translated for you to
a `org.codehaus.groovy.ast.stmt.ReturnStatement`
+<2> Adding the return statement to the new method
+<3> Adding the new code to the annotated class
+
+Although `macro` method is used in this example to create an **statement**
the `macro` method could also be used to create
+**expressions** as well, it depends on which `macro` signature you use:
+
+- `macro(Closure)`: Create a given statement with the code inside the
closure.
+- `macro(Boolean,Closure)`: if **true** wrap expressions inside the
closure inside an statement, if **false** then return
+an expression
+- `macro(CompilePhase, Closure)`: Create a given statement with the code
inside the closure in a specific compile phase
+- `macro(CompilePhase, Boolean, Closure)`: Create an statement or an
expression (true == statement, false == expression)
+in a specific compilation phase.
+
+NOTE: All this signatures can be found at
`org.codehaus.groovy.macro.runtime.MacroGroovyMethods`
+
+Sometimes we could be only interested in creating a given expression, not
the whole statement, in order to do that we
+should use any of the `macro` invocations with a boolean parameter:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroExpressionTest.groovy[tags=addgettwotransformation,indent=0]
+----
+
+<1> We're telling macro not to wrap the expression in any statement, we're
only interested in the expression
+<2> Assigning the expression
+<3> Creating a `ReturnStatement` using a method from `GeneralUtils` and
the expression returned
+<4> Adding the code to the new method
+<5> Adding the method to the class
+
+===== Variable substitution
+
+Macros are great but we can't create anything useful or reusable if our
macros couldn't receive parameters or resolve
+surrounding variables.
+
+In the following example we're creating an AST transformation `@MD5` that
when applied to a given String field will
+add a method returning the MD5 the value of that field.
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroVariableSubstitutionTest.groovy[tags=md5annotation,indent=0]
+----
+
+And the transformation:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroVariableSubstitutionTest.groovy[tags=md5transformation,indent=0]
+----
+
+<1> We need a reference to a variable expression
+<2> If using a class outside the standard packages we should whether add
needed imports or use the qualified name. When
+using the qualified named of a given static method you need to make sure
it's resolved in the proper compile phase. In
+this particular case we're instructing the macro to resolve it at
SEMANTIC_ANALYSIS, which is the first compile phase
+with type information.
+<3> In order to substitute any `expression` inside the macro we need to
use the `$v` method. `$v` receives a closure as an
+argument, and the closure is only allowed to substitute expressions,
meaning classes inheriting
+`org.codehaus.groovy.ast.expr.Expression`.
+
+===== MacroClass
+
+As we mentioned earlier the `macro` method is only capable of producing
`statements` and `expressions`. But what if we
+want to produce other types of nodes, such a method, a field... ?
+
+`org.codehaus.groovy.macro.transform.MacroClass` can be used to create
**classes** (ClassNode instances) in our
+transformations the same way we created statements and expressions with
the `macro` method before.
+
+The next example is a local transformation `@Statistics`. When applied to
a given class it will add two methods
+**getMethodCount()** and **getFieldCount()** which return how many methods
and fields has the class respectively. Here
+is the marker annotation.
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroClassTest.groovy[tags=statisticsannotation,indent=0]
+----
+
+And the AST transformation:
+
+[source,groovy]
+----
+include::{projectdir}/src/spec/test/metaprogramming/MacroClassTest.groovy[tags=statisticstransformation,indent=0]
+----
+
+<1> Creating a template class
+<2> Adding template class methods to the annotated class
+<3> Passing the reference class
+<4> Extracting reference class method count value expression
+<5> Extracting reference class field count value expression
+<6> Building the **getMethodCount()** method using reference's method
count value expression
+<7> Building the **getFieldCount()** method using reference's field count
value expression
+
+Basically we've created the **Statistics** class as a template to avoid
writing low level AST API, then we
+copied methods created in the template class to their final destination.
+
+NOTE: Types inside the `MacroClass` implementation should be resolved
inside, that's why I had to write
+`java.lang.Integer` instead of simply writing `Integer`.
+
+IMPORTANT: Notice that we'are using `@CompileDynamic`. That's because the
way we use `MacroClass` is like we
--- End diff --
:+1:
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
