--dump-lines tags [decl]/[bold]/[italic]; --dump-ast prints `inferred` params and `dead=[…]`. Migrate leftover italic-assign unit fixtures to bold/return. Co-authored-by: Cursor <cursoragent@cursor.com>
76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# 解释器流水线可视调试
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | 已定(开发期强制友好) |
|
||
| 日期 | 2026-08-04 |
|
||
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
|
||
|
||
---
|
||
|
||
## 2. CLI 开关
|
||
|
||
```bash
|
||
marqdo run FILE [dumps...]
|
||
marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||
```
|
||
|
||
| 标志 | 阶段 | 输出内容 |
|
||
|------|------|----------|
|
||
| `--dump-lines` | 行分类 | 每行:`kind=Comment\|Code\|Blank` + 原文;v0.3 行内位 `[decl n]` / `[bold …]` / `[italic …]` |
|
||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||
| `--dump-ast` | 语法 | 模块/函数/语句;形参带 `inferred`;叙述死绑定 `dead=[…]` |
|
||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||
|
||
格式约定:
|
||
|
||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||
- `--trace-eval`:每条事件一行 JSON,例如
|
||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||
|
||
---
|
||
|
||
## 3. 横幅示例
|
||
|
||
```
|
||
=== marqdo: lines (tests/structure/hello.mq.md) ===
|
||
1 Blank
|
||
2 Comment | # Hello World
|
||
3 Blank
|
||
4 Comment | 本程序调用...
|
||
5 Blank
|
||
6 Code | > print text=Hello World!
|
||
=== marqdo: end lines ===
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 实现要点
|
||
|
||
- dump 逻辑放在 `src/debug/`(或各阶段 `fmt`),**不**与安静求值路径搅在一起。
|
||
- 每个阶段纯函数:`input → (artifacts, diagnostics)`,CLI 负责打印。
|
||
- 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
|
||
|
||
---
|
||
|
||
## 5. 与里程碑
|
||
|
||
| 里程碑 | 必须可用的 dump |
|
||
|--------|-----------------|
|
||
| M1 | `--dump-lines`(及可选 tokens 雏形) |
|
||
| M2 | `--dump-ast` |
|
||
| M3–M4 | `--dump-sema`、`--trace-eval` |
|
||
| 全程 | `--dump-all` 随阶段增长自动变完整 |
|