Record Class ControlFlowChainDetails

java.lang.Object
java.lang.Record
org.ek9lang.compiler.ir.data.ControlFlowChainDetails
public record ControlFlowChainDetails(String result, String chainType, GuardVariableDetails guardDetails, EvaluationVariableDetails evaluationDetails, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DefaultCaseDetails defaultDetails, TryBlockDetails tryBlockDetails, List<IRInstr> finallyBlockEvaluation, DebugInfo debugInfo, String scopeId) extends Record
Record containing all information needed to create a CONTROL_FLOW_CHAIN instruction.

This record aggregates all the necessary data for generating the unified control flow IR, supporting all variants: Question operators, if/else statements, switch statements, guarded assignments, guard variable patterns, and try/catch/finally exception handling.

Used by ControlFlowChainGenerator to coordinate the creation of CONTROL_FLOW_CHAIN instructions with consistent memory management, scope boundaries, and optimization hints.

  • Constructor Details

    • ControlFlowChainDetails

      public ControlFlowChainDetails(String result, String chainType, GuardVariableDetails guardDetails, EvaluationVariableDetails evaluationDetails, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DefaultCaseDetails defaultDetails, TryBlockDetails tryBlockDetails, List<IRInstr> finallyBlockEvaluation, DebugInfo debugInfo, String scopeId)
      Creates an instance of a ControlFlowChainDetails record class.
      Parameters:
      result - the value for the result record component
      chainType - the value for the chainType record component
      guardDetails - the value for the guardDetails record component
      evaluationDetails - the value for the evaluationDetails record component
      returnDetails - the value for the returnDetails record component
      conditionChain - the value for the conditionChain record component
      defaultDetails - the value for the defaultDetails record component
      tryBlockDetails - the value for the tryBlockDetails record component
      finallyBlockEvaluation - the value for the finallyBlockEvaluation record component
      debugInfo - the value for the debugInfo record component
      scopeId - the value for the scopeId record component

  • Method Details

    • createQuestionOperator

      public static ControlFlowChainDetails createQuestionOperator(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for a Question operator (?). STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createNullCoalescing

      public static ControlFlowChainDetails createNullCoalescing(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for a Null Coalescing operator (??). STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createElvisCoalescing

      public static ControlFlowChainDetails createElvisCoalescing(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for an Elvis Coalescing operator (:?). Returns LHS if both memory allocated AND set, otherwise evaluates and returns RHS. STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createComparisonCoalescing

      public static ControlFlowChainDetails createComparisonCoalescing(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId, String chainType)
      Create details for comparison coalescing operators (<?, >?, <=?, >=?). Returns LHS if both operands valid and comparison true, else gracefully handles null/unset. STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createTernaryOperator

      public static ControlFlowChainDetails createTernaryOperator(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for a Ternary operator (condition <- thenValue : elseValue). Returns thenValue if condition is true, else returns elseValue. STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createIfElse

      public static ControlFlowChainDetails createIfElse(String result, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for an if/else statement. STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createIfElseWithGuards

      public static ControlFlowChainDetails createIfElseWithGuards(String result, GuardVariableDetails guardDetails, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for an if/else statement with guard variables. STACK-BASED: scopeId parameter extracted from stack context in generator.

    • createWhileLoop

      public static ControlFlowChainDetails createWhileLoop(List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a while loop (statement form). STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      conditionChain - Single ConditionCaseDetails with loop condition and body
      debugInfo - Debug information
      scopeId - Condition scope ID (_scope_2) where temps are registered
      Returns:
      ControlFlowChainDetails configured for while loop

    • createWhileLoopWithGuards

      public static ControlFlowChainDetails createWhileLoopWithGuards(GuardVariableDetails guardDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a while loop with guard variables (statement form). STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      guardDetails - Guard variable details (guard <- expr())
      conditionChain - Single ConditionCaseDetails with loop condition and body
      debugInfo - Debug information
      scopeId - Condition scope ID (_scope_2) where temps are registered
      Returns:
      ControlFlowChainDetails configured for while loop with guards

    • createDoWhileLoopWithGuards

      public static ControlFlowChainDetails createDoWhileLoopWithGuards(GuardVariableDetails guardDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a do-while loop with guard variables (statement form). STACK-BASED: scopeId parameter extracted from stack context in generator.

      Key difference from while loop: Body executes FIRST (at least once), then condition is evaluated. Backend generates IFNE (jump if true) instead of IFEQ (jump if false).

      Parameters:
      guardDetails - Guard variable details (do guard <- expr() { body } while condition)
      conditionChain - Single ConditionCaseDetails with loop body and condition
      debugInfo - Debug information
      scopeId - Whole loop scope ID (_scope_2) for loop control
      Returns:
      ControlFlowChainDetails configured for do-while loop with guards

    • createSwitchWithGuards

      public static ControlFlowChainDetails createSwitchWithGuards(String result, GuardVariableDetails guardDetails, String evaluationVariable, String evaluationVariableType, String returnVariable, String returnVariableType, List<IRInstr> returnVariableSetup, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for a switch statement with guard variable support. STACK-BASED: scopeId parameter extracted from stack context in generator.

      Uses guard details to determine chain type: - SWITCH_WITH_GUARDS when guards are present - SWITCH when no guards present

    • createTryCatchFinally

      public static ControlFlowChainDetails createTryCatchFinally(String result, GuardVariableDetails guardDetails, ReturnVariableDetails returnDetails, TryBlockDetails tryBlockDetails, List<ConditionCaseDetails> catchHandlers, List<IRInstr> finallyBlockEvaluation, DebugInfo debugInfo, String scopeId)
      Create details for a try/catch/finally construct. STACK-BASED: scopeId parameter extracted from stack context in generator.

      Try/catch/finally uses CONTROL_FLOW_CHAIN with exception handlers as condition cases. Each catch block is represented as a ConditionCaseDetails with EXCEPTION_HANDLER type. The finally block (if present) executes after try/catch completion.

      Parameters:
      result - Result variable for expression forms (null for statement forms)
      guardDetails - Guard variable details for pre-flow (try var <- getValue())
      returnDetails - Return variable details for expression forms
      tryBlockDetails - Try block scope and body evaluation
      catchHandlers - List of catch handlers (each is a ConditionCaseDetails with EXCEPTION_HANDLER type)
      finallyBlockEvaluation - Finally block instructions (empty if no finally)
      debugInfo - Debug information
      scopeId - Outer scope ID for the entire try/catch/finally construct
      Returns:
      ControlFlowChainDetails configured for try/catch/finally

    • createSwitchExpression

      public static ControlFlowChainDetails createSwitchExpression(String result, EvaluationVariableDetails evaluationDetails, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, List<IRInstr> defaultBodyEvaluation, String defaultResult, DebugInfo debugInfo, String scopeId)
      Create details for a switch expression (result <- switch expr).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis).

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      evaluationDetails - Evaluation variable details for the switch expression
      returnDetails - Return variable details from returningParam processing
      conditionChain - List of case conditions with their bodies
      defaultBodyEvaluation - Default case body instructions
      defaultResult - Default case result variable
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for switch expression

    • createForRangeExpression

      public static ControlFlowChainDetails createForRangeExpression(String result, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a for-range expression (result <- for i in start ..< end).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis). The loop accumulates results into the return variable.

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      returnDetails - Return variable details from returningParam processing
      conditionChain - Loop condition with body (single element)
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for for-range expression

    • createForInExpression

      public static ControlFlowChainDetails createForInExpression(String result, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a for-in expression (result <- for item in collection).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis). The loop accumulates results into the return variable.

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      returnDetails - Return variable details from returningParam processing
      conditionChain - Loop condition with body (single element)
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for for-in expression

    • createWhileExpression

      public static ControlFlowChainDetails createWhileExpression(String result, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a while expression (result <- while condition).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis).

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      returnDetails - Return variable details from returningParam processing
      conditionChain - Loop condition with body (single element)
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for while expression

    • createDoWhileExpression

      public static ControlFlowChainDetails createDoWhileExpression(String result, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Create details for a do-while expression (result <- do { body } while condition).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis). Body executes at least once before condition is checked.

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      returnDetails - Return variable details from returningParam processing
      conditionChain - Loop body with condition (single element)
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for do-while expression

    • createTryCatchExpression

      public static ControlFlowChainDetails createTryCatchExpression(String result, ReturnVariableDetails returnDetails, TryBlockDetails tryBlockDetails, List<ConditionCaseDetails> catchHandlers, List<IRInstr> finallyBlockEvaluation, DebugInfo debugInfo, String scopeId)
      Create details for a try-catch expression (result <- try { expr } catch { handler }).

      Expression forms return a value via the return variable declared in returningParam. Guards are NOT supported in expression forms (enforced by semantic analysis).

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      result - The overall result variable for the control flow
      returnDetails - Return variable details from returningParam processing
      tryBlockDetails - Try block scope and body evaluation
      catchHandlers - List of catch handlers as condition cases
      finallyBlockEvaluation - Finally block instructions (empty if no finally)
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for try-catch expression

    • createWhileLoopUnified

      public static ControlFlowChainDetails createWhileLoopUnified(GuardVariableDetails guardDetails, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Unified factory for while loops - automatically selects expression or statement form.

      Selection priority: 1. Expression form if returnDetails has return variable 2. Statement form with guards if guardDetails has guards 3. Plain statement form otherwise

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      guardDetails - Guard variable details (may be empty)
      returnDetails - Return variable details (may be empty)
      conditionChain - Single ConditionCaseDetails with loop condition and body
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for appropriate while form

    • createDoWhileLoopUnified

      public static ControlFlowChainDetails createDoWhileLoopUnified(GuardVariableDetails guardDetails, ReturnVariableDetails returnDetails, List<ConditionCaseDetails> conditionChain, DebugInfo debugInfo, String scopeId)
      Unified factory for do-while loops - automatically selects expression or statement form.

      Selection priority: 1. Expression form if returnDetails has return variable 2. Statement form with guards if guardDetails has guards 3. Plain statement form otherwise

      STACK-BASED: scopeId parameter extracted from stack context in generator.
      Parameters:
      guardDetails - Guard variable details (may be empty)
      returnDetails - Return variable details (may be empty)
      conditionChain - Single ConditionCaseDetails with loop body and condition
      debugInfo - Debug information
      scopeId - Scope ID from stack context
      Returns:
      ControlFlowChainDetails configured for appropriate do-while form

    • getScopeId

      public String getScopeId()
      Get the scope ID extracted from stack context at Details creation time. STACK-BASED: scopeId comes from IRGenerationContext.currentScopeId() where this object is created.

    • toString

      @Nonnull public String toString()
      IR-optimized toString following EK9's bracket-only, no-indentation format. Uses StringBuilder for performance and delegates to Details records for their sections.
      Specified by:
      toString in class Record

    • guardVariables

      public List<String> guardVariables()
      Get guard variables list.

    • guardScopeSetup

      public List<IRInstr> guardScopeSetup()
      Get guard scope setup instructions.

    • guardScopeId

      public String guardScopeId()
      Get guard scope ID.

    • conditionScopeId

      public String conditionScopeId()
      Get condition scope ID.

    • evaluationVariable

      public String evaluationVariable()
      Get evaluation variable.

    • evaluationVariableType

      public String evaluationVariableType()
      Get evaluation variable type.

    • evaluationVariableSetup

      public List<IRInstr> evaluationVariableSetup()
      Get evaluation variable setup instructions.

    • returnVariable

      public String returnVariable()
      Get return variable.

    • returnVariableType

      public String returnVariableType()
      Get return variable type.

    • returnVariableSetup

      public List<IRInstr> returnVariableSetup()
      Get return variable setup instructions.

    • defaultBodyEvaluation

      public List<IRInstr> defaultBodyEvaluation()
      Get default body evaluation instructions.

    • defaultResult

      public String defaultResult()
      Get default result variable.

    • hasGuardVariables

      public boolean hasGuardVariables()
      Check if this construct uses guard variables.

    • hasGuardScope

      public boolean hasGuardScope()
      Check if this construct has a guard scope.

    • hasSharedConditionScope

      public boolean hasSharedConditionScope()
      Check if this construct has a shared condition scope.

    • hasGuardEntryCheck

      public boolean hasGuardEntryCheck()
      Check if this construct has a guard entry check (for WHILE/DO-WHILE loops).

    • guardEntryCheck

      public List<IRInstr> guardEntryCheck()
      Get guard entry check instructions (for WHILE/DO-WHILE loops).

    • guardEntryCheckPrimitive

      public String guardEntryCheckPrimitive()
      Get guard entry check primitive variable name (for WHILE/DO-WHILE loops).

    • hasDefaultCase

      public boolean hasDefaultCase()
      Check if this construct has a default case.

    • tryScopeId

      public String tryScopeId()
      Get try scope ID.

    • tryBodyEvaluation

      public List<IRInstr> tryBodyEvaluation()
      Get try body evaluation instructions.

    • tryBodyResult

      public String tryBodyResult()
      Get try body result variable.

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • result

      public String result()
      Returns the value of the result record component.
      Returns:
      the value of the result record component

    • chainType

      public String chainType()
      Returns the value of the chainType record component.
      Returns:
      the value of the chainType record component

    • guardDetails

      public GuardVariableDetails guardDetails()
      Returns the value of the guardDetails record component.
      Returns:
      the value of the guardDetails record component

    • evaluationDetails

      public EvaluationVariableDetails evaluationDetails()
      Returns the value of the evaluationDetails record component.
      Returns:
      the value of the evaluationDetails record component

    • returnDetails

      public ReturnVariableDetails returnDetails()
      Returns the value of the returnDetails record component.
      Returns:
      the value of the returnDetails record component

    • conditionChain

      public List<ConditionCaseDetails> conditionChain()
      Returns the value of the conditionChain record component.
      Returns:
      the value of the conditionChain record component

    • defaultDetails

      public DefaultCaseDetails defaultDetails()
      Returns the value of the defaultDetails record component.
      Returns:
      the value of the defaultDetails record component

    • tryBlockDetails

      public TryBlockDetails tryBlockDetails()
      Returns the value of the tryBlockDetails record component.
      Returns:
      the value of the tryBlockDetails record component

    • finallyBlockEvaluation

      public List<IRInstr> finallyBlockEvaluation()
      Returns the value of the finallyBlockEvaluation record component.
      Returns:
      the value of the finallyBlockEvaluation record component

    • debugInfo

      public DebugInfo debugInfo()
      Returns the value of the debugInfo record component.
      Returns:
      the value of the debugInfo record component

    • scopeId

      public String scopeId()
      Returns the value of the scopeId record component.
      Returns:
      the value of the scopeId record component