Sublime Text 3 中的自定义语法 [英] Custom syntax in Sublime Text 3

问题描述

我正在努力寻找如何使用新的 .sublime-syntax 样式定义在 Sublime Text 3 中创建新的语法高亮显示(大多数以前的答案与旧的方法有关).

<块引用>

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

我可以找到:

• 语法规则
• 作用域命名规则
• 配色方案规则

但我找不到最基本的信息来详细说明这些是如何联系在一起的！

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

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

谢谢.

解决方案

关于如何创建自定义语法的完整讨论远远超出了 Stack Overflow 答案这样简单的范围.此外，我认为您的问题比实际情况更复杂(尽管创建语法通常非常复杂).

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

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

//这是一行注释如果 (x == 2)y = 1别的z = 1

您会注意到此文件的语法设置为 Plain Text(请参阅右下角的状态行)，这是 Sublime 未知文件的默认语法.

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

%YAML 1.2---# 见 http://www.sublimetext.com/docs/3/syntax.html文件扩展名:- 欧共体范围:source.example-c上下文:主要的:# 字符串以引号开始和结束，并使用反斜杠作为转义符# 特点- 比赛: '"'范围:punctuation.definition.string.begin.example-c推:double_quoted_string# 注释以//"开始并在行尾结束- 比赛: '//'范围:punctuation.definition.comment.example-c推送:line_comment# 关键字是 if、else for 和 while.# 注意黑斜线不需要在单引号内转义# YAML 中的字符串.使用单引号字符串时，只能使用单引号# 需要转义:这是通过在每个旁边使用两个单引号来完成的# 其他.- 匹配:'\b(if|else|for|while)\b'范围:keyword.control.example-c# 数字- 匹配:'\b(-)?[0-9.]+\b'范围:constant.numeric.example-cdouble_quoted_string:- meta_scope: string.quoted.double.example-c- 比赛: '\\.'范围:constant.character.escape.example-c- 比赛: '"'范围:punctuation.definition.string.end.example-c流行音乐:真的line_comment:- meta_scope:comment.line.example-c- 匹配:$流行音乐:真的

现在用 View > 打开 Sublime 控制台.显示控制台 或按关联的键绑定.你会看到控制台的最后一行是这样的:

生成语法总结

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

<块引用>

3. 是否有任何编译或刷新步骤，或者一切都会自动重新加载?

如这里所见，每次修改语法定义时，都会重新编译文件并缓存结果.所以没有编译步骤(除了保存)，你不需要做任何事情来刷新任何东西.

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

现在关闭文件并重新打开它；一个快捷方式是使用 File >打开最近的 >重新打开关闭的文件或其关联的键绑定.

请注意，现在重新打开文件后，有几处更改.首先，窗口右下角的语法名称显示 Sample(或任何你在上面命名的 sublime-syntax 文件).另一方面，文件的内容现在以语法高亮显示.

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

//这是一行注释如果 (x == 2)y = 1别的z = 1

<块引用>

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

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

这里的语法是自动使用的，但是如果您检查 View >Syntax 或单击窗口右下方的当前语法名称，您的语法将出现在那里.同样，现在命令面板中有一个名为 Set Syntax: Sample(或其他)的条目.

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

# 见 http://www.sublimetext.com/docs/3/syntax.html文件扩展名:- 欧共体范围:source.example-c

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

现在切换到 sample.ec 文件，将光标放在缓冲区中的某个位置并使用 Tools >开发人员显示范围名称或按相关键.

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

<块引用>

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

正如这里所见，没有范围文件"这样的东西；sublime-syntax 文件直接将范围指定为 语法的一部分规则，因此它是您创建语法所需的唯一文件.它可能看起来像一个文件名，但它不是一个.

语法中的语法匹配规则中应用的范围需要与您的配色方案中的范围一致才能突出显示语法；这就是为什么你应该使用 作用域命名规则来使用一组通用的作用域所有语法共享，除非您还计划制定配色方案使用您的语法，但除非您使用推荐的范围，否则您的语法不适用于其他配色方案，并且您的配色方案也不适用于其他语法.

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

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

除了查看现有的语法文件以了解它们是如何做的，您还可以在 崇高论坛.

I'm struggling to find out how to create a new syntax highlighting in Sublime Text 3 using the new .sublime-syntax style definition (most previous answers relate to old ways of doing it).

As of Sublime Text Build 3084, a new syntax definition format has been added, with the .sublime-syntax extension.

I can find the:

