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:
1 parent
fd128abd13
commit
1ae2ae0be8
5 files changed
+213
-55
No files matched your search
@@ -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
@@ -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/)。
|
||||
|
||||
@@ -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 正则玩具 | 达不到安全与长期目标 |
|
||||
@@ -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
@@ -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. 近期里程碑(可执行顺序)
|
||||
|
||||
Reference in new issue
Block a user