tree-sitter 负优先级（Negative Precedence）解析无括号函数调用与块的 shift/reduce 冲突

• 开发工具

导读：本篇文章以 tree-sitter 仓库中precedence_on_single_child_negative测试语法为切入点，深入讲解如何通过给规则赋予负数值优先级（prec.right(-1, ...)）来解决无括号函数调用（如 Ruby 风格foo bar { baz }）中"归约参数表达式"与"移入块作为调用体"之间的 shift/reduce 冲突。读完本文，你将理解 tree-sitter 的数值优先级如何决定移入（shift）与归约（reduce）的取舍，掌握正/负优先级两种解决方案的差异与适用场景。

1. 问题背景：单子节点上的优先级缺失

在 tree-sitter 的测试语法库中，precedence_on_single_child_negative是用于验证解析表生成器优先级消解机制的一组夹具之一。它与precedence_on_single_child_missing、precedence_on_single_child_positive两个兄弟语法共同组成了一个"同一冲突、三种解法"的对照实验。

冲突源头定义在 precedence_on_single_child_missing/grammar.js：

export default grammar({ name: 'precedence_on_single_child_missing', rules: { expression: $ => choice($.function_call, $.identifier), function_call: $ => prec.right(choice( seq($.identifier, $.expression), seq($.identifier, $.block), seq($.identifier, $.expression, $.block), )), block: $ => seq('{', $.expression, '}'), identifier: _ => /[a-zA-Z]+/, }, });

这是一门类似 Ruby 语法风格的语言：函数调用不需要括号，并且可以带可选代码块。给定输入：

foo bar { baz }

