JavaScript library and API for parsing, compiling and rendering snippets with tabstops.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.
Install with npm (requires Node.js >=8):
$ npm install --save tabstops- Tabstops in the following formats:
$1,${1} - Tabstops with placeholders:
${1:foo} - Nested tabstops:
$1 ${2:${1:foo}} - Variables in the following formats:
$name,${name} - Variables with placeholders:
${name:Jon Schlinkert} - Nested Variables:
${name:${1}},${name:${fullname:Jon Schlinkert}} - Choices:
${1|one,two,three|} - Variable Transforms:
${TM_FILENAME/(.*)\..+$/$1/gim} - Placeholder Transforms:
${1/^_(.*)/$1/g} - more...!
Supported Formats
Note that this library does not load snippets from the file system. You need to pass the snippet string.
const TabStops = require('tabstops');
// pass a string as the first argument
const tabstops = new TabStops('console.log("$1");');
console.log(tabstops.render()); //=> 'console.log("");'
tabstops.set(1, 'It worked!');
console.log(tabstops.render()); //=> 'console.log("It worked!");'
tabstops.set(1, 'Warning!');
console.log(tabstops.render()); //=> 'console.log("Warning!");'WIP - user and docs are in progress!!! In the meantime, see the unit tests for available features and usage examples.
WIP
The following documentation is based on the VSCode Snippets and TextMate Snippets docs.
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 are tabstops with values, like ${1:foo}. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can nested, like ${1:another ${2:placeholder}}.
Placeholders may have choices as values. The syntax is a comma-separated enumeration of values, enclosed with the pipe-character, e.g. ${1|one,two,three|}. When inserted and selected choices will prompt the user to pick one of the values.
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 value is undefined) the name of the variable is inserted instead, and it is transformed into a placeholder.
Transformations allow you to modify the value of a variable before it is being inserted. The definition of a transformation consists of four parts (including the variable to be transformed):
- The variable to transform
- A regular expression that is matched against the value of the variable, or the empty string when the variable cannot be resolved.
- A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications.
- Options that are passed to the regular expression
The following sample inserts the name of the current file without its ending, so from foo.txt it makes foo.
${<variable>/<regexp>/<format>/<options>}
${TM_FILENAME/(.*)\..+$/$1/gim}
| | | |
| | | |-> options (regex flags)
| | |
| | |-> references the contents of the first
| | capture group
| |
| |-> regex to capture everything before
| the final `.suffix`
|
|-> resolves to the filename
Like a Variable-Transform, a transformation of a placeholder allows changing the inserted text for the placeholder when moving to the next tab stop.
The inserted text is matched with the regular expression and the match or matches - depending on the options - are replaced with the specified replacement format text.
Every occurrence of a placeholder can define its own transformation independently using the value of the first placeholder.
The format for Placeholder-Transforms is the same as for Variable-Transforms.
The following sample removes an underscore at the beginning of the text, so that _transform becomes transform.
${1/^_(.*)/$1/g}
| | | |-> Options (regex flags)
| | |
| | |-> Replace it with the first capture group
| |
| |-> Regular expression to capture everything after the underscore
|
|-> Placeholder Index
Below is the EBNF for snippets. With \ (backslash) you can escape $, } and \, within choice elements the backslash also escapes comma and pipe characters.
placeholder ::= tabstop | choice | variable | text
tabstop ::= '$' int
| '${' int '}'
| '${' int1 ':' placeholder '}'
| '${' int1 '/' transform '}'
variable ::= '$' var
| '${' var '}'
| '${' var ':' placeholder '}'
| '${' var '/' transform '}'
transform ::= regex '/' (format | text)+ '/' flags
format ::= '$' int
| '${' int '}'
| '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}'
| '${' int ':+' if '}'
| '${' int ':?' if ':' else '}'
| '${' int ':-' else '}'
| '${' int ':' else '}'
choice ::= '${' int1 '|' text (',' text)* '|}'
regex ::= JavaScript Regular Expression value (ctor-string)
flags ::= JavaScript Regular Expression flags (ctor-flags)
var ::= [_a-zA-Z][_a-zA-Z0-9]*
int ::= [0-9]+
int1 ::= [1-9]+
text ::= .*
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm testBuilding docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verbJon Schlinkert
Copyright © 2019, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on July 24, 2019.