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

sharkdp/bat

菜单

示例语法定义

相关源文件

此页面记录了 bat 项目中的特定语法定义，这些定义是关于语法高亮如何实现的教学示例。这些示例演示了如何为其他语法高亮器可能不支持的文件格式创建自定义语法定义。

有关 bat 中通用语法高亮系统的信息，请参阅 语法高亮系统。有关如何添加自定义语法定义的详细信息，请参阅 语法定义和语言支持。

bat 中的语法定义概述

bat 工具使用 Sublime Text 语法定义格式（.sublime-syntax 文件）来定义不同文件类型的应如何高亮显示。这些定义以 YAML 编写，并使用正则表达式来识别文件的不同部分并应用适当的样式。

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax1-202

示例 1：Manpage 语法定义

Manpage 语法定义是 bat 为非传统编程语言的文件格式提供语法高亮的一个绝佳示例。此定义旨在高亮显示 Unix 手册页（man pages），使其在 bat 中更易读。

Manpage 语法定义的结构

Manpage 语法定义位于 assets/syntaxes/02_Extra/Manpage.sublime-syntax，并遵循以下基本结构

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax1-30 assets/syntaxes/02_Extra/Manpage.sublime-syntax31-60 assets/syntaxes/02_Extra/Manpage.sublime-syntax61-90

Manpage 语法的关键组件

  1. 元数据和文件扩展名:

  2. 用于模式匹配的变量:

  3. 上下文结构:

    • prototype：处理语法测试行
    • main：解析入口点
    • first_line：解析 manpage 标题行
    • body：处理 manpage 的主内容
    • 用于不同部分的专用上下文
      • synopsis：用于命令语法部分
      • commands：用于命令列表
      • options：用于命令行选项
      • environment-variables：用于环境变量
      • c-code：用于嵌入的 C 代码示例

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax1-20 assets/syntaxes/02_Extra/syntax_test_man.man1-20

Manpage 语法的特殊功能

Manpage 语法定义包含几项复杂的特性

  1. 章节识别：自动识别并高亮显示 manpage 的不同章节，如 SYNOPSIS、DESCRIPTION、OPTIONS 等。

  2. 命令行选项高亮：检测并高亮显示各种格式的命令行选项（例如 -a、--long-option）。

  3. 嵌入代码处理：能够识别并正确高亮 manpages 中嵌入的代码示例（特别是 C 代码）。

  4. 环境变量检测：识别并高亮显示环境变量。

  5. 命令高亮：在命令部分正确高亮显示命令及其参数。

这些组件的交互方式如下

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax40-70 assets/syntaxes/02_Extra/Manpage.sublime-syntax71-100 assets/syntaxes/02_Extra/Manpage.sublime-syntax101-130

测试 Manpage 语法

Manpage 语法定义在 tests/syntax-tests/source/Manpage/ 和 tests/syntax-tests/highlighted/Manpage/ 中包含全面的测试。这些测试确保语法高亮对各种 manpage 特性都能正常工作。

主要测试文件包括

  • syntax_test_man.man：测试基本的 manpage 功能
  • select-2.man：测试对复杂系统调用 manpage 的高亮
  • bat-0.16.man：测试对 bat 自身 manpage 的高亮
  • sway.5.man：测试对配置文件 manpage 的高亮
  • fzf-0.33.0.man：测试对命令行工具 manpage 的高亮

来源： tests/syntax-tests/highlighted/Manpage/select-2.man1-30 tests/syntax-tests/highlighted/Manpage/bat-0.16.man1-30

示例 2：VimL 语法定义

另一个教学示例是 VimL（Vim 脚本）语法定义，它用于高亮显示 Vim 的脚本语言。此示例展示了如何为领域特定脚本语言创建语法高亮。

VimL 语法的结构

VimL 语法定义处理 Vim 的脚本语言，这包括

  1. Vim 命令：内置命令，如 set、let、if、for 等。
  2. 变量：不同的变量作用域（全局、缓冲区、窗口等）
  3. 函数：函数定义和调用
  4. 条件语句和循环：VimL 特有的控制结构
  5. 特殊语法：VimL 特有的运算符和语法元素

来源： tests/syntax-tests/source/VimL/source.vim1-30 tests/syntax-tests/highlighted/VimL/source.vim1-30

VimL 语法的关键特性

VimL 语法定义展示了几个重要的技术

  1. 命令识别：识别 Vim 命令并对其进行适当高亮。

  2. 变量作用域处理：正确高亮显示不同的变量作用域。

  3. 函数定义和调用：高亮显示函数定义和调用。

  4. 控制结构：高亮显示 Vim 的控制结构。

  5. 特殊语法：处理 VimL 特有的语法，如映射和命令。

来源： tests/syntax-tests/source/VimL/source.vim31-60 tests/syntax-tests/highlighted/VimL/source.vim31-60

测试 VimL 语法

VimL 语法通过一个涵盖 Vim 脚本各个方面的综合测试文件进行测试

  • 声明具有不同作用域的变量
  • 函数定义和调用
  • 控制结构（if/else、for 循环）
  • 命令定义
  • 关键映射
  • 特殊 Vim 运算符和比较

此测试文件确保 VimL 的所有方面都能正确高亮。

来源： tests/syntax-tests/source/VimL/source.vim61-93 tests/syntax-tests/highlighted/VimL/source.vim61-93

创建自定义语法定义

基于这些示例，以下是创建有效语法定义的关键原则

语法定义文件的结构

组件目的示例
元数据定义语法的基本信息name、file_extensions、scope
变量定义可重用的正则模式section_heading: '^(?!#)\S.*$'
上下文 (Contexts)为文件的不同部分定义解析规则main、first_line、body
模式定义匹配内容的正则模式match: '^(?:SYNOPSIS|SYNTAX)'
作用域 (Scopes)为匹配内容定义样式目标scope: markup.heading.synopsis.man

示例的最佳实践

  1. 从清晰的元数据开始：清晰地定义名称、文件扩展名和作用域。

  2. 使用变量处理常见模式：将重复的正则模式提取为变量。

  3. 分层组织上下文：组织上下文以反映文件格式的结构。

  4. 处理特殊情况：为特殊部分或元素创建特定的上下文。

  5. 包含全面的测试：创建涵盖语法所有方面的测试文件。

  6. 使用适当的作用域：选择反映内容语义含义的作用域。

  7. 处理嵌入内容：创建处理嵌入代码或其他特殊内容的机制。

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax1-10 assets/syntaxes/02_Extra/syntax_test_man.man1-10

结论

Manpage 和 VimL 语法定义展示了 bat 语法高亮系统的灵活性和强大功能。通过学习这些示例，您可以了解如何为自己的文件格式创建有效的语法定义。

要点

  • 语法定义使用上下文和模式的层次结构
  • 使用正则表达式来识别文件的不同部分
  • 使用作用域来应用适当的样式
  • 专用上下文处理不同的部分或元素
  • 全面的测试确保了正确的高亮显示

有关如何为 bat 添加自定义语法定义的更多信息，请参阅 添加自定义语言。

来源： assets/syntaxes/02_Extra/Manpage.sublime-syntax1-202 tests/syntax-tests/source/VimL/source.vim1-93