Generators: yield + eager-list-building MVP

Seventh piece of the Python-ergonomics catch-up. Any fn whose body
contains `yield expr;` is a generator. Calling it runs the body to
completion, collecting yielded values into an Array, and returns the
Array. Composes naturally with `for x in gen` — the for loop just
iterates the result array.

  fn fibs(n) {
      h a = 0;
      h b = 1;
      h k = 0;
      while k < n {
          yield a;
          h t = a + b;
          a = b;
          b = t;
          k = k + 1;
      }
  }
  for v in fibs(10) { ... }   # 0, 1, 1, 2, 3, 5, 8, 13, 21, 34

Implementation strategy — EAGER list-building:

  AST:
    Statement::Yield(Expression) for `yield expr;`

  Detection:
    stmts_contain_yield() — recursive walker matching the existing
    stmts_contain_return() pattern. Generators are statically
    identifiable from the AST.

  Runtime:
    Interpreter gains `yield_stacks: Vec<Vec<Value>>` — a stack of
    yield-collectors for the current call chain. invoke_user_function
    detects a generator body, pushes a fresh collector, runs the
    body, pops the collector, returns Value::Array. The Yield
    statement's executor appends to the top of the stack.

This is NOT a real lazy generator. `yield` in an infinite loop
hangs (the body runs to completion before returning). Honest
trade-off for shipping the syntax now:

  + Composes cleanly with the existing for-loop iteration over
    Value::Array (no for-loop changes needed)
  + No coroutine state machine, no CPS transform, no separate
    iterator object — single Value type covers everything
  + Generator detection is a static AST walk; zero runtime cost
    for non-generator fns
  - Memory grows with yield count (no streaming)
  - Infinite generators don't terminate
  - Side effects between yields can't be observed lazily (caller
    sees the whole sequence at once)

Lazy generators via continuation-passing or stackful coroutines
are future work — the deferred-implementation comment in the
relevant code explains the path. For most uses today
(comprehension-style generation, finite-sequence factories, helper
generators that feed for loops), the eager approach matches
Python's surface behavior exactly.

Tests (examples/tests/test_generators.omc — 8 tests, all pass):
  - yield in a while loop produces an array
  - empty body / zero iterations yields []
  - yield-computed values (squares)
  - yield in if-conditional branch (only-evens)
  - multiple yields per iteration
  - generator composes with for-loop iteration
  - nested generator call (outer generator that uses naturals() inside)
  - yield + substrate primitives (yield nth_fibonacci(i))

Regression: 225 OMC tests pass (was 217 + 8 new generator tests).
All previous suites green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

examples/tests/test_generators.omc

