Class SymbolsAndScopes

java.lang.Object
org.ek9lang.compiler.common.SymbolsAndScopes
public class SymbolsAndScopes extends Object
Used as external helper to record symbols and scopes across the parser. They are held in the parsedModule against specific nodes in the parseTree. This enables later phases to look up the symbols and scopes when it encounters the same node in the parseTree. In this way the symbols get 'fleshed out' with more details in each of the compiler phases. This does push scopes on to the scope stack - that the listener uses. IMPORTANT concepts here: 1. The ParsedModule keeps a record of a Symbol against a ParseTree node 2. The ParsedModule keeps a record of a Scope against a ParseTree node 3. The scopeStack keeps a dynamic position of the current scope stuff is being added to. But the scopeStack is ephemeral - it grows and shrinks based on the language constructs the listener encounters, as stuff is added in - that scope become richer. But when the end of the scope is encountered - it is popped off the scopeStack. All would be lost! - But for the fact that the symbols/scopes were registered against a ParseTree node in the ParsedModule. Hence, it lives on - with all the sub scopes and symbols. This information in the ParsedModule will be enriched further in additional and different passes.
Now also uses a transient CodeFlowAnalyzer to assess whether variables in instruction blocks have been initialised.

  • Constructor Details

    • SymbolsAndScopes

      public SymbolsAndScopes(ParsedModule parsedModule, ScopeStack scopeStack)
      Create a new instance for symbol and scope management. If these types are not resolved then OK with a big exception and stop processing (so suppress get warning).

  • Method Details

    • isExternallyImplemented

      public boolean isExternallyImplemented()

    • isDevSource

      public boolean isDevSource()

    • getModuleScope

      public ModuleScope getModuleScope()

    • getEk9Types

      public Ek9Types getEk9Types()

    • getCodeFlowAnalyzers

      public List<CodeFlowAnalyzer> getCodeFlowAnalyzers()
      Provide access to the set of code flow analyzers being used for flow analysis.

    • getUninitialisedVariables

      public List<ISymbol> getUninitialisedVariables(IScope inScope)

    • isVariableInitialised

      public boolean isVariableInitialised(ISymbol identifierSymbol, IScope inScope)

    • isVariableInitialised

      public boolean isVariableInitialised(ISymbol identifierSymbol)

    • recordSymbolDeclaration

      public void recordSymbolDeclaration(ISymbol identifierSymbol)
      Records a variable against the appropriate scope.

    • recordSymbolDeclaration

      public void recordSymbolDeclaration(ISymbol identifierSymbol, IScope inScope)
      Record variable declaration against a specific scope.

    • recordDeclarationOfVariableUsingResult

      public void recordDeclarationOfVariableUsingResult(ISymbol identifierSymbol)

    • recordDeclarationOfVariableUsingOptional

      public void recordDeclarationOfVariableUsingOptional(ISymbol identifierSymbol)

    • recordDeclarationOfVariableUsingIterator

      public void recordDeclarationOfVariableUsingIterator(ISymbol identifierSymbol)

    • recordSymbolAssignment

      public void recordSymbolAssignment(ISymbol identifierSymbol)
      Record an identifier was assigned and therefore initialised.

    • recordInitialisedReturningVariable

      public void recordInitialisedReturningVariable(ISymbol returningVariable)
      Follow a returning variable that was declared WITH a value: from here on isInitialiserReplaced(ISymbol, IScope) says whether every path has since given it a new one. Records it against the current scope - the callable, switch, try or loop scope it is declared in.

    • recordInitialiserReplaced

      public void recordInitialiserReplaced(ISymbol returningVariable)
      Record a plain assignment to a followed returning variable: on this path its declared value is replaced.

    • isInitialiserReplaced

      public boolean isInitialiserReplaced(ISymbol returningVariable, IScope inScope)
      True when every path to the end of the scope has given the returning variable a new value - the definite assignment E08050 asks of a returning variable with no initialiser, asked of one that has an initialiser - so the value it was declared with cannot be the one returned.

    • recordUnconditionalThrow

      public void recordUnconditionalThrow()
      Record that the current block has just thrown, unconditionally: THE place a throw takes part in deciding whether a returning variable is always initialised (E08050) and whether a later read of a local may see it unset (E08020, phase5/IdentifierReadOrError) - one mark, read by both.

      A path that ends in a throw never continues, so it does not have to set a returning variable or a local (L-THROW, Steve 2026-10-08 for returning variables, 2026-10-11 for locals; Java's definite-assignment rule). Every such variable visible here - a local of any enclosing block, the enclosing function's, method's, operator's or dynamic function's returning variable, and that of any switch/try/while/for expression the throw is inside - is marked initialised in the throw's OWN block scope only. So an if/else or switch arm that throws counts as having set it when the arms are pulled up, a conditional throw does not (its block is one arm of an incomplete construct), and nothing outside that block learns anything.

      The guard for the absence proof: a catch or finally block is a separate scope, so the mark never reaches it, and a read of the variable there is still E08020 / a returning variable's pull-up still E08050. Call this on EXIT of the throw statement, so the thrown expression's own reads are checked first.

    • markSymbolAsInitialised

      public void markSymbolAsInitialised(ISymbol identifierSymbol, IScope inScope)
      Record an identifier was initialised.

    • markSymbolAccessSafe

      public void markSymbolAccessSafe(ISymbol identifierSymbol, IScope inScope)
      Record an identifier as being safe to access.

    • isSymbolAccessSafe

      public boolean isSymbolAccessSafe(ISymbol identifierSymbol)
      true if identifier is safe to access.

    • isSymbolAccessSafe

      public boolean isSymbolAccessSafe(ISymbol identifierSymbol, IScope inScope)
      true if identifier is safe to access within the specified scope (rather than the current top scope). Used by the Walk-0 constructor-field-initialisation pre-pass to query a constructor's body scope at the constructor's exit (the field markings + branch-merges land in the body/instruction-block scope, not the already-popped-to method scope).

    • markOkResultAccessSafe

      public void markOkResultAccessSafe(ISymbol identifierSymbol, IScope inScope)

    • isOkResultAccessSafe

      public boolean isOkResultAccessSafe(ISymbol identifierSymbol)

    • markErrorResultAccessSafe

      public void markErrorResultAccessSafe(ISymbol identifierSymbol, IScope inScope)

    • isErrorResultAccessSafe

      public boolean isErrorResultAccessSafe(ISymbol identifierSymbol)

    • markGetOptionalAccessSafe

      public void markGetOptionalAccessSafe(ISymbol identifierSymbol, IScope inScope)

    • isGetOptionalAccessSafe

      public boolean isGetOptionalAccessSafe(ISymbol identifierSymbol)

    • markNextIteratorAccessSafe

      public void markNextIteratorAccessSafe(ISymbol identifierSymbol, IScope inScope)

    • isNextIteratorAccessSafe

      public boolean isNextIteratorAccessSafe(ISymbol identifierSymbol)

    • enterScope

      public IScope enterScope(org.antlr.v4.runtime.tree.ParseTree ctx)
      Ensure that the correct scope is pushed on to the stack. This method takes a context, retrieves the scope, checks for null and then pushes it.
      Parameters:
      ctx - The contact that must have a scope recorded.

    • enterScope

      public void enterScope(IScope scope)
      To be used to ensure that a scope has been pushed on to the scopeStack.

    • exitScope

      public void exitScope()
      Normally called at the point where the parser listener exits a scope. The scope will be popped off the scopeStack to reveal the parent scope.

    • getTopScope

      public IScope getTopScope()
      Provides access to the top of the scope stack.

    • getParentOfTopScope

      public IScope getParentOfTopScope()

    • traverseBackUpStack

      public Optional<IScope> traverseBackUpStack(IScope.ScopeType scopeType)
      Navigates back up the scope stack to find the first match of the scope type passed in.

    • traverseBackUpStackBeyond

      public Optional<IScope> traverseBackUpStackBeyond(IScope beyond, IScope.ScopeType scopeType)
      As traverseBackUpStack(IScope.ScopeType), considering only the scopes outside beyond. See ScopeStack.traverseBackUpStackBeyond(IScope, IScope.ScopeType).

    • traverseBackUpStackToEnclosingMethod

      public Optional<MethodAndAggregateData> traverseBackUpStackToEnclosingMethod()
      Traversed back up the scope stack to try and locate the enclosing method (if there is one). Clearly the scope might not be within a method and so Optional.empty will result.
      Returns:
      The method and aggregate information if a method was located.

    • traverseBackUpStackToMethodOrFunction

      public Optional<IScopedSymbol> traverseBackUpStackToMethodOrFunction()

    • traverseBackUpStackToNearestAggregate

      public Optional<AggregateSymbol> traverseBackUpStackToNearestAggregate()

    • traverseBackUpStackToNearestAggregateBeyond

      public Optional<AggregateSymbol> traverseBackUpStackToNearestAggregateBeyond(IScope beyond)
      As traverseBackUpStackToNearestAggregate(), considering only the scopes outside beyond. See ScopeStack.traverseBackUpStackToNearestAggregateBeyond(IScope).

    • traverseBackUpStackToEnclosingNamedMethodOrFunction

      public Optional<IScopedSymbol> traverseBackUpStackToEnclosingNamedMethodOrFunction()

    • isWithinLoopScope

      public boolean isWithinLoopScope()
      Checks if the current scope is within a loop (for or while). Used to suppress "not referenced after assignment" errors for variables assigned inside loops, where the assignment will be re-evaluated on each iteration.
      Returns:
      true if currently within a loop scope.

    • resolveOrDefine

      public Optional<ISymbol> resolveOrDefine(PossibleGenericSymbol parameterisedSymbol, SemanticErrorReporter errorListener)
      Resolve or define a parameterised type here. When it is made inside a generic's body and is still conceptual in that generic's own type parameters (List(item) inferring a List of T in Holder of type T) it is recorded as a dependent of the generic - THE route for references found by inference, so every parameterisation of the generic gets its concrete counterpart (GenericBodyReference).

    • ensureParameterisedTypeExpanded

      public void ensureParameterisedTypeExpanded(Object typeOrScope, SemanticErrorReporter errorListener)
      THE pre-step of every phase-3 member resolution on a type: when typeOrScope is a PARAMETERISED type, resolve it here so its methods and operators are expanded - FULL_RESOLUTION cannot wait for the generic's own definition to be walked, because it may be referenced first. Anything else (a plain type, a function, null) is left alone. Three places wrote the instanceof PossibleGenericSymbol && isParameterisedType() test and the resolveOrDefine(PossibleGenericSymbol, SemanticErrorReporter) call (front-end rationalisation B-15); a member lookup on a type calls this first.

    • enterNewSymbol

      public void enterNewSymbol(ISymbol symbol, org.antlr.v4.runtime.tree.ParseTree node)
      A new symbol has been encountered and is defined within the current scope in the scope stack and recorded in the parsedModule against the appropriate node.

    • getRecordedSymbol

      public ISymbol getRecordedSymbol(org.antlr.v4.runtime.tree.ParseTree node)

    • getRecordedScope

      public IScope getRecordedScope(org.antlr.v4.runtime.tree.ParseTree node)

    • recordSymbol

      public void recordSymbol(ISymbol symbol, org.antlr.v4.runtime.tree.ParseTree node)
      Record a symbol against a specific node (so it can be looked up later).

    • enterNewLiteral

      public void enterNewLiteral(ISymbol symbol, org.antlr.v4.runtime.tree.ParseTree node)
      For literals, we only record in the parsedModule.

    • enterNewConstant

      public void enterNewConstant(ISymbol symbol, org.antlr.v4.runtime.tree.ParseTree node, SymbolChecker symbolChecker)
      Create a new constant as declared in the constants section and records the symbol.

    • enterModuleScopedSymbol

      public void enterModuleScopedSymbol(IScopedSymbol symbol, org.antlr.v4.runtime.tree.ParseTree node, SymbolChecker symbolChecker)
      To be used when defining a high level symbol at module scope.

    • defineScopedSymbol

      public void defineScopedSymbol(IScopedSymbol symbol, org.antlr.v4.runtime.tree.ParseTree node)
      Record a new scoped symbol in the current scope on the stack. Also records the symbol as both a scope and a symbol in the parsedModule.

    • enterNewScopedSymbol

      public void enterNewScopedSymbol(IScopedSymbol symbol, org.antlr.v4.runtime.tree.ParseTree node)
      Enter a new scoped symbol and record in parsed module as a symbol and as a scope. Then push the scope on to the working scope stack.

    • enterNewScope

      public void enterNewScope(IScope scope, org.antlr.v4.runtime.tree.ParseTree node)
      Enter a new scope and record in both the parsed module and push on to the working scope stack.

    • recordScopeForStackConsistency

      public void recordScopeForStackConsistency(IScope scope, org.antlr.v4.runtime.tree.ParseTree node)
      There are times in parsing/listening when symbols are already defined (due to a developer error). During this situation we cannot define a new node, but we can detect the duplicate (display errors). But so the scope stack does not get corrupted - it is important to still push the existing scope on to the stack. In this way when the stack is popped everything works out.