Variable.java

package org.perlonjava.frontend.parser;

import org.perlonjava.app.cli.CompilerOptions;

import org.perlonjava.frontend.astnode.*;
import org.perlonjava.frontend.lexer.LexerToken;
import org.perlonjava.frontend.lexer.LexerTokenType;
import org.perlonjava.frontend.semantic.SymbolTable;
import org.perlonjava.runtime.operators.WarnDie;
import org.perlonjava.runtime.perlmodule.Strict;
import org.perlonjava.runtime.runtimetypes.*;

import java.util.ArrayList;
import java.util.List;

import static org.perlonjava.frontend.parser.ParsePrimary.parsePrimary;
import static org.perlonjava.frontend.parser.ParserNodeUtils.atUnderscore;
import static org.perlonjava.frontend.parser.TokenUtils.peek;

/**
 * Parser for Perl variables with sigils ($, @, %, &, *).
 *
 * <p>This class handles the parsing of Perl variables including:
 * <ul>
 *   <li>Simple variables: {@code $var}, {@code @array}, {@code %hash}</li>
 *   <li>Braced variables: {@code ${var}}, {@code @{array}}</li>
 *   <li>Array/hash access: {@code $array[0]}, {@code $hash{key}}</li>
 *   <li>Dereferencing: {@code $ref->[0]}, {@code $ref->{key}}</li>
 *   <li>Typeglobs: {@code *name}</li>
 *   <li>Code references: {@code &sub}</li>
 *   <li>Class field access: automatic transformation of {@code $field} to {@code $self->{field}} in methods</li>
 * </ul>
 *
 * <p>The parser also handles special cases like:
 * <ul>
 *   <li>Special variables: {@code $@}, {@code $_}, {@code $!}, etc.</li>
 *   <li>Regex variables: {@code $1}, {@code $2}, etc.</li>
 *   <li>Array size: {@code $#array}</li>
 *   <li>Package-qualified names: {@code $Package::var}</li>
 * </ul>
 */
public class Variable {

    /**
     * Check if a field exists in the current class or any parent class.
     * Uses both the local symbol table (for current class) and the global
     * FieldRegistry (for parent classes that have been parsed).
     *
     * @param parser    The parser instance
     * @param fieldName The name of the field to check (without sigil)
     * @return true if the field exists in the class hierarchy
     */
    public static boolean isFieldInClassHierarchy(Parser parser, String fieldName) {
        // Get the current package/class name
        String currentClass = parser.ctx.symbolTable.getCurrentPackage();

        // First check field in current class via symbol table
        // Use getVariableIndex (not InCurrentScope) to search all parent scopes
        // Fields are in the class scope, methods create inner scopes
        String fieldSymbol = "field:" + fieldName;
        if (parser.ctx.symbolTable.getVariableIndex(fieldSymbol) != -1) {
            return true;
        }

        // Check if we're in a class (not just a regular package)
        if (!parser.ctx.symbolTable.currentPackageIsClass()) {
            return false;
        }

        // Check the global FieldRegistry for inherited fields
        // This works when parent classes were parsed before child classes
        return FieldRegistry.hasFieldInHierarchy(currentClass, fieldName);
    }

