Sublime Syntax
Sublime Text/Merge syntax highlighting definition
| Type | object |
|---|---|
| File match |
*.sublime-syntax
|
| Schema URL | https://catalog.lintel.tools/schemas/schemastore/sublime-syntax/latest.json |
| Source | https://www.schemastore.org/sublime-syntax.json |
Validate with Lintel
npx @lintel/lintel checkJSON schema for *.sublime-syntax yaml
Properties
The default scope assigned to all text in the file
This defines the name shown for the syntax in the menu. It’s optional, and will be derived from the file name if not used.
A list of strings, defining file extensions this syntax should be used for. Extensions listed here will be shown in file dialog dropdowns on some operating systems. If a file does not have a basename, e.g. .gitignore, the entirety of the filename including the leading . should be specified.
When a file is opened without a recognized extension, the first line of the file contents will be tested against this regex, to see if the syntax should be applied.
A base syntax (or list of syntaxes) to inherit from, specified using its package path, e.g. Packages/JavaScript/JavaScript.sublime-syntax. When using multiple inheritance, parent syntaxes are processed top to bottom and must share the same base. See Inheritance for an overview of syntax inheritance.
Variables must be defined at the top level of the .sublime-syntax file, and are referenced within regxes via {{varname}}. Variables may themselves include other variables. Note that any text that doesn’t match {{[A-Za-z0-9_]+}} won’t be considered as a variable, so regexes can still include literal {{ characters, for example. https://www.sublimetext.com/docs/syntax.html#variables
Definitions
Meta patterns must be listed first in the context, before any match or include patterns. https://www.sublimetext.com/docs/syntax.html#meta-patterns
This assigns the given scope to all text within this context, including the patterns that push the context onto the stack and pop it off.
This assigns the given scope to all text within this context, including the patterns that push the context onto the stack and pop it off. But does not apply to the text that triggers the context (e.g., in the above string example, the content scope would not get applied to the quote characters).
Used to stop the current context from automatically including the prototype context.
This setting allows removing scope names from the current stack. It can be an integer, or the value true to remove all scope names. It is applied before meta_scope and meta_content_scope. This is typically only used when one syntax is embedding another.
A boolean, controlling context name conflict resolution during inheritance. If this is specified, the rules in this context will be inserted before any existing rules from a context with the same name in an ancestor syntax definition.
A boolean, controlling context name conflict resolution during inheritance. If this is specified, the rules in this context will be inserted after to any existing rules from a context with the same name in an ancestor syntax definition.
The following keys control behavior that is exclusive, and only one can be specified per match pattern: push pop set embed branch fail https://www.sublimetext.com/docs/syntax.html#match-patterns
The regex used to match against the text. YAML allows many strings to be written without quotes, which can help make the regex clearer, but it's important to understand when you need to quote the regex. If your regex includes the characters #, :, -, {, [ or > then you likely need to quote it. Regexes are only ever run against a single line of text at a time.
The scope assigned to the matched text.
A mapping of numbers to scope, assigning scopes to captured portions of the match regex.
Pops contexts off the stack. The value true will pop a single context. An integer greater than zero will pop the corresponding number of contexts. The pop key can be combined with push, set, embed and branch. When combined, the specified number of contexts will be popped off of the stack before the other action is performed. For push, embed and branch actions, the pop treats the match as if it were a lookahead, which means the match will not receive the meta_scope of the contexts that are popped.
Accepts the name of a single context to push into. While similar to push, it pops out of any number of nested contexts as soon as the escape pattern is found. This makes it an ideal tool for embedding one syntax within another.
5 nested properties
This key is required if embed is used, and is a regex used to exit from the embedded context. Any backreferences in this pattern will refer to capture groups in the match regex.
A scope assigned to all text matched after the match and before the escape. Similar in concept to meta_content_scope.
A mapping of capture groups to scope names, for the escape pattern. Use capture group 0 to apply a scope to the entire escape match.
Accepts the names of two or more contexts, which are attempted in order. If a fail action is encountered, the highlighting of the file will be restarted at the character where the branch occurred, and the next context will be attempted.
1 nested properties
This is the unique identifier for the branch and is specified when a match uses the fail action.
Accepts the name of a branch_point to rewind to and retry the next context of. If a fail action specifies a branch_point that was never pushed on the stack, or has already been popped off of the stack, it will have no effect.
Frequently it’s convenient to include the contents of one context within another. For example, you may define several different contexts for parsing the C language, and almost all of them can include comments. Rather than copying the relevant match patterns into each of these contexts, you can include them. https://www.sublimetext.com/docs/syntax.html#include-patterns
With elements such as comments, it’s so common to include them that it’s simpler to make them included automatically in every context, and just list the exceptions instead. You can do this by creating a context named prototype, it will be included automatically at the top of every other context, unless the context contains the meta_include_prototype key. https://www.sublimetext.com/docs/syntax.html#prototype-context