feat(vm): add borrowed map iteration

Author: fffonion

Cargo.lock

@@ -67,6 +67,7 @@ regex = "1"
 serde = "1"
 serde_json = "1"
 rt-format = "0.3.1"
+self_cell = "1"
 rustyline = { version = "14", optional = true }
 
 [target.'cfg(windows)'.dependencies]

Cargo.toml

@@ -346,7 +346,7 @@ fn render_builtin_catalog(
         .and_then(|value| value.checked_add(1))
         .expect("builtin call base should fit in u16");
     assert!(
-        builtin_call_base >= 8,
+        builtin_call_base >= 14,
         "builtin call base must leave room for reserved special builtins"
     );
 
@@ -494,6 +494,31 @@ fn render_builtin_catalog(
         "    (BUILTIN_CALL_BASE - 8, BuiltinFunction::StringSplitLiteral),"
     )
     .unwrap();
+    writeln!(
+        &mut out,
+        "    (BUILTIN_CALL_BASE - 9, BuiltinFunction::MapIterInit),"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "    (BUILTIN_CALL_BASE - 10, BuiltinFunction::MapIterNext),"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "    (BUILTIN_CALL_BASE - 11, BuiltinFunction::MapIterTakeKey),"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "    (BUILTIN_CALL_BASE - 12, BuiltinFunction::MapIterTakeValue),"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "    (BUILTIN_CALL_BASE - 13, BuiltinFunction::MapIterClose),"
+    )
+    .unwrap();
     writeln!(&mut out, "];").unwrap();
     writeln!(&mut out).unwrap();
 
@@ -662,6 +687,31 @@ fn render_builtin_catalog(
         "            BuiltinFunction::StringSplitLiteral => BUILTIN_CALL_BASE - 8,"
     )
     .unwrap();
+    writeln!(
+        &mut out,
+        "            BuiltinFunction::MapIterInit => BUILTIN_CALL_BASE - 9,"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "            BuiltinFunction::MapIterNext => BUILTIN_CALL_BASE - 10,"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "            BuiltinFunction::MapIterTakeKey => BUILTIN_CALL_BASE - 11,"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "            BuiltinFunction::MapIterTakeValue => BUILTIN_CALL_BASE - 12,"
+    )
+    .unwrap();
+    writeln!(
+        &mut out,
+        "            BuiltinFunction::MapIterClose => BUILTIN_CALL_BASE - 13,"
+    )
+    .unwrap();
     writeln!(
         &mut out,
         "            _ => BUILTIN_CALL_BASE + self as u16,"
@@ -1301,6 +1351,11 @@ fn appended_builtin_order() -> &'static [&'static str] {
         "string_replace_literal",
         "string_lower_ascii",
         "string_split_literal",
+        "__map_iter_init",
+        "__map_iter_next",
+        "__map_iter_take_key",
+        "__map_iter_take_value",
+        "__map_iter_close",
     ]
 }
 
@@ -1466,6 +1521,11 @@ fn main_range_builtin_variants(builtin_variant_order: &[String]) -> Vec<String>
                     | "StringReplaceLiteral"
                     | "StringLowerAscii"
                     | "StringSplitLiteral"
+                    | "MapIterInit"
+                    | "MapIterNext"
+                    | "MapIterTakeKey"
+                    | "MapIterTakeValue"
+                    | "MapIterClose"
             )
         })
         .cloned()

build.rs

@@ -815,11 +815,66 @@ pub(crate) fn builtin_string_split_literal_impl(
         .collect()
 }
 