    /**
     * Parses a variable from the given lexer token.
     *
     * <p>This is the main entry point for parsing Perl variables. It handles various forms:
     * <ul>
     *   <li>Simple variables: {@code $var}, {@code @array}, {@code %hash}</li>
     *   <li>Braced forms: {@code ${expr}}, {@code @{expr}}, {@code %{expr}}</li>
     *   <li>Dereferencing: {@code $$ref}, {@code @$ref}, {@code %$ref}</li>
     *   <li>Special cases: {@code $#array} (array size), {@code $#[...]} (empty string)</li>
     *   <li>Class fields: automatic transformation in method context</li>
     * </ul>
     *
     * <p>The method also handles special parsing rules:
     * <ul>
     *   <li>Validates variable names according to Perl rules</li>
     *   <li>Checks for syntax errors (e.g., parentheses after non-sub variables)</li>
     *   <li>Vivifies typeglobs when using {@code *name} syntax</li>
     *   <li>Transforms field access to {@code $self->{field}} in class methods</li>
     * </ul>
     *
     * @param parser the parser instance containing the current parsing state
     * @param sigil  The sigil that starts the variable ($, @, %, &, *, or $#)
     * @return The parsed variable node (OperatorNode, BinaryOperatorNode, or other AST node)
     * @throws PerlCompilerException If there is a syntax error during parsing
     */
    public static Node parseVariable(Parser parser, String sigil) {
        Node operand;
        LexerToken nextToken = parser.tokenIndex < parser.tokens.size()
                ? parser.tokens.get(parser.tokenIndex)
                : new LexerToken(LexerTokenType.EOF, "");

        // Special case 1: $${...} - nested scalar dereference
        // Example: $${ref} means dereference $ref to get a scalar reference, then dereference that
        int nextNonWsIndex = Whitespace.skipWhitespace(parser, parser.tokenIndex, parser.tokens);
        LexerToken nextNonWsToken = nextNonWsIndex < parser.tokens.size()
                ? parser.tokens.get(nextNonWsIndex)
                : new LexerToken(LexerTokenType.EOF, "");
        if (nextNonWsToken.text.equals("$")) {
            // Check if we have ${...} pattern
            if (nextNonWsIndex + 1 < parser.tokens.size() && parser.tokens.get(nextNonWsIndex + 1).text.equals("{")) {
                // This is ${...}, parse as dereference of ${...}
                // Don't consume the $ token, let it be parsed as part of the variable
                operand = parser.parseExpression(parser.getPrecedence("$") + 1);
                return new OperatorNode(sigil, operand, parser.tokenIndex);
            }
        }

        // Special case 2: $#[...] - deprecated syntax that returns empty string
        // This is mentioned in t/base/lex.t as a special edge case
        if (sigil.equals("$#") && nextNonWsToken.text.equals("[")) {
            // This is $#[...] which is mentioned in t/base/lex.t and it returns an empty string
            parsePrimary(parser);
            return new StringNode("", parser.tokenIndex);
        }

        // Special case 3: ${...}, @{...}, %{...} - braced variable forms
        // PRE-CHECK: If next token is '{', skip identifier parsing and go directly to parseBracedVariable
        // This avoids backtracking and heredoc processing issues
        if (nextToken.text.equals("{")) {
            return parseBracedVariable(parser, sigil, false);
        }

        // Detect bare $# (no array name follows) — deprecated since Perl 5.30
        if (sigil.equals("$#")) {
            LexerToken afterSigil = nextNonWsToken;
            if (afterSigil.type != LexerTokenType.IDENTIFIER
                    && afterSigil.type != LexerTokenType.NUMBER
                    && !afterSigil.text.equals("{")
                    && !afterSigil.text.equals("[")
                    && !afterSigil.text.equals("$")
                    && !afterSigil.text.equals("'")
                    && !afterSigil.text.equals("+")
                    && !afterSigil.text.equals("-")
                    && !afterSigil.text.equals("^")) {
                parser.throwCleanError("$# is no longer supported as of Perl 5.30");
            }
        }

        // Normal variable parsing: try to parse an identifier
        // Store the current position before parsing the identifier
        int startIndex = parser.tokenIndex;

        String varName = IdentifierParser.parseComplexIdentifier(parser, sigil.equals("*"));
        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("Parsing variable: " + varName);

        if (varName != null) {
            if (varName.isEmpty()) {
                parser.throwError("syntax error");
            }
            IdentifierParser.validateIdentifier(parser, varName, startIndex);

            // Variable name is valid.
            // Check for illegal characters after a variable
            if (!parser.parsingForLoopVariable && !parser.parsingIndirectObject && peek(parser).text.equals("(") && !sigil.equals("&")) {
                // Parentheses are only allowed after a variable in specific cases:
                // - `for my $v (...`
                // - `&name(...`
                // - `obj->$name(...`
                parser.throwError("syntax error");
            }

            // Typeglob vivification: *name creates a glob entry if it doesn't exist
            // This is important for distinguishing file handles from barewords
            if (sigil.equals("*")) {
                // Vivify the GLOB if it doesn't exist yet
                // This helps distinguish between file handles and other barewords
                String fullName = NameNormalizer.normalizeVariableName(varName, parser.ctx.symbolTable.getCurrentPackage());
                GlobalVariable.getGlobalIO(fullName);
            }

            // ===== CLASS FIELD TRANSFORMATION =====
            // In Perl's class system (use feature 'class'), field variables are automatically
            // transformed to access $self->{field} when used inside methods.
            //
            // Example:
            //   class Point {
            //     field $x;
            //     method move($dx) {
            //       $x += $dx;  # Automatically becomes: $self->{x} += $dx
            //     }
            //   }
            //
            // Transformation rules:
            // 1. Only applies inside methods (not in regular subs or package code)
            // 2. Only if the field exists in the current class or parent classes
            // 3. Only if not shadowed by a local variable (my/our/state)
            //
            // Transformation by sigil:
            // - $field  -> $self->{field}        (scalar field access)
            // - @field  -> @{$self->{field}}     (array field dereference)
            // - %field  -> %{$self->{field}}     (hash field dereference)

            String localVar = sigil + varName;

            // Check if this is a field (in current or parent class) and not a locally declared variable
            // Note: We check if the variable is NOT defined locally (only in current scope)
            // but we DO check for fields in all scopes (fields are in parent scope)

            if (parser.isInMethod
                    && isFieldInClassHierarchy(parser, varName)
                    && parser.ctx.symbolTable.getVariableIndexInCurrentScope(localVar) == -1) {
                // This is a field and not shadowed by a local variable
                // Transform field access based on sigil type

                // Create $self variable reference
                OperatorNode selfVar = new OperatorNode("$",
                        new IdentifierNode("self", parser.tokenIndex), parser.tokenIndex);

                // Create hash subscript for field access: {fieldname}
                List<Node> keyList = new ArrayList<>();
                keyList.add(new IdentifierNode(varName, parser.tokenIndex));
                HashLiteralNode hashSubscript = new HashLiteralNode(keyList, parser.tokenIndex);

                // Create $self->{fieldname} access
                Node fieldAccess = new BinaryOperatorNode("->", selfVar, hashSubscript, parser.tokenIndex);

                // For array and hash fields, we need to dereference the reference
                // because fields are stored as references in the object hash
                if (sigil.equals("@") || sigil.equals("%")) {
                    // @field becomes @{$self->{field}}
                    // %field becomes %{$self->{field}}
                    return new OperatorNode(sigil, fieldAccess, parser.tokenIndex);
                } else {
                    // Scalar fields: $field becomes $self->{field}
                    return fieldAccess;
                }
            }

            // Check strict vars at parse time — catches undeclared variables in
            // lazily-compiled named sub bodies that would otherwise be missed
            checkStrictVarsAtParseTime(parser, sigil, varName);

            // Normal variable: create a simple variable reference node
            return new OperatorNode(sigil, new IdentifierNode(varName, parser.tokenIndex), parser.tokenIndex);
        } else if (peek(parser).text.equals("{")) {
            // Handle curly brackets - use parseBracedVariable instead of parseBlock
            return parseBracedVariable(parser, sigil, false);
        }

        // Not a variable name, not a block. This could be a dereference like @$a
        // Parse the expression with the appropriate precedence
        operand = parser.parseExpression(parser.getPrecedence("$") + 1);
        return new OperatorNode(sigil, operand, parser.tokenIndex);
    }

