Completions¶
Completions provide an IDE-like functionality to insert dynamic content through
the completions list or by pressing Tab
.
File Format¶
Completions are JSON files with the .sublime-completions
extension.
Structure of a Completions List¶
scope
- Determines whether the completions are to be sourced from this file. See Scopes for more information.
completions
- Array of completions.
Here’s an excerpt from the html completions:
{
"scope": "text.html - source - meta.tag, punctuation.definition.tag.begin",
"completions":
[
{ "trigger": "a", "contents": "<a href=\"$1\">$0</a>" },
{ "trigger": "abbr", "contents": "<abbr>$0</abbr>" },
{ "trigger": "acronym", "contents": "<acronym>$0</acronym>" }
]
}
Types of Completions¶
Plain Strings¶
Plain strings are equivalent to an entry where the trigger
is identical to
the contents
:
"foo"
# is equivalent to:
{ "trigger": "foo", "contents": "foo" }
Trigger-based Completions¶
trigger
- Text that will be displayed in the completions list and will cause the
contents
to be inserted when validated. contents
- Text to be inserted in the buffer. Can use snippet features.
Sources for Completions¶
These are the sources for completions the user can control:
.sublime-completions
EventListener.on_query_completions()
Additionally, other completions are folded into the final list:
- Snippets
- Words in the buffer
Priority of Sources for Completions¶
- Snippets
- API-injected completions
.sublime-completions
files- Words in buffer
Snippets will only be automatically completed against an exact match of their tab trigger. Other sources for completions are filtered with a case insensitve fuzzy search instead.
The Completions List¶
To use the completions list:
- Press
Ctrl+spacebar
to open- Optionally, press
Ctrl+spacebar
again to select next entry- Press
Enter
orTab
to validate selection
Note
The current selection in the completions list can actually be validated with any punctuation sign that isn’t itself bound to a snippet.
Snippets show up in the completions list following the pattern:
<tab_trigger> : <name>
. For the other completions, you will just see the
text to be inserted.
If the list of completions can be narrowed down to one choice, the autocomplete dialog will be bypassed and the corresponding content will be inserted straight away according to the priority rules stated above.
Enabling and Disabling Tab Completion for Completions¶
The tab_completion
setting is true
by default. Set it to false
if
you want Tab
to stop sourcing the most likely completion. This setting
has no effect on triggers defined in .sublime-snippet
files, so snippets
will always be inserted after a Tab
.
With tab_completion
on, The same order of priority as stated above applies,
but, unlike in the case of the completions list, Sublime Text will always
insert a completion, even if faced with an ambiguous choice.
Inserting a Literal Tab¶
If tab_completion
is true
, you can press Shift+Tab
after a prefix
to insert a literal tab character.