Question

commands

Namespace for dealing with commands. In short, a command is a function with a unique identifier. The function is sometimes also called command handler.

Commands can be added to the editor using the registerCommand and registerTextEditorCommand functions. Commands can be executed manually or from a UI gesture. Those are:

• palette - Use the commands-section in package.json to make a command show in the command palette.
• keybinding - Use the keybindings-section in package.json to enable keybindings for your extension.

Commands from other extensions and from the editor itself are accessible to an extension. However, when invoking an editor command not all argument types are supported.

This is a sample that registers a command handler and adds an entry for that command to the palette. First register a command handler with the identfier extension.sayHello.

commands.registerCommand('extension.sayHello', () => {
        window.showInformationMessage('Hello World!');
});

Second, bind the command identfier to a title under which it will show in the palette (package.json).

{
"contributes": {
        "commands": [{
        "command": "extension.sayHello",
        "title": "Hello World"
    }]
}

Functions

executeCommand<T>(command: string, ...rest: any[]): Thenable<T>

Executes the command denoted by the given command identifier.

When executing an editor command not all types are allowed to be passed as arguments. Allowed are the primitive types string, boolean, number, undefined, and null, as well as classes defined in this API. There are no restrictions when executing commands that have been contributed by extensions.

Parameter	Description
command: string	Identifier of the command to execute.
...rest: any[]	Parameters passed to the command function.
Returns	Description
Thenable<T>	A thenable that resolves to the returned value of the given command. undefined when the command handler function doesn't return anything.

getCommands(filterInternal?: boolean): Thenable<string[]>

Retrieve the list of all available commands. Commands starting an underscore are treated as internal commands.

Parameter	Description
filterInternal?: boolean	Set true to not see internal commands (starting with an underscore)
Returns	Description
Thenable<string[]>	Thenable that resolves to a list of command ids.

registerCommand(command: string, callback: (args: any[]) => any, thisArg?: any): Disposable

Registers a command that can be invoked via a keyboard shortcut, a menu item, an action, or directly.

Registering a command with an existing command identifier twice will cause an error.

Parameter	Description
command: string	A unique identifier for the command.
callback: (args: any[]) => any	A command handler function.
thisArg?: any	The this context used when invoking the handler function.
Returns	Description
Disposable	Disposable which unregisters this command on disposal.

registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit) => void, thisArg?: any): Disposable

Registers a text editor command that can be invoked via a keyboard shortcut, a menu item, an action, or directly.

Text editor commands are different from ordinary commands as they only execute when there is an active editor when the command is called. Also, the command handler of an editor command has access to the active editor and to an edit-builder.

Parameter	Description
command: string	A unique identifier for the command.
callback: (textEditor: TextEditor, edit: TextEditorEdit) => void	A command handler function with access to an editor and an edit.
thisArg?: any	The this context used when invoking the handler function.
Returns	Description
Disposable	Disposable which unregisters this command on disposal.

env

Namespace describing the environment the editor runs in.

Variables

language: string

Represents the preferred user-language, like de-CH, fr, or en-US.

• readonly

machineId: string

A unique identifier for the computer.

• readonly

sessionId: string

A unique identifier for the current session. Changes each time the editor is started.

• readonly

extensions

Namespace for dealing with installed extensions. Extensions are represented by an extension-interface which allows to reflect on them.

Extension writers can provide APIs to other extensions by returning their API public surface from the activate-call.

export function activate(context: vscode.ExtensionContext) {
        let api = {
            sum(a, b) {
                return a + b;
            },
            mul(a, b) {
                return a * b;
            }
        };
        // 'export' public api-surface
        return api;
}

When depending on the API of another extension add an extensionDependency-entry to package.json, and use the getExtension-function and the exports-property, like below:

let mathExt = extensions.getExtension('genius.math');
let importedApi = mathExt.exports;

console.log(importedApi.mul(42, 1));

Variables

all: Extension<any>[]

All extensions currently known to the system.

Functions

getExtension(extensionId: string): Extension<any>

Get an extension by its full identifier in the form of: publisher.name.

Parameter	Description
extensionId: string	An extension identifier.
Returns	Description
Extension<any>	An extension or undefined.

getExtension<T>(extensionId: string): Extension<T>

Get an extension its full identifier in the form of: publisher.name.

Parameter	Description
extensionId: string	An extension identifier.
Returns	Description
Extension<T>	An extension or undefined.

languages

Namespace for participating in language-specific editor features, like IntelliSense, code actions, diagnostics etc.

Many programming languages exist and there is huge variety in syntaxes, semantics, and paradigms. Despite that, features like automatic word-completion, code navigation, or code checking have become popular across different tools for different programming languages.

The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function that can be called with a TextDocument and a Position returning hover info. The rest, like tracking the mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor.

languages.registerHoverProvider('javascript', {
        provideHover(document, position, token) {
            return new Hover('I am a hover!');
        }
});

Registration is done using a document selector which is either a language id, like javascript or a more complex filter like { language: 'typescript', scheme: 'file' }. Matching a document against such a selector will result in a score that is used to determine if and how a provider shall be used. When scores are equal the provider that came last wins. For features that allow full arity, like hover, the score is only checked to be >0, for other features, like IntelliSense the score is used for determining the order in which providers are asked to participate.

Functions

createDiagnosticCollection(name?: string): DiagnosticCollection

Create a diagnostics collection.

Parameter	Description
name?: string	The name of the collection.
Returns	Description
DiagnosticCollection	A new diagnostic collection.

getLanguages(): Thenable<string[]>

Return the identifiers of all known languages.

Returns	Description
Thenable<string[]>	Promise resolving to an array of identifier strings.

match(selector: DocumentSelector, document: TextDocument): number

Compute the match between a document selector and a document. Values greater than zero mean the selector matches the document. The more individual matches a selector and a document have, the higher the score is. These are the abstract rules given a selector:

(1) When selector is an array, return the maximum individual result.
(2) When selector is a string match that against the [languageId](TextDocument.languageId).
    (2.1) When both are equal score is `10`,
    (2.2) When the selector is `*` score is `5`,
    (2.3) Else score is `0`.
(3) When selector is a [filter](#DocumentFilter) every property must score higher `0`. Iff the score is the sum of the following:
    (3.1) When [language](#DocumentFilter.language) is set apply rules from #2, when `0` the total score is `0`.
    (3.2) When [scheme](#Document.scheme) is set and equals the [uri](TextDocument.uri)-scheme add `10` to the score, else the total score is `0`.
    (3.3) When [pattern](#Document.pattern) is set
        (3.3.1) pattern eqauls the [uri](TextDocument.uri)-fsPath add `10` to the score,
        (3.3.1) if the pattern matches as glob-pattern add `5` to the score,
        (3.3.1) the total score is `0`

Parameter	Description
selector: DocumentSelector	A document selector.
document: TextDocument	A text document.
Returns	Description
number	A number >0 when the selector matches and 0 when the selector does not match.

registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider): Disposable

Register a code action provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: CodeActionProvider	A code action provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider): Disposable

Register a code lens provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: CodeLensProvider	A code lens provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider, ...triggerCharacters: string[]): Disposable

Register a completion provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and groups of equal score are sequentially asked for completion items. The process stops when one or many providers of a group return a result. A failing provider (rejected promise or exception) will not fail the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: CompletionItemProvider	A completion provider.
...triggerCharacters: string[]	Trigger completion when the user types one of the characters, like . or :.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable

Register a definition provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: DefinitionProvider	A definition provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable

Register a formatting provider for a document.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the result of best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: DocumentFormattingEditProvider	A document formatting edit provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable

Register a document highlight provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and groups sequentially asked for document highlights. The process stops when a provider returns a non-falsy or non-failure result.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: DocumentHighlightProvider	A document highlight provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable

Register a formatting provider for a document range.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the result of best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: DocumentRangeFormattingEditProvider	A document range formatting edit provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider): Disposable

Register a document symbol provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: DocumentSymbolProvider	A document symbol provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable

Register a hover provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: HoverProvider	A hover provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable

Register a formatting provider that works on type. The provider is active when the user enables the setting editor.formatOnType.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the result of best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: OnTypeFormattingEditProvider	An on type formatting edit provider.
firstTriggerCharacter: string	A character on which formatting should be triggered, like }.
...moreTriggerCharacter: string[]	More trigger characters.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable

Register a reference provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: ReferenceProvider	A reference provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable

Register a reference provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the result of best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: RenameProvider	A rename provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable

Register a signature help provider.

Multiple providers can be registered for a language. In that case providers are sorted by their score and the result of best-matching provider is used. Failure of the selected provider will cause a failure of the whole operation.

Parameter	Description
selector: DocumentSelector	A selector that defines the documents this provider is applicable to.
provider: SignatureHelpProvider	A signature help provider.
...triggerCharacters: string[]	Trigger signature help when the user types one of the characters, like , or (.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider): Disposable

Register a workspace symbol provider.

Multiple providers can be registered for a language. In that case providers are asked in parallel and the results are merged. A failing provider (rejected promise or exception) will not cause a failure of the whole operation.