    /**
     * Check strict vars at parse time for an unqualified variable.
     * This catches undeclared variables inside lazily-compiled named sub bodies
     * that would otherwise only be detected at call time (or never).
     * Mirrors the exemption logic from EmitVariable.java and BytecodeCompiler.java.
     */
    private static void checkStrictVarsAtParseTime(Parser parser, String sigil, String varName) {
        // Only check $, @, % sigils (not *, &, $#)
        if (!sigil.equals("$") && !sigil.equals("@") && !sigil.equals("%")) return;

        // Skip when parsing a my/our/state declaration — the variable is being declared
        if (parser.parsingDeclaration) return;

        // Only apply inside named subroutine bodies.  Named subs are compiled
        // lazily, so the existing code-generation strict check never fires at
        // compile time for them.  All other contexts (file-level, anonymous
        // subs, eval STRING) are handled correctly by the code-generation check.
        if (!parser.ctx.symbolTable.isInSubroutineBody()) return;
        String currentSub = parser.ctx.symbolTable.getCurrentSubroutine();
        if (currentSub == null || currentSub.isEmpty()) return;

        // Check if strict vars is enabled in the current scope
        if (!parser.ctx.symbolTable.isStrictOptionEnabled(Strict.HINT_STRICT_VARS)) return;

        // Variable declared lexically (my, our, state) — always allowed
        if (parser.ctx.symbolTable.getSymbolEntry(sigil + varName) != null) return;

        // For $name{...} (hash element) or $name[...] (array element), check the
        // container variable too: $hash{key} is valid if %hash is declared,
        // and $array[0] is valid if @array is declared.
        // Similarly, @name{...} is a hash slice (valid if %name is declared).
        if (sigil.equals("$") || sigil.equals("@")) {
            int peekIdx = Whitespace.skipWhitespace(parser, parser.tokenIndex, parser.tokens);
            if (peekIdx < parser.tokens.size()) {
                String nextText = parser.tokens.get(peekIdx).text;
                if (nextText.equals("{") && parser.ctx.symbolTable.getSymbolEntry("%" + varName) != null) return;
                if (nextText.equals("[") && parser.ctx.symbolTable.getSymbolEntry("@" + varName) != null) return;
            }
        }

        // Qualified names (Pkg::var) — always allowed
        if (varName.contains("::")) return;

        // Regex capture variables ($1, $2, ...) but not $01, $02
        if (ScalarUtils.isInteger(varName) && !varName.startsWith("0")) return;

        // Sort variables $a and $b
        if (sigil.equals("$") && (varName.equals("a") || varName.equals("b"))) return;

        // Built-in special length-one vars ($_, $!, $;, $0, etc.)
        if (sigil.equals("$") && varName.length() == 1 && !Character.isLetter(varName.charAt(0))) return;

        // Built-in special scalar vars (${^GLOBAL_PHASE}, $ARGV, $STDIN, etc.)
        if (sigil.equals("$") && !varName.isEmpty() && varName.charAt(0) < 32) return;
        if (sigil.equals("$") && (varName.equals("ARGV") || varName.equals("ARGVOUT")
                || varName.equals("ENV") || varName.equals("INC") || varName.equals("SIG")
                || varName.equals("STDIN") || varName.equals("STDOUT") || varName.equals("STDERR"))) return;

        // Built-in special container vars (%ENV, %SIG, @ARGV, @INC, etc.)
        if (sigil.equals("%") && (varName.equals("SIG") || varName.equals("ENV")
                || varName.equals("INC") || varName.equals("+") || varName.equals("-")
                || varName.equals("_"))) return;
        if (sigil.equals("@") && (varName.equals("ARGV") || varName.equals("INC")
                || varName.equals("_") || varName.equals("F"))) return;

        // Non-ASCII length-1 scalars under 'no utf8' (Latin-1 range)
        if (sigil.equals("$") && varName.length() == 1) {
            char c = varName.charAt(0);
            if (c > 127 && c <= 255
                    && !parser.ctx.symbolTable.isStrictOptionEnabled(Strict.HINT_UTF8)) return;
        }

        // Check if variable already exists in the global registry (from use vars, etc.)
        String normalizedName = NameNormalizer.normalizeVariableName(
                varName, parser.ctx.symbolTable.getCurrentPackage());
        boolean existsGlobally = false;
        if (sigil.equals("$")) {
            existsGlobally = GlobalVariable.existsGlobalVariable(normalizedName);
            // For $hash{...} and $array[...], also check global container
            if (!existsGlobally) {
                int peekIdx = Whitespace.skipWhitespace(parser, parser.tokenIndex, parser.tokens);
                if (peekIdx < parser.tokens.size()) {
                    String nextText = parser.tokens.get(peekIdx).text;
                    if (nextText.equals("{") && GlobalVariable.existsGlobalHash(normalizedName)) existsGlobally = true;
                    if (nextText.equals("[") && GlobalVariable.existsGlobalArray(normalizedName)) existsGlobally = true;
                }
            }
        } else if (sigil.equals("@")) {
            existsGlobally = GlobalVariable.existsGlobalArray(normalizedName);
            // For @hash{...} (hash slice), also check global hash
            if (!existsGlobally) {
                int peekIdx = Whitespace.skipWhitespace(parser, parser.tokenIndex, parser.tokens);
                if (peekIdx < parser.tokens.size()) {
                    String nextText = parser.tokens.get(peekIdx).text;
                    if (nextText.equals("{") && GlobalVariable.existsGlobalHash(normalizedName)) existsGlobally = true;
                }
            }
        } else if (sigil.equals("%") && !normalizedName.endsWith("::"))
            existsGlobally = GlobalVariable.existsGlobalHash(normalizedName);

        // Single-letter scalars ($A-$Z) bypass strict only if explicitly declared
        // (via use vars or Exporter import), not if merely auto-vivified under 'no strict'.
        if (sigil.equals("$") && varName.length() == 1
                && Character.isLetter(varName.charAt(0))
                && !varName.equals("a") && !varName.equals("b")) {
            if (!GlobalVariable.isDeclaredGlobalVariable(normalizedName)) {
                existsGlobally = false;
            }
        }

        if (existsGlobally) return;

        // Undeclared variable under strict vars
        throw new PerlCompilerException(parser.tokenIndex,
                "Global symbol \"" + sigil + varName
                        + "\" requires explicit package name (did you forget to declare \"my "
                        + sigil + varName + "\"?)",
                parser.ctx.errorUtil);
    }

