ASTTransformationCustomizer (Groovy 5.0.0)

Package: org.codehaus.groovy.control.customizers

## [Groovy] Class ASTTransformationCustomizer

- org.codehaus.groovy.control.customizers.ASTTransformationCustomizer

- All Implemented Interfaces and Traits:
    CompilationUnitAware

      @AutoFinal
      @CompileStatic
      class ASTTransformationCustomizer
      extends CompilationCustomizer
      implements CompilationUnitAware

  This customizer allows applying an AST transformation to a source unit with several strategies. Creating a customizer with the class constructor will trigger an AST transformation for each class node of a source unit. However, you cannot pass parameters to the annotation so the default values will be used. Writing :

           def configuration = new CompilerConfiguration()
           configuration.addCompilationCustomizers(new ASTTransformationCustomizer(Log))
           def shell = new GroovyShell(configuration)
           shell.evaluate("""
              class MyClass {

              }""")

  is equivalent to :

           def shell = new GroovyShell()
           shell.evaluate("""
              @Log
              class MyClass {

              }""")

  The class passed as a constructor parameter must be an AST transformation annotation. Alternatively, you can apply a global AST transformation by calling the AST transformation. In that case, the transformation is applied once for the whole source unit. Unlike a global AST transformation declared in the META-INF/services/org.codehaus.groovy.transform.ASTTransformation file, which are applied if the file is in the classpath, using this customizer you'll have the choice to apply your transformation selectively. It can also be useful to debug global AST transformations without having to package your annotation in a jar file.
  Since:
    1.8.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected CompilationUnit` | `compilationUnit` |

  - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `ASTTransformation` | `transformation`

  - ### Constructor Summary

    Constructors
    Constructor and description
    `ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, String astTransformationClassName, ClassLoader transformationClassLoader)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, String astTransformationClassName)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, String astTransformationClassName, ClassLoader transformationClassLoader)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, String astTransformationClassName)`
    `ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, ClassLoader transformationClassLoader)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(ASTTransformation transformation)` Creates an AST transformation customizer using the specified transformation.
    `ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, ClassLoader transformationClassLoader)` Creates an AST transformation customizer using the specified annotation.
    `ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation)`
    `ASTTransformationCustomizer(Map annotationParams, ASTTransformation transformation)`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `void` | `call(SourceUnit source, GeneratorContext context, ClassNode classNode)`
    `` | `void` | `setAnnotationParameters(Map<String, Object> params)` Specify annotation parameters.
    `` | `void` | `setCompilationUnit(CompilationUnit unit)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class CompilationCustomizer` | `getPhase`

- - ### Field Detail

    - #### protected CompilationUnit compilationUnit

  - ### Property Detail

    - #### final ASTTransformation transformation

  - ### Constructor Detail

    - #### ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, String astTransformationClassName, ClassLoader transformationClassLoader)

      Creates an AST transformation customizer using the specified annotation. The transformation classloader can be used if the transformation class cannot be loaded from the same class loader as the annotation class. It's assumed that the annotation is not annotated with `GroovyASTTransformationClass` and so the second argument supplies the link to the ASTTransformation class that should be used.

      Parameters:
        transformationAnnotation
        astTransformationClassName
        transformationClassLoader

    - #### ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, String astTransformationClassName)

      Creates an AST transformation customizer using the specified annotation. It's assumed that the annotation is not annotated with `GroovyASTTransformationClass` and so the second argument supplies the link to the ASTTransformation class that should be used.

      Parameters:
        transformationAnnotation
        astTransformationClassName

    - #### ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, String astTransformationClassName, ClassLoader transformationClassLoader)

      Creates an AST transformation customizer using the specified annotation. The transformation classloader can be used if the transformation class cannot be loaded from the same class loader as the annotation class. Additionally, you can pass a map of parameters that will be used to parameterize the annotation. It's assumed that the annotation is not annotated with `GroovyASTTransformationClass` and so the second argument supplies the link to the ASTTransformation class that should be used.

      Parameters:
        transformationAnnotation
        astTransformationClassName
        transformationClassLoader

    - #### ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, String astTransformationClassName)

    - #### ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation, ClassLoader transformationClassLoader)

      Creates an AST transformation customizer using the specified annotation. The transformation classloader can be used if the transformation class cannot be loaded from the same class loader as the annotation class.

      Parameters:
        transformationAnnotation
        transformationClassLoader

    - #### ASTTransformationCustomizer(Class<? extends Annotation> transformationAnnotation)

      Creates an AST transformation customizer using the specified annotation.

      Parameters:
        transformationAnnotation

    - #### ASTTransformationCustomizer(ASTTransformation transformation)

      Creates an AST transformation customizer using the specified transformation.

    - #### ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation, ClassLoader transformationClassLoader)

      Creates an AST transformation customizer using the specified annotation. The transformation classloader can be used if the transformation class cannot be loaded from the same class loader as the annotation class. Additionally, you can pass a map of parameters that will be used to parameterize the annotation.

      Parameters:
        transformationAnnotation
        transformationClassLoader

    - #### ASTTransformationCustomizer(Map annotationParams, Class<? extends Annotation> transformationAnnotation)

    - #### ASTTransformationCustomizer(Map annotationParams, ASTTransformation transformation)

  - ### Method Detail

    - #### @Override
      void call(SourceUnit source, GeneratorContext context, ClassNode classNode)

    - #### @CompileDynamic
      void setAnnotationParameters(Map<String, Object> params)

      Specify annotation parameters. For example, if the annotation is:

          @Log(value='logger')

      You could create an AST transformation customizer and specify the "value" parameter thanks to this method:

          annotationParameters = [value: 'logger']

      Note that you cannot specify annotation closure values directly. If the annotation you want to add takes a closure as an argument, you will have to set a ClosureExpression instead. This can be done by either creating a custom ClosureExpression from code, or using the AstBuilder.

      Here is an example:

           // add @Contract({distance >= 0 })
           def customizer = new ASTTransformationCustomizer(Contract)
           def expression = new AstBuilder().buildFromCode(CompilePhase.CONVERSION) { ->
              distance >= 0
           }.expression[0]
           customizer.annotationParameters = [value: expression]

      Parameters:
        `params` - the annotation parameters
      Since:
        1.8.1

    - #### void setCompilationUnit(CompilationUnit unit)