Parameter	Description
provider: WorkspaceSymbolProvider	A workspace symbol provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable

Set a language configuration for a language.

Parameter	Description
language: string	A language identifier like typescript.
configuration: LanguageConfiguration	Language configuration.
Returns	Description
Disposable	A disposable that unsets this configuration.

window

Namespace for dealing with the current window of the editor. That is visible and active editors, as well as, UI elements to show messages, selections, and asking for user input.

Variables

activeTextEditor: TextEditor

The currently active editor or undefined. The active editor is the one that currently has focus or, when none has focus, the one that has changed input most recently.

visibleTextEditors: TextEditor[]

The currently visible editors or an empty array.

Events

onDidChangeActiveTextEditor: Event<TextEditor>

An event which fires when the active editor has changed.

onDidChangeTextEditorOptions: Event<TextEditorOptionsChangeEvent>

An event which fires when the options of an editor have changed.

onDidChangeTextEditorSelection: Event<TextEditorSelectionChangeEvent>

An event which fires when the selection in an editor has changed.

onDidChangeTextEditorViewColumn: Event<TextEditorViewColumnChangeEvent>

An event which fires when the view column of an editor das changed.

Functions

createOutputChannel(name: string): OutputChannel

Create a new output channel with the given name.

Parameter	Description
name: string	Human-readable string which will be used to represent the channel in the UI.
Returns	Description
OutputChannel

createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem

Creates a status bar item.

Parameter	Description
alignment?: StatusBarAlignment	The alignment of the item.
priority?: number	The priority of the item. Higher values mean the item should be shown more to the left.
Returns	Description
StatusBarItem	A new status bar item.

createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType

Create a TextEditorDecorationType that can be used to add decorations to text editors.

Parameter	Description
options: DecorationRenderOptions	Rendering options for the decoration type.
Returns	Description
TextEditorDecorationType	A new decoration type instance.

setStatusBarMessage(text: string): Disposable

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Parameter	Description
text: string	The message to show, support icon subtitution as in status bar items.
Returns	Description
Disposable	A disposable which hides the status bar message.

setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Parameter	Description
text: string	The message to show, support icon subtitution as in status bar items.
hideAfterTimeout: number	Timeout in milliseconds after which the message will be disposed.
Returns	Description
Disposable	A disposable which hides the status bar message.

setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable

Set a message to the status bar. This is a short hand for the more powerful status bar items.

Parameter	Description
text: string	The message to show, support icon subtitution as in status bar items.
hideWhenDone: Thenable<any>	Thenable on which completion (resolve or reject) the message will be disposed.
Returns	Description
Disposable	A disposable which hides the status bar message.

showErrorMessage(message: string, ...items: string[]): Thenable<string>

Show an error message.

• see - showInformationMessage