+/// Initialize the hidden iterator used by borrowed map for-in loops.
+#[allow(dead_code)]
+#[pd_host_function(name = "__map_iter_init")]
+fn builtin_map_iter_init_metadata(map: VmMapRef<'_>, _slot: i64) -> VmMapHandle {
+    Arc::new(map.clone())
+}
+
+/// Advance a hidden borrowed-map iterator.
+#[allow(dead_code)]
+#[pd_host_function(name = "__map_iter_next")]
+fn builtin_map_iter_next_metadata(_slot: i64) -> bool {
+    false
+}
+
+/// Move the current iterator key into the loop binding.
+#[allow(dead_code)]
+#[pd_host_function(name = "__map_iter_take_key")]
+fn builtin_map_iter_take_key_metadata(_slot: i64) -> Value {
+    Value::Null
+}
+
+/// Move the current iterator value into the loop binding.
+#[allow(dead_code)]
+#[pd_host_function(name = "__map_iter_take_value")]
+fn builtin_map_iter_take_value_metadata(_slot: i64) -> Value {
+    Value::Null
+}
+
+/// Release a hidden borrowed-map iterator after loop exit.
+#[allow(dead_code)]
+#[pd_host_function(name = "__map_iter_close")]
+fn builtin_map_iter_close_metadata(map: VmMapRef<'_>, _slot: i64) -> VmMapHandle {
+    Arc::new(map.clone())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::builtins::{BUILTIN_CALL_BASE, BUILTIN_CALL_COUNT, BuiltinFunction};
     use std::sync::Arc;
 
+    #[test]
+    fn map_iterator_builtins_have_unique_reserved_call_indices() {
+        let reserved = [
+            (BuiltinFunction::MapIterInit, BUILTIN_CALL_BASE - 9),
+            (BuiltinFunction::MapIterNext, BUILTIN_CALL_BASE - 10),
+            (BuiltinFunction::MapIterTakeKey, BUILTIN_CALL_BASE - 11),
+            (BuiltinFunction::MapIterTakeValue, BUILTIN_CALL_BASE - 12),
+            (BuiltinFunction::MapIterClose, BUILTIN_CALL_BASE - 13),
+        ];
+        for (builtin, index) in reserved {
+            assert_eq!(builtin.call_index(), index);
+            assert_eq!(BuiltinFunction::from_call_index(index), Some(builtin));
+        }
+        assert_eq!(BUILTIN_CALL_COUNT, 89);
+        for alias in BUILTIN_CALL_BASE + 89..=BUILTIN_CALL_BASE + 92 {
+            assert_eq!(BuiltinFunction::from_call_index(alias), None);
+        }
+    }
+
     #[test]
     fn array_push_detaches_shared_array_before_write() {
         let shared = Value::array(vec![Value::Int(1)]);

src/builtins/runtime/core.rs

@@ -0,0 +1,70 @@
+use crate::bytecode::Value;
+use crate::vm::{CallReturn, Vm, VmError, VmResult};
+
+use super::{arg, return_one};
+
+fn iterator_slot(args: &[Value], index: usize, label: &'static str) -> VmResult<usize> {
+    let raw = arg::<i64>(args, index, label)?;
+    usize::try_from(raw).map_err(|_| VmError::HostError(format!("invalid map iterator slot {raw}")))
+}
+
+pub(super) fn init(vm: &mut Vm, args: &[Value]) -> VmResult<CallReturn> {
+    let map = match args.first() {
+        Some(Value::Map(map)) => map.clone(),
+        _ => return Err(VmError::TypeMismatch("map")),
+    };
+    let slot = iterator_slot(args, 1, "map iterator slot")?;
+    if map.iter().any(|(key, _)| !matches!(key, Value::String(_))) {
+        return Err(VmError::HostError(
+            "borrowed map iteration requires string keys".to_string(),
+        ));
+    }
+    vm.init_map_iterator(slot, map.clone())?;
+    Ok(return_one(Value::Map(map)))
+}
+
+pub(super) fn next(vm: &mut Vm, args: &[Value]) -> VmResult<CallReturn> {
+    let slot = iterator_slot(args, 0, "map iterator slot")?;
+    vm.advance_map_iterator(slot).map(return_one)
+}
+
+pub(super) fn take_key(vm: &mut Vm, args: &[Value]) -> VmResult<CallReturn> {
+    let slot = iterator_slot(args, 0, "map iterator slot")?;
+    vm.take_map_iterator_key(slot).map(return_one)
+}
+
+pub(super) fn take_value(vm: &mut Vm, args: &[Value]) -> VmResult<CallReturn> {
+    let slot = iterator_slot(args, 0, "map iterator slot")?;
+    vm.take_map_iterator_value(slot).map(return_one)
+}
+
+pub(super) fn close(vm: &mut Vm, args: &[Value]) -> VmResult<CallReturn> {
+    let map = match args.first() {
+        Some(Value::Map(map)) => map.clone(),
+        _ => return Err(VmError::TypeMismatch("map")),
+    };
+    let slot = iterator_slot(args, 1, "map iterator slot")?;
+    vm.close_map_iterator(slot)?;
+    Ok(return_one(Value::Map(map)))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{OpCode, Program};
+
+    #[test]
+    fn init_accepts_compaction_independent_ids_and_rejects_oversized_ids() {
+        let program = Program::new(Vec::new(), vec![OpCode::Ret as u8]).with_local_count(1);
+        let mut vm = Vm::new(program);
+
+        init(&mut vm, &[Value::map(Vec::new()), Value::Int(2)])
+            .expect("logical iterator ids must not depend on compacted local count");
+        let err = init(
+            &mut vm,
+            &[Value::map(Vec::new()), Value::Int(i64::from(u8::MAX) + 1)],
+        )
+        .expect_err("oversized iterator id should fail without allocating");
+        assert!(err.to_string().contains("invalid map iterator id"));
+    }
+}

src/builtins/runtime/map_iter.rs

@@ -15,6 +15,7 @@ mod io;
 mod io_wasm;
 mod jit;
 mod json;
+mod map_iter;
 mod math;
 pub(crate) mod print;
 pub(crate) mod regex;
@@ -64,6 +65,15 @@ pub(crate) fn execute_builtin_call(
         BuiltinFunction::Set => core::builtin_set(args).map(BuiltinCallOutcome::Return),
         BuiltinFunction::Keys => core::builtin_keys(args).map(BuiltinCallOutcome::Return),
         BuiltinFunction::Count => core::builtin_count(args).map(BuiltinCallOutcome::Return),
+        BuiltinFunction::MapIterInit => map_iter::init(vm, args).map(BuiltinCallOutcome::Return),
+        BuiltinFunction::MapIterNext => map_iter::next(vm, args).map(BuiltinCallOutcome::Return),
+        BuiltinFunction::MapIterTakeKey => {
+            map_iter::take_key(vm, args).map(BuiltinCallOutcome::Return)
+        }
+        BuiltinFunction::MapIterTakeValue => {
+            map_iter::take_value(vm, args).map(BuiltinCallOutcome::Return)
+        }
+        BuiltinFunction::MapIterClose => map_iter::close(vm, args).map(BuiltinCallOutcome::Return),
         BuiltinFunction::StringContains => core::builtin_string_contains(args)
             .map(IntoBuiltinCallOutcome::into_builtin_call_outcome),
         BuiltinFunction::StringReplaceLiteral => core::builtin_string_replace_literal(args)

src/builtins/runtime/mod.rs

@@ -113,6 +113,7 @@ impl CompileError {
             CompileError::StrictTypingRequired { line, .. } => {
                 line.and_then(|value| usize::try_from(value).ok())
             }
+
             _ => None,
         }
     }

src/compiler/mod.rs

@@ -232,6 +232,20 @@ impl Parser {
         line: u32,
         action: &str,
     ) -> Result<(), ParseError> {
+        if self.borrowed_map_iter_locals.contains(&index) {
+            let display = name_hint
+                .map(str::to_string)
+                .or_else(|| self.find_local_name_by_slot(index))
+                .unwrap_or_else(|| format!("#{index}"));
+            return Err(ParseError {
+                span: None,
+                code: Some("E_BORROW_CONFLICT".to_string()),
+                line: line as usize,
+                message: format!(
+                    "cannot {action} local '{display}' while it is borrowed by a map iterator"
+                ),
+            });
+        }
         if !self.enforce_mutable_bindings || self.is_local_slot_mutable(index) {
             return Ok(());
         }

src/compiler/parser/expressions.rs

@@ -138,6 +138,8 @@ pub(super) struct Parser {
     direct_host_call_aliases: HashMap<String, String>,
     direct_host_wildcard_imports: HashSet<String>,
     mutable_locals: Vec<bool>,
+    borrowed_map_iter_locals: Vec<LocalSlot>,
+    local_schemas: HashMap<LocalSlot, TypeSchema>,
 }
 
 struct ClosureCaptureContext {
@@ -190,6 +192,8 @@ impl Parser {
             direct_host_call_aliases: HashMap::new(),
             direct_host_wildcard_imports: HashSet::new(),
             mutable_locals: Vec::new(),
+            borrowed_map_iter_locals: Vec::new(),
+            local_schemas: HashMap::new(),
         })
     }