tabstops

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 :heart: and support.

Install

Install with npm (requires Node.js >=8):

$ npm install --save tabstops

Features

• 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

• TextMate Snippets
• Atom Snippets
• VSCode Snippets
• Sublime Text Snippets

Usage

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(2, 'Warning!');
console.log(tabstops.render()); //=> 'console.log("It worked!");'

Docs

WIP - user and docs are in progress!!! In the meantime, see the unit tests for available features and usage examples.

API

WIP

Snippet Features

The following documentation is based on the VSCode Snippets and TextMate Snippets docs.

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 nested, like ${1:another ${2:placeholder}}.

Choice

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.

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 value is undefined) the name of the variable is inserted instead, and it is transformed into a placeholder.

Variable-Transform

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):

1. The variable to transform
2. A regular expression that is matched against the value of the variable, or the empty string when the variable cannot be resolved.
3. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications.
4. 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

Placeholder-Transform

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

Grammar

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        ::= .*

About

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

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 test

(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 && verb

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2019, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on July 24, 2019.