🌴仔细瞧瞧 Tree-Sitter

Tree-sitter 是什么？

• 解析器生成器和增量解析库： Tree-sitter 不仅是一个能够根据语言文法生成解析器的工具，更是一个在代码发生变化时能够智能地、只重新解析修改部分的库 。这种增量解析的能力使得在文本编辑器中进行实时代码分析成为可能。

• 具体的语法树（Concrete Syntax Tree, CST）： Tree-sitter 将源代码解析成一棵包含代码中每一个词法单元（token）信息的具体语法树 。与抽象语法树（Abstract Syntax Tree, AST）不同，CST 保留了源代码的所有细节，这对于需要精确理解代码结构的应用场景非常有用。

• 查询语言： Tree-sitter 提供了一种简洁的、基于 S-表达式的查询语言，允许开发者方便地在生成的语法树中查找特定的代码模式 。这种查询能力是实现语法高亮、代码导航等功能的基础。

• 语言绑定： 为了方便在不同的编程环境中使用，Tree-sitter 提供了多种语言的绑定，包括官方支持的 C#, Go, Haskell, Java, JavaScript, Kotlin, Python, Rust, Zig，以及社区贡献的更多语言绑定 。这使得开发者可以使用自己熟悉的编程语言来操作 Tree-sitter。

Tree-sitter 的语法系统

grammar.json is generated with tree-sitter generate (along with everything in src minus scanner.c)

1. 首先，开发者在 JavaScript 文件 grammar.js 中定义语言语法规则

2. 当运行 Tree-sitter CLI 命令 tree-sitter generate 时，Tree-sitter 工具会：
• 解析 grammar.js 文件
• 提取语法规则
• 将这些规则转换为标准化的 JSON 格式
• 自动生成 src/grammar.json 文件

grammar.json 的构成

1. $schema:
• 类型为 string，表示 schema 的 URL。

2. name:
• 描述语法的名称。
• 类型为 string，必须匹配正则表达式 ^[a-zA-Z_]\\w*，即以字母或下划线开头，后面可以跟字母、数字或下划线。

3. inherits:
• 可选字段，表示继承自的父语法名称。
• 类型为 string，同样需要匹配正则表达式 ^[a-zA-Z_]\\w*。

4. rules:
• 定义语法的核心规则。
• 类型为 object，其键需要匹配正则表达式 ^[a-zA-Z_]\\w*$，值引用了 #/definitions/rule。

5. extras:
• 定义额外的规则（通常是空白字符或注释）。
• 类型为 array，元素是 rule，且不允许重复。

6. precedences:
• 定义规则的优先级。
• 类型为 array，每个元素是另一个数组，包含唯一的字符串或 symbol-rule。

7. reserved:
• 定义保留的规则。
• 类型为 object，键是规则名称，值是 rule 的数组。

8. externals:
• 定义外部规则。
• 类型为 array，元素是 rule。

9. inline:
• 定义内联规则。
• 类型为 array，元素是字符串，表示规则名称。

10. conflicts:
• 定义冲突规则。
• 类型为 array，每个元素是一个字符串数组，表示可能冲突的规则名称。

11. word:
• 定义一个特殊的规则名称，用于标识“单词”。
• 类型为 string，需要匹配正则表达式 ^[a-zA-Z_]\\w*。

12. supertypes:
• 定义隐藏规则的名称，这些规则会被视为“超类型”。
• 类型为 array，元素是字符串，表示规则名称。

Rules

• 键： 这些是语法规则的名称（例如 program、statement、for_statement、expression）。这些名称会成为抽象语法树（AST）中的节点类型，当 tree-sitter 解析代码时会生成这些节点。可以将它们视为语言中不同的语法结构。

• 值（规则定义）： 这些是规则定义本身。每个值是一个 JSON 对象，用于指定如何识别和解析由键命名的语法规则。这些定义告诉 tree-sitter 在输入文本中寻找哪些模式，以识别该规则的实例。

1. blank-rule

• 含义： 表示空或空规则。它通常用于 CHOICE 规则中，使语法的某些部分可选。

• 属性： 没有特别显著的属性，仅作为占位符。

• 必须包含字段： "type": "BLANK"。

2. string-rule

• 含义： 这种规则类型表示必须在输入中精确匹配的字面字符串。

• 关键属性： "value"
• "value"： 需要精确匹配的字符串。

• 必须包含字段：
• "type": "STRING"
• "value": 字符串值。

3. pattern-rule

• 含义： 这种规则类型使用正则表达式匹配一个标记。

• 关键属性： "value"
• "value"： 正则表达式模式。

