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`
  `visitSwitchExpression(SwitchExpression expression)`
  Visits a `SwitchExpression`, traversing the selector, case arms, and default arm (GROOVY-12255).
  `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, visitYieldStatement`

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

  `afterSwitchCaseStatementsVisited, afterSwitchCaseStatementsVisited, afterSwitchConditionExpressionVisited, 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

  - ### visitSwitchExpression

    public void visitSwitchExpression(SwitchExpression expression)
    Visits a `SwitchExpression`, traversing the selector, case arms, and default arm (GROOVY-12255).
    Specified by:
      `visitSwitchExpression` in interface `GroovyCodeVisitor`
    Overrides:
      `visitSwitchExpression` in class `CodeVisitorSupport`
    Parameters:
      `expression` - the switch expression

  - ### 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