Tree walk logs enter_fn/stmt/leave_fn; bytecode logs op events for print/input/call/return, paving the way for view debug pause hooks. Co-authored-by: Cursor <cursoragent@cursor.com>
2.6 KiB
2.6 KiB
解释器流水线可视调试
| 状态 | 已定(开发期强制友好) |
| 日期 | 2026-08-04 |
| 参考 | Crafting Interpreters — Scanning(先打 token)· AstPrinter · CLI --dump-ast 类实践 |
1. 目标
开发 marqdo 时,对任意 .mq.md 应能分阶段看见中间结果,避免黑盒;正式 run 默认安静,仅输出程序 print 的内容。
2. CLI 开关
marqdo run FILE [dumps...]
marqdo dump FILE --stage lines|tokens|ast|sema|all
| 标志 | 阶段 | 输出内容 |
|---|---|---|
--dump-lines |
行分类 | 每行:LINE kind=Comment|Code|Blank + 原文预览 |
--dump-tokens |
词法 | Token 流:type lexeme line:col |
--dump-ast |
语法 | S 表达式或缩进树(模块/函数/语句) |
--dump-sema |
语义 | 作用域、导入图、提升后的符号表 |
--trace-eval |
求值 | JSON 行(stderr):语句级事件,含 path / span(line:col) |
--dump-bytecode |
字节码 | 反汇编 Program(指令旁带 @line:col;见 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 随阶段增长自动变完整 |