OP 0020: 诊断消息质量(效仿 Python 的错误消息改进)¶
摘要¶
把「能用但含混」的诊断消息改进为「说出类别、指对位置」的消息。本轮覆盖
四个高频类别:词法错误(未终止字符串、非法字符)、定界符错误
(未闭合/多余的括号)、花括号字面量习惯提示(Python 式 {1, 2} 的
定向 did-you-mean)与Python 习惯建议(None/True/self、&&/||/!、
{} 空块、行首 //、i++、lambda、条件内 =)。方法论与措辞对照
Python 3.10+ 的错误消息改进。
动机¶
改进前的真实输出(oort -c):
$ oort -c "'1"
line 1:0 token recognition error at: ''1' # ANTLR 原文透出,且退出码 0
$ oort -c "{: '1':"
<string>:1:8: OortSyntaxError: Invalid syntax # 位置与 caret 都不知所云
{: '1':
^^^^^
问题分三层:
- 词法错误未接入诊断管线:ANTLR Lexer 挂的是默认 ConsoleErrorListener, 原文直接进 stderr,且出错字符被跳过后程序可能以退出码 0「成功」;
- 消息不分类:
Invalid token/Invalid syntax是 V8Invalid or unexpected token式的万能句,用户无从下手; - 位置指错地方:括号未闭合时,ANTLR 在耗尽输入处报错,离真正的 错误(开括号)很远。
参照系(各语言对同一类错误的措辞):
| 语言 | 未终止字符串 | 非法字符 | 未闭合括号 |
|---|---|---|---|
| Python 3.10+ | unterminated string literal |
invalid character '“' (U+201C) |
'{' was never closed |
| javac | unclosed string literal |
illegal character: '#' |
reached end of file while parsing |
| Go | newline in string |
— | unexpected $end |
| SpiderMonkey | unterminated string literal |
— | — |
| V8(反例) | Invalid or unexpected token |
同左 | 同左 |
要点:好的消息命名类别并带上出错文本(含码点,对从网页/字处理
软件粘贴的全角引号、不可见字符至关重要);Python 3.10 的 PEG 解析器
错误消息重写(3.8 的 EOL while scanning string literal → 3.10 的
unterminated string literal)证明了这不是玄学,而是可以逐类积累的
工程工作。本提案采取同样的路径。
设计¶
原则¶
- 说类别,不说行话:消息命名失败种类(unterminated / unmatched / invalid character),不暴露实现细节(token、rule、ANTLR 术语);
- 指对位置:错误指向根因处(开括号、出错字符),不是解析器 放弃处;caret 覆盖最小有用跨度;
- 保持单条:定界符错误引发的级联解析错误被替换为一条根因诊断, 不重复报噪音(Python 同此行为);
- 分类信号来自已有数据:不新增词法/语法分析遍数——词法分类用 ANTLR msg 中「失败规则尝试匹配的文本」,定界符用 token 后处理层 既有的括号栈(OP 0008 为 REPL 完整性检查引入)。
词法错误分类¶
Lexer 挂 OortErrorListener(与 parser 同一管线)。词法通知没有
offending token,位置由行/列构造,caret 指向出错字符。消息按尝试匹配
文本分类:
| 输入 | 消息 |
|---|---|
'1 / "abc / r'x |
Unterminated string literal |
"""abc |
Unterminated triple-quoted string literal |
` / \ |
Invalid character '`' (U+0060) |
| 兜底(msg 不可解析) | Invalid token |
分类依据文法可穷尽:EscapeSequence 在词法层宽松(\\ ~[\n]),
字符串类词法错误只有「未终止」;数字字面量总能回退到 DEC_INT 短匹配
(0x 的词法结果是 0 + 标识符 x,报解析错),不产生词法错误;
非引号开头的失败按构造只可能是单个非法字符。
三引号判别:ANTLR 对 """abc 的报错在第 3 个引号处(前两个引号
先匹配成空字符串),因此用错误位置之前的两个源码字符是否同为该
引号来判别,而非错误文本前缀。
定界符错误¶
process_tokens(OP 0008 的 token 后处理层)本就维护括号栈供 REPL
判断输入完整性;现在把栈内容与「栈空时遇到的闭括号」记入
TokenizedInput.unclosed_openers / unmatched_closers。
Compiler.build_ast 在解析产生错误且存在定界符问题时,回撤本次
解析新增的诊断,替换为一条指向定界符本身的消息:
| 输入 | 消息 | 位置 |
|---|---|---|
{: '1': |
'{:' was never closed |
开括号处(1:1) |
if true { print(1) |
'{' was never closed |
开括号处(1:9) |
] |
Unmatched ']' |
闭括号处 |
措辞与位置策略均对齐 Python('{' was never closed 指向开括号、
unmatched ']' 指向闭括号)。REPL 不受影响:未闭合括号仍判定为
「输入未完成」继续读行;仅 EOF flush 路径会给出该诊断。
花括号字面量提示(轻量 did-you-mean)¶
Python 用户的常见习惯错误是写 {1, 2} / {1: 2}——在 Oort 里 {} 是
代码块,解析失败后报的是 ANTLR 噪音
(mismatched input '}' expecting {AUG_ASSIGN, '='})。对齐 Python 3.10+
"did you mean" 的思路,解析失败后扫描 token 流:单行 { 块体内、
括号嵌套深度为 0 处出现的首个分隔符(: → Dict、, → Set)触发一条
OortSyntaxWarning 建议:
val _ = {1, 2}
<string>:1:9: OortSyntaxWarning: Did you mean a Set literal '{. item, ... .}'? '{' opens a code block.
守卫:块体首 token 为语句关键字(if/def/var 等,避免误报
{ if a: 1 })、分隔符嵌套在 ()/[] 内({ g(1, 2) } 正常解析且
不提示)、每次输入至多一条提示。
Python 习惯建议¶
对运行期与解析期的另几类 Python 习惯,追加「did you mean」建议:
| 输入 | 诊断 |
|---|---|
print(None) / True / self |
Name 'None' is not defined (did you mean 'null'?)(名称表:None/True/False/self → null/true/false/this;解释器与 VM 共享) |
1 && 2 / !true |
does not support operator '&&' (did you mean 'and'?)(运算符表:&&/||/! → and/or/not;VM 运算符分发委托解释器,天然共享) |
val d = {} |
Did you mean an empty Dict '{:}' or Set '{.}'?——{} 是空代码块,程序合法且值为 null,属静默语义陷阱,故以 SyntaxWarning 提示且退出码仍为 0;仅表达式位置(前一 token 为 =/(/,/return)触发,空类体/空函数体不误报 |
行首 // |
Did you mean a comment? …——// 是整除运算符,// comment 会解析成奇怪的表达式后在运行期报无关的 NameError |
i++ |
Oort has no postfix '++'; use += 1.——措辞限定后缀:二元 operator "++" 可被用户定义,但 Oort 没有任何后缀运算符;提示仅在解析失败时触发,合法的中缀 a ++ b 不受影响 |
lambda(x): x |
'lambda' is not a keyword; Oort lambdas use 'do' |
if x = 1 { } |
Assignment is a statement; did you mean '==' in the condition? |
Pratt 阶段的错误(如缺操作数)在 AST 构建期才进入错误处理器,因此
失败门控的提示在解析后与构建后各跑一次(发出即短路);elif 经查是
既有关键字(if/elif/else 链),无需提示。
输出通道¶
rich 控制台按宽度折行会把消息短语拆开(也使 grep/管道处理困难)。
新增 --plain 选项:诊断输出不走 rich,每条记录一行,用于管道与
脚本场景。
边界与限制¶
本轮不做(记录为后续工作):
- ANTLR
extraneous input … expecting {大集合}的精简(如val x 1、x =;需要 curated 规则或迁移到带恢复策略的解析层); - 拼写错误的编辑距离 did-you-mean(固定 Python 拼写对照表已完成,
esle这类任意拼写候选仍属后续); - 多错误恢复(当前首个解析错误后由 ANTLR 默认恢复策略继续,质量不一);
- REPL 控制台对长消息的折行美化(rich 按宽度折行会把短语拆开;
--plain是当前的出口)。
正交性检查¶
- 与类型系统:无关(纯前端诊断);
- 与类/对象:无关;
- 与函数/闭包:无关;
- 与模块:
compile_unit_details(模块导入编译)同样传入 tokenized, 模块文件享受相同诊断; - 与方言:诊断发生在词法/解析层,先于方言门控,两方言一致;
- 与 REPL:括号栈语义不变(
incomplete判定不动),仅 flush 路径新增 诊断。
实现与测试¶
diagnostics/error_listener.py:词法分类(尝试文本 + 源码前缀);parser/token_processor.py:unclosed_openers/unmatched_closers;diagnostics/error_handler.py:retract_since(回撤级联条目);driver/compiler.py:build_ast(tokenized=...)与_report_delimiter_diagnostic;REPL flush 传入 tokenized。- 测试:CLI 参数化语料(词法 5 例 + 定界符 8 例 + 花括号提示 3 例与
防误报守卫 + 习惯建议 10 例与防误报,断言消息与位置)、token 后处理
定界符追踪 8 例、
--plain子进程用例、REPL EOF 子进程用例更新。
后续工作¶
- 解析错误 curated 消息:
missing ... before ...、expected ':'等 (Python 3.10 PEG 的做法是给每个失败点写人话模板); - 语义/名称阶段引入 did-you-mean(编辑距离 ≤ 2 的候选);
docs/spec/06-conformance.md增补诊断消息清单,作为回归基线。
参考¶
- Python 3.10 错误消息改进(PEG parser rewrite)与 invalid character 诊断说明; 版本间 SyntaxError 演进;
- javac
unclosed string literal/illegal character; - Go
newline in string;SpiderMonkeyunterminated string literal; V8Invalid or unexpected token(反面参照)。