snippets Bundled

Expand snippets matching the current prefix with `tab`.

pulsar-edit

0

0

1.8.0

MIT

GitHub

This package provides the following services:

Snippets package

Expand snippets matching the current prefix with tab in Pulsar.

To add your own snippets, select the Pulsar > Snippets... menu option if you're using macOS, or the File > Snippets... menu option if you're using Windows, or the Edit > Snippets... menu option if you are using Linux.

Snippet Format

Snippets files are stored in a package's snippets/ folder and also loaded from ~/.pulsar/snippets.cson. They can be either .json or .cson file types.

'.source.js':
  'console.log':
    'prefix': 'log'
    'command': 'insert-console-log'
    'body': 'console.log(${1:"crash"});$2'

The outermost keys are the selectors where these snippets should be active, prefixed with a period (.) (details below).

The next level of keys are the snippet names. Because this is object notation, each snippet must have a different name.

Under each snippet name is a body to insert when the snippet is triggered.

$ followed by a number are the tabs stops which can be cycled between by pressing Tab once a snippet has been triggered.

The above example adds a console.log snippet to JavaScript files that would expand to:

console.log("crash");

The string "crash" would be initially selected and pressing tab again would place the cursor after the ;

A snippet specifies how it can be triggered. Thus it must provide at least one of the following keys:

The ‘prefix’ key

If a prefix is defined, it specifies a string that can trigger the snippet. In the above example, typing log (as its own word) and then pressing Tab would replace log with the string console.log("crash") as described above.

Prefix completions can be suggested if partially typed thanks to the autocomplete-snippets package.

The ‘command’ key

If a command is defined, it specifies a command name that can trigger the snippet. That command can be invoked from the command palette or mapped to a keyboard shortcut via your keymap.cson.

If a package called some-package had defined that snippet, it would be available in the keymap as some-package:insert-console-log, or in the command palette as Some Package: Insert Console Log.

If you defined the console.log snippet described above in your own snippets.cson, it could be referenced in a keymap file as snippets:insert-console-log, or in the command palette as Snippets: Insert Console Log.

Invoking the command would insert the snippet at the cursor, replacing any text that may be selected.

Snippet command names must be unique. They can’t conflict with each other, nor can they conflict with any other commands that have been defined. If there is such a conflict, you’ll see an error notification describing the problem.

Optional parameters

These parameters are meant to provide extra information about your snippet to autocomplete-plus.

autocomplete-description

Example:

'.source.js':
  'console.log':
    'prefix': 'log'
    'body': 'console.log(${1:"crash"});$2'
    'description': 'Output data to the console'
    'rightLabelHTML': '<span style="color:#ff0">JS</span>'

Determining the correct scope for a snippet

The outmost key of a snippet is the “scope” that you want the descendent snippets to be available in. The key should be prefixed with a period (text.html.basic → .text.html.basic). You can find out the correct scope by opening the Settings (cmd-, on macOS) and selecting the corresponding Language [xxx] package. For example, here’s the settings page for language-html:

Screenshot of Language Html settings

If it's difficult to determine the package handling the file type in question (for example, for .md-documents), you can use another approach:

  1. Put your cursor in a file in which you want the snippet to be available.
  2. Open the Command Palette (cmd-shift-p or ctrl-shift-p).
  3. Run the Editor: Log Cursor Scope command.

This will trigger a notification which will contain a list of scopes. The first scope that's listed is the scope for that language. Here are some examples: source.coffee, text.plain, text.html.basic.

Snippet syntax

This package supports a subset of the features of TextMate snippets, documented here, as well as most features described in the LSP specification and supported by VSCode.

The following features from TextMate snippets are not yet supported:

The following features from VSCode snippets are not yet supported:

Variables

Pulsar snippets support all of the variables mentioned in the LSP specification, plus many of the variables supported by VSCode.

Variables can be referenced with $, either without braces ($CLIPBOARD) or with braces (${CLIPBOARD}). Variables can also have fallback values (${CLIPBOARD:http://example.com}), simple flag-based transformations (${CLIPBOARD:/upcase}), or sed-style transformations (${CLIPBOARD/ /_/g}).

One of the most useful is TM_SELECTED_TEXT, which represents whatever text was selected when the snippet was invoked. (Naturally, this can only happen when a snippet is invoked via command or key shortcut, rather than by typing in a Tab trigger.)

Others that can be useful:

Any variable that has no value — for instance, TM_FILENAME on an untitled document, or LINE_COMMENT in a CSS file — will resolve to an empty string.

Variable transformation flags

Pulsar supports the three flags defined in the LSP snippets specification and two other flags that are implemented in VSCode:

It also supports two other common transformations:

These transformation flags can also be applied on backreferences in sed-style replacements for transformed tab stops. Given the following example snippet body…

[$1] becomes [${1/(.*)/${1:/upcase}/}]

…invoking the snippet and typing Lorem ipsum dolor will produce:

[Lorem ipsum dolor] becomes [LOREM IPSUM DOLOR]

Variable caveats

Variables that are not yet supported

Of the variables supported by VSCode, Pulsar does not yet support:

Multi-line Snippet Body

You can also use multi-line syntax using """ for larger templates:

'.source.js':
  'if, else if, else':
    'prefix': 'ieie'
    'body': """
      if (${1:true}) {
        $2
      } else if (${3:false}) {
        $4
      } else {
        $5
      }
    """

Escaping Characters

Including a literal closing brace inside the text provided by a snippet's tab stop will close that tab stop early. To prevent that, escape the brace with two backslashes, like so:

'.source.js':
  'function':
    'prefix': 'funct'
    'body': """
      ${1:function () {
        statements;
      \\}
      this line is also included in the snippet tab;
      }
      """

Likewise, if your snippet includes literal references to $ or {, you may have to escape those with two backslashes as well, depending on the context.

Multiple snippets for the same scope

Snippets for the same scope must be placed within the same key. See this section of the Pulsar Flight Manual for more information.