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:
1 parent
409b8df2cb
commit
0405a60d68
7 files changed
+205
No files matched your search
@@ -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` | 本文件 |
|
||||
@@ -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,
|
||||
} => {
|
||||
|
||||
@@ -419,6 +419,7 @@ impl<'a> FnCompiler<'a> {
|
||||
Stmt::ForEach {
|
||||
item,
|
||||
collection,
|
||||
label: _,
|
||||
body,
|
||||
span,
|
||||
} => {
|
||||
|
||||
@@ -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))?;
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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}");
|
||||
}
|
||||
@@ -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="果子=" + `果`
|
||||
Reference in new issue
Block a user