范围命名

Sublime Text中的语法定义和颜色方案通过使用范围名称进行交互。范围是虚线字符串,从最小到最特定。例如,if在PHP关键字可通过的范围名称来指定keyword.control.php。

Sublime Text支持TextMate语言语法,并从各种开源包继承其默认语法。该TextMate的语言语法的文档提供了一组基本已经由社区在慢慢扩大和改变的范围名称。

这是一个活动文档,试图记录在语法定义和颜色方案中使用范围名称的最佳实践。所有的Sublime Text默认包都努力遵守这些建议。

语法定义中的用法

下面介绍的范围是在创建语法定义时使用的推荐范围名称的基本集合。

在本文档中,从点范围名称的末尾省略语法名称。当编写语法时,除非另有说明,语法名称应为点名称的最后一段。例如,在Ruby中控制关键字会keyword.control.ruby,而在Python这将是keyword.control.python。

这是一个持续的过程,以改进和扩展Sublime Text附带的默认语法。截至2016年年中,以下语法最近已重新工作,可能用作参考:

顶级作用域索引

以下顶级范围列表按字母顺序排序。建议在写或修改语法之前至少读一遍整个列表。

comment.

单行和多行注释应分别使用:

用作文档的多行注释(如Javadoc或PhpDoc)应使用:

即划定一个评论,如符号//或/*,应另外使用:

具有表示一段代码的特殊语法的注释应仅在文本上使用以下范围。这将使其显示在符号列表中。

constant.

数字文字(包括整数,浮点数等)应使用以下值之一:

构建到语言中的常量(例如布尔值和空值)应使用:

字符转义字符串中,如\n和\x20,应使用:

格式化的占位符,如那些用于sprintf(),例如%s,应使用:

其他特定于语言的常量值(例如Ruby中的符号)应该使用:

entity.

实体范围通常分配给代码和标记中的数据结构,类型和其他唯一可识别的结构的名称。值得注意的例外是entity.name.tag和entity.other.attribute-name,这是在HTML和XML标记使用。

数据结构的名称将使用下列范围之一,还是一个新的子范围entity.name-这个名单并不详尽。为了提供丰富的语义信息,请使用给定语言结构的特定术语。

避免entity.name.type.class和entity.name.type.struct下窝不必要的范围标签type。

forward-decl以上的变体在诸如C和C ++的语言中使用。这样的范围可以用于从符号列表和索引中排除标识符。

作为继承类或实现的接口/ trait列出的类,接口和trait名称应该使用:

函数名称接收以下范围之一。这些包括在符号列表和索引中。

命名空间,包和模块使用以下范围。在一种语言中通常没有多种类型的这样的结构,因此这个范围应该足够了。

常数应该使用以下范围或variable.other.constant,根据语言的语义。此作用域通常包含在符号列表和索引中。

goto样结构的标签应使用:

标记语言(例如Markdown和Textile)中的标题名称应使用:

HTML和XML标签应使用以下范围。这是唯一的entity.name应用到重复构建体的范围。

HTML,CSS和XML对标记属性名称使用以下命令:

invalid.

在特定上下文中非法的元素应使用以下范围。过度使用这可能会导致用户在编辑代码时不愉快的突出显示。

不推荐使用的元素应使用以下作用域。这应该很少使用,因为用户可能正在使用较旧版本的语言。

keyword.

控制关键字的例子包括if,try,end和while。有些语法喜欢标记if,并else与conditional变体。所述import变体通常在适当的情况下使用。

包含标点,如关键字@在CSS中的符号,下面的范围添加到符号:

所有剩余的非运营商的关键字属于以下other变种:

运营商是典型的标志,所以这个词keyword似乎有点矛盾。具体变体有时基于算子的类型来引用。

当操作者是一个字,例如and,or或者not,下列变体被用于:

markup.

标记范围用于内容,而不是代码。这包括Markdown和Textile等语法。

部分标题应该使用:

列表应使用以下列表之一:

基本文本样式应使用以下选项之一:

插入和删除内容,如与diff输出,应该使用:

链接应该使用:

块引用和其他引用样式应使用:

通常用于代码的内联和块字面引用应该使用:

其他标记,包括脚注和表格等结构,应该使用:

meta.

元范围用于扩展代码或标记的更大部分,通常包含多个更具体的范围。这些不是由颜色方案样式化,而是由首选项和插件使用。

应使用以下范围之一来限定数据结构的完整内容。类似的entity.name,他们应该每语言来提供丰富的语义信息定制。它们应包括所有元素,例如名称,继承详细信息和正文。

