This is a reimagining of the original snippets
package. It introduces new features such as variables and advanced formatting.
Snippets as in the snippets
package, plus:
$0
(end tab stop) semanticsSee the wiki for more in depth information.
Check the wiki page for snippet syntax.
Snippets can be provided by packages. Any .cson
or .json
file in a top level snippets
directory will be searched. Users can also provide snippets directly through the ~/.atom/snippets.cson
file.
The structure is as follows:
source1:name1:prefix: "foo"body: "Hello world"name2:prefix: "bar"body: "second snippet"source2:name1:prefix: "foo"body: "a snippet for a different scope"
The top level keys are scope selectors. These control what parts of a file the snippet can be expanded in. For example,
.source.js
allows the snippet to be expanded in all JavaScript files.source.js,.source.ts
allows the snippet to be used in JS and TS files.source.js .string
only allows the snippet to expand in JS strings.string
allows the snippet in any string of any languageYour file may have any number of these selectors. Note that because of how CSON and JSON work, all sibling keys must be unique. If you want to add multiple snippets to the same scope, make sure to do it under the same key. E.g.,
# No good, two keys on the same object have the same value".source.js":name1:prefix: 'snippet1'body: 'my first snippet'".source.js":name2:prefix: 'snippet2'body: 'my next snippet'################ Fixed".source.js":name1:prefix: 'snippet1'body: 'my first snippet'name2:prefix: 'snippet2'body: 'my next snippet'
name
is a unique identifier for the snippet.prefix
is a string that must be directly behind the cursor for this snippet to be expanded. It must be a single line, and no longer than 50 characters.You can also add autocomplete-plus
attributes like description
and rightLabel
. They are not used by this package, but can make the autocomplete popup more descriptive.
Until now this is all the same as for the original snippets package. But this package supports a shorthand structure for when you don't care about naming snippets. If you don't declare a prefix
key, then the snippet name will be used instead. And if the snippet declaration is a string, then it will be used as the body. So the following are all equivalent
".source.js":log:prefix: "log",body: "console.log($1)$0"################".source.js":log:body: "console.log($1)$0"################".source.js":log: "console.log($1)$0"
As with the original package, user snippets are watched and automatically updated when the file changes.
This package also provides a new snippet attribute key
, which lets you associate a snippet with a keybinding. Doing this effectively skips using the prefix. Use prefix: null
to prevent the snippet from having a prefix.
The key binding uses the same scope as the snippet to determine when it can be triggered, so you can have multiple snippets on the same key and the most specific match will be expanded.
To expand a snippet, type it's prefix and run the Snippets: Expand
command. This command is assigned the shortcut tab by default.
The selection of snippet to expand is follows:
So if we had candidate prefixes log
and conlog
, then for the following text before the cursor:
conlogq
: no snippet matchesconlog
: picks the conlog
snippetonlog
: picks the log
snippetog
: no snippet matchesTo goto the next tab stop, run Snippets: Next Tab Stop
(again, tab by default) and to goto the previous run Snippets: Previous Tab Stop
(shift-tab by default). The keybindings can be disabled and replaced with your own.
Technical details on how expanded snippets behave can be found on the wiki.
I found I have many snippets that are defined like as follows
\\\\textbf{$1}$2
Under the snippets
package I never noticed a problem, but with this one you see it is still in snippets mode when you reach the $2
stop. This can cause unexpected behaviour when you next press tab, and if you have the tab stops markers visible it will look weird too.
By default, this package will try to correct snippets like these. If this option is enabled, then if
then it will be converted to a $0
stop. So the above becomes
\\\\textbf{$1}$0
Which behaves much better. Disable this mode if you want full control over your snippets.
Easiest is to open the project in Atom and run Window: Run Package Specs
.
Alteratively run atom test .
in the command line to run the test suite. Replace atom
with atom-beta
and atom-nightly
as appropriate.
Good catch. Let us know what about this package looks wrong to you, and we'll investigate right away.