Snippets should be triggerable from keystrokes

[savetheclocktower]

Have you checked for existing feature requests?

• Completed

Summary

There are a few gaps in support between Pulsar snippets and those of other editors. One of them is the lack of variables like $TM_SELECTED_TEXT.

In my opinion, the main reason there has been no urgency to add support for $TM_SELECTED_TEXT is that there is only one official way of triggering a snippet — by typing its prefix and pressing Tab. For this reason, it’s not been possible for any text to be selected at the time of a snippet’s invocation. This stands in contrast to TextMate itself (which always allowed snippets to be invoked either by tab trigger or by arbitrary keystroke) and VSCode (which, as far as I can tell, allows for triggering of snippets via the command palette).

I’d like to add support for the whole range of variables mentioned in the LSP specification, but it’d be premature unless there were a way to invoke a snippet with a keystroke.

Proposal

The snippet config file should be enhanced. Rather than give it the ability to map to hotkeys directly (a job which should belong only to keymap.cson), I’d propose the ability to give a particular snippet a command name, which would expose it as a command that could be invoked like any other.

As an example:

'.text.html':
  'wrap in HTML tag':
    body: '<${1:p}>${0:TM_SELECTED_TEXT}</$1>'
    command: 'wrap-in-html-tag'

Here, a prefix property is omitted, and a command property is specified. The format of the command conforms to what is expected by atom.commands.add.

Command names must follow the namespace:action pattern, where namespace will typically be the name of your package, and action describes the behavior of your command. If either part consists of multiple words, these must be separated by hyphens. E.g. awesome-package:turn-it-up-to-eleven. All words should be lowercased.

Since the package name is snippets, the user would define the part after the colon.

So that’s how a user would register a command that simply invokes a snippet. When the snippets package parses a user’s snippets.cson, it would:

1. Enforce the presence of either prefix or command (but it’s OK for both to be specified);
2. If command is present, ensure (a) that the value conforms to kebab-kase, (b) that the snippets package has not registered another command with the same identifier (whether it be built-in or already registered by an earlier snippet);
3. Register the command name and associate it with a handler that will programmatically trigger the given snippet.

With no further configuration, this would allow a snippet to be triggered from the command palette. But a user can go further and map a snippet’s command to a keystroke via their keymap.cson:

'atom-pane atom-text-editor[data-grammar~="html"]':
  'cmd-shift-w': 'snippets:wrap-in-html-tag'

Challenges

There are a few challenges that I can envision, none of which are complicated.

Snippets provided by packages?

If a user defines their own snippet, that command should use the snippets command namespace by default.

But if a snippet is provided by a package, and it defines a command, I think that command should be given the package’s own namespace. Otherwise it’d be too easy for different packages to step on each others’ toes.

Autocomplete?

I don’t use autocomplete-plus, but I imagine a lot of people do, and also rely on autocomplete-snippets to make snippets available as possible completions. I imagine that autocomplete-snippets expects all snippets to have a prefix.

I think this is fine, though. If a snippet defines command but not prefix, that strikes me as a clear signal that the snippet should never be suggested by autocomplete-snippets, since prefix is the only logical token that snippet suggestions can use.

Settings view?

The settings view for a particular package lists all the snippets provided by that package, and right now imagines that each one will have a prefix property (though the settings view calls it “trigger”). These snippets are listed so that you can figure out which package supplies a given snippet, and so that you can turn them off wholesale if you think they’re too invasive. (You are also able to copy the CSON for individual snippets so that you can pick and choose which ones you want to add back to your snippets.cson.)

We’d want to coordinate a change with settings-view so that

• snippets without a prefix are still represented in this table,
• snippets with a command have that name displayed in a new column, whether or not they have a prefix;
• the Copy button preserves any command property so that it gets retained when pasted into someone’s snippets.cson.

And I would argue that the “Enable” checkbox, when unchecked, should prevent certain snippets from being triggered by prefix — but I think any snippet with a defined command name should still be triggerable via the command palette.

Why? The purpose of the “Enable” checkbox, as I see it, is that certain packages define a lot of snippets (e.g., language-html), and that can cause pollution of one’s autocomplete suggestions, and possibly have surprising effects when you hit Tab and trigger a snippet when you didn’t mean to.

