Documentation TOP Completions

Sublime Text includes a few methods to save typing and time by finishing words or inserting boilerplate. Completions include the following sources:

• Words from the current file
• Context-aware suggestions 4050
• Completion files
• Snippet files
• Plugins

Various settings exist to customize the behavior of completions. Users can write their own snippets or completions files, and many third-party packages exist to provide completions.

• Usage
• Context-Aware Suggestions

4050 - Completion Metadata

4050 - Customization : - Completion Files - Snippets : - Fields - Variables - Variable Substitution - Escaping - Plugins - Settings

Usage

By default, Sublime Text will automatically show the completions popup when a user is editing source code or markup, but not within prose in comments, strings or markups.

Pressing the Esc key will hide the completions popup. To manually show the completions popup, press Ctrl+Space. If no completions are available, the message No available completions will be displayed in the status bar.

Context-Aware Suggestions

The completion engine in Sublime Text uses background processes to scan all of the files in a project to build a completion index. This index is used to provide suggested completions to the user, based on patterns in existing code.

Some examples:

• If a property is frequently set to a boolean value, the suggestions will include true or false.
• If an identifier is typically “called”, the name will be suggested with () appended.

The exact completions offered are based on various heuristics, and are derived from existing code in a project. Since completions are based on analyzing existing code, words not used in a project will not be suggested.

4050

Completion Metadata

In addition to their textual contents, completions may also provide additional details to users. These include the kind of element the completion represents, a short annotation to help in picking a completion, and details that may contain links to additional resources.

Kind Info

Completions may provide kind info to be presented with the completion trigger. This includes a high-level category, an identifying letter, and a name. The following are some of the most common kinds:

Both in this documentation and in Sublime Text, hovering the mouse over a kind letter will show a tooltip with the full name. The color of kind metadata is determined by the theme, and may not match what is shown above.

.sublime-completions files and plugins can use combinations of any category listed above, along with any Unicode character and name for a custom presentation.

Annotations

Annotations are displayed on the right-hand edge of the completions popup, and may contain any information the author deems useful. Typically the annotations will be a word or two.

Details

The details field of a completion may contain a rich text description with links. The details for a completion is shown at the bottom of the completions popup when the completion is selected.

4050

Customization

There exist a number of ways in which the engine can be augmented with new completions:

• Completion Files
• Snippets
• Plugins

Completion Files

The most basic form of adding completions to Sublime Text is by creating a .sublime-completions file. Completions files use the JSON format, and contain an object with the keys “scope” and “completions”.

The “scope” key’s value is a string containing a selector of the syntax the completions apply to. The “completions” value is an array of completions. Each entry in the array represents a single completion, and may be a string or an object.

Simple Format

When a completion is a string, the string represents both the trigger text and the completion contents.

A basic .sublime-completions file:

{
    "scope": "source.python",
    "completions": [
        "def",
        "class",
        "None",
        "True",
        "False"
    ]
}

Rich Format

When a completion is an object, the valid keys include:

“trigger” string (REQUIRED) : The text the user must enter to match the completion.

“contents” string (REQUIRED) : The contents that will be inserted into the file. Supports snippet fields and variables.

“annotation” string 4073

: The annotation to display for the completion.

“kind” string, 3-element array of strings 4073

: The kind metadata for the completion.

If the value is a string, it must be one of:

- `“ambiguous”`
- `“function”`
- `“keyword”`
- `“markup”`
- `“namespace”`
- `“navigation”`
- `“snippet”`
- `“type”`
- `“variable”`

*Example:* `“kind”: “function”`

If the value is a 3-element array of strings, they must be:

1. A string from the list above, which is used by the theme to select the
   color of the kind metadata
2. A single Unicode character to be shown to the left of the trigger
3. A description of the kind, viewable in the kind letter tool tip, and the
   detail pane (when visible)

*Example:* `“kind”: [“function”, “m”, “Method”]`

“details” string 4073

: A single line description of the completion. May contain the following HTML tags for basic formatting:

- `<a href=“”>` – [minihtml Protocols](https://www.sublimetext.com/docs/minihtml.html#protocols)
- `<b>`
- `<strong>`
- `<i>`
- `<em>`
- `<u>`
- `<tt>`
- `<code>`

*No other attributes or tags are supported other than those listed above.*

*Example:* `“details”: “Wraps selection in a <code>&lt;b&gt;</code> tag”`

A .sublime-completions file with examples of each field:

{
    "scope": "source.python",
    "completions": [
        {
            "trigger": "def",
            "contents": "def",
            "kind": "keyword"
        },
        {
            "trigger": "fun",
            "annotation": "basic function",
            "contents": "def ${1:name}($2):\n    $0\n",
            "kind": "snippet",
            "details": "A simple, non-<code>async</code> function definition"
        }
    ]
}

Snippets

Snippets are typically used for boilerplate-type content that isn’t easily authored using the .sublime-completions format due to spanning multiple lines.

Snippets are XML files with the extension .sublime-snippet. They have a top-level tag <snippet>, containing the following tags:

scope : The selector of the syntax the snippet should be enabled for

tabTrigger : The text used to match the snippet in the completions popup

contents : The text to insert into the document when the snippet it applied. Supports snippet fields and variables.

Typically the contents of this tag are wrapped in `<![CDATA[`
and `]]>` so that the contents do not need to be XML-escaped.

description : An optional description of the snippet, which is shown in the Command Palette.

An example .sublime-snippet file:

<snippet>
    <scope>source.python</scope>
    <tabTrigger>fun</tabTrigger>
    <content><![CDATA[def ${1:name}($2):
    ${0:pass}]]></content>
    <description>function, non-async</description>
</snippet>

Fields

Snippets support fields, locations within the snippet that the user may Tab through after inserting the snippet. Fields may be simple positions, but may also provide default content.

Simple fields are a $ followed by an integer. Field $0 is where the selection will be placed once the snippet is completed. Fields $1 through $n are all filled in before moving to $0.

Name: $1
Email: $2
Description: $0

Fields with default content use the format ${1:default text}. Default content may be literal text, or it may contain variables.

Name: ${1:first} ${2:last}
Email: ${3:user}@${4:example.com}

If a snippet does not contain field $0, it is implicitly added at the end.

Variables

The following variables may be added to a snippet to include information from the file the snippet is being inserted into:

In addition to the named variables above, fields may also be used as variables, allowing a user to enter a single value and have it repeated in multiple places.

Name: ${1:first} ${2:last}
Email: ${3:$1}@${4:example.com}

Variable Substitution

Variables can be directly referenced, or they may be modified using a regular expression. Variables with substitutions are written in the format ${name/regex/replace/flags}.

The regex segment supports regular expressions. The replace segment supports a corresponding replace format. The flags segment will contain zero letters from:

• g – all occurrences, rather than just the first, should be replaced
• i – case insensitive matching
• m – multiline mode, where ^ matches the beginning of each line

Often times variable substitutions are combined with numeric variables referencing fields.

The following uses the first field as the default content of the second field, after removing the first whitespace and everything after:

Name: ${1:name}
Email: ${2:${1/\s.*//}}@${3:example.com}

Escaping

Since snippets can contain variables, which start with a $, literal $ characters must be written as \$.

When performing variable substitution, literal / characters must be written as \/.*

Plugins

The most powerful tool for adding completions are Python plugins.

Writing a plugin to provide completions involves implementing EventListener.on_query_completions() or ViewEventListener.on_query_completions().

import sublime
import sublime_plugin

class MyCompletions(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        if not view.match_selector(locations[0], "source.python"):
            return []

        available_completions = [
            "def",
            "class",
            "None",
            "True",
            "False"
        ]

        prefix = prefix.lower()

        out = []
        for comp in available_completions:
            if comp.lower().startswith(prefix):
                out.append(comp)

        return out

Asynchronous completions can be provided by on_query_completions() returning a sublime.CompletionList object.

Completion details, including kind metadata, are provided by on_query_completions() returning sublime.CompletionItem objects.

4050

Settings

“tab_completion” boolean : When enabled, pressing Tab will insert the best matching completion. When disabled, Tab will only trigger snippets or insert a tab character. Shift+Tab can be used to insert an explicit tab when tab_completion is enabled.

*Disabling this setting will not implicitly disable `auto_complete`.*

“auto_complete” boolean : Automatically show the completions popup when typing.

*This behavior is not influenced by the setting `tab_completion`.*

“auto_complete_size_limit” integer : If the file size in bytes of the current file is larger than this, the completions popup will not be automatically shown.

“auto_complete_delay” integer : The number of milliseconds to wait before showing the completions popup automatically.

“auto_complete_selector” string : A selector to limit when the completions popup will be automatically shown.

*Example:* `“meta.tag, source - comment - string.quoted.double.block - string.quoted.single.block - string.unquoted.heredoc”`

*The `“auto_complete_triggers”` setting may be used to re-enable the
automatic completions popup in specific situations.*

“auto_complete_triggers” array of objects : Provides explicit triggers for when to automatically show the completions popup.

Each object must contain the keys `“selector”` with a string value
containing a [selector](https://www.sublimetext.com/docs/selectors.html) to match the caret position against,
and a `“characters”` key with a string value specifying what characters
must be present to the left of the caret.

*Example:*

```
[
    {
        "selector": "text.html",
        "characters": "<"
    }
]
```

*Triggers will override the setting `auto_complete_selector`.*

“auto_complete_commit_on_tab” boolean : By default, auto complete will commit the current completion on Enter. This setting can be used to make it complete on Tab instead.

Completing on **Tab** is generally a superior option, as it removes
ambiguity between committing the completion and inserting a newline.

“auto_complete_with_fields” boolean : Controls if the completions popup is automatically shown when snippet fields are active. Only relevant if auto_complete_commit_on_tab is enabled.

“auto_complete_cycle” boolean : Controls what happens when pressing ⬆ while the first item in the completions popup is selected: if false, the popup is hidden, otherwise the last completion in the popup is selected.

Also causes the first completion to be selected when **⬇** is pressed on
the last completion.

“auto_complete_use_history” boolean : If previously-selected completions should be automatically selected.

“auto_complete_use_index” boolean 4052

: When enabled, the completions popup will show context-aware suggestions based on other files in the project.

“auto_complete_preserve_order” string 4052

: Controls how the auto complete results are reordered when typing:

- `“none”` – fully reorder the results according to how well the
  :   completion matches the typed text
- `“some”` – partially reorder the results, taking into account how
  :   well the completion matches whats typed, and likelihood of the
      completion
- `“strict”` – never reorder the results

“auto_complete_trailing_symbols” boolean 4050

: Add trailing symbols (e.g., ., ()) if the completion engine thinks they‘re likely enough.

“auto_complete_trailing_spaces” boolean 4050

: Add a space after completions if the completion engine thinks they‘re likely enough.

“auto_complete_include_snippets” boolean 4050

: Controls if snippets will not be included in the completions popup.

*When disabled, snippets can still be triggered by typing their tab trigger
in, and pressing **Tab** when the completion popup is not showing.*

“auto_complete_include_snippets_when_typing” boolean

.. since:: 4052 : When this is set to false, snippets won‘t be present in the completions popup when it is automatically triggered. They will be shown if it is manually triggered.

“ignored_snippets” array of strings 4050

: File Patterns specifying which snippet files to ignore.

*For example, to ignore all the default C++ snippets:*

```
[
    "C++/*"
]
```

Introducing our Git client Sublime Merge