Package org.codehaus.groovy.classgen

Class VariableScopeVisitor

java.lang.Object

org.codehaus.groovy.ast.CodeVisitorSupport

org.codehaus.groovy.ast.ClassCodeVisitorSupport

org.codehaus.groovy.classgen.VariableScopeVisitor

All Implemented Interfaces:

GroovyClassVisitor, GroovyCodeVisitor, ErrorCollecting

public class VariableScopeVisitor
extends ClassCodeVisitorSupport

Initializes the variable scopes for an AST.

For JEP 394 instanceof pattern variables (GROOVY-12242), this class is the single authoritative source of scope decisions. VariableScopeVisitor.InstanceofFlowBindings answers which pattern variables are definitely bound on each control-flow path; this visitor:

• declares each pattern variable only where it is live, so out-of-scope references become DynamicVariable (runtime MissingPropertyException in dynamic Groovy — the same rule @TypeChecked enforces at compile time); and
• attaches the same VariableScopeVisitor.InstanceofFlowBindings instance as AST metadata so later phases (classgen) can read path-live names without re-running the analysis.

See Also:

• VariableScopeVisitor.InstanceofFlowBindings

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	VariableScopeVisitor.InstanceofFlowBindings	Flow-sensitive result for JEP 394 instanceof pattern bindings (GROOVY-12242) — the Groovy equivalent of the JLS §6.3.1 “introduced by” sets.

Constructor Summary

Constructors

Constructor	Description
VariableScopeVisitor(SourceUnit source)	Creates a new variable scope visitor that does not recurse into inner classes.
VariableScopeVisitor(SourceUnit source, boolean recurseInnerClasses)	Creates a new variable scope visitor with optional recursion into inner classes.

Method Summary

Modifier and Type	Method	Description
protected SourceUnit	getSourceUnit()	Provides access to the SourceUnit for error reporting during visitation.
void	prepareVisit(ClassNode node)	Sets the current class node context.
protected void	visitAnnotation(AnnotationNode node)	Visits an individual AnnotationNode, traversing all member expression values.
void	visitArrayExpression(ArrayExpression expression)	Visits an ArrayExpression, traversing element expressions and size expressions.
void	visitAssertStatement(AssertStatement statement)	Visits an AssertStatement, invoking the statement hook before parent traversal.
void	visitBinaryExpression(BinaryExpression expression)	Visits binary expressions with flow-aware scoping for && / || so pattern variables follow Java short-circuit rules (GROOVY-12242 / JEP 394): a && b — true-path bindings of a are in scope in b a || b — true-path bindings of a are not in scope in b; false-path bindings of a are e !instanceof T t / !(e instanceof T t) — pattern declare is isolated on the left of short-circuit ops; only flow-live sets are re-introduced
void	visitBlockStatement(BlockStatement statement)	Visits a BlockStatement, invoking the statement hook before parent traversal.
void	visitCastExpression(CastExpression expression)	Visits a CastExpression, traversing the operand expression.
void	visitCatchStatement(CatchStatement statement)	Visits a CatchStatement, processing variable annotations and invoking the statement hook.
void	visitClass(ClassNode node)	Visits a ClassNode, processing its annotations, package, imports, contents, and object initializers.
void	visitClassExpression(ClassExpression expression)	Visits a ClassExpression.
void	visitClosureExpression(ClosureExpression expression)	Visits a ClosureExpression with annotation processing, traversing parameter annotations before delegating to parent traversal.
void	visitConstantExpression(ConstantExpression expression)	Visits a ConstantExpression.
void	visitConstructorCallExpression(ConstructorCallExpression expression)	Visits a ConstructorCallExpression, traversing its argument list.
protected void	visitConstructorOrMethod(MethodNode node, boolean isConstructor)	Visits a constructor or method node (implementation detail for both visit methods).
void	visitDeclarationExpression(DeclarationExpression expression)	Visits a DeclarationExpression with annotation processing, traversing expression annotations before delegating to parent traversal.
void	visitDoWhileLoop(DoWhileStatement statement)	Visits a do/while loop (GROOVY-12242).
void	visitExpressionStatement(ExpressionStatement statement)	Visits an ExpressionStatement, invoking the statement hook before parent traversal.
void	visitField(FieldNode node)	Visits a FieldNode, processing its annotations and initial value expression if present.
void	visitFieldExpression(FieldExpression expression)	Visits a FieldExpression.
void	visitForLoop(ForStatement statement)	Visits a ForStatement, invoking statement hooks and processing loop variable annotations.
void	visitIfElse(IfStatement statement)	Visits an if/else statement, establishing correct lexical scopes for JEP 394 instanceof pattern variables (GROOVY-12242) and attaching VariableScopeVisitor.InstanceofFlowBindings metadata so later phases need not re-derive the flow analysis.
void	visitMethodCallExpression(MethodCallExpression expression)	Visits a MethodCallExpression, traversing the object expression, method expression, and argument list.
void	visitProperty(PropertyNode node)	Visits a PropertyNode, processing its annotations, initial value expression, and getter/setter blocks if present.
void	visitPropertyExpression(PropertyExpression expression)	Visits a PropertyExpression, traversing the object and property name expressions.
void	visitReturnStatement(ReturnStatement statement)	Visits a ReturnStatement, invoking the statement hook before parent traversal.
void	visitSwitch(SwitchStatement statement)	Visits a SwitchStatement, invoking the statement hook before parent traversal.
void	visitTernaryExpression(TernaryExpression expression)	Visits a ternary / Elvis expression with flow scoping for pattern variables: true-path bindings are in scope in the then-branch; false-path bindings in the else-branch (GROOVY-12242 / JEP 394).
void	visitVariableExpression(VariableExpression expression)	Visits a VariableExpression.
void	visitWhileLoop(WhileStatement statement)	Visits a while loop with partial JEP 394 flow scoping for instanceof pattern variables (GROOVY-12242).