函数的整个范围应由以下范围之一覆盖。每个变体应该应用于特定部分,而不是堆叠。例如,meta.function.php meta.function.parameters.php应该不会发生,而是在范围应之间切换meta.function.php,然后meta.function.parameters.php再换meta.function.php。

命名空间,模块或包的全部应使用:

C语言中的预处理器语句应该使用:

完整的标识符(包括命名空间名称)应使用以下范围。这种标识符是变量,函数和类名的完全限定形式。例如,在C ++中的路径可能看起来像myns::myclass,而在PHP它会出现如\MyNS\MyClass。

函数名称(包括完整路径)和所有参数应接收以下作用域。函数或方法的名称应该是variable.function,除非该功能与范围support.function。

代码段由大括号界定应使用下列之一meta范围的基础上,适当的语义。在{和}字符应另外使用punctuation范围。

代码段括号划定应使用下列之一meta范围的基础上,适当的语义。在(和)字符应另外使用punctuation范围。

由方括号描述的代码段应使用以下范围。在[和]字符应另外使用punctuation范围。

通用数据类型结构应使用以下作用域。这表示开始和结束,如任何符号<和>,应另外使用punctuation范围。

HTML和XML标记(包括标点符号,名称和属性)应使用以下内容:

标记语言中的段落使用:

punctuation.

以下范围是未嵌入其他范围内的标点符号范围。例如,string.部分包括约作用域的字符串标点文档。

分隔符(例如逗号和冒号)应使用:

分号或其他语句终止符应使用:

行连续字符,例如在Python和R中,应该使用:

成员访问,范围解析或类似结构应使用以下范围。对于Python或JavaScript,这将是.。在PHP这将适用于->和::。在C ++中,这将应用于所有三个。

source.

以下范围的语言特定变体通常应用于整个源代码文件:

storage.

类型和定义/声明关键字应使用以下范围。例子包括int,bool,char,func,function,class和def。根据语言和语义,const可能是这种或storage.modifier。

影响变量,函数或数据结构存储的关键字应使用以下范围。例子包括static,inline,const,public和private。

string.

基本字符串使用以下范围之一,基于使用的引号类型:

所使用非常规的报价,如字符串<,并>用C的进口,应该使用:

字符串开头和结尾的标点应该使用:

无引号字符串(如Shell和批处理文件)应使用:

正则表达式字面量应该使用:

support.

基本框架提供的元素应使用以下范围之一。示例包括Objective-C中的Cocoa,或JavaScript中的浏览器/节点。

虽然也用于基本框架,但许多语法将这些应用于未识别的类和类型,有效地限定所有用户结构。

text.

编程语言使用source.作为基地的范围,而内容的用途text.。其中一个最大的不同是,许多插件等动态功能是禁用范围内的事实text.范围。markup.范围通常在文本中使用。

HTML应该使用以下范围。对于此范围内的变体比其他领域不同,在该变体后总是添加.html,如text.html.basic或text.html.markdown。

XML应该使用:

variable.

通用变量应使用以下范围。一些语言使用readwrite变体用于与对比度constant下面讨论的变体。

作为变量名称一部分的符号,应另外应用于以下范围。例如,$在PHP和壳牌。

不可变的变量,通常是通过const修改,会收到以下范围。根据不同的语言和语义,entity.name.constant可能是一个更好的选择。

由指定的语言保留的变量名,如this,self,super等应使用:

函数或方法的参数应使用以下范围。这也可以用于其他类似参数的变量,例如Go中的接收器或命名的返回值。

类或其他数据结构的字段,属性,成员和属性应使用:

函数和方法名称应该使用以下范围,但仅在调用它们时。定义时,他们应该使用entity.name.function。

颜色方案中的用法

一般来说,当在颜色方案中将颜色和样式应用于范围时,应首先对选择器的最通用形式进行样式化。利用上一节中概述的范围的高质量语法应为最终用户带来良好的用户体验。

最小范围覆盖

以下是要突出显示的建议最小范围集。添加额外的可能会导致略微改善的体验,但是太具体将导致通常只看起来好的一个或两个语法的配色方案。

meta. 颜色

当造型范围,抗拒的冲动,直接的风格meta范围。它们主要用于提供首选项和插件的上下文信息。

entity.name. 颜色

历史上,许多颜色方案已经提供了一种颜色entity.name.function和entity.name.type,并经常有不同的颜色entity.name.tag。这使得新的entity.name.*领域未突出。

配色方案应该代替指定一个颜色entity.name将被应用到类,类型,结构,接口和许多其他数据结构。这种颜色可以重写为两个范围entity.name.tag和entity.name.section,被用于不同类型构建体。