Variables & Expressions

When running tasks and resolving the arguments to provide, the IDE has the ability to evaluate certain strings against a set of built-in variables and expressions, allowing some options to be specified using knowledge only available at runtime.


These are the primary set of variables available to all evaluation contexts:

Configuration Expressions

String substitution may reference values stored in the user’s global and project configuration using an expression of the form $(Config:my.config-key), where my.config-key is a key for a configuration item. Expressions of this form will check the most specific configuration available first, falling back if no value is found.

The order of precedence for configurations is:

If no value is found within a configuration, the default will be returned (if one is defined) before moving on to the next context. If no value is found, an empty string will be substituted.

Command Expressions

For more complex handling of substitution, an extension Command may be invoked. This command need not be defined in an extension’s visible commands object in its extension.json file, it only needs to be registered with the extension’s CommandsRegistry.

Commands may be invoked by using an expression of the form $(Command:my.command-name), where my.command-name is the name of the command used to register with the nova.commands.add() of the commands registry. The command will then be invoked asynchronously by the extension runtime. If it returns a Promise object, the runtime will wait for the promise to resolve before peforming the string substitution, unless the task requesting it is cancelled before the promise resolves.