Methods inherited from class org.codehaus.groovy.ast.ClassCodeVisitorSupport

addError, visitAnnotations, visitAnnotations, visitBreakStatement, visitCaseStatement, visitClassCodeContainer, visitConstructor, visitContinueStatement, visitImports, visitMethod, visitObjectInitializerStatements, visitPackage, visitStatement, visitStatementAnnotations, visitSynchronizedStatement, visitThrowStatement, visitTryCatchFinally

Methods inherited from class org.codehaus.groovy.ast.CodeVisitorSupport

afterSwitchCaseStatementsVisited, afterSwitchConditionExpressionVisited, visitArgumentlistExpression, visitAttributeExpression, visitBitwiseNegationExpression, visitBooleanExpression, visitBytecodeExpression, visitClosureListExpression, visitEmptyStatement, visitGStringExpression, visitLambdaExpression, visitListExpression, visitMapEntryExpression, visitMapExpression, visitMethodPointerExpression, visitMethodReferenceExpression, visitNotExpression, visitPostfixExpression, visitPrefixExpression, visitRangeExpression, visitShortTernaryExpression, visitSpreadExpression, visitSpreadMapExpression, visitStaticMethodCallExpression, visitTupleExpression, visitUnaryMinusExpression, visitUnaryPlusExpression

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.codehaus.groovy.ast.GroovyCodeVisitor

visit, visit, visitEmptyExpression, visitListOfExpressions

Constructor Details

VariableScopeVisitor

public VariableScopeVisitor(SourceUnit source,
 boolean recurseInnerClasses)

Creates a new variable scope visitor with optional recursion into inner classes.

Parameters:

source - the source unit being processed

recurseInnerClasses - whether to recurse into inner classes

VariableScopeVisitor

public VariableScopeVisitor(SourceUnit source)

Creates a new variable scope visitor that does not recurse into inner classes.

Parameters:

source - the source unit being processed

Method Details

getSourceUnit

protected SourceUnit getSourceUnit()

Provides access to the SourceUnit for error reporting during visitation. Implementations must override this method.

Specified by:

