diff --git a/docs/development/proposals/phase-195-pattern4.md b/docs/development/proposals/phase-195-pattern4.md new file mode 100644 index 00000000..37152b63 --- /dev/null +++ b/docs/development/proposals/phase-195-pattern4.md @@ -0,0 +1,106 @@ +# Phase 195: Pattern 4 (Loop with Continue) Implementation Plan + +**Status**: Deferred (not yet implemented) + +## Overview + +Pattern 4 handles loops with `continue` statements that skip to the next iteration. This is the most complex loop pattern due to additional control flow requirements. + +## Why Deferred? + +1. **Continue semantics require additional PHI and control flow analysis** + - Continue creates an additional edge to the loop header + - Requires phi nodes for both continue and normal paths + - More complex than break (which exits the loop) + +2. **Pattern 3 covers most practical cases** + - Pattern 1: Simple while loops + - Pattern 2: Loops with break + - Pattern 3: Loops with if + PHI (most common complex pattern) + - Pattern 4: Loops with continue (less common in practice) + +3. **Lower priority than break/if patterns** + - Break patterns (Pattern 2) are more common + - If + PHI patterns (Pattern 3) handle complex control flow + - Continue can often be refactored using if statements + +## Example Use Case + +```nyash +local i = 0 +local sum = 0 +loop(i < 10) { + i = i + 1 + if (i % 2 == 0) { + continue // Skip even numbers + } + sum = sum + i +} +// sum = 25 (1+3+5+7+9) +``` + +## Implementation Requirements + +When implemented, Pattern 4 lowering will need to: + +1. **Detect continue statements** in the loop body +2. **Generate PHI nodes** for continue target (loop header) +3. **Handle carrier variables** (i, sum) across continue boundaries +4. **Generate exit PHI nodes** for final values after loop + +## Control Flow Diagram + +``` + header + | + v + body + | + /----+----\ + / \ + v v +continue normal + | | + \-----+-------/ + | + v + latch + | + /---+---\ + / \ + v v +loop exit +``` + +## Workaround + +Until Pattern 4 is implemented, use Pattern 3 (if + PHI) instead: + +```nyash +local i = 0 +local sum = 0 +loop(i < 10) { + i = i + 1 + if (not (i % 2 == 0)) { // Invert condition + sum = sum + i + } +} +``` + +## Migration Path + +1. **Pattern 1**: Simple while loops (no break/continue) +2. **Pattern 2**: Loops with break +3. **Pattern 3**: Loops with if + PHI +4. **Pattern 4**: (FUTURE) Loops with continue statements + +## Related Files + +- `src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs` - Stub implementation +- `src/mir/join_ir/lowering/loop_with_continue_minimal.rs` - Lowering logic (TODO) + +## Timeline + +- Phase 195+: Implementation planned but deferred +- Priority: Lower than Pattern 1-3 +- Complexity: High (additional control flow edges) diff --git a/src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs b/src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs index a022fcac..d0f24696 100644 --- a/src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs +++ b/src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs @@ -1,6 +1,21 @@ -//! Pattern 4: Loop with Continue minimal lowerer +//! Phase 195: Pattern 4 (Loop with Continue) - STUB IMPLEMENTATION //! -//! Phase 194+: Structure-based detection for loops with continue statements. +//! **Status**: Not yet implemented. Use Pattern 1-3 for production. +//! +//! **Migration Path**: +//! - Pattern 1: Simple while loops (no break/continue) +//! - Pattern 2: Loops with break +//! - Pattern 3: Loops with if + PHI +//! - Pattern 4: (FUTURE) Loops with continue statements +//! +//! **Why Deferred**: +//! - Continue semantics require additional phi and control flow analysis +//! - Pattern 3 covers most practical cases +//! - Planned for Phase 195+ (lower priority than Break/If patterns) +//! +//! **Feature Gate**: None (returns explicit error, safe fallback) +//! +//! See: docs/development/proposals/phase-195-pattern4.md use crate::ast::ASTNode; use crate::mir::builder::MirBuilder; @@ -35,11 +50,13 @@ pub fn can_lower(_builder: &MirBuilder, ctx: &super::router::LoopPatternContext) /// Phase 194+: Lowering function for Pattern 4 /// +/// **STUB IMPLEMENTATION**: Returns explicit error. Pattern 4 is not yet implemented. +/// /// Wrapper around cf_loop_pattern4_with_continue to match router signature. /// -/// # TODO +/// # Future Implementation Plan /// -/// Implement Pattern 4 lowering logic: +/// When implemented, this will: /// 1. Extract loop variables from condition /// 2. Generate JoinIR with continue support /// 3. Convert JoinModule → MirModule @@ -47,15 +64,22 @@ pub fn can_lower(_builder: &MirBuilder, ctx: &super::router::LoopPatternContext) /// 5. Merge MIR blocks into current_function /// 6. Return Void (loop doesn't produce values) pub fn lower( - builder: &mut MirBuilder, + _builder: &mut MirBuilder, ctx: &super::router::LoopPatternContext, ) -> Result, String> { - builder.cf_loop_pattern4_with_continue(ctx.condition, ctx.body, ctx.func_name, ctx.debug) + Err(format!( + "[cf_loop/pattern4] Pattern 4 (continue) not yet implemented for '{}' loop.\n\ + Use Pattern 1-3 instead (simple while, break, or if+phi patterns).\n\ + See: docs/development/proposals/phase-195-pattern4.md", + ctx.func_name + )) } impl MirBuilder { /// Phase 194+: Pattern 4 (Loop with Continue) minimal lowerer /// + /// **STUB IMPLEMENTATION**: This function is a placeholder for future implementation. + /// /// Handles loops with continue statements that skip to next iteration. /// /// # Example @@ -75,7 +99,7 @@ impl MirBuilder { /// /// # Implementation Status /// - /// **TODO**: This is a stub implementation. Pattern 4 lowering logic needs to be implemented. + /// **NOT IMPLEMENTED**: This is a stub. Pattern 4 lowering logic needs to be implemented. /// /// The lowerer should: /// 1. Detect continue statements in the loop body @@ -91,6 +115,8 @@ impl MirBuilder { /// 4. Create JoinInlineBoundary for input/output mapping /// 5. Merge MIR blocks into current_function /// 6. Return Void (loop doesn't produce values) + #[doc(hidden)] // Not ready for public use + #[allow(dead_code)] // Will be implemented in Phase 195+ pub(in crate::mir::builder) fn cf_loop_pattern4_with_continue( &mut self, condition: &ASTNode,