feat(lang): M2 遮蔽语法 [描述](实现) — 描述不执行,payload 是唯一执行体

新增 Expr::Occluded { label, payload: Option<Box<Expr>> }:
- [] 描述:自由文本,永不执行(仅用于检索/统计/过期校验)
- () 实现:唯一执行体;为空时值为 None(空载荷桩)
- 支持嵌套遮蔽、描述含空格与中文标点、\] 转义

关键决策:**模式开关,暂不切换语义**
[键](集合) 与 [描述](实现) 外形完全相同;M2 若直接改语义,全仓 506 处取元会
静默变成"遮蔽整个集合"(同形换义,文档点名的最坏一类)。
故 M2 只实现能力:
- 默认 Classic:MARQDO_MARKUP 未设 → [a](b) 仍是取元
- 纯度 Occlusion:MARQDO_MARKUP=occlusion/purity/1/on → 遮蔽
M7 才迁移语料、翻转默认、对旧形报 syntax.legacy_index 硬错误。

实现:
- ast.rs 新节点
- parse/expr.rs:Markup 枚举 + set_markup_default + parse_expr_markup(显式模式,
  避免测试依赖全局) + parse_occluded(描述扫描到 ]、\] 转义、必须紧跟 (、
  空载荷 → None)+ Parser.markup 字段
- interp.rs:有 payload 求值 payload,否则 None;collect_decl_reads 递归 payload
- bytecode/compile.rs:编译 payload(空则 Op::None_),双后端一致
- view/render.rs:expr_prec 渲染 [描述](payload) / [描述]()
- parse/mod.rs:pub mod expr
- main.rs:MARQDO_MARKUP 环境变量(init_markup_from_env)

