Class AstInspector
java.lang.Object
org.spockframework.util.inspector.AstInspector
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 </pre
- Author:
- Peter Niederwieser
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs 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 TypeMethodDescriptionorg.codehaus.groovy.ast.ClassNode
Returns the first class found with the specified simple name.org.codehaus.groovy.ast.ConstructorNode
getConstructor
(String className) Returns the first constructor found in the class with the specified simple name.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)".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
getMarkedNode
(String name) 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
getProperty
(String name) 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
getStatement
(String name) 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
Compiles the source text in the specified file up to the configured compile phase and stores the resulting AST for subsequent inspection.void
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 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
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 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
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
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
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
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
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
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
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
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
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
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
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
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
-