Switch reference impl to Rust and document deps without Flex/Bison.

Interpreters need lex/parse phases via hand-written descent plus a GFM crate; record the Cargo toolchain and reject C generator frontends for Marqdo.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-04 11:13:23 +08:00
1 parent fd128abd13
commit 1ae2ae0be8
5 files changed
+213 -55

No files matched your search

+4 -4
View File
@@ -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`。
---
+3 -2
View File
@@ -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/)。
+26 -25
View File
@@ -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 正则玩具 | 达不到安全与长期目标 |
+169
View File
@@ -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。
+11 -24
View File
@@ -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. 近期里程碑(可执行顺序)