测试:
- 8 个单元(值直通/空载荷/描述空格标点/转义/嵌套/classic 仍取元/缺括号报错)
- 3 个集成 tests/occlusion.rs + tests/occlusion/*.mq.md
- 全量 cargo test --release:575 passed / 0 failed(M1 后 565 + 10)
- tree 与 bytecode 双后端一致

文档:doc/design/change-m2-occlusion.md
This commit is contained in:
cflmy committed 2026-10-22 15:11:59 +08:00
1 parent 13012cac0e
commit 11417c42e0
11 files changed
+424 -1

No files matched your search

+126
View File
@@ -0,0 +1,126 @@
# 变更记录:M2 遮蔽语法 `[描述](实现)`
| | |
|---|---|
| 状态 | **Implemented**(模式开关默认仍是 classic) |
| 日期 | 2026-10-22 |
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
---
## 1. 新增语法
```markdown
[描述](实现)
```
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
- `()` = **实现**(唯一执行体)
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
实测(`MARQDO_MARKUP=occlusion`):
```
a=2 [加一之后的值](1 + 1)
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
c=True [某某功能开发中]() ← 空载荷 → None
```
---
## 2. 关键决策:**模式开关,暂不切换语义**
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
因此 M2 只**实现能力**,不动默认:
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|------|-----------------|-----------------|
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
---
## 3. 实现要点
### 3.1 AST
```rust
Occluded {
label: String,
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
}
```
### 3.2 解析
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
### 3.3 求值(两个后端一致)
| 位置 | 处理 |
|------|------|
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
**描述永不参与求值**——守住铁律 1。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
| 双后端 | tree 与 `--backend bytecode` | 一致 |
---
## 5. 顺带重构
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
(全局只由 CLI 入口设置一次)。
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
---
## 6. 边界
| 项 | 说明 |
|----|------|
| 描述不参与作用域/类型 | 写什么都不影响执行 |
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
| 跨行描述 | 不支持(v1) |
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
| `src/interp.rs` | 求值 + 读引用收集 |
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
| `doc/design/change-m2-occlusion.md` | 本文件 |
+8
View File
@@ -211,6 +211,14 @@ pub enum Expr {
Formula(FormulaExpr),
/// Bound ```lang … ``` fence (`code` value).
Code(CodeBlock),
/// `[描述](实现)` — **occlusion**: `label` is inert prose (never executed,
/// only scanned for keywords and checked for staleness), `payload` is the
/// only thing that runs. `payload: None` means the empty-payload stub
/// (`[某某功能开发中]()`), which evaluates to `None`. `<TAB>` M2
Occluded {
label: String,
payload: Option<Box<Expr>>,
},
}
#[derive(Debug, Clone)]
+6
View File
@@ -825,6 +825,12 @@ impl<'a> FnCompiler<'a> {
fn compile_expr(&mut self, expr: &Expr) -> Result<()> {
match expr {
// `<TAB>` M2: occlusion is transparent for execution — only the
// payload runs; the label is diagnosed/rendered, never evaluated.
Expr::Occluded { payload, .. } => match payload {
Some(inner) => self.compile_expr(inner)?,
None => self.emit(Op::None_),
},
Expr::Literal(lit) => match lit {
Literal::None => self.emit(Op::None_),
Literal::Bool(true) => self.emit(Op::True),
+10
View File
@@ -1113,6 +1113,11 @@ impl Interpreter {
}
Expr::Formula(e) => Ok(Value::Formula(e.clone())),
Expr::Code(c) => Ok(Value::Code(c.clone())),
// `<TAB>` M2: the label is inert prose; only the payload evaluates.
Expr::Occluded { payload, .. } => match payload {
Some(inner) => self.eval_expr(module, fun, env, inner),
None => Ok(Value::None),
},
}
}
@@ -1652,6 +1657,11 @@ fn bind_args(
fn collect_decl_reads(expr: &Expr, out: &mut std::collections::HashSet<String>) {
match expr {
Expr::Occluded { payload, .. } => {
if let Some(inner) = payload {
collect_decl_reads(inner, out);
}
}
Expr::Var(name) => {
out.insert(name.clone());
}
+13
View File
@@ -388,7 +388,20 @@ enum ViewAction {
},
}
/// `<TAB>` M2: `MARQDO_MARKUP=occlusion` enables `[描述](实现)` (purity mode).
/// Default stays `classic` so legacy `[键](集合)` keeps its meaning until M7.
fn init_markup_from_env() {
if let Ok(v) = std::env::var("MARQDO_MARKUP") {
let m = match v.trim().to_ascii_lowercase().as_str() {
"occlusion" | "purity" | "1" | "on" | "true" => marqdo::parse::expr::Markup::Occlusion,
_ => marqdo::parse::expr::Markup::Classic,
};
marqdo::parse::expr::set_markup_default(m);
}
}
fn main() -> ExitCode {
init_markup_from_env();
let cli = Cli::parse();
let json_errors = matches!(
&cli.command,
+178
View File
@@ -8,6 +8,38 @@ pub fn parse_expr(input: &str) -> Result<Expr> {
parse_expr_mode(input, false)
}
/// Markup mode for `[描述](实现)` vs the legacy `[键](集合)` index. `<TAB>` M2
///
/// `Classic` keeps today's index semantics; `Occlusion` reads the same shape as
/// an occlusion. The default is `Classic` until M7 migrates the corpus and flips
/// the gate (otherwise every legacy index would silently change meaning).
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
pub enum Markup {
#[default]
Classic,
Occlusion,
}
static MARKUP: std::sync::atomic::AtomicU8 = std::sync::atomic::AtomicU8::new(0);
/// Set the process-wide default markup mode (CLI / tests).
pub fn set_markup_default(m: Markup) {
MARKUP.store(
match m {
Markup::Classic => 0,
Markup::Occlusion => 1,
},
std::sync::atomic::Ordering::Relaxed,
);
}
pub fn markup_default() -> Markup {
match MARKUP.load(std::sync::atomic::Ordering::Relaxed) {
1 => Markup::Occlusion,
_ => Markup::Classic,
}
}
/// Italic / bold value syntax: bare words are variables; text needs `"…"` / `'…'`.
pub fn parse_expr_prefer_var(input: &str) -> Result<Expr> {
parse_expr_mode(input, true)
@@ -17,6 +49,17 @@ fn parse_expr_mode(input: &str, prefer_var: bool) -> Result<Expr> {
parse_expr_opts(input, prefer_var, true)
}
/// Parse a full expression under an explicit markup mode (tests / migration).
pub fn parse_expr_markup(input: &str, prefer_var: bool, markup: Markup) -> Result<Expr> {
let mut p = Parser::new(input.trim(), prefer_var, true).with_markup(markup);
let e = p.parse_or()?;
p.skip_ws();
if !p.rest().is_empty() {
bail!("trailing input in expression: {:?}", p.rest());
}
Ok(e)
}
/// Parse a full expression; `allow_paren_call` controls `name(args)` postfix calls.
fn parse_expr_opts(input: &str, prefer_var: bool, allow_paren_call: bool) -> Result<Expr> {
let mut p = Parser::new(input.trim(), prefer_var, allow_paren_call);
@@ -232,6 +275,8 @@ struct Parser<'a> {
i: usize,
/// When true (italic/bold), bare words are variables, not text literals.
prefer_var: bool,
/// `<TAB>` M2: how to read `[…] (...)`.
markup: Markup,
/// `<TAB>` M1: allow `name(args)` postfix calls inside this expression.
/// Classic (space-separated) call *values* stay text-like, so they turn
/// this off to keep `source=print(2+2)` as text.
@@ -244,10 +289,16 @@ impl<'a> Parser<'a> {
src,
i: 0,
prefer_var,
markup: markup_default(),
allow_paren_call,
}
}
fn with_markup(mut self, markup: Markup) -> Self {
self.markup = markup;
self
}
fn rest(&self) -> &str {
&self.src[self.i..]
}
@@ -466,6 +517,9 @@ impl<'a> Parser<'a> {
// Link-shaped index `[key](collection)` vs bracket-marked call `[callee] …`
// vs JSON-ish `[…]` (arg text fallback when expr parse fails).
if self.starts_with("[") && !self.starts_with("[^") {
if self.markup == Markup::Occlusion {
return self.parse_occluded();
}
if link_index_shape_ahead(self.rest()) {
return self.parse_link_index();
}
@@ -622,6 +676,63 @@ impl<'a> Parser<'a> {
bail!("unexpected expression input: {:?}", self.rest());
}
/// `[描述](实现)` — occlusion. `<TAB>` M2
///
/// - label: raw prose up to `]` (`\]` escapes a literal bracket)
/// - payload: expression, or empty → `None` (empty-payload stub)
fn parse_occluded(&mut self) -> Result<Expr> {
if !self.eat("[") {
bail!("expected '[' for occlusion");
}
let mut label = String::new();
loop {
let Some(c) = self.peek_char() else {
bail!("unterminated occlusion label `[…]`");
};
match c {
']' => {
self.bump_char();
break;
}
'\\' => {
self.bump_char();
match self.peek_char() {
Some(n) => {
label.push(n);
self.bump_char();
}
None => bail!("unterminated escape in occlusion label"),
}
}
'\n' | '\r' => bail!("unterminated occlusion label `[…]`"),
_ => {
label.push(c);
self.bump_char();
}
}
}
self.skip_ws();
if !self.eat("(") {
bail!("occlusion `[描述]` must be followed by `(实现)`");
}
self.skip_ws();
if self.eat(")") {
return Ok(Expr::Occluded {
label: label.trim().to_string(),
payload: None,
});
}
let inner = self.parse_or()?;
self.skip_ws();
if !self.eat(")") {
bail!("expected ')' to close occlusion payload");
}
Ok(Expr::Occluded {
label: label.trim().to_string(),
payload: Some(Box::new(inner)),
})
}
/// `` `xs`[^1] `` / `m[^key]` / chained `m[^k][^1]` (base already parsed).
fn parse_index_chain(&mut self, mut expr: Expr) -> Result<Expr> {
loop {
@@ -1951,6 +2062,73 @@ mod bracket_call_tests {
assert_eq!(c.callee, "加一 号");
}
// ---- M2: 遮蔽语法 `[描述](实现)` ----
fn occl(e: Expr) -> (String, Option<Expr>) {
match e {
Expr::Occluded { label, payload } => (label, payload.map(|b| *b)),
other => panic!("expected Occluded, got {other:?}"),
}
}
#[test]
fn occlusion_basic_value_passthrough() {
let e = parse_expr_markup("[加一之后的值](加(1))", false, Markup::Occlusion).unwrap();
let (label, payload) = occl(e);
assert_eq!(label, "加一之后的值");
assert!(matches!(payload, Some(Expr::Call(_))));
}
#[test]
fn occlusion_empty_payload_is_none() {
let e = parse_expr_markup("[某某功能开发中]()", false, Markup::Occlusion).unwrap();
let (label, payload) = occl(e);
assert_eq!(label, "某某功能开发中");
assert!(payload.is_none());
}
#[test]
fn occlusion_label_allows_spaces_and_punctuation() {
let e = parse_expr_markup(
"[按 `税率` 与档位计算,注意四舍五入](1 + 2)",
true,
Markup::Occlusion,
)
.unwrap();
let (label, payload) = occl(e);
assert!(label.contains("税率"));
assert!(payload.is_some());
}
#[test]
fn occlusion_label_escaped_bracket() {
let e = parse_expr_markup("[数组 a\\]b 的长度](1)", false, Markup::Occlusion).unwrap();
let (label, _) = occl(e);
assert_eq!(label, "数组 a]b 的长度");
}
#[test]
fn occlusion_nested() {
let e = parse_expr_markup("[外层]([内层](1))", false, Markup::Occlusion).unwrap();
let (label, payload) = occl(e);
assert_eq!(label, "外层");
let (inner_label, inner_payload) = occl(payload.unwrap());
assert_eq!(inner_label, "内层");
assert!(matches!(inner_payload, Some(Expr::Literal(Literal::Int(1)))));
}
#[test]
fn occlusion_classic_mode_keeps_index() {
let e = parse_expr_markup("[键](表)", false, Markup::Classic).unwrap();
assert!(matches!(e, Expr::Index { .. }), "classic must stay an index");
}
#[test]
fn occlusion_requires_paren() {
let err = parse_expr_markup("[只有描述]", false, Markup::Occlusion).unwrap_err();
assert!(err.to_string().contains("followed by"), "{err}");
}
#[test]
fn modifier_conflict_expands() {
let (c, _) = parse_call_tail("礼貌 [问候] 礼貌=False", false).unwrap();
+6 -1
View File
@@ -1,6 +1,6 @@
//! Line-oriented recursive descent → AST (no Bison).
mod expr;
pub mod expr;
mod prose;
pub use expr::{
@@ -2091,6 +2091,11 @@ fn collect_reads_call(call: &crate::ast::CallExpr, reads: &mut std::collections:
fn collect_reads_expr(expr: &Expr, reads: &mut std::collections::HashSet<String>) {
match expr {
Expr::Occluded { payload, .. } => {
if let Some(inner) = payload {
collect_reads_expr(inner, reads);
}
}
Expr::Var(n) => {
reads.insert(n.clone());
}
+10
View File
@@ -132,6 +132,11 @@ fn collect_input_prompts_stmt(stmt: &Stmt, out: &mut Vec<String>) {
fn collect_input_prompts_expr(expr: &Expr, out: &mut Vec<String>) {
match expr {
Expr::Occluded { payload, .. } => {
if let Some(inner) = payload {
collect_input_prompts_expr(inner, out);
}
}
Expr::Call(call) => {
push_input_prompt(call, out);
for a in &call.args {
@@ -1445,6 +1450,11 @@ pub fn expr_display(expr: &Expr) -> String {
fn expr_prec(expr: &Expr, parent_prec: u8) -> String {
match expr {
// `<TAB>` M2: show the occlusion surface (label + payload).
Expr::Occluded { label, payload } => match payload {
Some(inner) => format!("[{}]({})", label, expr_prec(inner, 0)),
None => format!("[{}]()", label),
},
Expr::Literal(lit) => lit_display(lit),
Expr::Var(name) => format!("`{name}`"),
Expr::Interp(parts) => {
+45
View File
@@ -0,0 +1,45 @@
//! `<TAB>` M2: occlusion syntax end-to-end (CLI + `MARQDO_MARKUP=occlusion`).
//!
//! The mode flag keeps `[键](集合)` (classic index) intact until M7 migrates the
//! corpus; these tests pin both sides of the switch.
use std::process::Command;
fn run(path: &str, markup: Option<&str>) -> (i32, String, String) {
let mut cmd = Command::new(env!("CARGO_BIN_EXE_marqdo"));
cmd.args(["run", path]);
if let Some(m) = markup {
cmd.env("MARQDO_MARKUP", m);
}
let out = cmd.output().expect("run marqdo");
(
out.status.code().unwrap_or(1),
String::from_utf8_lossy(&out.stdout).into_owned(),
String::from_utf8_lossy(&out.stderr).into_owned(),
)
}
#[test]
fn occlusion_value_is_payload() {
let (code, stdout, stderr) = run("tests/occlusion/value.mq.md", Some("occlusion"));
assert_eq!(code, 0, "stderr={stderr}");
assert_eq!(stdout.trim_end(), "a=2\nb=42\nc=True");
}
#[test]
fn occlusion_off_keeps_classic_index() {
let (code, stdout, stderr) = run("tests/occlusion/classic-index.mq.md", None);
assert_eq!(code, 0, "stderr={stderr}");
assert_eq!(stdout.trim_end(), "值");
}
#[test]
fn occlusion_mode_rejects_legacy_index_shape() {
// In occlusion mode `[键](集合)` is read as an occlusion whose payload is the
// collection — i.e. it returns the *whole* map, not the member. This is why
// M7 must migrate before flipping the default; here we only pin that the
// shape no longer means "index".
let (code, stdout, stderr) = run("tests/occlusion/classic-index.mq.md", Some("occlusion"));
assert_eq!(code, 0, "stderr={stderr}");
assert_ne!(stdout.trim_end(), "值", "occlusion mode must not index");
}
+10
View File
@@ -0,0 +1,10 @@
---
title: classic index still works
import json:lib/json.mq.md
---
# main
**表 = > json.parse text={"键":"值"}**
**v = [键](`表`)**
> print text=`v`
+12
View File
@@ -0,0 +1,12 @@
---
title: occlusion value passthrough
---
# main
**a = [加一之后的值](1 + 1)**
**b = [外层]([内层](40 + 2))**
**c = [某某功能开发中]()**
> print text="a=" + `a`
> print text="b=" + `b`
> print text="c=" + (`c` == None)