Parameter	Description
message: string	The message to show.
...items: string[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<string>	A thenable that resolves to the selected item or undefined when being dismissed.

showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T>

Show an error message.

• see - showInformationMessage

Parameter	Description
message: string	The message to show.
...items: T[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<T>	A thenable that resolves to the selected item or undefined when being dismissed.

showInformationMessage(message: string, ...items: string[]): Thenable<string>

Show an information message to users. Optionally provide an array of items which will be presented as clickable buttons.

Parameter	Description
message: string	The message to show.
...items: string[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<string>	A thenable that resolves to the selected item or undefined when being dismissed.

showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T>

Show an information message.

• see - showInformationMessage

Parameter	Description
message: string	The message to show.
...items: T[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<T>	A thenable that resolves to the selected item or undefined when being dismissed.

showInputBox(options?: InputBoxOptions): Thenable<string>

Opens an input box to ask the user for input.

The returned value will be undefined if the input box was canceled (e.g. pressing ESC). Otherwise the returned value will be the string typed by the user or an empty string if the user did not type anything but dismissed the input box with OK.

Parameter	Description
options?: InputBoxOptions	Configures the behavior of the input box.
Returns	Description
Thenable<string>	A promise that resolves to a string the user provided or to undefined in case of dismissal.

showQuickPick(items: string[] | Thenable<string[]>, options?: QuickPickOptions): Thenable<string>

Shows a selection list.

Parameter	Description
items: string[] | Thenable<string[]>	An array of strings, or a promise that resolves to an array of strings.
options?: QuickPickOptions	Configures the behavior of the selection list.
Returns	Description
Thenable<string>	A promise that resolves to the selection or undefined.

showQuickPick<T extends QuickPickItem>(items: T[] | Thenable<T[]>, options?: QuickPickOptions): Thenable<T>

Shows a selection list.

Parameter	Description
items: T[] | Thenable<T[]>	An array of items, or a promise that resolves to an array of items.
options?: QuickPickOptions	Configures the behavior of the selection list.
Returns	Description
Thenable<T>	A promise that resolves to the selected item or undefined.

showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor>

Show the given document in a text editor. A column can be provided to control where the editor is being shown. Might change the active editor.

Parameter	Description
document: TextDocument	A text document to be shown.
column?: ViewColumn	A view column in which the editor should be shown. The default is the one, other values are adjusted to be Min(column, columnCount + 1).
preserveFocus?: boolean	When true the editor will not take focus.
Returns	Description
Thenable<TextEditor>	A promise that resolves to an editor.

showWarningMessage(message: string, ...items: string[]): Thenable<string>

Show a warning message.

• see - showInformationMessage

Parameter	Description
message: string	The message to show.
...items: string[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<string>	A thenable that resolves to the selected item or undefined when being dismissed.

showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T>

Show a warning message.

• see - showInformationMessage

Parameter	Description
message: string	The message to show.
...items: T[]	A set of items that will be rendered as actions in the message.
Returns	Description
Thenable<T>	A thenable that resolves to the selected item or undefined when being dismissed.

workspace

Namespace for dealing with the current workspace. A workspace is the representation of the folder that has been opened. There is no workspace when just a file but not a folder has been opened.

The workspace offers support for listening to fs events and for finding files. Both perform well and run outside the editor-process so that they should be always used instead of nodejs-equivalents.

Variables

rootPath: string

The folder that is open in VS Code. undefined when no folder has been opened.

• readonly

textDocuments: TextDocument[]

All text documents currently known to the system.

• readonly

Events

onDidChangeConfiguration: Event<void>

An event that is emitted when the configuration changed.

onDidChangeTextDocument: Event<TextDocumentChangeEvent>

An event that is emitted when a text document is changed.

onDidCloseTextDocument: Event<TextDocument>

An event that is emitted when a text document is disposed.

onDidOpenTextDocument: Event<TextDocument>

An event that is emitted when a text document is opened.

onDidSaveTextDocument: Event<TextDocument>

An event that is emitted when a text document is saved to disk.

Functions

applyEdit(edit: WorkspaceEdit): Thenable<boolean>

Make changes to one or many resources as defined by the given workspace edit.

When applying a workspace edit, the editor implements an 'all-or-nothing'-strategy, that means failure to load one document or make changes to one document will cause the edit to be rejected.

Parameter	Description
edit: WorkspaceEdit	A workspace edit.
Returns	Description
Thenable<boolean>	A thenable that resolves when the edit could be applied.

asRelativePath(pathOrUri: string | Uri): string

Returns a path that is relative to the workspace root.

When there is no workspace root or when the path is not a child of that folder, the input is returned.

Parameter	Description
pathOrUri: string | Uri	A path or uri. When a uri is given its fsPath is used.
Returns	Description
string	A path relative to the root or the input.

createFileSystemWatcher(globPattern: string, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher

Creates a file system watcher.

A glob pattern that filters the file events must be provided. Optionally, flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed.

Parameter	Description
globPattern: string	A glob pattern that is applied to the names of created, changed, and deleted files.
ignoreCreateEvents?: boolean	Ignore when files have been created.
ignoreChangeEvents?: boolean	Ignore when files have been changed.
ignoreDeleteEvents?: boolean	Ignore when files have been deleted.
Returns	Description
FileSystemWatcher	A new file system watcher instance.

findFiles(include: string, exclude: string, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>

Find files in the workspace.

• sample - findFiles('**∕*.js', '**∕node_modules∕**', 10)

Parameter	Description
include: string	A glob pattern that defines the files to search for.
exclude: string	A glob pattern that defines files and folders to exclude.
maxResults?: number	An upper-bound for the result.
token?: CancellationToken	A token that can be used to signal cancellation to the underlying search engine.
Returns	Description
Thenable<Uri[]>	A thenable that resolves to an array of resource identifiers.

getConfiguration(section?: string): WorkspaceConfiguration

Get a configuration object.

When a section-identifier is provided only that part of the configuration is returned. Dots in the section-identifier are interpreted as child-access, like { myExt: { setting: { doIt: true }}} and getConfiguration('myExt.setting.doIt') === true.

Parameter	Description
section?: string	A dot-separated identifier.
Returns	Description
WorkspaceConfiguration	The full workspace configuration or a subset.

openTextDocument(uri: Uri): Thenable<TextDocument>

Opens the denoted document from disk. Will return early if the document is already open, otherwise the document is loaded and the open document-event fires. The document to open is denoted by the uri. Two schemes are supported:

file: A file on disk, will be rejected if the file does not exist or cannot be loaded, e.g. 'file:///Users/frodo/r.ini'. untitled: A new file that should be saved on disk, e.g. 'untitled:/Users/frodo/new.js'. The language will be derived from the file name.

Uris with other schemes will make this method return a rejected promise.

Parameter	Description
uri: Uri	Identifies the resource to open.
Returns	Description
Thenable<TextDocument>	A promise that resolves to a document.

openTextDocument(fileName: string): Thenable<TextDocument>

A short-hand for openTextDocument(Uri.file(fileName)).

• see - openTextDocument

Parameter	Description
fileName: string	A name of a file on disk.
Returns	Description
Thenable<TextDocument>	A promise that resolves to a document.

registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable

Register a text document content provider.

Only one provider can be registered per scheme.

Parameter	Description
scheme: string	The uri-scheme to register for.
provider: TextDocumentContentProvider	A content provider.
Returns	Description
Disposable	A disposable that unregisters this provider when being disposed.

saveAll(includeUntitled?: boolean): Thenable<boolean>

Save all dirty files.

Parameter	Description
includeUntitled?: boolean	Also save files that have been created during this session.
Returns	Description
Thenable<boolean>	A thenable that resolves when the files have been saved.

CancellationToken

A cancellation token is passed to an asynchronous or long running operation to request cancellation, like cancelling a request for completion items because the user continued to type.

To get an instance of a CancellationToken use a CancellationTokenSource.

Properties

isCancellationRequested: boolean

Is true when the token has been cancelled, false otherwise.

onCancellationRequested: Event<any>

An event which fires upon cancellation.

CancellationTokenSource

A cancellation source creates and controls a cancellation token.

Properties

token: CancellationToken

The cancellation token of this source.

Methods

cancel(): void

Signal cancellation on the token.

Returns	Description
void

dispose(): void

Dispose object and free resources. Will call cancel.

Returns	Description
void

CharacterPair

A tuple of two characters, like a pair of opening and closing brackets.

CharacterPair: [string, string]

CodeActionContext

Contains additional diagnostic information about the context in which a code action is run.

Properties

diagnostics: Diagnostic[]

An array of diagnostics.

• readonly

CodeActionProvider

The code action interface defines the contract between extensions and the light bulb feature.

A code action can be any command that is known to the system.

Methods

provideCodeActions(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken): Command[] | Thenable<Command[]>

Provide commands for the given document and range.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
range: Range	The range for which the command was invoked.
context: CodeActionContext	Context carrying additional information.
token: CancellationToken	A cancellation token.
Returns	Description
Command[] | Thenable<Command[]>	An array of commands or a thenable of such. The lack of a result can be signaled by returning undefined, null, or an empty array.

CodeLens

A code lens represents a command that should be shown along with source text, like the number of references, a way to run tests, etc.

A code lens is unresolved when no command is associated to it. For performance reasons the creation of a code lens and resolving should be done to two stages.

• see - CodeLensProvider.provideCodeLenses

• see - CodeLensProvider.resolveCodeLens

Constructors

new CodeLens(range: Range, command?: Command): CodeLens

Creates a new code lens object.

Parameter	Description
range: Range	The range to which this code lens applies.
command?: Command	The command associated to this code lens.
Returns	Description
CodeLens

Properties

command: Command

The command this code lens represents.

isResolved: boolean

true when there is a command associated.

range: Range

The range in which this code lens is valid. Should only span a single line.

CodeLensProvider

A code lens provider adds commands to source text. The commands will be shown as dedicated horizontal lines in between the source text.

Methods

provideCodeLenses(document: TextDocument, token: CancellationToken): CodeLens[] | Thenable<CodeLens[]>

Compute a list of lenses. This call should return as fast as possible and if computing the commands is expensive implementors should only return code lens objects with the range set and implement resolve.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
CodeLens[] | Thenable<CodeLens[]>	An array of code lenses or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

resolveCodeLens(codeLens: CodeLens, token: CancellationToken): CodeLens | Thenable<CodeLens>

This function will be called for each visible code lens, usually when scrolling and after calls to compute-lenses.

Parameter	Description
codeLens: CodeLens	code lens that must be resolved.
token: CancellationToken	A cancellation token.
Returns	Description
CodeLens | Thenable<CodeLens>	The given, resolved code lens or thenable that resolves to such.

Command

Represents a reference to a command. Provides a title which will be used to represent a command in the UI and, optionally, an array of arguments which will be passed to the command handler function when invoked.

Properties

arguments?: any[]

Arguments that the command handler should be invoked with.

command: string

The identifier of the actual command handler.

• see - commands.registerCommand.

title: string

Title of the command, like save.

CommentRule

Describes how comments for a language work.

Properties

blockComment?: CharacterPair

The block comment character pair, like /* block comment */

lineComment?: string

The line comment token, like // this is a comment

CompletionItem

A completion item represents a text snippet that is proposed to complete text that is being typed.

• see - CompletionItemProvider.provideCompletionItems

• see - CompletionItemProvider.resolveCompletionItem

Constructors

new CompletionItem(label: string): CompletionItem

Creates a new completion item.

Completion items must have at least a label which then will be used as insert text as well as for sorting and filtering.

Parameter	Description
label: string	The label of the completion.
Returns	Description
CompletionItem

Properties

detail: string

A human-readable string with additional information about this item, like type or symbol information.

documentation: string

A human-readable string that represents a doc-comment.

filterText: string

A string that should be used when filtering a set of completion items. When falsy the label is used.

insertText: string

A string that should be inserted in a document when selecting this completion. When falsy the label is used.

kind: CompletionItemKind

The kind of this completion item. Based on the kind an icon is chosen by the editor.

label: string

The label of this completion item. By default this is also the text that is inserted when selecting this completion.

sortText: string

A string that should be used when comparing this item with other items. When falsy the label is used.

textEdit: TextEdit

An edit which is applied to a document when selecting this completion. When an edit is provided the value of insertText is ignored.

The range of the edit must be single-line and one the same line completions where requested at.

CompletionItemKind

Completion item kinds.

Enumeration members

Class

Color

Constructor

Enum

Field

File

Function

Interface

Keyword

Method

Module

Property

Reference

Snippet

Text

Unit

Value

Variable

CompletionItemProvider

The completion item provider interface defines the contract between extensions and the IntelliSense.

When computing complete completion items is expensive, providers can optionally implement the resolveCompletionItem-function. In that case it is enough to return completion items with a label from the provideCompletionItems-function. Subsequently, when a completion item is shown in the UI and gains focus this provider is asked to resolve the item, like adding doc-comment or details.

Methods

provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken): CompletionItem[] | Thenable<CompletionItem[]> | CompletionList | Thenable<CompletionList>

Provide completion items for the given position and document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
CompletionItem[] | Thenable<CompletionItem[]> | CompletionList | Thenable<CompletionList>	An array of completions, a completion list, or a thenable that resolves to either. The lack of a result can be signaled by returning undefined, null, or an empty array.

resolveCompletionItem(item: CompletionItem, token: CancellationToken): CompletionItem | Thenable<CompletionItem>

Given a completion item fill in more data, like doc-comment or details.

The editor will only resolve a completion item once.

Parameter	Description
item: CompletionItem	A completion item currently active in the UI.
token: CancellationToken	A cancellation token.
Returns	Description
CompletionItem | Thenable<CompletionItem>	The resolved completion item or a thenable that resolves to of such. It is OK to return the given item. When no result is returned, the given item will be used.

CompletionList

Represents a collection of completion items to be presented in the editor.

Constructors

new CompletionList(items?: CompletionItem[], isIncomplete?: boolean): CompletionList

Creates a new completion list.

Parameter	Description
items?: CompletionItem[]	The completion items.
isIncomplete?: boolean	The list is not complete.
Returns	Description
CompletionList

Properties

isIncomplete: boolean

This list it not complete. Further typing should result in recomputing this list.

items: CompletionItem[]

The completion items.

DecorationOptions

Represents options for a specific decoration in a decoration set.

Properties

hoverMessage: MarkedString | MarkedString[]

A message that should be rendered when hovering over the decoration.

range: Range

Range to which this decoration is applied.

DecorationRenderOptions

Represents rendering styles for a text editor decoration.

Properties

backgroundColor?: string

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations.

borderColor?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderRadius?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderSpacing?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderStyle?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderWidth?: string

CSS styling property that will be applied to text enclosed by a decoration.

color?: string

CSS styling property that will be applied to text enclosed by a decoration.

cursor?: string

CSS styling property that will be applied to text enclosed by a decoration.

dark?: ThemableDecorationRenderOptions

Overwrite options for dark themes.

gutterIconPath?: string

An absolute path to an image to be rendered in the gutterIconPath.

isWholeLine?: boolean

Should the decoration be rendered also on the whitespace after the line text. Defaults to false.

letterSpacing?: string

CSS styling property that will be applied to text enclosed by a decoration.

light?: ThemableDecorationRenderOptions

Overwrite options for light themes.

outlineColor?: string

CSS styling property that will be applied to text enclosed by a decoration.

outlineStyle?: string

CSS styling property that will be applied to text enclosed by a decoration.

outlineWidth?: string

CSS styling property that will be applied to text enclosed by a decoration.

overviewRulerColor?: string

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

overviewRulerLane?: OverviewRulerLane

The position in the overview ruler where the decoration should be rendered.

textDecoration?: string

CSS styling property that will be applied to text enclosed by a decoration.

Definition

The definition of a symbol represented as one or many locations. For most programming languages there is only one location at which a symbol is defined.

Definition: Location | Location[]

DefinitionProvider

The definition provider interface defines the contract between extensions and the go to definition and peek definition features.

Methods

provideDefinition(document: TextDocument, position: Position, token: CancellationToken): Definition | Thenable<Definition>

Provide the definition of the symbol at the given position and document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
Definition | Thenable<Definition>	A definition or a thenable that resolves to such. The lack of a result can be signaled by returning undefined or null.

Diagnostic

Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a file.

Constructors

new Diagnostic(range: Range, message: string, severity?: DiagnosticSeverity): Diagnostic

Creates a new diagnostic object.

Parameter	Description
range: Range	The range to which this diagnostic applies.
message: string	The human-readable message.
severity?: DiagnosticSeverity	The severity, default is error.
Returns	Description
Diagnostic

Properties

code: string | number

A code or identifier for this diagnostics. Will not be surfaced to the user, but should be used for later processing, e.g. when providing code actions.

message: string

The human-readable message.

range: Range

The range to which this diagnostic applies.

severity: DiagnosticSeverity

The severity, default is error.

source: string

A human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.

DiagnosticCollection

A diagnostics collection is a container that manages a set of diagnostics. Diagnostics are always scopes to a a diagnostics collection and a resource.

To get an instance of a DiagnosticCollection use createDiagnosticCollection.

Properties

name: string

The name of this diagnostic collection, for instance typescript. Every diagnostic from this collection will be associated with this name. Also, the task framework uses this name when defining problem matchers.

Methods

clear(): void

Remove all diagnostics from this collection. The same as calling #set(undefined);

Returns	Description
void

delete(uri: Uri): void

Remove all diagnostics from this collection that belong to the provided uri. The same as #set(uri, undefined).

Parameter	Description
uri: Uri	A resource identifier.
Returns	Description
void

dispose(): void

Dispose and free associated resources. Calls clear.

Returns	Description
void

set(uri: Uri, diagnostics: Diagnostic[]): void

Assign diagnostics for given resource. Will replace existing diagnostics for that resource.

Parameter	Description
uri: Uri	A resource identifier.
diagnostics: Diagnostic[]	Array of diagnostics or undefined
Returns	Description
void

set(entries: [Uri, Diagnostic[]][]): void

Replace all entries in this collection.

Parameter	Description
entries: [Uri, Diagnostic[]][]	An array of tuples, like [[file1, [d1, d2]], [file2, [d3, d4, d5]]], or undefined.
Returns	Description
void

DiagnosticSeverity

Represents the severity of diagnostics.

Enumeration members

Error

0

Hint

3

Information

2

Warning

1

Disposable

Represents a type which can release resources, such as event listening or a timer.

Static

from(...disposableLikes: {dispose: () => any}[]): Disposable

Combine many disposable-likes into one. Use this method when having objects with a dispose function which are not instances of Disposable.

Parameter	Description
...disposableLikes: {dispose: () => any}[]	Objects that have at least a dispose-function member.
Returns	Description
Disposable	Returns a new disposable which, upon dispose, will dispose all provided disposables.

Constructors

new Disposable(callOnDispose: Function): Disposable

Creates a new Disposable calling the provided function on dispose.

Parameter	Description
callOnDispose: Function	Function that disposes something.
Returns	Description
Disposable

Methods

dispose(): any

Dispose this object.

Returns	Description
any

DocumentFilter

A document filter denotes a document by different properties like the language, the scheme of its resource, or a glob-pattern that is applied to the path.

• sample - A language filter that applies to typescript files on disk: { language: 'typescript', scheme: 'file' }

• sample - A language filter that applies to all package.json paths: { language: 'json', pattern: '**∕project.json' }

Properties

language?: string

A language id, like typescript.

pattern?: string

A glob pattern, like *.{ts,js}.

scheme?: string

A Uri scheme, like file or untitled.

DocumentFormattingEditProvider

The document formatting provider interface defines the contract between extensions and the formatting-feature.

Methods

provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): TextEdit[] | Thenable<TextEdit[]>

Provide formatting edits for a whole document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
options: FormattingOptions	Options controlling formatting.
token: CancellationToken	A cancellation token.
Returns	Description
TextEdit[] | Thenable<TextEdit[]>	A set of text edits or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

DocumentHighlight

A document highlight is a range inside a text document which deserves special attention. Usually a document highlight is visualized by changing the background color of its range.

Constructors

new DocumentHighlight(range: Range, kind?: DocumentHighlightKind): DocumentHighlight

Creates a new document highlight object.

Parameter	Description
range: Range	The range the highlight applies to.
kind?: DocumentHighlightKind	The highlight kind, default is text.
Returns	Description
DocumentHighlight

Properties

kind: DocumentHighlightKind

The highlight kind, default is text.

range: Range

The range this highlight applies to.

DocumentHighlightKind

A document highlight kind.

Enumeration members

Read

Text

Write

DocumentHighlightProvider

The document highlight provider interface defines the contract between extensions and the word-highlight-feature.

Methods

provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): DocumentHighlight[] | Thenable<DocumentHighlight[]>

Provide a set of document highlights, like all occurrences of a variable or all exit-points of a function.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
DocumentHighlight[] | Thenable<DocumentHighlight[]>	An array of document highlights or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

DocumentRangeFormattingEditProvider

The document formatting provider interface defines the contract between extensions and the formatting-feature.

Methods

provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): TextEdit[] | Thenable<TextEdit[]>

Provide formatting edits for a range in a document.

The given range is a hint and providers can decide to format a smaller or larger range. Often this is done by adjusting the start and end of the range to full syntax nodes.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
range: Range	The range which should be formatted.
options: FormattingOptions	Options controlling formatting.
token: CancellationToken	A cancellation token.
Returns	Description
TextEdit[] | Thenable<TextEdit[]>	A set of text edits or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

DocumentSelector

A language selector is the combination of one or many language identifiers and language filters.

• sample - let sel:DocumentSelector = 'typescript';

• sample - let sel:DocumentSelector = ['typescript', { language: 'json', pattern: '**∕tsconfig.json' }];

DocumentSelector: string | DocumentFilter | string | DocumentFilter[]

DocumentSymbolProvider

The document symbol provider interface defines the contract between extensions and the go to symbol-feature.

Methods

provideDocumentSymbols(document: TextDocument, token: CancellationToken): SymbolInformation[] | Thenable<SymbolInformation[]>

Provide symbol information for the given document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
SymbolInformation[] | Thenable<SymbolInformation[]>	An array of document highlights or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

EnterAction

Describes what to do when pressing Enter.

Properties

appendText?: string

Describes text to be appended after the new line and after the indentation.

indentAction: IndentAction

Describe what to do with the indentation.

removeText?: number

Describes the number of characters to remove from the new line's indentation.

Event<T>

Represents a typed event.

A function that represents an event to which you subscribe by calling it with a listener function as argument.

• sample - item.onDidChange(function(event) { console.log("Event happened: " + event); });

(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable

A function that represents an event to which you subscribe by calling it with a listener function as argument.

A function that represents an event to which you subscribe by calling it with a listener function as argument.

Parameter	Description
listener: (e: T) => any	The listener function will be called when the event happens.
thisArgs?: any	The this-argument which will be used when calling the event listener.
disposables?: Disposable[]	An array to which a disposeable will be added.
Returns	Description
Disposable	A disposable which unsubscribes the event listener.

EventEmitter<T>

An event emitter can be used to create and manage an event for others to subscribe to. One emitter always owns one event.

Use this class if you want to provide event from within your extension, for instance inside a TextDocumentContentProvider or when providing API to other extensions.

Properties

event: Event<T>

The event listeners can subscribe to.

Methods

dispose(): void

Dispose this object and free resources.

Returns	Description
void

fire(data?: T): void

Notify all subscribers of the event. Failure of one or more listener will not fail this function call.

Parameter	Description
data?: T	The event object.
Returns	Description
void

Extension<T>

Represents an extension.

To get an instance of an Extension use getExtension.

Properties

exports: T

The public API exported by this extension. It is an invalid action to access this field before this extension has been activated.

• readonly

extensionPath: string

The absolute file path of the directory containing this extension.

• readonly

id: string

The canonical extension identifier in the form of: publisher.name.

• readonly

isActive: boolean

true if the extension has been activated.

• readonly

packageJSON: any

The parsed contents of the extension's package.json.

• readonly

Methods

activate(): Thenable<T>

Activates this extension and returns its public API.

Returns	Description
Thenable<T>	A promise that will resolve when this extension has been activated.

ExtensionContext

An extension context is a collection of utilities private to an extension.

An instance of an ExtensionContext is provided as the first parameter to the activate-call of an extension.

Properties

extensionPath: string

The absolute file path of the directory containing the extension.

globalState: Memento

A memento object that stores state independent of the current opened workspace.

subscriptions: {dispose}[]

An array to which disposables can be added. When this extension is deactivated the disposables will be disposed.

workspaceState: Memento

A memento object that stores state in the context of the currently opened workspace.

Methods

asAbsolutePath(relativePath: string): string

Get the absolute path of a resource contained in the extension.

Parameter	Description
relativePath: string	A relative path to a resource contained in the extension.
Returns	Description
string	The absolute path of the resource.

FileSystemWatcher

A file system watcher notifies about changes to files and folders on disk.

To get an instance of a FileSystemWatcher use createFileSystemWatcher.

Events

onDidChange: Event<Uri>

An event which fires on file/folder change.

onDidCreate: Event<Uri>

An event which fires on file/folder creation.

onDidDelete: Event<Uri>

An event which fires on file/folder deletion.

Static

from(...disposableLikes: {dispose: () => any}[]): Disposable

Combine many disposable-likes into one. Use this method when having objects with a dispose function which are not instances of Disposable.

Parameter	Description
...disposableLikes: {dispose: () => any}[]	Objects that have at least a dispose-function member.
Returns	Description
Disposable	Returns a new disposable which, upon dispose, will dispose all provided disposables.

Constructors

new FileSystemWatcher(callOnDispose: Function): FileSystemWatcher

Creates a new Disposable calling the provided function on dispose.

Parameter	Description
callOnDispose: Function	Function that disposes something.
Returns	Description
FileSystemWatcher

Properties

ignoreChangeEvents: boolean

true if this file system watcher has been created such that it ignores change file system events.

ignoreCreateEvents: boolean

true if this file system watcher has been created such that it ignores creation file system events.

ignoreDeleteEvents: boolean

true if this file system watcher has been created such that it ignores delete file system events.

Methods

dispose(): any

Dispose this object.

Returns	Description
any

FormattingOptions

Value-object describing what options formatting should use.

Properties

insertSpaces: boolean

Prefer spaces over tabs.

tabSize: number

Size of a tab in spaces.

Hover

A hover represents additional information for a symbol or word. Hovers are rendered in a tooltip-like widget.

Constructors

new Hover(contents: MarkedString | MarkedString[], range?: Range): Hover

Creates a new hover object.

Parameter	Description
contents: MarkedString | MarkedString[]	The contents of the hover.
range?: Range	The range to which the hover applies.
Returns	Description
Hover

Properties

contents: MarkedString[]

The contents of this hover.

range: Range

The range to which this hover applies. When missing, the editor will use the range at the current position or the current position itself.

HoverProvider

The hover provider interface defines the contract between extensions and the hover-feature.

Methods

provideHover(document: TextDocument, position: Position, token: CancellationToken): Hover | Thenable<Hover>

Provide a hover for the given position and document. Multiple hovers at the same position will be merged by the editor. A hover can have a range which defaults to the word range at the position when omitted.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
Hover | Thenable<Hover>	A hover or a thenable that resolves to such. The lack of a result can be signaled by returning undefined or null.

IndentAction

Describes what to do with the indentation when pressing Enter.

Enumeration members

Indent

IndentOutdent

None

Outdent

IndentationRule

Describes indentation rules for a language.

Properties

decreaseIndentPattern: RegExp

If a line matches this pattern, then all the lines after it should be unindendented once (until another rule matches).

increaseIndentPattern: RegExp

If a line matches this pattern, then all the lines after it should be indented once (until another rule matches).

indentNextLinePattern?: RegExp

If a line matches this pattern, then only the next line after it should be indented once.

unIndentedLinePattern?: RegExp

If a line matches this pattern, then its indentation should not be changed and it should not be evaluated against the other rules.

InputBoxOptions

Options to configure the behavior of the input box UI.

Properties

password?: boolean

Set to true to show a password prompt that will not show the typed value.

placeHolder?: string

An optional string to show as place holder in the input box to guide the user what to type.

prompt?: string

The text to display underneath the input box.

validateInput?: (value: string) => string

An optional function that will be called to valide input and to give a hint to the user.

• param - The current value of the input box.

• returns - A human readable string which is presented as diagnostic message. Return undefined, null, or the empty string when 'value' is valid.

value?: string

The value to prefill in the input box.

LanguageConfiguration

The language configuration interfaces defines the contract between extensions and various editor features, like automatic bracket insertion, automatic indentation etc.

Properties

___characterPairSupport?: {autoClosingPairs: {close: string, notIn: string[], open: string}[]}

Deprecated Do not use.

• deprecated - Will be replaced by a better API soon.

___electricCharacterSupport?: {docComment: {close: string, lineStart: string, open: string, scope: string}}

Deprecated Do not use.

• deprecated - Will be replaced by a better API soon.

brackets?: CharacterPair[]

The language's brackets. This configuration implicitly affects pressing Enter around these brackets.

comments?: CommentRule

The language's comment settings.

indentationRules?: IndentationRule

The language's indentation settings.

onEnterRules?: OnEnterRule[]

The language's rules to be evaluated when pressing Enter.

wordPattern?: RegExp

The language's word definition. If the language supports Unicode identifiers (e.g. JavaScript), it is preferable to provide a word definition that uses exclusion of known separators. e.g.: A regex that matches anything except known separators (and dot is allowed to occur in a floating point number): /(-?\d.\d\w)|([^`~!\@@#\%\^\&*()-\=+[{]}\|\;\:\'\"\,.\<>\/\?\s]+)/g

Location

Represents a location inside a resource, such as a line inside a text file.

Constructors

new Location(uri: Uri, rangeOrPosition: Range | Position): Location

Creates a new location object.

Parameter	Description
uri: Uri	The resource identifier.
rangeOrPosition: Range | Position	The range or position. Positions will be converted to an empty range.
Returns	Description
Location

Properties

range: Range

The document range of this locations.

uri: Uri

The resource identifier of this location.

MarkedString

MarkedString can be used to render human readable text. It is either a markdown string or a code-block that provides a language and a code snippet. Note that markdown strings will be sanitized - that means html will be escaped.

MarkedString: string | {language: string, value: string}

Memento

A memento represents a storage utility. It can store and retrieve values.

Methods

get<T>(key: string, defaultValue?: T): T

Return a value.

Parameter	Description
key: string	A string.
defaultValue?: T	A value that should be returned when there is no value (undefined) with the given key.
Returns	Description
T	The stored value, undefined, or the defaultValue.

update(key: string, value: any): Thenable<void>

Store a value. The value must be JSON-stringifyable.

Parameter	Description
key: string	A string.
value: any	A value. MUST not contain cyclic references.
Returns	Description
Thenable<void>

MessageItem

Represents an action that is shown with an information, warning, or error message.

• see - showInformationMessage

• see - showWarningMessage

• see - showErrorMessage

Properties

title: string

A short title like 'Retry', 'Open Log' etc.

OnEnterRule

Describes a rule to be evaluated when pressing Enter.

Properties

action: EnterAction

The action to execute.

afterText?: RegExp

This rule will only execute if the text after the cursor matches this regular expression.

beforeText: RegExp

This rule will only execute if the text before the cursor matches this regular expression.

OnTypeFormattingEditProvider

The document formatting provider interface defines the contract between extensions and the formatting-feature.

Methods

provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): TextEdit[] | Thenable<TextEdit[]>

Provide formatting edits after a character has been typed.

The given position and character should hint to the provider what range the position to expand to, like find the matching { when } has been entered.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
ch: string	The character that has been typed.
options: FormattingOptions	Options controlling formatting.
token: CancellationToken	A cancellation token.
Returns	Description
TextEdit[] | Thenable<TextEdit[]>	A set of text edits or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

OutputChannel

An output channel is a container for readonly textual information.

To get an instance of an OutputChannel use createOutputChannel.

Properties

name: string

The human-readable name of this output channel.

• readonly

Methods

append(value: string): void

Append the given value to the channel.

Parameter	Description
value: string	A string, falsy values will not be printed.
Returns	Description
void

appendLine(value: string): void

Append the given value and a line feed character to the channel.

Parameter	Description
value: string	A string, falsy values will be printed.
Returns	Description
void

clear(): void

Removes all output from the channel.

Returns	Description
void

dispose(): void

Dispose and free associated resources.

Returns	Description
void

hide(): void

Hide this channel from the UI.

Returns	Description
void

show(column?: ViewColumn, preserveFocus?: boolean): void

Reveal this channel in the UI.

• deprecated - This method is deprecated.

Parameter	Description
column?: ViewColumn	The column in which to show the channel, default in one.
preserveFocus?: boolean	When true the channel will not take focus.
Returns	Description
void

show(preservceFocus?: boolean): void

Reveal this channel in the UI.

Parameter	Description
preservceFocus?: boolean
Returns	Description
void

OverviewRulerLane

Represents different positions for rendering a decoration in an overview ruler. The overview ruler supports three lanes.

Enumeration members

Center

2

Full

7

Left

1

Right

4

ParameterInformation

Represents a parameter of a callable-signature. A parameter can have a label and a doc-comment.

Constructors

new ParameterInformation(label: string, documentation?: string): ParameterInformation

Creates a new parameter information object.

Parameter	Description
label: string	A label string.
documentation?: string	A doc string.
Returns	Description
ParameterInformation

Properties

documentation: string

The human-readable doc-comment of this signature. Will be shown in the UI but can be omitted.

label: string

The label of this signature. Will be shown in the UI.

Position

Represents a line and character position, such as the position of the cursor.

Position objects are immutable. Use the with or translate methods to derive new positions from an existing position.

Constructors

new Position(line: number, character: number): Position

Parameter	Description
line: number	A zero-based line value.
character: number	A zero-based character value.
Returns	Description
Position

Properties

character: number

The zero-based character value.

• readonly

line: number

The zero-based line value.

• readonly

Methods

compareTo(other: Position): number

Compare this to other.

Parameter	Description
other: Position	A position.
Returns	Description
number	A number smaller than zero if this position is before the given position, a number greater than zero if this position is after the given position, or zero when this and the given position are equal.

isAfter(other: Position): boolean

Check if other is after this position.

Parameter	Description
other: Position	A position.
Returns	Description
boolean	true if position is on a greater line or on the same line on a greater character.

isAfterOrEqual(other: Position): boolean

Check if other is after or equal to this position.

Parameter	Description
other: Position	A position.
Returns	Description
boolean	true if position is on a greater line or on the same line on a greater or equal character.

isBefore(other: Position): boolean

Check if other is before this position.

Parameter	Description
other: Position	A position.
Returns	Description
boolean	true if position is on a smaller line or on the same line on a smaller character.

isBeforeOrEqual(other: Position): boolean

Check if other is before or equal to this position.

Parameter	Description
other: Position	A position.
Returns	Description
boolean	true if position is on a smaller line or on the same line on a smaller or equal character.

isEqual(other: Position): boolean

Check if other equals this position.

Parameter	Description
other: Position	A position.
Returns	Description
boolean	true if the line and character of the given position are equal to the line and character of this position.

translate(lineDelta?: number, characterDelta?: number): Position

Create a new position relative to this position.

Parameter	Description
lineDelta?: number	Delta value for the line value, default is 0.
characterDelta?: number	Delta value for the character value, default is 0.
Returns	Description
Position	A position which line and character is the sum of the current line and character and the corresponding deltas.

with(line?: number, character?: number): Position

Create a new position derived from this position.

Parameter	Description
line?: number	Value that should be used as line value, default is the existing value
character?: number	Value that should be used as character value, default is the existing value
Returns	Description
Position	A position where line and character are replaced by the given values.

QuickPickItem

Represents an item that can be selected from a list of items.

Properties

description: string

A human readable string which is rendered less prominent.

detail?: string

A human readable string which is rendered less prominent.

label: string

A human readable string which is rendered prominent.

QuickPickOptions

Options to configure the behavior of the quick pick UI.

Events

onDidSelectItem?: (item: T | string) => any

An optional function that is invoked whenever an item is selected.

Properties

matchOnDescription?: boolean

An optional flag to include the description when filtering the picks.

matchOnDetail?: boolean

An optional flag to include the detail when filtering the picks.

placeHolder?: string

An optional string to show as place holder in the input box to guide the user what to pick on.

Range

A range represents an ordered pair of two positions. It is guaranteed that start.isBeforeOrEqual(end)

Range objects are immutable. Use the with, intersection, or union methods to derive new ranges from an existing range.

Constructors

new Range(start: Position, end: Position): Range

Create a new range from two positions. If start is not before or equal to end, the values will be swapped.

Parameter	Description
start: Position	A position.
end: Position	A position.
Returns	Description
Range

new Range(startLine: number, startCharacter: number, endLine: number, endCharacter: number): Range

Create a new range from number coordinates. It is a shorter equivalent of using new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))

Parameter	Description
startLine: number	A zero-based line value.
startCharacter: number	A zero-based character value.
endLine: number	A zero-based line value.
endCharacter: number	A zero-based character value.
Returns	Description
Range

Properties

end: Position

The end position. It is after or equal to start.

• readonly

isEmpty: boolean

true iff start and end are equal.

isSingleLine: boolean

true iff start.line and end.line are equal.

start: Position

The start position. It is before or equal to end.

• readonly

Methods

contains(positionOrRange: Position | Range): boolean

Check if a position or a range is contained in this range.

Parameter	Description
positionOrRange: Position | Range	A position or a range.
Returns	Description
boolean	true iff the position or range is inside or equal to this range.

intersection(range: Range): Range

Intersect range with this range and returns a new range or undefined if the ranges have no overlap.

Parameter	Description
range: Range	A range.
Returns	Description
Range	A range of the greater start and smaller end positions. Will return undefined when there is no overlap.

isEqual(other: Range): boolean

Check if other equals this range.

Parameter	Description
other: Range	A range.
Returns	Description
boolean	true when start and end are equal to start and end of this range.

union(other: Range): Range

Compute the union of other with this range.

Parameter	Description
other: Range	A range.
Returns	Description
Range	A range of smaller start position and the greater end position.

with(start?: Position, end?: Position): Range

Create a new range derived from this range.

Parameter	Description
start?: Position	A position that should be used as start. The default value is the current start.
end?: Position	A position that should be used as end. The default value is the current end.
Returns	Description
Range	A range derived from this range with the given start and end position. If start and end are not different this range will be returned.

ReferenceContext

Value-object that contains additional information when requesting references.

Properties

includeDeclaration: boolean

Include the declaration of the current symbol.

ReferenceProvider

The reference provider interface defines the contract between extensions and the find references-feature.

Methods

provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): Location[] | Thenable<Location[]>