• syntax rules
• scope naming rules
• colour scheme rules

But I can't find the most basic piece of information detailing how these tie together!

I'm not trying to create a theme, or tweaking an existing syntax definition. I just want to create syntax highlighting to files with an extension I plan on using for my own purposes.

1. In the syntax definition I have to specify a scope (e.g. scope: source.c) but where does that scope file live? Or rather, where do I create my scope file, and how do I name it, so that it loads?
2. How do I know that my syntax file, and the scope file it uses, are loaded and applied successfully?
3. Are there any compile or refresh steps, or does everything automatically reload?

Thanks.

解决方案

A full discussion of how to create a custom syntax is well outside the bounds of something as simple as a Stack Overflow answer. Also I think you're making your problem more complicated than it actually is (although creating a syntax is pretty complicated in general).

In order to walk you through the steps that you would take to create a custom syntax, here's an example.

To start with, create a file with the following contents and save it somewhere as sample.ec, and leave the file open:

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

You'll notice that the syntax for this file is set to Plain Text (see the status line in the lower right), which is the default syntax for files that are unknown to Sublime.

Now, select Tools > Developer > New Syntax... from the menu. A buffer with the following will appear. Use File > Save to save the file; the location will default to your User package. The name you give it is not important, but make sure that the extension is sublime-syntax. In my example I'm calling my file 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

Now open the Sublime Console with View > Show Console or press the associated key binding. You'll see that the last line in the console is this:

generating syntax summary

Leaving the console open, click in the syntax file and perform another save operation again without changing anything. The same line appears in the console again.

3. Are there any compile or refresh steps, or does everything automatically reload?

As seen here, every time you modify the syntax definition, the file is recompiled and the results are cached. So there are no compile steps (other than saving) and nothing you need to do in order to refresh anything.

Now lets turn our attention back to the sample file. It's still open, and the syntax still says that it's Plain Text.

Now close the file and re-open it again; a shortcut for this is to use File > Open Recent > Reopen Closed File or it's associated key binding.

Notice that now that the file is re-opened, there are several changes. Firstly, the syntax name in the bottom right side of the window says Sample (or whatever you named your sublime-syntax file above). For another, the contents of the file are now syntax highlighted.

The colors you see are dependent on the color scheme you use, but an example might look like this:

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

2. How do I know that my syntax file, and the scope file it uses, are loaded and applied successfully?

You can see that the syntax file was compiled by the lack of an error message when you save your changes, and you can tell that it's applied by trying to use the syntax.

Here the syntax is being used automatically, but you'll find that if you check View > Syntax in the menu or click the current syntax name in the bottom right of the window, your syntax will appear there. Similarly there is now an entry in the command palette named Set Syntax: Sample (or whatever).

That leads us into your last question. If you go back to your sublime-syntax file, you'll see this at the top:

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

The first thing to note is that file_extensions includes ec, and our sample file is called sample.ec; thus this syntax applies to it automatically due to it's name.

Now switch into the sample.ec file, place the cursor somewhere in the buffer and use Tools > Developer > Show Scope Name or press the associated key.

The content of the popup that appears will vary depending on where in the file the cursor is located, but the common point is that the scope that appears always starts with source.example-c.

1. In the syntax definition I have to specify a scope (e.g. scope: source.c) but where does that scope file live? Or rather, where do I create my scope file, and how do I name it, so that it loads?

As seen here, there is no such thing as a "scope file"; the sublime-syntax file directly specifies the scope as part of the syntax rules, so it's the only file that you need to create in order to create a syntax. It may look like a filename, but it is not one.

The scopes that are applied in the syntax matching rules in the syntax need to coincide with the scopes in your color scheme in order to be syntax highlighted; that's why you should use the scope naming rules to use the common set of scopes that all syntaxes share unless you're also planning to make a color scheme to go along with your syntax, but unless you use the recommended scopes, your syntax won't work well with other color schemes and your color scheme won't work well for other syntaxes.

From this starting point you can modify the sublime-syntax file here in order to make it highlight files the way you want. That would include changing the base scope at the top, applying an appropriate extension, and then including all of the rules that match your language.

As mentioned above, creating the actual rules to match your file is the most complicated part of creating a syntax unless your file format is very simplistic. It's outside the scope of something that could be conveyed in a Stack Overflow answer, but the official documentation linked above gives you some information on it.

Apart from looking at existing syntax files to see how they're doing what they do, you can also ask more directed questions on the Sublime forum.

这篇关于Sublime Text 3 中的自定义语法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！