.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _completions: *********** Completions *********** Sublime |nbsp| Text Completions provide a multi-faceted way to save typing and time by finishing words or inserting boilerplate text. You use completions by typing something while Sublime |nbsp| Text pays attention to the similarities of what you are typing, and what has already been typed. There are 2 main kinds of Completions. - Snippets are activated by typing a "key" prefix and then hitting [Tab]. When: - the choice is unambiguous (i.e. resolves to only one, or you supplied the exact key for a certain Snippet), and - the context of the cursor(s) is (are) a match for a :term:`Scope` specified in the ``.sublime-snippet`` file, the content of the Snippet is drawn from that Snippet file and inserted into the text where the cursor is. Snippets are covered more thoroughly :ref:`in the Snippets section `. Snippets are the preferred type of Completion when the boilerplate text they provide is be extensive (more than can be easily maintained in a Completions file). Snippets can also be inserted programmatically. This is an extremely powerful feature, allowing any number of Snippet variables to be computed on the fly, based on the current context. See :doc:`snippets` for more details. - All other Completion types involved a popup list just below the cursor that offers one or more choices, often including additional information about each item in the list, like what kind of Completion it is (function, variable, Snippet, etc.), annotations giving helpful hints about it, and sometimes even a link to more information about it. The source of these types of Completions may be drawn from a number of sources (in priority order): - Snippet files (when the exact "tab trigger key" was not supplied, or ``[Ctrl+Space]`` was used instead of [Tab]) - Plugins (via ``on_query_completions`` event hooks) - Completion files - Context-aware suggestions (words from the current file, as of build 4050) `A large number settings `_ exist to customize the behavior of Completions. Like most everything else in Sublime |nbsp| Text, Completions can be extensively customized, and users can create their own. Many third-party :term:`Packages ` exist to provide Completions for specific editing contexts (e.g. with a programming or formatting/layout language). Using Completions ***************** When Completions are active, there is a popup list just below the cursor enabling you to select from the list with the mouse or [UpArrow] and [DownArrow] keys, and hit [Tab] or [Enter] to accept the current entry (the ``auto_complete_commit_on_tab`` setting's Boolean value controls which one), or [Esc] to close the Completions popup list and continue typing. If the Completions popup list is not visible and you want it to be, you can open it in one of 2 ways: :[Ctrl+Space]: opens the Completions popup list :[Tab]: completes the string left of the cursor with a Completion or Snippet if there is only one choice, or opens the Completions popup if there is more than one choice. (If the ``tab_completion`` setting is ``false``, [Tab] will only work to trigger Snippets, not Completions.) The Completions popup list items can be adorned (on the right) with annotations that indicate the meaning of each item, and the end of the list can sometimes display a clickable link about the selected item, or other information provided via the details_ key of a Completion object in a Completions file. .. note:: 1. The Completions popup list may be opened when there are multiple cursors, but this will only happen if each cursor shares identical trigger context (text and scope). 2. If your cursor is after some trigger text and you instead want to insert an actual ``\t`` character, hold the [Shift] key while hitting [Tab]. [1]_ .. [1] As of 10-Jun-2025, the ``sublime-rst-completions`` Package had a bug in handling the [shift+tab] Key Binding. This was fixed in its `pull request #108`_. Specifically it was failing to honor the conditions under which [shift+tab] should perform an "unindent" rather than insert a "\\t" character when any of the following are true: A) multiple lines are selected, B) the cursor is at the beginning of the line possibly preceded by tabs and/or spaces, or C) the "shift_tab_unindent" setting is ``true``. If your ``sublime-rst-completions`` Package is causing problematic behavior with the [shift+tab] key binding, simply install the fix submitted in `pull request #108`_. Creating Your Own Completions ***************************** Sublime text uses the following to supply the Completions popup with a list of likely candidates: - any Snippet files whose scope applies to the current editing context, - any Completion files whose scope applies to the current editing context, - the content of the current file. If you want to supplement that list, you can do so in any of 3 ways: - create a Snippet file (see :ref:`Snippets` for details), - create a Completions file (see below for details), and/or - manage Completions from a Plugin (see `Implementing Completions in a Plugin`_ for details). Using the latter has the most flexibility and even allows you to suppress automatically-supplied Completion-list items (source from words the buffer) if desired. .. _completions file format: Completions File Format *********************** ``.sublime-completions`` files use this :term:`Sublime-relaxed-JSON format`: .. code-block:: text { "scope": "selector_defining_when_this_list_is_active", "completions": [ { completion_object }, { completion_object }, { completion_object }, { completion_object }, { completion_object }, { completion_object }, ... ] } See :doc:`selectors` for details about the syntax for the "scope" entry. ``completion_object`` is a dictionary object with these entries: +--------------+-----------------------------------------------------------------+ | Key | Value | +==============+=================================================================+ | "trigger" | required, trigger string | +--------------+-----------------------------------------------------------------+ | "contents" | required, :ref:`smart-template syntax` described with Snippets | +--------------+-----------------------------------------------------------------+ | "kind" | optional, string or 3-element array of strings described below | +--------------+-----------------------------------------------------------------+ | "annotation" | optional, annotation described below | +--------------+-----------------------------------------------------------------+ | "details" | optional, single-line description; may contain basic formatting | | | HTML tags | +--------------+-----------------------------------------------------------------+ Trigger ======= The trigger string (or an approximation of it) must immediately precede the cursor. This string provides the first "filter" as to what is placed in the Completions list. If the string in the text is only the beginning (or a partial string), fuzzy matches are done to build the Completions list with likely candidates. Contents ======== The syntax of the "contents" value is described fully in the :ref:`smart-template syntax` section. The only difference is that it must be entirely contained in a JSON string (in the Completions file) rather than as free-form text inside an XML CDATA tag, as it is for a Snippets file. Line endings are added by including newline characters in the string like this: "line1\nline2\nline3". Kind ==== If "kind" is a single string, it must be one of these: - "ambiguous" - "function" - "keyword" - "markup" - "namespace" - "navigation" - "snippet" - "type" - "variable" If "kind" 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 (opened by hovering the mouse over the "kind" letter), and the detail pane at the bottom of the list (when visible). Example: "kind": ["function", "m", "Method"] Annotation ========== If provided, the "annotation" entry contains a short textual "hint", shown to right of the completions popup list item, giving the end user a reminder about what it is, helping him to differentiate it from other similar Completion items that might also be in the list. Details ======= If provided, the "details" entry contains at most one line of text with a very brief description (beyond the annotation) to help the user understand the purpose of that Completion item in the list. That line of text will appear at the bottom of the list in the "detail pane" when it is visible. That text may contain any of the following HTML tags - --- `miniHTML Protocols`_ - - - - - - - If an anchor tag is included, remember that the quotation marks containing the ``href`` value must be escaped since they will be inside of a JSON string (the Completions file contains JSON data). The link text will be shown in the Completion list's "detail pane" when it is visible. Example ======= Here is a ``.sublime-completions`` file with examples of each field: .. code-block:: json { "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-async function definition" } ] } .. _completions in a plugin: Implementing Completions in a Plugin ************************************ Plugins provide the widest flexibility in implementing and managing Completions. Special handling for the end user clicking links in the detail pane can be provided via a :term:`Plugin`: a callback can be specified via the API to handle clicks on anchor tags. See the following API elements for how this is done: - sublime.add_regions() ``on_navigate`` argument - sublime.show_popup() ``on_navigate`` argument - sublime.Phantom() ``on_navigate`` argument Study this Python code presented in OdatNurd video [P101-14] about implementing Completions in a Plugin. Remember that your class' needs to inherit from one of the following: - ``sublime_plugin.EventListener`` (instantiated once [for whole ST application]) - ``sublime_plugin.ViewEventListener`` (instantiated once per VIEW object) - ``sublime_plugin.TextChangeListener`` (instantiated ONCE per BUFFER object) And note that it will need to be filtered by using the ``is_applicable()`` and other event callback functions. See OdatNurd `P101 lessons 11-16 `__ on safely harnessing Sublime |nbsp| Text events: .. code-block:: python def on_query_completions(self, view, prefix, locations): # We get called in every view we apply to; if it matters, we should # make sure our completions are relevant for the current location # or file type. # if not view.match_selector(0, "source.python"): # return None # if not view.match_selector(locations[0], "source.python"): # return None if not all(view.match_selector(pt, "source.python") for pt in locations): return None print(f'prefix=[{prefix}] locations=[{locations}]') #return [["something"], ["otherthing"]] # return [ # ["something", "something()"], # ["otherthing", "otherthing()"] # ] # return [ # ["something\thelper function", "something()"], # ["otherthing\thelper function", "otherthing()"] # ] # $0 is where cursor is placed after completion, and # ${TM_FILENAME} is the name of the file being edited (stem + ext). # These "variables" work the same way as they do for Snippets. # return [ # ["something\thelper function", "something($0)"], # ["otherthing\thelper function", "otherthing('${TM_FILENAME}')"] # ] # NONE = 0 # INHIBIT_WORD_COMPLETIONS = 8 # Prevent Sublime |nbsp| Text from showing completions based on # the contents of the view. # INHIBIT_EXPLICIT_COMPLETIONS = 16 # Prevent Sublime |nbsp| Text from showing completions based on # :path:`.sublime-completions` files. # DYNAMIC_COMPLETIONS = 32 # If completions should be re-queried as the user types. # .. since:: 4057 # INHIBIT_REORDER = 128 # Prevent Sublime |nbsp| Text from changing the completion order. return ([ ["something\thelper function", "something($0)"], ["otherthing\thelper function", "otherthing('${TM_FILENAME}')"] ], sublime.AutoCompleteFlags.INHIBIT_WORD_COMPLETIONS \ | sublime.AutoCompleteFlags.INHIBIT_EXPLICIT_COMPLETIONS ) Further Reading *************** There are a large number of Sublime |nbsp| Text's settings that control behavior of Completions. These are well documented here: https://www.sublimetext.com/docs/completions.html#settings