Provide a set of project-wide references for the given position and document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
context: ReferenceContext
token: CancellationToken	A cancellation token.
Returns	Description
Location[] | Thenable<Location[]>	An array of locations or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.

RenameProvider

The rename provider interface defines the contract between extensions and the rename-feature.

Methods

provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): WorkspaceEdit | Thenable<WorkspaceEdit>

Provide an edit that describes changes that have to be made to one or many resources to rename a symbol to a different name.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
newName: string	The new name of the symbol. If the given name is not valid, the provider must return a rejected promise.
token: CancellationToken	A cancellation token.
Returns	Description
WorkspaceEdit | Thenable<WorkspaceEdit>	A workspace edit or a thenable that resolves to such. The lack of a result can be signaled by returning undefined or null.

Selection

Represents a text selection in an editor.

Constructors

new Selection(anchor: Position, active: Position): Selection

Create a selection from two postions.

Parameter	Description
anchor: Position	A position.
active: Position	A position.
Returns	Description
Selection

new Selection(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number): Selection

Create a selection from four coordinates.

Parameter	Description
anchorLine: number	A zero-based line value.
anchorCharacter: number	A zero-based character value.
activeLine: number	A zero-based line value.
activeCharacter: number	A zero-based character value.
Returns	Description
Selection