    /**
     * Parses array and hash access operations within braces (for ${...} constructs).
     * This is similar to parseArrayHashAccess but stops at the closing brace.
     *
     * @param parser  the parser instance
     * @param operand the base variable node to which access operations are applied
     * @param isRegex whether this is in a regex context (affects bracket handling)
     * @return the modified operand with access operations applied
     */
    static Node parseArrayHashAccessInBraces(Parser parser, Node operand, boolean isRegex) {
        while (true) {
            // Skip whitespace, comments, etc. inside braces
            parser.tokenIndex = Whitespace.skipWhitespace(parser, parser.tokenIndex, parser.tokens);

            if (parser.tokenIndex >= parser.tokens.size()) {
                break;
            }

            var token = parser.tokens.get(parser.tokenIndex);
            if (token.text.equals("}")) {
                // Hit the closing brace, stop parsing
                break;
            }

            var text = token.text;
            try {
                switch (text) {
                    case "[" -> {
                        if (isRegex) {
                            // In regex context, '[' might be a character class
                            // Need sophisticated lookahead to distinguish:
                            // $foo[$A] - array subscript (should interpolate)
                            // $foo[$A-Z] - character class (should NOT interpolate)
                            if (!isArraySubscriptInRegex(parser, parser.tokenIndex)) {
                                return operand; // Stop parsing, let caller handle as character class
                            }
                        }
                        operand = ParseInfix.parseInfixOperation(parser, operand, 0);
                        if (operand == null) {
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Missing closing bracket", parser.ctx.errorUtil);
                        }
                        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                    }
                    case "{" -> {
                        // Hash access
                        operand = ParseInfix.parseInfixOperation(parser, operand, 0);
                        if (operand == null) {
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Missing closing brace", parser.ctx.errorUtil);
                        }
                        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                    }
                    case "->" -> {
                        // Method call or dereference
                        var previousIndex = parser.tokenIndex;
                        parser.tokenIndex++;
                        if (parser.tokenIndex < parser.tokens.size()) {
                            text = parser.tokens.get(parser.tokenIndex).text;
                            switch (text) {
                                case "[", "{" -> {
                                    // Dereference followed by access: $var->[0] or $var->{key}
                                    parser.tokenIndex = previousIndex;  // Re-parse "->"
                                    operand = ParseInfix.parseInfixOperation(parser, operand, 0);
                                    if (operand == null) {
                                        throw new PerlCompilerException(parser.tokenIndex, "syntax error: Unterminated dereference", parser.ctx.errorUtil);
                                    }
                                    if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                                }
                                default -> {
                                    // Not a dereference we can handle
                                    parser.tokenIndex = previousIndex;
                                    return operand; // Stop parsing
                                }
                            }
                        } else {
                            parser.tokenIndex = previousIndex;
                            return operand;
                        }
                    }
                    default -> {
                        // No more access operations we recognize
                        return operand;
                    }
                }
            } catch (Exception e) {
                // If parsing fails, throw a more informative error
                throw new PerlCompilerException(parser.tokenIndex, "syntax error: Unterminated array or hash access", parser.ctx.errorUtil);
            }
        }
        return operand;
    }

    /**
     * Parses array and hash access operations following a variable.
     *
     * @param parser  the parser instance
     * @param operand the base variable node to which access operations are applied
     * @param isRegex whether this is in a regex context (affects bracket handling)
     * @return the modified operand with access operations applied
     */
    static Node parseArrayHashAccess(Parser parser, Node operand, boolean isRegex) {
        outerLoop:
        while (true) {
            if (parser.tokenIndex >= parser.tokens.size()) {
                break;
            }

            var token = parser.tokens.get(parser.tokenIndex);
            if (token.type == LexerTokenType.EOF) {
                break;
            }

            var text = token.text;
            try {
                switch (text) {
                    case "[" -> {
                        if (isRegex) {
                            // In regex context, '[' might be a character class
                            // Critical distinction:
                            // 1. Scalar variables: $foo[$A-Z] -> character class (should NOT interpolate)
                            // 2. Array variables: $X[-1] -> array element (should interpolate)

                            // Enhanced parsing logic that considers strict mode context
                            // Key insight: Strict mode affects how $foo[...] is parsed
                            //
                            // In NON-STRICT mode (like t/base/lex.t):
                            //   - $foo[$A-Z] works as character class (barewords allowed)
                            //   - $X[-1] works as array element access
                            //
                            // In STRICT mode:
                            //   - $foo[$A-Z] may cause parsing issues (barewords not allowed)
                            //   - Need more careful disambiguation

                            boolean shouldTreatAsCharacterClass = false;

                            if (operand instanceof OperatorNode opNode && "$".equals(opNode.operator)) {
                                // This is a scalar variable access like $foo or $X
                                // Use enhanced logic to distinguish array subscripts from character classes
                                if (!isArraySubscriptInRegex(parser, parser.tokenIndex)) {
                                    shouldTreatAsCharacterClass = true;
                                }
                            }

                            if (shouldTreatAsCharacterClass) {
                                // This is a character class pattern
                                break outerLoop; // Stop parsing, let caller handle as character class
                            }
                        }

                        // Check for malformed array access (unclosed bracket)
                        int savedIndex = parser.tokenIndex;
                        Node result = null;
                        try {
                            result = ParseInfix.parseInfixOperation(parser, operand, 0);
                        } catch (Exception e) {
                            parser.tokenIndex = savedIndex;
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Unterminated array access", parser.ctx.errorUtil);
                        }

                        if (result == null) {
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Missing closing bracket", parser.ctx.errorUtil);
                        }
                        operand = result;
                        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                    }
                    case "{" -> {
                        // Hash access
                        int savedIndex = parser.tokenIndex;
                        Node result = null;
                        try {
                            result = ParseInfix.parseInfixOperation(parser, operand, 0);
                        } catch (Exception e) {
                            parser.tokenIndex = savedIndex;
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Unterminated hash access", parser.ctx.errorUtil);
                        }

                        if (result == null) {
                            throw new PerlCompilerException(parser.tokenIndex, "syntax error: Missing closing brace", parser.ctx.errorUtil);
                        }
                        operand = result;
                        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                    }
                    case "->" -> {
                        // Method call or dereference
                        var previousIndex = parser.tokenIndex;
                        parser.tokenIndex++;
                        if (parser.tokenIndex < parser.tokens.size()) {
                            text = parser.tokens.get(parser.tokenIndex).text;
                            switch (text) {
                                case "[", "{" -> {
                                    // Dereference followed by access: $var->[0] or $var->{key}
                                    parser.tokenIndex = previousIndex;  // Re-parse "->"
                                    Node result = ParseInfix.parseInfixOperation(parser, operand, 0);
                                    if (result == null) {
                                        throw new PerlCompilerException(parser.tokenIndex, "syntax error: Unterminated dereference", parser.ctx.errorUtil);
                                    }
                                    operand = result;
                                    if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("str operand " + operand);
                                }
                                default -> {
                                    // Not a dereference we can handle
                                    parser.tokenIndex = previousIndex;
                                    break outerLoop;
                                }
                            }
                        } else {
                            parser.tokenIndex = previousIndex;
                            break outerLoop;
                        }
                    }
                    default -> {
                        // No more access operations
                        break outerLoop;
                    }
                }
            } catch (PerlCompilerException e) {
                // Re-throw PerlCompilerExceptions as-is
                throw e;
            } catch (Exception e) {
                // Convert other exceptions to PerlCompilerException
                throw new PerlCompilerException(parser.tokenIndex, "syntax error: " + e.getMessage(), parser.ctx.errorUtil);
            }
        }
        return operand;
    }

