Syntax Definitions¶
Warning
This topic is a draft and may contain wrong information.
Compatibility with Textmate¶
Sublime Text syntax definitions are generally compatible with Textmate language files.
File Format¶
Syntax definitions are files in the Plist format with the tmLanguage
extension.
In this reference files, however, JSON is used instead and converted into Plist.
{ "name": "Sublime Snippet (Raw)",
"scopeName": "source.ssraw",
"fileTypes": ["ssraw"],
"patterns": [
{ "match": "\\$(\\d+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Tab stops like $1, $2..."
},
{ "match": "\\$([A-Za-z][A-Za-z0-9_]+)",
"name": "keyword.ssraw",
"captures": {
"1": { "name": "constant.numeric.ssraw" }
},
"comment": "Variables like $PARAM1, $TM_SELECTION..."
},
{ "name": "variable.complex.ssraw",
"begin": "(\\$)(\\{)([0-9]+):",
"beginCaptures": {
"1": { "name": "keyword.control.ssraw" },
"3": { "name": "constant.numeric.ssraw" }
},
"patterns": [
{ "include": "$self" },
{ "name": "string.ssraw",
"match": "."
}
],
"end": "\\}"
},
{ "name": "constant.character.escape.ssraw",
"match": "\\\\(\\$|\\>|\\<)"
},
{ "name": "invalid.ssraw",
"match": "(\\$|\\>|\\<)"
}
],
"uuid": "ca03e751-04ef-4330-9a6b-9b99aae1c418"
}
name
- Descriptive name for the syntax definition. Shows up in the syntax definition dropdown menu located in the bottom right of 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 everything else. fileTypes
- And array of file type extensions for which this syntax should be automatically activated. Include the extensions without the leading dot.
uuid
- Unique indentifier for this syntax definition. Currently ignored.
foldingStartMarker
- Currently ignored. Used for code folding.
foldingStopMarker
- Currently ignored. Used for code folding.
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. Optional.
The Patterns Array¶
Elements contained in the patterns
array.
match
Contains the following elements:
match
Pattern to search for. name
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:0..n
Name of the group referenced. name
Scope to be assigned to the group. Examples:
// Simple { "name": "constant.character.escape.ssraw", "match": "\\\\(\\$|\\>|\\<)" "comment". "Sequences like \$, \> and \<" } // With captures { "match": "\\$(\\d+)", "name": "keyword.ssraw", "captures": { "1": { "name": "constant.numeric.ssraw" } }, "comment": "Tab stops like $1, $2..." }
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 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:
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
patterns
to be matched against the content.contentName
Scope name for the content excluding the markers. Example:
{ "name": "variable.complex.ssraw", "begin": "(\\$)(\\{)([0-9]+):", "beginCaptures": { "1": { "name": "keyword.control.ssraw" }, "3": { "name": "constant.numeric.ssraw" } }, "patterns": [ { "include": "$self" }, { "name": "string.ssraw", "match": "." } ], "end": "\\}" }
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:
Simple elements:
"elementName": { "match": "some regexp", "name": "some.scope.somelang" }Complex elements:
"elementName": { "patterns": [ { "match": "some regexp", "name": "some.scope.somelang" }, { "match": "other regexp", "name": "some.other.scope.somelang" } ] }
Examples:
"repository": {
"numericConstant": {
"patterns": [
{ "match": "\\d*(?<!\\.)(\\.)\\d+(d)?(mb|kb|gb)?",
"name": "constant.numeric.double.powershell",
"captures": {
"1": { "name": "support.constant.powershell" },
"2": { "name": "support.constant.powershell" },
"3": { "name": "keyword.other.powershell" }
}
},
{ "match": "(?<!\\w)\\d+(d)?(mb|kb|gb)?(?!\\w)",
"name": "constant.numeric.powershell",
"captures": {
"1": { "name": "support.constant.powershell" },
"2": { "name": "keyword.other.powershell" }
}
}
]
},
"scriptblock": {
"begin": "\\{",
"end": "\\}",
"name": "meta.scriptblock.powershell",
"patterns": [
{ "include": "$self" }
]
},
}
Escape Sequences¶
Be sure to escape JSON/XML sequences as needed.