Properties

active: Position

The position of the cursor. This position might be before or after anchor.

anchor: Position

The position at which the selection starts. This position might be before or after active.

end: Position

The end position. It is after or equal to start.

• readonly

isEmpty: boolean

true iff start and end are equal.

isReversed: boolean

A selection is reversed if active.isBefore(anchor).

isSingleLine: boolean

true iff start.line and end.line are equal.

start: Position

The start position. It is before or equal to end.

• readonly

Methods

contains(positionOrRange: Position | Range): boolean

Check if a position or a range is contained in this range.

Parameter	Description
positionOrRange: Position | Range	A position or a range.
Returns	Description
boolean	true iff the position or range is inside or equal to this range.

intersection(range: Range): Range

Intersect range with this range and returns a new range or undefined if the ranges have no overlap.

Parameter	Description
range: Range	A range.
Returns	Description
Range	A range of the greater start and smaller end positions. Will return undefined when there is no overlap.

isEqual(other: Range): boolean

Check if other equals this range.

Parameter	Description
other: Range	A range.
Returns	Description
boolean	true when start and end are equal to start and end of this range.

union(other: Range): Range

Compute the union of other with this range.

Parameter	Description
other: Range	A range.
Returns	Description
Range	A range of smaller start position and the greater end position.

with(start?: Position, end?: Position): Range