    /**
     * Parses a code reference variable, handling Perl's `&` code reference parsing rules.
     * This method is responsible for parsing expressions that start with `&`, which in Perl
     * can be used to refer to subroutines or to call them.
     *
     * @param parser the parser instance
     * @param token  The lexer token representing the `&` operator.
     * @return A Node representing the parsed code reference or subroutine call.
     */
    static Node parseCoderefVariable(Parser parser, LexerToken token) {
        int index = parser.tokenIndex;

        // Special case: detect &{sub ...} and parse as code block
        LexerToken nextToken = TokenUtils.peek(parser);
        if (nextToken.text.equals("{")) {
            // Look ahead to see if there's 'sub' after the brace (skipping whitespace)
            int lookAheadIndex = parser.tokenIndex + 1;
            while (lookAheadIndex < parser.tokens.size()) {
                LexerToken afterBrace = parser.tokens.get(lookAheadIndex);
                if (afterBrace.type == LexerTokenType.WHITESPACE) {
                    lookAheadIndex++;
                    continue;
                }
                if (afterBrace.type == LexerTokenType.IDENTIFIER && afterBrace.text.equals("sub")) {
                    // This is &{sub ...} - parse as code block
                    TokenUtils.consume(parser); // consume '{'
                    Node block = ParseBlock.parseBlock(parser);
                    TokenUtils.consume(parser, LexerTokenType.OPERATOR, "}");
                    return new OperatorNode("&", block, index);
                }
                break; // Not whitespace and not 'sub', so exit
            }
        }

        // IMPORTANT: Check for lexical subs BEFORE parsing as a variable
        // This handles &foo where foo is "our sub foo" or "my sub foo"
        LexerToken peeked = TokenUtils.peek(parser);
        if (peeked.type == LexerTokenType.IDENTIFIER) {
            String subName = peeked.text;
            String lexicalKey = "&" + subName;
            SymbolTable.SymbolEntry lexicalEntry = parser.ctx.symbolTable.getSymbolEntry(lexicalKey);

            if (lexicalEntry != null && lexicalEntry.ast() instanceof OperatorNode varNode) {
                // Check if this is an "our sub" - if so, replace with fully qualified name
                Boolean isOurSub = (Boolean) varNode.getAnnotation("isOurSub");
                if (isOurSub != null && isOurSub) {
                    String storedFullName = (String) varNode.getAnnotation("fullSubName");
                    if (storedFullName != null) {
                        // Consume the identifier token
                        TokenUtils.consume(parser);
                        // Create node with fully qualified name
                        Node qualifiedNode = new OperatorNode("&",
                                new IdentifierNode(storedFullName, index), index);

                        // Handle arguments if present
                        Node list;
                        boolean shareArgs = false;
                        if (!TokenUtils.peek(parser).text.equals("(")) {
                            list = atUnderscore(parser);
                            shareArgs = true; // &func shares caller's @_
                        } else {
                            list = ListParser.parseZeroOrMoreList(parser, 0, false, true, false, false);
                        }
                        BinaryOperatorNode callNode = new BinaryOperatorNode("(", qualifiedNode, list, index);
                        if (shareArgs) callNode.setAnnotation("shareCallerArgs", true);
                        return callNode;
                    }
                }

                // Check if this is a "my sub" or "state sub" - use hidden variable
                String hiddenVarName = (String) varNode.getAnnotation("hiddenVarName");
                if (hiddenVarName != null) {
                    // Consume the identifier token
                    TokenUtils.consume(parser);

                    // Get the package where this lexical sub was declared
                    String declaringPackage = (String) varNode.getAnnotation("declaringPackage");

                    // Make the hidden variable name fully qualified with the declaring package
                    String qualifiedHiddenVarName = hiddenVarName;
                    if (declaringPackage != null && !hiddenVarName.contains("::")) {
                        qualifiedHiddenVarName = declaringPackage + "::" + hiddenVarName;
                    }

                    // Create reference to hidden variable: &$hiddenVar
                    // IMPORTANT: For state variables, we need to preserve the ID from the declaration!
                    OperatorNode dollarOp = new OperatorNode("$",
                            new IdentifierNode(qualifiedHiddenVarName, index), index);
                    // Propagate hiddenVarName annotation so that emitters can detect lexical subs
                    // (e.g., for `undef &x` and `defined(&x)` special handling)
                    dollarOp.setAnnotation("hiddenVarName", hiddenVarName);

                    // Copy the ID from the original declaration if it's a state variable
                    if (varNode.operator.equals("state") && varNode.operand instanceof OperatorNode innerNode) {
                        dollarOp.id = innerNode.id;
                    }

                    // If we're taking a reference (\&foo), return &$hiddenVar
                    // This becomes \&$hiddenVar which calls createCodeReference
                    // createCodeReference will detect the CODE value and return it directly
                    // But if the next token is '(', this is a call, not a reference take
                    if (parser.parsingTakeReference && !TokenUtils.peek(parser).text.equals("(")) {
                        return new OperatorNode("&", dollarOp, index);
                    }

                    // Handle arguments for actual calls (&foo or &foo())
                    // Use $hiddenVar directly - the () operator will handle dereferencing
                    Node list;
                    boolean shareArgs = false;
                    if (!TokenUtils.peek(parser).text.equals("(")) {
                        list = atUnderscore(parser);
                        shareArgs = true; // &func shares caller's @_
                    } else {
                        list = ListParser.parseZeroOrMoreList(parser, 0, false, true, false, false);
                    }
                    BinaryOperatorNode callNode = new BinaryOperatorNode("(", dollarOp, list, index);
                    if (shareArgs) callNode.setAnnotation("shareCallerArgs", true);
                    return callNode;
                }
            }
        }

        // Set a flag to allow parentheses after a variable, as in &$sub(...)
        parser.parsingForLoopVariable = true;
        // Parse the variable following the `&` sigil
        Node node = parseVariable(parser, token.text);
        // Reset the flag after parsing
        parser.parsingForLoopVariable = false;

        // If we are parsing a reference (e.g., \&sub or defined(&sub)),
        // return the node without adding parameters.
        // But if the next token is '(', this is a call like defined(&$sub("args")),
        // so we should parse the arguments and treat it as a call.
        if (parser.parsingTakeReference && !peek(parser).text.equals("(")) {
            return node;
        }

        if (CompilerOptions.DEBUG_ENABLED) parser.ctx.logDebug("parse & node: " + node);

        // Check if the node is an OperatorNode with a BinaryOperatorNode operand
        if (node instanceof OperatorNode operatorNode) {
            if (operatorNode.operand instanceof IdentifierNode identifierNode
                    && identifierNode.name.equals("CORE::__SUB__")
                    && parser.ctx.symbolTable.isFeatureCategoryEnabled("current_sub")) {
                // &CORE::__SUB__
                return new OperatorNode("__SUB__", new ListNode(index), index);
            }

            if (operatorNode.operand instanceof BinaryOperatorNode binaryOperatorNode) {
                // If the operator is `(`, return the BinaryOperatorNode directly
                if (binaryOperatorNode.operator.equals("(")) {
                    return binaryOperatorNode;
                }
            }
        }

        Node list;
        boolean shareArgs = false;
        // If the next token is not `(`, handle auto-call by transforming `&subr` to `&subr(@_)`
        if (!peek(parser).text.equals("(")) {
            list = atUnderscore(parser);
            shareArgs = true; // &func shares caller's @_
        } else {
            // Otherwise, parse the list of arguments
            list = ListParser.parseZeroOrMoreList(parser,
                    0,
                    false,
                    true,
                    false,
                    false);
        }

        // Handle cases where the node is an OperatorNode
        if (node instanceof OperatorNode operatorNode) {
            // If the operand is another OperatorNode, transform &$sub to $sub(@_)
            if (operatorNode.operand instanceof OperatorNode) {
                node = operatorNode.operand;
            } else if (operatorNode.operand instanceof BlockNode blockNode) {
                // If the operand is a BlockNode, transform &{$sub} to $sub(@_)
                node = blockNode;
            }
        }

        // Return a new BinaryOperatorNode representing the function call with arguments
        BinaryOperatorNode callNode = new BinaryOperatorNode("(", node, list, parser.tokenIndex);
        if (shareArgs) callNode.setAnnotation("shareCallerArgs", true);
        return callNode;
    }

