mirror of
https://github.com/microsoft/language-server-protocol.git
synced 2025-12-23 08:48:16 +00:00
79 lines
4 KiB
Markdown
79 lines
4 KiB
Markdown
# Snippet Syntax
|
||
|
||
The `body` of a snippet can use special constructs to control cursors and the text being inserted. The following are supported features and their syntaxes:
|
||
|
||
### Tabstops
|
||
|
||
With tabstops, you can make the editor cursor move inside a snippet. Use `$1`, `$2` to specify cursor locations. The number is the order in which tabstops will be visited, whereas `$0` denotes the final cursor position. Multiple tabstops are linked and updated in sync.
|
||
|
||
### Placeholders
|
||
|
||
Placeholders are tabstops with values, like `${1:foo}`. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can be nested, like `${1:another ${2:placeholder}}`.
|
||
|
||
### Choice
|
||
|
||
Placeholders can have choices as values. The syntax is a comma separated enumeration of values, enclosed with the pipe-character, for example `${1|one,two,three|}`. When the snippet is inserted and the placeholder selected, choices will prompt the user to pick one of the values.
|
||
|
||
### Variables
|
||
|
||
With `$name` or `${name:default}` you can insert the value of a variable. When a variable isn’t set, its *default* or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder.
|
||
|
||
The following variables can be used:
|
||
|
||
* `TM_SELECTED_TEXT` The currently selected text or the empty string
|
||
* `TM_CURRENT_LINE` The contents of the current line
|
||
* `TM_CURRENT_WORD` The contents of the word under cursor or the empty string
|
||
* `TM_LINE_INDEX` The zero-index based line number
|
||
* `TM_LINE_NUMBER` The one-index based line number
|
||
* `TM_FILENAME` The filename of the current document
|
||
* `TM_FILENAME_BASE` The filename of the current document without its extensions
|
||
* `TM_DIRECTORY` The directory of the current document
|
||
* `TM_FILEPATH` The full file path of the current document
|
||
|
||
### Variable Transforms
|
||
|
||
Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts:
|
||
|
||
1. A regular expression that is matched against the value of a variable, or the empty string when the variable cannot be resolved.
|
||
2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications.
|
||
3. Options that are passed to the regular expression.
|
||
|
||
The following example inserts the name of the current file without its ending, so from `foo.txt` it makes `foo`.
|
||
|
||
```
|
||
${TM_FILENAME/(.*)\..+$/$1/}
|
||
| | | |
|
||
| | | |-> no options
|
||
| | |
|
||
| | |-> references the contents of the first
|
||
| | capture group
|
||
| |
|
||
| |-> regex to capture everything before
|
||
| the final `.suffix`
|
||
|
|
||
|-> resolves to the filename
|
||
```
|
||
|
||
### Grammar
|
||
|
||
Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for snippets. With `\` (backslash), you can escape `$`, `}` and `\`. Within choice elements, the backslash also escapes comma and pipe characters.
|
||
|
||
```
|
||
any ::= tabstop | placeholder | choice | variable | text
|
||
tabstop ::= '$' int | '${' int '}'
|
||
placeholder ::= '${' int ':' any '}'
|
||
choice ::= '${' int '|' text (',' text)* '|}'
|
||
variable ::= '$' var | '${' var }'
|
||
| '${' var ':' any '}'
|
||
| '${' var '/' regex '/' (format | text)+ '/' options '}'
|
||
format ::= '$' int | '${' int '}'
|
||
| '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}'
|
||
| '${' int ':+' if '}'
|
||
| '${' int ':?' if ':' else '}'
|
||
| '${' int ':-' else '}' | '${' int ':' else '}'
|
||
regex ::= JavaScript Regular Expression value (ctor-string)
|
||
options ::= JavaScript Regular Expression option (ctor-options)
|
||
var ::= [_a-zA-Z] [_a-zA-Z0-9]*
|
||
int ::= [0-9]+
|
||
text ::= .*
|
||
```
|