Class RecordedSymbols

java.lang.Object

org.ek9lang.compiler.support.RecordedSymbols

public final class RecordedSymbols
extends Object

THE symbol-identity walk over a parse-tree fragment for the compiler and the mcp.oracle tools - use this (moved down from compiler-services with SymbolWrites, 2026-10-04), never a by-NAME walk (a regex over body text, getText().equals(name) on identifier nodes, a set of names).

Why: a name is not a symbol. The symbol-table audit (2026-10-02, EK9_SYMBOL_TABLE_AUDIT_2026_10_02.md) found eight editors that matched by name and so treated a same-named local in a SIBLING scope, a word in a comment or in a String, or a longer name sharing a prefix as the variable they were editing. The compiler has already bound every identifier to the symbol it means (ParsedModule.getRecordedSymbol(ParseTree)); this class reads those bindings and nothing else, so comments and String text can never appear (they are not identifier nodes) and two locals called label in sibling blocks are two different symbols.

• referencedIn(ParsedModule, ParseTree) - every identifier in the fragment the compiler bound to a symbol, in source order (reads AND writes; declarations are declaredIn(ParsedModule, ParseTree)).
• usesOf(ParsedModule, ParseTree, ISymbol) - the references to ONE symbol instance, including the uses inside a dynamic function or class through the copy it captured (aliasesOf(ParsedModule, ParseTree, ISymbol)).
• declaredIn(ParsedModule, ParseTree) - the declarations in the fragment (variables, parameters, loop variables, guards).

The fragment must come from the COMPILED tree of parsedModule (the one the program was built from): a re-parsed copy has no recorded symbols, so every query on it answers empty. Writes are SymbolWrites, which is built on this.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	RecordedSymbols.Reference	One identifier occurrence the compiler bound to a symbol.

Method Summary

Modifier and Type	Method	Description
static Set<ISymbol>	aliasesOf(ParsedModule parsedModule, org.antlr.v4.runtime.tree.ParseTree within, ISymbol symbol)	symbol and every captured copy of it made by a dynamic function or class inside within (transitively: a capture of a capture), as an identity set.
static List<RecordedSymbols.Reference>	declaredIn(ParsedModule parsedModule, org.antlr.v4.runtime.tree.ParseTree fragment)	The declarations in fragment, in source order: variables (x <- 1, x as T: v, the s <- next() of a guard), variable-only declarations (parameters, returns, x as T?) and loop variables.
static List<RecordedSymbols.Reference>	referencedIn(ParsedModule parsedModule, org.antlr.v4.runtime.tree.ParseTree fragment)	Every identifier in fragment that the compiler bound to a symbol, in source order: variables, parameters, properties (bare and through .), functions and methods called, types named, this and super.
static List<RecordedSymbols.Reference>	usesOf(ParsedModule parsedModule, org.antlr.v4.runtime.tree.ParseTree within, ISymbol symbol)	The references in within to symbol - that INSTANCE, never another symbol with the same name - plus the references to the copies of it that dynamic functions and classes inside within captured (a capture is a copy symbol; a += on it mutates the same object).

Methods inherited from class Object

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

Method Details

referencedIn

public static List<RecordedSymbols.Reference> referencedIn(ParsedModule parsedModule,
 org.antlr.v4.runtime.tree.ParseTree fragment)

Every identifier in fragment that the compiler bound to a symbol, in source order: variables, parameters, properties (bare and through .), functions and methods called, types named, this and super. Reads and writes alike (SymbolWrites tells them apart); the NAME of a declaration is not a reference (declaredIn(ParsedModule, ParseTree)). Never a comment, never String text - only the identifiers inside an interpolation hole ${...}, which are code.

usesOf

public static List<RecordedSymbols.Reference> usesOf(ParsedModule parsedModule,
 org.antlr.v4.runtime.tree.ParseTree within,
 ISymbol symbol)

The references in within to symbol - that INSTANCE, never another symbol with the same name - plus the references to the copies of it that dynamic functions and classes inside within captured (a capture is a copy symbol; a += on it mutates the same object).

aliasesOf

public static Set<ISymbol> aliasesOf(ParsedModule parsedModule,
 org.antlr.v4.runtime.tree.ParseTree within,
 ISymbol symbol)

symbol and every captured copy of it made by a dynamic function or class inside within (transitively: a capture of a capture), as an identity set. Each copy is matched through the capture's own argument - (acc) and (total: acc) both capture acc - never by name alone.

declaredIn

public static List<RecordedSymbols.Reference> declaredIn(ParsedModule parsedModule,
 org.antlr.v4.runtime.tree.ParseTree fragment)

The declarations in fragment, in source order: variables (x <- 1, x as T: v, the s <- next() of a guard), variable-only declarations (parameters, returns, x as T?) and loop variables. The node is the declaration rule; RecordedSymbols.Reference.name() is its whole text, so use symbol().getName() for the name.