diff --git a/doc/design/change-m3-access-and-loop.md b/doc/design/change-m3-access-and-loop.md new file mode 100644 index 0000000..70b86e6 --- /dev/null +++ b/doc/design/change-m3-access-and-loop.md @@ -0,0 +1,89 @@ +# 变更记录:M3 `access` 与遮蔽循环 + +| | | +|---|---| +| 状态 | **Implemented** | +| 日期 | 2026-10-22 | +| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) | +| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` | +| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 | + +--- + +## 1. `access(集合, 键)` + +旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。 +纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式: + +```markdown +**a = [取表项](access(`表`, "键"))** +**b = [取列表第二项](access(`列`, 2))** +``` + +- 别名:`取` / `取值` / `access` +- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None) +- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移 + +实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`, +**不新增平行实现**(避免两套索引语义)。 + +--- + +## 2. 遮蔽循环 + +```markdown +- [篮子里的每个果子](遍历 `列` 为 `果`) + > print text=`果` +``` + +- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach) +- 接受 `遍历`/`for` 与 `为`/`as`/`in` +- 描述存入 `Stmt::ForEach.label`(`Option`),供 M8 渲染/诊断使用 + +实测: + +``` +a=值 +b=二 +果子=一 +果子=二 +``` + +--- + +## 3. 为什么先做 M3 再做 M7 + +迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。 +先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。 + +--- + +## 4. 测试 + +| 层 | 内容 | 结果 | +|----|------|------| +| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ | +| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) | + +--- + +## 5. 边界 + +| 项 | 说明 | +|----|------| +| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 | +| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 | +| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 | + +--- + +## 6. 变更清单 + +| 文件 | 变更 | +|------|------| +| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) | +| `src/ast.rs` | `Stmt::ForEach.label: Option` | +| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 | +| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` | +| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 | +| `doc/design/change-m3-access-and-loop.md` | 本文件 | diff --git a/src/ast.rs b/src/ast.rs index 4bacf45..be9378d 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -115,6 +115,8 @@ pub enum Stmt { ForEach { item: String, collection: String, + /// `` M3: occlusion form `- [描述](遍历 集合 为 变量)` carries prose. + label: Option, body: Vec, span: Span, }, @@ -368,6 +370,7 @@ fn dump_stmt(out: &mut String, stmt: &Stmt, depth: usize) { Stmt::ForEach { item, collection, + label: _, body, span, } => { diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs index 3a89f53..6463f9b 100644 --- a/src/bytecode/compile.rs +++ b/src/bytecode/compile.rs @@ -419,6 +419,7 @@ impl<'a> FnCompiler<'a> { Stmt::ForEach { item, collection, + label: _, body, span, } => { diff --git a/src/interp.rs b/src/interp.rs index d6b883c..2612b07 100644 --- a/src/interp.rs +++ b/src/interp.rs @@ -883,6 +883,7 @@ impl Interpreter { Stmt::ForEach { item, collection, + label: _, body, span, } => { @@ -1184,6 +1185,28 @@ impl Interpreter { } match call.callee.as_str() { + // `` M3: `access(集合, 键)` — the exact polymorphism of the + // legacy `[键](集合)` index (map key / 1-based list index, error on + // missing). Migration rewrites legacy indexes to this call, so the + // two must stay semantically identical. + "access" | "取" | "取值" => { + let bound = bind_args(&["value".into(), "key".into()], &ev_args, false) + .map_err(|m| self.err(m))?; + let base = bound + .get("value") + .cloned() + .ok_or_else(|| self.err("access requires value (collection)"))?; + let key = bound + .get("key") + .map(|v| match v { + Value::Text(t) => t.clone(), + Value::Int(i) => i.to_string(), + other => other.as_display(), + }) + .ok_or_else(|| self.err("access requires key"))?; + return crate::builtin::builtin_footnote_get(&base, &key) + .map_err(|m| self.err(m)); + } "print" => { let bound = bind_args(&["text".into()], &ev_args, false) .map_err(|m| self.err(m))?; diff --git a/src/parse/mod.rs b/src/parse/mod.rs index 604ff05..0600432 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -961,6 +961,20 @@ impl<'a> Cursor<'a> { let trimmed = line.text.trim(); let rest = trimmed.strip_prefix('-').unwrap().trim(); + // `` M3: occlusion loop `- [描述](遍历 集合 为 变量)` + if crate::parse::expr::markup_default() == crate::parse::expr::Markup::Occlusion { + if let Some((label, coll, item)) = parse_occluded_foreach(rest) { + let body = self.parse_indented_body(base_indent)?; + return Ok(Stmt::ForEach { + item, + collection: coll, + label: Some(label), + body, + span, + }); + } + } + // foreach: [item](collection) or narrative sugar if let Some((item, coll)) = parse_foreach_header(rest) .or_else(|| parse_foreach_narrative(rest)) @@ -969,6 +983,7 @@ impl<'a> Cursor<'a> { return Ok(Stmt::ForEach { item, collection: coll, + label: None, body, span, }); @@ -1263,6 +1278,34 @@ fn parse_foreach_ident(s: &str) -> Option { Some(s.to_string()) } +/// `` M3: `[描述](遍历 集合 为 变量)` → `(label, collection, item)`. +fn parse_occluded_foreach(rest: &str) -> Option<(String, String, String)> { + let rest = rest.trim(); + if !rest.starts_with('[') { + return None; + } + let end = rest.find(']')?; + let label = rest[1..end].trim().to_string(); + let after = rest[end + 1..].trim_start(); + if !after.starts_with('(') || !after.ends_with(')') { + return None; + } + let inner = after[1..after.len() - 1].trim(); + let parts: Vec<&str> = inner.split_whitespace().collect(); + // `遍历 为 ` (English `for as ` accepted too) + if parts.len() != 4 { + return None; + } + let head_ok = matches!(parts[0], "遍历" | "for"); + let mid_ok = matches!(parts[2], "为" | "as" | "in"); + if !head_ok || !mid_ok { + return None; + } + let coll = parse_foreach_ident(parts[1])?; + let item = parse_foreach_ident(parts[3])?; + Some((label, coll, item)) +} + fn parse_foreach_header(rest: &str) -> Option<(String, String)> { // [`item`](`collection`) or bare [item](collection); sides may mix. let rest = rest.trim(); diff --git a/tests/occlusion.rs b/tests/occlusion.rs index e3562fd..33362c0 100644 --- a/tests/occlusion.rs +++ b/tests/occlusion.rs @@ -277,3 +277,33 @@ fn implicit_labels_opt_in_stays_quiet_when_consistent() { let text = String::from_utf8_lossy(&out.stdout).into_owned(); assert!(!text.contains("调用上方的描述"), "{text}"); } + +// ---- M3: `access` (legacy index semantics) + occlusion loop ---- + +#[test] +fn access_matches_legacy_index_semantics() { + let (code, stdout, stderr) = run("tests/occlusion/access-and-loop.mq.md", Some("occlusion")); + assert_eq!(code, 0, "stderr={stderr}"); + assert_eq!(stdout.trim_end(), "a=值\nb=二\n果子=一\n果子=二"); +} + +#[test] +fn access_errors_on_missing_key_like_legacy() { + // Same failure mode as `[键](集合)`: no silent None. + let dir = std::env::temp_dir().join("marqdo-m3-access"); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("missing.mq.md"); + std::fs::write( + &path, + "---\nimport json:lib/json.mq.md\n---\n\n# main\n\n`表` = > json.parse text={\"键\":\"值\"}\n**x = [取不存在的键](access(`表`, \"无\"))**\n> print text=`x`\n", + ) + .unwrap(); + let out = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["run", path.to_str().unwrap()]) + .env("MARQDO_MARKUP", "occlusion") + .output() + .expect("run"); + assert_ne!(out.status.code(), Some(0)); + let err = String::from_utf8_lossy(&out.stderr); + assert!(err.contains("missing map key"), "err={err}"); +} diff --git a/tests/occlusion/access-and-loop.mq.md b/tests/occlusion/access-and-loop.mq.md new file mode 100644 index 0000000..660160c --- /dev/null +++ b/tests/occlusion/access-and-loop.mq.md @@ -0,0 +1,16 @@ +--- +title: access + occlusion loop +import json:lib/json.mq.md +--- + +# main + +`表` = > json.parse text={"键":"值"} +`列` = > json.parse text=["一","二"] + +**a = [取表项](access(`表`, "键"))** +**b = [取列表第二项](access(`列`, 2))** +> print text="a=" + `a` +> print text="b=" + `b` +- [篮子里的每个果子](遍历 `列` 为 `果`) + > print text="果子=" + `果`