snippet

Overview ¶

Package snippet provides primitives for parsing and evaluating TextMate snippets. In general, snippets are text with "placeholders" for the user to fill in. For example something like "foo ${bar}" would expect the user to provide a value for the `bar` variable.

This code is influenced heavily by the more formal treatment specified by the Language Server Protocol, though (since this does not have to serve an interactive prompt in an IDE) we do omit some features for simplification (e.g., we have limited support for tabstops and builtin variables like `TM_SELECTED_TEXT`).

A parsed snippet template is represented as a tree consisting of one of several types:

• Text: representing free text, i.e., text that is not a part of (e.g.) a variable.
• Variable: Takes the forms `${varName}` and `${varName:defaultValue}`. When a variable isn't set, an empty string is inserted. If the variable is undefined, its name is inserted as the default value.
• Tabstop (currently unused by our tool, but implemented anyway): takes the form of the '$' character followed by a number, e.g., `$1` or `$2`. Inside an editor, a tabstop represents where to navigate when the user presses tab or shift-tab.
• Placeholder (currently unused by our tool, but implemented anyway): representing a tabstop with a default value. These are usually of the form `${3:someDefaultValue}`. They can also be nested, as in `${1:firstValue${2:secondValue}`, or recursive, as in `${1:foo$1}`.

TextMate does not specify a grammar for this templating language. This parser implements the following grammar for, which we believe is close enough to the intention of TextMate. The characters `$`, `}`, and `\` can be escaped with `\`, but for simplicity we omit them from the grammar.

any         ::= tabstop | placeholder | choice | variable | text
tabstop     ::= '$' int | '${' int '}'
placeholder ::= '${' int ':' any '}'
choice      ::= '${' int '|' text (',' text)* '|}'
variable    ::= '$' var | '${' var }' | '${' var ':' any '}'
var         ::= [_a-zA-Z] [_a-zA-Z0-9]*
int         ::= [0-9]+
text        ::= .*