Sublime Text 3 中的自定义语法

Question

我正在努力找出如何使用新的 .sublime-syntax 样式定义在 Sublime Text 3 中创建新的语法突出显示（以前的大多数答案都与旧的做法有关）。

从 Sublime Text Build 3084 开始，添加了新的语法定义格式，扩展名为 .sublime-syntax。

我可以找到：

• syntax rules
• scope naming rules
• colour scheme rules

但我找不到详细说明它们如何联系在一起的最基本信息！

我不是想创建一个主题，也不是调整现有的语法定义。我只想为具有我计划用于我自己目的的扩展名的文件创建语法突出显示。

1. 在语法定义中，我必须指定一个范围（例如 scope: source.c），但该范围文件在哪里？或者更确切地说，我在哪里创建我的范围文件，以及如何命名它，以便它加载？
2. 我如何知道我的语法文件及其使用的范围文件已成功加载和应用？
3. 是否有任何编译或刷新步骤，或者是否所有内容都会自动重新加载？

谢谢。

Answer 1

关于如何创建自定义语法的完整讨论远远超出了 Stack Overflow 答案这样简单的范围。另外，我认为您使问题变得比实际更复杂（尽管创建语法通常非常复杂）。

为了引导您完成创建自定义语法所需的步骤，这里有一个示例。

首先，创建一个包含以下内容的文件并将其保存为sample.ec，然后保持文件打开：

// This is a line comment
if (x == 2)
    y = 1
else
    z = 1

你会注意到这个文件的语法设置为Plain Text（见右下角的状态行），这是 Sublime 不知道的文件的默认语法。

现在，从菜单中选择Tools > Developer > New Syntax...。将出现具有以下内容的缓冲区。使用File > Save保存文件；该位置将默认为您的 User 包。你给它的名字并不重要，但要确保扩展名是sublime-syntax。在我的示例中，我调用我的文件Sample.sublime-syntax。

%YAML 1.2
---
# See http://www.sublimetext.com/docs/3/syntax.html
file_extensions:
  - ec
scope: source.example-c
contexts:
  main:
    # Strings begin and end with quotes, and use backslashes as an escape
    # character
    - match: '"'
      scope: punctuation.definition.string.begin.example-c
      push: double_quoted_string

    # Comments begin with a '//' and finish at the end of the line
    - match: '//'
      scope: punctuation.definition.comment.example-c
      push: line_comment

    # Keywords are if, else for and while.
    # Note that blackslashes don't need to be escaped within single quoted
    # strings in YAML. When using single quoted strings, only single quotes
    # need to be escaped: this is done by using two single quotes next to each
    # other.
    - match: '\b(if|else|for|while)\b'
      scope: keyword.control.example-c

    # Numbers
    - match: '\b(-)?[0-9.]+\b'
      scope: constant.numeric.example-c

  double_quoted_string:
    - meta_scope: string.quoted.double.example-c
    - match: '\\.'
      scope: constant.character.escape.example-c
    - match: '"'
      scope: punctuation.definition.string.end.example-c
      pop: true

  line_comment:
    - meta_scope: comment.line.example-c
    - match: $
      pop: true

现在使用View > Show Console 打开 Sublime 控制台或按下相关的键绑定。你会看到控制台的最后一行是这样的：

generating syntax summary

保持控制台打开，单击语法文件并再次执行另一个保存操作而不更改任何内容。同一行再次出现在控制台中。

1. 是否有任何编译或刷新步骤，或者是否所有内容都会自动重新加载？

如此处所示，每次修改语法定义时，都会重新编译文件并缓存结果。所以没有编译步骤（除了保存），你不需要做任何事情来刷新任何东西。

现在让我们将注意力转回到示例文件上。它仍然是开放的，语法仍然显示它是Plain Text。

现在关闭文件并重新打开它；一个快捷方式是使用File > Open Recent > Reopen Closed File 或其关联的键绑定。

请注意，现在文件已重新打开，有几处更改。首先，窗口右下角的语法名称为Sample（或您在上面为sublime-syntax 文件命名的任何名称）。另一方面，文件的内容现在语法突出显示。

您看到的颜色取决于您使用的配色方案，但示例可能如下所示：

// This is a line comment
if (x == 2)
    y = 1
else
    z = 1

1. 我如何知道我的语法文件及其使用的范围文件已成功加载和应用？

您可以在保存更改时看到该语法文件是由于缺少错误消息而编译的，您可以通过尝试使用该语法来判断它已被应用。

这里的语法是自动使用的，但是你会发现如果你在菜单中勾选View > Syntax或者点击窗口右下角的当前语法名称，你的语法就会出现在那里。同样，现在命令面板中有一个名为 Set Syntax: Sample（或其他名称）的条目。

这就引出了你的最后一个问题。如果您返回到您的 sublime-syntax 文件，您会在顶部看到：

# See http://www.sublimetext.com/docs/3/syntax.html
file_extensions:
  - ec
scope: source.example-c

首先要注意的是file_extensions包含ec，我们的示例文件名为sample.ec；因此，由于它的名称，此语法会自动应用于它。

现在切换到sample.ec 文件，将光标放在缓冲区中的某处并使用Tools > Developer > Show Scope Name 或按相关键。

弹出的内容会根据光标所在文件的位置而有所不同，但共同点是出现的范围总是以source.example-c开头。

1. 在语法定义中，我必须指定一个范围（例如范围：source.c），但该范围文件在哪里？或者更确切地说，我在哪里创建我的范围文件，以及如何命名它，以便它加载？

正如这里所见，没有“范围文件”之类的东西； sublime-syntax 文件直接将作用域指定为syntax rules 的一部分，因此它是您创建语法时唯一需要创建的文件。它可能看起来像一个文件名，但它不是一个。

语法中的语法匹配规则中应用的范围需要与你的配色方案中的范围一致，才能被语法高亮；这就是为什么您应该使用 scope naming rules 来使用所有语法共享的通用范围集，除非您还计划 make a color scheme 与您的语法一起使用，但除非您使用推荐的范围，否则您的语法不会与其他配色方案配合良好，而您的配色方案不适用于其他语法。

从此开始，您可以在此处修改sublime-syntax 文件，以使其以您想要的方式突出显示文件。这将包括更改顶部的基本范围，应用适当的扩展，然后包括与您的语言匹配的所有规则。

如上所述，创建与您的文件匹配的实际规则是创建语法中最复杂的部分，除非您的文件格式非常简单。它超出了可以在 Stack Overflow 答案中传达的内容的范围，但上面链接的官方文档为您提供了一些相关信息。

除了查看现有语法文件以了解它们的工作方式外，您还可以在 Sublime forum 上提出更多有针对性的问题。

Answer 2

我会尽快回答你的问题，其他人可以随意写一个更长的指南：

1. 您将语法定义放在一个包中：选择 Preferences > Browse Packages... 这应该会打开您的文件资源管理器。在那里，您可以为新包创建一个新文件夹或使用 User 文件夹，这是默认的用户包。在里面创建一个文件YourSyntax.sublime-syntax。
2. 您可以打开 ST 控制台ctrl+`，它会输出语法已加载和潜在错误。也可以按ctrl+shift+p，在缓冲区中写Set Syntax: YourSyntax直接看到。
3. 您只需要保存文件，它就会重新加载语法定义。