diff --git a/README.md b/README.md index 3dc6cda..3fe21e6 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程 1. 叙述默认安全(无标记 = 注释)。 2. 返回是架构;打印只是函数。 3. 依赖清单由工具生成(OKF 风格),不是手填配置。 -4. **正经解释器**:词法/行分类 → 语法 → 语义 → 树遍历(再字节码);见 [路线图](doc/roadmap/interpreter.md)。实现语言 **Python**([ADR 0001](doc/adr/0001-implementation-language.md))。 +4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。 --- @@ -48,10 +48,10 @@ Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程 - 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md) - 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md) -- 选型:[ADR 0001 Accepted — Python](doc/adr/0001-implementation-language.md) -- Spike 存档:[spike/REPORT.md](spike/REPORT.md) +- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md) +- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) -下一步:按路线图 M0 起建正式包,目标 `marqdo run index.mq.md`。 +下一步:Cargo 工程 M0 + 金样例框架,目标 `marqdo run index.mq.md`。 --- diff --git a/doc/README.md b/doc/README.md index e3ecd7b..5c90bb7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -20,8 +20,9 @@ | [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 | | [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 | | [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 | -| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Python 参考解释器** | -| [roadmap/interpreter.md](roadmap/interpreter.md) | **正经解释器路线图**(词法→语法→语义→树遍历→字节码) | +| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** | +| [design/dependencies.md](design/dependencies.md) | **依赖详单**:工具链、Cargo crate、为何不用 Flex/Bison | +| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 | | [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 | 示例与验收集:[`examples/`](../examples/)。Spike 存档:[`spike/`](../spike/)。 diff --git a/doc/adr/0001-implementation-language.md b/doc/adr/0001-implementation-language.md index 93a717e..262dfee 100644 --- a/doc/adr/0001-implementation-language.md +++ b/doc/adr/0001-implementation-language.md @@ -1,52 +1,53 @@ -# ADR 0001:参考实现语言与 Markdown 前端 +# ADR 0001:参考实现语言与前端工具 | | | |---|---| -| 状态 | **Accepted** | +| 状态 | **Accepted**(修订:实现语言 = Rust) | | 日期 | 2026-08-04 | | 决策者 | chaungming + 协作 | -| 相关 | [tech-stack.md](../design/tech-stack.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) | +| 相关 | [dependencies.md](../design/dependencies.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) | --- ## 背景 -语法宪法 v0.1 已定;Python Spike(S1–S5)已通过。需要选定**正经参考解释器**的实现语言(非玩具脚本)。 - -目标:实现完整流水线(词法/行分类 → 语法 → 语义 → 树遍历解释,日后字节码),使 `marqdo run index.mq.md` 得到真实结果。编译到龙芯/LLVM **不是** v1 目标(见路线图与 [USTC 编译课](https://ustc-compiler-2025.github.io/homepage/) 的对照说明)。 +语法宪法 v0.1 已定;Python Spike 已验证 GFM/行扫描风险。产品目标是正经**解释器**(`marqdo run index.mq.md`),实现语言需兼顾安全与可维护性。 --- ## 决策 -1. **参考解释器实现语言:Python 3.11+** - - Markdown 辅助:`markdown-it-py`(表格/强调等) - - 测试:`pytest` + examples 金样例 - - CLI:`marqdo` 入口 +1. **参考解释器实现语言:Rust(stable)** + - 内存安全、单静态二进制、适合长期演进到字节码 VM。 + - Python Spike **保留为算法原型/对照**,不是运行时依赖。 -2. **架构分期**(强制): - - **Phase I**:递归下降 AST + **树遍历解释器**(对齐 Crafting Interpreters jlox) - - **Phase II**:AST → **字节码 + VM**(对齐 clox / 主流脚本语言实现) - - 详情:[interpreter.md](../roadmap/interpreter.md) +2. **词法 / 语法:不使用 Flex、Bison** + - 解释器需要词法·语法**阶段**,不需要这两个 C 生成器。 + - Marqdo 采用:自研行分类 + GFM 库 + **手写递归下降** → AST。 + - 详见 [dependencies.md](../design/dependencies.md)。 -3. **`spike/`** 仅作风险探测存档;正式代码在可安装包 `marqdo/`(或 `src/marqdo/`)中生长。 +3. **架构分期不变** + - Phase I:树遍历解释器 + - Phase II:字节码 + VM + - 见 [interpreter.md](../roadmap/interpreter.md) -4. **长期**:不排除 Rust 重写 VM/全前端;须另开 ADR,且金样例行为不变。 +4. **Markdown 库** + - `pulldown-cmark` 或 `comrak` 二选一(建包前短 Spike 钉死)。 --- ## 后果 -- 立即按路线图建立正式包与 M0–M4,禁止 hello 特判冒充完成。 -- TypeScript / 纯编译后端不作为 v1 主路径。 -- USTC 课程中的词法/语法/语义/IR 思想复用;Flex/Bison/龙芯后端不搬用。 +- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。 +- 金样例仍为 `examples/`;行为与宪法一致。 +- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。 --- -## 否决的替代 +## 否决 -| 方案 | 否决原因 | -|------|----------| -| 只做正则玩具跑 hello | 达不到「一门语言」 | -| v1 直接 LLVM/龙芯 | 与「文档即运行」产品形态错配;工期错置 | -| Spike 未过就上 TS/npm | 已用 Python 验证前端风险,换栈无增益 | +| 方案 | 原因 | +|------|------| +| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 | +| v1 上 LLVM | 产品是解释执行文档,不是机器后端 | +| 仅 Python 正则玩具 | 达不到安全与长期目标 | diff --git a/doc/design/dependencies.md b/doc/design/dependencies.md new file mode 100644 index 0000000..a5188dd --- /dev/null +++ b/doc/design/dependencies.md @@ -0,0 +1,169 @@ +# Marqdo 实现依赖说明(Rust 参考解释器) + +| | | +|---|---| +| 状态 | 已定 | +| 日期 | 2026-08-04 | +| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) | + +--- + +## 1. 要不要 Flex / Bison? + +### 结论:**不需要。解释器也不依赖 Flex/Bison。** + +| 工具 | 典型用途 | Marqdo 为何不用 | +|------|----------|-----------------| +| **Flex** | 从正则生成 C 词法分析器 | 我们的「词法」是 **行分类 + Markdown 标记**,不是 C 式 `identifier|number|…` 字符流;且目标实现是 **Rust**,不是 C 工具链 | +| **Bison** | 从 Yacc 文法生成 C LR 语法分析器 | Marqdo 表面是 **GFM 文档结构**;整体语法不适合写成单一 Bison 文法。解释器主流做法是 **手写递归下降** 或 Rust 生态的 PEG/组合子,而非 Bison | + +[USTC 编译课 Lab1](https://ustc-compiler-2025.github.io/homepage/) 用 Flex/Bison 是为 **Cminusf 编译器** 教学服务的,和「从 `.mq.md` 解释执行」不是同一条产品路径。 + +**解释型语言同样需要词法与语法分析**,但是: + +- 需要的是 **阶段**(lex → parse → AST),不是 **Flex/Bison 这两个具体程序**; +- Python、Ruby、Lua、Crafting Interpreters 的 jlox/clox,大量使用 **手写 lexer + 递归下降**; +- Flex/Bison 是「生成器」选项之一,不是解释器的充分或必要条件。 + +--- + +## 2. Marqdo 前端应怎样做(替代 Flex/Bison) + +拆成三层,比「一个大 lexer/parser」更贴合宪法: + +``` +.mq.md 文本 + │ + ├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行 + ├─② GFM 块/行内(库) 标题、表、强调、列表结构 + ├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md` + └─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST + └─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom +``` + +| 阶段 | 做法 | 对应编译学 | +|------|------|------------| +| ①③ | Rust 手写扫描 | 词法 / 扫描器 | +| ② | `pulldown-cmark` 或 `comrak` | 复用 GFM,避免自研表格/强调 | +| ④ | **手写递归下降**(推荐主路径) | 语法分析 | +| Expr(可选) | `pest`(PEG)或 `nom`(组合子) | 仅迷你表达式,不是整门语言 | + +**不推荐**整门语言上 LALRPOP / rusty_lr / Bison 等价物作为 v1 主前端:Markdown 外壳 + 行语义会让文法极度别扭。若将来有「纯文本 Marqdo 方言」,再另议生成器。 + +--- + +## 3. 详细依赖清单(Rust) + +### 3.1 工具链(开发机) + +| 依赖 | 用途 | 安装 | +|------|------|------| +| **Rust**(stable,建议 ≥ 1.75) | 编译实现 | [rustup](https://rustup.rs/):`rustup default stable` | +| **Cargo** | 包与构建 | 随 rustup | +| **rustfmt / clippy** | 格式与静态检查 | `rustup component add rustfmt clippy` | +| **Git** | 版本管理 | 已有 | + +**不要安装:** Flex、Bison、LLVM(v1 解释器不需要)。 +(日后若做原生后端再开 ADR;与当前解释器无关。) + +### 3.2 Cargo crate(建议写入根 `Cargo.toml` / workspace) + +#### 必选(Phase I 树遍历解释器) + +| Crate | 角色 | 说明 | +|-------|------|------| +| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 | +| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 | +| **clap** | CLI | `marqdo run [path]` | +| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) | + +#### 强烈建议 + +| Crate | 角色 | +|-------|------| +| **camino** 或标准 `PathBuf` | 路径 | +| **indexmap** | 保序 map(模块导出等) | + +#### 测试 + +| Crate | 角色 | +|-------|------| +| **rust 自带** `#[test]` | 单元测试 | +| **insta** 或手写金文件 | examples 期望 stdout 快照(可选) | +| **assert_cmd** / **predicates** | CLI 集成测试(可选) | + +#### Phase II(字节码 VM,后加) + +无强制新依赖;VM 以自研为主。可选: + +| Crate | 角色 | +|-------|------| +| **num_enum** 等 | opcode 枚举(可选) | + +#### 明确不引入(v1) + +| 东西 | 原因 | +|------|------| +| flex / bison / lemon | 见 §1 | +| lalrpop / rusty_lr 作**整语言**前端 | 与 MD 外壳冲突;递归下降更合适 | +| llvm-sys / inkwell | 非解释器 v1 | +| 完整 Python 运行时嵌入 | 参考实现已定为 Rust,避免双运行时 | + +### 3.3 表达式子语言(可选增强) + +若手写 Expr 递归下降过痛,**仅**对 `` `a` + 1 == `b` `` 这类表达式引入其一: + +| 选项 | 类型 | 何时用 | +|------|------|--------| +| **手写递归下降** | 无新依赖 | 默认;与全书一致、错误信息最好控 | +| **pest** | PEG 生成器 | 文法清晰、想要 `.pest` 文件时 | +| **nom** | 解析组合子 | 要零拷贝/细控时 | + +整文件 `.mq.md` **不要**整份丢给 pest/nom。 + +--- + +## 4. 仓库布局(与依赖对应) + +``` +Cargo.toml # workspace 或单包 +crates/marqdo/ # 或根包 marqdo + src/ + main.rs / lib.rs + lex/ # 行分类、Token(自研,无 flex) + parse/ # 递归下降(自研,无 bison) + ast/ + sema/ + interp/ # Phase I + bytecode/ # Phase II + runtime/ + tests/ +examples/ # 金样例(已有) +spike/ # Python 风险探测存档(可保留,非运行时依赖) +``` + +开发命令示例: + +```bash +cargo build +cargo test +cargo run -- run examples/index.mq.md +``` + +--- + +## 5. 与 Python Spike 的关系 + +| | Python `spike/` | Rust 参考实现 | +|--|-----------------|---------------| +| 角色 | 已验证 S1–S5 风险 | **正式**词法/语法/语义/解释器 | +| 是否运行时依赖 | 否 | 是 | +| 算法可迁移 | 行扫描、`split_front_matter`、导入正则 | 用 Rust 重写同算法 | + +--- + +## 6. 一句话对照 + +- **需要:** 词法(行分类+标记)、语法(递归下降→AST)、语义、解释器/日后 VM。 +- **不需要:** Flex、Bison、LLVM(v1)。 +- **外部库只需:** Rust 工具链 + GFM crate(pulldown-cmark/comrak)+ CLI/错误/测试若干;表达式可选 pest/nom。 diff --git a/doc/roadmap/interpreter.md b/doc/roadmap/interpreter.md index d452a11..09d414f 100644 --- a/doc/roadmap/interpreter.md +++ b/doc/roadmap/interpreter.md @@ -52,12 +52,13 @@ index.mq.md (+ 导入的 .mq.md) ▼ ┌───────────────────┐ │ 1. 词法·行分类 │ 注释行丢弃语义;代码行 → Token 流 -│ (+ MD 块辅助) │ markdown-it 管表/强调/标题;+/- 靠行扫描 +│ (+ MD 块辅助) │ pulldown-cmark/comrak;+/- 靠行扫描 └─────────┬─────────┘ ▼ ┌───────────────────┐ │ 2. 语法分析 │ Token/块 → Marqdo AST │ (递归下降) │ Module / Fun / Stmt / Expr / Branch / Loop … +│ │ **不用 Flex/Bison**(见 dependencies.md) └─────────┬─────────┘ ▼ ┌───────────────────┐ @@ -127,39 +128,25 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对 ## 5. 实现语言(本路线图默认) -在 Spike 已通过的前提下,**参考解释器默认继续 Python 3.11+**: +**参考解释器:Rust**([ADR 0001](../adr/0001-implementation-language.md))。 -- 与 `spike/` 同栈,立刻能长成正式包; -- 树遍历与日后字节码 VM 都可用 Python 写清; -- 若日后要单二进制/极致性能,再 ADR 引入 Rust **重写 VM 或全前端**,金样例不变。 - -将 [ADR 0001](../adr/0001-implementation-language.md) 标为 Accepted(Python 参考实现)。 +- 词法/语法:**自研 + GFM crate**,不用 Flex/Bison([dependencies.md](../design/dependencies.md))。 +- Python `spike/` 仅作风险探测与算法草稿。 +- Phase I 树遍历、Phase II 字节码 VM 均在 Rust 中实现。 --- ## 6. 目录规划(正式代码,非 spike) ``` -marqdo/ # 可安装包 - __init__.py - cli.py # marqdo run - lex/ # 行分类、标记词法 - parse/ # 递归下降 → AST - ast_nodes.py - sema/ # 作用域、导入、提升 - runtime/ # 值、环境、内置 - interp/ # Phase I 树遍历 - bytecode/ # Phase II(后建) - diagnostics.py +Cargo.toml +crates/marqdo/ # 或根包 + src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/ tests/ - gold/ # examples → expected.stdout - unit/ -examples/ # 已有宪法示例 = 验收集 -docs → 已有 doc/ +examples/ +spike/ # Python 存档,非运行时依赖 ``` -`spike/` 仅保留为风险探测;**正式逻辑不得长期只活在 spike 里**。 - --- ## 7. 近期里程碑(可执行顺序)