Syntax Definitions

Creating a TextMate Syntax Definition

1. Command Palette: PackageDev: New Syntax Definition
2. Edit the file to your liking
3. Save it within a package or somewhere else

Converting a TextMate to a Sublime Text Syntax Definition

To convert a TextMate Syntax Definition to the new Sublime Text format,

1. Open a view (e.g. an empty view with Primary+N).
2. Set the view's syntax to the one you want to convert.
3. Menu: Tools → Developer → New Syntax from .tmLanguage…
4. Save the file. (The correct syntax definition should be applied afterwards.)

Features for Sublime Text Syntax Definitions

• Syntax highlighting, including for Oniguruma regular expressions

  

• Static and dynamic completions for:

  • All keys, like match and include
  • Scope names are completed from scope naming conventions, which includes official and not yet documented but generally accepted scope names.
  • Context names from the current file are completed for keys that expect them (include, set, pop)
  • Variable names from the current file

  

• Visual highlighting of the capture group that a line in the captures mapping affects The highlighting style can be configured in the settings.

  

General Tips

Documentation on syntax definitions is available here: http://www.sublimetext.com/docs/3/syntax.html

The following sub-sections will go a bit more into detail on some situations you may or may not encounter.

See also this issue on the Default Packages repository, where community members provide some insight on their methods or tricks they developed.

Syntax Definition Tips

sregex Engine

Sublime Text uses its custom sregex regular expression engine. This engine supports a subset of Onigurumas operations and is significantly faster, because it is non-backtracking. Thus, you should pay attention to using only expressions that are compatible with the custom engine.

The regular expression constructs that sregex doesn't support are:

• Look-behinds ((?<=\s))
• Possessive quantifiers ((a|b)++)
• Atomic groups ((?>a|ab))
• Backtracking in sub-expressions

To avoid having to use look-behinds, work with the context stack.

Sublime Text provides a build system variant that checks whether all expressions in the currently active view are compatible with sregex and will point out those that aren't. Select Build With: Syntax Test - Regex Compatibility in the Command Palette.

Scope Naming Conventions

Official scope naming conventions are available here: http://www.sublimetext.com/docs/3/scope_naming.html

Just like any other conventions, these may change over time and are not complete. If you are curious about a specific situation or would like to discuss the conventions with other developers, you should monitor (or create) issues with the RFC label on the Default Packages repository.

Tests

Do write tests. They will come in handy, should you ever change your syntax in the future or even refactor large parts of it. However, they are also useful for ensuring your syntax definitions works as you expect it to. Test-driven development has proven to be very useful here.

See Syntax Tests for more information about writing tests.

YAML Tips

Single Quotes

YAML allows unquoted strings, but the nature of regular expression will occasionally cause you to run into sequences that YAML does not recognize as strings. In these situations, you should usually use single quotes, because double quotes require backslash escape sequences and things get very ugly very quickly. To escape a single quote within a single-quoted string, specify it twice. The following YAML "scalars" are equal and represent '[^\]]':

• '''[^\]]'''
• \'[^\]]'
• "'[!\\]]'"

Block Scalars

When your regular expression become very large, you might want to use PCRE Extended Mode to split it over multiple lines and add comments. The proper way to do this within YAML is a block scalar, which looks as follows:

|-
  (?x:
    \\  # literal backslash
    (?:
        ["\\/bfnrt]
      | u [0-9a-fA-F]{4}
    )
  )

The pipe character (|) denotes that a new block scalar is being started. The following hyphen (-) indicates that there should not be a trailing newline at the end of the scalar. The resulting string will end with ). Afterwards you must begin a new line with the regular expression. Usually you start by enabling Extended Mode either globally ((?x)) or within a group ((?x:…)). The latter is widely preferred for variables, while it doesn't matter what you choose for match values.

YAML Macros

The YAML Macros package provides more advanced templating capabilities, for example to extend existing syntaxes by appending patterns to certain contexts only. It can be used together with this package.