Create a new range derived from this range.

Parameter	Description
start?: Position	A position that should be used as start. The default value is the current start.
end?: Position	A position that should be used as end. The default value is the current end.
Returns	Description
Range	A range derived from this range with the given start and end position. If start and end are not different this range will be returned.

SignatureHelp

Signature help represents the signature of something callable. There can be multiple signatures but only one active and only one active parameter.

Properties

activeParameter: number

The active parameter of the active signature.

activeSignature: number

The active signature.

signatures: SignatureInformation[]

One or more signatures.

SignatureHelpProvider

The signature help provider interface defines the contract between extensions and the parameter hints-feature.

Methods

provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken): SignatureHelp | Thenable<SignatureHelp>

Provide help for the signature at the given position and document.

Parameter	Description
document: TextDocument	The document in which the command was invoked.
position: Position	The position at which the command was invoked.
token: CancellationToken	A cancellation token.
Returns	Description
SignatureHelp | Thenable<SignatureHelp>	Signature help or a thenable that resolves to such. The lack of a result can be signaled by returning undefined or null.

SignatureInformation

Represents the signature of something callable. A signature can have a label, like a function-name, a doc-comment, and a set of parameters.

Constructors

new SignatureInformation(label: string, documentation?: string): SignatureInformation

Creates a new signature information object.

