diff --git a/doc/design/change-m2-occlusion.md b/doc/design/change-m2-occlusion.md new file mode 100644 index 0000000..85fdccc --- /dev/null +++ b/doc/design/change-m2-occlusion.md @@ -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>, // 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` | 本文件 | diff --git a/src/ast.rs b/src/ast.rs index 329ad4d..4bacf45 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -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`. `` M2 + Occluded { + label: String, + payload: Option>, + }, } #[derive(Debug, Clone)] diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs index 0c1b768..3a89f53 100644 --- a/src/bytecode/compile.rs +++ b/src/bytecode/compile.rs @@ -825,6 +825,12 @@ impl<'a> FnCompiler<'a> { fn compile_expr(&mut self, expr: &Expr) -> Result<()> { match expr { + // `` 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), diff --git a/src/interp.rs b/src/interp.rs index 2f5609a..d6b883c 100644 --- a/src/interp.rs +++ b/src/interp.rs @@ -1113,6 +1113,11 @@ impl Interpreter { } Expr::Formula(e) => Ok(Value::Formula(e.clone())), Expr::Code(c) => Ok(Value::Code(c.clone())), + // `` 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) { match expr { + Expr::Occluded { payload, .. } => { + if let Some(inner) = payload { + collect_decl_reads(inner, out); + } + } Expr::Var(name) => { out.insert(name.clone()); } diff --git a/src/main.rs b/src/main.rs index f9dcc00..48f524c 100644 --- a/src/main.rs +++ b/src/main.rs @@ -388,7 +388,20 @@ enum ViewAction { }, } +/// `` 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, diff --git a/src/parse/expr.rs b/src/parse/expr.rs index 6bef9bf..2e998c5 100644 --- a/src/parse/expr.rs +++ b/src/parse/expr.rs @@ -8,6 +8,38 @@ pub fn parse_expr(input: &str) -> Result { parse_expr_mode(input, false) } +/// Markup mode for `[描述](实现)` vs the legacy `[键](集合)` index. `` 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 { parse_expr_mode(input, true) @@ -17,6 +49,17 @@ fn parse_expr_mode(input: &str, prefer_var: bool) -> Result { 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 { + 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 { 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, + /// `` M2: how to read `[…] (...)`. + markup: Markup, /// `` 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. `` M2 + /// + /// - label: raw prose up to `]` (`\]` escapes a literal bracket) + /// - payload: expression, or empty → `None` (empty-payload stub) + fn parse_occluded(&mut self) -> Result { + 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 { loop { @@ -1951,6 +2062,73 @@ mod bracket_call_tests { assert_eq!(c.callee, "加一 号"); } + // ---- M2: 遮蔽语法 `[描述](实现)` ---- + + fn occl(e: Expr) -> (String, Option) { + 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(); diff --git a/src/parse/mod.rs b/src/parse/mod.rs index a4f6f95..604ff05 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -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) { match expr { + Expr::Occluded { payload, .. } => { + if let Some(inner) = payload { + collect_reads_expr(inner, reads); + } + } Expr::Var(n) => { reads.insert(n.clone()); } diff --git a/src/view/render.rs b/src/view/render.rs index 77d561c..7813a79 100644 --- a/src/view/render.rs +++ b/src/view/render.rs @@ -132,6 +132,11 @@ fn collect_input_prompts_stmt(stmt: &Stmt, out: &mut Vec) { fn collect_input_prompts_expr(expr: &Expr, out: &mut Vec) { 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 { + // `` 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) => { diff --git a/tests/occlusion.rs b/tests/occlusion.rs new file mode 100644 index 0000000..6512a77 --- /dev/null +++ b/tests/occlusion.rs @@ -0,0 +1,45 @@ +//! `` 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"); +} diff --git a/tests/occlusion/classic-index.mq.md b/tests/occlusion/classic-index.mq.md new file mode 100644 index 0000000..b790e35 --- /dev/null +++ b/tests/occlusion/classic-index.mq.md @@ -0,0 +1,10 @@ +--- +title: classic index still works +import json:lib/json.mq.md +--- + +# main + +**表 = > json.parse text={"键":"值"}** +**v = [键](`表`)** +> print text=`v` diff --git a/tests/occlusion/value.mq.md b/tests/occlusion/value.mq.md new file mode 100644 index 0000000..a405a3f --- /dev/null +++ b/tests/occlusion/value.mq.md @@ -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)