Class AstInspector


  • public class AstInspector
    extends java.lang.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
     
    
    Author:
    Peter Niederwieser
    • Constructor Summary

      Constructors 
      Constructor Description
      AstInspector()
      Constructs an AstInspector, configuring the GroovyClassLoader used underneath with default values.
      AstInspector​(java.lang.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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      org.codehaus.groovy.ast.ClassNode getClass​(java.lang.String name)
      Returns the first class found with the specified simple name.
      org.codehaus.groovy.ast.ConstructorNode getConstructor​(java.lang.String className)
      Returns the first constructor found in the class with the specified simple name.
      org.codehaus.groovy.ast.expr.Expression getExpression​(java.lang.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)".
      java.util.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.
      java.util.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 getField​(java.lang.String name)
      Returns the first field found with the specified name.
      org.codehaus.groovy.ast.AnnotatedNode getMarkedNode​(java.lang.String name)
      Returns the first declaration found that is marked with an @Inspect annotation with the specified name.
      org.codehaus.groovy.ast.MethodNode getMethod​(java.lang.String name)
      Returns the first method found with the specified name (including both script and class methods).
      org.codehaus.groovy.ast.ModuleNode getModule()
      Returns the root of the inspected AST.
      org.codehaus.groovy.ast.PropertyNode getProperty​(java.lang.String name)
      Returns the first property found with the specified name.
      java.util.List<org.codehaus.groovy.ast.expr.Expression> getScriptExpressions()
      Returns the top-level expressions in a script.
      java.util.List<org.codehaus.groovy.ast.stmt.Statement> getScriptStatements()
      Returns the top-level statements in a script.
      org.codehaus.groovy.ast.stmt.Statement getStatement​(java.lang.String name)
      Returns the first statement found immediately preceded by a label with the specified name.
      java.util.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.
      java.util.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​(java.io.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​(java.lang.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 Detail

      • 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:
        setCompilePhase(org.codehaus.groovy.control.CompilePhase)
      • AstInspector

        public AstInspector​(java.lang.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 Detail

      • 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:
        java.lang.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​(java.lang.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​(java.io.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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​(java.lang.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​(java.lang.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