• 可选属性： "flags"
• "flags"： 正则表达式标志（例如 "i" 表示不区分大小写匹配）

• 必须包含字段：
• "type": "PATTERN"
• "value": 正则表达式。

4. symbol-rule

• 含义： 这种规则类型表示对同一 rules 字段中定义的另一个规则的引用。它用于从简单规则构建更复杂的规则。

• 关键属性： "name"
• "name"： "name" 的值是另一个规则的名称，此规则引用该名称。

• 必须包含字段：
• "type": "SYMBOL"
• "name": 符号名称。

5. seq-rule

• 含义： 这种规则类型定义了必须按顺序匹配的一组规则。可以理解为“规则 A 后接规则 B 后接规则 C”。

• 关键属性： "members"
• "members"： 一个规则定义数组（可以是 SYMBOL、STRING、PATTERN 或其他规则类型）。这个数组中的每个元素都是一个子规则的定义。SEQ 规则要求输入文本必须按照 "members" 数组中子规则定义的顺序依次匹配。

• 必须包含字段：
• "type": "SEQ"
• "members": 一个 rule 的数组。

1. 固定开头: SEQ 的第一个成员确保了每个函数内的静态变量声明必须以 static 关键字开始。

2. 变量声明序列: SEQ 的第二个成员（本身也是一个 SEQ）处理了静态变量声明的列表。它强制至少要有一个 static_variable_declaration，并且允许通过逗号分隔声明多个变量。这种嵌套的 SEQ 结构展示了如何用 SEQ 组合更复杂的序列模式。

3. 语句结束符: SEQ 的第三个成员确保了整个 static 变量声明语句以分号结束，符合 PHP 语句的语法规则。

• static $count = 0; 匹配 function_static_declaration，因为：
1. 以 static 关键字开始 (members[0])。
2. 接着是一个 static_variable_declaration ($count = 0) (members[1] 的内部 SEQ 的 members[0])。
3. 最后以分号 ; 结束 (members[2])。

• static $name = "example", $value; 也匹配 function_static_declaration，因为：
1. 以 static 关键字开始 (members[0])。
2. 接着是第一个 static_variable_declaration ($name = "example") (members[1] 的内部 SEQ 的 members[0])。
3. 然后是逗号 , 和第二个 static_variable_declaration ($value)， 这部分通过 members[1] 的内部 SEQ 的 members[1] (即 REPEAT 规则) 来处理。
4. 最后以分号 ; 结束 (members[2])。

6. choice-rule

• 含义： 这种规则类型定义了多个规则之间的选择。它表示“匹配规则 A 或规则 B 或规则 C”。

• 关键属性： "members"
• "members"： 一个规则定义数组。

• 必须包含字段：
• "type": "CHOICE"
• "members": 一个 rule 的数组。

7. alias-rule

• 含义： 这种规则类型重命名 AST 中的节点类型。这对于使 AST 更具语义意义或一致性非常有用，即使底层语法规则名称不同。

• 关键属性： "content"、"value"、"named"
• "content"：需要重命名的规则。
• "value"：希望在 AST 中为节点命名的新名称。
• "named"：布尔值，决定了通过别名创建的节点是命名节点(named node)还是匿名节点(anonymous node)，通常关键字为 false，命名节点为 true。

• 必须包含字段：
• "type": "ALIAS"
• "value": 别名值。
• "named": 是否命名规则。
• "content": 引用的规则。

8. repeat-rule & repeat1-rule

• 含义： 这些规则类型定义重复。
• "REPEAT"：匹配 content 规则零次或多次。
• "REPEAT1"：匹配 content 规则一次或多次。

• 关键属性： "content"
• "content"： 要重复的规则定义。

• 必须包含字段：
• "type": "REPEAT" || "type": "REPEAT1"
• "content": 引用的规则。

9. token-rule

• 含义： 将一个复杂的模式标记为单个词法单元，适用于“当多个字符应该被视为单个不可分割的标记时”，通常用于语法中的终结符号（标记）。

• 关键属性： "content"
• "content"：定义标记的规则

• 必须包含字段：
• "type": 可以是 "TOKEN" 或 "IMMEDIATE_TOKEN"。
• "content": 引用的规则。

10. field-rule

• 含义：为 AST 中的子节点命名。

• 关键属性： "name"、"content"
• "name"：希望赋予子节点的名称（例如 "condition"、"body"、"name"）。
• "content"：子节点的规则定义。

• 必须包含字段：
• "name": 字段名称。
• "type": "FIELD"
• "content": 引用的规则。

11. prec-rule 和优先级规则（PREC_LEFT、PREC_RIGHT、PREC_DYNAMIC）

• 含义： 这些规则用于处理语法中的运算符优先级和结合性，尤其是在表达式中。它们帮助解析时解决歧义。
• "PREC"：设置一个通用的优先级级别。
• "PREC_LEFT"：设置左结合性和优先级。
• "PREC_RIGHT"：设置右结合性和优先级。
• "PREC_DYNAMIC"：动态优先级，通常用于更复杂的情况。

• 关键属性： "value" 和 "content"
• "value"：优先级级别（数字越大优先级越高）。
• "content"：优先级适用的规则。

• 必须包含字段：
• "type": 可以是 "PREC"、"PREC_LEFT"、"PREC_RIGHT" 或 "PREC_DYNAMIC"。
• "value": 优先级值，可以是整数或字符串。
• "content": 引用的规则。

示例阐述

1. members[0]:
• 这是一个 ALIAS 规则，它将一个 PATTERN 规则别名为 "if"。
• PATTERN 规则匹配字符串 "if"（value: "if"），并且 flags: "i" 表示匹配是大小写不敏感的，所以可以匹配 if, If, IF 等。
• named: false 表示这个节点在抽象语法树中不会被明确命名，而是作为其父节点的匿名子节点。
• value: "if" 表示在 AST 中，这个节点会被标记为 "if" 类型。
• 含义: if_statement 必须以关键字 if 开头。

2. members[1]:
• 这是一个 FIELD 规则，它给子规则命名为 "condition"。
• content 是一个 SYMBOL 规则，引用了另一个规则 "parenthesized_expression"。
• 含义: 在 if 关键字之后，必须紧跟着一个用圆括号包裹的表达式，这个表达式会被解析为 "parenthesized_expression" 规则，并且在 AST 中被标记为 "condition" 字段，表示 if 语句的条件。

3. members[2]:
• 这是一个 CHOICE 规则，表示在条件表达式之后，if_statement 可以有两种不同的结构。
• members 数组包含两个 SEQ 规则，分别对应了两种 if 语句的语法形式：
• 第一个 SEQ 分支： 对应使用花括号 {} 包裹代码块的 if 语句。
• 第二个 SEQ 分支： 对应使用冒号 : 和 endif 关键字的代码块形式。
让我们进一步看 第一个 SEQ 分支（使用花括号的代码块）：
• members[0]: FIELD 规则，命名为 "body"，content 是 SYMBOL 规则 "statement"。
• 含义: if 条件之后，可以紧跟着一个 statement，作为 if 的主体代码块，在 AST 中标记为 "body" 字段。
• members[1]: REPEAT 规则，表示重复零次或多次。content 是 FIELD 规则，命名为 "alternative"，content 是 SYMBOL 规则 "else_if_clause"。
• 含义: 在 if 主体代码块之后，可以有零个或多个 elseif 分支，每个 elseif 分支会被解析为 "else_if_clause" 规则，并在 AST 中标记为 "alternative" 字段。
• members[2]: CHOICE 规则，表示选择。 members 数组包含两个规则：
• members[0]: FIELD 规则，命名为 "alternative"，content 是 SYMBOL 规则 "else_clause"。
• 含义: 可以有一个 else 分支，解析为 "else_clause" 规则，并在 AST 中标记为 "alternative" 字段。
• members[1]: BLANK 规则。
• 含义: else 分支是可选的，可以没有 else 分支。

1. 以 if 关键字开始 (members[0]).

2. 紧跟圆括号包裹的条件表达式 ($condition) (members[1]).

3. 然后是一个花括号 {} 包裹的代码块 (members[2] 的第一个 SEQ 分支的 members[0]).

4. 之后是一个 elseif 分支 (members[2] 的第一个 SEQ 分支的 members[1]).

5. 最后是一个 else 分支 (members[2] 的第一个 SEQ 分支的 members[2]).

Tree-sitter 的一些 Python package

• 官方的 python tree-sitter 库：https://github.com/tree-sitter/py-tree-sitter

• 很方便的集成调用库，看起来不打算维护了：https://github.com/grantjenks/py-tree-sitter-languages
• fork 出来，最新维护的库：https://github.com/Goldziher/tree-sitter-language-pack

1. 使用 py-tree-sitter（基础库）

1.1 手动编译

• 需要手动编译语法

• 可完全控制语法版本

1.2 联动 tree-sitter-{language}

2. 使用 py-tree-sitter-languages

• 包含预编译的 C++ 语法

• 无需构建依赖

3. 使用 tree-sitter-language-pack

• 维护良好的分支，支持 100+ 种语言

• 兼容 Tree-sitter ≥0.22.0

• 提供适用于所有主流平台的预构建包

可视化 Tree-sitter 解析的 AST

总结