@@ -0,0 +1,154 @@
+# Tests for generator functions (eager-list MVP).
+#
+# Any fn whose body contains `yield expr;` is a generator. Calling
+# it runs the body to completion, collecting each yielded value into
+# an array, and returns the array. This is NOT lazy — `yield` in an
+# infinite loop would hang. Lazy coroutine-based generators are
+# future work; eager list-building lets us ship the syntax and
+# compose with `for x in gen` today.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) {
+    if !cond { test_record_failure(msg); }
+}
+
+# ---- basics ----
+
+fn naturals(n) {
+    h i = 0;
+    while i < n {
+        yield i;
+        i = i + 1;
+    }
+}
+
+fn test_yield_loop() {
+    h r = naturals(5);
+    assert_eq(arr_len(r), 5, "5 values yielded");
+    assert_eq(arr_get(r, 0), 0, "first is 0");
+    assert_eq(arr_get(r, 4), 4, "last is 4");
+}
+
+fn test_yield_empty() {
+    h r = naturals(0);
+    assert_eq(arr_len(r), 0, "zero yields → empty array");
+}
+
+# ---- yield with computed values ----
+
+fn squares(n) {
+    h i = 1;
+    while i <= n {
+        yield i * i;
+        i = i + 1;
+    }
+}
+
+fn test_yield_computed() {
+    h r = squares(4);
+    assert_eq(arr_get(r, 0), 1, "1^2");
+    assert_eq(arr_get(r, 3), 16, "4^2");
+}
+
+# ---- yield in conditional branch ----
+
+fn even_only(n) {
+    h i = 0;
+    while i < n {
+        if i % 2 == 0 {
+            yield i;
+        }
+        i = i + 1;
+    }
+}
+
+fn test_yield_in_if() {
+    h r = even_only(10);
+    assert_eq(arr_len(r), 5, "5 evens in 0..10");
+    assert_eq(arr_get(r, 0), 0, "first even");
+    assert_eq(arr_get(r, 4), 8, "last even");
+}
+
+# ---- multiple yields per loop iteration ----
+
+fn pairs(n) {
+    h i = 0;
+    while i < n {
+        yield i;
+        yield i * 10;
+        i = i + 1;
+    }
+}
+
+fn test_multiple_yields() {
+    h r = pairs(3);
+    assert_eq(arr_len(r), 6, "2 yields × 3 iters");
+    assert_eq(arr_get(r, 0), 0, "first yield, iter 0");
+    assert_eq(arr_get(r, 1), 0, "second yield, iter 0");
+    assert_eq(arr_get(r, 2), 1, "first yield, iter 1");
+    assert_eq(arr_get(r, 3), 10, "second yield, iter 1");
+}
+
+# ---- generator composes with for loop ----
+
+fn fibs(n) {
+    h a = 0;
+    h b = 1;
+    h k = 0;
+    while k < n {
+        yield a;
+        h t = a + b;
+        a = b;
+        b = t;
+        k = k + 1;
+    }
+}
+
+fn test_generator_with_for() {
+    h sum = 0;
+    for v in fibs(10) {
+        sum = sum + v;
+    }
+    # fib(0..9) = 0,1,1,2,3,5,8,13,21,34 — sum = 88
+    assert_eq(sum, 88, "sum of first 10 Fibonaccis");
+}
+
+# ---- nested generators ----
+
+fn outer(n) {
+    h r = naturals(n);
+    h k = 0;
+    while k < arr_len(r) {
+        yield arr_get(r, k) * 2;
+        k = k + 1;
+    }
+}
+
+fn test_nested_generator_call() {
+    h r = outer(4);
+    # naturals(4) = [0,1,2,3], doubled = [0,2,4,6]
+    assert_eq(arr_len(r), 4, "4 values");
+    assert_eq(arr_get(r, 3), 6, "last is 6");
+}
+
+# ---- yield + substrate primitives ----
+
+fn substrate_aligned_fibs(n) {
+    h i = 0;
+    while i < n {
+        yield nth_fibonacci(i);
+        i = i + 1;
+    }
+}
+
+fn test_yield_substrate_primitives() {
+    h r = substrate_aligned_fibs(6);
+    # nth_fibonacci(0..5) = 0, 1, 1, 2, 3, 5
+    assert_eq(arr_get(r, 0), 0, "fib(0)");
+    assert_eq(arr_get(r, 5), 5, "fib(5)");
+}

omnimcode-core/src/ast.rs

@@ -105,6 +105,14 @@ pub enum Statement {
     /// Future work: carry the thrown Value through Err(Value) instead
     /// of stringifying, enabling typed-catch hierarchies.
     Throw(Expression),
+    /// `yield expr` — emit one value from a generator function.
+    /// MVP semantics (eager list-building): a fn containing any Yield
+    /// statement is a generator. Calling it runs the body to completion,
+    /// collecting yielded values into an array, and returns that array.
+    /// This is NOT lazy — infinite generators would hang. Real
+    /// coroutine-based lazy generators are future work; the eager
+    /// list-building approach unlocks the syntactic shape today.
+    Yield(Expression),
     /// `class Name { field1; field2; fn method1(self, ...) { ... } }`
     /// (optional `extends Parent` clause for inheritance).
     ///

omnimcode-core/src/compiler.rs

@@ -992,11 +992,12 @@ impl Compiler {
             Statement::FunctionDef { .. } => {
                 // Function defs hoisted by compile_program(); skip here.
             }
-            Statement::Try { .. } | Statement::Throw(_) => {
+            Statement::Try { .. } | Statement::Throw(_) | Statement::Yield(_) => {
                 // Tree-walk fallback. See Op::ExecStmt comments — full
                 // exception unwind would require a side try-stack and
                 // a Result-aware op dispatch loop. Until that pays for
-                // itself, fall back to the AST walker for try/catch/throw.
+                // itself, fall back to the AST walker for try/catch/
+                // throw/yield.
                 self.emit(Op::ExecStmt(Box::new(s.clone())));
             }
             Statement::ClassDef { .. } => {

omnimcode-core/src/formatter.rs

@@ -199,6 +199,11 @@ fn format_stmt(stmt: &Statement, level: usize, out: &mut String) {
             format_expr(e, out);
             out.push_str(";\n");
         }
+        Statement::Yield(e) => {
+            out.push_str("yield ");
+            format_expr(e, out);
+            out.push_str(";\n");
+        }
         Statement::Match { scrutinee, arms } => {
             out.push_str("match ");
             format_expr(scrutinee, out);

omnimcode-core/src/interpreter.rs

@@ -20,6 +20,13 @@ pub struct Interpreter {
     /// dispatch path walks this chain when `<Child>__<method>` isn't
     /// found, trying `<Parent>__<method>` and so on.
     class_parents: HashMap<String, String>,
+    /// Active yield collector for the current generator frame. Set
+    /// by invoke_user_function when entering a generator fn (one
+    /// whose body contains Yield); each Yield statement appends to
+    /// the top of this stack. On exit, the collector is popped and
+    /// returned as a Value::Array. Stack-of-vecs supports nested
+    /// generator invocations.
+    yield_stacks: Vec<Vec<Value>>,
     /// Optional JIT dispatch hook. When set, `invoke_user_function_at`
     /// consults this BEFORE running the tree-walk body. If the hook
     /// returns `Some(result)`, that result wins; otherwise tree-walk
@@ -105,6 +112,7 @@ impl Interpreter {
             call_stack: Vec::new(),
             host_builtins: HashMap::new(),
             class_parents: HashMap::new(),
+            yield_stacks: Vec::new(),
         }
     }
 
@@ -667,6 +675,9 @@ impl Interpreter {
             Statement::Throw(e) => Statement::Throw(
                 Self::rewrite_call_expr(e, module_names, alias),
             ),
+            Statement::Yield(e) => Statement::Yield(
+                Self::rewrite_call_expr(e, module_names, alias),
+            ),
             Statement::Match { scrutinee, arms } => Statement::Match {
                 scrutinee: Self::rewrite_call_expr(scrutinee, module_names, alias),
                 arms: arms
@@ -1589,6 +1600,18 @@ impl Interpreter {
                 let v = self.eval_expr(expr)?;
                 Err(v.to_display_string())
             }
+            Statement::Yield(expr) => {
+                // Append the yielded value to the current generator
+                // frame's collector (top of yield_stacks). If we're
+                // not inside a generator (no collector pushed), it's
+                // a programming error — but rather than panic, we
+                // accept silently for ergonomics during dev.
+                let v = self.eval_expr(expr)?;
+                if let Some(top) = self.yield_stacks.last_mut() {
+                    top.push(v);
+                }
+                Ok(())
+            }
             _ => Ok(()),
         }
     }
@@ -6895,6 +6918,20 @@ impl Interpreter {
         // and error paths so the trace doesn't leak across calls.
         self.call_stack.push((name.to_string(), call_site));
 
+        // Generator detection: a fn body that contains any Yield
+        // statement is a generator. We push a fresh yield-collector
+        // onto yield_stacks; every Yield in the body appends to it.
+        // On exit, the collector is popped and returned as a
+        // Value::Array. Any explicit `return` inside a generator is
+        // silently ignored (Python's behavior: `return` in a
+        // generator without an expression ends iteration; with an
+        // expression, it becomes the StopIteration value, which OMC
+        // doesn't represent in the eager-list model).
+        let is_generator = stmts_contain_yield(body);
+        if is_generator {
+            self.yield_stacks.push(Vec::new());
+        }
+
         let mut exec_err: Option<String> = None;
         for stmt in body {
             if let Err(e) = self.execute_stmt(stmt) {
@@ -6910,9 +6947,8 @@ impl Interpreter {
         self.locals.pop();
 
         if let Some(e) = exec_err {
-            // Append our own frame + the call site and rethrow.
-            // Each invoke_user_function up the stack does the same,
-            // so the final message lists every frame innermost-first.
+            // Drop the generator's collector on error.
+            if is_generator { self.yield_stacks.pop(); }
             return Err(format!(
                 "{}\n  at {}{}",
                 e,
@@ -6921,6 +6957,14 @@ impl Interpreter {
             ));
         }
 
+        if is_generator {
+            // Return the collected yields as an array. Ignore the
+            // fn's return slot — generators communicate via yield.
+            self.return_value.take();
+            let yields = self.yield_stacks.pop().unwrap_or_default();
+            return Ok(Value::Array(crate::value::HArray::from_vec(yields)));
+        }
+
         let result = self.return_value.take().unwrap_or(Value::Null);
         Ok(result)
     }
@@ -8060,6 +8104,35 @@ fn stmt_contains_return(s: &Statement) -> bool {
     }
 }
 
+/// Does a statement list contain any `yield` statement? Used by the
+/// generator-fn detector — a fn body with at least one Yield is
+/// dispatched through the yield-collector path at call time.
+pub(crate) fn stmts_contain_yield(stmts: &[Statement]) -> bool {
+    for s in stmts {
+        if stmt_contains_yield(s) { return true; }
+    }
+    false
+}
+
+fn stmt_contains_yield(s: &Statement) -> bool {
+    match s {
+        Statement::Yield(_) => true,
+        Statement::If { then_body, elif_parts, else_body, .. } => {
+            stmts_contain_yield(then_body)
+                || elif_parts.iter().any(|(_, b)| stmts_contain_yield(b))
+                || else_body.as_ref().is_some_and(|b| stmts_contain_yield(b))
+        }
+        Statement::While { body, .. } => stmts_contain_yield(body),
+        Statement::For { body, .. } => stmts_contain_yield(body),
+        Statement::Try { body, handler, finally, .. } => {
+            stmts_contain_yield(body)
+                || stmts_contain_yield(handler)
+                || finally.as_ref().is_some_and(|b| stmts_contain_yield(b))
+        }
+        _ => false,
+    }
+}
+
 /// Missing-return heal: for every user fn lacking ANY return statement,
 /// append `return null;` at the tail. Keeps callers from seeing the
 /// confusing "fn ended without return" runtime error — most users mean

omnimcode-core/src/parser.rs

@@ -43,6 +43,7 @@ pub enum Token {
     Match,
     Class,
     Extends,
+    Yield,
     /// f-string template — alternating literal and expression segments.
     /// Parser turns this into `concat_many(parts...)` at expression
     /// position.
@@ -477,6 +478,7 @@ impl Lexer {
                         "throw" => Token::Throw,
                         "class" => Token::Class,
                         "extends" => Token::Extends,
+                        "yield" => Token::Yield,
                         "match" => Token::Match,
                         "and" => Token::And,
                         "or" => Token::Or,
@@ -883,6 +885,15 @@ impl Parser {
                 self.expect(Token::Semicolon)?;
                 Ok(Statement::Throw(expr))
             }
+            Token::Yield => {
+                // `yield expr;` — emit one value from a generator fn.
+                // Eager-list MVP: each yield appends to a collector
+                // that the call boundary turns into a Value::Array.
+                self.advance();
+                let expr = self.parse_expression()?;
+                self.expect(Token::Semicolon)?;
+                Ok(Statement::Yield(expr))
+            }
             Token::Match => self.parse_match_stmt(),
             // `import core;` or `import core as c;` or `load "path";`
             Token::Import | Token::Load => {