//! Tree-walk interpreter (Phase I). use anyhow::{bail, Result}; use std::collections::{HashMap, HashSet}; use std::path::{Path, PathBuf}; use crate::ast::{ Arg, BinaryOp, CallExpr, Expr, Function, IndexKey, InterpPart, Literal, Module, Param, Stmt, UnaryOp, }; use crate::builtin::{ builtin_at, builtin_footnote_get, builtin_int, builtin_iter_items, builtin_join, builtin_len, builtin_split, builtin_str, builtin_trim, builtin_type, }; use crate::debug::{emit_trace, DebugController}; use crate::diagnostics::{bail_at, Span}; use crate::host::{call_host, HostContext, HostFn}; use crate::input_feed::InputFeed; use crate::capture::{ BranchHit, CallFrame, LoopFrame, LoopHit, LoopIter, StmtEvent, StmtEventKind, ViewTrace, }; use crate::value::Value; use std::sync::Arc; pub struct Interpreter { pub path: Option, pub trace: bool, capture: bool, pub captured_stdout: String, /// Bindings in the entry (`# main` / sole object) env after it finishes. pub entry_bindings: HashMap, /// Silent branch/loop hits for `marqdo view` annotations. pub view_trace: ViewTrace, next_call_id: u32, call_stack: Vec, fn_ordinals: HashMap, next_loop_id: u32, /// Active loops: `(loop_id, iter_index_0based)`. loop_stack: Vec<(u32, u32)>, current_span: Span, input: InputFeed, host: HostContext, debug: Option>, /// Entry module pointer for `host_query("call_lib_path")` while plugins run. site_module: Option<*const Module>, } struct Env { vars: HashMap, } impl Env { fn new() -> Self { Self { vars: HashMap::new(), } } /// Phase 2: lift resolved Artifact Metadata into the entry environment. /// Existing keys are left unchanged (`or_insert` semantics). fn with_metadata(module: &Module) -> Self { let mut env = Self::new(); for (k, v) in &module.metadata { env.vars.entry(k.clone()).or_insert_with(|| v.clone()); } env } fn get(&self, name: &str) -> Option<&Value> { self.vars.get(name) } fn set(&mut self, name: String, value: Value) { self.vars.insert(name, value); } fn vars_clone(&self) -> HashMap { self.vars.clone() } } pub(crate) enum EvArg { Positional(Value), Named(String, Value), } impl Interpreter { pub fn new(path: Option<&Path>, trace: bool) -> Self { Self { path: path.map(|p| p.to_path_buf()), trace, capture: false, captured_stdout: String::new(), entry_bindings: HashMap::new(), view_trace: ViewTrace::default(), next_call_id: 1, call_stack: Vec::new(), fn_ordinals: HashMap::new(), next_loop_id: 1, loop_stack: Vec::new(), current_span: Span::new(1, 1), input: InputFeed::new(false, Vec::new()), host: HostContext::for_run(path, Default::default(), Vec::new()), debug: None, site_module: None, } } pub fn with_capture(path: Option<&Path>, trace: bool) -> Self { Self { path: path.map(|p| p.to_path_buf()), trace, capture: true, captured_stdout: String::new(), entry_bindings: HashMap::new(), view_trace: ViewTrace::default(), next_call_id: 1, call_stack: Vec::new(), fn_ordinals: HashMap::new(), next_loop_id: 1, loop_stack: Vec::new(), current_span: Span::new(1, 1), input: InputFeed::new(true, Vec::new()), host: HostContext::for_capture(path, Default::default()), debug: None, site_module: None, } } pub fn with_stdin(mut self, lines: Vec) -> Self { self.input = InputFeed::new(self.capture, lines); self } pub fn with_host(mut self, host: HostContext) -> Self { self.host = host; self } pub fn with_debug(mut self, debug: Arc) -> Self { self.debug = Some(debug); self } pub fn take_plots(&mut self) -> Vec { std::mem::take(&mut self.host.plots) } fn err(&self, message: impl Into) -> anyhow::Error { bail_at(self.path.as_deref(), self.current_span, message) } fn emit_line(&mut self, text: &str) { if self.capture { self.captured_stdout.push_str(text); self.captured_stdout.push('\n'); } else { println!("{text}"); } } fn emit_prompt(&mut self, prompt: &str) { if prompt.is_empty() { return; } if self.capture { self.captured_stdout.push_str(prompt); } else { print!("{prompt}"); use std::io::Write; let _ = std::io::stdout().flush(); } } fn current_call_id(&self) -> u32 { self.call_stack.last().copied().unwrap_or(0) } fn loop_ctx(&self) -> (Option, Option) { self.loop_stack .last() .map(|(id, iter)| (Some(*id), Some(*iter))) .unwrap_or((None, None)) } fn push_view_call(&mut self, fun: &Function, env: &Env) { if !self.capture { return; } let call_id = self.next_call_id; self.next_call_id += 1; let ordinal = { let e = self.fn_ordinals.entry(fun.name.clone()).or_insert(0); *e += 1; *e }; let args_brief = fun .params .iter() .filter_map(|p| { env.get(&p.name) .map(|v| format!("{}={}", p.name, brief_trace_val(v))) }) .collect::>() .join(", "); self.view_trace.calls.push(CallFrame { call_id, fn_name: fun.name.clone(), fn_line: fun.span.line, call_line: self.current_span.line, ordinal, args_brief, }); self.call_stack.push(call_id); } fn pop_view_call(&mut self) { if self.capture { self.call_stack.pop(); } } fn begin_view_loop( &mut self, line: u32, item: Option<&str>, collection: Option<&str>, ) -> u32 { let loop_id = self.next_loop_id; self.next_loop_id += 1; self.view_trace.loop_frames.push(LoopFrame { loop_id, line, item_name: item.map(|s| s.to_string()), collection: collection.map(|s| s.to_string()), iterations: Vec::new(), }); self.loop_stack.push((loop_id, 0)); loop_id } fn enter_loop_iter(&mut self, loop_id: u32, index: u32, item_value: &str) { if let Some((_, cur)) = self.loop_stack.iter_mut().rev().find(|(id, _)| *id == loop_id) { *cur = index; } let call_id = self.current_call_id(); if let Some(fr) = self .view_trace .loop_frames .iter_mut() .find(|f| f.loop_id == loop_id) { fr.iterations.push(LoopIter { index, item_value: item_value.to_string(), call_id, }); } } fn end_view_loop(&mut self, loop_id: u32) { if self .loop_stack .last() .map(|(id, _)| *id == loop_id) .unwrap_or(false) { self.loop_stack.pop(); } } fn record_stmt_event(&mut self, mut ev: StmtEvent) { if self.capture { if ev.loop_id.is_none() || ev.iter.is_none() { let (lid, iter) = self.loop_ctx(); if ev.loop_id.is_none() { ev.loop_id = lid; } if ev.iter.is_none() { ev.iter = iter; } } self.view_trace.events.push(ev); } } fn record_branch_hit(&mut self, line: u32, arm_index: usize) { let call_id = self.current_call_id(); if let Some(existing) = self.view_trace.branches.iter_mut().find(|h| { h.line == line && h.arm_index == arm_index && h.call_id == call_id }) { existing.count += 1; } else { self.view_trace.branches.push(BranchHit { line, arm_index, count: 1, call_id, }); } let (loop_id, iter) = self.loop_ctx(); self.record_stmt_event(StmtEvent { line, kind: StmtEventKind::Branch, name: None, value_after: Some(format!("arm {}", arm_index + 1)), arm_index: Some(arm_index), iter, call_id, loop_id, }); } fn record_loop_hit(&mut self, line: u32, iterations: u32, last_item: Option) { if let Some(existing) = self.view_trace.loops.iter_mut().find(|h| h.line == line) { existing.iterations = iterations; if last_item.is_some() { existing.last_item = last_item.clone(); } } else { self.view_trace.loops.push(LoopHit { line, iterations, last_item: last_item.clone(), }); } let (loop_id, _) = self.loop_ctx(); self.record_stmt_event(StmtEvent { line, kind: StmtEventKind::Loop, name: None, value_after: Some(format!("{iterations} iters")), arm_index: None, // Summary event: total count (not 0-based index). iter: Some(iterations), call_id: self.current_call_id(), loop_id, }); } /// Run a function by name anywhere in the module (for `lib/subtask` workers). pub fn invoke_function( &mut self, module: &Module, name: &str, args: &[(String, Value)], ) -> Result { let fun = find_function_anywhere(module, name) .ok_or_else(|| self.err(format!("unknown function `{name}`")))?; self.run_function(module, fun, Env::new(), args, false) } /// Call a function using (and updating) [`Self::entry_bindings`] from `# main`. /// Used by browser WASM sessions so handlers share state with the entry object. pub fn invoke_in_entry( &mut self, module: &Module, name: &str, args: &[(String, Value)], ) -> Result { let fun = find_function_anywhere(module, name) .ok_or_else(|| self.err(format!("unknown function `{name}`")))?; let mut env = Env::with_metadata(module); for (k, v) in &self.entry_bindings { env.set(k.clone(), v.clone()); } let prev = self.site_module; self.site_module = Some(module as *const Module); let result = self.run_function(module, fun, env, args, true); self.site_module = prev; result } /// Evaluate only the entry object's top-level assignments, without running /// calls/returns/control flow. This is the view plan's language-native /// projection: cell tables are ordinary Marqdo values, not source scans. /// Evaluate selected entry bindings plus their assignment dependencies. /// This is the view plan's language-native projection: cell tables are /// ordinary Marqdo values, not source scans. pub fn capture_declarations( &mut self, module: &Module, names: &[&str], ) -> Result> { let prev = self.site_module; self.site_module = Some(module as *const Module); let result = (|| { let entry = find_top(module, "main").or_else(|| { let entries: Vec<&Function> = module .functions .iter() .filter(|f| f.is_object() && f.params.is_empty()) .collect(); if entries.len() == 1 { Some(entries[0]) } else { None } }); let entry = entry.ok_or_else(|| self.err("no `# main` object to inspect"))?; let assignments: std::collections::HashMap<&str, &Expr> = entry .body .iter() .filter_map(|stmt| match stmt { Stmt::Assign { name, value, .. } => Some((name.as_str(), value)), _ => None, }) .collect(); let mut env = Env::with_metadata(module); let mut done = std::collections::HashSet::new(); let mut visiting = std::collections::HashSet::new(); fn resolve( this: &mut Interpreter, module: &Module, fun: &Function, assignments: &std::collections::HashMap<&str, &Expr>, name: &str, env: &mut Env, done: &mut std::collections::HashSet, visiting: &mut std::collections::HashSet, ) -> Result<()> { if done.contains(name) { return Ok(()); } if !visiting.insert(name.to_string()) { return Err(this.err(format!("cyclic view-plan binding `{name}`"))); } let Some(expr) = assignments.get(name) else { visiting.remove(name); return Ok(()); }; let mut deps = std::collections::HashSet::new(); collect_decl_reads(expr, &mut deps); for dep in deps { if assignments.contains_key(dep.as_str()) && env.get(&dep).is_none() { resolve(this, module, fun, assignments, &dep, env, done, visiting)?; } } let value = this.eval_expr(module, fun, env, expr)?; env.set(name.to_string(), value); done.insert(name.to_string()); visiting.remove(name); Ok(()) } for name in names { resolve( self, module, entry, &assignments, name, &mut env, &mut done, &mut visiting, )?; } self.entry_bindings = env.vars_clone(); Ok(self.entry_bindings.clone()) })(); self.site_module = prev; result } pub fn run_module(&mut self, module: &Module) -> Result { let prev = self.site_module; self.site_module = Some(module as *const Module); let result = (|| { if let Some(main) = find_top(module, "main") { return self.run_function(module, main, Env::with_metadata(module), &[], true); } // Document-as-entry: sole top-level `#` object with no params (e.g. `# Hello World`). let entries: Vec<&Function> = module .functions .iter() .filter(|f| f.is_object() && f.params.is_empty()) .collect(); if entries.len() == 1 { return self.run_function( module, entries[0], Env::with_metadata(module), &[], true, ); } // Web Artifact entry (ADR 0007): `type: web|endpoint` may be pure document — // no `# main`. Return a Result-shaped summary for run/check gold paths. if let Some(kind) = crate::artifact::classify(&module.metadata) { use crate::artifact::ArtifactKind; if matches!(kind, ArtifactKind::Web | ArtifactKind::Endpoint) { return Ok(Self::artifact_run_summary(module, kind)); } } bail!("no `# main` object to run"); })(); self.site_module = prev; result } fn artifact_run_summary(module: &Module, kind: crate::artifact::ArtifactKind) -> Value { use crate::artifact::{endpoint_path, http_method, web_route, ArtifactKind}; let kind_s = match kind { ArtifactKind::Web => "web", ArtifactKind::Endpoint => "endpoint", ArtifactKind::Prompt => "prompt", ArtifactKind::Other => "other", }; let mut value = vec![ ("kind".into(), Value::Text(kind_s.into())), ("method".into(), Value::Text(http_method(&module.metadata))), ]; match kind { ArtifactKind::Web => { if let Some(r) = web_route(&module.metadata) { value.push(("route".into(), Value::Text(r))); } } ArtifactKind::Endpoint => { if let Some(r) = endpoint_path(&module.metadata) { value.push(("path".into(), Value::Text(r))); } } _ => {} } Value::Map(vec![ ("ok".into(), Value::Bool(true)), ("value".into(), Value::Map(value)), ("error".into(), Value::None), ]) } /// Resolve `lib.member` on the site (entry) module — used by ABI `call_lib_path`. pub(crate) fn call_site_lib_path( &mut self, path: &str, args: Option<&Value>, ) -> std::result::Result { let site = self .site_module .ok_or_else(|| "call_lib_path: no site module".to_string())?; let site = unsafe { &*site }; let parts: Vec = path .split('.') .map(|s| s.trim().to_string()) .filter(|s| !s.is_empty()) .collect(); if parts.len() < 2 { return Err(format!( "call_lib_path: need `lib.member`, got `{path}`" )); } let mut ev_args: Vec = Vec::new(); if let Some(Value::Map(pairs)) = args { for (k, v) in pairs { ev_args.push(EvArg::Named(k.clone(), v.clone())); } } self.eval_path_call(site, &parts, &ev_args) .map_err(|e| e.to_string()) } fn call_plugin_registered( &mut self, name: &str, bound: &HashMap, ) -> std::result::Result { struct HookData { interp: *mut Interpreter, } fn trampoline( data: *mut (), path: &str, args: Option<&Value>, ) -> std::result::Result { let data = unsafe { &mut *(data as *mut HookData) }; let interp = unsafe { &mut *data.interp }; interp.call_site_lib_path(path, args) } let mut data = HookData { interp: self as *mut Interpreter, }; let hook = crate::host::plugin::LibPathCall { call: trampoline, data: &mut data as *mut HookData as *mut (), }; crate::host::plugin::with_lib_path_call(hook, || { crate::host::plugin::call_registered(&mut self.host, name, bound) }) } fn run_function( &mut self, module: &Module, fun: &Function, mut env: Env, args: &[(String, Value)], capture_entry_env: bool, ) -> Result { if self.trace { emit_trace( self.path.as_deref(), Some(fun.span), "enter_fn", &[("fn", fun.name.as_str())], ); } for (k, v) in args { env.set(k.clone(), v.clone()); } for p in &fun.params { if env.get(&p.name).is_none() { env.set(p.name.clone(), Value::None); } } let ret = Value::None; self.push_view_call(fun, &env); self.host.push_call_frame(&fun.name); let body_result = (|| -> Result { for stmt in &fun.body { if let Some(v) = self.exec_stmt(module, fun, &mut env, stmt)? { return Ok(v); } } Ok(ret) })(); self.host.pop_call_frame(); self.pop_view_call(); let ret = body_result?; if capture_entry_env { self.entry_bindings = env.vars_clone(); } if self.trace { let display = ret.as_display(); emit_trace( self.path.as_deref(), Some(fun.span), "leave_fn", &[("fn", fun.name.as_str()), ("value", display.as_str())], ); } Ok(ret) } fn exec_stmt( &mut self, module: &Module, fun: &Function, env: &mut Env, stmt: &Stmt, ) -> Result> { let span = stmt_span(stmt); self.current_span = span; self.host.current_line = span.line; if let Some(dbg) = &self.debug { dbg.on_stmt(span.line, &fun.name, &env.vars, &self.captured_stdout) .map_err(|m| self.err(m))?; } match stmt { Stmt::Assign { name, value, span, .. } => { self.current_span = *span; let v = self.eval_expr(module, fun, env, value)?; // 契约边界 3(T2.2):表绑定 vs 字段契约。 if let Some(c) = fun.var_contracts.get(name) { if let Some(d) = crate::contract::fields_diag(c, name, &v, self.path.as_deref(), *span) { return Err(d.into()); } } if self.trace { let display = v.as_display(); emit_trace( self.path.as_deref(), Some(*span), "stmt", &[ ("kind", "assign"), ("name", name.as_str()), ("value", display.as_str()), ], ); } if self.capture { self.record_stmt_event(StmtEvent { line: span.line, kind: StmtEventKind::Assign, name: Some(name.clone()), value_after: Some(v.as_display()), arm_index: None, iter: None, call_id: self.current_call_id(), loop_id: None, }); } env.set(name.clone(), v); Ok(None) } Stmt::Return { value, span } => { self.current_span = *span; let v = self.eval_expr(module, fun, env, value)?; // 契约边界 2(T2.2):返回值 vs 返回契约。 if let Some(c) = &fun.contract { if let Some(d) = crate::contract::return_diag(c, &fun.name, &v, self.path.as_deref(), *span) { return Err(d.into()); } } if self.trace { let display = v.as_display(); emit_trace( self.path.as_deref(), Some(*span), "stmt", &[("kind", "return"), ("value", display.as_str())], ); } if self.capture { self.record_stmt_event(StmtEvent { line: span.line, kind: StmtEventKind::Return, name: None, value_after: Some(v.as_display()), arm_index: None, iter: None, call_id: self.current_call_id(), loop_id: None, }); } Ok(Some(v)) } Stmt::Call { call, span } => { self.current_span = *span; if self.trace { emit_trace( self.path.as_deref(), Some(*span), "stmt", &[("kind", "call"), ("callee", call.callee.as_str())], ); } let stdout_before = self.captured_stdout.len(); let v = self.eval_call(module, fun, env, call)?; if self.capture { let (loop_id, iter) = self.loop_ctx(); self.record_stmt_event(StmtEvent { line: span.line, kind: StmtEventKind::Call, name: Some(call.callee.clone()), value_after: Some(call_event_brief( &v, &self.captured_stdout, stdout_before, &call.callee, )), arm_index: None, iter, call_id: self.current_call_id(), loop_id, }); } Ok(None) } Stmt::Expr { value, span } => { self.current_span = *span; if self.trace { emit_trace( self.path.as_deref(), Some(*span), "stmt", &[("kind", "expr")], ); } let stdout_before = self.captured_stdout.len(); let v = self.eval_expr(module, fun, env, value)?; if self.capture { let (loop_id, iter) = self.loop_ctx(); let name = match value { Expr::Call(c) => Some(c.callee.clone()), _ => None, }; self.record_stmt_event(StmtEvent { line: span.line, kind: StmtEventKind::Call, name: name.clone(), value_after: Some(call_event_brief( &v, &self.captured_stdout, stdout_before, name.as_deref().unwrap_or("expr"), )), arm_index: None, iter, call_id: self.current_call_id(), loop_id, }); } Ok(None) } Stmt::Branch { arms, span } => { self.current_span = *span; if self.trace { emit_trace( self.path.as_deref(), Some(*span), "stmt", &[("kind", "branch")], ); } for (arm_index, arm) in arms.iter().enumerate() { let take = match &arm.condition { None => true, Some(cond) => self.eval_expr(module, fun, env, cond)?.truthy(), }; if take { if self.capture { self.record_branch_hit(span.line, arm_index); } for s in &arm.body { if let Some(v) = self.exec_stmt(module, fun, env, s)? { return Ok(Some(v)); } } break; } } Ok(None) } Stmt::While { condition, body, span, } => { self.current_span = *span; if self.trace { emit_trace( self.path.as_deref(), Some(*span), "stmt", &[("kind", "while")], ); } let loop_id = if self.capture { Some(self.begin_view_loop(span.line, None, None)) } else { None }; let mut guard = 0u32; while self.eval_expr(module, fun, env, condition)?.truthy() { guard += 1; if guard > 1_000_000 { return Err(self.err("while loop exceeded iteration limit")); } if let Some(lid) = loop_id { self.enter_loop_iter(lid, guard - 1, &format!("iter {guard}")); } for s in body { if let Some(v) = self.exec_stmt(module, fun, env, s)? { if self.capture { if let Some(lid) = loop_id { self.end_view_loop(lid); } self.record_loop_hit(span.line, guard, None); } return Ok(Some(v)); } } } if self.capture { if let Some(lid) = loop_id { self.end_view_loop(lid); } self.record_loop_hit(span.line, guard, None); } Ok(None) } Stmt::ForEach { item, collection, body, span, } => { self.current_span = *span; if self.trace { emit_trace( self.path.as_deref(), Some(*span), "stmt", &[ ("kind", "foreach"), ("item", item.as_str()), ("collection", collection.as_str()), ], ); } let coll = env.get(collection).cloned().ok_or_else(|| { self.err(format!("undefined collection `{collection}`")) })?; let items = match builtin_iter_items(&coll) { Ok(Value::List(xs)) => xs, Ok(_) => unreachable!(), Err(m) => return Err(self.err(m)), }; let loop_id = if self.capture { Some(self.begin_view_loop( span.line, Some(item.as_str()), Some(collection.as_str()), )) } else { None }; let mut iterations = 0u32; let mut last_item: Option = None; for val in items { let index = iterations; iterations += 1; let display = val.as_display(); last_item = Some(display.clone()); if let Some(lid) = loop_id { self.enter_loop_iter(lid, index, &display); self.record_stmt_event(StmtEvent { line: span.line, kind: StmtEventKind::BindRef, name: Some(item.clone()), value_after: Some(format!( "{collection}[{index}]={display}" )), arm_index: None, iter: Some(index), call_id: self.current_call_id(), loop_id: Some(lid), }); } env.set(item.clone(), val); for s in body { if let Some(v) = self.exec_stmt(module, fun, env, s)? { if self.capture { if let Some(lid) = loop_id { self.end_view_loop(lid); } self.record_loop_hit(span.line, iterations, last_item.clone()); } return Ok(Some(v)); } } } if self.capture { if let Some(lid) = loop_id { self.end_view_loop(lid); } self.record_loop_hit(span.line, iterations, last_item); } Ok(None) } } } fn resolve_index_key( &mut self, _module: &Module, _fun: &Function, env: &mut Env, label: &IndexKey, ) -> Result { match label { IndexKey::Lit(s) => Ok(s.clone()), IndexKey::Var(name) => { let v = env.get(name).cloned().ok_or_else(|| { self.err(format!("undefined variable `{name}` in footnote key")) })?; Ok(v.as_display()) } } } fn eval_expr( &mut self, module: &Module, fun: &Function, env: &mut Env, expr: &Expr, ) -> Result { match expr { Expr::Literal(lit) => Ok(lit_to_value(lit)), Expr::Var(name) => env .get(name) .cloned() .ok_or_else(|| self.err(format!("undefined variable `{name}`"))), Expr::Interp(parts) => { let mut s = String::new(); for part in parts { match part { InterpPart::Lit(t) => s.push_str(t), InterpPart::Var(n) => { let v = env .get(n) .ok_or_else(|| self.err(format!("undefined variable `{n}`")))?; s.push_str(&v.as_display()); } InterpPart::Index { base, labels } => { let mut v = env.get(base).cloned().ok_or_else(|| { self.err(format!("undefined variable `{base}`")) })?; for label in labels { v = builtin_footnote_get(&v, label).map_err(|m| self.err(m))?; } s.push_str(&v.as_display()); } } } Ok(Value::Text(s)) } Expr::Unary { op, expr } => { let v = self.eval_expr(module, fun, env, expr)?; match op { UnaryOp::Not => Ok(Value::Bool(!v.truthy())), UnaryOp::Neg => match v { Value::Int(n) => Ok(Value::Int(-n)), Value::Num(n) => Ok(Value::Num(-n)), _ => Err(self.err("unary `-` needs int or num")), }, } } Expr::Binary { op, left, right } => { let l = self.eval_expr(module, fun, env, left)?; match op { BinaryOp::And => { if !l.truthy() { return Ok(Value::Bool(false)); } let r = self.eval_expr(module, fun, env, right)?; return Ok(Value::Bool(r.truthy())); } BinaryOp::Or => { if l.truthy() { return Ok(Value::Bool(true)); } let r = self.eval_expr(module, fun, env, right)?; return Ok(Value::Bool(r.truthy())); } _ => {} } let r = self.eval_expr(module, fun, env, right)?; if let Some(v) = crate::linalg_ops::try_matrix_binary( &mut self.host, *op, &l, &r, ) .map_err(|e| self.err(e))? { return Ok(v); } eval_binary(*op, &l, &r).map_err(|e| self.err(e.to_string())) } Expr::Call(call) => self.eval_call(module, fun, env, call), Expr::List(items) => { let mut out = Vec::new(); for it in items { out.push(self.eval_expr(module, fun, env, it)?); } Ok(Value::List(out)) } Expr::Map(pairs) => { let mut out = Vec::new(); for (k, e) in pairs { out.push((k.clone(), self.eval_expr(module, fun, env, e)?)); } Ok(Value::Map(out)) } Expr::Index { base, label } => { let v = self.eval_expr(module, fun, env, base)?; let key = self.resolve_index_key(module, fun, env, label)?; // 契约边界 4(T2.2):字段访问 vs 字段契约——键存在性**先于**取值 // (契约诊断优先于运行时 `missing map key`)。 if let Expr::Var(name) = base.as_ref() { if let Some(c) = fun.var_contracts.get(name) { if let Some(d) = crate::contract::index_diag( c, name, &key, &Value::None, self.path.as_deref(), self.current_span, ) { return Err(d.into()); } } } let out = builtin_footnote_get(&v, &key).map_err(|m| self.err(m))?; if let Expr::Var(name) = base.as_ref() { if let Some(c) = fun.var_contracts.get(name) { if let Some(d) = crate::contract::index_diag( c, name, &key, &out, self.path.as_deref(), self.current_span, ) { return Err(d.into()); } } } Ok(out) } Expr::Formula(e) => Ok(Value::Formula(e.clone())), Expr::Code(c) => Ok(Value::Code(c.clone())), } } fn eval_call( &mut self, module: &Module, fun: &Function, env: &mut Env, call: &CallExpr, ) -> Result { let mut call = call.clone(); // Method callees keep author names (`绘图` on quantum ≠ math `host_plot`). if call.path.is_none() && call.receiver.is_none() { let callee = crate::aliases::normalize_call_callee_and_args( &call.callee, &mut call.args, ); call.callee = callee; } for m in &call.pre_modifiers { if call.args.iter().any(|a| matches!(a, Arg::Named { name, .. } if name == m)) { return Err(self.err(format!( "pre-bracket modifier `{m}` conflicts with named argument `{m}`" ))); } } let mut ev_args = Vec::new(); for m in &call.pre_modifiers { ev_args.push(EvArg::Named(m.clone(), Value::Bool(true))); } for arg in &call.args { match arg { Arg::Positional(e) => { ev_args.push(EvArg::Positional(self.eval_expr(module, fun, env, e)?)); } Arg::Named { name, value } => { ev_args.push(EvArg::Named( name.clone(), self.eval_expr(module, fun, env, value)?, )); } } } if let Some(recv_name) = &call.receiver { return self.eval_method_call(module, fun, env, recv_name, &call.callee, &ev_args); } if let Some(path) = &call.path { // Bare dotted callee `a.b`: if `a` is a local variable, it is a method // receiver (Python-style unified namespace); otherwise it's a library path. if path.len() == 2 && env.get(&path[0]).is_some() { let recv = path[0].clone(); let method = path[1].clone(); return self.eval_method_call(module, fun, env, &recv, &method, &ev_args); } return self.eval_path_call(module, path, &ev_args); } if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) { return self.eval_path_call(module, &u.path, &ev_args); } match call.callee.as_str() { "print" => { let bound = bind_args(&["text".into()], &ev_args, false) .map_err(|m| self.err(m))?; let text = bound .get("text") .map(|v| v.as_display()) .ok_or_else(|| self.err("print requires text (named or positional)"))?; self.emit_line(&text); return Ok(Value::None); } "input" => { let bound = bind_args(&["prompt".into()], &ev_args, true) .map_err(|m| self.err(m))?; let prompt = bound .get("prompt") .map(|v| v.as_display()) .unwrap_or_default(); let line = if self.capture { self.emit_prompt(&prompt); self.input.read_line() } else if crate::input_feed::stdin_is_tty() { self.input .read_line_with_prompt(&prompt) .map(|(line, _)| line) } else { self.emit_prompt(&prompt); self.input.read_line() } .map_err(|e| { let msg = e.to_string(); if msg.contains("input needs a line") { self.err(msg) } else { e } })?; return Ok(Value::Text(line)); } "len" => { let bound = bind_args(&["value".into()], &ev_args, false) .map_err(|m| self.err(m))?; let v = bound .get("value") .ok_or_else(|| self.err("len requires value"))?; let n = builtin_len(v).map_err(|m| self.err(m))?; return Ok(Value::Int(n)); } "str" => { let bound = bind_args(&["value".into()], &ev_args, false) .map_err(|m| self.err(m))?; let v = bound .get("value") .ok_or_else(|| self.err("str requires value"))?; return Ok(builtin_str(v)); } "int" => { let bound = bind_args(&["value".into()], &ev_args, false) .map_err(|m| self.err(m))?; let v = bound .get("value") .ok_or_else(|| self.err("int requires value"))?; let n = builtin_int(v).map_err(|m| self.err(m))?; return Ok(Value::Int(n)); } "type" => { let bound = bind_args(&["value".into()], &ev_args, false) .map_err(|m| self.err(m))?; let v = bound .get("value") .ok_or_else(|| self.err("type requires value"))?; return Ok(builtin_type(v)); } "trim" => { let bound = bind_args(&["value".into()], &ev_args, false) .map_err(|m| self.err(m))?; let v = bound .get("value") .ok_or_else(|| self.err("trim requires value"))?; return builtin_trim(v).map_err(|m| self.err(m)); } "split" => { let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false) .map_err(|m| self.err(m))?; let value = bound .get("value") .ok_or_else(|| self.err("split requires value"))?; let sep = bound .get("sep") .ok_or_else(|| self.err("split requires sep"))?; return builtin_split(value, sep).map_err(|m| self.err(m)); } "join" => { let bound = bind_args(&["value".into(), "sep".into()], &ev_args, false) .map_err(|m| self.err(m))?; let value = bound .get("value") .ok_or_else(|| self.err("join requires value"))?; let sep = bound .get("sep") .ok_or_else(|| self.err("join requires sep"))?; return builtin_join(value, sep).map_err(|m| self.err(m)); } "at" => { let bound = bind_args(&["value".into(), "index".into()], &ev_args, false) .map_err(|m| self.err(m))?; let value = bound .get("value") .ok_or_else(|| self.err("at requires value"))?; let index = bound .get("index") .ok_or_else(|| self.err("at requires index"))?; return builtin_at(value, index).map_err(|m| self.err(m)); } "call_fn" => { let bound = bind_args(&["name".into()], &ev_args, false) .map_err(|m| self.err(m))?; let name = match bound.get("name") { Some(Value::Text(s)) => s.as_str(), _ => return Err(self.err("call_fn requires text name")), }; let target = lookup_function(module, fun, name).ok_or_else(|| { self.err(format!("call_fn: unknown function `{name}`")) })?; if !target.params.is_empty() { return Err(self.err(format!( "call_fn: `{name}` must have no parameters" ))); } return self.run_function(module, target, Env::new(), &[], false); } other if HostFn::from_name(other).is_some() => { let hf = HostFn::from_name(other).unwrap(); let mut params: Vec = hf.required_params().iter().map(|s| (*s).to_string()).collect(); for p in hf.optional_params() { params.push((*p).to_string()); } let bound = bind_args(¶ms, &ev_args, true).map_err(|m| self.err(m))?; for req in hf.required_params() { if !bound.contains_key(*req) { return Err(self.err(format!("{} requires `{req}`", hf.name()))); } } return call_host(&mut self.host, hf, &bound).map_err(|m| self.err(m)); } _ => {} } if let Some(reg) = self.host.plugins.get(&call.callee).cloned() { let bound = bind_args(®.params, &ev_args, false).map_err(|m| self.err(m))?; return self .call_plugin_registered(&call.callee, &bound) .map_err(|m| self.err(m)); } let target = lookup_function(module, fun, &call.callee) .ok_or_else(|| self.err(format!("unknown function `{}`", call.callee)))?; let bound = bind_function_args(self, module, fun, env, &target.params, &ev_args, false) .map_err(|m| self.err(m))?; // 契约边界 1(T2.2):调用实参 vs 形参契约。 if let Some(c) = &target.contract { if let Some(d) = crate::contract::call_arg_diag( c, &target.name, &bound, self.path.as_deref(), self.current_span, ) { return Err(d.into()); } } let mut call_env = Env::new(); for (k, v) in bound { call_env.set(k, v); } self.host.push_call_site_line(self.host.current_line); let result = self.run_function(module, target, call_env, &[], false); self.host.pop_call_site_line(); let result = result?; if target.is_object() { Ok(tag_instance(&target.name, result)) } else { Ok(result) } } /// Resolve bare path `lib.member` / `lib.Type.member` (definition-tree addressing). pub(crate) fn eval_path_call( &mut self, module: &Module, path: &[String], ev_args: &[EvArg], ) -> Result { let display = path.join("."); if path.len() < 2 { return Err(self.err(format!("library path `{display}`: need at least `lib.member`"))); } let lib_name = &path[0]; let lib = module.import_modules.get(lib_name).ok_or_else(|| { self.err(format!("unknown library `{lib_name}` (import it in frontmatter)")) })?; let mut parent_is_object = false; let mut node = lib .functions .iter() .find(|f| f.name == path[1]) .ok_or_else(|| self.err(format!("unknown `{display}`")))?; for seg in &path[2..] { parent_is_object = node.is_object(); node = node .children .iter() .find(|c| c.name == *seg) .ok_or_else(|| self.err(format!("unknown `{display}`")))?; } if parent_is_object && !node.is_object() { return Err(self.err(format!( "`{display}` is an instance method; call it as `var`.{}", node.name ))); } let bound = { let mut dummy_env = Env::new(); bind_function_args( self, lib, node, &mut dummy_env, &node.params, ev_args, false, ) .map_err(|m| self.err(m))? }; // 契约边界 1(T2.2):库路径调用的实参 vs 形参契约。 if let Some(c) = &node.contract { if let Some(d) = crate::contract::call_arg_diag( c, &display, &bound, self.path.as_deref(), self.current_span, ) { return Err(d.into()); } } let mut call_env = Env::new(); for (k, v) in bound { call_env.set(k, v); } self.host.push_call_site_line(self.host.current_line); let result = self.run_function(lib, node, call_env, &[], false); self.host.pop_call_site_line(); let result = result?; if node.is_object() { Ok(tag_instance(&node.name, result)) } else { Ok(result) } } fn eval_method_call( &mut self, module: &Module, fun: &Function, env: &mut Env, recv_name: &str, method: &str, ev_args: &[EvArg], ) -> Result { let recv = env .get(recv_name) .cloned() .ok_or_else(|| self.err(format!("undefined variable `{recv_name}`")))?; let type_name = instance_type_name(&recv).map_err(|m| self.err(m))?; if find_object_type(module, &type_name).is_none() { return Err(self.err(format!("unknown object type `{type_name}`"))); } let (owner, _obj, target) = find_method_along_bases(module, &type_name, method) .ok_or_else(|| { let chain = crate::inherit::inheritance_chain(module, &type_name) .into_iter() .map(|o| o.name.as_str()) .collect::>() .join(" → "); self.err(format!( "unknown method `{type_name}.{method}` (searched {chain})" )) })?; let bound = bind_function_args(self, module, fun, env, &target.params, ev_args, false) .map_err(|m| self.err(m))?; // 契约边界 1(T2.2):方法调用的实参 vs 形参契约。 if let Some(c) = &target.contract { if let Some(d) = crate::contract::call_arg_diag( c, &target.name, &bound, self.path.as_deref(), self.current_span, ) { return Err(d.into()); } } let mut call_env = Env::new(); for (k, v) in bound { call_env.set(k, v); } call_env.set("自".into(), recv.clone()); call_env.set("self".into(), recv.clone()); self.host.push_call_site_line(self.host.current_line); let result = self.run_function(owner, target, call_env, &[], false); self.host.pop_call_site_line(); let result = result?; if crate::linalg_ops::is_matrix_value(&recv) { Ok(crate::linalg_ops::retag_matrix_like(&type_name, result)) } else { Ok(result) } } } fn instance_type_name(v: &Value) -> std::result::Result { match v { Value::Map(entries) => entries .iter() .find(|(k, _)| k == "_type") .and_then(|(_, v)| match v { Value::Text(s) => Some(s.clone()), _ => None, }) .ok_or_else(|| "method receiver needs a map with `_type`".into()), _ => Err("method receiver must be an object map".into()), } } fn tag_instance(type_name: &str, value: Value) -> Value { match value { Value::Map(mut entries) => { // Always stamp the constructed type so explicit `` `self` = > Parent `` // in a child constructor still yields the most specific `_type`. entries.retain(|(k, _)| k != "_type"); entries.insert(0, ("_type".into(), Value::Text(type_name.into()))); Value::Map(entries) } Value::None => Value::Map(vec![("_type".into(), Value::Text(type_name.into()))]), other => Value::Map(vec![ ("_type".into(), Value::Text(type_name.into())), ("value".into(), other), ]), } } /// Bind evaluated args onto parameter names. Err is a plain message (caller adds span/path). fn bind_function_args( interp: &mut Interpreter, module: &Module, caller: &Function, caller_env: &mut Env, params: &[Param], args: &[EvArg], allow_missing: bool, ) -> std::result::Result, String> { let mut named: HashMap = HashMap::new(); let mut positionals = Vec::new(); for a in args { match a { EvArg::Positional(v) => positionals.push(v.clone()), EvArg::Named(k, v) => { if named.contains_key(k) { return Err(format!("duplicate named argument `{k}`")); } named.insert(k.clone(), v.clone()); } } } let mut out: HashMap = HashMap::new(); let mut used_named = HashSet::new(); let mut pos_i = 0usize; for p in params { if let Some(v) = named.get(&p.name) { out.insert(p.name.clone(), v.clone()); used_named.insert(p.name.clone()); } else if pos_i < positionals.len() { out.insert(p.name.clone(), positionals[pos_i].clone()); pos_i += 1; } else if let Some(def) = &p.default { let v = interp .eval_expr(module, caller, caller_env, def) .map_err(|e| e.to_string())?; out.insert(p.name.clone(), v); } else if !allow_missing { return Err(format!("missing argument for parameter `{}`", p.name)); } } if pos_i < positionals.len() { return Err(format!( "too many positional arguments ({} extra)", positionals.len() - pos_i )); } for (k, v) in named { if !used_named.contains(&k) && !out.contains_key(&k) { out.insert(k, v); } } Ok(out) } /// Bind evaluated args onto parameter names (host / plugin functions). fn bind_args( params: &[String], args: &[EvArg], allow_missing: bool, ) -> std::result::Result, String> { let mut named: HashMap = HashMap::new(); let mut positionals = Vec::new(); for a in args { match a { EvArg::Positional(v) => positionals.push(v.clone()), EvArg::Named(k, v) => { if named.contains_key(k) { return Err(format!("duplicate named argument `{k}`")); } named.insert(k.clone(), v.clone()); } } } let mut out: HashMap = HashMap::new(); let mut used_named = HashSet::new(); let mut pos_i = 0usize; for p in params { if let Some(v) = named.get(p) { out.insert(p.clone(), v.clone()); used_named.insert(p.clone()); } else if pos_i < positionals.len() { out.insert(p.clone(), positionals[pos_i].clone()); pos_i += 1; } else if !allow_missing { return Err(format!("missing argument for parameter `{p}`")); } } if pos_i < positionals.len() { return Err(format!( "too many positional arguments ({} extra)", positionals.len() - pos_i )); } for (k, v) in named { if !used_named.contains(&k) && !out.contains_key(&k) { out.insert(k, v); } } Ok(out) } fn collect_decl_reads(expr: &Expr, out: &mut std::collections::HashSet) { match expr { Expr::Var(name) => { out.insert(name.clone()); } Expr::Interp(parts) => { for part in parts { match part { InterpPart::Var(name) => { out.insert(name.clone()); } InterpPart::Index { base, .. } => { out.insert(base.clone()); } InterpPart::Lit(_) => {} } } } Expr::Index { base, label } => { collect_decl_reads(base, out); if let IndexKey::Var(name) = label { out.insert(name.clone()); } } Expr::Binary { left, right, .. } => { collect_decl_reads(left, out); collect_decl_reads(right, out); } Expr::Unary { expr, .. } => collect_decl_reads(expr, out), Expr::List(xs) => { for x in xs { collect_decl_reads(x, out); } } Expr::Map(entries) => { for (_, v) in entries { collect_decl_reads(v, out); } } Expr::Call(call) => { if let Some(receiver) = &call.receiver { out.insert(receiver.clone()); } for arg in &call.args { match arg { Arg::Positional(e) | Arg::Named { value: e, .. } => { collect_decl_reads(e, out); } } } } Expr::Literal(_) | Expr::Formula(_) | Expr::Code(_) => {} } } fn find_top<'a>(module: &'a Module, name: &str) -> Option<&'a Function> { module.functions.iter().find(|f| f.name == name) } /// Resolve `#` object type by name in the entry module or any imported library. fn find_object_type<'a>(module: &'a Module, name: &str) -> Option<(&'a Module, &'a Function)> { fn search<'a>( module: &'a Module, name: &str, seen: &mut std::collections::HashSet<*const Module>, ) -> Option<(&'a Module, &'a Function)> { let key = module as *const Module; if !seen.insert(key) { return None; } if let Some(f) = module .functions .iter() .find(|f| f.name == name && f.is_object()) { return Some((module, f)); } for lib in module.import_modules.values() { if let Some(hit) = search(lib, name, seen) { return Some(hit); } } None } let mut seen = std::collections::HashSet::new(); search(module, name, &mut seen) } /// Resolve `` `obj`.method `` along the inheritance chain (`_type` first, then bases). fn find_method_along_bases<'a>( module: &'a Module, type_name: &str, method: &str, ) -> Option<(&'a Module, &'a Function, &'a Function)> { let mut cur = type_name.to_string(); let mut seen = std::collections::HashSet::new(); while seen.insert(cur.clone()) { let (owner, obj) = find_object_type(module, &cur)?; if let Some(target) = obj.children.iter().find(|c| c.name == method) { return Some((owner, obj, target)); } match &obj.base { Some(b) => cur = b.clone(), None => break, } } None } fn find_function_anywhere<'a>(module: &'a Module, name: &str) -> Option<&'a Function> { for f in &module.functions { if f.name == name { return Some(f); } if let Some(child) = find_in_tree(f, name) { return Some(child); } } None } fn lookup_function<'a>( module: &'a Module, current: &'a Function, name: &str, ) -> Option<&'a Function> { if let Some(f) = find_in_tree(current, name) { return Some(f); } module.functions.iter().find(|f| f.name == name) } fn find_in_tree<'a>(fun: &'a Function, name: &str) -> Option<&'a Function> { for child in &fun.children { if child.name == name { return Some(child); } if let Some(f) = find_in_tree(child, name) { return Some(f); } } None } fn lit_to_value(lit: &Literal) -> Value { match lit { Literal::None => Value::None, Literal::Bool(b) => Value::Bool(*b), Literal::Int(n) => Value::Int(*n), Literal::Num(n) => Value::Num(*n), Literal::Text(s) => Value::Text(s.clone()), } } fn eval_binary(op: BinaryOp, l: &Value, r: &Value) -> Result { match op { BinaryOp::Add => match (l, r) { (Value::Int(a), Value::Int(b)) => Ok(Value::Int(a + b)), (Value::Num(a), Value::Num(b)) => Ok(Value::Num(a + b)), (Value::Int(a), Value::Num(b)) => Ok(Value::Num(*a as f64 + b)), (Value::Num(a), Value::Int(b)) => Ok(Value::Num(a + *b as f64)), (Value::Text(a), Value::Text(b)) => Ok(Value::Text(format!("{a}{b}"))), (Value::Text(a), Value::Secret(b)) => Ok(Value::Text(format!("{a}{b}"))), (Value::Secret(a), Value::Text(b)) => Ok(Value::Text(format!("{a}{b}"))), (Value::Secret(a), Value::Secret(b)) => Ok(Value::Text(format!("{a}{b}"))), (Value::Text(a), b) => Ok(Value::Text(format!("{a}{}", b.as_display()))), (a, Value::Text(b)) => Ok(Value::Text(format!("{}{b}", a.as_display()))), _ => bail!("`+` needs ints, nums, or text"), }, BinaryOp::Sub => match (l, r) { (Value::Int(a), Value::Int(b)) => Ok(Value::Int(a - b)), (Value::Num(a), Value::Num(b)) => Ok(Value::Num(a - b)), (Value::Int(a), Value::Num(b)) => Ok(Value::Num(*a as f64 - b)), (Value::Num(a), Value::Int(b)) => Ok(Value::Num(a - *b as f64)), _ => bail!("`-` needs ints or nums"), }, BinaryOp::Mul => match (l, r) { (Value::Int(a), Value::Int(b)) => Ok(Value::Int(a * b)), (Value::Num(a), Value::Num(b)) => Ok(Value::Num(a * b)), (Value::Int(a), Value::Num(b)) => Ok(Value::Num(*a as f64 * b)), (Value::Num(a), Value::Int(b)) => Ok(Value::Num(a * *b as f64)), _ => bail!("`*` needs ints or nums"), }, BinaryOp::Div => match (l, r) { (Value::Int(_), Value::Int(0)) => bail!("division by zero"), (Value::Int(a), Value::Int(b)) => Ok(Value::Int(a / b)), (Value::Num(_), Value::Num(b)) if *b == 0.0 => bail!("division by zero"), (Value::Int(_), Value::Num(b)) if *b == 0.0 => bail!("division by zero"), (Value::Num(_), Value::Int(0)) => bail!("division by zero"), (Value::Num(a), Value::Num(b)) => Ok(Value::Num(a / b)), (Value::Int(a), Value::Num(b)) => Ok(Value::Num(*a as f64 / b)), (Value::Num(a), Value::Int(b)) => Ok(Value::Num(a / *b as f64)), _ => bail!("`/` needs ints or nums"), }, BinaryOp::Eq => Ok(Value::Bool(l == r)), BinaryOp::Ne => Ok(Value::Bool(l != r)), BinaryOp::Lt => cmp_ord(l, r, |o| o.is_lt()), BinaryOp::Le => cmp_ord(l, r, |o| o.is_le()), BinaryOp::Gt => cmp_ord(l, r, |o| o.is_gt()), BinaryOp::Ge => cmp_ord(l, r, |o| o.is_ge()), BinaryOp::And | BinaryOp::Or => unreachable!("handled above"), } } fn cmp_ord(l: &Value, r: &Value, f: impl Fn(std::cmp::Ordering) -> bool) -> Result { match (l, r) { (Value::Int(a), Value::Int(b)) => Ok(Value::Bool(f(a.cmp(b)))), (Value::Num(a), Value::Num(b)) => Ok(Value::Bool(f(a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal)))), (Value::Int(a), Value::Num(b)) => { Ok(Value::Bool(f((*a as f64).partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal)))) } (Value::Num(a), Value::Int(b)) => { Ok(Value::Bool(f(a.partial_cmp(&(*b as f64)).unwrap_or(std::cmp::Ordering::Equal)))) } (Value::Text(a), Value::Text(b)) => Ok(Value::Bool(f(a.cmp(b)))), _ => bail!("comparison needs two ints/nums or two texts"), } } fn brief_trace_val(v: &Value) -> String { let s = v.as_display(); if s.chars().count() > 24 { format!("{}…", s.chars().take(24).collect::()) } else { s } } /// Prefer real result; else last stdout line emitted by the call; else callee name. fn call_event_brief(v: &Value, stdout: &str, stdout_before: usize, callee: &str) -> String { if !matches!(v, Value::None) { return brief_trace_val(v); } if stdout.len() > stdout_before { let delta = &stdout[stdout_before..]; let line = delta .trim_end() .lines() .last() .unwrap_or(delta.trim_end()); if !line.is_empty() { return if line.chars().count() > 48 { format!("{}…", line.chars().take(48).collect::()) } else { line.to_string() }; } } callee.to_string() } fn stmt_span(stmt: &Stmt) -> Span { match stmt { Stmt::Assign { span, .. } | Stmt::Return { span, .. } | Stmt::Call { span, .. } | Stmt::Expr { span, .. } | Stmt::Branch { span, .. } | Stmt::While { span, .. } | Stmt::ForEach { span, .. } => *span, } }