Parameter	Description
label: string	A label string.
documentation?: string	A doc string.
Returns	Description
SignatureInformation

Properties

documentation: string

The human-readable doc-comment of this signature. Will be shown in the UI but can be omitted.

label: string

The label of this signature. Will be shown in the UI.

parameters: ParameterInformation[]

The parameters of this signature.

StatusBarAlignment

Represents the alignment of status bar items.

Enumeration members

Left

Right

StatusBarItem

A status bar item is a status bar contribution that can show text and icons and run a command on click.

Properties

alignment: StatusBarAlignment

The alignment of this item.

• readonly

color: string

The foreground color for this entry.

command: string

The identifier of a command to run on click. The command must be known.

priority: number

The priority of this item. Higher value means the item should be shown more to the left.

• readonly

text: string

The text to show for the entry. You can embed icons in the text by leveraging the syntax:

My text $(icon-name) contains icons like $(icon'name) this one.

Where the icon-name is taken from the octicon icon set, e.g. light-bulb, thumbsup, zap etc.

tooltip: string

The tooltip text when you hover over this entry.

Methods

dispose(): void

Dispose and free associated resources. Call hide.

Returns	Description
void

hide(): void

Hide the entry in the status bar.

Returns	Description
void

show(): void

Shows the entry in the status bar.

Returns	Description
void

SymbolInformation

Represents information about programming constructs like variables, classes, interfaces etc.

Constructors

new SymbolInformation(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string): SymbolInformation

Creates a new symbol information object.

Parameter	Description
name: string	The name of the symbol.
kind: SymbolKind	The kind of the symbol.
range: Range	The range of the location of the symbol.
uri?: Uri	The resource of the location of symbol, defaults to the current document.
containerName?: string	The name of the symbol containing the symbol.
Returns	Description
SymbolInformation

Properties

containerName: string

The name of the symbol containing this symbol.

kind: SymbolKind

The kind of this symbol.

location: Location

The location of this symbol.

name: string

The name of this symbol.

SymbolKind

A symbol kind.

Enumeration members

Array

Boolean

Class

Constant

Constructor

Enum

Field

File

Function

Interface

Key

Method

Module

Namespace

Null

Number

Object

Package

Property

String

Variable

TextDocument

Represents a text document, such as a source file. Text documents have lines and knowledge about an underlying resource like a file.

Properties

fileName: string

The file system path of the associated resource. Shorthand notation for TextDocument.uri.fsPath. Independent of the uri scheme.

• readonly

isDirty: boolean

true if there are unpersisted changes.

• readonly

isUntitled: boolean

Is this document representing an untitled file.

• readonly

languageId: string

The identifier of the language associated with this document.

• readonly

lineCount: number

The number of lines in this document.

• readonly

uri: Uri

The associated URI for this document. Most documents have the file-scheme, indicating that they represent files on disk. However, some documents may have other schemes indicating that they are not available on disk.

• readonly

version: number

The version number of this document (it will strictly increase after each change, including undo/redo).

• readonly

Methods

getText(range?: Range): string

Get the text of this document. A substring can be retrieved by providing a range. The range will be adjusted.

Parameter	Description
range?: Range	Include only the text included by the range.
Returns	Description
string	The text inside the provided range or the entire text.

getWordRangeAtPosition(position: Position): Range

Get a word-range at the given position. By default words are defined by common separators, like space, -, _, etc. In addition, per languge custom word definitions can be defined.

The position will be adjusted.

Parameter	Description
position: Position	A position.
Returns	Description
Range	A range spanning a word, or undefined.

lineAt(line: number): TextLine

Returns a text line denoted by the line number. Note that the returned object is not live and changes to the document are not reflected.

Parameter	Description
line: number	A line number in [0, lineCount).
Returns	Description
TextLine	A line.

lineAt(position: Position): TextLine

Returns a text line denoted by the position. Note that the returned object is not live and changes to the document are not reflected.

The position will be adjusted.

• see - TextDocument.lineAt

Parameter	Description
position: Position	A position.
Returns	Description
TextLine	A line.

offsetAt(position: Position): number

Converts the position to a zero-based offset.

The position will be adjusted.

Parameter	Description
position: Position	A position.
Returns	Description
number	A valid zero-based offset.

positionAt(offset: number): Position

Converts a zero-based offset to a position.

Parameter	Description
offset: number	A zero-based offset.
Returns	Description
Position	A valid position.

save(): Thenable<boolean>

Save the underlying file.

Returns	Description
Thenable<boolean>	A promise that will resolve to true when the file has been saved.

validatePosition(position: Position): Position

Ensure a position is contained in the range of this document.

Parameter	Description
position: Position	A position.
Returns	Description
Position	The given position or a new, adjusted position.

validateRange(range: Range): Range

Ensure a range is completely contained in this document.

Parameter	Description
range: Range	A range.
Returns	Description
Range	The given range or a new, adjusted range.

TextDocumentChangeEvent

An event describing a transactional document change.

Properties

contentChanges: TextDocumentContentChangeEvent[]

An array of content changes.

document: TextDocument

The affected document.

TextDocumentContentChangeEvent

An event describing an individual change in the text of a document.

Properties

range: Range

The range that got replaced.

rangeLength: number

The length of the range that got replaced.

text: string

The new text for the range.

TextDocumentContentProvider

A text document content provider allows to add readonly documents to the editor, such as source from a dll or generated html from md.

Content providers are registered for a uri-scheme. When a uri with that scheme is to be loaded the content provider is asked.

Events

onDidChange?: Event<Uri>

An event to signal a resource has changed.

Methods

provideTextDocumentContent(uri: Uri, token: CancellationToken): string | Thenable<string>

Provide textual content for a given uri.

The editor will use the returned string-content to create a readonly document. Resources allocated should be released when the corresponding document has been closed.

Parameter	Description
uri: Uri	An uri which scheme matches the scheme this provider was registered for.
token: CancellationToken	A cancellation token.
Returns	Description
string | Thenable<string>	A string or a thenable that resolves to such.

TextEdit

A text edit represents edits that should be applied to a document.

Static

delete(range: Range): TextEdit

Utility to create a delete edit.

Parameter	Description
range: Range	A range.
Returns	Description
TextEdit	A new text edit object.

insert(position: Position, newText: string): TextEdit

Utility to create an insert edit.

Parameter	Description
position: Position	A position, will become an empty range.
newText: string	A string.
Returns	Description
TextEdit	A new text edit object.

replace(range: Range, newText: string): TextEdit

Utility to create a replace edit.

Parameter	Description
range: Range	A range.
newText: string	A string.
Returns	Description
TextEdit	A new text edit object.

Constructors

new TextEdit(range: Range, newText: string): TextEdit

Create a new TextEdit.

Parameter	Description
range: Range	A range.
newText: string	A string.
Returns	Description
TextEdit

Properties

newText: string

The string this edit will insert.

range: Range

The range this edit applies to.

TextEditor

Represents an editor that is attached to a document.

Properties

document: TextDocument

The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.

options: TextEditorOptions

Text editor options.

selection: Selection

The primary selection on this text editor. Shorthand for TextEditor.selections[0].

selections: Selection[]

The selections in this text editor. The primary selection is always at index 0.

viewColumn: ViewColumn

The column in which this editor shows. Will be undefined in case this isn't one of the three main editors, e.g an embedded editor.

Methods

edit(callback: (editBuilder: TextEditorEdit) => void): Thenable<boolean>

Perform an edit on the document associated with this text editor.

The given callback-function is invoked with an edit-builder which must be used to make edits. Note that the edit-builder is only valid while the callback executes.

Parameter	Description
callback: (editBuilder: TextEditorEdit) => void	A function which can make edits using an edit-builder.
Returns	Description
Thenable<boolean>	A promise that resolves with a value indicating if the edits could be applied.

hide(): void

Hide the text editor.

• deprecated - This method is deprecated. Use the command 'workbench.action.closeActiveEditor' instead. This method shows unexpected behavior and will be removed in the next major update.

Returns	Description
void

revealRange(range: Range, revealType?: TextEditorRevealType): void

Scroll as indicated by revealType in order to reveal the given range.

Parameter	Description
range: Range	A range.
revealType?: TextEditorRevealType	The scrolling strategy for revealing range.
Returns	Description
void

setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void

Adds a set of decorations to the text editor. If a set of decorations already exists with the given decoration type, they will be replaced.

• see - createTextEditorDecorationType.

Parameter	Description
decorationType: TextEditorDecorationType	A decoration type.
rangesOrOptions: Range[] | DecorationOptions[]	Either ranges or more detailed options.
Returns	Description
void

show(column?: ViewColumn): void

Show the text editor.

• deprecated - This method is deprecated. Use window.showTextDocument instead. This method shows unexpected behavior and will be removed in the next major update.

Parameter	Description
column?: ViewColumn	The column in which to show this editor.
Returns	Description
void

TextEditorDecorationType

Represents a handle to a set of decorations sharing the same styling options in a text editor.

To get an instance of a TextEditorDecorationType use createTextEditorDecorationType.

Properties

key: string

Internal representation of the handle.

• readonly

Methods

dispose(): void

Remove this decoration type and all decorations on all text editors using it.

Returns	Description
void

TextEditorEdit

A complex edit that will be applied in one transaction on a TextEditor. This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) they can be applied on a document associated with a text editor.

