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
.
Example Syntaxes
It is an on-going process to improve and expand upon the default syntaxes that are shipped with Sublime Text. As of early-2019, the following syntaxes have been recently re-worked, and may be used as a reference:
Alphabetical Reference
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:
-
comment.line
-
comment.block
Multi-line comments used as documentation, such as Javadoc or PhpDoc, should use:
-
comment.block.documentation
Symbols that delineate a comment, e.g. //
or /*
, should additionally use:
-
punctuation.definition.comment
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.
-
meta.toc-list
constant.
Numeric literals, including integers, floats, etc. should use one of:
-
constant.numeric
-
constant.numeric.integer
-
constant.numeric.integer.binary
-
constant.numeric.integer.octal
-
constant.numeric.integer.decimal
-
constant.numeric.integer.hexadecimal
-
constant.numeric.integer.other
-
constant.numeric.float
-
constant.numeric.float.binary
-
constant.numeric.float.octal
-
constant.numeric.float.decimal
-
constant.numeric.float.hexadecimal
-
constant.numeric.float.other
-
constant.numeric.complex
-
constant.numeric.complex.real
-
constant.numeric.complex.imaginary
Constants that are built into the language, such as booleans and null values, should use:
-
constant.language
Character escapes in strings, e.g. \n
and \x20
, should use:
-
constant.character.escape
Formatting placeholders, such as those used for sprintf()
, e.g. %s
, should use:
-
constant.other.placeholder
Other language-specific constant values, such as symbols in Ruby, should use:
-
constant.other
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
.
-
entity.name.class
-
entity.name.struct
-
entity.name.enum
-
entity.name.union
-
entity.name.trait
-
entity.name.interface
-
entity.name.impl
-
entity.name.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.
-
entity.name.class.forward-decl
Class, interface and trait names listed as an inherited class or implemented interface/trait should use:
-
entity.other.inherited-class
Function names receive one of the following scopes. These are included in the symbol list and index.
-
entity.name.function
-
entity.name.function.constructor
-
entity.name.function.destructor
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.
-
entity.name.namespace
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.
-
entity.name.constant
Labels for goto-like constructs should use:
-
entity.name.label
Heading names in markup languages, such as Markdown and Textile, should use:
-
entity.name.section
HTML and XML tags should use the following scope. This is the only entity.name
scope that is applied to repeated constructs.
-
entity.name.tag
HTML, CSS and XML use the following for tag attribute names:
-
entity.other.attribute-name
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.
-
invalid.illegal
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.
-
invalid.deprecated
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.
-
keyword.control
-
keyword.control.conditional
-
keyword.control.import
Keywords that contain punctuation, such as the @
symbol in CSS, add the following scope to the symbols:
-
punctuation.definition.keyword
All remaining non-operator keywords fall under the other
variant:
-
keyword.other
Operators are typically symbols, so the term keyword
can seem somewhat contradictory. Specific variants are sometimes referenced based on the type of operator.
-
keyword.operator
-
keyword.operator.assignment
-
keyword.operator.arithmetic
-
keyword.operator.bitwise
-
keyword.operator.logical
When the operator is a word, such as and
, or
or not
, the following variant is used:
-
keyword.operator.word
markup.
Markup scopes are used for content, as opposed to code. This includes syntaxes such as Markdown and Textile.
Section headings should use:
-
markup.heading
Lists should use one of:
-
markup.list.unnumbered
-
markup.list.numbered
Basic text styling should use one of:
-
markup.bold
-
markup.italic
-
markup.underline
Inserted and deleted content, such as with diff
output, should use:
-
markup.inserted
-
markup.deleted
Links should use:
-
markup.underline.link
Blockquotes and other quote styles should use:
-
markup.quote
Inline and block literal quoting, often used for code, should use:
-
markup.raw.inline
-
markup.raw.block
Other markup, including constructs such as footnotes and tables, should use:
-
markup.other
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.
-
meta.class
-
meta.struct
-
meta.enum
-
meta.union
-
meta.trait
-
meta.interface
-
meta.impl
-
meta.type
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
.
-
meta.function
-
meta.function.parameters
-
meta.function.return-type
The entirety of a namespace, module or package should use:
-
meta.namespace
Preprocessor statements in language such as C should use:
-
meta.preprocessor
Annotations, attributes and decorator statements that are used to modify the behavior or implementation of a class, method or function should use one of the following meta
scopes for each component of the annotation. That is to say, there should never be more than one meta.annotation*
scope on the stack at any given time. See variable.annotation
for scoping the identifier.
-
meta.annotation
-
meta.annotation.identifier
-
meta.annotation.parameters
-
punctuation.definition.annotation
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
.
-
meta.path
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
.
-
meta.function-call
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.
-
meta.block
-
punctuation.section.block.begin
-
punctuation.section.block.end
-
meta.braces
-
punctuation.section.braces.begin
-
punctuation.section.braces.end
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.
-
meta.group
-
punctuation.section.group.begin
-
punctuation.section.group.end
-
meta.parens
-
punctuation.section.parens.begin
-
punctuation.section.parens.end
Sections of code delineated by square brackets should use the following scope. The [
and ]
characters should additionally use the punctuation
scopes.
-
meta.brackets
-
punctuation.section.brackets.begin
-
punctuation.section.brackets.end
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.
-
meta.generic
-
punctuation.definition.generic.begin
-
punctuation.definition.generic.end
HTML and XML tags, including punctuation, names and attributes should use the following:
-
meta.tag
Paragraphs in markup languages use:
-
meta.paragraph
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:
-
punctuation.separator
Semicolons or other statement terminators should use:
-
punctuation.terminator
Line-continuation characters, such as in Python and R, should use:
-
punctuation.separator.continuation
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.
-
punctuation.accessor
source.
A language-specific variant of the following scope is typically applied to the entirety of a source code file:
-
source
storage.
Types should use the following scope. Examples include int
, bool
and char
.
-
storage.type
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
.
-
storage.modifier
Keywords for functions or methods should use the following scopes. Example keywords include func
, function
and def
. This includes storage.type
for backwards compatibility with older color schemes.
-
storage.type.function keyword.declaration.function
Keywords for classes, structs, interfaces, etc should use the following scopes – this list is not exhaustive. Example keywords include class
, struct
, impl
and typedef
. This includes storage.type
for backwards compatibility with older color schemes.
-
storage.type.class keyword.declaration.class
-
storage.type.struct keyword.declaration.struct
-
storage.type.enum keyword.declaration.enum
-
storage.type.union keyword.declaration.union
-
storage.type.trait keyword.declaration.trait
-
storage.type.interface keyword.declaration.interface
-
storage.type.impl keyword.declaration.impl
-
storage.type keyword.declaration.type
string.
Basic strings use the one of the following scopes, based on the type of quotes used:
-
string.quoted.single
-
string.quoted.double
-
string.quoted.triple
Strings that used unconventional quotes, such as <
and >
with C imports, should use:
-
string.quoted.other
The entirety of a string, along with all punctuation, prefixes, suffixes and interpolations should use:
-
meta.string
Punctuation at the beginning and end of strings should use:
-
punctuation.definition.string.begin
-
punctuation.definition.string.end
Unquoted strings, such as in Shell and Batch File, should use:
-
string.unquoted
Regular expression literals should use:
-
string.regexp
When a string contain interpolated code, such as a variable or expression, the string.*
scope should be removed using clear_scopes:
, and the following should be added to the entirety of the interpolation, including punctuation:
-
meta.interpolation
The punctuation for an interpolated expression should be:
-
punctuation.section.interpolation.begin
-
punctuation.section.interpolation.end
Between the punctuation, the interpolated expression should get:
-
source.language-suffix.embedded
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.
-
support.constant
-
support.function
-
support.module
While also used for base frameworks, many syntaxes apply these to scopes unrecognized classes and types, effectively scoping all user constructs.
-
support.type
-
support.class
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
.
-
text.html
XML should use:
-
text.xml
variable.
A generic variable should use the following scope. Some languages use the readwrite
variant for contrast with the constant
variant discussed below.
-
variable.other
-
variable.other.readwrite
Symbols that are part of the variable name, should additionally be applied the following scope. For example, the $
in PHP and Shell.
-
punctuation.definition.variable
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.
-
variable.other.constant
Reserved variable names that are specified by the language, such as this
, self
, super
, etc. should use:
-
variable.language
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.
-
variable.parameter
Fields, properties, members and attributes of a class or other data structure should use:
-
variable.other.member
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
.
-
variable.function
The final label in an identifier that is part of an annotation should use the following. For the entire identifier, the meta.path
scope should be used. The entire annotation should get meta.annotation
.
-
variable.annotation
The leading symbol used to delineate an annotation should use:
-
punctuation.definition.annotation
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.
entity.name
entity.other.inherited-class
entity.name.section
entity.name.tag
entity.other.attribute-name
variable
variable.language
variable.parameter
variable.function
constant
constant.numeric
constant.language
constant.character.escape
storage.type
storage.modifier
support
keyword
keyword.control
keyword.operator
keyword.declaration
string
comment
invalid
invalid.deprecated
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.