    /**
     * Parses a braced variable expression like {@code ${var}} or {@code ${expr}}.
     *
     * <p>This method handles various braced forms:
     * <ul>
     *   <li>Simple braced variables: {@code ${var}}, {@code @{array}}, {@code %{hash}}</li>
     *   <li>Complex expressions: {@code ${$ref}}, {@code ${expr}}</li>
     *   <li>Array/hash access: {@code ${array[0]}}, {@code ${hash{key}}}</li>
     *   <li>Empty braces: {@code ${}} (returns empty string)</li>
     * </ul>
     *
     * <p>The method is shared between regular variable parsing and string interpolation.
     * When used in string interpolation context, it handles special escaping rules for
     * quotes inside the braces (e.g., {@code "${\"quoted\"}"})</p>
     *
     * @param parser                the parser instance
     * @param sigil                 the sigil that precedes the braced expression ($, @, %, etc.)
     * @param isStringInterpolation true if parsing within a string interpolation context
     * @return A Node representing the parsed braced variable expression
     * @throws PerlCompilerException if the braced expression is malformed or unterminated
     */
    public static Node parseBracedVariable(Parser parser, String sigil, boolean isStringInterpolation) {
        int startLineNumber = parser.ctx.errorUtil.getLineNumber(parser.tokenIndex - 1); // Save line number before peek() side effects
        TokenUtils.consume(parser); // Consume the '{'

        // Check if this is an empty ${} construct
        if (TokenUtils.peek(parser).text.equals("}")) {
            TokenUtils.consume(parser); // Consume the '}'
            return new OperatorNode(sigil, new StringNode("", parser.tokenIndex), parser.tokenIndex);
        }

        // For string interpolation, preprocess \" sequences IN PLACE
        if (isStringInterpolation) {
            int startIndex = parser.tokenIndex;
            int braceLevel = 1;

            while (braceLevel > 0 && parser.tokenIndex < parser.tokens.size()) {
                var token = parser.tokens.get(parser.tokenIndex);
                if (token.type == LexerTokenType.EOF) {
                    break;
                }

                if (token.text.equals("{")) {
                    braceLevel++;
                    parser.tokenIndex++;
                } else if (token.text.equals("}")) {
                    braceLevel--;
                    if (braceLevel == 0) {
                        break; // Don't consume the closing brace yet
                    }
                    parser.tokenIndex++;
                } else if (token.text.equals("\\") && parser.tokenIndex + 1 < parser.tokens.size()) {
                    var nextToken = parser.tokens.get(parser.tokenIndex + 1);
                    if (nextToken.text.equals("\"")) {
                        // Just remove the backslash - the quote token will slide down to current position
                        parser.tokens.remove(parser.tokenIndex);
                        // DON'T increment tokenIndex - the quote is now at the current position
                        // and we want to move past it in the next iteration
                    } else {
                        parser.tokenIndex++;
                    }
                } else {
                    parser.tokenIndex++;
                }
            }

            // Reset to start position and continue with original parsing logic
            parser.tokenIndex = startIndex;
        }

        // Continue with original parsing logic - this preserves context for special variables
        int savedIndex = parser.tokenIndex;

        // Check if this starts with ^ (control character variable)
        String bracedVarName = null;
        if (parser.tokens.get(parser.tokenIndex).text.equals("^")) {
            // Save position before trying to parse ^ variable
            int beforeCaret = parser.tokenIndex;
            parser.tokenIndex++; // consume ^

            // Now parse the identifier part after ^
            String identifier = IdentifierParser.parseComplexIdentifierInner(parser, false);
            if (identifier != null && !identifier.isEmpty()) {
                // Convert ^X to control character as parseComplexIdentifier would do
                char firstChar = identifier.charAt(0);
                String ctrlChar;
                if (firstChar >= 'A' && firstChar <= 'Z') {
                    ctrlChar = String.valueOf((char) (firstChar - 'A' + 1));
                } else if (firstChar >= 'a' && firstChar <= 'z') {
                    ctrlChar = String.valueOf((char) (firstChar - 'a' + 1));
                } else if (firstChar == '@') {
                    ctrlChar = String.valueOf((char) 0);
                } else if (firstChar >= '[' && firstChar <= '_') {
                    ctrlChar = String.valueOf((char) (firstChar - '[' + 27));
                } else if (firstChar == '?') {
                    ctrlChar = String.valueOf((char) 127);
                } else {
                    ctrlChar = String.valueOf(firstChar);
                }
                bracedVarName = ctrlChar + identifier.substring(1);
            } else {
                // Failed to parse identifier after ^, restore position
                parser.tokenIndex = beforeCaret;
            }
        }

        // If we didn't parse a ^ variable, try normal parsing
        if (bracedVarName == null) {
            bracedVarName = IdentifierParser.parseComplexIdentifierInner(parser, true);
        }

        if (bracedVarName != null) {
            // Check if this might be ambiguous with an operator
            boolean isAmbiguous = isAmbiguousOperatorName(bracedVarName);

            // Check if this is potentially an operator (s, m, q, etc.) followed by delimiter
            if (isMaybeOperator(bracedVarName, parser)) {
                // Reset and parse as expression
                parser.tokenIndex = savedIndex;
            } else if (isBuiltinFunctionFollowedByArrow(bracedVarName, parser)) {
                // Built-in function followed by -> should be parsed as expression, not variable
                // Example: @{ shift->{'pagers'} } should be @{ (shift)->{'pagers'} }
                parser.tokenIndex = savedIndex;
            } else {
                Node operand = new OperatorNode(sigil, new IdentifierNode(bracedVarName, parser.tokenIndex), parser.tokenIndex);

                try {
                    int beforeAccess = parser.tokenIndex;
                    operand = parseArrayHashAccessInBraces(parser, operand, isStringInterpolation);

                    // Check if we successfully parsed to the closing brace
                    if (TokenUtils.peek(parser).text.equals("}")) {
                        TokenUtils.consume(parser, LexerTokenType.OPERATOR, "}");

                        // Issue ambiguity warning if needed (not inside string interpolation,
                        // matching Perl 5 which only warns in code context)
                        if (isAmbiguous && !isStringInterpolation) {
                            String accessType = "";
                            if (operand instanceof BinaryOperatorNode binOp) {
                                if (binOp.operator.equals("[")) {
                                    accessType = "[...]";
                                } else if (binOp.operator.equals("{")) {
                                    accessType = "{...}";
                                }
                            }

                            if (accessType.isEmpty()) {
                                // Simple variable like ${s}
                                WarnDie.warn(
                                        new RuntimeScalar("Ambiguous use of ${" + bracedVarName + "} resolved to $" + bracedVarName),
                                        new RuntimeScalar(parser.ctx.errorUtil.errorMessage(parser.tokenIndex, "")),
                                        null, 0
                                );
                            } else {
                                // Array/hash access like ${tr[10]}
                                WarnDie.warn(
                                        new RuntimeScalar("Ambiguous use of ${" + bracedVarName + accessType + "} resolved to $" + bracedVarName + accessType),
                                        new RuntimeScalar(parser.ctx.errorUtil.errorMessage(parser.tokenIndex, "")),
                                        null, 0
                                );
                            }
                        }

                        return operand;
                    } else {
                        // We didn't reach the closing brace, which means there's more content
                        // that couldn't be parsed as array/hash access. This might be an operator.
                        parser.tokenIndex = savedIndex;
                    }
                } catch (Exception e) {
                    if (e instanceof PerlParserException) {
                        throw (PerlParserException) e;
                    }
                    parser.tokenIndex = savedIndex;
                }
            }
        } else {
            parser.tokenIndex = savedIndex;
        }

        // Check for heredoc constructs like ${<<END} which should evaluate to empty string
        // The challenge is distinguishing ${<<END} from ${<...>} where $< is a special variable
        if (parser.tokenIndex < parser.tokens.size()) {
            var currentToken = parser.tokens.get(parser.tokenIndex);
            if (currentToken.text.equals("<")) {
                // Look ahead to see if this is <<IDENTIFIER (heredoc) vs <...> (angle brackets)
                if (parser.tokenIndex + 1 < parser.tokens.size()) {
                    var nextToken = parser.tokens.get(parser.tokenIndex + 1);
                    // If the next token after < is an identifier (not another <), this could be <<IDENTIFIER
                    // We need to check if this pattern matches heredoc syntax
                    if (nextToken.type == LexerTokenType.IDENTIFIER) {
                        // This looks like <<IDENTIFIER - treat as heredoc in ${<<END} context

                        // Skip the < token
                        parser.tokenIndex++;

                        // Get the identifier
                        String identifier = nextToken.text;
                        parser.tokenIndex++; // Skip identifier

                        // Create a heredoc node and add it to the queue for later processing
                        OperatorNode heredocNode = new OperatorNode("HEREDOC", null, parser.tokenIndex);
                        heredocNode.setAnnotation("identifier", identifier);
                        heredocNode.setAnnotation("delimiter", "\""); // Default to double-quoted
                        parser.getHeredocNodes().add(heredocNode);

                        // Consume the closing brace
                        if (!TokenUtils.peek(parser).text.equals("}")) {
                            throw new PerlCompilerException(parser.tokenIndex, "Missing closing brace in variable interpolation", parser.ctx.errorUtil);
                        }
                        TokenUtils.consume(parser, LexerTokenType.OPERATOR, "}");

                        // In ${<<END} context, this evaluates to empty string
                        return new OperatorNode(sigil, new StringNode("", parser.tokenIndex), parser.tokenIndex);
                    }
                }
            }
        }

// Fall back to parsing as a block.
        // When the sigil is %, inner {} should be treated as hash constructor (not block)
        // to match Perl 5's behavior: %{ {map { $_ => 1 } @_} } should parse the inner {} as hashref.
        boolean savedInsideBracedDereference = parser.insideBracedDereference;
        if (sigil.equals("%")) {
            parser.insideBracedDereference = true;
        }
        try {
            BlockNode block = ParseBlock.parseBlock(parser);
            if (!TokenUtils.peek(parser).text.equals("}")) {
                throw new PerlCompilerException(parser.tokenIndex, "Missing closing brace in variable interpolation", parser.ctx.errorUtil);
            }
            TokenUtils.consume(parser, LexerTokenType.OPERATOR, "}");
            if (block.elements.size() == 1 && block.elements.getFirst() instanceof OperatorNode operatorNode && operatorNode.operator.equals("*")) {
                // ${*F} is a fancy way to say $Package::F (glob dereference of bareword)
                // But ${*{expr}} or @{*{expr}} should remain as glob dereference of expression
                // This distinction is critical for Moo's extends which uses:
                //   @{*{_getglob("${target}::ISA")}} = @_
                // Without this check, *{expr} would be incorrectly unwrapped like *F
                if (operatorNode.operand instanceof IdentifierNode identifierNode) {
                    identifierNode.name = NameNormalizer.normalizeVariableName(identifierNode.name, parser.ctx.symbolTable.getCurrentPackage());
                    return new OperatorNode(sigil, operatorNode.operand, parser.tokenIndex);
                }
                // When operand is NOT an IdentifierNode (e.g., it's a block like {expr}),
                // fall through to return the full block as the dereference target
            }
            return new OperatorNode(sigil, block, parser.tokenIndex);
        } catch (Exception e) {
            // Use the saved line number from before peek() side effects
            String fileName = parser.ctx.errorUtil.getFileName();
            String multiLineError = "Missing right curly or square bracket at " + fileName + " line " + startLineNumber + ", at end of line\n" +
                    "syntax error at " + fileName + " line " + startLineNumber + ", at EOF\n" +
                    "Execution of " + fileName + " aborted due to compilation errors.";
            throw new PerlParserException(multiLineError);
        } finally {
            parser.insideBracedDereference = savedInsideBracedDereference;
        }
    }

