- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
7.2 KiB
Executable File
7.2 KiB
Executable File
Marqdo 实现依赖说明(Rust 参考解释器)
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 相关 | ADR 0001 · interpreter 路线图 |
1. 要不要 Flex / Bison?
结论:不需要。 主因不是「用了 Rust」,而是 Marqdo 的语法形态 + 解释器并不绑定生成器。
把两件事分开:
| 问题 | 答案 |
|---|---|
| 因为 Rust 才不用 Flex/Bison? | 否。 Flex/Bison 生成的是 C(也可接 C++)。若实现改成 C++,仍然不建议用它们做 Marqdo 主前端。 |
| 因为是解释器才不用? | 部分相关,但不是全部。 解释器需要词法/语法阶段,但不规定必须用 Flex/Bison;手写递归下降是主流。即便将来做「编译到字节码/原生」,Marqdo 也因 Markdown 外壳而不适合整语言 Bison 化。 |
| 真正主因 | Markup-as-Syntax:源是 GFM 文档结构(标题/列表/强调/表格/行分类),不是 Cminusf 那种纯字符流文法。 |
| 工具 | 典型用途 | Marqdo 为何不用(与宿主语言无关) |
|---|---|---|
| Flex | 正则 → C 词法分析器 | 「词法」是 行分类 + Markdown 标记,不是经典 id|num|op 字符流 |
| Bison | Yacc 文法 → C LR 分析器 | 整体语法绑在 GFM 块结构上,硬写成单一 Bison 文法别扭且难与预览器对齐 |
USTC 编译课 Lab1 用 Flex/Bison,是因为对象语言是 C 式源码的编译器;换 C++ 写那个编译器也合理。
Marqdo 换 Rust 或 C++ 都不改变「主前端不该是 Flex/Bison」这一判断。
解释型语言同样需要词法与语法分析,要的是阶段,不是这两个具体程序。
2. Marqdo 前端应怎样做(替代 Flex/Bison)
拆成三层,比「一个大 lexer/parser」更贴合宪法:
.mq.md 文本
│
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
├─② GFM 块/行内(库) 标题、表、强调、列表结构
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `import file: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: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 键值;嵌套 import: 映射与其它 YAML 键一并解析 |
| ureq (=2.9.7) | HTTP(S) | lib/net;为 Cargo 1.81 另钉 idna_adapter/zeroize(见根 Cargo.toml) |
| regex (=1.13.1) | 正则 | Mid M1 lib/re;default-features=false + std/unicode;无回溯引用 |
| sha2 (=0.10.9) / sha1 (=0.10.6) / md-5 (=0.10.6) / hmac (=0.12.1) | 摘要 | Mid M3 lib/hash |
| getrandom (=0.2.17) | OS 熵 | Mid M3 lib/secrets |
强烈建议
| Crate | 角色 |
|---|---|
camino 或标准 PathBuf |
路径 |
| indexmap | 保序 map(模块导出等) |
测试
| Crate | 角色 |
|---|---|
rust 自带 #[test] |
单元测试 |
| insta 或手写金文件 | tests 期望 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/ # gold.rs + structure|keywords|errors
public/ # 用户可执行文档
spike/ # Python 风险探测存档(可保留,非运行时依赖)
开发命令示例:
cargo build
cargo test
cargo run -- run tests/structure/nested-call.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。