在bar与{之间会产生一个shift/reduce 冲突（见 precedence_on_single_child_missing/readme.md）：

foo bar { baz } ^

解析器面临两种合法动作：

1. reduce(expression, 1)—— 把bar归约成一个expression，作为传递给foo函数的参数；
2. shift—— 把bar视为一个函数，把{ baz }作为代码块移入，构成一次新的function_call。

值得注意的是，这里的function_call规则虽然包裹在prec.right(...)中，但没有给出任何数值。按照 tree-sitter 的语义，所有规则的默认优先级为0（见 2-the-grammar-dsl.md 对prec(number, rule)的说明），因此移入动作与归约动作的优先级持平，冲突无法通过数值消解——这就是 readme 标题中 "missing"（缺失）的含义。

2. 负优先级方案：偏好归约参数

precedence_on_single_child_negative这一夹具的解决思路是：给function_call赋予一个负数优先级。其 readme（即本文关联文档）明确指出：

This grammar resolves the conflict shown in theprecedence_on_single_child_missinggrammar by givingfunction_calla negative precedence. This causes reducing thebarvariable to an expression to be preferred over shifting the{token as part offunction_call.

对应的完整语法见 precedence_on_single_child_negative/grammar.js：

export default grammar({ name: 'precedence_on_single_child_negative', rules: { expression: $ => choice($.function_call, $.identifier), function_call: $ => prec.right(-1, choice( seq($.identifier, $.expression), seq($.identifier, $.block), seq($.identifier, $.expression, $.block), )), block: $ => seq('{', $.expression, '}'), identifier: _ => /[a-zA-Z]+/, }, });

与 missing 版本唯一的不同，就是把prec.right(choice(...))改为prec.right(-1, choice(...))。这个-1意味着function_call这条规则的优先级低于默认的 0 级，也低于归约动作默认携带的 0 级优先级，于是解析器生成阶段会移除移入（shift）动作、保留归约（reduce）动作，即选择"把bar当作foo的参数"这一解读。

最终，foo bar { baz }的解析结果由 corpus 测试断言（见 precedence_on_single_child_negative/corpus.txt）：

(expression (function_call (identifier) (expression (identifier)) (block (expression (identifier)))))

解析树清楚地表明：foo是函数，bar是作为expression传入的实参，{ baz }是附加在调用之后的块——即"归约优先"的选择结果。

3. 对照实验：正优先级方案

为了说明"负数优先级"这一选择的含义，仓库同时提供了正优先级版本 precedence_on_single_child_positive/grammar.js：

export default grammar({ name: 'precedence_on_single_child_positive', rules: { expression: $ => choice($.function_call, $.identifier), function_call: $ => prec.right(1, choice( seq($.identifier, $.expression), seq($.identifier, $.block), seq($.identifier, $.expression, $.block), )), block: $ => seq('{', $.expression, '}'), identifier: _ => /[a-zA-Z]+/, }, });

其 readme 的解释（见 precedence_on_single_child_positive/readme.md）正好是负版本的镜像：

This grammar resolves the conflict ... by givingfunction_calla positive precedence. This causes shifting the{token as part offunction_callto be preferred over reducing thebarvariable to an expression.

对应的 corpus 断言（见 precedence_on_single_child_positive/corpus.txt）则断言了完全相反的树形结构：

(expression (function_call (identifier) (expression (function_call (identifier) (block (expression (identifier)))))))

在这里，bar被解析为被{ baz }调用的函数，{ baz }作为bar的调用块移入——即"移入优先"。

两个夹具放在一起，恰好构成一份完整的对照实验：

注：positive 版本的语法中存在一处细节差异——其identifier正则为/[a-zA-X]+/（注意X大写截断），这应当属于测试夹具的历史遗留拼写，不影响本文对优先级语义的讨论。

4. 原理纵深：优先级如何在解析表生成期消解冲突

为什么一个-1就能让解析器稳定地选择归约？这需要回到 tree-sitter 的解析表构建器——build_parse_table.rs 中处理 LR(1) 冲突的核心逻辑。

在add_reduce_actions（约 L840-L924）中，当某个状态下的同一终结符（这里是{）同时触发 shift 与 reduce 动作时，生成器会按以下次序裁决：

1. 比较优先级：收集所有候选移入动作携带的优先级（shift_precedence，见 L803-L825），与归约动作的优先级逐一比较（compare_precedence）；
2. 移入更高 → 保留移入：若移入动作的优先级严格更高（shift_is_more && !shift_is_less），则调用keep_last()保留移入动作、删除归约动作（L874-L876）；
3. 归约更高 → 保留归约：若归约动作的优先级更高（shift_is_less && !shift_is_more），则调用pop()移除移入动作（L878-L900），此时需同时考虑归约动作的右结合性豁免（见 L886-L896）；
4. 优先级相同 → 参考结合性：若两者持平，则依据归约动作的左结合/右结合属性取舍（L902-L923）。

回到本案例：function_call被标记为prec.right(-1, ...)，其数值优先级为-1；而"把bar归约为expression"这个归约动作的优先级是默认的0。由于-1 < 0，归约优先级更高，走第 3 条分支——移入{的动作被移除，归约胜出。这正是 readme 所述"reducing thebarvariable to an expression [is] preferred"的底层实现依据。反之，positive 版本用prec.right(1, ...)让移入动作优先级（1）高于归约动作（0），走第 2 条分支，移入胜出。

另外，prec.right中显式给出的数值与prec(...)底层是同一套机制：在 rules.rs 中，prec、prec.left、prec.right都通过metadata_with写入规则的precedence字段，区别仅在于prec.left/prec.right会额外记录Associativity::Left/Right。也就是说，prec.right(-1, rule)等价于"数值优先级 -1 + 右结合性标记"，二者在冲突消解中是两个相互独立的维度：数值决定归约/移入的胜负，结合性只在数值持平时起作用。

5. 实战要点与适用场景

综合上述分析，在使用prec/prec.right等函数时，可以总结出以下实操要点：

1. 默认优先级是 0：不带数值的prec(rule)、prec.right(rule)与不带prec的规则优先级持平，无法解决"优先级相等"型的冲突；
2. 负数值 ≠ 非法：tree-sitter 的优先级是开放区间的整数（从 rules.rs 的实现看，precedence直接保存传入值），-1、-2等负数完全合法，且语义明确——低于所有默认 0 级动作；
3. 负数优先级的典型用途：当某条规则"希望让位于"其他更常规的解读时使用。例如本例中，只有当bar无法被归约成实参时，才把bar { baz }解读为带块的调用，即"函数调用"是"参数序列"的次选解读；
4. 与正优先级对称：正优先级让规则成为"首选"解读。选择正还是负，取决于哪种解读才是语法设计者预期的默认行为——本夹具用两个对称的 corpus 断言把两种选择的结果固化成了可回归的测试；
5. 测试验证方式：三个夹具的corpus.txt均由 tree-sitter CLI 的测试系统驱动（corpus 测试位于 crates/cli/src/test.rs，其渲染解析树的输出格式见 L1188 附近）。修改语法后运行tree-sitter generate && tree-sitter test即可验证冲突是否按预期消解。

若需要更细粒度的优先级控制，还可以使用命名优先级（grammar 的precedences字段）或运行时优先级（prec.dynamic），前者将优先级限定在命名集合内比较，后者在 GLR 算法探索多种可行解析时按动态优先级总分取舍（详见 2-the-grammar-dsl.md 与 2-the-grammar-dsl.md）。

6. 小结

precedence_on_single_child_negative虽然只是一个几行代码的测试夹具，却精准地示范了 tree-sitter 文法设计中的一个关键技巧：通过负数优先级把某个语法解读声明为"次选"，从而在解析表生成阶段就把 shift/reduce 冲突确定性地消解为"归约优先"。结合positive与missing两个对照版本，以及 build_parse_table.rs 中的裁决逻辑，可以完整理解"优先级数值决定移入与归约胜负"这一核心机制——这正是编写无歧义、可预测的 tree-sitter 语法（尤其是 Ruby 风格无括号调用这类语言）时所必需的知识。

• 开发工具