CommandsRegistry

The CommandsRegistry class is used to register and invoke extension commands. A shared instance of the class is always available as the nova.commands environment property.

How Commands Handle Arguments

All commands receive at least one argument, whose type changes depending on the context in which it was invoked, and commands can also optionally receive additional arguments based on context as well.

There is a general set of rules for the arguments of commands:

• The callback of most commands will receive the current Workspace as its first argument.
  • The only time this is not true is for commands invoked from the Editor menu, for legacy reasons.
• Any additional arguments for a command will succeed this, in the order they were specified by the caller.

For commands that appear in the Editor menu, this can cause a different first object to be delivered, as those commands typically expect a TextEditor object. Commands can test the type of their first argument using the TextEditor.isTextEditor() class method.

Supported Types for Arguments

Commands can be invoked between the application IDE and the extension host in many different ways. Because of this, arbitrary JavaScript objects are not supported as arguments to commands, as the caller may exist in a separate execution context from the extension’s JavaScript sandbox.

Arguments to commands must adhere to a specific set of value types, which include all JSON-codable types as well as several types that can be easily transferred between execution contexts. Container types (arrays and bare objects) are supported as long as all of their contents are also transferrable. For bare objects, their keys must also be strings. If any of these conditions are not met for an argument, an Error will be thrown when the command is invoked.

As of Nova 3, the supported set of transferrable types are:

• Array (as long as all contained types are also transferrable)
• Date
• Null
• Number
• Object (as long as the object is bare, its keys are strings, and all values are also transferrable)
• RegExp
• String
• Color
• Range

(Prior to Nova 3, the set of supported types was limited to only JSON-codable values.)

Methods

register(name, callable, [thisValue])

Registers a command with the registry, making it available for binding to command palette and menu items declared in the extension’s extension.json file.

If the command should be user-visible, the name argument should match a command declared in the extension manifest.

The callable will be invoked with a different first argument depending on the category / context in which the command is defined:

• Commands that are present in the Editor menu (using the editor commands category) will receive the focused TextEditor object
• Commands appearing in all other categories will receive the current Workspace object
• Commands that are not defined in the manifest will receive the current Workspace object

The optional thisValue argument may be used to set what this is bound to when the callable is invoked. If omitted, this will be undefined.

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

invoke(name, [argument…])

Invokes the command registered for a given name, if any.

The command’s callback will be invoked as if the user had chosen it from the Extensions menu (or command palette).

The first argument the command’s callback receives will be the current Workspace. Additional arguments provided to this method will be delivered to the command after this workspace argument, assuming they are valid to be transferred to the command.

See above for more information on how arguments are handled.

This method returns a Promise object that resolves to the result of invoking the command. If no command is registered for the name, the promise will be rejected with an error.