Class ModuleScope

java.lang.Object
org.ek9lang.compiler.symbols.SymbolTable
org.ek9lang.compiler.symbols.ModuleScope
All Implemented Interfaces:
Serializable, IScope
public class ModuleScope extends SymbolTable
This is a very special scope, because the same 'module name' can be defined in multiple files. So when looking to resolve variables we need to look up the scope tree back to the global (program) scope - but when we get here to this module scope we need to look across all the other modules scopes (with the same module name) to check in those as well. So 'resolve' -> 'resolveInThisModuleOnly' or 'resolveWithEnclosingScope' Then 'resolveInThisModuleOnly' -> scopes * 'resolveInThisScopeOnly' for all in scope in module Also 'resolveInThisModuleOnly' -> scopes * 'resolveReferenceInThisScopeOnly' for all scopes in module Finally 'resolveWithEnclosingScope' -> delegates to 'program' 'resolveByFullyQualifiedSearch' And 'resolveWithEnclosingScope' -> delegates to 'program' 'resolveFromImplicitScopes' (org.ek9.lang etc.).
See Also:

  • Constructor Details

  • Method Details

    • clone

      public ModuleScope clone(SharedThreadContext<CompilableProgram> newContext)
      Create a clone of this ModuleScope.

    • getSourceToken

      public IToken getSourceToken()
      Get the source token for the module declaration.
      Returns:
      the module declaration token, or null if not set

    • setSourceToken

      public void setSourceToken(IToken sourceToken)
      Set the source token for the module declaration.
      Parameters:
      sourceToken - the token from the 'defines module X' declaration

    • putModuleMetric

      public void putModuleMetric(CommonValues key, String value)
      Squirrel a module-level metric (e.g. MODULE_COUPLING) onto this module scope. Written by the phase-5 module checkers during sequential validation.

    • getModuleMetric

      public Optional<String> getModuleMetric(CommonValues key)
      Read a module-level metric previously squirrelled by a phase-5 module checker, if present.

    • addPreBuiltParameterisedTypeNames

      public void addPreBuiltParameterisedTypeNames(Set<String> names)
      Add pre-built parameterized type names discovered during introspection. These are the mangled class names (e.g., _List_8F118296...) for which Java implementations already exist.
      Parameters:
      names - the set of mangled class names

    • addForwardTargetTypeNames

      public void addForwardTargetTypeNames(Set<String> names)
      Record the forward-target-dispatched function type EK9 FQNs discovered during introspection (MutexKey, Comparator). These are stamped with the FORWARD_TARGET flag when their base generic function symbol is defined in this same module (FunctionFactory.newFunction).
      Parameters:
      names - the set of EK9 FQNs (e.g. org.ek9.lang::MutexKey)

    • isForwardTargetType

      public boolean isForwardTargetType(String fullyQualifiedName)
      True if the given EK9 FQN is a forward-target-dispatched function type for THIS module. The set is populated and consumed within the same module (org.ek9.lang), so a local check suffices - unlike pre-built parameterised types, forward-target base functions are defined and stamped in-module.
      Parameters:
      fullyQualifiedName - the function's EK9 FQN (e.g. org.ek9.lang::MutexKey)
      Returns:
      true if that function type is forward-target dispatched

    • addRetentions

      public void addRetentions(Map<String,String> retentions)
      Record the @Ek9Retains reference-retention declarations discovered during introspection, keyed by typeFqn|normalisedSignature. Consumed by OperationFactory to squirrel each onto the matching method/operator symbol (data-touch escape axis §6.3).
      Parameters:
      retentions - the signature-keyed retention DSL map

    • retentionFor

      public String retentionFor(String signatureKey)
      The retention DSL declared for signatureKey (typeFqn|normalisedSignature), or null when none. Keyed per SIGNATURE so two overloads with different retention never collide (§9.1).
      Parameters:
      signatureKey - typeFqn|normalisedSignature
      Returns:
      the joined retention DSL, or null

    • useDirectProgramAccess

      public void useDirectProgramAccess(CompilableProgram program)
      Hold the program for direct read-only access. Call ONLY when nothing can be writing to it.
      Parameters:
      program - the program to read directly, or null to go back through the lock.

    • isPreBuiltParameterisedType

      public boolean isPreBuiltParameterisedType(String mangledName)
      Check if a parameterized type with the given mangled name is pre-built. Pre-built types have existing Java implementations and don't need code generation.

      This method checks ALL ModuleScopes for this module name, not just this one, because pre-built names may be aggregated across multiple source files.

      Parameters:
      mangledName - the mangled name to check (e.g., _List_8F118296...)
      Returns:
      true if a pre-built Java class exists for this parameterized type

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class SymbolTable

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class SymbolTable

    • define

      public void define(ISymbol symbol)
      Every module-level define invalidates any memoised "absent" that was answered from this module. Overridden here rather than in SymbolTable deliberately: that base method also runs for local scopes, aggregates and blocks, and bumping on those would invalidate the memo constantly for defines that cannot change a module-level answer.
      Specified by:
      define in interface IScope
      Overrides:
      define in class SymbolTable

    • defineReference

      public void defineReference(IToken token, ISymbol symbol)
      Add a reference to another construct in another module, so it can be used in shorthand form in this module.

    • getOriginalReferenceLocation

      public Optional<IToken> getOriginalReferenceLocation(SymbolSearch search)
      Returns the original location a reference was made (if present).

    • resolveOrDefine

      public Optional<ISymbol> resolveOrDefine(PossibleGenericSymbol parameterisedSymbol, SemanticErrorReporter errorListener)
      Used when resolving or needing to define a parameterised type, like 'List of String' for example. Now while this moduleScope maybe for the code being parsed and processed, the reference to a generic type like org.ek9.lang::List means that the resulting new type: 'org.ek9.lang::List of org.ek9.lang::String' or 'org.ek9.lang::List of my.mod.area::Widget' will be stored in the module space of the Generic Type. So do not assume this new type will reside in this module scope, it most probably won't.

    • addGenericInGenericReference

      public void addGenericInGenericReference(PossibleGenericSymbol genericSymbol, PossibleGenericSymbol reference, SemanticErrorReporter errorListener)
      Record that a generic type or function's body makes, by INFERENCE in FULL_RESOLUTION, a parameterised type that is still conceptual in the generic's own type parameters (a generic-in-generic reference), and bring it through for every parameterisation of the generic already substituted - see TypeSubstitution.substituteLateReference(PossibleGenericSymbol, PossibleGenericSymbol). Done under the program lock, as every substitution is. Earlier phases record only what is DECLARED, in phase 2 (ResolveDefineExplicitTypeListener), before any substitution - nothing is late then, so nothing is done here.

    • defineOrError

      public boolean defineOrError(ISymbol symbol, SymbolChecker symbolChecker)
      Defines a new symbol and returns true if all when OK But if there were errors created then false is returned. This is expensive in the sense that it does the check and define by owning the re-entrant lock on the compilable program.

    • errorsIfNameDiffersOnlyByCase

      public boolean errorsIfNameDiffersOnlyByCase(ISymbol symbol, SymbolChecker symbolChecker)
      THE case-variant name check for module scope - call this from every path that defines a module-level construct, including any that bypasses defineOrError(ISymbol, SymbolChecker) with a raw define. TextFactory's text 'base' aggregate is exactly such a path, and skipping this made the rule order-dependent (a text base defined before a same-word function went unreported, the reverse order was caught).

      Returns true if an error was added to the error listener.

    • getSymbolsAcrossModule

      public List<ISymbol> getSymbolsAcrossModule()
      THE symbols defined in this module across ALL of its source files - use this, never SymbolTable.getSymbolsForThisScope(), for any question about the whole module.

      A module name can span several source files and each has its own ModuleScope, so getSymbolsForThisScope() answers only for the file this scope was made for. That difference was front-end audit FE31: a text's locale dispatch was built from the scope of the file that happened to create the text's base, so locales declared in any other file were silently unset at runtime - and which ones depended on the order the files were read.

    • resolve

      public Optional<ISymbol> resolve(SymbolSearch search)
      Description copied from class: SymbolTable
      Search and resolve from a symbol search.
      Specified by:
      resolve in interface IScope
      Overrides:
      resolve in class SymbolTable

    • resolveInThisModuleOnly

      public Optional<ISymbol> resolveInThisModuleOnly(SymbolSearch search)
      Looks to resolve search in either the references held or the symbols in all the scopes for this module.

    • resolveInThisScopeOnly

      public Optional<ISymbol> resolveInThisScopeOnly(SymbolSearch search)
      Just does a search in this particular module scope. Which means as there can be multiple module scopes in the name module, this is only a partial search.
      Specified by:
      resolveInThisScopeOnly in interface IScope
      Overrides:
      resolveInThisScopeOnly in class SymbolTable

    • getReferencedSymbols

      public Map<String,ISymbol> getReferencedSymbols()
      The declared references manifest of this module scope — the short-name to resolved-symbol map for every reference entry. Read-only snapshot; the caller reads FQNs off the values. Used by architecture tooling to distinguish declared coupling (a references entry) from ad-hoc inline-FQN coupling.

    • referencedByModule

      public Optional<ISymbol> referencedByModule(String moduleName, String shortName)
      DIAGNOSTIC ONLY - never a resolution route: a qualified name resolves only to what its module defines. The symbol module moduleName imports under shortName with 'references', if any - so an unresolved qualified name can say where the symbol the user probably meant is actually defined (see QualifiedNameHint).

    • resolveReferenceInThisScopeOnly

      public Optional<ISymbol> resolveReferenceInThisScopeOnly(SymbolSearch search)
      Does a check if there is a references of that symbol already held in this module scope. But remember there can be multiple of these per named module.

      Matches by SHORT (unqualified) name, whatever the search's qualification: that is what the duplicate and conflicting reference checks need. It is therefore NOT a resolution route for a qualified name - resolution consults references only for unqualified names (front-end audit FE52/FE62).

    • resolveWithEnclosingScope

      public Optional<ISymbol> resolveWithEnclosingScope(SymbolSearch search)
      Description copied from class: SymbolTable
      This class is the root and so there is no enclosing scope. subclasses will override to provide the scope that encloses them
      Overrides:
      resolveWithEnclosingScope in class SymbolTable

    • clearResolutionMemo

      public void clearResolutionMemo()
      Drop every memoised negative held by this scope. Called at a phase boundary - a negative observed in one phase says nothing about the next.