Files
marqdo/doc/design/pipeline-debug.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

2.7 KiB
Executable File
Raw Blame History

解释器流水线可视调试

状态 已定(开发期强制友好)
日期 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 行分类 每行: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)
--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 随阶段增长自动变完整