.. | ||
keymaps | ||
lib | ||
menus | ||
spec | ||
.eslintignore | ||
.eslintrc | ||
.gitignore | ||
.pairs | ||
CONTRIBUTING.md | ||
package-lock.json | ||
package.json | ||
README.md |
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.
leftLabel
will add text to the left part of the autocomplete results box.leftLabelHTML
will overwrite what's inleftLabel
and allow you to use a bit of CSS such ascolor
.rightLabelHTML
. By default, in the right part of the results box you will see the name of the snippet. When usingrightLabelHTML
the name of the snippet will no longer be displayed, and you will be able to use a bit of CSS.description
will add text to a description box under the autocomplete results list.descriptionMoreURL
URL to the documentation of the snippet.
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
:
If it's difficult to determine the package handling the file type in question (for example, for .md
-documents), you can use another approach:
- Put your cursor in a file in which you want the snippet to be available.
- Open the Command Palette (cmd-shift-p or ctrl-shift-p).
- 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:
- Interpolated shell code can’t reliably be supported cross-platform, and is probably a bad idea anyway. No other editors that support snippets have adopted this feature, and Pulsar won’t either.
The following features from VSCode snippets are not yet supported:
- “Choice” syntax like
${1|one,two,three|}
requires that the autocomplete engine pop up a menu to offer the user a choice between the available placeholder options. This may be supported in the future, but right now Pulsar effectively converts this to${1:one}
, treating the first choice as a conventional placeholder.
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:
TM_FILENAME
: The name of the current file (foo.rb
).TM_FILENAME_BASE
: The name of the current file, but without its extension (foo
).TM_FILEPATH
: The entire path on disk to the current file.TM_CURRENT_LINE
: The entire current line that the cursor is sitting on.TM_CURRENT_WORD
: The entire word that the cursor is within or adjacent to, as interpreted bycursor.getCurrentWordBufferRange
.CLIPBOARD
: The current contents of the clipboard.CURRENT_YEAR
,CURRENT_MONTH
, et cetera: referneces to the current date and time in various formats.LINE_COMMENT
,BLOCK_COMMENT_START
,BLOCK_COMMENT_END
: uses the correct comment delimiters for whatever language you’re in.
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:
/upcase
(foo
→FOO
)/downcase
(BAR
→bar
)/capitalize
(lorem ipsum dolor
→Lorem ipsum dolor
) (first letter uppercased; rest of input left intact)/camelcase
(foo bar
→fooBar
,lorem-ipsum.dolor
→loremIpsumDolor
)/pascalcase
(foo bar
→FooBar
,lorem-ipsum.dolor
→LoremIpsumDolor
)
It also supports two other common transformations:
/snakecase
(foo bar
→foo_bar
,lorem-ipsum.dolor
→lorem_ipsum_dolor
)/kebabcase
(foo bar
→foo-bar
,lorem-ipsum.dolor
→lorem-ipsum-dolor
)
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
WORKSPACE_NAME
,WORKSPACE_FOLDER
, andRELATIVE_PATH
all rely on the presence of a root project folder, but a Pulsar project can technically have multiple root folders. While this is rare, it is handled bysnippets
as follows: whichever project path is an ancestor of the currently active file is treated as the project root — or the first one found if multiple roots are ancestors.WORKSPACE_NAME
in VSCode refers to “the name of the opened workspace or folder.” In the former case, this appears to mean bundled projects with a.code-workspace
file extension — which have no Pulsar equivalent. Instead,WORKSPACE_NAME
will always refer to the last path component of your project’s root directory as defined above.
Variables that are not yet supported
Of the variables supported by VSCode, Pulsar does not yet support:
UUID
(Will automatically be supported when Pulsar uses a version of Electron that has nativecrypto.randomUUID
.)
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.