Scope Naming

Syntax definitions and color schemes in Sublime Text interact through the use of scope names. Scopes are dotted strings, specified from least-to-most specific. For example, the if keyword in PHP could be specified via the scope name keyword.control.php.

Sublime Text supports TextMate language grammars, and inherited its default syntaxes from various open-source bundles. The TextMate language grammar documentation provided a base set of scope names that have been slowly expanded and changed by the community.

This is a living document that attempts to document best practices for using scope names in syntax definitions and color schemes. All of the Sublime Text default packages strive to adhere to these recommendations.

Usage in Syntax Definitions

The scopes documented below are a recommended base set of scope names to use when creating a syntax definition.

In this documentation, the syntax name is omitted from the end of the dotted scope name. When writing a syntax, unless otherwise noted, the syntax name should be the final segment of a dotted name. For example, a control keyword in Ruby would be keyword.control.ruby, whereas in Python it would be keyword.control.python.

It is an on-going process to improve and expand upon the default syntaxes that are shipped with Sublime Text. As of mid-2016, the following syntaxes have been recently re-worked, and may be used as a reference:

Top-Level Scope Index

The following, top-level, list of scopes is sorted alphabetically. It is recommended to read through the entire list at least once before writing or modifying a syntax.

comment.

Single and multi-line comments should use, respectively:

Multi-line comments used as documentation, such as Javadoc or PhpDoc, should use:

Symbols that delineate a comment, e.g. // or /*, should additionally use:

Comments with special syntax that denote a section of code, should use the following scope on the text only. This will cause it to be shown in the symbol list.

constant.

Numeric literals, including integers, floats, etc. should use one of:

Constants that are built into the language, such as booleans and null values, should use:

Character escapes in strings, e.g. \n and \x20, should use:

Formatting placeholders, such as those used for sprintf(), e.g. %s, should use:

Other language-specific constant values, such as symbols in Ruby, should use:

entity.

The entity scopes are generally assigned to the names of data structures, types and other uniquely-identifiable constructs in code and markup. The notable exceptions are entity.name.tag and entity.other.attribute-name, which are used in HTML and XML tags.

The names of data structures will use one of the following scopes, or a new sub-scope of entity.name – this list is not exhaustive. To provide rich semantic information, use the specific terminology for a given language construct.

Avoid entity.name.type.class and entity.name.type.struct which unnecessarily nest scope labels under type.

forward-decl variants of the above are used in languages such as C and C++. Such scopes can be used to exclude identifiers from the symbol list and indexing.

Class, interface and trait names listed as an inherited class or implemented interface/trait should use:

Function names receive one of the following scopes. These are included in the symbol list and index.

Namespaces, packages and modules use the following scope. There are usually not multiple types of such constructs in a language, so this scope should suffice.

Constants should use the following scope or variable.other.constant, depending on the language semantics. This scope is often included in the symbol list and index.

Labels for goto-like constructs should use:

Heading names in markup languages, such as Markdown and Textile, should use:

HTML and XML tags should use the following scope. This is the only entity.name scope that is applied to repeated constructs.

HTML, CSS and XML use the following for tag attribute names:

invalid.

Elements that are illegal in a specific context should use the following scope. Overuse of this will likely lead to unpleasant highlighting for users as they edit code.

Deprecated elements should be scoped using the following scope. This should be very rarely used, as users may be working with older versions of a language.

keyword.

Control keywords examples include if, try, end and while. Some syntaxes prefer to mark if and else with the conditional variant. The import variant is often used in appropriate situations.

Keywords that contain punctuation, such as the @ symbol in CSS, add the following scope to the symbols:

All remaining non-operator keywords fall under the other variant:

Operators are typically symbols, so the term keyword can seem somewhat contradictory. Specific variants are sometimes referenced based on the type of operator.

When the operator is a word, such as and, or or not, the following variant is used:

markup.

Markup scopes are used for content, as opposed to code. This includes syntaxes such as Markdown and Textile.

Section headings should use:

Lists should use one of:

Basic text styling should use one of:

Inserted and deleted content, such as with diff output, should use:

Links should use:

Blockquotes and other quote styles should use:

Inline and block literal quoting, often used for code, should use:

Other markup, including constructs such as footnotes and tables, should use:

meta.

Meta scopes are used to scope larger sections of code or markup, generally containing multiple, more specific scopes. These are not intended to be styled by a color scheme, but used by preferences and plugins.

The complete contents of data structures should be scoped using one of the following scopes. Similar to entity.name, they should be customized per language to provide rich semantic information. They should include all elements, such as the name, inheritance details and body.

