Syntax Definitions¶
Warning
Development of Sublime Text has moved on to version 3.
As a result,
this branch for Sublime Text 2
will not be updated any more.
Please select the latest
branch
in the panel on the bottom left
and consider updating Sublime Text.
Warning
This topic is a draft and may contain wrong information.
Compatibility with Textmate¶
Generally, Sublime Text syntax definitions are compatible with Textmate language files.
File Format¶
Textmate syntax definitions are Plist files with the tmLanguage
extension.
However, for convenience in this reference document, YAML is shown instead.
Additionally, Sublime Text also understands the hidden-tmLanguage
extension,
which can not be selected by the user but only by set by plugins. “Find in
Files” makes use of this. The downsite is that these can not be included by
import statements in other language definitions.
---
name: Sublime Snippet (Raw)
scopeName: source.ssraw
fileTypes: [ssraw]
uuid: 0da65be4-5aac-4b6f-8071-1aadb970b8d9
patterns:
- comment: Tab stops like $1, $2...
name: keyword.other.ssraw
match: \$\d+
- comment: Variables like $PARAM1, $TM_SELECTION...
name: keyword.other.ssraw
match: \$([A-Za-z][A-Za-z0-9_]+)
captures:
'1': {name: constant.numeric.ssraw}
- name: variable.complex.ssraw
begin: '(\$)(\{)([0-9]+):'
beginCaptures:
'1': {name: keyword.other.ssraw}
'3': {name: constant.numeric.ssraw}
end: \}
patterns:
- include: $self
- name: support.other.ssraw
match: .
- name: constant.character.escape.ssraw
match: \\[$<>]
- name: invalid.illegal.ssraw
match: '[$<>]'
...
name
- Descriptive name for the syntax definition. Shows up in the syntax definition dropdown menu located in the bottom right of the Sublime Text interface. It’s usually the name of the programming language or equivalent.
scopeName
- Name of the top-level scope for this syntax definition. Either
source.<lang>
ortext.<lang>
. Usesource
for programming languages andtext
for markup and everything else. fileTypes
- This is a list of file extensions (without the leading dot). When opening files of these types, Sublime Text will automatically activate this syntax definition for them. Optional.
uuid
- Unique indentifier for this syntax definition. Currently ignored.
patterns
- Array of patterns to match against the buffer’s text.
repository
- Array of patterns abstracted out from the
patterns
element. Useful to keep the syntax definition tidy as well as for specialized uses like recursive patterns or re-using the same pattern. Optional.
The Patterns Array¶
Elements contained in the patterns
array.
match
Contains the following elements:
match
Pattern to search for. name
Optional. Scope name to be assigned to matches of match
.comment
Optional. For information only. captures
Optional. Refinement of match
. See below.In turn,
captures
can contain n of the following pairs of elements (note that0
refers to the whole match):0..n
Name of the group referenced. Must be a string. name
Scope to be assigned to the group. Examples:
# Simple - comment: Sequences like \$, \> and \< name: constant.character.escape.ssraw match: \\[$<>] # With captures - comment: Tab stops like $1, $2... name: keyword.other.ssraw match: \$(\d+) captures: '1': {name: constant.numeric.ssraw}
include
Includes items in the repository, other syntax definitions or the current one.
References:
$self The current syntax definition. #itemName itemName in the repository. source.js External syntax definitions. Examples:
# Requires presence of DoubleQuotedStrings element in the repository. - include: '#DoubleQuotedStrings' # Recursively includes the complete current syntax definition. - include: $self # Includes and external syntax definition. - include: source.js
begin..end
Defines a scope potentially spanning multiple lines
Contains the following elements (only
begin
andend
are required):name
Scope name for the content including the markers. contentName
Scope name for the content excluding the markers. begin
The start marker pattern. end
The end marker pattern. name
Scope name for the whole region. beginCaptures
captures
forbegin
. Seecaptures
.endCaptures
captures
forend
. Seecaptures
.patterns
Array of patterns to be matched against the content. Example:
name: variable.complex.ssraw begin: '(\$)(\{)([0-9]+):' beginCaptures: '1': {name: keyword.other.ssraw} '3': {name: constant.numeric.ssraw} end: \} patterns: - include: $self - name: support.other.ssraw match: .
Repository¶
Can be referenced from patterns
or from itself in an include
element.
See include
for more information.
The repository can contain the following elements:
repository:
# Simple elements
elementName:
match: some regexp
name: some.scope.somelang
# Complex elements
otherElementName:
patterns:
- match: some regexp
name: some.scope.somelang
- match: other regexp
name: some.other.scope.somelang
Examples:
repository:
numericConstant:
patterns:
- name: constant.numeric.double.powershell
match: \d*(?<!\.)(\.)\d+(d)?(mb|kb|gb)?
captures:
'1': {name: support.constant.powershell}
'2': {name: support.constant.powershell}
'3': {name: keyword.other.powershell}
- name: constant.numeric.powershell
match: (?<!\w)\d+(d)?(mb|kb|gb)?(?!\w)
captures:
'1': {name: support.constant.powershell}
'2': {name: keyword.other.powershell}
scriptblock:
name: meta.scriptblock.powershell
begin: \{
end: \}
patterns:
- include: $self
Escape Sequences¶
Be sure to escape JSON/XML sequences as needed.
For YAML, additionally make sure that you didn’t unintentionally start a new scalar by not using quotes for your strings. Examples that won’t work as expected:
match: [aeiou]
include: #this-is-actually-a-comment
match: "#"\w+""