getSourceUnit in class ClassCodeVisitorSupport

Returns:

the source unit for this visitor

prepareVisit

public void prepareVisit(ClassNode node)

Sets the current class node context.

visitClass

public void visitClass(ClassNode node)

Visits a ClassNode, processing its annotations, package, imports, contents, and object initializers.

Specified by:

visitClass in interface GroovyClassVisitor

Overrides:

visitClass in class ClassCodeVisitorSupport

Parameters:

node - the class node to visit

visitField

public void visitField(FieldNode node)

Visits a FieldNode, processing its annotations and initial value expression if present.

Specified by:

visitField in interface GroovyClassVisitor

Overrides:

visitField in class ClassCodeVisitorSupport

Parameters:

node - the field node to visit

visitProperty

public void visitProperty(PropertyNode node)

Visits a PropertyNode, processing its annotations, initial value expression, and getter/setter blocks if present.

Specified by:

visitProperty in interface GroovyClassVisitor

Overrides:

visitProperty in class ClassCodeVisitorSupport

Parameters:

node - the property node to visit

visitAnnotation

protected void visitAnnotation(AnnotationNode node)

Visits an individual AnnotationNode, traversing all member expression values. Subclasses may override to perform custom annotation processing.

Overrides:

visitAnnotation in class ClassCodeVisitorSupport

Parameters:

node - the annotation node to visit

visitConstructorOrMethod

protected void visitConstructorOrMethod(MethodNode node,
 boolean isConstructor)

Visits a constructor or method node (implementation detail for both visit methods). Processes the node's annotations, all parameter annotations, and code block.

Overrides:

visitConstructorOrMethod in class ClassCodeVisitorSupport

Parameters:

node - the method or constructor node

isConstructor - true if node is a constructor, false if it is a method

visitAssertStatement

public void visitAssertStatement(AssertStatement statement)

Visits an AssertStatement, invoking the statement hook before parent traversal.

Specified by:

visitAssertStatement in interface GroovyCodeVisitor

Overrides:

visitAssertStatement in class ClassCodeVisitorSupport

Parameters:

statement - the assert statement to visit

visitBlockStatement

public void visitBlockStatement(BlockStatement statement)

Visits a BlockStatement, invoking the statement hook before parent traversal.

Specified by:

visitBlockStatement in interface GroovyCodeVisitor

Overrides:

visitBlockStatement in class ClassCodeVisitorSupport

Parameters:

statement - the block statement to visit

See Also:

• CodeVisitorSupport.visitForLoop(ForStatement)
• CodeVisitorSupport.visitWhileLoop(WhileStatement)

visitCatchStatement

public void visitCatchStatement(CatchStatement statement)

Visits a CatchStatement, processing variable annotations and invoking the statement hook.

Specified by:

visitCatchStatement in interface GroovyCodeVisitor

Overrides:

visitCatchStatement in class ClassCodeVisitorSupport

Parameters:

statement - the catch statement to visit

visitDoWhileLoop

public void visitDoWhileLoop(DoWhileStatement statement)

Visits a do/while loop (GROOVY-12242).

The body runs before the condition, so pattern variables from the condition are not in scope in the body (same as Java). The condition is visited in a nested scope so short-circuit RHS works and pattern names do not leak after the loop. Like visitWhileLoop(org.codehaus.groovy.ast.stmt.WhileStatement), there is no after-loop introduction of whenFalse bindings.

Specified by:

visitDoWhileLoop in interface GroovyCodeVisitor

Overrides:

visitDoWhileLoop in class ClassCodeVisitorSupport

Parameters:

statement - the do-while statement to visit

visitExpressionStatement

public void visitExpressionStatement(ExpressionStatement statement)

Visits an ExpressionStatement, invoking the statement hook before parent traversal.

Specified by:

visitExpressionStatement in interface GroovyCodeVisitor

Overrides:

visitExpressionStatement in class ClassCodeVisitorSupport

Parameters:

statement - the expression statement to visit

visitForLoop

