Completions

A completions definition can be used to add static and symbolic completions to a syntax language in the editor.

Completion definitions are XML documents defined in the Completions/ folder of an extension. The name of the file does not matter, but is most often reflects the set of the completions being added. If the completions are the base set for a language, the file will often be named after the syntax (such as HTML.xml for the set of HTML completions).

Completion definitions declare a top-level <completions> tag that contains the entirety of the rules for the definition, and are composed of two major components: Providers and Completions Sets. They may define multiple providers and multiple completion sets as needed.

Completion sets may be divided into two types: Static Completions and Symbolic Completions

Providers

A completion provider determines where specific completions should be offered based on logical rules about the document.

While typing, the editor will evaluate each provider against the current cursor location in a document. The providers that match will then have their completions filtered and offered in the completion list.

Providers are defined using a <provider> element within the top-level element, which may then contain several other types of sub-elements for matching rules and determining which completion sets will be used.

A provider may optionally provide a name attribute. This attribute is not used for any rule matching, and instead is provided for debugging purposes.

<provider name="css.attributes">
    <syntax>css</syntax>
    <selector>style.attribute-list, style.attribute.name</selector>
    <expression>(\b|-)[a-zA-Z0-9-]*</expression>
    
    <set>css.properties</set>
</provider>

Syntax

The <syntax> element defines the name of a syntax in which the provider will be valid. The contents of the element should be the identifying name of a validly registered syntax. Most often, completions that are bundle alongside a syntax will use that syntax’s name.

Multiple syntax elements may be provided, in which case the provider will be valid in more than one syntax.

Selector

The <selector> element defines a CSS-style selector expression that can be used to finely determine in which syntax scopes a provider is valid. These expressions match based on the scope name components used for syntax highlighting. If the selector does not match the current position in the document, the provider will not be used.

A provider may only define a single selector element.

The selector format support several operators and pseudo-selectors inspired by CSS, as well as some unique features:

When utilizing any inheritance operators, the inheritance tree referenced is the parse tree of the document.

Expression

The <expression> element defines a regular expression that is evaluated anchored to the end of the text preceding the cursor position. If the expression does not match, the provider will not be used.

The text matched by the expression will be used as the range to be used when filtering completions, and the range replaced or modified by inserting a completion. As such, the text matched by the expression must contain all the characters that will be valid to be replaced by the completion.

Any text that an extension author wishes to match using this expression that should not be considered part of the completing text should be matched within regular expression look-behinds or a simliar mechanism.

Expressions may successfully match and evaluate to an zero-length string, at which point all completions for a provider will be offered.

Sets

A provider may define one or more <set> elements to declare which static completion sets are filtered and shown to the user when matched. The text of the element should be the name of a static completion set defined by any completions definition.

Symbols

A provider may define one or more <symbols> elements to declare which symbolic completion sets are filtered and shown to the user when matched.

See Symbolic Completions for more information.

Captures

Captures are a special behavior of the selector expressions that allows a single provider to match multiple possible completion sets based on the contents of the evaluated text.

Using a :capture(variable) pseudo-selector on a specific component of the selector will “capture” its textual contents using a key named variable. This key may be any valid alphanumeric identifier, including underscores and dashes.

When defining completion sets (see below), these variables may then be used in a string formatting syntax to change the completion set used.

An example of this in action is the CSS attribute completion provider:

<provider name="values">
    <syntax>css</syntax>
    <selector>style.attribute:has-child(style.attribute.name:capture(property)) style.value</selector>
    <expression>(?&lt;!\!)(\b|-|\!)[a-zA-Z0-9-]*</expression>
    
    <set>css.values.all</set>
    <set>css.values.${property}</set>
</provider>

This provider defines a selector that is valid in a CSS attribute definition (such as after border:). The name of this element in the syntax grammar, defined by style.attribute.name, is captured into the variable property.

This variable is then used in a <set> element string formatting expression.

