Class IRGenerationContext

java.lang.Object
org.ek9lang.compiler.phase7.generation.IRGenerationContext
public class IRGenerationContext extends Object
Central state management for IR generation, following the proven SymbolsAndScopes pattern.

This context provides stack-based scope management that eliminates parameter threading throughout the IR generation process. It manages the transient stack of scope contexts, provides debug information management, and handles instruction building coordination.

Like SymbolsAndScopes, this class provides the shared state management that allows focused helpers to work together cleanly without complex parameter passing.

  • Constructor Details

    • IRGenerationContext

      public IRGenerationContext(IRContext irContext)
      Create a new IR generation context with existing IRContext. Creates a new CoverageProbePlacer for this module. Use the overload with CoverageProbePlacer for shared module-level coverage tracking.

    • IRGenerationContext

      public IRGenerationContext(IRContext irContext, CoverageProbePlacer sharedProbePlacer)
      Create a new IR generation context with optional shared CoverageProbePlacer. This allows multiple constructs in a module to share probe ID numbering.
      Parameters:
      irContext - The IR context for this generation scope
      sharedProbePlacer - Optional shared probe placer; if null, a new one is created

  • Method Details

    • enterScope

      public void enterScope(String scopeId, DebugInfo debugInfo, IRFrameType frameType)
      Enter a new IR scope context.

    • enterMethodScope

      public void enterMethodScope(String scopeId, DebugInfo debugInfo, IRFrameType frameType)
      Enter a method/function scope with fresh IRContext for counter isolation. Creates new IRContext via copy constructor to ensure fresh temp var and label counters.

    • exitScope

      public void exitScope()
      Exit the current IR scope.

    • currentScopeId

      public String currentScopeId()
      Get current scope ID from the stack.

    • currentDebugInfo

      public Optional<DebugInfo> currentDebugInfo()
      Get current debug info from the stack.

    • hasLeftHandSide

      public boolean hasLeftHandSide()
      Check if current scope has left-hand side.

    • currentFrameType

      public IRFrameType currentFrameType()
      Get current frame type.

    • createDebugInfo

      public DebugInfo createDebugInfo(org.antlr.v4.runtime.tree.ParseTree ctx)
      Create debug info from a parse context.

    • createDebugInfo

      public DebugInfo createDebugInfo(Ek9Token token)
      Create debug info from a token.

    • createDebugInfo

      public DebugInfo createDebugInfo(org.antlr.v4.runtime.Token token)
      Create debug info from an ANTLR token.

    • createDebugInfo

      public DebugInfo createDebugInfo(IToken token)
      Create debug info from an EK9 IToken.

    • createDebugInfoAlways

      public DebugInfo createDebugInfoAlways(org.antlr.v4.runtime.Token token)
      Create debug info ALWAYS, regardless of debug mode flag. Used for require/assert statements where source location is essential for error reporting in production, not just debugging.

    • createDebugInfoAlways

      public DebugInfo createDebugInfoAlways(org.antlr.v4.runtime.tree.ParseTree ctx)
      Create debug info ALWAYS from a parse context, regardless of debug mode flag. Used for require/assert statements where source location is essential for error reporting in production, not just debugging.

    • getCurrentIRContext

      public IRContext getCurrentIRContext()
      Get current IRContext from stack frame (traverses up to find method-level IRContext). Always creates a fresh IRContext for proper counter isolation if none exists.

    • generateTempName

      public String generateTempName()
      Generate a unique temporary variable name.

    • generateScopeId

      public String generateScopeId(String prefix)
      Generate a unique scope identifier.

    • generateBlockLabel

      public String generateBlockLabel(String prefix)
      Generate a unique block label.

    • generateLabelName

      public String generateLabelName(String prefix)
      Generate a unique label name.

    • addInstruction

      public void addInstruction(IRInstr instruction)
      Add instruction to current instruction list.

    • addInstructions

      public void addInstructions(List<IRInstr> instructions)
      Add multiple instructions to current instruction list.

    • extractInstructions

      public List<IRInstr> extractInstructions()
      Get current instruction list and clear it.

    • getCurrentInstructions

      public List<IRInstr> getCurrentInstructions()
      Get current instruction list without clearing.

    • clearInstructions

      public void clearInstructions()
      Clear current instruction list.

    • needsResultVariable

      public boolean needsResultVariable(String returnType)
      Check if we need a result variable for the current context.

    • findFrameOfType

      public Optional<IRStackFrame> findFrameOfType(IRFrameType frameType)
      Navigate back up stack to find frame of specific type.

    • findMethodOrFunctionFrame

      public Optional<IRStackFrame> findMethodOrFunctionFrame()
      Navigate back up stack to find method or function frame.

    • findAggregateFrame

      public Optional<IRStackFrame> findAggregateFrame()
      Navigate back up stack to find aggregate frame.

    • isInFrameType

      public boolean isInFrameType(IRFrameType frameType)
      Check if we're currently in a specific frame type.

    • getParsedModule

      public ParsedModule getParsedModule()
      Get the parsed module from IRContext.

    • getCompilerFlags

      public CompilerFlags getCompilerFlags()
      Get the compiler flags from IRContext.

    • getIRContext

      public IRContext getIRContext()
      Get the underlying IR context.

    • getIRGenerationStack

      public IRGenerationStack getIRGenerationStack()
      Get the IR generation stack (for advanced operations).

    • getStackDepth

      public int getStackDepth()
      Get current stack depth (for debugging).

    • getCoverageProbePlacer

      public CoverageProbePlacer getCoverageProbePlacer()
      Get the coverage probe placer for inserting coverage instrumentation.

      The placer is always available, but only inserts probes when coverage is enabled in compiler flags. This allows generator code to unconditionally call probe methods without checking coverage state.

    • isCoverageEnabled

      public boolean isCoverageEnabled()
      Check if coverage instrumentation is enabled.

    • setTypeParameterMapping

      public void setTypeParameterMapping(PositionalConceptualLookupMapping.Mapping typeMapping)
      Set the active Scenario 3 substitution for parameterized type IR generation.

      The mapping pairs the generic type's conceptual 'type parameters' with the concrete 'type arguments' it was parameterized with, positionally and by symbol - the SAME PositionalConceptualLookupMapping.Mapping phase 6 TypeSubstitution uses, so both phases substitute identically.

      Parameters:
      typeMapping - The conceptual to concrete mapping, or null to clear

    • resolveTypeName

      public String resolveTypeName(ISymbol typeSymbol)
      THE "what concrete type name does this (possibly conceptual) type have inside the current Scenario-3 monomorphisation?" step - use this, and never re-derive a variant.

      Scenario 3 generates a parameterized type's method BODIES by walking the GENERIC type's AST (there is only one AST, shared by every parameterization), so every symbol recorded against that AST carries TEMPLATE types - a bare T, or a dependent parameterisation such as List of T and the Iterator of T that its iterator() returns. Each must be re-pointed at its concrete counterpart before it is emitted. Signatures and fields need none of this: those come from the parameterized symbol itself, already substituted by phase 6.

      This MUST take the type SYMBOL, never its name. A parameterised type's fully qualified name is a one-way SHA-256 digest (_List_<hash over Box::T>), so a template name cannot be decomposed - a name-to-name lookup silently returns the TEMPLATE name and leaks a class that is never generated into the emitted IR (NoClassDefFoundError, or NoSuchMethodError where it leaks into a call's return type). ConceptualTypeReplacement does the substitution structurally, from symbols.

      Parameters:
      typeSymbol - The (possibly conceptual) type symbol
      Returns:
      The concrete type FQN to emit

    • resolveScopeTypeName

      public String resolveScopeTypeName(IScope scope)
      resolveTypeName(ISymbol) for an owning SCOPE that is usually - but not always - a symbol (a method's parent scope, giving the type the method is emitted on). Kept here rather than repeated at each call site so the symbol form, and hence the structural substitution, is never skipped.
      Parameters:
      scope - The scope naming the owning type
      Returns:
      The concrete type FQN to emit