Sublime Text: scope selector operators

Question

Of the 243 colour schemes currently registered on TmThemeEditor, I noticed that almost none of them use scope selector operators.

The operators are very useful for situations like this:

(text.html | text.xml) & (meta.tag entity)

I think the reason they're so rarely used by colour scheme designers is that they're poorly documented. They're not mentioned at all in the official docs for ST2 or ST3, or in the unofficial docs for colour schemes. The unofficial docs for syntax definitions mention scope selectors, but not the operators.

Where can I find documentation of the scope selector operators supported by Sublime Text?

Answer 1

The operators, in order of precedence (highest first), are:

( )  Grouping

&  Intersection

-  Asymmetric Difference (Relative Complement)

|  Union

,  Comma

The file format of colour scheme files (.tmTheme) is inherited from TextMate.

Here are some relevant links and quotes from TextMate's documentation, regarding scope selector operators:

• Manual: Scope Selectors
  • Excluding Elements
    "we can subtract scope selectors to get the (asymmetric) difference using the minus operator."
  • Comma
    "When we want something to match several distinct scopes, we can group scope selectors with the comma operator. For example to match both strings and comments the scope selector would be: string, comment."
• Introduction to scopes
  "it's also possible to AND, OR, and subtract scope selectors, e.g.: (a | b) & c - d would select the scope which is not matched by d, and matched by both c, and a or b."
• Beta 17 notes: Scope selectors
  "it's possible to perform boolean operations on scope selectors and take the asymmetric difference between two scope selectors. So in the example above we want our custom action on # to expand in source.ruby string but we don't want it for string source (embedded code in strings). For this we can now set the scope to: (source.ruby string) - (string source). I added the parentheses for clarity, they are not necessary (since - has lowest precedence)."

Allan Odgaard (the creator of TextMate) provided some very helpful responses to questions about scope selector operators on the TextMate mailing list. The thread is archived here, and the original messages are here: 1, 2, 3, 4, 5, 6. This response is particularly helpful:

scopes are matched literally (e.g. string). These can form a “descendent selector” e.g. source.ruby string, and for descendent selectors one can take the union (| or ,), the intersection (&), or the asymmetric difference (-).

one can also group with parenthesis. The reason though that both , and | can be used for union is that , was introduced long before the other operators (mimics CSS syntax), so when & was added, I felt that there should be | and | has higher precedence than , it is the operator with lowest precedence, so e.g.:

a - b | c & d, e - f | g & h ⇔ (a - b | c & d), (e - f | g & h)

TextMate supports other operators which are not supported by Sublime Text, including *, ^, >, $, L:, R:, B:. These are documented here: 1, 2, 3, 4.