    /**
     * Checks if the given identifier might be the start of an operator rather than a variable name.
     * This handles cases like ${s|||} where 's' could be either a variable or the substitution operator.
     */
    private static boolean isMaybeOperator(String identifier, Parser parser) {
        // Check if this could be a quote-like operator
        if (isAmbiguousOperatorName(identifier)) {
            // Look at what follows
            if (parser.tokenIndex < parser.tokens.size()) {
                var nextToken = parser.tokens.get(parser.tokenIndex);
                // If followed by a delimiter character (not alphanumeric, _, [, {, or }), it's likely an operator
                if (nextToken.text.length() == 1) {
                    char ch = nextToken.text.charAt(0);
                    // Exclude [ and { because those indicate array/hash access on a variable
                    return !Character.isLetterOrDigit(ch) && ch != '_' && ch != '}' && ch != '[' && ch != '{';
                }
            }
        }
        return false;
    }

    /**
     * Checks if an identifier name could be ambiguous with a Perl operator.
     */
    private static boolean isAmbiguousOperatorName(String identifier) {
        return "s".equals(identifier) || "m".equals(identifier) || "q".equals(identifier) ||
                "qx".equals(identifier) || "qr".equals(identifier) || "y".equals(identifier) ||
                "tr".equals(identifier) || "qq".equals(identifier) || "qw".equals(identifier);
    }

