Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
179 lines
7.2 KiB
Markdown
179 lines
7.2 KiB
Markdown
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | 已定 |
|
||
| 日期 | 2026-08-04 |
|
||
| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) |
|
||
|
||
---
|
||
|
||
## 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](https://ustc-compiler-2025.github.io/homepage/) 用 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](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 **键值**;嵌套 `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 风险探测存档(可保留,非运行时依赖)
|
||
```
|
||
|
||
开发命令示例:
|
||
|
||
```bash
|
||
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。
|