This allows the completion set to be determined based on the contents of the parse tree, so that requesting completions after a border: attribute will choose the completion set named css.values.border, which defines values valid only for the CSS border attribute.

Additionally, the provider includes the css.values.all set, which defines values valid for all CSS attributes.

Static Completions

Static completions are those that have predefined definitions unrelated to the documents in a user’s project, such as the standard library of a language or framework.

A <set> element within the top-level completions element of the definition defines a set of related completions and how they behave when inserted.

Each completion set defines a name attribute, used to reference the set in completion providers. Set names may contain the same set of characters as Scope names: alphanumeric characters, as well as the period, underscore, and dash.

Note: Static completion set names are defined globally to the parse and completion engine, much like syntax names.

As such, it is highly recommended that you name them in a specific way that is unlikely to confict with other languages and those provided by built-in and third-party extensions. It is common to name a completion set using the syntax or framework name in which they are valid, such as css.attributes.border or react-framework.stdlib.

<set name="javascript.classes">
    <completion string="Array" />
    <completion string="BigInt" />
    <completion string="BigInt64Array" />
    <completion string="BigUint64Array" />
    <completion string="Boolean" />
    […additional completions…]
</set>

This completion set defines JavaScript built-in class names. The <set> element contains multiple <completion> elements that define each completion item.

Each <completion> element within a static completion set defines one item that will be offered to a user in the completions list.

The string attribute of the element is the base text that will be used when filtering based on the originating provider’s expression, as well as the base text inserted if the item is chosen.

The behavior of how completion items are inserted when chosen may be further modified using Behaviors.

The visual appearance of a completion may be further modified by several attributes of the completion element:

Symbol

The symbol attribute declares the type of symbol icon displayed to the user for the item:

<set name="javascript.classes">
    <completion string="Array" symbol="class" />
    <completion string="BigInt" symbol="class" />
    <completion string="BigInt64Array" symbol="class" />
    <completion string="BigUint64Array" symbol="class" />
    <completion string="Boolean" symbol="class" />
    […additional completions…]
</set>

A completion that does not declare a symbol will not show a corresponding icon.

For convenience, this attribute may also be set on the <set> element to apply to all completion items within that do not otherwise override it:

<set name="javascript.classes" symbol="class">
    <completion string="Array" />
    <completion string="BigInt" />
    <completion string="BigInt64Array" />
    <completion string="BigUint64Array" />
    <completion string="Boolean" />
    […additional completions…]
</set>

Case Insensitivity

The case-insensitive attribute may be applied with a value of "true" to make the completion case-insensitive for matching. In this way, the completion will match text behind the cursor regardless of the case of that text.

Using | as the cursor, a case-insensitive completion using the string "Array" will match these expressions:

Deprecated

The deprecated element may be applied with a value of "true" to mark the completion as deprecated in the completions list. Deprecated completions are deemphasized to the user, allowing them to be available but denoting that their use is discouraged.

Behaviors

Behaviors are a conditional feature that allow completions to define how they are presented and inserted into the document based on the text around them.

A <completion> element may contain one or more <behavior> elements. This forms an ordered array of behaviors that will be matched against the state of the document where the insertion is to take place. The first behavior (if any) that matches will be used. In this way, behaviors should be ordered most-specific to least-specific. If no behavior matches, the completion will be inserted without modifications.

Consider the following completion item for the CSS rgb() function:

<completion string="rgb" symbol="function">
    <behavior suffix="\(">
        <append>($[])</append>
    </behavior>
</completion>

The item defines the rgb string that will be completed from user typing. There is one behavior defined within the item, indicating how the inserted text should be manipulated, using a suffix attribute and an <append> element (indicating the text will be appended to the completed text).