The entire scope of a function should be covered by one of the following scopes. Each variant should be applied to a specific part, and not stacked. For example, meta.function.php meta.function.parameters.php should never occur, but instead the scopes should alternate between meta.function.php then meta.function.parameters.php and back to meta.function.php.

The entirety of a namespace, module or package should use:

Preprocessor statements in language such as C should use:

Complete identifiers, including namespace names, should use the following scope. Such identifiers are the fully-qualified forms of variable, function and class names. For example, in C++ a path may look like myns::myclass, whereas in PHP it would appears such as \MyNS\MyClass.

Function names, including the full path, and all parameters should receive the following scope. The name of the function or method should be variable.function, unless the function is scoped with support.function.

Sections of code delineated by curly braces should use one the following meta scopes, based on appropriate semantics. The { and } characters should additionally use the punctuation scopes.

Sections of code delineated by parentheses should use one the following meta scopes, based on appropriate semantics. The ( and ) characters should additionally use the punctuation scopes.

Sections of code delineated by square brackets should use the following scope. The [ and ] characters should additionally use the punctuation scopes.

Generic data type constructs should use the following scope. Any symbols that denote the beginning and end, such as < and >, should additionally use the punctuation scopes.

HTML and XML tags, including punctuation, names and attributes should use the following:

Paragraphs in markup languages use:

punctuation.

The following scopes are punctuation scopes that are not embedded within other scopes. For instance, the string. section includes documentation about scopes for string punctuation.

Separators such as commas and colons should use:

Semicolons or other statement terminators should use:

Line-continuation characters, such as in Python and R, should use:

Member access, scope resolution, or similar constructs should use the following scope. For Python or JavaScript this would be .. In PHP this would be applied to -> and ::. In C++, this would be applied to all three.

source.

A language-specific variant of the following scope is typically applied to the entirety of a source code file:

storage.

Types and definition/declaration keywords should use the following scope. Examples include int, bool, char, func, function, class and def. Depending on the language and semantics, const may be this or storage.modifier.

Keywords that affect the storage of a variable, function or data structure should use the following scope. Examples include static, inline, const, public and private.

string.

Basic strings use the one of the following scopes, based on the type of quotes used:

Strings that used unconventional quotes, such as < and > with C imports, should use:

Punctuation at the beginning and end of strings should use:

Unquoted strings, such as in Shell and Batch File, should use:

Regular expression literals should use:

support.

Elements provided by a base framework should use one of the following scopes. Examples include Cocoa within Objective-C, or the browser/Node within JavaScript.

While also used for base frameworks, many syntaxes apply these to scopes unrecognized classes and types, effectively scoping all user constructs.

text.

Programming languages use source. as their base scope, whereas content uses text.. One of the biggest differences is the fact that many plugins and other dynamic functionality is disabled within text. scopes. markup. scopes are typically used within text.

HTML should use the following scope. Variants for this scope are different than other scopes, in that the variant is always added after the .html, such as text.html.basic or text.html.markdown.

XML should use:

variable.

A generic variable should use the following scope. Some languages use the readwrite variant for contrast with the constant variant discussed below.

Symbols that are part of the variable name, should additionally be applied the following scope. For example, the $ in PHP and Shell.

Immutable variables, often via a const modifier, should receive the following scope. Depending on the language and semantics, entity.name.constant may be a better choice.

Reserved variable names that are specified by the language, such as this, self, super, etc. should use:

Parameters to a function or methods should use the following scope. This may also be used for other parameter-like variables, such as receivers or named return values in Go.

Fields, properties, members and attributes of a class or other data structure should use:

Function and method names should be scoped using the following, but only when they are being invoked. When defined, they should use entity.name.function.

Usage in Color Schemes

In general, when applying colors and styles to scopes in a color scheme, the most general form of a selector should be styled first. High-quality syntaxes utilizing the scopes outlined in the previous section should result is good user experience for end users.

Minimal Scope Coverage

The following is a recommended minimal set of scopes to highlight. Adding extra may result in a slightly improved experience, however being too specific will result in a color scheme that often only looks good for one or two syntaxes.

meta. Colors

When styling scopes, resist the urge to directly style meta scopes. They are primarily intended to provide contextual information for preferences and plugins.

entity.name. Colors

Historically, many color schemes have provided one color for entity.name.function and entity.name.type, and often a different color for entity.name.tag. This leaves new entity.name.* scopes un-highlighted.

Color schemes should instead specify a color for entity.name that will be applied to classes, types, structs, interfaces and many other data structures. This color can be overridden for the two scopes entity.name.tag and entity.name.section, that are used for different types of constructs.