AssistantsRegistry

The AssistantsRegistry class is used to register and invoke assistants, which can provide specific extension functionality within the editor. A shared instance of the class is always available as the nova.assistants environment property.

Selectors

Some assistant registration methods takes a selector argument that specifies when the assistant is applicable. This value may be a string, an object, or an array of either.

If a selector is a string, it should be the name of a language syntax, such as "javascript". The assistant will then apply to all JavaScript documents. The special string "*" may be used to match all available syntaxes.

If a selector is an object, it may have the following properties:

By using an array, you may specify multiple selectors that may match (for example, for multiple syntaxes):

let selectors = ["javascript", "jsx", "typescript", "tsx"] // string values

let selectors = [{syntax: "javascript"}, {syntax: "jsx"}, {syntax: "typescript"}, {syntax: "tsx"}] // object values

Methods

registerColorAssistant(selector, object)

Registers a color assistant, which can provide document color information to the editor’s color picker.

This method returns a Disposable that can be used to unregister the assistant.

The object provided should conform to the following interface:

interface ColorAssistant {
    provideColors(editor, context);
    provideColorPresentations(color, editor, context);
}

Added in Nova 5.

provideColors(editor, context)

This method requests document color information for an editor.

The provideColors method of the assistant should take as an argument the TextEditor instance requesting color information, and a ColorInformationContext providing contextual information, and then return an array of ColorInformation objects, or a Promise resolving to such.

provideColorPresentations(color, editor, context)

This method requests color presentations for a color object.

The provideColorPresentations method of the assistant should take as an argument the Color instance being transformed, the TextEditor instance that is requesting presentations, and a ColorPresentationContext providing contextual information, and then return an array of ColorPresentation objects, or a Promise resolving to such.

An assistant may return one or more color presentation objects for the color to represent different “formats” the color may be represented as, such as the various color functions in CSS (rgb(), rgba(), hsl(), etc.).

registerCompletionAssistant(selector, object[, options])

Registers a completion assistant, which can provide completion items to the editor’s autocomplete list.

This method returns a Disposable that can be used to unregister the assistant.

The object provided should conform to the following interface:

interface CompletionAssistant {
    provideCompletionItems(editor, context);
}

Completion Assistant Options

The options parameter is optional, and can be an Object with the following properties:

provideCompletionItems(editor, context)

The provideCompletionItems method of the assistant should take as an argument the TextEditor instance requesting completion, and a CompletionContext object.

This method should return an array of the following object types, or a Promise resolving to such:

• CompletionItem: A completions item that can be inserted into the editor
• CompletionColorPop: A color pop that can be displayed to mix and choose colors

registerIssueAssistant(selector, object[, options])

Registers an issue assistant, which can provide diagnostic issues to the editor.

This method returns a Disposable that can be used to unregister the assistant.

The object provided should conform to the following interface:

interface IssueAssistant {
    provideIssues(editor);
}

Issue Assistant Options

The options parameter is optional, and can be an Object with the following properties:

Issue Request Events

The event option for issue assistants provided at registration time can affect when the editor asks for issues from the assistant:

• "onChange": Issues are requested shortly after the user stops typing (this is the default)
• "onSave": Issues are requested after each time the document is saved

Some issue assistants may be better suited to operating when the user saves a document as opposed to when the user changes a document. For best results, consider offering an option in an extension’s global or workspace configuration that allows this to be changed by the user.

provideIssues(editor)

The provideIssues method of the assistant should take as an argument the TextEditor instance requesting completion and return an array of Issue objects, or a Promise resolving to such.

registerTaskAssistant(object[, options])

Added in Nova 2.

Registers a Task Assistant, which can provide tasks to the IDE.

This method returns a Disposable that can be used to unregister the assistant.

The object provided should conform to the following interface:

interface TaskAssistant {
    provideTasks();
}

The options parameter is optional, and can be an Object with the following properties:

provideTasks()

The provideTasks method of the assistant should return an array of Task objects.

resolveTaskAction(context)

Invoked when a TaskResolvableAction is run by the user to provide the actual action that should be invoked.

The context parameter is an instance of the TaskActionResolveContext class, and provides contextual information about the action being resolved.

This method should return a more concrete instance of a task action (such as a TaskProcessAction), which will be invoked as if it had been provided when the task was created. This method may also return a Promise that resolves to such an action.

Returning null, undefined, or another instance of a resolvable action will cause the task invocation to fail.

Added in Nova 4.