Class AstInspector
- java.lang.Object
-
- org.spockframework.util.inspector.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.
-
-
-
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 underneathconfig
- 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 compilationAstInspectorException
- 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
-
-