TablePro 语法高亮基石:TreeSitter 语法仓库(vendored grammars)的选型、编译与升级指南
TablePro 语法高亮基石:TreeSitter 语法仓库(vendored grammars)的选型、编译与升级指南
导读
本文以 Packages/TableProGrammars/Sources/TreeSitterGrammars/ORIGIN.md 为核心脉络,系统讲解 TablePro 编辑器语法高亮所使用的四套 tree-sitter 语法(bash、javascript、json、sql)的来源、许可证合规管理、查询文件(.scm)组织方式,以及如何安全地升级一个语法而不破坏编辑器。读完本文,你将理解这些 vendored 语法如何被编译进 Swift 包、如何通过测试守护查询文件与解析器的同步,并掌握从上游发布版复制 parser.c/scanner.c/queries 到跑通编辑器的完整升级流程。
一、为什么 TablePro 要 vendored 语法,而不是运行时下载
TreeSitter 采用"生成式解析器"模式:每个语言的解析器(parser.c,必要时附带 scanner.c)由语法仓库根据语言规范生成,编译进宿主程序后即可稳定、增量地解析源码。TablePro 选择把这四套语法直接复制进自己的代码库,而不是在运行时动态下载,原因可以从仓库结构直接读出来:
- 可确定性:语法随应用版本发布,编辑器的高亮、缩进行为不随上游仓库变化而漂移,任何一次构建产出的高亮结果都可复现。
- 零网络依赖:编辑器的代码编辑功能不依赖网络即可完成解析与着色。
- 合规可追溯:每个语法目录内都保留上游
LICENSE,并且在应用的三方许可清单中逐一登记(见下文第三节)。
这一点在 ORIGIN.md 中说得非常直白:Generated parsers and their query files, copied from each grammar's own repository. Nothing here is written by TablePro. —— 这些解析器是上游生成的产物,TablePro 只负责搬运、编译与测试验证。
二、四个 vendored 语法与查询文件全景
ORIGIN.md 中的清单表格完整列出四套语法及其上游来源与许可证,仓库实际布局完全一一对应:
| 语法目录 | 上游仓库 | 许可证 | 仓库内文件 |
|---|---|---|---|
bash |
tree-sitter-bash | MIT,Copyright (c) 2017 Max Brunsfeld | parser.c、scanner.c、LICENSE |
javascript |
tree-sitter-javascript | MIT,Copyright (c) 2014 Max Brunsfeld | parser.c、scanner.c、LICENSE |
json |
tree-sitter-json | MIT,Copyright (c) 2014 Max Brunsfeld | parser.c、LICENSE(无 scanner) |
sql |
tree-sitter-sql(Derek Stride) | MIT,Copyright (c) 2021 Derek Stride | parser.c、scanner.c、LICENSE |
以上文件均位于 Packages/TableProGrammars/Sources/TreeSitterGrammars 下。注意 json 只有 parser.c 没有 scanner.c——因为 JSON 的词法可以用纯上下文无关文法描述,不需要外部扫描器,这与 bash/javascript/sql 三种语言(需要处理注释、字符串、here-doc 等上下文敏感词法)形成对比。
2.1 解析器 ABI 头文件
ORIGIN.md 还强调了一点:vendored-headers/tree_sitter 存放的是生成解析器编译时依赖的 ABI 头文件,来自 tree-sitter 主仓库(MIT,Copyright (c) 2018-2024 Max Brunsfeld)。仓库内对应目录为 Packages/TableProGrammars/Sources/TreeSitterGrammars/vendored-headers/tree_sitter,包含:
parser.h:TSLanguage 等核心类型与 API 声明alloc.h、array.h:运行时辅助ts_assert.h:断言辅助
而对外暴露的符号由 include/TreeSitterGrammars.h 声明,共四个入口函数,与四个语法一一对应:
const TSLanguage *tree_sitter_sql(void);
const TSLanguage *tree_sitter_bash(void);
const TSLanguage *tree_sitter_javascript(void);
const TSLanguage *tree_sitter_json(void);
2.2 Swift 侧如何消费这些 C 解析器
C 目标与 Swift 目标的桥接关系可以在 Packages/TableProGrammars/Package.swift 中确认:
TreeSitterGrammars是一个 C target,publicHeadersPath指向include,并在cSettings中通过.headerSearchPath("vendored-headers")让四个parser.c找到 ABI 头。TableProGrammarsSwift target 依赖TreeSitterGrammars与 SwiftTreeSitter(ChimeHQ/SwiftTreeSitter,版本0.9.0起),并把Queries目录作为 bundle 资源复制(resources: [.copy("Queries")])。
Swift 侧的消费点在 CodeLanguage.swift:parser 私有属性通过 switch id 直接调用四个 tree_sitter_*() 入口,再包装成 SwiftTreeSitter 的 Language 对象。其中有一个关键设计:jsx 语言与 javascript 共用同一个解析器与查询目录(grammarName 都是 "javascript"),这也是 ORIGIN.md 中提到的"JSX 读取 JavaScript 解析器"在源码层的落点。
三、许可证合规:从语法目录到 Acknowledgements 窗口
ORIGIN.md 描述了一条完整的合规链:每个语法目录内的 LICENSE 是"就近携带"的许可证副本,而 TablePro/Resources/ThirdPartyLicenses/licenses.yml 是应用级的统一登记表,最终文本会进入应用的 Acknowledgements 窗口。
在 licenses.yml 中,四个语法的登记条目(tree-sitter-bash、tree-sitter-javascript、tree-sitter-json、tree-sitter-sql)都标注了 source: manual、spdx: MIT、patched: false,并一一指向 texts/ 下的许可证文本文件。以 tree-sitter-sql 条目为例:
- 版权行:
Copyright (c) 2021 Derek Stride - 说明:
Generated parser and scanner plus the highlight and indent queries. This is the grammar behind every colour in the SQL editor. The upstream LICENSE travels with the sources at Sources/TreeSitterGrammars/sql/LICENSE. Confirmed shipping: the _tree_sitter_sql entry point in the app dylib.
这条 notes 非常关键,它印证了 ORIGIN.md 的两点主张:许可证文本跟随源码目录,并且应用通过符号(_tree_sitter_sql 入口点)确认了这些解析器确实被打进发布二进制。测试也守护了这一点——TableProGrammarsTests.swift 中的 everyGrammarShipsItsLicence 会读取每个语法目录的 LICENSE,断言其包含 MIT 与 Copyright 字样。
提醒:
licenses.yml中的homepageURL等字段指向上游仓库。若你在本地仓库中修改或新增语法,应同步更新这张登记表,保持"目录内 LICENSE + 统一清单 + Acknowledgements 文本"三层一致。
四、查询文件(.scm):高亮规则的存放与加载顺序
ORIGIN.md 明确指出:Sources/TableProGrammars/Queries 下的 .scm 查询文件同样来自四个上游仓库,携带相同许可证。仓库内的实际布局为 Packages/TableProGrammars/Sources/TableProGrammars/Queries:
| 语法 | 查询文件 |
|---|---|
| tree-sitter-bash | highlights.scm |
| tree-sitter-javascript | highlights.scm、highlights-jsx.scm、highlights-params.scm、injections.scm、locals.scm、tags.scm |
| tree-sitter-json | highlights.scm |
| tree-sitter-sql | highlights.scm、indents.scm |
以 SQL 的 highlights.scm 为例,可以看到 tree-sitter 查询的典型写法——用 S-expression 模式把语法节点映射到高亮捕获名(@function.call、@type、@variable、@field、@number、@float、@keyword.* 等),并支持 #match? 谓词做数值形态的区分:
(invocation
(object_reference
name: (identifier) @function.call))
((literal) @number
(#match? @number "^[-+]?\\d+$"))
((literal) @float
(#match? @float "^[-+]?\\d*\\.\\d*$"))
4.1 加载与缓存机制
查询文件由 HighlightQueries.swift 负责编译与缓存:
- 每个语言首次被请求时,把其
additionalQueries(如 javascript 的injections、jsx 的highlights-jsx+injections)按字母序排在高亮主查询之前拼接成一个查询源,然后调用 SwiftTreeSitter 的Query(language:data:)编译。 - 顺序是语义性的:
highlights-jsx.scm必须在 JS 主高亮之前读取,因为它是对 JS 模式的"收窄";tree-sitter 取第一个匹配的模式,顺序颠倒会让 JSX 节点被 JS 模式抢先匹配。 - 编译后的
Query按GrammarID缓存于进程级单例(HighlightQueries.shared),加锁保护;测试queriesAreCached验证了同一查询多次取回的是同一个实例(first === second)。
4.2 资源定位的细节
CodeLanguage.queryURL(for:) 通过 Bundle.module.url(forResource:withExtension:subdirectory:) 定位 .scm 文件。源码注释特意解释了为什么必须走 Bundle 而不是手工拼接 resourceURL:不同工具链下 bundle 的资源可能位于根目录或 Contents/Resources 下,只有 Bundle 知道正确的布局。测试 queryDirectoryDoesNotShadowTheResourcesRoot 还防范了一个陷阱——复制进来的目录若恰好叫 Resources,会被误当作资源根目录,导致每次查找路径翻倍。
五、语言注册表:CodeLanguage 与 GrammarID
两个 Swift 枚举/结构体把"语法仓库"与"编辑器高亮"连接起来:
- GrammarID.swift 定义
bash、javascript、jsx、json、sql、plainText六个 case,其中plainText表示"没有语法"。 - CodeLanguage.swift 为每个语言声明文件扩展名、注释语法与额外查询:
| 语言 | grammarName | 扩展名 | 行注释 | 块注释 | additionalQueries |
|---|---|---|---|---|---|
| bash | bash | sh、bash |
# |
:' … ' |
— |
| javascript | javascript | js、cjs、mjs |
// |
/* */ |
injections |
| jsx | javascript | jsx |
// |
/* */ |
highlights-jsx、injections |
| json | json | json |
— | — | — |
| sql | sql | sql |
-- |
/* */ |
— |
| default(纯文本) | plaintext | txt |
— | — | — |
这些声明是编辑器注释功能、文件扩展名识别、高亮查询加载的直接数据源。测试套件对这张表做了多种一致性校验:每个非纯文本的 GrammarID 都能解析出解析器(everyIDHasAParser)、每种语言的高亮查询都能针对自己的语法编译成功(everyHighlightQueryCompiles)、没有两种语言抢占同一扩展名(extensionsDoNotCollide)、SQL 的注释符号与编辑器写入行为一致(sqlCommentSyntax)。
六、升级一个语法:从上游发布版到测试通过
ORIGIN.md 最后一段给出升级流程的浓缩版,结合仓库布局可以展开为一份可操作的清单:
- 选择发布版:去对应上游仓库(表格见第二节)找到要升级的 tagged release,注意
sql语法来自 DerekStride/tree-sitter-sql,与前三者不在同一组织下。 - 复制解析器源文件:把
src/parser.c、src/scanner.c(如有)复制到对应的Sources/TreeSitterGrammars/<grammar>/目录,覆盖旧文件。 - 刷新查询文件:把
queries/*.scm复制到Sources/TableProGrammars/Queries/tree-sitter-<grammar>/。若上游删改或新增了查询文件(如 JS 的injections.scm/locals.scm/tags.scm),需要同步调整 CodeLanguage.swift 中对应语言的additionalQueries集合。 - 刷新许可证:把上游新的
LICENSE复制到语法目录内(测试everyGrammarShipsItsLicence会校验 MIT 与 Copyright 字样),并按需更新 licenses.yml 的登记条目。 - 跑编辑器套件:运行
TableProGrammarsTests与编辑器相关测试。ORIGIN.md特别强调:SyntaxHighlightingTests会把每个.scm查询文件对着自己的语法编译一遍,因此某个查询与重新生成的解析器"脱节"(例如引用了已删除的节点名)会在测试阶段失败,而不是等到用户打开文档时才在运行时暴露。仓库内对应的测试即 TableProGrammarsTests.swift 中的everyHighlightQueryCompiles与everyNamedQueryFileExists。
6.1 为什么不把测试当运行时
ORIGIN.md 的这段话值得细读:"a query that drifts out of step with a regenerated parser fails there rather than at runtime." 这正是测试前置校验的价值:编译期/测试期拦截 query 与 parser 的不兼容,把故障面从"用户文档打开瞬间的高亮异常"前移到"CI 中的一次失败"。如果升级后想快速验证,可以在仓库内通过 swift test --package-path Packages/TableProGrammars 运行该包的全部测试。
七、小结
| 关注点 | 结论 | 仓库证据 |
|---|---|---|
| 语法来源 | bash / javascript / json / sql 全部来自各自上游仓库,TablePro 零自写解析器代码 | ORIGIN.md |
| 许可证合规 | 目录内 LICENSE + licenses.yml 登记 + Acknowledgements 文本三层闭环 | licenses.yml |
| 高亮规则 | .scm 查询文件按"额外查询在前、主查询在后"的顺序拼接编译并缓存 |
HighlightQueries.swift |
| 语言注册 | CodeLanguage 声明扩展名/注释/查询,GrammarID 映射解析器 | CodeLanguage.swift |
| 升级保障 | 每个查询都必须能对着自己的语法编译,漂移在测试期暴露 | TableProGrammarsTests.swift |
如果你接下来要在 TablePro 中扩展新的语法支持(例如加入 Rust、Python 等语言),完全可以复用这套模式:新增 Sources/TreeSitterGrammars/<grammar>/ 目录(parser.c + LICENSE)→ 在 include/TreeSitterGrammars.h 声明入口函数 → 在 GrammarID 增加 case → 在 CodeLanguage 注册语言属性 → 在 Queries/tree-sitter-<grammar>/ 放置高亮查询 → 在 licenses.yml 登记——最后让测试替你确认整条链路是自洽的。