Snippets

Nova’s editor supports a format for placeholder management known as the Snippets format. This format is in part based on the TextMate editor’s snippet support. This format allows Nova’s Clips feature and Completions to intelligently insert placeholders into the editor that allow rich user interaction.

API Format Support

The Snippets format is supported in the following places:

• Clips, both user-created and those provided by extensions
• The CompletionItem API through the insertTextFormat property
• The TextEditor API through the insert() method
• The LanguageClient API through the LSP specification’s InsertTextFormat enumeration

Support for the Snippets format was added to the Extension API in Nova 1.2.

Format

The Snippets format uses a special placeholder syntax defined by the use of the dollar sign and (in certain cases) curly braces.

Tab Stops

Tab stops allow the editor cursor to move inside a snippet. Use $0, $1, $2, etc. to specify cursor locations. The number is the order in which tab stops will be visited. Multiple tab stops with the same numeric value are linked and update together as the user types.

Placeholders

Placeholders are tab stops with a visible value, such as ${1:foo}. The placeholder text will be inserted within a token such that it can be chosen by pressing Return while the token is selected.

Variables

With $name or ${name:default} you can insert the value of a variable. When a variable isn’t set, its default or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder.

The set of available variables differs depending on which area of the IDE the snippet is being evaluated.

• For Clips and text inserted using the InsertTextFormat.Snippet format, the available variables are documented below.
• For Task Templates, the available variables are documented here

Variables Available to the Extension API

The following variables are supported from snippets in both the Nova Clips JSON format as well as when using the InsertTextFormat.Snippets API:

• SELECTED_TEXT: The currently selected text or the empty string
• DATE: The current date in the user’s standard locale format
• FILENAME: The filename of the current document
• FILE_PATH: The full file path of the current document
• PARENT_FOLDER: The directory of the current document
• WORKSPACE_NAME: The name of the current workspace
• AUTHOR_NAME: The user’s displayable name from either source control or user account
• SCM_REVISION: The current source control revision ID
• PREVIOUS_TEXT: The word directly preceding the cursor or the empty string
• PASTEBOARD_TEXT: The text that is currently on the user’s pasteboard or the empty string