By contrast, a snippet that has a command name isn’t really getting in anything’s way, and would be quite hard to trigger by accident. The explanation of “Enable” would have to be a bit more nuanced, but I think this would be the best option.

Scope?

The snippets.cson file uses top-level keys to restrict certain snippets so that they’re triggerable only within certain scopes. When a snippet defines a command property, it makes it possible for the user to attempt to trigger that snippet from the command palette, regardless of the scope they’re in. I think that we should still guard against this possibility by writing the command handler so that it verifies we’re in a valid scope for that snippet, and throws up an error notification otherwise.

If the user wants that snippet to apply globally, they can define it under the * scope.

You’ll notice that keymap.cson has its own (clumsy) way of allowing certain keystrokes to have meaning only in certain kinds of files. Thus this also solves the hypothetical (probably rare) scenario where a user mistakenly maps a keystroke to a context that is mutually exclusive with the one under which the snippet itself is defined. In that scenario, we’d show the user a helpful error message to explain where they’d gone wrong.

What benefits does this feature provide?

Currently, the only good way I can think of to make a snippet triggerable by keystroke is to definie it in init.js/init.coffee:

atom.commands.add('atom-text-editor', {
  'custom:wrap-in-html-tag': () => {
    let editor = atom.workspace.getActiveTextEditor();
    let selection = editor.getLastSelection();
    let snippet = util.getSnippetsModule();

    // Closing tag transforms the first tab stop's text so that it ignores
    // anything that comes after the tag name.
    snippet.insert('<${1:div}>' + selection.getText() + '</${1/[ ]+.*$//}>');
  }
});

I use this approach in a number of places in my own init.js, but it cries out for a simpler solution.

Any alternatives?

There are hypothetical alternatives, but this is the one that (to me) works best within Pulsar’s existing architectural choices.

Other examples:

See also the documentation for snippets in TextMate (the originator) and in VSCode.

[savetheclocktower]

I should point out (because I forgot) that there is actually a second way of triggering a snippet: through the “Snippets Available” command. Invoking it opens a palette showing you all snippets that are triggerable from your current scope. This is not nothing, but it still doesn't allow you to bind to a keystroke.

[mauricioszabo]

One thing to add - autocomplete-plus allows one to complete a snippet - I use that functionality on my generic-lsp package.

Another thing is that I'm studying a way to avoid the prefix on autocomplete-plus (which will also affect Snippets) so there may be a pattern that we can re-use there

[savetheclocktower]

One thing to add - autocomplete-plus allows one to complete a snippet - I use that functionality on my generic-lsp package.

Sure, I should be more specific: I'm talking about ways of triggering snippets that would preserve the functionality of $TM_SELECTED_TEXT, meaning ways to trigger a snippet while having some other text selected.

[savetheclocktower]

I'm working on implementing this. It's going well in general, but there's one giant thorn in my side and I'm writing it down here for my own benefit. Others might find it interesting.

How snippets work

Your snippets.cson’s top-level keys are scope selectors. If a snippet is defined within it, it is triggerable only when the cursor’s scope descriptor matches that scope selector.

'source.gfm comment.quote':
  'some snippet':
    prefix: 'test'
    body: 'lorem $0 ipsum'
    command: 'some-snippet'

Using this example, the current behavior of snippets is to act as though this snippet doesn’t exist unless we’re in its matching scope. If you’re within a Markdown blockquote, typing test and pressing Tab will expand the snippet. In all other contexts, a literal tab stop will be inserted. No error will be thrown, nothing logged to the console. This is fine; it's how it ought to work.

How keymaps work

Say I’m a user trying to add a fat-arrow-function snippet to my snippets.cson:

'source.js':
  'fat-arrow function':
    prefix: 'ff'
    body: '${1:($2)} => {\n  $0\n}'
    command: 'insert-fat-arrow'

Having exposed a command name, I use it in my keymap.cson:

'atom-text-editor':
  'shift-opt-f': 'snippets:insert-fat-arrow'

This is fine, but now I’ve mapped that key in all contexts — Markdown, PHP, what-have-you. It won’t do anything if we're not in the right context, but it’s still theoretically preventing us from mapping something else to that key. Not a huge deal, but it’d be nice to define something more specific so that shift-opt-f can be mapped to something else when I’m working in another language.

