在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

sharkdp/bat

菜单

语法定义和语言支持

相关源文件

本页面介绍了 bat 中语法高亮定义是如何构建和管理的，以及如何向系统中添加新的语言支持。内容涵盖语法定义的格式、它们如何集成到代码库中，以及添加新语言支持的流程。

有关语法定义如何被检测和映射到文件类型的信息，请参阅 语法检测与映射。有关资源如何构建和分发的详细信息，请参阅 资源管理与构建流程。

语法定义系统概述

bat 使用 syntect库来提供语法高亮。Syntect基于Sublime Text的语法定义格式，该格式使用YAML编写的.sublime-syntax文件来定义语言语法。

来源：doc/assets.md1-35

语法定义格式

bat 中的语法定义使用 .sublime-syntax 格式，这是一种基于 YAML 的格式，最初为 Sublime Text 开发。每个语法定义文件包含：

  1. 元数据：名称、文件扩展名和作用域信息
  2. 上下文：用于匹配和高亮代码不同部分的规则
  3. 模式：定义要匹配的内容和如何着色的正则表达式

以下是 .sublime-syntax 文件的简化结构示例

来源：assets/syntaxes/02_Extra/syslog.sublime-syntax1-66 assets/syntaxes/02_Extra/log.sublime-syntax1-185

示例：语法定义结构

我们以 syslog.sublime-syntax 文件中的简化示例为例进行说明

此示例展示了

  • 元数据：定义名称、文件扩展名和基础作用域
  • 上下文：带有匹配日期/时间模式规则的 main 上下文
  • 规则：带有捕获组、作用域赋值和上下文转换的正则表达式模式

来源：assets/syntaxes/02_Extra/syslog.sublime-syntax1-15

添加新的语言支持

要向 bat 添加新语言，需要遵循以下步骤：

来源：doc/assets.md1-35

1. 查找或创建语法定义

首先，找到你想要添加的语言的现有 Sublime Text 语法定义。理想情况下，它应该位于一个单独的 Git 仓库中，可以作为子模块包含进来。

如果语法仅以 .tmLanguage 格式（TextMate 格式）提供，则需要将其转换为 .sublime-syntax 格式。这可以使用 Sublime Text 或其他转换工具完成。

来源：doc/assets.md11-21

2. 将语法添加到项目中

将语法仓库添加为 Git 子模块

git submodule add <https github link> ./assets/syntaxes/02_Extra/<repo name>

对于没有独立仓库的语法，你可以手动将其添加到 assets/syntaxes 目录中。

来源：doc/assets.md11-14 doc/assets.md92-106

3. 构建资源

运行 assets/create.sh 脚本将语法定义构建为二进制格式。

./assets/create.sh

此脚本会调用 bat cache --build 来解析所有可用的 .sublime-syntax 文件，并将它们序列化为一个 syntaxes.bin 文件。

来源：doc/assets.md23-24

4. 重新编译 bat

重新编译 bat 以包含新的语法定义。

cargo build

在编译时，syntaxes.bin 文件将被嵌入到 bat 二进制文件中。

来源：doc/assets.md26-27

5. 测试新语言

验证新语言是否可用。

bat --list-languages

你可能需要调整你的 PATH 环境变量，以确保你使用的是本地编译的版本。

来源：doc/assets.md29

6. 添加语法测试

创建语法测试以确保高亮正常工作，并防止回归问题。

来源：doc/assets.md37-68

纳入标准

bat 默认不包含所有语法定义。要纳入，语法应满足以下标准：

这确保了只包含广泛使用的语法，从而使二进制文件的大小保持在可控范围内。

来源：doc/assets.md75-77

手动修改

一些语法定义在从原始格式转换后需要手动修改。这些修改记录在 doc/assets.md 文件中，通常包括：

  • 添加或删除文件扩展名
  • 修复兼容性问题
  • 改进语言检测

手动修改的语法示例包括：

  • Apache.sublime_syntax：删除了 conf 和 CONF 文件类型
  • INI.sublime-syntax：添加了各种配置文件扩展名
  • Robot.sublime_syntax：更改名称为“Robot Framework”，添加了 .resource 扩展名

来源：doc/assets.md79-90

非子模块添加

有些语法定义是手动添加的，而不是作为子模块。这发生在以下情况：

  • 语法未在独立的仓库中维护
  • 存在 Git 递归问题
  • 只需要一个大型仓库中的特定文件

示例包括

  • Assembly (x86_64)：因 Git 递归问题而手动添加
  • Nim.sublime-syntax：从 Zola 项目添加，因为没有合适的 Git 仓库
  • Rego.sublime-syntax：从 OPA 项目添加

来源：doc/assets.md92-106

语法测试系统

bat 包含一个全面的语法高亮测试系统，以防止回归。

语法测试系统的工作原理如下：

  1. 将示例源文件添加到 tests/syntax-tests/source/<Language>/
  2. 运行 update.sh 脚本生成高亮版本。
  3. 验证高亮是否正确。
  4. 提交源文件和高亮文件。

这确保了语法高亮在不同版本之间保持一致，并防止了回归。

来源：doc/assets.md37-68 tests/syntax-tests/source/Syslog/example.syslog1-18 tests/syntax-tests/highlighted/Syslog/example.syslog1-18

示例语法定义

让我们来看一些 bat 中的语法定义示例。

日志文件语法

log.sublime-syntax 文件为通用日志文件提供高亮。

  • 检测日志级别（error、warning、info、debug）
  • 高亮显示日期、时间、IP 地址
  • 支持各种数字格式
  • 高亮显示 URL 和引号字符串

来源：assets/syntaxes/02_Extra/log.sublime-syntax1-185 tests/syntax-tests/highlighted/Log/example.log1-4

INI 文件语法

INI.sublime-syntax 文件处理各种配置文件格式。

  • 支持多种文件扩展名（.ini, .inf, .cfg 等）
  • 高亮显示节标题、键、值和注释
  • 处理带引号的字符串和特殊字符

来源：assets/syntaxes/02_Extra/INI.sublime-syntax1-51 tests/syntax-tests/source/INI/test.inf1-6 tests/syntax-tests/highlighted/INI/test.inf1-6

环境变量文件

DotENV.sublime-syntax 文件支持各种环境变量文件格式

  • 处理多个 .env 文件变体
  • 高亮显示变量赋值、字符串和插值
  • 支持注释和特殊值

来源：assets/syntaxes/02_Extra/DotENV.sublime-syntax1-99

故障排除

在使用语法定义时，您可能会遇到问题。以下是一些故障排除技巧

  • 清除本地缓存，确保它不会干扰内部存储的语法

    bat cache --clear

  • 如果语法未被正确检测，请检查文件扩展名映射和语言检测规则。

  • 对于语法高亮问题，请检查语法定义文件并确保模式与预期内容匹配。

来源：doc/assets.md70-73

结论

bat 中的语法定义系统基于 Sublime Text 的 .sublime-syntax 格式，并通过 Git 子模块和手动添加进行管理。添加新的语言支持涉及查找或创建语法定义，将其添加到项目中，构建资产，并测试结果。

该系统设计为可扩展的，同时保持了包含的语法的高质量标准。全面的测试系统确保语法高亮保持一致并防止回归。