Class AstInspector

java.lang.Object
org.spockframework.util.inspector.AstInspector

public class AstInspector extends Object
Utility class for inspecting the abstract syntax tree (AST) produced by the Groovy compiler. Provides convenient ways to directly access AST nodes without having to navigate the AST from its root.

Nodes representing class/method/property/field declarations are most easily accessed by name. In the case of ambiguity the first node found is returned. Another, more fine-grained but slightly invasive way to access declarations is to annotate them with @Inspect.

Individual statements and expressions can be accessed by prepending them with a label, or by wrapping them in an "inspect_" method call. See AstInspectorTest for examples.

Code example:

 def inspector = new AstInspector(CompilePhase.SEMANTIC_ANALYSIS)
 inspector.load("def foo() { label: println 'hi!' }")
 def expr = inspector.getExpression("label")
 assert expr instanceof MethodCallExpression
 invalid input: '<'/pre
Author:
Peter Niederwieser
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs an AstInspector, configuring the GroovyClassLoader used underneath with default values.
    AstInspector(ClassLoader parent, org.codehaus.groovy.control.CompilerConfiguration config)
    Constructs an AstInspector, configuring the GroovyClassLoader used underneath with the specified parent class loader and compiler configuration.
    AstInspector(org.codehaus.groovy.control.CompilePhase phase)
    Convenience constructor that calls the default constructor and additionally sets the specified compile phase.
  • Method Summary

    Modifier and Type
    Method
    Description
    org.codehaus.groovy.ast.ClassNode
    Returns the first class found with the specified simple name.
    org.codehaus.groovy.ast.ConstructorNode
    Returns the first constructor found in the class with the specified simple name.
    org.codehaus.groovy.ast.expr.Expression
    Returns the first expression found that is either immediately preceded by a label with the specified name, or is the single argument in a method call of the form "inspect_name(expression)".
    List<org.codehaus.groovy.ast.expr.Expression>
    getExpressions(org.codehaus.groovy.ast.expr.ClosureExpression expr)
    Returns the top-level expressions in the specified closure definition.
    List<org.codehaus.groovy.ast.expr.Expression>
    getExpressions(org.codehaus.groovy.ast.MethodNode node)
    Returns the top-level expressions in the specified method or constructor.
    org.codehaus.groovy.ast.FieldNode
    Returns the first field found with the specified name.
    org.codehaus.groovy.ast.AnnotatedNode
    Returns the first declaration found that is marked with an @Inspect annotation with the specified name.
    org.codehaus.groovy.ast.MethodNode
    Returns the first method found with the specified name (including both script and class methods).
    org.codehaus.groovy.ast.ModuleNode
    Returns the root of the inspected AST.
    org.codehaus.groovy.ast.PropertyNode
    Returns the first property found with the specified name.
    List<org.codehaus.groovy.ast.expr.Expression>
    Returns the top-level expressions in a script.
    List<org.codehaus.groovy.ast.stmt.Statement>
    Returns the top-level statements in a script.
    org.codehaus.groovy.ast.stmt.Statement
    Returns the first statement found immediately preceded by a label with the specified name.
    List<org.codehaus.groovy.ast.stmt.Statement>
    getStatements(org.codehaus.groovy.ast.expr.ClosureExpression expr)
    Returns the top-level statements in the specified closure definition.
    List<org.codehaus.groovy.ast.stmt.Statement>
    getStatements(org.codehaus.groovy.ast.MethodNode node)
    Returns the top-level statements in the specified method or constructor.
    void
    load(File sourceFile)
    Compiles the source text in the specified file up to the configured compile phase and stores the resulting AST for subsequent inspection.
    void
    load(String sourceText)
    Compiles the specified source text up to the configured compile phase and stores the resulting AST for subsequent inspection.
    void
    setCompilePhase(org.codehaus.groovy.control.CompilePhase phase)
    Sets the compile phase up to which compilation should proceed.
    void
    setThrowOnNodeNotFound(boolean flag)
    Controls whether to throw an AstInspectorException or to return null when a getXXX() method cannot find a matching AST node.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • AstInspector

      public AstInspector()
      Constructs an AstInspector, configuring the GroovyClassLoader used underneath with default values.
    • AstInspector

      public AstInspector(org.codehaus.groovy.control.CompilePhase phase)
      Convenience constructor that calls the default constructor and additionally sets the specified compile phase.
      Parameters:
      phase - the compile phase up to which compilation should proceed
      See Also:
    • AstInspector

      public AstInspector(ClassLoader parent, org.codehaus.groovy.control.CompilerConfiguration config)
      Constructs an AstInspector, configuring the GroovyClassLoader used underneath with the specified parent class loader and compiler configuration.
      Parameters:
      parent - the parent class loader for the GroovyClassLoader used underneath
      config - the compiler configuration for the GroovyClassLoader used underneath
  • Method Details

    • setCompilePhase

      public void setCompilePhase(org.codehaus.groovy.control.CompilePhase phase)
      Sets the compile phase up to which compilation should proceed. Defaults to CompilePhase.CONVERSION (the phase in which the AST is first constructed).
      Parameters:
      phase - the compile phase up to which compilation should proceed
      Throws:
      IllegalArgumentException - if a compile phase before CompilePhase.CONVERSION is specified
    • setThrowOnNodeNotFound

      public void setThrowOnNodeNotFound(boolean flag)
      Controls whether to throw an AstInspectorException or to return null when a getXXX() method cannot find a matching AST node. Defaults to true.
      Parameters:
      flag - true if an exception should be thrown, false otherwise
    • load

      public void load(String sourceText) throws org.codehaus.groovy.control.CompilationFailedException
      Compiles the specified source text up to the configured compile phase and stores the resulting AST for subsequent inspection.
      Parameters:
      sourceText - the source text to compile
      Throws:
      org.codehaus.groovy.control.CompilationFailedException - if an error occurrs during compilation
    • load

      public void load(File sourceFile) throws org.codehaus.groovy.control.CompilationFailedException
      Compiles the source text in the specified file up to the configured compile phase and stores the resulting AST for subsequent inspection.
      Parameters:
      sourceFile - the file containing the source text to compile
      Throws:
      org.codehaus.groovy.control.CompilationFailedException - if an error occurs during compilation
      AstInspectorException - if an IOException occurs when reading from the file
    • getModule

      public org.codehaus.groovy.ast.ModuleNode getModule()
      Returns the root of the inspected AST.
      Returns:
      the root of the inspected AST
    • getMarkedNode

      public org.codehaus.groovy.ast.AnnotatedNode getMarkedNode(String name)
      Returns the first declaration found that is marked with an @Inspect annotation with the specified name.
      Parameters:
      name - the name specified in the @Inspect annotation marking the declaration of interest
      Returns:
      the first declaration found that is marked with an @Inspect annotation with the specified name
    • getClass

      public org.codehaus.groovy.ast.ClassNode getClass(String name)
      Returns the first class found with the specified simple name.
      Parameters:
      name - the simple name of the class of interest
      Returns:
      the first class found with the specified simple name
    • getField

      public org.codehaus.groovy.ast.FieldNode getField(String name)
      Returns the first field found with the specified name.
      Parameters:
      name - the name of the field of interest
      Returns:
      the first field found with the specified name
    • getProperty

      public org.codehaus.groovy.ast.PropertyNode getProperty(String name)
      Returns the first property found with the specified name.
      Parameters:
      name - the name of the property of interest
      Returns:
      the first property found with the specified name
    • getConstructor

      public org.codehaus.groovy.ast.ConstructorNode getConstructor(String className)
      Returns the first constructor found in the class with the specified simple name.
      Parameters:
      className - the simple name of the class declaring the constructor of interest
      Returns:
      the first constructor found in the class with the specified simple name
    • getMethod

      public org.codehaus.groovy.ast.MethodNode getMethod(String name)
      Returns the first method found with the specified name (including both script and class methods).
      Parameters:
      name - the name of the method of interest
      Returns:
      the first method found with the specified name
    • getScriptStatements

      public List<org.codehaus.groovy.ast.stmt.Statement> getScriptStatements()
      Returns the top-level statements in a script. If no such statements are found, an empty list is returned.
      Returns:
      the top-level statements in a script
    • getScriptExpressions

      public List<org.codehaus.groovy.ast.expr.Expression> getScriptExpressions()
      Returns the top-level expressions in a script. If no such expressions are found, an empty list is returned.
      Returns:
      the top-level expressions in a script
    • getStatements

      public List<org.codehaus.groovy.ast.stmt.Statement> getStatements(org.codehaus.groovy.ast.MethodNode node)
      Returns the top-level statements in the specified method or constructor. If no such statements are found, an empty list is returned.
      Parameters:
      node - a MethodNode representing a method or constructor
      Returns:
      the top-level statements in the specified method or constructor
    • getExpressions

      public List<org.codehaus.groovy.ast.expr.Expression> getExpressions(org.codehaus.groovy.ast.MethodNode node)
      Returns the top-level expressions in the specified method or constructor. If no such expressions are found, an empty list is returned.
      Parameters:
      node - a MethodNode representing a method or constructor
      Returns:
      the top-level expressions in the specified method or constructor
    • getStatements

      public List<org.codehaus.groovy.ast.stmt.Statement> getStatements(org.codehaus.groovy.ast.expr.ClosureExpression expr)
      Returns the top-level statements in the specified closure definition. If no such statements are found, an empty list is returned.
      Parameters:
      expr - a ClosureExpression representing a closure defintion
      Returns:
      the top-level statements in the specified closure definition
    • getExpressions

      public List<org.codehaus.groovy.ast.expr.Expression> getExpressions(org.codehaus.groovy.ast.expr.ClosureExpression expr)
      Returns the top-level expressions in the specified closure definition. If no such expressions are found, an empty list is returned.
      Parameters:
      expr - a ClosureExpression representing a closure definition
      Returns:
      the top-level expressions in the specified closure definition
    • getStatement

      public org.codehaus.groovy.ast.stmt.Statement getStatement(String name)
      Returns the first statement found immediately preceded by a label with the specified name.
      Parameters:
      name - the name of the label immediately preceding the statement of interest
      Returns:
      the first statement found immediately preceded by a label with the specified name
    • getExpression

      public org.codehaus.groovy.ast.expr.Expression getExpression(String name)
      Returns the first expression found that is either immediately preceded by a label with the specified name, or is the single argument in a method call of the form "inspect_name(expression)".

      Example:

       def inspector = new AstInspector()
       inspector.load("fooBar: foo.bar(inspect_firstArg(a), b)")
       def fooBar = inspector.getExpression("fooBar")
       def firstArg = inspector.getExpression("firstArg")
       
      Parameters:
      name - the name of a label immediately preceding the expression of interest, or NAME in a method call "inspect_NAME" wrapping the expression of interest
      Returns:
      the Expression representing the first matching expression