feat(compiler): CPython parity for min/max key=, enumerate start=, next default, iter sentinel; #[repr(u8)] on OpCode

Author: dylan-sutton-chavez

compiler/src/modules/parser/literals.rs

@@ -379,9 +379,9 @@ impl<'src, I: Iterator<Item = Token>> Parser<'src, I> {
             return true;
         }
 
-        // min()/max() take a `default=` keyword, so keep positional and keyword counts distinct.
-        if name == "min" || name == "max" {
-            let op = if name == "min" { OpCode::CallMin } else { OpCode::CallMax };
+        // min()/max() (`default=`/`key=`) and enumerate() (`start=`) take keywords, so keep positional and keyword counts distinct.
+        if name == "min" || name == "max" || name == "enumerate" {
+            let op = match name.as_str() { "min" => OpCode::CallMin, "max" => OpCode::CallMax, _ => OpCode::CallEnumerate };
             let (pos, kw) = self.parse_args();
             self.chunk.emit(op, ((kw & 0xFF) << 8) | (pos & 0xFF));
             self.chunk.record_call_pos(call_pos);

compiler/src/modules/parser/types.rs

@@ -8,6 +8,7 @@ pub(crate) const MAX_EXPR_DEPTH: usize = 200;
 pub(crate) const MAX_INSTRUCTIONS: usize = 65_535;
 
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[repr(u8)] // <256 variants; guarantees a 1-byte tag for stable bytecode / transmute / jump-table dispatch
 pub enum OpCode {
     LoadConst, LoadName, StoreName, Call, PopTop, ReturnValue, BuildString, CallPrint, CallLen, 
     FormatValue, CallAbs, Minus, CallStr, CallInt, CallRange, Phi, CallChr, CallType, MakeFunction, 

compiler/src/modules/vm/builtins/numeric.rs

@@ -215,18 +215,19 @@ impl<'a> VM<'a> {
         self.push(v); Ok(())
     }
 
-    pub fn call_min(&mut self, op: u16) -> Result<(), VmErr> { self.call_minmax(op, true) }
-    pub fn call_max(&mut self, op: u16) -> Result<(), VmErr> { self.call_minmax(op, false) }
+    pub fn call_min(&mut self, op: u16, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> { self.call_minmax(op, true, chunk, slots) }
+    pub fn call_max(&mut self, op: u16, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> { self.call_minmax(op, false, chunk, slots) }
 
-    fn call_minmax(&mut self, op: u16, is_min: bool) -> Result<(), VmErr> {
+    fn call_minmax(&mut self, op: u16, is_min: bool, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
         let (positional, kw_flat, _np, _nk) = self.parse_call_args(op)?;
-        // Optional `default=` (returned when a single iterable is empty).
+        // Optional `default=` (returned when a single iterable is empty) and `key=` (compare by key(x)).
         let mut default: Option<Val> = None;
+        let mut key: Option<Val> = None;
         for pair in kw_flat.chunks_exact(2) {
-            if matches!(self.heap.try_get(pair[0]), Some(HeapObj::Str(s)) if s == "default") {
-                default = Some(pair[1]);
-            } else {
-                return Err(cold_type("min()/max() got an unexpected keyword argument"));
+            match self.heap.try_get(pair[0]) {
+                Some(HeapObj::Str(s)) if s == "default" => default = Some(pair[1]),
+                Some(HeapObj::Str(s)) if s == "key" => { if !pair[1].is_none() { key = Some(pair[1]); } }
+                _ => return Err(cold_type("min()/max() got an unexpected keyword argument")),
             }
         }
         // One arg iterable; many args are values.
@@ -235,11 +236,21 @@ impl<'a> VM<'a> {
         if items.is_empty() {
             return match default { Some(d) => { self.push(d); Ok(()) }, None => Err(cold_value(label)) };
         }
-        let m = items[1..].iter().try_fold(items[0], |m, &x| {
-            let (l, r) = if is_min { (x, m) } else { (m, x) };
-            self.lt_vals(l, r).map(|lt| if lt { x } else { m })
-        })?;
-        self.push(m); Ok(())
+        // Without a key, compare elements directly; with one, compare key(x) but return the winning element.
+        let keys: Vec<Val> = match key {
+            None => items.clone(),
+            Some(k) => {
+                let mut ks = Vec::with_capacity(items.len());
+                for &x in &items { self.push(k); self.push(x); self.exec_call(1, chunk, slots)?; ks.push(self.pop()?); }
+                ks
+            }
+        };
+        let mut best = 0;
+        for i in 1..items.len() {
+            let (l, r) = if is_min { (keys[i], keys[best]) } else { (keys[best], keys[i]) };
+            if self.lt_vals(l, r)? { best = i; }
+        }
+        self.push(items[best]); Ok(())
     }
 
     pub fn call_sum(&mut self, op: u16) -> Result<(), VmErr> {

compiler/src/modules/vm/builtins/sequence.rs

@@ -221,12 +221,28 @@ impl<'a> VM<'a> {
         self.alloc_and_push_list(items)
     }
 
-    pub fn call_enumerate(&mut self) -> Result<(), VmErr> {
-        let o = self.pop()?;
-        let src = self.extract_iter(o, false)?;
+    pub fn call_enumerate(&mut self, op: u16) -> Result<(), VmErr> {
+        let (positional, kw_flat, _np, _nk) = self.parse_call_args(op)?;
+        if positional.is_empty() || positional.len() > 2 {
+            return Err(cold_type("enumerate() takes 1 or 2 positional arguments"));
+        }
+        // `start` is positional (`enumerate(xs, 5)`) or keyword (`enumerate(xs, start=5)`); default 0.
+        let mut start = if positional.len() == 2 { positional[1] } else { Val::int(0) };
+        for pair in kw_flat.chunks_exact(2) {
+            match self.heap.try_get(pair[0]) {
+                Some(HeapObj::Str(s)) if s == "start" => start = pair[1],
+                _ => return Err(cold_type("enumerate() got an unexpected keyword argument")),
+            }
+        }
+        let start = match self.as_i128(start) {
+            Some(n) => n,
+            None => return Err(cold_type("enumerate() start must be an integer")),
+        };
+        let src = self.extract_iter(positional[0], false)?;
         let mut pairs: Vec<Val> = Vec::with_capacity(src.len());
         for (i, x) in src.into_iter().enumerate() {
-            let t = self.heap.alloc(HeapObj::Tuple(vec![Val::int(i as i64), x]))?;
+            let idx = self.int_to_val(start.checked_add(i as i128))?;
+            let t = self.heap.alloc(HeapObj::Tuple(vec![idx, x]))?;
             pairs.push(t);
         }
         self.alloc_and_push_list(pairs)
@@ -335,21 +351,43 @@ impl<'a> VM<'a> {
         self.extract_iter(o, true)
     }
 
-    /* `iter(x)`, eager flatten into a fresh List drained front-to-back by `next()`. Original isn't touched. Mirrors the universal ABI's `Op::Iter`. */
-    pub fn call_iter(&mut self) -> Result<(), VmErr> {
+    /* `iter(x)`, eager flatten into a fresh List drained front-to-back by `next()`. Original isn't touched. Mirrors the universal ABI's `Op::Iter`. The 2-arg form `iter(callable, sentinel)` calls `callable()` until it returns `sentinel`, eagerly. */
+    pub fn call_iter(&mut self, argc: u16, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
+        if argc == 2 {
+            let sentinel = self.pop()?;
+            let callable = self.pop()?;
+            let mut items: Vec<Val> = Vec::new();
+            loop {
+                self.charge_step()?; // bound the call loop against the op budget
+                self.push(callable);
+                self.exec_call(0, chunk, slots)?;
+                let v = self.pop()?;
+                if eq_vals_with_heap(v, sentinel, &self.heap) { break; }
+                if items.len() >= self.heap.limit() { return Err(cold_heap()); }
+                items.push(v);
+            }
+            return self.alloc_and_push_list(items);
+        }
+        if argc != 1 { return Err(cold_type("iter() takes 1 or 2 arguments")); }
         let o = self.pop()?;
         let items = self.iter_to_vec_general(o)?;
         self.alloc_and_push_list(items)
     }
 
-    pub fn call_next(&mut self) -> Result<(), VmErr> {
+    pub fn call_next(&mut self, argc: u16) -> Result<(), VmErr> {
+        if argc == 0 || argc > 2 { return Err(cold_type("next() takes 1 or 2 arguments")); }
+        // `next(it, default)`: the 2nd arg is returned instead of raising StopIteration on exhaustion.
+        let default = if argc == 2 { Some(self.pop()?) } else { None };
         let o = self.pop()?;
         if !o.is_heap() { return Err(cold_type("next() requires an iterator")); }
         // List path mirrors the ABI's IterNext op so script `next()` and host `Op::IterNext` match.
         if let HeapObj::List(rc) = self.heap.get(o) {
             let rc = rc.clone();
             let mut v = rc.borrow_mut();
-            if v.is_empty() { return Err(VmErr::Raised(s!("StopIteration"))); }
+            if v.is_empty() {
+                drop(v);
+                return match default { Some(d) => { self.push(d); Ok(()) }, None => Err(VmErr::Raised(s!("StopIteration"))) };
+            }
             let item = v.remove(0);
             drop(v);
             self.push(item);
@@ -365,7 +403,7 @@ impl<'a> VM<'a> {
             self.push(result);
             Ok(())
         } else {
-            Err(VmErr::Runtime("StopIteration"))
+            match default { Some(d) => { self.push(d); Ok(()) }, None => Err(VmErr::Runtime("StopIteration")) }
         }
     }
 

compiler/src/modules/vm/handlers/function.rs

@@ -47,12 +47,12 @@ impl<'a> VM<'a> {
             OpCode::CallSorted => self.call_sorted(false),
             OpCode::CallList => self.call_list(chunk, slots),
             OpCode::CallTuple => self.call_tuple(chunk, slots),
-            OpCode::CallEnumerate => self.call_enumerate(),
+            OpCode::CallEnumerate => self.call_enumerate(operand),
             OpCode::CallIsInstance => self.call_isinstance(),
             OpCode::CallRange => self.call_range(operand),
             OpCode::CallRound => self.call_round(operand),
-            OpCode::CallMin => self.call_min(operand),
-            OpCode::CallMax => self.call_max(operand),
+            OpCode::CallMin => self.call_min(operand, chunk, slots),
+            OpCode::CallMax => self.call_max(operand, chunk, slots),
             OpCode::CallSum => self.call_sum(operand),
             OpCode::CallZip => self.call_zip(operand),
             OpCode::CallDict => self.call_dict(operand),
@@ -667,9 +667,10 @@ impl<'a> VM<'a> {
         let expected: Option<u16> = match id {
             Input | Receive => Some(0),
             Len | Abs | Str | Int | Float | Bool | Type | Chr | Ord
-            | Sorted | Enumerate | List | Tuple | Bin | Oct | Hex
-            | Repr | Reversed | Callable | Id | Hash | Next | Sleep
-            | Iter => Some(1),
+            | Sorted | List | Tuple | Bin | Oct | Hex
+            | Repr | Reversed | Callable | Id | Hash | Sleep => Some(1),
+            // Enumerate (start), Next (default), Iter (sentinel) accept an optional 2nd arg; validated in their handlers.
+            Enumerate | Next | Iter => None,
             Divmod | IsInstance | IsSubclass | HasAttr | Map | Filter | DelAttr => Some(2),
             SetAttr => Some(3),
             WithTimeout => Some(2),
@@ -702,8 +703,8 @@ impl<'a> VM<'a> {
             }
             Range => self.call_range(argc),
             Round => self.call_round(argc),
-            Min => self.call_min(argc),
-            Max => self.call_max(argc),
+            Min => self.call_min(argc, chunk, slots),
+            Max => self.call_max(argc, chunk, slots),
             Sum => self.call_sum(argc),
             Zip => self.call_zip(argc),
             Dict => self.call_dict(argc),
@@ -725,7 +726,7 @@ impl<'a> VM<'a> {
             Chr => self.call_chr(),
             Ord => self.call_ord(),
             Sorted => self.call_sorted_with_key(sort_key, sort_reverse, chunk, slots),
-            Enumerate => self.call_enumerate(),
+            Enumerate => self.call_enumerate(argc),
             List => self.call_list(chunk, slots),
             Tuple => self.call_tuple(chunk, slots),
             Bin => self.call_bin(),
@@ -740,14 +741,14 @@ impl<'a> VM<'a> {
             IsInstance => self.call_isinstance(),
             IsSubclass => self.call_issubclass(),
             HasAttr => self.call_hasattr(),
-            Next => self.call_next(),
+            Next => self.call_next(argc),
             Run => self.call_run(argc),
             Sleep => self.call_sleep(),
             Frame => self.call_frame(),
             Receive => self.call_receive(),
             Map => self.call_map(chunk, slots),
             Filter => self.call_filter(chunk, slots),
-            Iter => self.call_iter(),
+            Iter => self.call_iter(argc, chunk, slots),
             Bytes => self.call_bytes(argc),
             Slice => self.call_slice(argc),
             Vars => self.call_vars(),

compiler/tests/cases/vm.json

@@ -2283,5 +2283,17 @@
   {"src": "def add(xs):\n    xs += [9]\nys = [1]\nadd(ys)\nprint(ys)", "output": ["[1, 9]"]},
   {"src": "i = 5\ni += 3\nprint(i)", "output": ["8"]},
   {"src": "s = \"a\"\nt = s\ns += \"b\"\nprint(s, t)", "output": ["ab a"]},
-  {"src": "acc = []\nfor i in range(3):\n    acc += [i]\nprint(acc)", "output": ["[0, 1, 2]"]}
+  {"src": "acc = []\nfor i in range(3):\n    acc += [i]\nprint(acc)", "output": ["[0, 1, 2]"]},
+  {"src": "print(min([1, -5, 3], key=abs))", "output": ["1"]},
+  {"src": "print(max([\"a\", \"bbb\", \"cc\"], key=len))", "output": ["bbb"]},
+  {"src": "print(min([3, 1, 2], key=lambda x: -x))", "output": ["3"]},
+  {"src": "print(max([1, 2, 3], default=0, key=lambda x: -x))", "output": ["1"]},
+  {"src": "print(max([], default=-1, key=abs))", "output": ["-1"]},
+  {"src": "print(list(enumerate([\"a\", \"b\"], 5)))", "output": ["[(5, 'a'), (6, 'b')]"]},
+  {"src": "print(list(enumerate([\"a\", \"b\"], start=10)))", "output": ["[(10, 'a'), (11, 'b')]"]},
+  {"src": "for i, c in enumerate(\"xy\", 1):\n    print(i, c)", "output": ["1 x", "2 y"]},
+  {"src": "it = iter([1])\nprint(next(it))\nprint(next(it, \"done\"))", "output": ["1", "done"]},
+  {"src": "print(next(iter([]), -1))", "output": ["-1"]},
+  {"src": "it = iter([5, 6])\nprint(next(it, 0), next(it, 0), next(it, 0))", "output": ["5 6 0"]},
+  {"src": "def make():\n    n = [0]\n    def f():\n        n[0] += 1\n        return n[0]\n    return f\ng = make()\nprint(list(iter(g, 4)))", "output": ["[1, 2, 3]"]}
 ]

docs/content/reference/builtins.md

@@ -82,7 +82,7 @@ print(round(1.55, 1))
 
 ### min, max
 
-Variadic or single iterable. Accept a `default=` returned when a single iterable is empty; without it an empty input raises `ValueError`. No `key=` (transform inline). Ordering follows `<`: numbers, strings, bytes, and tuples/lists (lexicographic).
+Variadic or single iterable. Accept a `default=` returned when a single iterable is empty; without it an empty input raises `ValueError`. A `key=` function selects the comparison value (the original element is returned). Ordering follows `<`: numbers, strings, bytes, and tuples/lists (lexicographic).
 
 ```python
 print(min(3, 1, 4))
@@ -346,7 +346,7 @@ print(reversed("abc"))
 
 ### enumerate
 
-Pairs each element with its index -> list of `(i, value)` tuples. No `start=`, add the offset yourself.
+Pairs each element with its index -> list of `(i, value)` tuples. A second argument (positional or `start=`) sets the first index.
 
 ```python
 for i, v in enumerate(["a", "b", "c"]):
@@ -379,7 +379,7 @@ print(list(zip([1, 2], [3, 4], [5, 6])))
 
 ### next
 
-`next(iterator)` -> next item. Exhausted -> `StopIteration`. Two-arg `next(it, default)` not supported.
+`next(iterator)` -> next item. Exhausted -> `StopIteration`. Two-arg `next(it, default)` returns `default` instead of raising on exhaustion.
 
 ```python
 it = iter([10, 20, 30])
@@ -396,7 +396,7 @@ print(next(it))
 
 ### iter
 
-`iter(x)` returns a fresh iterator over any iterable (list, tuple, set, dict, range, str, bytes, frozenset). Materialises a snapshot, original never mutated. Two-arg `iter(callable, sentinel)` not supported.
+`iter(x)` returns a fresh iterator over any iterable (list, tuple, set, dict, range, str, bytes, frozenset). Materialises a snapshot, original never mutated. Two-arg `iter(callable, sentinel)` calls `callable()` until it returns `sentinel`, eagerly.
 
 ```python
 it = iter([1, 2, 3])