    /**
     * Checks if the identifier is a built-in function that returns a value and is followed by '->'.
     * In contexts like @{ shift->{'key'} }, 'shift' should be parsed as a function call, not as @shift.
     * <p>
     * Example:
     * - @{ shift->{'pagers'} } should be @{ (shift)->{'pagers'} }, not @shift->{'pagers'}
     * - %{ caller(1)->[3] } should be %{ (caller(1))->[3] }, not %caller(1)->[3]
     */
    private static boolean isBuiltinFunctionFollowedByArrow(String identifier, Parser parser) {
        // List of built-in functions that commonly return objects/references
        // and might be used with -> for method calls or dereferences
        switch (identifier) {
            case "shift", "pop", "caller", "bless", "ref", "tied", "prototype",
                 "localtime", "gmtime", "stat", "lstat", "each", "keys", "values" -> {
                // Check if followed by ->
                if (parser.tokenIndex < parser.tokens.size()) {
                    var nextToken = parser.tokens.get(parser.tokenIndex);
                    return "->".equals(nextToken.text);
                }
            }
        }
        return false;
    }

    /**
     * Determines if a '[' in regex context should be treated as an array subscript
     * rather than a character class by looking ahead for character class patterns.
     *
     * <p>This is a critical disambiguation in regex string interpolation. Consider:
     * <pre>
     * /$foo[$A]/    # Array subscript - interpolate $foo[$A]
     * /$foo[$A-Z]/  # Character class - do NOT interpolate, treat as literal
     * /$foo[0]/     # Array subscript - interpolate $foo[0]
     * /$foo[a-z]/   # Character class - do NOT interpolate
     * </pre>
     *
     * <p>The method uses lookahead to detect the pattern:
     * <ul>
     *   <li>Array subscript: {@code [expr]} where expr is a simple variable or number</li>
     *   <li>Character class: {@code [x-y]} where there's a dash indicating a range</li>
     * </ul>
     *
     * @param parser       the parser instance
     * @param bracketIndex the index of the '[' token
     * @return true if this should be treated as array subscript, false for character class
     */
    private static boolean isArraySubscriptInRegex(Parser parser, int bracketIndex) {
        // Look ahead to distinguish between:
        // $foo[$A] - array subscript (should interpolate)
        // $foo[$A-Z] - character class (should NOT interpolate)
        // $foo[0] - array subscript with number (should interpolate)
        // $foo[a-z] - character class (should NOT interpolate)

        int index = bracketIndex + 1; // Skip the '['
        if (index >= parser.tokens.size()) {
            return false; // Incomplete, treat as character class
        }

        var firstToken = parser.tokens.get(index);

        // Handle different token patterns:
        // Array access (should interpolate):
        //   [$A] -> tokens: $, A, ]
        //   [0] -> tokens: 0, ]  
        //   [-1] -> tokens: -, 1, ]
        // Character class (should NOT interpolate):
        //   [$A-Z] -> tokens: $, A, -, Z, ]
        //   [0-9] -> tokens: 0, -, 9, ]
        //   [a-z] -> tokens: a, -, z, ]

        if (firstToken.text.equals("$")) {
            // Variable case: $A, need to skip both $ and A tokens
            index++; // Skip the $ token
            if (index >= parser.tokens.size()) {
                return false; // Incomplete variable, treat as character class
            }
            var variableNameToken = parser.tokens.get(index);
            index++; // Skip the variable name token
        } else if (firstToken.type == LexerTokenType.NUMBER) {
            // Number case: just skip the number token
            index++;
        } else if (firstToken.text.equals("-")) {
            // Negative number case: skip the - and the following number
            index++; // Skip the - token
            if (index >= parser.tokens.size()) {
                return false; // Incomplete, treat as character class
            }
            var numberToken = parser.tokens.get(index);
            if (numberToken.type != LexerTokenType.NUMBER) {
                return false; // Not a negative number, treat as character class
            }
            index++; // Skip the number token
        } else {
            // If it doesn't start with $, number, or -, it's definitely a character class
            return false;
        }

        if (index >= parser.tokens.size()) {
            return true; // Just [$A], [0], or [-1] - treat as array subscript
        }

        var nextToken = parser.tokens.get(index);

        // If followed by '-', it's a character class range
        if (nextToken.text.equals("-")) {
            return false; // Character class pattern like [$A-Z] or [0-9]
        }

        // If followed by ']', it's a simple array subscript
        if (nextToken.text.equals("]")) {
            return true; // Array subscript like [$A], [0], or [-1]
        }

        // For other cases, default to array subscript behavior
        return true;
    }

}