org.spockframework.util.inspector
Class AstInspector

java.lang.Object
  extended by 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
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
 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


Copyright © 2013. All rights reserved