public void visitForLoop(ForStatement statement)

Visits a ForStatement, invoking statement hooks and processing loop variable annotations.

Specified by:

visitForLoop in interface GroovyCodeVisitor

Overrides:

visitForLoop in class ClassCodeVisitorSupport

Parameters:

statement - the for statement to visit

visitIfElse

public void visitIfElse(IfStatement statement)

Visits an if/else statement, establishing correct lexical scopes for JEP 394 instanceof pattern variables (GROOVY-12242) and attaching VariableScopeVisitor.InstanceofFlowBindings metadata so later phases need not re-derive the flow analysis.

Rules applied (JLS §6.3.2.2 / JEP 394):

• §6.3.2.2-200-A: e.whenTrue() are in scope in the then-block (S).
• §6.3.2.2-200-B: e.whenFalse() are in scope in the else-block (T).
• §6.3.2.2-200-C-A: if T cannot complete normally and S can, and the var is in e.whenTrue(), the var is introduced after the if-else.
• §6.3.2.2-200-C-B: if S cannot complete normally and T can (or there is no T), and the var is in e.whenFalse(), the var is introduced after the if-else.

In dynamic Groovy, undeclared references resolve to DynamicVariable (runtime MissingPropertyException). @TypeChecked enforces the same rules at compile time; both modes share this visitor.

Specified by:

visitIfElse in interface GroovyCodeVisitor

Overrides:

visitIfElse in class ClassCodeVisitorSupport

Parameters:

statement - the if statement to visit

visitReturnStatement

public void visitReturnStatement(ReturnStatement statement)

Visits a ReturnStatement, invoking the statement hook before parent traversal.

Specified by:

visitReturnStatement in interface GroovyCodeVisitor

Overrides:

visitReturnStatement in class ClassCodeVisitorSupport

Parameters:

statement - the return statement to visit

visitSwitch

public void visitSwitch(SwitchStatement statement)

Visits a SwitchStatement, invoking the statement hook before parent traversal.

Specified by:

visitSwitch in interface GroovyCodeVisitor

Overrides:

visitSwitch in class ClassCodeVisitorSupport

Parameters:

statement - the switch statement to visit

visitWhileLoop

public void visitWhileLoop(WhileStatement statement)

Visits a while loop with partial JEP 394 flow scoping for instanceof pattern variables (GROOVY-12242).

What is supported (aligned with the if-then rule for the body):

• Short-circuit visibility inside the condition (&& / ||).
• e.whenTrue() pattern variables are in scope in the loop body.

Intentional divergence from JLS §6.3.2.3 (while): Groovy does not introduce e.whenFalse() after the loop when the body cannot complete normally. Full after-loop introduction would need definite abrupt-completion analysis of every exit path (including break/continue of nested loops) and is left out for 6.0 — pattern variables never leak past the loop. Documented as a deliberate partial implementation, not an oversight.

Specified by:

visitWhileLoop in interface GroovyCodeVisitor

Overrides:

visitWhileLoop in class ClassCodeVisitorSupport

Parameters:

statement - the while statement to visit

visitArrayExpression

public void visitArrayExpression(ArrayExpression expression)

Visits an ArrayExpression, traversing element expressions and size expressions.

Specified by:

visitArrayExpression in interface GroovyCodeVisitor

Overrides:

visitArrayExpression in class CodeVisitorSupport

Parameters:

expression - the array expression

visitBinaryExpression

public void visitBinaryExpression(BinaryExpression expression)

Visits binary expressions with flow-aware scoping for && / || so pattern variables follow Java short-circuit rules (GROOVY-12242 / JEP 394):

• a && b — true-path bindings of a are in scope in b
• a || b — true-path bindings of a are not in scope in b; false-path bindings of a are
• e !instanceof T t / !(e instanceof T t) — pattern declare is isolated on the left of short-circuit ops; only flow-live sets are re-introduced

Specified by:

visitBinaryExpression in interface GroovyCodeVisitor

Overrides:

visitBinaryExpression in class CodeVisitorSupport

Parameters:

expression - the binary expression

visitTernaryExpression

public void visitTernaryExpression(TernaryExpression expression)

Visits a ternary / Elvis expression with flow scoping for pattern variables: true-path bindings are in scope in the then-branch; false-path bindings in the else-branch (GROOVY-12242 / JEP 394). Also attaches VariableScopeVisitor.InstanceofFlowBindings metadata for later phases.

Specified by:

visitTernaryExpression in interface GroovyCodeVisitor

Overrides:

visitTernaryExpression in class CodeVisitorSupport

Parameters:

expression - the ternary expression

visitCastExpression

public void visitCastExpression(CastExpression expression)

Visits a CastExpression, traversing the operand expression.

Specified by:

visitCastExpression in interface GroovyCodeVisitor

Overrides:

visitCastExpression in class CodeVisitorSupport

Parameters:

expression - the cast expression

visitClassExpression

public void visitClassExpression(ClassExpression expression)

Visits a ClassExpression. No traversal is performed as class expressions contain no child expressions.

Specified by:

visitClassExpression in interface GroovyCodeVisitor

Overrides:

visitClassExpression in class CodeVisitorSupport

Parameters:

expression - the class expression

visitClosureExpression

public void visitClosureExpression(ClosureExpression expression)

Visits a ClosureExpression with annotation processing, traversing parameter annotations before delegating to parent traversal.

Specified by:

visitClosureExpression in interface GroovyCodeVisitor

Overrides:

visitClosureExpression in class ClassCodeVisitorSupport

Parameters:

expression - the closure expression to visit

visitConstantExpression

public void visitConstantExpression(ConstantExpression expression)

Visits a ConstantExpression. No traversal is performed as constants contain no child expressions.

Specified by:

visitConstantExpression in interface GroovyCodeVisitor

Overrides:

visitConstantExpression in class CodeVisitorSupport

Parameters:

expression - the constant expression

visitConstructorCallExpression

public void visitConstructorCallExpression(ConstructorCallExpression expression)

Visits a ConstructorCallExpression, traversing its argument list.

Specified by:

visitConstructorCallExpression in interface GroovyCodeVisitor

Overrides:

visitConstructorCallExpression in class CodeVisitorSupport

Parameters:

expression - the constructor call expression

visitDeclarationExpression

public void visitDeclarationExpression(DeclarationExpression expression)

Visits a DeclarationExpression with annotation processing, traversing expression annotations before delegating to parent traversal.

Specified by:

visitDeclarationExpression in interface GroovyCodeVisitor

Overrides:

visitDeclarationExpression in class ClassCodeVisitorSupport

Parameters:

expression - the declaration expression to visit

visitFieldExpression

public void visitFieldExpression(FieldExpression expression)

Visits a FieldExpression. No traversal is performed as field expressions contain no child expressions.

Specified by:

visitFieldExpression in interface GroovyCodeVisitor

Overrides:

visitFieldExpression in class CodeVisitorSupport

Parameters:

expression - the field expression

visitMethodCallExpression

public void visitMethodCallExpression(MethodCallExpression expression)

Visits a MethodCallExpression, traversing the object expression, method expression, and argument list.

Specified by:

visitMethodCallExpression in interface GroovyCodeVisitor

Overrides:

visitMethodCallExpression in class CodeVisitorSupport

Parameters:

expression - the method call expression

visitPropertyExpression

public void visitPropertyExpression(PropertyExpression expression)

Visits a PropertyExpression, traversing the object and property name expressions.

Specified by:

visitPropertyExpression in interface GroovyCodeVisitor

Overrides:

visitPropertyExpression in class CodeVisitorSupport

Parameters:

expression - the property expression

visitVariableExpression

public void visitVariableExpression(VariableExpression expression)

Visits a VariableExpression. No traversal is performed as variable expressions contain no child expressions.

Specified by:

visitVariableExpression in interface GroovyCodeVisitor

Overrides:

visitVariableExpression in class CodeVisitorSupport

Parameters:

expression - the variable expression