feat(vm): add 'key=' and 'reverse=' to 'sorted()' and 'list.sort()'.

Author: dylan-sutton-chavez

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

@@ -74,21 +74,53 @@ impl<'a> VM<'a> {
         self.push(Val::int(n)); Ok(())
     }
 
-    pub fn call_sorted(&mut self) -> Result<(), VmErr> {
+    pub fn call_sorted(&mut self, reverse: bool) -> Result<(), VmErr> {
         let o = self.pop()?;
         let mut items = self.extract_iter(o, false)?;
         self.sort_by_lt(&mut items)?;
+        if reverse { items.reverse(); }
         self.alloc_and_push_list(items)
     }
 
-    /* sorted(iterable, key=fn), decorate-sort-undecorate via a parallel keys vec. key=None delegates to the no-key path. */
-    pub fn call_sorted_with_key(&mut self, key: Option<Val>, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
+    /* sorted(iterable, key=fn, reverse=False) — delegates to call_sorted when key is absent. */
+    pub fn call_sorted_with_key(&mut self, key: Option<Val>, reverse: bool, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
         let key = match key {
             Some(k) if !k.is_none() => k,
-            _ => return self.call_sorted(),
+            _ => return self.call_sorted(reverse),
         };
         let o = self.pop()?;
         let items = self.extract_iter(o, false)?;
+        let mut sorted = self.sort_by_key(items, key, chunk, slots)?;
+        if reverse { sorted.reverse(); }
+        self.alloc_and_push_list(sorted)
+    }
+
+    /* list.sort(key=fn, reverse=False) in-place. Snapshots list before key calls so heap borrow ends before exec_call. */
+    pub fn call_list_sort_keyed(&mut self, recv: Val, key: Option<Val>, reverse: bool, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
+        let items = match self.heap.get(recv) {
+            HeapObj::List(rc) => rc.borrow().clone(),
+            _ => return Err(cold_type("sort: receiver is not a list")),
+        };
+        let mut result = if let Some(k) = key.filter(|k| !k.is_none()) {
+            self.sort_by_key(items, k, chunk, slots)?
+        } else {
+            let mut s = items;
+            self.sort_by_lt(&mut s)?;
+            s
+        };
+        if reverse { result.reverse(); }
+        let rc = match self.heap.get(recv) {
+            HeapObj::List(rc) => rc.clone(),
+            _ => return Err(cold_type("sort: receiver is not a list")),
+        };
+        *rc.borrow_mut() = result;
+        self.mark_impure();
+        self.push(Val::none());
+        Ok(())
+    }
+
+    /* Decorate-sort-undecorate: applies key fn to each item, sorts by resulting keys, returns reordered items. */
+    fn sort_by_key(&mut self, items: Vec<Val>, key: Val, chunk: &crate::modules::parser::SSAChunk, slots: &mut [Val]) -> Result<Vec<Val>, VmErr> {
         let mut keys: Vec<Val> = Vec::with_capacity(items.len());
         for &item in &items {
             self.push(key);
@@ -111,8 +143,7 @@ impl<'a> VM<'a> {
             }
         });
         if let Some(e) = sort_err { return Err(e); }
-        let sorted: Vec<Val> = indices.into_iter().map(|i| items[i]).collect();
-        self.alloc_and_push_list(sorted)
+        Ok(indices.into_iter().map(|i| items[i]).collect())
     }
 
     /* In-place sort via `lt_vals`. Stashes the first error and surfaces it after the sort, `sort_by` closures can't return Result. */

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

@@ -30,7 +30,7 @@ impl<'a> VM<'a> {
             OpCode::CallType => self.call_type(),
             OpCode::CallChr => self.call_chr(),
             OpCode::CallOrd => self.call_ord(),
-            OpCode::CallSorted => self.call_sorted(),
+            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(),
@@ -241,6 +241,23 @@ impl<'a> VM<'a> {
         if let HeapObj::BoundMethod(recv, id) = self.heap.get(callee) {
             let recv = *recv;
             let id = *id;
+            if id.name() == "sort" && !kw_flat.is_empty() {
+                if !positional.is_empty() {
+                    return Err(cold_type("list.sort() takes no positional arguments"));
+                }
+                let mut sort_key: Option<Val> = None;
+                let mut sort_reverse = false;
+                for pair in kw_flat.chunks(2) {
+                    let (name_v, val_v) = (pair[0], pair[1]);
+                    let is_key = name_v.is_heap() && matches!(self.heap.get(name_v), HeapObj::Str(s) if s == "key");
+                    let is_reverse = name_v.is_heap() && matches!(self.heap.get(name_v), HeapObj::Str(s) if s == "reverse");
+                    if is_key { sort_key = Some(val_v); }
+                    else if is_reverse { sort_reverse = self.truthy(val_v); }
+                    else { return Err(cold_type("list.sort() got unexpected keyword argument")); }
+                }
+                self.call_list_sort_keyed(recv, sort_key, sort_reverse, chunk, slots)?;
+                return Ok(true);
+            }
             self.exec_bound_method(recv, id, positional, kw_flat)?;
             return Ok(true);
         }
@@ -594,20 +611,19 @@ impl<'a> VM<'a> {
     pub(crate) fn dispatch_native(&mut self, id: super::super::types::NativeFnId, positional: &[Val], kw: &[Val], chunk: &SSAChunk, slots: &mut [Val]) -> Result<(), VmErr> {
         use super::super::types::NativeFnId::*;
 
-        // `sorted()` is the only builtin taking kwargs (`key=fn`); extract it before the no-kw guard.
+        // `sorted()` is the only builtin taking kwargs (`key=`, `reverse=`); extract them before the no-kw guard.
         let mut sort_key: Option<Val> = None;
+        let mut sort_reverse = false;
         let leftover_storage: Vec<Val>;
         let kw_remaining: &[Val] = if id == Sorted {
             let mut leftover: Vec<Val> = Vec::new();
             for chunk_pair in kw.chunks(2) {
                 let (name_v, val_v) = (chunk_pair[0], chunk_pair[1]);
                 let is_key = name_v.is_heap() && matches!(self.heap.get(name_v), HeapObj::Str(s) if s == "key");
-                if is_key {
-                    sort_key = Some(val_v);
-                } else {
-                    leftover.push(name_v);
-                    leftover.push(val_v);
-                }
+                let is_reverse = name_v.is_heap() && matches!(self.heap.get(name_v), HeapObj::Str(s) if s == "reverse");
+                if is_key { sort_key = Some(val_v); }
+                else if is_reverse { sort_reverse = self.truthy(val_v); }
+                else { leftover.push(name_v); leftover.push(val_v); }
             }
             leftover_storage = leftover;
             &leftover_storage
@@ -679,7 +695,7 @@ impl<'a> VM<'a> {
             Type => self.call_type(),
             Chr => self.call_chr(),
             Ord => self.call_ord(),
-            Sorted => self.call_sorted_with_key(sort_key, chunk, slots),
+            Sorted => self.call_sorted_with_key(sort_key, sort_reverse, chunk, slots),
             Enumerate => self.call_enumerate(),
             List => self.call_list(chunk, slots),
             Tuple => self.call_tuple(chunk, slots),

compiler/tests/cases/vm.json

@@ -1776,5 +1776,9 @@
   {"src": "print((1, 2, 3) < (1, 2))", "output": ["False"]},
   {"src": "print(b'abc' < b'abd')", "output": ["True"]},
   {"src": "print(sorted([[2], [1], [1, 0]]))", "output": ["[[1], [1, 0], [2]]"]},
-  {"src": "print(sorted([10, 5, 8, 1, 67], key=lambda x: -x))", "output": ["[67, 10, 8, 5, 1]"]}
+  {"src": "print(sorted([10, 5, 8, 1, 67], key=lambda x: -x))", "output": ["[67, 10, 8, 5, 1]"]},
+  {"src": "print(sorted([3, 1, 2], reverse=True))", "output": ["[3, 2, 1]"]},
+  {"src": "print(sorted([3, 1, 2], key=lambda x: -x, reverse=False))", "output": ["[3, 2, 1]"]},
+  {"src": "lst = [3, 1, 2]; lst.sort(reverse=True); print(lst)", "output": ["[3, 2, 1]"]},
+  {"src": "lst = [3, 1, 2]; lst.sort(key=lambda x: -x); print(lst)", "output": ["[3, 2, 1]"]}
 ]

docs/pages/reference/builtins.md

@@ -297,11 +297,13 @@ print(list(range(10, 0, -2)))
 
 ### sorted
 
-New sorted list. No `key=` / `reverse=`, sort by derived value via a precomputed list of `(key, value)` tuples. Numbers, strings, bytes, and tuples/lists order lexicographically; mixed un-orderable types raise `TypeError`.
+New sorted list. Accepts `key=fn` and `reverse=True/False`. Numbers, strings, bytes, and tuples/lists order lexicographically; mixed un-orderable types raise `TypeError`.
 
 ```python
 print(sorted([3, 1, 4, 1, 5]))
 print(sorted("hello"))
+print(sorted([3, 1, 4, 1, 5], reverse=True))
+print(sorted(["banana", "apple", "kiwi"], key=len))
 ```
 
 ```text Output

docs/pages/reference/methods.md

@@ -215,7 +215,7 @@ print(ys)
 
 ### Mutating
 
-Return `None`, mutate in place. `extend` accepts any iterable. `sort` has no `key=` / `reverse=`, sort by derived key via precomputed tuples.
+Return `None`, mutate in place. `extend` accepts any iterable. `sort` accepts `key=fn` and `reverse=True/False`.
 
 ```python
 xs = [1, 2, 3]