Completions
In the spirit of IDEs, Sublime Text suggests completions that aggregate code or content while writing by catching everything that you have written, like variable names.
There are however several ways to extend the list of completions (for example, depending on the current syntax).
This topic deals with how completions are used and where they come from.
How to Use Completions
There are two methods for using completions. Even though, when screening them, the priority given to completions always stays the same, the two methods produce different results.
Completions can be inserted in two ways:
- through the completions list (Ctrl ␣), or
- by pressing ⭾.
The Completions List
To use the completions list:
- Press Ctrl ␣ or just type something.
- Optionally, press Ctrl ␣ again to select the next entry or use up and down arrow keys.
- Press ⏎ or ⭾ to validate selection (depending on the
auto_complete_commit_on_tab
setting). - Optionally, press ⭾ repeatedly to insert the next available completion.
Note
If the completions list was opened explicitly, the current selection in the completions list can also be validated with any punctuation sign that isn't itself bound to a snippet (e.g. .
).
When the list of completion candidates can be narrowed down to one unambiguous choice given the current prefix, this one completion will be validated automatically the moment you trigger the completion list.
Hints
Additionally, you may see a trigger hint on the right side of a completion's trigger in the completions list. This can be used as a preview of the completion's content.
The above is in fact a snippet and expands to $arrayName = array('' => , );
.
Triggers and Contents
Completions not sourced from the text in the current file may provide a trigger that is different to the content they will insert if selected. This is commonly used for function completions where the content also includes the function's signature.
For example, completing array_map
from the PHP completions will result in array_map({callback}, {arr1})
:
You may notice in the animation that the cursor automatically selected callback
. This is because completions support the same features as snippets with fields and placeholders. For more details, refer to Snippet Features.
Completions with multiple cursors
Sublime Text can also handle completions with multiple cursors but will only open the completion list when all cursors share the same text between the current cursor positions and the last word separator character (e.g. .
or a line break).
Working example (|
represents one cursor):
l|
some text with l|
l| and.l|
Not working example:
l|
some text with la|
l| andl|
Selections are essentially ignored, only the position of the cursor matters. Thus, e|[-some selection] example
, with |
as the cursor and [...]
as the current selection, completes to example|[-some selection] example
.
⭾-Completed Completions
If you want to be able to tab-complete completions, the setting tab_completion
must be set to true
(default). Snippet tab-completion is unaffected by this setting: They will always be completed according to their tab trigger.
With tab_completion
enabled, completion of items is always automatic. This means, unlike the case of the completions list, that Sublime Text will always make the decision for you. The rules for selecting the best completion are the same as described above, but in case of ambiguity, Sublime Text will insert the item it deems most suitable. You can press the ⭾ key multiple times to walk through other available options.
Inserting a Literal tab Character
When tab_completion
is enabled, you can press ⇧ ⭾ to insert a literal tab character.
Sources for Completions and their Priorities
These are the sources for completions the user can control, in the order they are prioritized:
- Snippets
- API-injected completions via
on_query_completions
- Completions files
Additionally, the following completions are folded into the final list:
- Words in the buffer
Snippets will always win when the current prefix matches their tab trigger exactly. For the rest of the completion sources, a fuzzy match is performed. Furthermore, snippets always lose in a fuzzy match.
When a list of completions is shown, snippets will still be listed alongside the other items, even if the prefix only partially matches the snippets' tab triggers.
Note
Completions sourced from words in the buffer can be suppressed explicitly from an on_query_completions
event hook.
Auto Completion Triggers and Selector
Sublime Text provides two settings for users and package authors to tweak their auto completion behavior. Both settings work independently of each other and either of them can trigger the auto-completion popup.
auto_complete_selector
expects a scope selector that when matched causes the auto-completion popup to open for any non-punctuation character, i.e. for identifiers. The default configuration disables this for syntaxes with a focus on plain text, comments and strings.Before 4070, the selector was applied to the position after the just-typed character.
auto_complete_triggers
expects a list of mappings that may specifycharacters
that should trigger the auto-completion popup and/or a scopeselector
. If both are provided, both are required to match.Additionally, a
rhs_empty
boolean may be provided that states whether the right-hand side of the caret must be empty or a whitespace character. It defaults tofalse
.
Package authors may be interested in configuring triggers and/or the selector in a syntax-specific settings file.