OK, let’s pare it down:

'atom-text-editor[data-grammar~="source"][data-grammar~="js"]':
  'shift-opt-f': 'snippets:insert-fat-arrow'

Now it’s available in too few contexts. It’ll work in base JS files and the source.js.jsx grammar from language-babel, but it won’t work in script blocks in HTML files (text.html) or any other grammar that embeds JS.

If I, with my years of Pulsar experience, were defining this shortcut, I’d probably do something like this:

'atom-text-editor[data-grammar^="source js"], atom-text-editor[data-grammar~="html"]':
  'shift-opt-f': 'snippets:insert-fat-arrow'

That’ll match any grammar whose name starts with source.js, plus any grammar that has html as one of its tokens. Good enough.

The problem isn’t that this took a while to work out. The problem is twofold:

1. A snippet’s scope doesn’t distinguish between base grammar scope names and other types of scopes, but keymaps do. Given a snippet’s scope, there’s no good way to translate it to the syntax understood by commands and keymaps without losing some meaning, or adding meaning that wasn’t intended. Hence a user will need to add a keymap manually. But…
2. …there’s no good way to describe to a typical Pulsar user what we just did with the keymap without giving them a crash course in the implementation details of Pulsar commands and keymaps.

The technical problem of exposing specific snippets as invokable commands is easy; the UX problem of making it intuitive to define a shortcut for that snippet in one’s keymap is difficult.

What’s the answer?

Despite my attempts to avoid it, here’s the situation as I see it:

• If a snippet is exposed as a command, that command will appear in the palette whenever an editor is focused.
• When it’s invoked, the command will enforce the scope described in the snippet, and will only expand if the cursor’s scope matches. Otherwise it’ll abort the key binding and do nothing.
• Just because the snippet failed to expand doesn’t mean the user was wrong to have invoked it, or mapped their hotkey incorrectly. (For instance, they could’ve mapped their command to a very common key on purpose, like the space bar, on the reasoning that the command will abort when the scope doesn’t match, and fall back to the default behavor for pressing Space.) So we probably don’t want to throw up an error here.
• If someone maps a snippet to a command and then gets confused when their shortcut doesn’t work, I think the main thing we can do to help that person is document the hell out of this in the Flight Manual.

And in the long term, I think the answer is to introduce more robust scope handling in commands and keymaps. atom.commands.add could optionally take an argument that applies a further scope-descriptor constraint on the ability to invoke the command, with the scope descriptor coming from the editor’s last cursor.

This could come with some sort of enhancement to keymap.cson syntax, with care taken not to break backward-compatibility:

'atom-text-editor':
  'open link':
    key: 'numpadenter'
    command: 'link:open'
    scope: 'link, markup.underline.link'
  'extend shell comment':
    key: 'numpadenter'
    command: 'custom:extend-shell-comment'
    scope: 'source.shell & comment.block'

The object keys under atom-text-editor here are just arbitrary strings that aren’t used for anything, which lets us remove the uniqueness constraint from the key combinations themselves. That lets us define more than one shortcut for numpadenter here. When the key is pressed, these shortcuts could respond in order of definition, and only claim the shortcut if the specified scope matches.

If all of this worked, then the command palette could be rewritten to show only the contextual commands whose scope matched the cursor. And we’d be able to describe a hotkey for a given snippet that far more closely matches the intent described in the snippet definition.

This is honestly how I want keymaps to work, but I have no idea how much work it'd be. That said, if this makes sense to anyone else, I can propose this in an issue in the main repo, and eventually I might feel motivated to attempt it.

[mauricioszabo]

When you say "scope", you mean the grammar?

[savetheclocktower]

I mean the scopes applied by a TextMate or tree-sitter grammar: entity.name.function, variable.parameter, whatever. But that hierarchy does include the root scope descriptor, which is the scope defined by the grammar — source.js, text.html.basic, and so on.

Right now, keymaps and commands can only be targeted based on that root scope, but snippets can be targeted to any kind of scope selector understood by scoped-property-store.

[mauricioszabo]

Wow, so.... you can actually type a<tab> and then get that expanded to different things, depending if your editor is currently under a function or a variable?

[savetheclocktower]

Yup!

[savetheclocktower]

Implemented in #10.