feat(lang): M3 access 内建与遮蔽循环 — 为 M7 迁移准备等价语义

access(集合, 键)(别名 取/取值):
- 复用 builtin_footnote_get,与旧 [键](集合) 语义完全一致
  (Map 按键 / List 1-based 下标 / 缺键报 missing map key,不静默 None)
- 不新增平行实现,避免两套索引语义漂移
- 用途:M7 把 506 处 [k](c) 机械改写成 access(c, k),语义零漂移

遮蔽循环:- [描述](遍历 集合 为 变量)
- 仅 occlusion 模式识别;接受 遍历/for 与 为/as/in
- 描述存入 Stmt::ForEach.label(Option<String>),供 M8 渲染/诊断

为什么先 M3 后 M7:迁移目标必须先存在且等价,否则就是"边迁移边发明语义"。

实测:
  access(`表`,"键") → 值;access(`列`,2) → 二;
  缺键 → missing map key(与旧取元同一错误)
  - [篮子里的每个果子](遍历 `列` 为 `果`) → 果=一 / 果=二

测试:2 个集成(含缺键错误保真);全量 595 passed / 0 failed(M5 后 593 + 2)

文档:doc/design/change-m3-access-and-loop.md
This commit is contained in:
cflmy committed 2026-10-22 15:23:36 +08:00
1 parent 409b8df2cb
commit 0405a60d68
7 files changed
+205

No files matched your search

+89
View File
@@ -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<String>`),供 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<String>` |
| `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` | 本文件 |
+3
View File
@@ -115,6 +115,8 @@ pub enum Stmt {
ForEach {
item: String,
collection: String,
/// `<TAB>` M3: occlusion form `- [描述](遍历 集合 为 变量)` carries prose.
label: Option<String>,
body: Vec<Stmt>,
span: Span,
},
@@ -368,6 +370,7 @@ fn dump_stmt(out: &mut String, stmt: &Stmt, depth: usize) {
Stmt::ForEach {
item,
collection,
label: _,
body,
span,
} => {
+1
View File
@@ -419,6 +419,7 @@ impl<'a> FnCompiler<'a> {
Stmt::ForEach {
item,
collection,
label: _,
body,
span,
} => {
+23
View File
@@ -883,6 +883,7 @@ impl Interpreter {
Stmt::ForEach {
item,
collection,
label: _,
body,
span,
} => {
@@ -1184,6 +1185,28 @@ impl Interpreter {
}
match call.callee.as_str() {
// `<TAB>` 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))?;
+43
View File
@@ -961,6 +961,20 @@ impl<'a> Cursor<'a> {
let trimmed = line.text.trim();
let rest = trimmed.strip_prefix('-').unwrap().trim();
// `<TAB>` 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<String> {
Some(s.to_string())
}
/// `<TAB>` 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();
// `遍历 <collection> 为 <item>` (English `for <c> as <i>` 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();
+30
View File
@@ -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}");
}
+16
View File
@@ -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="果子=" + `果`