Documentation TOP Selectors

Syntax definitions in Sublime Text use of scope names to provide metadata about tokens. 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. Tokens may have one or more scope names associated with them. Multiple scope names are associated with a token in an ordered manner.

This document covers selectors, which are the means to match scope names. Color schemes, key bindings, the API and even some settings all deal with selectors in one way or another. For information about standardized scope names, please see the Scope Naming documentation.

Basic Matching

A basic selector specifies one or more scope names, and is matched against a token‘s scope names starting with the left-most scope. For a selector to match a token‘s scope name, all of its labels must be present in the same order.

Scope Name Selector Matches
keyword.control.php keyword yes
keyword.control.php keyword.control yes
keyword.control.php control no, control != keyword
keyword.control.php keyword.cont no, cont != control
keyword.control.php keyword.control.php.embedded no, embedded could not be matched

When a selector has multiple scope names, each must match one of the token‘s scope names, in order.

Scope Name Selector Matches
source.php meta.block.php keyword.control.php keyword yes
source.php meta.block.php keyword.control.php meta keyword yes
source.php meta.block.php keyword.control.php keyword meta no, meta could not be matched after keyword

Child Operator

Using > a selector can signify that the next scope name must follow immediately after the previous.

Scope Name Selector Matches
source.php meta.block.php keyword.control.php source > keyword no
source.php meta.block.php keyword.control.php meta.block > keyword yes
source.php meta.block.php keyword.control.php source.php > > keyword.control yes

Logical Operators

In addition to matching scope names based of label prefix matches, selectors may also specify logical operators.

Logical OR

The logical OR operator is | or ,. If either the selector to the right or left of the operator is matched, the expression will be a match.

Scope Name Selector Matches
source.php meta.block.php text meta
source.php text, meta no

Logical AND

The logical AND operator is &. It will require the selector to the right and left of the operator are both matched for the expression to be a match. This is different than a space between selectors, since that denoted hierarchy.

Scope Name Selector Matches
source.php meta.block.php keyword.control.php keyword & meta yes
source.php meta.block.php keyword & meta no

Logical NOT

The logical NOT operator is -. It will require the selector to the right to not match for the expression to be a match.

Scope Name Selector Matches
source.php meta.block.php source - keyword yes
source.php meta.block.php keyword.control.php source - keyword no

Grouping

When working with logical operators, parentheses may be used to group selectors.

Scope Name Selector Matches
source.php meta.block.php source - (keyword storage)
source.php meta.block.php (source - source.php) text

Order of Operations

Operators have the following precedence:

  • () Grouping
  • - Logical NOT
  • & Logical AND
  • | Logical OR
  • , Logical OR

Otherwise they are ordered left-to-right. So the following are equivalent:

a , b & -c | d , e

(a , ((b & (- c)) | d)) , e

Introducing our Git client Documentation TOP Selectors - 图1 Sublime Merge Documentation TOP Selectors - 图2