AstBuilder (groovy 2.4.12 API)
Date: 2017-06-21

Package: org.codehaus.groovy.ast.builder

## [Groovy] Class AstBuilder

- org.codehaus.groovy.ast.builder.AstBuilder

- The AstBuilder provides several ways to build an abstract syntax tree (AST) of Groovy code. You can convert a String into AST using the buildFromString method. You can convert code into AST using the buildFromCode method. You can use the AST DSL with the buildFromSpec method. For more information, see the resources on the Groovy wiki pages.

  Authors:
    Hamlet D'Arcy

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `List<ASTNode>` | `buildFromCode(CompilePhase phase = CompilePhase.CLASS_GENERATION, boolean statementsOnly = true, Closure block)` Builds AST based on the code within the Closure parameter.
    `` | `List<ASTNode>` | `buildFromSpec(Closure specification)` Builds AST based on the DSL data within the Closure parameter.
    `` | `List<ASTNode>` | `buildFromString(CompilePhase phase = CompilePhase.CLASS_GENERATION, boolean statementsOnly = true, String source)` Builds AST based on the code within the String parameter.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Method Detail

    - #### List<ASTNode> buildFromCode(CompilePhase phase = CompilePhase.CLASS_GENERATION, boolean statementsOnly = true, Closure block)

      Builds AST based on the code within the Closure parameter. This method must be invoked at compile time and never at runtime, because an ASTTransformation must be run to support it. If you receive an IllegalStateException then you most likely need to add stronger typing. For instance, this will not work: `def builder = new AstBuilder() builder.buildFromCode { // some code }` While this code will: `new AstBuilder().buildFromCode { // some code }` The compiler rewrites buildFromCode invocations into AstBuilder.buildFromString invocations. An exception raised during AST generation will show a stack trace from AstBuilder.buildFromString and not from AstBuilder.buildFromCode . The compiler saves the source code of the closure as a String within the Java class file. The String source of the closure will be visible and un-obfuscated within the class file. If your Closure parameter contains sensitive data such as a hard-coded password then that data is free to be seen by anyone with the class file. Do not store sensitive data within the closure parameter.

      returns:
        a List of ASTNode .
      throws:
        IllegalStateException this method may not be invoked at runtime. It works via a compile-time transformation of the closure source code into a String, which is sent to the AstBuilder.buildFromString method. The buildFromCode() method must be invoked against a strongly typed AstBuilder.
      Parameters:
        `phase` - the CompilePhase the AST will be targeted towards. Default is CompilePhase.CLASS_GENERATION
        `statementsOnly` - when true, only the script statements are returned. WHen false, you will receive back a Script class node also. Default is true.
        `block` - the code that will be converted

    - #### List<ASTNode> buildFromSpec(@DelegatesTo(AstSpecificationCompiler) Closure specification)

      Builds AST based on the DSL data within the Closure parameter.

      Parameters:
        `specification` - the contents to create

    - #### List<ASTNode> buildFromString(CompilePhase phase = CompilePhase.CLASS_GENERATION, boolean statementsOnly = true, String source)

      Builds AST based on the code within the String parameter.

      returns:
        a List of ASTNode .
      throws:
        IllegalArgumentException if source is null or empty
      Parameters:
        `phase` - the CompilePhase the AST will be targeted towards. Default is CompilePhase.CLASS_GENERATION
        `statementsOnly` - when true, only the script statements are returned. WHen false, you will receive back a Script class node also. Default is true.
        `source` - The source code String that will be compiled.