OP 0008: 词法后处理层与 REPL 重构¶
摘要¶
把 Oort.g4 中与 Python 绑定的词法动作(括号计数、换行抑制、特殊 token 计数)
移出文法,改为词法器之后、解析器之前的 token 后处理层;同时重构 REPL 为
独立的 ReplSession 状态机,不再依赖 ANTLR 的 lexer/parser 内部字段。
目标是让文法本身与宿主语言无关、让换行规则可单元测试,并让 REPL 的续行、 EOF、错误恢复行为可预测。
动机¶
1. 文法依赖 Python 动作¶
当前 grammars/Oort.g4 在 lexer 中嵌入 Python:
@lexer::members保存parenthesisCount、bracketCount、dictLiteralCount、setLiteralCount与brackets栈;LPA/RPA/LBK/RBK/AT_LBK/LBC/RBC与字典/集合字面量 token 都带{...}动作;IGNORED_NEWLINE用self.brackets谓词决定是否丢弃换行。
后果:
- 文法不能直接生成其他 ANTLR target,阻碍未来的 Rust/其他语言实现;
- 动作在词法阶段执行宿主代码,未匹配的闭括号会直接崩溃:
这是语法错误,应该由诊断系统报告,而不是 Python traceback; - 括号状态是 REPL 续行判断的唯一来源,导致 REPL 依赖 lexer 内部实现。
2. REPL 依赖 ANTLR 内部字段¶
driver/repl.py 目前:
- 复用同一个 lexer/parser,通过修改
lexer.inputStream、lexer.line来喂新行; - 调用
token_stream.fill()后手动tokens.pop()、重置fetchedEOF; - 用
lexer.brackets判断是否需要续行; - 没有处理 EOFError:管道输入或 Ctrl-D 会以 traceback 结束;
- Ctrl-C 的语义固定为退出,无法“取消当前多行输入”。
这些细节与 ANTLR 运行时版本耦合,难以测试,也难以在未来后端复用。
设计¶
1. 文法纯净¶
Oort.g4 中删除所有宿主语言动作与谓词:
- 移除
@lexer::members; - 移除所有 token 上的
{...}动作; - 删除
IGNORED_NEWLINE,NEWLINE始终产生; LINE_ESCAPE(行尾\续行)可以保留为纯文法规则。
删除后,词法器只负责把源码切成 token,不再维护语义状态。
2. 词法后处理层¶
新增 parser/token_processor.py(名称可调整),对 token 序列做纯函数处理:
- 维护一个括号栈,打开 token:
LPA、LBK、AT_LBK、LDICT_LITERAL、LSET_LITERAL、LBC;关闭 token:RPA、RBK、RDICT_LITERAL、RSET_LITERAL、RBC。 - 与当前规则保持一致:只有当栈非空且栈顶不是
LBC(代码块)时,丢弃NEWLINE; 代码块内的换行仍作为语句分隔符。 - 未匹配的关闭 token 不做栈操作,原样交给 parser,由错误监听器报告。
- 暴露
bracket_depth/is_incomplete供 REPL 使用。 - 输入结束后若括号栈非空,或最后一行以未转义的
\结束,则视为“输入未完成”。
实现上可以预先把 token 收集为列表,再由 ListTokenSource 构造
CommonTokenStream;正常文件与 REPL 共用同一条管线。
3. REPL 会话状态机¶
把 run_repl 拆成两层:
ReplSession:纯逻辑,不依赖 rich/Console。- 累积源码缓冲区与
InputInfo; - 调用词法后处理判断是否完整;
- 完整时解析整个缓冲区、语义分析、在当前解释器中求值;
- 持有持久的全局环境/解释器与语句计数;
- 返回
CONTINUE/EVALUATED/ERROR/EXIT等动作。 ConsoleIO(或ReplConsole):负责提示符、颜色、输入、结果打印; 测试时替换为FakeConsoleIO。
行为约定:
- 每次提交重新解析完整缓冲区,不修改 lexer/parser 内部状态;
- 语法错误后清空当前缓冲区并保留解释器环境,REPL 继续运行;
- EOF(Ctrl-D、Windows Ctrl-Z + Enter,或管道结束)正常退出并返回 0;
- Ctrl-C 在输入阶段取消当前输入,在执行阶段中断当前语句,均不退出;
exit/quit在空闲提示符下显式退出;- 非 TTY(管道/重定向)下仍可工作;是否隐藏提示符另行决定,但必须有 subprocess 冒烟测试覆盖。
4. 与方言的关系¶
词法后处理与 REPL 都属于共享骨架,不携带方言策略:
#lang指令的解析放在词法后处理之前的入口层(注意#也是注释起始符, 需要单独处理首行);- 运算符表、特性门控仍由方言配置决定;
- REPL 的求值器与语义分析器由方言提供,会话本身不感知具体方言。
测试策略¶
REPL 建议按层次测试,而不是只靠手动输入:
| 层级 | 内容 | 位置 |
|---|---|---|
| 单元 | 括号栈/换行过滤:()、[]、{}、{: :}、{. .}、嵌套、字符串/注释中的括号、未匹配闭括号、行尾 \ |
tests/unit/frontend/ |
| 单元 | ReplSession 完整性判断与状态迁移,不依赖 Console |
tests/unit/ 或 tests/integration/ |
| 集成 | 脚本化 transcript:多行、错误恢复、变量持久化、空行、提示符/结果格式 | tests/integration/test_repl.py |
| 子进程 | 用管道 stdin 启动真实 CLI,检查退出码、stdout/stderr、EOF、版本 banner | tests/integration/ |
| PTY(可选) | Ctrl-C/Ctrl-D、行编辑、历史、粘贴;跨平台成本高,可用标记在本地/夜间运行 | 可选 |
| 性质/模糊 | 合法程序的所有前缀都不应崩溃或挂起;完整判断应单调 | 可选 |
| 手动冒烟 | 终端特有的显示、颜色、快捷键与交互体验 | private/repl-smoke.md |
原则:自动化测试放 tests/,private/ 只放无法稳定自动化的终端人工检查清单;
冒烟测试不应成为唯一的 REPL 保障。
正交性检查¶
- 与方言:后处理层与 REPL 是共享骨架;方言只提供语义分析器与求值器。
- 与运算符:换行/括号处理不改变 Pratt 表或运算符语义。
- 与模块:
#lang指令解析在入口层,可复用同一 token 管线。 - 与后端:token 后处理与 REPL 不依赖 AST 解释器;字节码/编译模式可复用同一会话接口。
替代方案¶
- 保留 lexer 内嵌 Python 动作:实现最简单,但文法不可移植、错误输入会导致 Python traceback,REPL 继续依赖内部字段。放弃。
- REPL 自己按字符统计括号:会把字符串/注释中的括号算进去,且与文法规则 重复实现。放弃。
- 为 REPL 维护独立的分词器:造成两套词法规则,容易漂移。放弃。
- 增量解析器:长期可能有价值,但当前规模不需要;先做整缓冲区重解析。
迁移计划¶
- 在文法中删除 lexer 动作与
IGNORED_NEWLINE,让NEWLINE始终产生。 - 实现 token 后处理层,并让
Compiler与 REPL 共用。 - 添加单元测试:括号/换行过滤、未匹配闭括号、字符串与注释中的括号。
- 重构 REPL 为
ReplSession+ConsoleIO,处理 EOFError、Ctrl-C 语义与 整缓冲区重解析。 - 添加 transcript、子进程与(可选)PTY 测试;建立
private/repl-smoke.md。 - 更新
docs/implementation/02-parser.md与测试文档。
已决问题(2026-11-20)¶
- Ctrl-C:输入阶段取消当前行与待提交的多行缓冲区;执行阶段中断当前语句
(
KeyboardInterrupt)并回到提示符;两种情况下环境保留已发生的副作用。 与 CPython/IPython/IRB/GHCi/Julia 一致,不采用 Node 的“双击 Ctrl-C 退出”。 - 退出键:Unix 为 Ctrl-D;Windows 控制台为 Ctrl-Z 后按 Enter(Python
input()的 EOF 约定,PowerShell 同样适用)。 - 显式退出:整行恰为
exit或quit时由 REPL 层拦截(仅在没有待提交 多行输入时),不进入语言语义;与 Python/IPython/Ruby/Bash 的显式退出命令 对齐,也为 Windows 用户提供可发现的退出方式。 - 非 TTY:隐藏
In [n]/Out[n]提示符,但仍正常求值;管道 EOF 正常 退出并返回 0。 - 历史/行编辑:本版不做,依赖终端自身;后续如需再引入
prompt_toolkit。 #lang消歧:继续在入口层按首行预处理,词法器仍把它当注释;后处理层 不负责指令剥离或位置重映射。- 未匹配闭括号:token 后处理不做栈操作,原样交给解析器报语法错误。
未解决问题¶
- 是否支持增量解析(当前每次提交重解析整个缓冲区)。
- 非 TTY 下是否需要完全静默 banner(当前保留 banner,便于日志识别)。
#lang与首行 BOM/空行的更细边界(现有入口层测试已覆盖主要情形)。