Class GuardedScopeOrchestrator

java.lang.Object

org.ek9lang.compiler.phase7.generator.AbstractGenerator

org.ek9lang.compiler.phase7.generator.GuardedScopeOrchestrator

public final class GuardedScopeOrchestrator
extends AbstractGenerator

Orchestrates the common guard + scope + return variable pattern shared by control flow generators (while, do-while, for-range, for-in, try-catch).

Each control flow construct follows an identical template:

1. Create debug info and enter outer scope
2. Evaluate guard variable (if present)
3. Process returning param for expression form
4. Generate core body (DIFFERS per construct — supplied as lambda)
5. Wrap with guard entry check or scope enter/exit
6. Exit outer scope

Two orchestration methods handle different core body types:

• orchestrate(ParseTree, EK9Parser.PreFlowStatementContext, EK9Parser.ReturningParamContext, Function) — core produces List<IRInstr> (for-range, for-in, try-catch). No-guard path wraps body with explicit SCOPE_ENTER/EXIT.
• orchestrateChain(ParseTree, EK9Parser.PreFlowStatementContext, EK9Parser.ReturningParamContext, Function) — core produces ControlFlowChainDetails (while, do-while). No-guard path delegates to ControlFlowChainGenerator which manages scope internally.

For guards with entry checks (<-, :=?, ?= operators), the guard is checked ONCE at entry. If the check fails, the entire body is skipped via an IF wrapper.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	GuardedScopeOrchestrator.OrchestratorContext	Context record passed to core generator lambdas.

Field Summary

Fields inherited from class AbstractGenerator

debugInfoCreator, instructionBuilder, MAX_MESSAGE_LENGTH, stackContext, typeNameOrException

Constructor Summary

Constructors

Constructor	Description
GuardedScopeOrchestrator(IRGenerationContext stackContext, GeneratorSet generators)

Method Summary

Modifier and Type	Method	Description
List<IRInstr>	orchestrate(org.antlr.v4.runtime.tree.ParseTree ctx, EK9Parser.PreFlowStatementContext preFlowStmt, EK9Parser.ReturningParamContext returningParam, Function<GuardedScopeOrchestrator.OrchestratorContext, List<IRInstr>> coreGenerator)	Orchestrate for constructs whose core produces List<IRInstr>.
List<IRInstr>	orchestrate(org.antlr.v4.runtime.tree.ParseTree ctx, EK9Parser.PreFlowStatementContext preFlowStmt, EK9Parser.ReturningParamContext returningParam, Function<GuardedScopeOrchestrator.OrchestratorContext, List<IRInstr>> coreGenerator, boolean coreManagesReturnSetup)	Orchestrate with control over return-variable setup placement.
List<IRInstr>	orchestrateChain(org.antlr.v4.runtime.tree.ParseTree ctx, EK9Parser.PreFlowStatementContext preFlowStmt, EK9Parser.ReturningParamContext returningParam, Function<GuardedScopeOrchestrator.OrchestratorContext, ControlFlowChainDetails> coreGenerator)	Orchestrate for constructs whose core produces ControlFlowChainDetails.

Methods inherited from class AbstractGenerator

addCoverageProbe, createTempVariable, createTempVariableFromContext, extractReturnType, getRecordedSymbolOrException, processBlockStatements, processBlockStatements, truncateMessage, truncateMessage

Methods inherited from class Object

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

Constructor Details

GuardedScopeOrchestrator

GuardedScopeOrchestrator(IRGenerationContext stackContext,
 GeneratorSet generators)

Method Details

orchestrate

public List<IRInstr> orchestrate(org.antlr.v4.runtime.tree.ParseTree ctx,
 EK9Parser.PreFlowStatementContext preFlowStmt,
 EK9Parser.ReturningParamContext returningParam,
 Function<GuardedScopeOrchestrator.OrchestratorContext, List<IRInstr>> coreGenerator)

Orchestrate for constructs whose core produces List<IRInstr>. Used by for-range, for-in, and try-catch generators.

No-guard path adds explicit SCOPE_ENTER/EXIT around return variable setup and core body. Guard path uses LoopGuardHelper.wrapExpressionFormWithGuardEntryCheck(GuardVariableDetails, List, List, String, DebugInfo) which handles both statement and expression forms (empty returnVariableSetup for statement form).

Parameters:

ctx - The parse tree context for debug info

preFlowStmt - Pre-flow statement with guard (may be null)

returningParam - Returning param for expression form (may be null)

coreGenerator - Lambda that generates the core body instructions

Returns:

Complete IR instructions with scope and guard wrapping

orchestrate

public List<IRInstr> orchestrate(org.antlr.v4.runtime.tree.ParseTree ctx,
 EK9Parser.PreFlowStatementContext preFlowStmt,
 EK9Parser.ReturningParamContext returningParam,
 Function<GuardedScopeOrchestrator.OrchestratorContext, List<IRInstr>> coreGenerator,
 boolean coreManagesReturnSetup)

Orchestrate with control over return-variable setup placement.

When coreManagesReturnSetup is true, the no-guard path does NOT emit ReturnVariableDetails.returnVariableSetup() before the core body; the core generator is responsible for placing the return-variable declaration and its value production itself. This lets try keep the value production inside the guarded try body (so the guarded region is never empty and a resource-referencing initialiser is evaluated after the resource is acquired). The guard path is unaffected: the initialiser stays in setup, preserving the guard-skip contract (returns the initialiser when the body is skipped — E08050).

Parameters:

coreManagesReturnSetup - when true, the no-guard path leaves return-variable setup to the core

orchestrateChain

public List<IRInstr> orchestrateChain(org.antlr.v4.runtime.tree.ParseTree ctx,
 EK9Parser.PreFlowStatementContext preFlowStmt,
 EK9Parser.ReturningParamContext returningParam,
 Function<GuardedScopeOrchestrator.OrchestratorContext, ControlFlowChainDetails> coreGenerator)

Orchestrate for constructs whose core produces ControlFlowChainDetails. Used by while and do-while generators.

No-guard path delegates to ControlFlowChainGenerator which adds SCOPE_ENTER/EXIT internally, so no explicit scope instructions are added here. Guard path distinguishes expression form (with return variable) from statement form: expression form wraps the chain instruction with return variable setup outside IF, statement form wraps directly without return variable.

Parameters:

ctx - The parse tree context for debug info

preFlowStmt - Pre-flow statement with guard (may be null)

returningParam - Returning param for expression form (may be null)

coreGenerator - Lambda that generates the core ControlFlowChainDetails

Returns:

Complete IR instructions with scope and guard wrapping