groovy-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mariogarcia <...@git.apache.org>
Subject [GitHub] groovy pull request #439: WIP Add groovy-macro docs
Date Sun, 09 Oct 2016 14:00:30 GMT
Github user mariogarcia commented on a diff in the pull request:

    https://github.com/apache/groovy/pull/439#discussion_r82522915
  
    --- 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`
    --- 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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message