Building Extensions
Contributing Languages
JavaScript API Reference

Documentation Release Notes

Changes to the documentation by Nova version.

This document outlines changes to the extension APIs by Nova version number.

Nova 12

Tree-sitter

CompletionContext

ParseTreeMatch and ParseTreeCapture

“Any” Query Predicates / Directives

A new set of “any” predicates / directives have been implemented for Tree-sitter queries. These are useful when working with captures which might match multiple parse tree nodes, such as on nodes using the regex-style * and + operators.

These will evaluate true if any of the nodes which are captured match, and act as counterparts to the existing “non-any” versions, which only evaluate true if all captured nodes match.

Predicates

Directives

Query Metadata for Captures

The Nova 12 release brings new APIs to JavaScript Completions providers which allow an extension developer to collect metadata about a document’s parse tree from the Tree-sitter highlights queries of their language extension.

Language queries have previously had the capability to set metadata on a matched parse tree node by using the set*! family of directives. Such metadata was, until now, only utilized by Nova’s syntax engine as a way for queries to specify contextual info (such as for symbolication).

Now, metadata can also be set on specific captures of a match. To do this, a capture name can be specified immediately preceding the variable parameter of the directive. For directives which already take a capture parameter to compare (such as #set-if-eq!), the existing parameter is being renamed compareCapture in documentation to clarify. Otherwise, the behavior of these directives remains the same.

For example, using the following directive will set variableName to variableValue on the captured node @myNode, if the text of the node @nodeToCompare is foobar:

(#set-if-eq! @nodeToCompare "foobar" @myNode "variableName" "variableValue")

Completion Provider API for Query Metadata

Additionally, extensions vending a Completion Provider via JavaScript can now access the metadata applied by a language’s “highlights” query during a completion request. This should allow completion provider logic to access much richer parse tree information.

The CompletionContext type has a new matches property, which is an array of ParseTreeMatch objects matched during evaluation of the relevant language’s highlights query when a completion request is made at the cursor’s location.

Each ParseTreeMatch object in the array has two properties: metadata and captures. The metadata is a simple object mapping metadata variable keys to values. The captures is a simple object mapping capture names to ParseTreeCapture objects. Each capture object, in turn, has a metadata property (containing any metadata set on that capture), as well as text (the text captured) and range (the range of the captured node). Note: the text property is the final result which may have been transformed by query directives (such as prefix!); the range is the range of the original text.

For example, taking the directive used above, a completion provider can access the metadata like so:

provideCompletionItems(editor, context) {
    var items = [];
    let matches = context.matches;
    for match of matches {
      let value = match.captures["myNode"].metadata["variableValue"];
      if value == "variableValue" {
        // Do something interesting!
      }
    }
    return items;
}

Nova 11

Tree-sitter

Nova 10

Tree-sitter

Crypto

Environment

FileSystem

Nova 9

Extension Manifest

DebugAdapterAction

DebugSession

DebugSessionCustomEvent

FileStats

FileSystem

Workspace

Nova 8

Path

Nova 7

CompletionItem

Nova 6

Workspace

Nova 5

AssistantsRegistry

ColorCandidate

ColorInformation

ColorInformationContext

ColorPresentation

ColorPresentationContext

Task

TaskActionResolveContext

Task Actions

TextEditor

TextEditorEdit

Nova 4

AssistantsRegistry

CompletionItem

Symbol

TaskResolvableAction

TaskActionResolveContext

Nova 3

AssistantsRegistry

Color

CompletionContext

ScopeSelector

TaskCommandAction

Nova 2

Extension Manifest

AssistantsRegistry

CompletionItem

LanguageClient

Task

TaskProcessAction

TextEdit

Nova 1.2

CompletionItem

Clipboard

Environment

TextEditor

← Previous

Getting Started

Next →

Debug Adapters
↑ Return to top