The suffix attribute defines that the behavior should only be used if the provided regular expression matches at the end of the completing text position. This can allow behaviors to be applied only when certain text is (or isn’t) ahead of the cursor. Here, the behavior is only applied if there is no ( parenthesis after the cursor.

The $[] is a shorthand syntax used in behaviors that indicates the editor should insert a token. When the completion is inserted, the cursor will automatically jump and select this token. By default, the token will be rendered using a simple ... ellipses icon. Placing text inside of the square brackets, such as $[colors] will render the token with that string within.

In this case, the behavior above appends a set of parenthesis with an insertion token inside, resulting in rgb(…) being inserted into the editor.

Static completion behaviors support several option attributes:

Static completion behaviors support several text manipulation options elements:

As a convenience, <behavior> elements may be added to the <set> element (generally at the top, but this is not enforced) to apply those behaviors to all completion items within that do not provide their own behaviors.

Symbolic Completions

Symbolic completions are those defined from the Symbols in the parse tree as well as the IDE’s workspace index.

Consider the following provider:

<provider name="javascript.string-formatting">
    <syntax>javascript</syntax>
    <selector>javascript.string-template</selector>
    <expression>(?&lt;=$\{)\b[a-zA-Z_][a-zA-Z0-9_]*</expression>
    
    <symbols type="variable,constant" />
</provider>

This provider defines completions for string formatting expressions within a JavaScript string, which take the form "this is a ${adjective} string!".

Here, the <symbols> element defines the types variable and constant. If this provider matches, it will offer all JavaScript variables and constants that are in currently in scope.

The full set of valid symbolic type identifiers are defined in the Symbol API reference.

More complex symbolic completions that affect how they are inserted into the document may be offered using Behaviors within each <symbols> element:

<provider name="javascript.properties">
    <syntax>javascript</syntax>
    <selector>*:not(string,comment)</selector>
    <expression>(?&lt;=\.)@?@?([a-zA-Z_][a-zA-Z0-9_]*)?</expression>
    
    <symbols type="function">
        <behavior>
            <arguments prefix="(" suffix=")" separator=", " />
        </behavior>
    </symbols>
    <symbols type="method">
        <behavior>
            <arguments prefix="(" suffix=")" separator=", " />
        </behavior>
    </symbols>
    <symbols type="property,getter,setter" />
    
    <set>javascript.properties</set>
</provider>

This provider will offer completions of JavaScript functions, methods, properties, getters, and setters.

For functions and methods, the behaviors define how indexed arguments for those symbols are written out into the document, including prepended and appended text and separators between tokens. See the Behaviors section for more information.

Behaviors

Behaviors are a conditional feature that allow completions to define how they are presented and inserted into the document based on the text around them.

A <symbols> element may contain one or more <behavior> elements. This forms an ordered array of behaviors that will be matched against the state of the document where the insertion is to take place. The first behavior (if any) that matches will be used. In this way, behaviors should be ordered most-specific to least-specific. If no behavior matches, the completion will be inserted without modifications.

Consider the following completion item for the CSS rgb() function:

<symbols type="method">
    <behavior prefix="(?&lt;=def\s)">
        <arguments prefix="(self" suffix=")" separator=", " prepend-separator="true" />
    </behavior>
    <behavior>
        <arguments prefix="(" suffix=")" separator=", " />
    </behavior>
</symbols>

The symbols element above defines symbolic completions for methods in Python. There are two behaviors defined within, indicating how the inserted text should be manipulated based on what text is after the cursor.

The prefix attribute defines that the behavior should only be used if the provided regular expression matches at the head of the completing text position using a regular expression lookbehind. This can allow behaviors to be applied only when certain text is (or isn’t) ahead of the cursor. Here, the first behavior is used if the literal text def appears befor the completion point. This affects how the arguments of the method are completed.

If the text def precedes the cursor, a method foo with two arguments (arg1 and arg2) will be inserted as def foo(self, arg1, arg2) (as in a method definition). If that text does not precede the cursor, it will be inserted as foo(arg1, arg2) (as in a method invocation).

Symbolic completion behaviors support several option attributes:

Symbolic completion behaviors support several text manipulation options elements: