tree-sitter 测试语法夹具test_grammars指南特性演示与回归测试【免费下载链接】tree-sitterAn incremental parsing system for programming tools项目地址: https://gitcode.com/gh_mirrors/tr/tree-sitter导读在 tree-sitter 仓库的 test/fixtures/test_grammars 目录下存放着一批小规模、单点聚焦的测试语法test grammars。它们以最小可复现的形态逐一演示 grammar DSL 的某项具体特性或针对某些特定回归缺陷进行回归验证——这就是目录中 readme.md 所定义的职责这些小语法用于演示特定特性或测试特定回归问题。其中一部分预期在编译时失败并输出指定的错误信息另一部分则预期生成的解析器能产生特定的语法树。本文将以此说明为核心骨架结合仓库中的实际夹具文件与测试加载源码系统讲解这些夹具的组织方式、两种验证形态expected_error.txt与corpus.txt、常见语法特性示例以及它们在 CLI 测试链路中的实际作用帮助读者理解如何为自己的语言解析器编写同样形态的回归测试。一、夹具的两种验证形态根据 readme.md 的表述全部 60 余个夹具目录可分为两类形态判定依据配套文件典型目录编译失败型生成解析器阶段必须报出指定错误grammar.jsexpected_error.txtassociativity_missing、epsilon_rules、conflict_in_repeat_rule等解析结果型解析器必须产出指定语法树grammar.jscorpus.txt部分含scanner.cbasic_cst、inline_rules、external_tokens等这两种形态在测试套件中的执行路径不同下文分别以具体夹具展开。二、编译失败型夹具用 expected_error.txt 锁定错误信息2.1 关联性缺失associativity_missingassociativity_missing/grammar.js 定义了一个左递归的二元运算语法但没有声明结合性export default grammar({ name: associativity_missing, rules: { expression: $ choice($.math_operation, $.identifier), math_operation: $ seq( $.expression, , $.expression, ), identifier: $ /[a-z]/, } });由于expression与math_operation相互递归且没有prec.left/prec.right修饰生成解析表时会出现 shift/reduce 冲突。此时编译必须失败且错误文本须与 expected_error.txt 完全一致Unresolved conflict for symbol sequence: expression expression • … Possible interpretations: 1: (math_operation expression expression) • … 2: expression (math_operation expression • expression) Possible resolutions: 1: Specify a left or right associativity in math_operation 2: Add a conflict for these rules: math_operation这段错误信息本身就是绝佳的使用指引它明确提示两种解决手段——在规则上声明prec.left/prec.right结合性或者通过conflicts字段显式声明冲突。对照同目录下的成功夹具可看到正确写法例如 external_tokens/grammar.js 中sum: $ prec.left(seq($.expression, , $.expression))。2.2 空串匹配规则epsilon_rulesepsilon_rules/expected_error.txt 锁定的是另一条硬性约束——语法规则不允许匹配空串The rule rule_2 matches the empty string. Tree-sitter does not support syntactic rules that match the empty string unless they are used only as the grammars start rule.这条约束对初学者极其常见误写optional、repeat或纯可选分支时容易制造出空串规则。该夹具在生成阶段就拦截此类错误避免在运行时产生歧义。仓库中另有epsilon_external_tokens、epsilon_external_extra_tokens两个夹具说明外部扫描器 token 允许空串的例外场景可作为对比参考。2.3 其他编译失败型示例conflict_in_repeat_rulerepeat 规则内部的冲突检测conflict_in_repeat_rule_after_external_token外部 token 之后的 repeat 规则冲突conflicting_precedence优先级声明相互矛盾eof_misplaced、eof_repeat_via_nullable_ruleEOF 与可空规则相关约束invisible_start_rule、start_rule_is_blank、start_rule_is_tokenstart rule 形态限制terminal_supertypesupertype 规则不能是终结符indirect_recursion_in_transitions间接递归转换检测precedence_on_single_child_missing单子节点上的缺失优先级。这些夹具共同构成了一张“语法校验错误手册”开发者在编写 grammar.js 遇到同名报错时可以直接到对应目录查看最小复现与错误文本。三、解析结果型夹具corpus.txt 与 CST 断言3.1 基本 CSTbasic_cstbasic_cst/grammar.js 是理解 corpus 断言格式的最小样例export default grammar({ name: basic_cst, rules: { document: $ $.assignment, assignment: $ seq( field(name, $.identifier), , field(value, $.number), ), identifier: _ /[a-z]/, number: _ /[0-9]/, }, });对应的 corpus.txt 展示了两种断言语法。第一部分是带:cst指令的紧凑 CST 渲染 Basic CST rendering :cst answer 42 --- 0:0 - 0:11 document 0:0 - 0:11 assignment 0:0 - 0:6 name: identifier answer 0:7 - 0:8 0:9 - 0:11 value: number 42可以看到name: identifier、value: number正是field()声明的具名字段匿名 token以带引号形式呈现0:0 - 0:11表示行:列的字节区间。这种 CST 渲染格式由 CLI 的parse --cst能力支撑便于人工核对字段与区间。3.2 S 表达式断言eof_basiceof_basic/corpus.txt 演示了 tree-sitter 测试的标准 S 表达式断言格式同时验证 EOF 处理 trailing newline text text --- (source_file (line) (line))每个用例块由标题、输入---之前与期望语法树---之后组成。该夹具特意覆盖三种边界带尾换行、无尾换行、单行无换行确保解析器在文件末尾不产生多余或缺失节点。3.3 内联规则inline_rulesinline_rules/grammar.js 演示inline字段与优先级组合的常见写法export default grammar({ name: inline_rules, extras: $ [/\s/], inline: $ [$.expression], rules: { program: $ repeat1($.statement), statement: $ seq($.expression, ;), expression: $ choice($.sum, $.product, $.number, $.parenthesized_expression), parenthesized_expression: $ seq((, $.expression, )), sum: $ prec.left(seq($.expression, , $.expression)), product: $ prec.left(2, seq($.expression, *, $.expression)), number: $ /\d/, } });要点inline将expression内联进调用点以减少栈深度与节点开销prec.left声明左结合prec.left(2, ...)通过数字提高优先级使乘法先于加法结合。配合extras空白声明这是编写表达式语言的经典骨架。四、外部扫描器夹具external_tokens 与 scanner.c部分夹具需要处理正则无法表达的词法如括号嵌套计数此时引入外部扫描器。测试加载链路会自动识别夹具目录中的scanner.c并参与编译见下文源码路径。external_tokens/grammar.js 模拟了类似 Ruby 百分号字符串的嵌套括号计数export default grammar({ name: external_tokens, externals: $ [ $._percent_string, $._percent_string_start, $._percent_string_end, ], extras: $ [/\s/], rules: { expression: $ choice($.string, $.sum, $.identifier), sum: $ prec.left(seq($.expression, , $.expression)), string: $ choice($._percent_string, seq( $._percent_string_start, $.expression, $._percent_string_end, )), identifier: $ /[a-z]/ } });scanner.c 中Scanner结构体保存开闭分隔符与嵌套深度open_delimiter/close_delimiter/depth在scan函数内通过TSLexer的lookahead、advance、log、result_symbol接口逐字符扫描实现%(...)与#{...}插值等上下文相关词法。create/destroy/serialize/deserialize四个生命周期函数保证扫描器状态在增量重解析中可保存恢复。同类的扫描器夹具还有depends_on_column、uses_current_column、get_col_eof、get_col_should_hang_not_crash列号相关、utf16_surrogate_oobUTF-16 越界防护、wasm_realloc_clobber_region与wasm_realloc_overflow_heapWasm 内存重分配回归等覆盖了外部扫描器易踩的边界场景。五、测试加载链路夹具如何被编译与断言夹具并不仅是被动陈列的样例它们被 CLI 测试套件实际加载执行。核心路径在 crates/cli/src/tests/helpers/fixtures.rsget_test_fixture_language(name)通过load_grammar_file读取test_grammars/name/grammar.js再调用generate_parser生成解析器代码fixtures.rs若目录中存在scanner.c测试代码会将其复制到临时src_dir与parser.c一起编译fixtures.rs编译出的解析器经Loader加载为Language交由corpus_test、parser_test等测试模块执行 corpus 断言对于expected_error.txt型夹具测试在生成阶段捕获错误并逐字比对错误文本。这也解释了为什么每个夹具目录的命名即测试用例名测试代码按目录名动态查找 grammar.js、corpus.txt、scanner.c、expected_error.txt形成“一个目录 一个回归场景”的约定。目录结构本身test/fixtures/test_grammars/由 dirs.rs 中的FIXTURES_DIR常量定位。六、夹具速查按语法特性归类为方便开发者在编写自己的 grammar.js 时快速找到可参考的样例下面把主要夹具按演示特性归类完整清单以 test/fixtures/test_grammars 目录为准别名aliasingaliased_rules、aliased_token_rules、aliased_unit_reductions、aliased_inlined_rules、aliases_in_root、inlined_aliased_rules、named_rule_aliased_as_anonymous、named_precedences结合性与优先级associativity_left、associativity_right、associativity_left_with_lower_precedence_shift、associativity_right_with_lower_precedence_shift、duplicate_reduction_precedence、dynamic_precedence、precedence_on_token、precedence_on_subsequence、precedence_on_single_child_negative、precedence_on_single_child_positive外部扫描器external_tokens、external_extra_tokens、external_and_internal_tokens、external_and_internal_anonymous_tokens、external_lookahead_eof_boundary、epsilon_external_tokens、epsilon_external_extra_tokens、inverted_external_tokenEOF 与空串eof_basic、eof_dropped_branch、eof_duplicate_reduction、eof_repeat_terminated、next_sibling_from_zwt、epsilon_rulesinline / repeat / extrainline_rules、nested_inlined_rules、extra_non_terminals、extra_non_terminals_with_shared_rules、unused_rules词法与 unicodeanonymous_tokens_with_escaped_chars、unicode_classes、anonymous_error辅助元信息部分目录还附带readme.md/readme.txt说明背景例如 unused_rules/readme.md 解释了“未使用 token 必须从 token 计数中省略”的生成器约束dynamic_precedence 目录同样带说明文档值得逐篇阅读。七、结语如何借鉴这套夹具体系从 readme.md 的两句总纲出发这套夹具体系给出了三条可直接复用的工程实践最小化复现每个特性/回归一个独立小语法目录目录名即语义杜绝大而全的样例双轨验证预期失败的场景用expected_error.txt锁定错误文本防止错误信息漂移预期成功的场景用corpus.txt锁定语法树防止解析行为漂移两者互为补充可自动执行通过get_test_fixture_language等加载函数与目录命名约定夹具天然接入cargo test链路无需额外注册。无论你是正在编写新语言的 grammar.js还是为已有语法补充回归测试都可以参照 test/fixtures/test_grammars 的组织方式先为你的特性建立一个同名小目录再分别写出“应当失败”的错误文本与“应当成功”的 corpus 断言最后让测试套件替你守住这两个边界。【免费下载链接】tree-sitterAn incremental parsing system for programming tools项目地址: https://gitcode.com/gh_mirrors/tr/tree-sitter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考