tree-sitter-cangjie 版本演进解析:从 v0.1.0 到 v1.0.0 的语法解析能力与实现细节

原创2026-10-14 22:35:201,340 阅读
文章标签:开发工具编译器

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、scope source.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 生态的开发者而言,这份变更记录加上上述源码路径,就是最直接的二次开发地图。

登录后查看全文
tree-sitter-cangjie