tree-sitter-cangjie 版本演进解析:从 v0.1.0 到 v1.0.0 的语法解析能力与实现细节
tree-sitter-cangjie 版本演进解析:从 v0.1.0 到 v1.0.0 的语法解析能力与实现细节
本篇文章以仓库 CHANGELOG.md 为骨架,结合 grammar.js、src/scanner.c、queries 与 test/corpus/main.txt 等源码与配置,逐条拆解 tree-sitter-cangjie 两个版本的关键变更:多行字符串词法支持、语法高亮与缩进查询、节点命名收敛、结束符号自动识别,以及 Range 表达式与浮点数歧义的消除。读完你将理解该解析器语法树的结构设计、外部扫描器(external scanner)的工作原理,以及如何按新规范完成安装与测试。
一、CHANGELOG 与项目定位:一份简短但信息密度极高的版本史
tree-sitter-cangjie 是专为仓颉(Cangjie)编程语言设计的 Tree-sitter 语法解析器,核心产物是 src/parser.c(由 grammar.js 生成)与 src/scanner.c(手写的多行原始字符串词法扫描器),并配套高亮、缩进、标签与文本对象四套查询规则。
仓库的 CHANGELOG.md 记录了两次正式发布,全文虽然只有 9 行,但每条变更都对应仓库中可验证的具体实现:
| 版本 | 变更要点 | 对应实现位置 |
|---|---|---|
| v0.1.0 | 支持源文件解析、多行字符串、高亮和缩进 | grammar.js、src/scanner.c、queries/highlights.scm、queries/indents.scm |
| v1.0.0 | 优化节点语法表示;解决结束符号自动识别;解决 Range 与浮点数冲突;取消 modifier/modifiers 节点;安装示例不再使用预生成文件 | grammar.js、grammar_common.js、grammar_literal.js、README.md、Makefile |
下文以版本为脉络,逐一展开这些变更背后的源码细节。
二、v0.1.0:从零到可用——解析、多行字符串、高亮与缩进
2.1 源文件解析:translationUnit 驱动的顶层结构
v0.1.0 首先交付的是“源文件解析”能力。在 grammar.js 中,翻译单元的规则如下:
translationUnit: $ => seq(
optional(choice($.packageDeclaration, $.macroPackageDeclaration)),
repeat($.importList),
optional($._topObjects),
optional($.mainDefinition),
optional($._topObjects),
),
它覆盖了仓颉源文件的所有顶层形态:可选的 package/macro package 声明、任意数量的 import、顶层对象(变量声明、函数定义、类/接口/结构体/枚举定义、类型别名、extend、foreign 声明、宏定义与宏表达式,见 _topLevelObject)、main 入口,且允许 main 前后都出现顶层对象。
对应的解析测试见 test/corpus/main.txt,其中 macro package、import std.ast.*、import std.collection.ArrayList 被解析为 macroPackageDeclaration、packageFull 与 scoped_identifier 节点,验证了包与导入语句的树形结构。
2.2 多行字符串:普通三引号与带 # 定界符的原始字符串
“多行字符串”是 v0.1.0 的标志性能力。在 grammar_literal.js 中,字符串字面量被细分为三类:
- 行内字符串
_lineStringLiteral:支持单引号与双引号两种写法,内部可包含 Unicode 转义\u{...}、转义标识符以及${...}内嵌表达式; - 多行字符串
_multiLineStringLiteral:以"""开头(要求紧跟换行),内容中同样支持转义与${...}多行内嵌表达式; - 多行原始字符串
_multiLineRawStringLiteral:通过#定界符控制,这也是需要外部扫描器的原因。
原始字符串的定界规则是:# 的数量决定定界符强度,#"..."#、##"..."## 可层层嵌套区分,从而使字符串内容中的 " 或 "# 不会误终止字符串。这一逻辑由 src/scanner.c 实现:
- 扫描器状态仅含两个字段:
in_string(是否处于字符串内)与delimiter_length(当前定界符#的数量),见 Scanner 结构体; - scan_opening_delimiter 统计开头的
#数量,随后要求紧跟",记录定界符长度并进入字符串状态; - scan_string_content 逐字符消费内容,每当遇到
"就前瞻统计后续#的数量,只有与定界符长度完全一致时才判定为内容结束; - scan_closing_delimiter 负责在收尾阶段校验
#数量与起始定界符一致后完成闭合。
值得一提的还有 serialize/deserialize:Tree-sitter 做增量解析时会序列化外部扫描器的状态(此处仅 2 字节),恢复后再继续解析,从而保证编辑器内边输入边解析时多行字符串的定界状态不丢失——这正是“增量解析”在词法层面的支撑。
2.3 高亮与缩进:queries 目录的两套查询
v0.1.0 同时交付了编辑器体验所需的查询文件:
- queries/highlights.scm:将
stringLiteral标为@string、integerLiteral/floatLiteral标为@number、类名/结构体名/接口名标为@type、funcName标为@function,并维护了完整的仓颉关键字表(struct、enum、package、import、func、match、where、extend、spawn等约 60 个)与运算符表; - queries/indents.scm:定义了缩进规则——
classBody、block、callSuffix、arrayLiteral、matchCase等作为@indent.begin,右括号]、)、}作为@indent.end与@indent.branch,注释行标为@indent.auto。
此外,仓库还提供 queries/tags.scm(符号定义跳转,如 classDefinition 的 @definition.class、functionDefinition 的 @definition.function)与 queries/textobjects.scm(文本对象选区),供 IDE 与 LSP 工具链使用。
三、v1.0.0:四项关键优化背后的源码依据
3.1 优化节点语法表示:alias 收敛语法树
“节点语法表示”优化在 grammar.js 中通过 alias 机制实现。语法树对外呈现的节点名不再与内部匿名规则绑定,而是收敛为语义清晰的命名节点,例如:
_functionName: $ => alias($.identifier, $.funcName), // 函数名
_className: $ => alias($.identifier, $.className), // 类名
_structName: $ => alias($.identifier, $.structName), // 结构体名
interfaceName / propertyName / typeAliasName / macroName … // 其余类型同理
这样,node-types.json 中会稳定出现 funcName、className、propertyName 等节点类型,下游的高亮查询((funcName) @function)与文本对象查询可以直接按名匹配,无需关心底层 identifier 的内部形态。在 grammar.js 中,基础类型同样用 alias(TOKENS.INT8, $.Int8) 等方式将 Int8、Float32、Bool、Rune、Unit、Nothing 等收敛为类型节点,与 queries/highlights.scm 的类型高亮一一对应。
3.2 结束符号的自动识别:换行与分号统一为 terminator
“结束符号的自动识别”解决了语句边界判定的问题。在 grammar_common.js 中定义:
const newline = /\r?\n/;
const terminator = choice(newline, ';');
terminator 同时接受换行与分号,因此包声明、导入列表、顶层对象、成员声明、表达式序列等规则(见 grammar.js 中大量 repeat1(terminator)、optional(repeat1(terminator)) 的用法)都能在“以换行结束”或“以分号结束”之间自由切换,自动识别。
从源码演化看,旧版的 grammar_expression.js(README 中已注明“后期不再需要”的合并前文件)仍残留 repeat(seq(repeat1($._END), $._expressionOrDeclaration)) 这类以 _END 符号分隔的写法;合并进主文件后的 grammar.js 统一改用 terminator,正是该优化落地的证据。
3.3 Range 表达式与浮点数的冲突:数字词法的最优匹配
“Range 表达式与浮点数的冲突”是文本解析中的经典歧义:1..10 是 Range(区间),而 1.5 是浮点数,两者都以 数字. 开头。仓库通过两套规则的分工消解冲突:
- 浮点数规则在 grammar_literal.js 中要求小数点后必须跟数字(
seq(decimalLiteral, '.', decimalDigits, ...)),1.后面若是.(而不是数字)则不会被识别为浮点数; - Range 表达式规则在 grammar.js 中定义:
start .. end或start ..= end,并可带: step步长:
rangeExpression: $ => prec.right(PREC.RANGE, seq(
field('start', $._expression),
choice(token('..'), token('..=')),
field('end', $._expression),
optional(seq(':', field('step', $._expression)))
)),
因此 1..10、0.5..=2.5 均能正确切分:词法器在 1. 处因后跟 . 而回退浮点数匹配,转而交给 Range 规则。同时 grammar_common.js 中 PREC.RANGE = 20 的优先级低于算术运算(ADD_SUB = 22、MUL_DIV = 23),确保 a + 1..10 这类组合表达式的结合方向符合语言预期。node-types.json 中大量出现的 rangeExpression 与 floatLiteral 节点类型,也印证了两种字面量在语法树中各自独立、互不干扰。
3.4 取消 modifier 与 modifiers 节点:修饰符收敛为单一组合节点
CHANGELOG 记录 v1.0.0 取消了 modifier 与 modifiers 节点。从当前源码结构看,演化结果是:不再为每个修饰符生成独立的 modifier 子节点,而统一由 modifiers 组合节点承载。证据如下:
- grammar.js 中
modifiers规则定义为repeat1(choice(PUBLIC, PROTECTED, PRIVATE, INTERNAL, ABSTRACT, STATIC, SEALED, REDEF, OPEN, OVERRIDE, MUT, UNSAFE, CONST)),全部是 token 级选择,不会展开为子节点; - 对 src/node-types.json 检索
"type": "modifier"(精确到单数)无任何结果,而modifiers作为声明规则的子节点出现约 18 处,覆盖packageDeclaration、variableDeclaration、functionDefinition、classDefinition、interfaceDefinition、structDefinition、enumDefinition、typeAlias、init、primaryInit、macroDefinition等全部可带修饰符的声明。
也就是说,语法树中一个带 public sealed 修饰的类定义,其修饰符整体呈现为一个 modifiers 节点,而非多个细粒度节点,这显著简化了查询与遍历逻辑。需要注意:该优化同时要求编辑器的高亮查询不再依赖 modifier 节点——highlights.scm 中 (modifiers) @keyword 的写法与当前语法树状态是一致的。
3.5 安装示例不再使用预生成文件:从生成到安装的完整链路
v1.0.0 的最后一个变更关系到安装方式:示例不再直接使用仓库预生成的 parser.c,而是要求从 grammar.js 现场生成。这与本仓库的实际工程配置完全吻合:
- README.md 的 nvim-treesitter 安装配置中明确写出:
parser_config.cangjie = {
install_info = {
url = "https://gitcode.com/Cangjie-SIG/tree-sitter-cangjie", -- 或指定本地文件夹
files = { "src/parser.c", "src/scanner.c" },
branch = "main",
generate_requires_npm = false,
requires_generate_from_grammar = true, -- 不使用预生成的文件,需要先安装 tree-sitter-cli
},
filetype = "cangjie",
}
- Makefile 定义了生成依赖:
$(PARSER): $(SRC_DIR)/grammar.json后执行$(TS) generate,即parser.c由tree-sitter generate根据语法定义产出;同时 tree-sitter.json 声明语法名cangjie、scopesource.cj、文件后缀cangjie/cj,并指向queries/highlights.scm与queries/indents.scm; - 多语言绑定(C/Go/Node/Python/Rust/Swift)均围绕同一份生成产物展开,例如 Rust 侧 bindings/rust/lib.rs 通过
tree_sitter_cangjie()暴露LANGUAGE常量,Node 侧 bindings/node/index.js 通过 node-gyp-build 加载原生模块。
四、版本能力自检:如何验证两个版本承诺的功能
要验证 v0.1.0 与 v1.0.0 承诺的能力,可按仓库给出的标准流程执行:
# 克隆仓库(或使用本地目录)
git clone https://gitcode.com/Cangjie-SIG/tree-sitter-cangjie
cd tree-sitter-cangjie
# 从 grammar.js 生成 parser.c 并编译
tree-sitter build
# 运行语法解析测试(corpus 测试)
tree-sitter test
tree-sitter test 会读取 test/corpus/main.txt 等用例,校验输入代码与期望的语法树是否一致;tree-sitter playground 可打开交互式解析界面实时观察语法树。验证点可覆盖:多行原始字符串(#"..."# 定界符)能否被 scanner 正确分段、1..10 与 1.5 是否各自解析为 rangeExpression 与 floatLiteral、带 public sealed 修饰的声明是否只产生单一 modifiers 节点。
此外,node-types.json 是语法树节点类型的权威清单,任何基于该解析器开发的高亮、补全、缩进或重构工具,都应以其为准进行匹配。
五、结语:从 CHANGELOG 读出的工程脉络
回顾 CHANGELOG.md,v0.1.0 解决的是“能不能解析”(语法覆盖、多行字符串、编辑器查询),v1.0.0 解决的是“解析得好不好”(节点命名、歧义消除、状态收敛与安装流程现代化)。每一行变更都能在 grammar.js、src/scanner.c、queries 与 Makefile 中找到对应实现,这本身就是一份高质量 CHANGELOG 应有的样子——既记录事实,也留下可追溯的源码线索。对于希望为仓颉语言接入 Tree-sitter 生态的开发者而言,这份变更记录加上上述源码路径,就是最直接的二次开发地图。