Methods

delete(location: Range | Selection): void

Delete a certain text region.

Parameter	Description
location: Range | Selection	The range this operation should remove.
Returns	Description
void

insert(location: Position, value: string): void

Insert text at a location. You can use \r\n or \n in value and they will be normalized to the current document. Although the equivalent text edit can be made with replace, insert will produce a different resulting selection (it will get moved).

Parameter	Description
location: Position	The position where the new text should be inserted.
value: string	The new text this operation should insert.
Returns	Description
void

replace(location: Position | Range | Selection, value: string): void

Replace a certain text region with a new value. You can use \r\n or \n in value and they will be normalized to the current document.

Parameter	Description
location: Position | Range | Selection	The range this operation should remove.
value: string	The new text this operation should insert after removing location.
Returns	Description
void

TextEditorOptions

Represents a text editor's options.

Properties

insertSpaces?: boolean | string

When pressing Tab insert n spaces. When getting a text editor's options, this property will always be a boolean (resolved). When setting a text editor's options, this property is optional and it can be a boolean or "auto".

tabSize?: number | string

The size in spaces a tab takes. This is used for two purposes:

• the rendering width of a tab character;
• the number of spaces to insert when insertSpaces is true. When getting a text editor's options, this property will always be a number (resolved). When setting a text editor's options, this property is optional and it can be a number or "auto".

TextEditorOptionsChangeEvent

Represents an event describing the change in a text editor's options.

Properties

options: TextEditorOptions

The new value for the text editor's options.

textEditor: TextEditor

The text editor for which the options have changed.

TextEditorRevealType

Represents different reveal strategies in a text editor.

Enumeration members

Default

InCenter

InCenterIfOutsideViewport

TextEditorSelectionChangeEvent

Represents an event describing the change in a text editor's selections.

Properties

selections: Selection[]

The new value for the text editor's selections.

textEditor: TextEditor

The text editor for which the selections have changed.

TextEditorViewColumnChangeEvent

Represents an event describing the change of a text editor's view column.

Properties

textEditor: TextEditor

The text editor for which the options have changed.

viewColumn: ViewColumn

The new value for the text editor's view column.

TextLine

Represents a line of text, such as a line of source code.

TextLine objects are immutable. When a document changes, previously retrieved lines will not represent the latest state.

Properties

firstNonWhitespaceCharacterIndex: number

The offset of the first character which is not a whitespace character as defined by /\s/.

• readonly

isEmptyOrWhitespace: boolean

Whether this line is whitespace only, shorthand for TextLine.firstNonWhitespaceCharacterIndex === TextLine.text.length.

• readonly

lineNumber: number

The zero-based line number.

• readonly

range: Range

The range this line covers without the line separator characters.

• readonly

rangeIncludingLineBreak: Range

The range this line covers with the line separator characters.

• readonly

text: string

The text of this line without the line separator characters.

• readonly

ThemableDecorationRenderOptions

Represents theme specific rendering styles for a text editor decoration.

Properties

backgroundColor?: string

Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations.

borderColor?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderRadius?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderSpacing?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderStyle?: string

CSS styling property that will be applied to text enclosed by a decoration.

borderWidth?: string

CSS styling property that will be applied to text enclosed by a decoration.

color?: string

CSS styling property that will be applied to text enclosed by a decoration.

cursor?: string

CSS styling property that will be applied to text enclosed by a decoration.

gutterIconPath?: string

An absolute path to an image to be rendered in the gutterIconPath.

letterSpacing?: string

CSS styling property that will be applied to text enclosed by a decoration.

outlineColor?: string

CSS styling property that will be applied to text enclosed by a decoration.

outlineStyle?: string

CSS styling property that will be applied to text enclosed by a decoration.

outlineWidth?: string

CSS styling property that will be applied to text enclosed by a decoration.

overviewRulerColor?: string

The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.

textDecoration?: string

CSS styling property that will be applied to text enclosed by a decoration.

Uri

A universal resource identifier representing either a file on disk or another resource, like untitled resources.

Static

file(path: string): Uri

Create an URI from a file system path. The scheme will be file.

Parameter	Description
path: string	A file system or UNC path.
Returns	Description
Uri	A new Uri instance.

parse(value: string): Uri

Create an URI from a string. Will throw if the given value is not valid.

Parameter	Description
value: string	The string value of an Uri.
Returns	Description
Uri	A new Uri instance.

Properties

authority: string

Authority is the www.msft.com part of http://www.msft.com/some/path?query#fragment. The part between the first double slashes and the next slash.

fragment: string

Fragment is the fragment part of http://www.msft.com/some/path?query#fragment.

fsPath: string

The string representing the corresponding file system path of this URI.

Will handle UNC paths and normalize windows drive letters to lower-case. Also uses the platform specific path separator. Will not validate the path for invalid characters and semantics. Will not look at the scheme of this URI.

path: string

Path is the /some/path part of http://www.msft.com/some/path?query#fragment.

query: string

Query is the query part of http://www.msft.com/some/path?query#fragment.

scheme: string

Scheme is the http part of http://www.msft.com/some/path?query#fragment. The part before the first colon.

Methods

toJSON(): any

Returns a JSON representation of this Uri.

Returns	Description
any	An object.

toString(): string

Returns a canonical representation of this URI. The representation and normalization of a URI depends on the scheme.

Returns	Description
string	A string that is the encoded version of this Uri.

ViewColumn

Denotes a column in the VS Code window. Columns are used to show editors side by side.

Enumeration members

One

1

Three

3

Two

2

WorkspaceConfiguration

Represents the workspace configuration. The workspace configuration is always a merged view of the configuration of the current workspace and the installation-wide configuration.

Methods

get<T>(section: string, defaultValue?: T): T

Return a value from this configuration.

Parameter	Description
section: string	Configuration name, supports dotted names.
defaultValue?: T	A value should be returned when no value could be found, is undefined.
Returns	Description
T	The value section denotes or the default.

has(section: string): boolean

Check if this configuration has a certain value.

Parameter	Description
section: string	configuration name, supports dotted names.
Returns	Description
boolean	true iff the section doesn't resolve to undefined.

WorkspaceEdit

A workspace edit represents textual changes for many documents.

Properties

size: number

The number of affected resources.

• readonly

Methods

delete(uri: Uri, range: Range): void

Delete the text at the given range.

Parameter	Description
uri: Uri	A resource identifier.
range: Range	A range.
Returns	Description
void

entries(): [Uri, TextEdit[]][]

Get all text edits grouped by resource.

Returns	Description
[Uri, TextEdit[]][]	An array of [Uri, TextEdit[]]-tuples.

get(uri: Uri): TextEdit[]

Get the text edits for a resource.

Parameter	Description
uri: Uri	A resource identifier.
Returns	Description
TextEdit[]	An array of text edits.

has(uri: Uri): boolean

Check if this edit affects the given resource.

Parameter	Description
uri: Uri	A resource identifier.
Returns	Description
boolean	true if the given resource will be touched by this edit.

insert(uri: Uri, position: Position, newText: string): void

Insert the given text at the given position.

Parameter	Description
uri: Uri	A resource identifier.
position: Position	A position.
newText: string	A string.
Returns	Description
void

replace(uri: Uri, range: Range, newText: string): void

Replace the given range with given text for the given resource.

Parameter	Description
uri: Uri	A resource identifier.
range: Range	A range.
newText: string	A string.
Returns	Description
void

set(uri: Uri, edits: TextEdit[]): void

Set (and replace) text edits for a resource.

Parameter	Description
uri: Uri	A resource identifier.
edits: TextEdit[]	An array of text edits.
Returns	Description
void

WorkspaceSymbolProvider

The workspace symbol provider interface defines the contract between extensions and the symbol search-feature.

Methods

provideWorkspaceSymbols(query: string, token: CancellationToken): SymbolInformation[] | Thenable<SymbolInformation[]>

Project-wide search for a symbol matching the given query string. It is up to the provider how to search given the query string, like substring, indexOf etc.

Parameter	Description
query: string	A non-empty query string.
token: CancellationToken	A cancellation token.
Returns	Description
SymbolInformation[] | Thenable<SymbolInformation[]>	An array of document highlights or a thenable that resolves to such. The lack of a result can be signaled by returning undefined, null, or an empty array.