diff --git a/.eslintrc.json b/.eslintrc.json
new file mode 100644
index 0000000..f9b22b7
--- /dev/null
+++ b/.eslintrc.json
@@ -0,0 +1,24 @@
+{
+ "root": true,
+ "parser": "@typescript-eslint/parser",
+ "parserOptions": {
+ "ecmaVersion": 6,
+ "sourceType": "module"
+ },
+ "plugins": [
+ "@typescript-eslint"
+ ],
+ "rules": {
+ "@typescript-eslint/naming-convention": "warn",
+ "@typescript-eslint/semi": "warn",
+ "curly": "warn",
+ "eqeqeq": "warn",
+ "no-throw-literal": "warn",
+ "semi": "off"
+ },
+ "ignorePatterns": [
+ "out",
+ "dist",
+ "**/*.d.ts"
+ ]
+}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..0b60dfa
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+out
+dist
+node_modules
+.vscode-test/
+*.vsix
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..3d11ddc
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,8 @@
+{
+ // See http://go.microsoft.com/fwlink/?LinkId=827846
+ // for the documentation about the extensions.json format
+ "recommendations": [
+ "dbaeumer.vscode-eslint",
+ "eamodio.tsl-problem-matcher"
+ ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..64afa42
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,35 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Run Extension",
+ "type": "extensionHost",
+ "request": "launch",
+ "args": [
+ "--extensionDevelopmentPath=${workspaceFolder}",
+ "--enable-proposed-api"
+ ],
+ "outFiles": [
+ "${workspaceFolder}/dist/**/*.js"
+ ],
+ "preLaunchTask": "${defaultBuildTask}"
+ },
+ {
+ "name": "Extension Tests",
+ "type": "extensionHost",
+ "request": "launch",
+ "args": [
+ "--extensionDevelopmentPath=${workspaceFolder}",
+ "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
+ ],
+ "outFiles": [
+ "${workspaceFolder}/out/test/**/*.js"
+ ],
+ "preLaunchTask": "npm: test-watch"
+ }
+ ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..5c5ac48
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,13 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+ "files.exclude": {
+ "out": false, // set this to true to hide the "out" folder with the compiled JS files
+ "dist": false // set this to true to hide the "dist" folder with the compiled JS files
+ },
+ "search.exclude": {
+ "out": true, // set this to false to include "out" folder in search results
+ "dist": true // set this to false to include "dist" folder in search results
+ },
+ // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
+ "typescript.tsc.autoDetect": "off"
+}
\ No newline at end of file
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 0000000..136cbbc
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,33 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "type": "npm",
+ "script": "watch",
+ "problemMatcher": [
+ "$ts-webpack-watch",
+ "$tslint-webpack-watch"
+ ],
+ "isBackground": true,
+ "presentation": {
+ "reveal": "never"
+ },
+ "group": {
+ "kind": "build",
+ "isDefault": true
+ }
+ },
+ {
+ "type": "npm",
+ "script": "test-watch",
+ "problemMatcher": "$tsc-watch",
+ "isBackground": true,
+ "presentation": {
+ "reveal": "never"
+ },
+ "group": "build"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/.vscodeignore b/.vscodeignore
new file mode 100644
index 0000000..69da5fb
--- /dev/null
+++ b/.vscodeignore
@@ -0,0 +1,12 @@
+.vscode/**
+.vscode-test/**
+out/**
+node_modules/**
+src/**
+.gitignore
+.yarnrc
+vsc-extension-quickstart.md
+**/tsconfig.json
+**/.eslintrc.json
+**/*.map
+**/*.ts
diff --git a/.yarnrc b/.yarnrc
new file mode 100644
index 0000000..f757a6a
--- /dev/null
+++ b/.yarnrc
@@ -0,0 +1 @@
+--ignore-engines true
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..f2ff9d2
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,9 @@
+# Change Log
+
+All notable changes to the "vscode-notebook-cell-linenumber" extension will be documented in this file.
+
+Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
+
+## [Unreleased]
+
+- Initial release
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b4b871c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,7 @@
+A [Visual Studio Code](https://code.visualstudio.com/) [extension](https://marketplace.visualstudio.com/items?itemName=donjayamanne.jupyterpowertools) that provides ability to view cursor position in cell or window statusbar.
+
+## Cursor position in Cell Statusbar
+
+
+## Cursor position in VS Code Statusbar
+
diff --git a/images/cellStatusbarDemo.gif b/images/cellStatusbarDemo.gif
new file mode 100644
index 0000000..0b0b38a
Binary files /dev/null and b/images/cellStatusbarDemo.gif differ
diff --git a/images/statusbarDemo.gif b/images/statusbarDemo.gif
new file mode 100644
index 0000000..fabdc47
Binary files /dev/null and b/images/statusbarDemo.gif differ
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..2024ca6
--- /dev/null
+++ b/package.json
@@ -0,0 +1,73 @@
+{
+ "name": "vscode-notebook-cell-linenumber",
+ "displayName": "vscode-notebook-cell-linenumber",
+ "description": "",
+ "version": "0.0.1",
+ "enableProposedApi": true,
+ "engines": {
+ "vscode": "1.57.0-insider"
+ },
+ "categories": [
+ "Other"
+ ],
+ "activationEvents": [
+ "*",
+ "onNotebook:jupyter-notebook",
+ "onCommand:vscode-notebook-cell-linenumber.helloWorld"
+ ],
+ "main": "./dist/extension.js",
+ "contributes": {
+ "configuration": {
+ "type": "object",
+ "properties": {
+ "notebook.cursorPositionLocation": {
+ "type": "string",
+ "default": "statusbar",
+ "enum": [
+ "statusbar",
+ "cellstatusbar"
+ ],
+ "description": "Displays cell line and column number in cell or window statusbar.",
+ "scope": "machine"
+ }
+ }
+ },
+ "commands": [
+ {
+ "command": "vscode-notebook-cell-linenumber.helloWorld",
+ "title": "Hello World"
+ }
+ ]
+ },
+ "scripts": {
+ "vscode:prepublish": "yarn run package",
+ "compile": "webpack",
+ "watch": "webpack --watch",
+ "package": "webpack --mode production --devtool hidden-source-map",
+ "test-compile": "tsc -p ./",
+ "test-watch": "tsc -watch -p ./",
+ "pretest": "yarn run test-compile && yarn run lint",
+ "lint": "eslint src --ext ts",
+ "test": "node ./out/test/runTest.js",
+ "download-api": "vscode-dts dev",
+ "postdownload-api": "vscode-dts main",
+ "postinstall": "npm run download-api"
+ },
+ "devDependencies": {
+ "@types/glob": "^7.1.3",
+ "@types/mocha": "^8.0.4",
+ "@types/node": "^12.11.7",
+ "@types/vscode": "^1.56.0",
+ "@typescript-eslint/eslint-plugin": "^4.14.1",
+ "@typescript-eslint/parser": "^4.14.1",
+ "eslint": "^7.19.0",
+ "glob": "^7.1.6",
+ "mocha": "^8.2.1",
+ "ts-loader": "^8.0.14",
+ "typescript": "^4.1.3",
+ "vscode-dts": "^0.3.1",
+ "vscode-test": "^1.5.0",
+ "webpack": "^5.19.0",
+ "webpack-cli": "^4.4.0"
+ }
+}
diff --git a/src/extension.ts b/src/extension.ts
new file mode 100644
index 0000000..1a71219
--- /dev/null
+++ b/src/extension.ts
@@ -0,0 +1,205 @@
+// The module 'vscode' contains the VS Code extensibility API
+// Import the module and reference it with the alias vscode in your code below
+import {
+ EventEmitter,
+ commands,
+ ConfigurationChangeEvent,
+ ExtensionContext,
+ notebook,
+ NotebookCellStatusBarItemProvider,
+ NotebookCell,
+ CancellationToken,
+ NotebookCellStatusBarItem,
+ window,
+ TextEditorSelectionChangeEvent,
+ TextDocument,
+ Position,
+ Disposable,
+ NotebookCellStatusBarAlignment,
+ NotebookEditorSelectionChangeEvent,
+ CodeActionProvider,
+ Range,
+ Selection,
+ CodeActionContext,
+ languages,
+ DocumentHighlightProvider,
+ workspace,
+ StatusBarItem,
+ StatusBarAlignment,
+} from "vscode";
+
+// this method is called when your extension is activated
+// your extension is activated the very first time the command is executed
+export function activate(context: ExtensionContext) {
+ // Use the console to output diagnostic information (console.log) and errors (console.error)
+ // This line of code will only be executed once when your extension is activated
+ console.log(
+ 'Congratulations, your extension "vscode-notebook-cell-linenumber" is now active!'
+ );
+
+ // The command has been defined in the package.json file
+ // Now provide the implementation of the command with registerCommand
+ // The commandId parameter must match the command field in package.json
+ let disposable = commands.registerCommand(
+ "vscode-notebook-cell-linenumber.helloWorld",
+ () => {
+ // The code you place here will be executed every time your command is executed
+
+ // Display a message box to the user
+ window.showInformationMessage(
+ "Hello World from vscode-notebook-cell-linenumber!"
+ );
+ }
+ );
+
+ context.subscriptions.push(disposable);
+ const provider = new StatusbarProvider(context);
+ context.subscriptions.push(provider);
+}
+
+class StatusbarProvider implements NotebookCellStatusBarItemProvider {
+ public get onDidChangeCellStatusBarItems() {
+ return this._onDidChangeCellStatusBarItems.event;
+ }
+ private readonly disposables: Disposable[] = [];
+ private _lineLocation?: "cellstatusbar" | "statusbar";
+ private readonly _onDidChangeCellStatusBarItems = new EventEmitter();
+ private cellStatusbarProvider?: Disposable;
+ private statusbar?: StatusBarItem;
+ private readonly textDocumentPositions = new WeakMap<
+ TextDocument,
+ Position
+ >();
+ private get lineLocation(): "cellstatusbar" | "statusbar" {
+ if (!this._lineLocation) {
+ this._lineLocation = workspace
+ .getConfiguration("notebook")
+ .get<"cellstatusbar" | "statusbar">(
+ "cursorPositionLocation",
+ "statusbar"
+ );
+ }
+ return this._lineLocation;
+ }
+
+ /**
+ * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state.
+ */
+ constructor(private readonly context: ExtensionContext) {
+ this.registerProviders();
+ workspace.onDidChangeConfiguration(
+ this.onDidChangeConfiguration,
+ this,
+ this.disposables
+ );
+ window.onDidChangeTextEditorSelection(
+ this.onDidChangeTextEditorSelection,
+ this,
+ this.disposables
+ );
+ window.onDidChangeNotebookEditorSelection(
+ this.onDidChangeNotebookEditorSelection,
+ this,
+ this.disposables
+ );
+ }
+ public dispose() {
+ this._onDidChangeCellStatusBarItems.dispose();
+ this.disposables.forEach((d) => d.dispose());
+ this.cellStatusbarProvider?.dispose();
+ }
+ public provideCellStatusBarItems(
+ cell: NotebookCell,
+ _token: CancellationToken
+ ): NotebookCellStatusBarItem[] {
+ if (this.lineLocation === "statusbar") {
+ return [];
+ }
+ const activeEditor = window.activeNotebookEditor;
+ if (!activeEditor || activeEditor.document !== cell.notebook) {
+ return [];
+ }
+ if (
+ !activeEditor.selections.some(
+ (range) => range.start <= cell.index && range.end > cell.index
+ )
+ ) {
+ return [];
+ }
+ const item = this.textDocumentPositions.get(cell.document);
+ if (!item) {
+ return [];
+ }
+
+ const line = item.line;
+ const character = item.character;
+ return [
+ new NotebookCellStatusBarItem(
+ `Ln ${line + 1}, Col ${character + 1}`,
+ NotebookCellStatusBarAlignment.Left,
+ undefined,
+ undefined,
+ 999999999999999
+ ),
+ ];
+ }
+ private registerProviders() {
+ if (this.lineLocation === "statusbar") {
+ this.statusbar = window.createStatusBarItem({
+ id: "notebookLinePosition",
+ name: "notebookLine",
+ alignment: StatusBarAlignment.Right,
+ priority: 9999999999,
+ });
+ } else {
+ this.statusbar?.hide();
+ if (!this.cellStatusbarProvider) {
+ this.cellStatusbarProvider = notebook.registerNotebookCellStatusBarItemProvider(
+ { viewType: "*" },
+ this
+ );
+ }
+ }
+ }
+ private doesDocumentBelongToCurrentNotebook(document: TextDocument) {
+ const activeEditor = window.activeNotebookEditor;
+ return activeEditor?.document === document.notebook;
+ }
+ private onDidChangeNotebookEditorSelection(
+ e: NotebookEditorSelectionChangeEvent
+ ) {
+ console.error("1");
+ }
+ private onDidChangeTextEditorSelection(e: TextEditorSelectionChangeEvent) {
+ const document = e.textEditor.document;
+ if (document.notebook) {
+ if (e.selections.length) {
+ this.textDocumentPositions.set(
+ e.textEditor.document,
+ e.selections[0].start
+ );
+ if (this.statusbar && this.lineLocation === "statusbar") {
+ this.statusbar.text = `Ln ${e.selections[0].start.line + 1}, Col ${
+ e.selections[0].start.character + 1
+ }`;
+ this.statusbar.show();
+ }
+ } else {
+ this.statusbar?.hide();
+ this.textDocumentPositions.delete(e.textEditor.document);
+ }
+ if (this.doesDocumentBelongToCurrentNotebook(document)) {
+ this._onDidChangeCellStatusBarItems.fire();
+ }
+ }
+ }
+ private onDidChangeConfiguration(e: ConfigurationChangeEvent) {
+ if (e.affectsConfiguration("notebook.cursorPositionLocation")) {
+ this._lineLocation = undefined;
+ this.registerProviders();
+ }
+ }
+}
+
+// this method is called when your extension is deactivated
+export function deactivate() {}
diff --git a/src/test/runTest.ts b/src/test/runTest.ts
new file mode 100644
index 0000000..1eabfa3
--- /dev/null
+++ b/src/test/runTest.ts
@@ -0,0 +1,23 @@
+import * as path from 'path';
+
+import { runTests } from 'vscode-test';
+
+async function main() {
+ try {
+ // The folder containing the Extension Manifest package.json
+ // Passed to `--extensionDevelopmentPath`
+ const extensionDevelopmentPath = path.resolve(__dirname, '../../');
+
+ // The path to test runner
+ // Passed to --extensionTestsPath
+ const extensionTestsPath = path.resolve(__dirname, './suite/index');
+
+ // Download VS Code, unzip it and run the integration test
+ await runTests({ extensionDevelopmentPath, extensionTestsPath });
+ } catch (err) {
+ console.error('Failed to run tests');
+ process.exit(1);
+ }
+}
+
+main();
diff --git a/src/test/suite/extension.test.ts b/src/test/suite/extension.test.ts
new file mode 100644
index 0000000..4ca0ab4
--- /dev/null
+++ b/src/test/suite/extension.test.ts
@@ -0,0 +1,15 @@
+import * as assert from 'assert';
+
+// You can import and use all API from the 'vscode' module
+// as well as import your extension to test it
+import * as vscode from 'vscode';
+// import * as myExtension from '../../extension';
+
+suite('Extension Test Suite', () => {
+ vscode.window.showInformationMessage('Start all tests.');
+
+ test('Sample test', () => {
+ assert.strictEqual(-1, [1, 2, 3].indexOf(5));
+ assert.strictEqual(-1, [1, 2, 3].indexOf(0));
+ });
+});
diff --git a/src/test/suite/index.ts b/src/test/suite/index.ts
new file mode 100644
index 0000000..7029e38
--- /dev/null
+++ b/src/test/suite/index.ts
@@ -0,0 +1,38 @@
+import * as path from 'path';
+import * as Mocha from 'mocha';
+import * as glob from 'glob';
+
+export function run(): Promise {
+ // Create the mocha test
+ const mocha = new Mocha({
+ ui: 'tdd',
+ color: true
+ });
+
+ const testsRoot = path.resolve(__dirname, '..');
+
+ return new Promise((c, e) => {
+ glob('**/**.test.js', { cwd: testsRoot }, (err, files) => {
+ if (err) {
+ return e(err);
+ }
+
+ // Add files to the test suite
+ files.forEach(f => mocha.addFile(path.resolve(testsRoot, f)));
+
+ try {
+ // Run the mocha test
+ mocha.run(failures => {
+ if (failures > 0) {
+ e(new Error(`${failures} tests failed.`));
+ } else {
+ c();
+ }
+ });
+ } catch (err) {
+ console.error(err);
+ e(err);
+ }
+ });
+ });
+}
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..b65c745
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "module": "commonjs",
+ "target": "es6",
+ "outDir": "out",
+ "lib": [
+ "es6"
+ ],
+ "sourceMap": true,
+ "rootDir": "src",
+ "strict": true /* enable all strict type-checking options */
+ /* Additional Checks */
+ // "noImplicitReturns": true, /* Report error when not all code paths in function return a value. */
+ // "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */
+ // "noUnusedParameters": true, /* Report errors on unused parameters. */
+ },
+ "exclude": [
+ "node_modules",
+ ".vscode-test"
+ ]
+}
diff --git a/vscode.d.ts b/vscode.d.ts
new file mode 100644
index 0000000..7e59e1e
--- /dev/null
+++ b/vscode.d.ts
@@ -0,0 +1,12747 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+declare module 'vscode' {
+
+ /**
+ * The version of the editor.
+ */
+ export const version: string;
+
+ /**
+ * 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.
+ */
+ export interface Command {
+ /**
+ * Title of the command, like `save`.
+ */
+ title: string;
+
+ /**
+ * The identifier of the actual command handler.
+ * @see {@link commands.registerCommand}
+ */
+ command: string;
+
+ /**
+ * A tooltip for the command, when represented in the UI.
+ */
+ tooltip?: string;
+
+ /**
+ * Arguments that the command handler should be
+ * invoked with.
+ */
+ arguments?: any[];
+ }
+
+ /**
+ * Represents a line of text, such as a line of source code.
+ *
+ * TextLine objects are __immutable__. When a {@link TextDocument document} changes,
+ * previously retrieved lines will not represent the latest state.
+ */
+ export interface TextLine {
+
+ /**
+ * The zero-based line number.
+ */
+ readonly lineNumber: number;
+
+ /**
+ * The text of this line without the line separator characters.
+ */
+ readonly text: string;
+
+ /**
+ * The range this line covers without the line separator characters.
+ */
+ readonly range: Range;
+
+ /**
+ * The range this line covers with the line separator characters.
+ */
+ readonly rangeIncludingLineBreak: Range;
+
+ /**
+ * The offset of the first character which is not a whitespace character as defined
+ * by `/\s/`. **Note** that if a line is all whitespace the length of the line is returned.
+ */
+ readonly firstNonWhitespaceCharacterIndex: number;
+
+ /**
+ * Whether this line is whitespace only, shorthand
+ * for {@link TextLine.firstNonWhitespaceCharacterIndex} === {@link TextLine.text TextLine.text.length}.
+ */
+ readonly isEmptyOrWhitespace: boolean;
+ }
+
+ /**
+ * Represents a text document, such as a source file. Text documents have
+ * {@link TextLine lines} and knowledge about an underlying resource like a file.
+ */
+ export interface TextDocument {
+
+ /**
+ * The associated uri for this document.
+ *
+ * *Note* that most documents use the `file`-scheme, which means they are files on disk. However, **not** all documents are
+ * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk.
+ *
+ * @see {@link FileSystemProvider}
+ * @see {@link TextDocumentContentProvider}
+ */
+ readonly uri: Uri;
+
+ /**
+ * The file system path of the associated resource. Shorthand
+ * notation for {@link TextDocument.uri TextDocument.uri.fsPath}. Independent of the uri scheme.
+ */
+ readonly fileName: string;
+
+ /**
+ * Is this document representing an untitled file which has never been saved yet. *Note* that
+ * this does not mean the document will be saved to disk, use {@link Uri.scheme `uri.scheme`}
+ * to figure out where a document will be {@link FileSystemProvider saved}, e.g. `file`, `ftp` etc.
+ */
+ readonly isUntitled: boolean;
+
+ /**
+ * The identifier of the language associated with this document.
+ */
+ readonly languageId: string;
+
+ /**
+ * The version number of this document (it will strictly increase after each
+ * change, including undo/redo).
+ */
+ readonly version: number;
+
+ /**
+ * `true` if there are unpersisted changes.
+ */
+ readonly isDirty: boolean;
+
+ /**
+ * `true` if the document has been closed. A closed document isn't synchronized anymore
+ * and won't be re-used when the same resource is opened again.
+ */
+ readonly isClosed: boolean;
+
+ /**
+ * Save the underlying file.
+ *
+ * @return A promise that will resolve to true when the file
+ * has been saved. If the file was not dirty or the save failed,
+ * will return false.
+ */
+ save(): Thenable;
+
+ /**
+ * The {@link EndOfLine end of line} sequence that is predominately
+ * used in this document.
+ */
+ readonly eol: EndOfLine;
+
+ /**
+ * The number of lines in this document.
+ */
+ readonly lineCount: number;
+
+ /**
+ * 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.
+ *
+ * @param line A line number in [0, lineCount).
+ * @return A {@link TextLine line}.
+ */
+ lineAt(line: number): 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 {@link TextDocument.validatePosition adjusted}.
+ *
+ * @see {@link TextDocument.lineAt}
+ *
+ * @param position A position.
+ * @return A {@link TextLine line}.
+ */
+ lineAt(position: Position): TextLine;
+
+ /**
+ * Converts the position to a zero-based offset.
+ *
+ * The position will be {@link TextDocument.validatePosition adjusted}.
+ *
+ * @param position A position.
+ * @return A valid zero-based offset.
+ */
+ offsetAt(position: Position): number;
+
+ /**
+ * Converts a zero-based offset to a position.
+ *
+ * @param offset A zero-based offset.
+ * @return A valid {@link Position}.
+ */
+ positionAt(offset: number): Position;
+
+ /**
+ * Get the text of this document. A substring can be retrieved by providing
+ * a range. The range will be {@link TextDocument.validateRange adjusted}.
+ *
+ * @param range Include only the text included by the range.
+ * @return The text inside the provided range or the entire text.
+ */
+ getText(range?: Range): string;
+
+ /**
+ * Get a word-range at the given position. By default words are defined by
+ * common separators, like space, -, _, etc. In addition, per language custom
+ * [word definitions} can be defined. It
+ * is also possible to provide a custom regular expression.
+ *
+ * * *Note 1:* A custom regular expression must not match the empty string and
+ * if it does, it will be ignored.
+ * * *Note 2:* A custom regular expression will fail to match multiline strings
+ * and in the name of speed regular expressions should not match words with
+ * spaces. Use {@link TextLine.text `TextLine.text`} for more complex, non-wordy, scenarios.
+ *
+ * The position will be {@link TextDocument.validatePosition adjusted}.
+ *
+ * @param position A position.
+ * @param regex Optional regular expression that describes what a word is.
+ * @return A range spanning a word, or `undefined`.
+ */
+ getWordRangeAtPosition(position: Position, regex?: RegExp): Range | undefined;
+
+ /**
+ * Ensure a range is completely contained in this document.
+ *
+ * @param range A range.
+ * @return The given range or a new, adjusted range.
+ */
+ validateRange(range: Range): Range;
+
+ /**
+ * Ensure a position is contained in the range of this document.
+ *
+ * @param position A position.
+ * @return The given position or a new, adjusted position.
+ */
+ validatePosition(position: Position): Position;
+ }
+
+ /**
+ * Represents a line and character position, such as
+ * the position of the cursor.
+ *
+ * Position objects are __immutable__. Use the {@link Position.with with} or
+ * {@link Position.translate translate} methods to derive new positions
+ * from an existing position.
+ */
+ export class Position {
+
+ /**
+ * The zero-based line value.
+ */
+ readonly line: number;
+
+ /**
+ * The zero-based character value.
+ */
+ readonly character: number;
+
+ /**
+ * @param line A zero-based line value.
+ * @param character A zero-based character value.
+ */
+ constructor(line: number, character: number);
+
+ /**
+ * Check if this position is before `other`.
+ *
+ * @param other A position.
+ * @return `true` if position is on a smaller line
+ * or on the same line on a smaller character.
+ */
+ isBefore(other: Position): boolean;
+
+ /**
+ * Check if this position is before or equal to `other`.
+ *
+ * @param other A position.
+ * @return `true` if position is on a smaller line
+ * or on the same line on a smaller or equal character.
+ */
+ isBeforeOrEqual(other: Position): boolean;
+
+ /**
+ * Check if this position is after `other`.
+ *
+ * @param other A position.
+ * @return `true` if position is on a greater line
+ * or on the same line on a greater character.
+ */
+ isAfter(other: Position): boolean;
+
+ /**
+ * Check if this position is after or equal to `other`.
+ *
+ * @param other A position.
+ * @return `true` if position is on a greater line
+ * or on the same line on a greater or equal character.
+ */
+ isAfterOrEqual(other: Position): boolean;
+
+ /**
+ * Check if this position is equal to `other`.
+ *
+ * @param other A position.
+ * @return `true` if the line and character of the given position are equal to
+ * the line and character of this position.
+ */
+ isEqual(other: Position): boolean;
+
+ /**
+ * Compare this to `other`.
+ *
+ * @param other A position.
+ * @return 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.
+ */
+ compareTo(other: Position): number;
+
+ /**
+ * Create a new position relative to this position.
+ *
+ * @param lineDelta Delta value for the line value, default is `0`.
+ * @param characterDelta Delta value for the character value, default is `0`.
+ * @return A position which line and character is the sum of the current line and
+ * character and the corresponding deltas.
+ */
+ translate(lineDelta?: number, characterDelta?: number): Position;
+
+ /**
+ * Derived a new position relative to this position.
+ *
+ * @param change An object that describes a delta to this position.
+ * @return A position that reflects the given delta. Will return `this` position if the change
+ * is not changing anything.
+ */
+ translate(change: { lineDelta?: number; characterDelta?: number; }): Position;
+
+ /**
+ * Create a new position derived from this position.
+ *
+ * @param line Value that should be used as line value, default is the {@link Position.line existing value}
+ * @param character Value that should be used as character value, default is the {@link Position.character existing value}
+ * @return A position where line and character are replaced by the given values.
+ */
+ with(line?: number, character?: number): Position;
+
+ /**
+ * Derived a new position from this position.
+ *
+ * @param change An object that describes a change to this position.
+ * @return A position that reflects the given change. Will return `this` position if the change
+ * is not changing anything.
+ */
+ with(change: { line?: number; character?: number; }): Position;
+ }
+
+ /**
+ * A range represents an ordered pair of two positions.
+ * It is guaranteed that {@link Range.start start}.isBeforeOrEqual({@link Range.end end})
+ *
+ * Range objects are __immutable__. Use the {@link Range.with with},
+ * {@link Range.intersection intersection}, or {@link Range.union union} methods
+ * to derive new ranges from an existing range.
+ */
+ export class Range {
+
+ /**
+ * The start position. It is before or equal to {@link Range.end end}.
+ */
+ readonly start: Position;
+
+ /**
+ * The end position. It is after or equal to {@link Range.start start}.
+ */
+ readonly end: Position;
+
+ /**
+ * Create a new range from two positions. If `start` is not
+ * before or equal to `end`, the values will be swapped.
+ *
+ * @param start A position.
+ * @param end A position.
+ */
+ constructor(start: Position, end: Position);
+
+ /**
+ * Create a new range from number coordinates. It is a shorter equivalent of
+ * using `new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))`
+ *
+ * @param startLine A zero-based line value.
+ * @param startCharacter A zero-based character value.
+ * @param endLine A zero-based line value.
+ * @param endCharacter A zero-based character value.
+ */
+ constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number);
+
+ /**
+ * `true` if `start` and `end` are equal.
+ */
+ isEmpty: boolean;
+
+ /**
+ * `true` if `start.line` and `end.line` are equal.
+ */
+ isSingleLine: boolean;
+
+ /**
+ * Check if a position or a range is contained in this range.
+ *
+ * @param positionOrRange A position or a range.
+ * @return `true` if the position or range is inside or equal
+ * to this range.
+ */
+ contains(positionOrRange: Position | Range): boolean;
+
+ /**
+ * Check if `other` equals this range.
+ *
+ * @param other A range.
+ * @return `true` when start and end are {@link Position.isEqual equal} to
+ * start and end of this range.
+ */
+ isEqual(other: Range): boolean;
+
+ /**
+ * Intersect `range` with this range and returns a new range or `undefined`
+ * if the ranges have no overlap.
+ *
+ * @param range A range.
+ * @return A range of the greater start and smaller end positions. Will
+ * return undefined when there is no overlap.
+ */
+ intersection(range: Range): Range | undefined;
+
+ /**
+ * Compute the union of `other` with this range.
+ *
+ * @param other A range.
+ * @return A range of smaller start position and the greater end position.
+ */
+ union(other: Range): Range;
+
+ /**
+ * Derived a new range from this range.
+ *
+ * @param start A position that should be used as start. The default value is the {@link Range.start current start}.
+ * @param end A position that should be used as end. The default value is the {@link Range.end current end}.
+ * @return 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.
+ */
+ with(start?: Position, end?: Position): Range;
+
+ /**
+ * Derived a new range from this range.
+ *
+ * @param change An object that describes a change to this range.
+ * @return A range that reflects the given change. Will return `this` range if the change
+ * is not changing anything.
+ */
+ with(change: { start?: Position, end?: Position }): Range;
+ }
+
+ /**
+ * Represents a text selection in an editor.
+ */
+ export class Selection extends Range {
+
+ /**
+ * The position at which the selection starts.
+ * This position might be before or after {@link Selection.active active}.
+ */
+ anchor: Position;
+
+ /**
+ * The position of the cursor.
+ * This position might be before or after {@link Selection.anchor anchor}.
+ */
+ active: Position;
+
+ /**
+ * Create a selection from two positions.
+ *
+ * @param anchor A position.
+ * @param active A position.
+ */
+ constructor(anchor: Position, active: Position);
+
+ /**
+ * Create a selection from four coordinates.
+ *
+ * @param anchorLine A zero-based line value.
+ * @param anchorCharacter A zero-based character value.
+ * @param activeLine A zero-based line value.
+ * @param activeCharacter A zero-based character value.
+ */
+ constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number);
+
+ /**
+ * A selection is reversed if {@link Selection.active active}.isBefore({@link Selection.anchor anchor}).
+ */
+ isReversed: boolean;
+ }
+
+ /**
+ * Represents sources that can cause {@link window.onDidChangeTextEditorSelection selection change events}.
+ */
+ export enum TextEditorSelectionChangeKind {
+ /**
+ * Selection changed due to typing in the editor.
+ */
+ Keyboard = 1,
+ /**
+ * Selection change due to clicking in the editor.
+ */
+ Mouse = 2,
+ /**
+ * Selection changed because a command ran.
+ */
+ Command = 3
+ }
+
+ /**
+ * Represents an event describing the change in a {@link TextEditor.selections text editor's selections}.
+ */
+ export interface TextEditorSelectionChangeEvent {
+ /**
+ * The {@link TextEditor text editor} for which the selections have changed.
+ */
+ readonly textEditor: TextEditor;
+ /**
+ * The new value for the {@link TextEditor.selections text editor's selections}.
+ */
+ readonly selections: ReadonlyArray;
+ /**
+ * The {@link TextEditorSelectionChangeKind change kind} which has triggered this
+ * event. Can be `undefined`.
+ */
+ readonly kind?: TextEditorSelectionChangeKind;
+ }
+
+ /**
+ * Represents an event describing the change in a {@link TextEditor.visibleRanges text editor's visible ranges}.
+ */
+ export interface TextEditorVisibleRangesChangeEvent {
+ /**
+ * The {@link TextEditor text editor} for which the visible ranges have changed.
+ */
+ readonly textEditor: TextEditor;
+ /**
+ * The new value for the {@link TextEditor.visibleRanges text editor's visible ranges}.
+ */
+ readonly visibleRanges: ReadonlyArray;
+ }
+
+ /**
+ * Represents an event describing the change in a {@link TextEditor.options text editor's options}.
+ */
+ export interface TextEditorOptionsChangeEvent {
+ /**
+ * The {@link TextEditor text editor} for which the options have changed.
+ */
+ readonly textEditor: TextEditor;
+ /**
+ * The new value for the {@link TextEditor.options text editor's options}.
+ */
+ readonly options: TextEditorOptions;
+ }
+
+ /**
+ * Represents an event describing the change of a {@link TextEditor.viewColumn text editor's view column}.
+ */
+ export interface TextEditorViewColumnChangeEvent {
+ /**
+ * The {@link TextEditor text editor} for which the view column has changed.
+ */
+ readonly textEditor: TextEditor;
+ /**
+ * The new value for the {@link TextEditor.viewColumn text editor's view column}.
+ */
+ readonly viewColumn: ViewColumn;
+ }
+
+ /**
+ * Rendering style of the cursor.
+ */
+ export enum TextEditorCursorStyle {
+ /**
+ * Render the cursor as a vertical thick line.
+ */
+ Line = 1,
+ /**
+ * Render the cursor as a block filled.
+ */
+ Block = 2,
+ /**
+ * Render the cursor as a thick horizontal line.
+ */
+ Underline = 3,
+ /**
+ * Render the cursor as a vertical thin line.
+ */
+ LineThin = 4,
+ /**
+ * Render the cursor as a block outlined.
+ */
+ BlockOutline = 5,
+ /**
+ * Render the cursor as a thin horizontal line.
+ */
+ UnderlineThin = 6
+ }
+
+ /**
+ * Rendering style of the line numbers.
+ */
+ export enum TextEditorLineNumbersStyle {
+ /**
+ * Do not render the line numbers.
+ */
+ Off = 0,
+ /**
+ * Render the line numbers.
+ */
+ On = 1,
+ /**
+ * Render the line numbers with values relative to the primary cursor location.
+ */
+ Relative = 2
+ }
+
+ /**
+ * Represents a {@link TextEditor text editor}'s {@link TextEditor.options options}.
+ */
+ export interface TextEditorOptions {
+
+ /**
+ * 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 {@link TextEditorOptions.insertSpaces 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"`.
+ */
+ tabSize?: number | string;
+
+ /**
+ * When pressing Tab insert {@link TextEditorOptions.tabSize 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"`.
+ */
+ insertSpaces?: boolean | string;
+
+ /**
+ * The rendering style of the cursor in this editor.
+ * When getting a text editor's options, this property will always be present.
+ * When setting a text editor's options, this property is optional.
+ */
+ cursorStyle?: TextEditorCursorStyle;
+
+ /**
+ * Render relative line numbers w.r.t. the current line number.
+ * When getting a text editor's options, this property will always be present.
+ * When setting a text editor's options, this property is optional.
+ */
+ lineNumbers?: TextEditorLineNumbersStyle;
+ }
+
+ /**
+ * Represents a handle to a set of decorations
+ * sharing the same {@link DecorationRenderOptions styling options} in a {@link TextEditor text editor}.
+ *
+ * To get an instance of a `TextEditorDecorationType` use
+ * {@link window.createTextEditorDecorationType createTextEditorDecorationType}.
+ */
+ export interface TextEditorDecorationType {
+
+ /**
+ * Internal representation of the handle.
+ */
+ readonly key: string;
+
+ /**
+ * Remove this decoration type and all decorations on all text editors using it.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Represents different {@link TextEditor.revealRange reveal} strategies in a text editor.
+ */
+ export enum TextEditorRevealType {
+ /**
+ * The range will be revealed with as little scrolling as possible.
+ */
+ Default = 0,
+ /**
+ * The range will always be revealed in the center of the viewport.
+ */
+ InCenter = 1,
+ /**
+ * If the range is outside the viewport, it will be revealed in the center of the viewport.
+ * Otherwise, it will be revealed with as little scrolling as possible.
+ */
+ InCenterIfOutsideViewport = 2,
+ /**
+ * The range will always be revealed at the top of the viewport.
+ */
+ AtTop = 3
+ }
+
+ /**
+ * Represents different positions for rendering a decoration in an {@link DecorationRenderOptions.overviewRulerLane overview ruler}.
+ * The overview ruler supports three lanes.
+ */
+ export enum OverviewRulerLane {
+ Left = 1,
+ Center = 2,
+ Right = 4,
+ Full = 7
+ }
+
+ /**
+ * Describes the behavior of decorations when typing/editing at their edges.
+ */
+ export enum DecorationRangeBehavior {
+ /**
+ * The decoration's range will widen when edits occur at the start or end.
+ */
+ OpenOpen = 0,
+ /**
+ * The decoration's range will not widen when edits occur at the start of end.
+ */
+ ClosedClosed = 1,
+ /**
+ * The decoration's range will widen when edits occur at the start, but not at the end.
+ */
+ OpenClosed = 2,
+ /**
+ * The decoration's range will widen when edits occur at the end, but not at the start.
+ */
+ ClosedOpen = 3
+ }
+
+ /**
+ * Represents options to configure the behavior of showing a {@link TextDocument document} in an {@link TextEditor editor}.
+ */
+ export interface TextDocumentShowOptions {
+ /**
+ * An optional view column in which the {@link TextEditor editor} should be shown.
+ * The default is the {@link ViewColumn.Active active}, other values are adjusted to
+ * be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is
+ * not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`} to open the
+ * editor to the side of the currently active one.
+ */
+ viewColumn?: ViewColumn;
+
+ /**
+ * An optional flag that when `true` will stop the {@link TextEditor editor} from taking focus.
+ */
+ preserveFocus?: boolean;
+
+ /**
+ * An optional flag that controls if an {@link TextEditor editor}-tab will be replaced
+ * with the next editor or if it will be kept.
+ */
+ preview?: boolean;
+
+ /**
+ * An optional selection to apply for the document in the {@link TextEditor editor}.
+ */
+ selection?: Range;
+ }
+
+ /**
+ * A reference to one of the workbench colors as defined in https://code.visualstudio.com/docs/getstarted/theme-color-reference.
+ * Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.
+ */
+ export class ThemeColor {
+
+ /**
+ * Creates a reference to a theme color.
+ * @param id of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference.
+ */
+ constructor(id: string);
+ }
+
+ /**
+ * A reference to a named icon. Currently, {@link ThemeIcon.File File}, {@link ThemeIcon.Folder Folder},
+ * and [ThemeIcon ids](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing) are supported.
+ * Using a theme icon is preferred over a custom icon as it gives product theme authors the possibility to change the icons.
+ *
+ * *Note* that theme icons can also be rendered inside labels and descriptions. Places that support theme icons spell this out
+ * and they use the `$()`-syntax, for instance `quickPick.label = "Hello World $(globe)"`.
+ */
+ export class ThemeIcon {
+ /**
+ * Reference to an icon representing a file. The icon is taken from the current file icon theme or a placeholder icon is used.
+ */
+ static readonly File: ThemeIcon;
+
+ /**
+ * Reference to an icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon is used.
+ */
+ static readonly Folder: ThemeIcon;
+
+ /**
+ * The id of the icon. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing.
+ */
+ readonly id: string;
+
+ /**
+ * The optional ThemeColor of the icon. The color is currently only used in {@link TreeItem}.
+ */
+ readonly color?: ThemeColor;
+
+ /**
+ * Creates a reference to a theme icon.
+ * @param id id of the icon. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing.
+ * @param color optional `ThemeColor` for the icon. The color is currently only used in {@link TreeItem}.
+ */
+ constructor(id: string, color?: ThemeColor);
+ }
+
+ /**
+ * Represents theme specific rendering styles for a {@link TextEditorDecorationType text editor decoration}.
+ */
+ export interface ThemableDecorationRenderOptions {
+ /**
+ * Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations.
+ * Alternatively a color from the color registry can be {@link ThemeColor referenced}.
+ */
+ backgroundColor?: string | ThemeColor;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ outline?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'outline' for setting one or more of the individual outline properties.
+ */
+ outlineColor?: string | ThemeColor;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'outline' for setting one or more of the individual outline properties.
+ */
+ outlineStyle?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'outline' for setting one or more of the individual outline properties.
+ */
+ outlineWidth?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ border?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'border' for setting one or more of the individual border properties.
+ */
+ borderColor?: string | ThemeColor;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'border' for setting one or more of the individual border properties.
+ */
+ borderRadius?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'border' for setting one or more of the individual border properties.
+ */
+ borderSpacing?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'border' for setting one or more of the individual border properties.
+ */
+ borderStyle?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ * Better use 'border' for setting one or more of the individual border properties.
+ */
+ borderWidth?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ fontStyle?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ fontWeight?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ textDecoration?: 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.
+ */
+ color?: string | ThemeColor;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ opacity?: string;
+
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ letterSpacing?: string;
+
+ /**
+ * An **absolute path** or an URI to an image to be rendered in the gutter.
+ */
+ gutterIconPath?: string | Uri;
+
+ /**
+ * Specifies the size of the gutter icon.
+ * Available values are 'auto', 'contain', 'cover' and any percentage value.
+ * For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx
+ */
+ gutterIconSize?: string;
+
+ /**
+ * The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.
+ */
+ overviewRulerColor?: string | ThemeColor;
+
+ /**
+ * Defines the rendering options of the attachment that is inserted before the decorated text.
+ */
+ before?: ThemableDecorationAttachmentRenderOptions;
+
+ /**
+ * Defines the rendering options of the attachment that is inserted after the decorated text.
+ */
+ after?: ThemableDecorationAttachmentRenderOptions;
+ }
+
+ export interface ThemableDecorationAttachmentRenderOptions {
+ /**
+ * Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.
+ */
+ contentText?: string;
+ /**
+ * An **absolute path** or an URI to an image to be rendered in the attachment. Either an icon
+ * or a text can be shown, but not both.
+ */
+ contentIconPath?: string | Uri;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ border?: string;
+ /**
+ * CSS styling property that will be applied to text enclosed by a decoration.
+ */
+ borderColor?: string | ThemeColor;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ fontStyle?: string;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ fontWeight?: string;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ textDecoration?: string;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ color?: string | ThemeColor;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ backgroundColor?: string | ThemeColor;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ margin?: string;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ width?: string;
+ /**
+ * CSS styling property that will be applied to the decoration attachment.
+ */
+ height?: string;
+ }
+
+ /**
+ * Represents rendering styles for a {@link TextEditorDecorationType text editor decoration}.
+ */
+ export interface DecorationRenderOptions extends ThemableDecorationRenderOptions {
+ /**
+ * Should the decoration be rendered also on the whitespace after the line text.
+ * Defaults to `false`.
+ */
+ isWholeLine?: boolean;
+
+ /**
+ * Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range.
+ * Defaults to `DecorationRangeBehavior.OpenOpen`.
+ */
+ rangeBehavior?: DecorationRangeBehavior;
+
+ /**
+ * The position in the overview ruler where the decoration should be rendered.
+ */
+ overviewRulerLane?: OverviewRulerLane;
+
+ /**
+ * Overwrite options for light themes.
+ */
+ light?: ThemableDecorationRenderOptions;
+
+ /**
+ * Overwrite options for dark themes.
+ */
+ dark?: ThemableDecorationRenderOptions;
+ }
+
+ /**
+ * Represents options for a specific decoration in a {@link TextEditorDecorationType decoration set}.
+ */
+ export interface DecorationOptions {
+
+ /**
+ * Range to which this decoration is applied. The range must not be empty.
+ */
+ range: Range;
+
+ /**
+ * A message that should be rendered when hovering over the decoration.
+ */
+ hoverMessage?: MarkedString | MarkedString[];
+
+ /**
+ * Render options applied to the current decoration. For performance reasons, keep the
+ * number of decoration specific options small, and use decoration types wherever possible.
+ */
+ renderOptions?: DecorationInstanceRenderOptions;
+ }
+
+ export interface ThemableDecorationInstanceRenderOptions {
+ /**
+ * Defines the rendering options of the attachment that is inserted before the decorated text.
+ */
+ before?: ThemableDecorationAttachmentRenderOptions;
+
+ /**
+ * Defines the rendering options of the attachment that is inserted after the decorated text.
+ */
+ after?: ThemableDecorationAttachmentRenderOptions;
+ }
+
+ export interface DecorationInstanceRenderOptions extends ThemableDecorationInstanceRenderOptions {
+ /**
+ * Overwrite options for light themes.
+ */
+ light?: ThemableDecorationInstanceRenderOptions;
+
+ /**
+ * Overwrite options for dark themes.
+ */
+ dark?: ThemableDecorationInstanceRenderOptions;
+ }
+
+ /**
+ * Represents an editor that is attached to a {@link TextDocument document}.
+ */
+ export interface TextEditor {
+
+ /**
+ * The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.
+ */
+ readonly document: TextDocument;
+
+ /**
+ * The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`.
+ */
+ selection: Selection;
+
+ /**
+ * The selections in this text editor. The primary selection is always at index 0.
+ */
+ selections: Selection[];
+
+ /**
+ * The current visible ranges in the editor (vertically).
+ * This accounts only for vertical scrolling, and not for horizontal scrolling.
+ */
+ readonly visibleRanges: Range[];
+
+ /**
+ * Text editor options.
+ */
+ options: TextEditorOptions;
+
+ /**
+ * The column in which this editor shows. Will be `undefined` in case this
+ * isn't one of the main editors, e.g. an embedded editor, or when the editor
+ * column is larger than three.
+ */
+ readonly viewColumn?: ViewColumn;
+
+ /**
+ * Perform an edit on the document associated with this text editor.
+ *
+ * The given callback-function is invoked with an {@link TextEditorEdit edit-builder} which must
+ * be used to make edits. Note that the edit-builder is only valid while the
+ * callback executes.
+ *
+ * @param callback A function which can create edits using an {@link TextEditorEdit edit-builder}.
+ * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
+ * @return A promise that resolves with a value indicating if the edits could be applied.
+ */
+ edit(callback: (editBuilder: TextEditorEdit) => void, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable;
+
+ /**
+ * Insert a {@link SnippetString snippet} and put the editor into snippet mode. "Snippet mode"
+ * means the editor adds placeholders and additional cursors so that the user can complete
+ * or accept the snippet.
+ *
+ * @param snippet The snippet to insert in this edit.
+ * @param location Position or range at which to insert the snippet, defaults to the current editor selection or selections.
+ * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
+ * @return A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal
+ * that the snippet is completely filled-in or accepted.
+ */
+ insertSnippet(snippet: SnippetString, location?: Position | Range | ReadonlyArray | ReadonlyArray, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable;
+
+ /**
+ * Adds a set of decorations to the text editor. If a set of decorations already exists with
+ * the given {@link TextEditorDecorationType decoration type}, they will be replaced.
+ *
+ * @see {@link window.createTextEditorDecorationType createTextEditorDecorationType}.
+ *
+ * @param decorationType A decoration type.
+ * @param rangesOrOptions Either {@link Range ranges} or more detailed {@link DecorationOptions options}.
+ */
+ setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void;
+
+ /**
+ * Scroll as indicated by `revealType` in order to reveal the given range.
+ *
+ * @param range A range.
+ * @param revealType The scrolling strategy for revealing `range`.
+ */
+ revealRange(range: Range, revealType?: TextEditorRevealType): void;
+
+ /**
+ * Show the text editor.
+ *
+ * @deprecated Use {@link window.showTextDocument} instead.
+ *
+ * @param column The {@link ViewColumn column} in which to show this editor.
+ * This method shows unexpected behavior and will be removed in the next major update.
+ */
+ show(column?: ViewColumn): void;
+
+ /**
+ * Hide the text editor.
+ *
+ * @deprecated Use the command `workbench.action.closeActiveEditor` instead.
+ * This method shows unexpected behavior and will be removed in the next major update.
+ */
+ hide(): void;
+ }
+
+ /**
+ * Represents an end of line character sequence in a {@link TextDocument document}.
+ */
+ export enum EndOfLine {
+ /**
+ * The line feed `\n` character.
+ */
+ LF = 1,
+ /**
+ * The carriage return line feed `\r\n` sequence.
+ */
+ CRLF = 2
+ }
+
+ /**
+ * 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 {@link TextDocument document} associated with a {@link TextEditor text editor}.
+ */
+ export interface TextEditorEdit {
+ /**
+ * 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 {@link TextDocument document}.
+ *
+ * @param location The range this operation should remove.
+ * @param value The new text this operation should insert after removing `location`.
+ */
+ replace(location: Position | Range | Selection, 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 {@link TextDocument document}.
+ * Although the equivalent text edit can be made with {@link TextEditorEdit.replace replace}, `insert` will produce a different resulting selection (it will get moved).
+ *
+ * @param location The position where the new text should be inserted.
+ * @param value The new text this operation should insert.
+ */
+ insert(location: Position, value: string): void;
+
+ /**
+ * Delete a certain text region.
+ *
+ * @param location The range this operation should remove.
+ */
+ delete(location: Range | Selection): void;
+
+ /**
+ * Set the end of line sequence.
+ *
+ * @param endOfLine The new end of line for the {@link TextDocument document}.
+ */
+ setEndOfLine(endOfLine: EndOfLine): void;
+ }
+
+ /**
+ * A universal resource identifier representing either a file on disk
+ * or another resource, like untitled resources.
+ */
+ export class Uri {
+
+ /**
+ * Create an URI from a string, e.g. `http://www.msft.com/some/path`,
+ * `file:///usr/home`, or `scheme:with/path`.
+ *
+ * *Note* that for a while uris without a `scheme` were accepted. That is not correct
+ * as all uris should have a scheme. To avoid breakage of existing code the optional
+ * `strict`-argument has been added. We *strongly* advise to use it, e.g. `Uri.parse('my:uri', true)`
+ *
+ * @see {@link Uri.toString}
+ * @param value The string value of an Uri.
+ * @param strict Throw an error when `value` is empty or when no `scheme` can be parsed.
+ * @return A new Uri instance.
+ */
+ static parse(value: string, strict?: boolean): Uri;
+
+ /**
+ * Create an URI from a file system path. The {@link Uri.scheme scheme}
+ * will be `file`.
+ *
+ * The *difference* between {@link Uri.parse} and {@link Uri.file} is that the latter treats the argument
+ * as path, not as stringified-uri. E.g. `Uri.file(path)` is *not* the same as
+ * `Uri.parse('file://' + path)` because the path might contain characters that are
+ * interpreted (# and ?). See the following sample:
+ * ```ts
+ const good = URI.file('/coding/c#/project1');
+ good.scheme === 'file';
+ good.path === '/coding/c#/project1';
+ good.fragment === '';
+
+ const bad = URI.parse('file://' + '/coding/c#/project1');
+ bad.scheme === 'file';
+ bad.path === '/coding/c'; // path is now broken
+ bad.fragment === '/project1';
+ ```
+ *
+ * @param path A file system or UNC path.
+ * @return A new Uri instance.
+ */
+ static file(path: string): Uri;
+
+ /**
+ * Create a new uri which path is the result of joining
+ * the path of the base uri with the provided path segments.
+ *
+ * - Note 1: `joinPath` only affects the path component
+ * and all other components (scheme, authority, query, and fragment) are
+ * left as they are.
+ * - Note 2: The base uri must have a path; an error is thrown otherwise.
+ *
+ * The path segments are normalized in the following ways:
+ * - sequences of path separators (`/` or `\`) are replaced with a single separator
+ * - for `file`-uris on windows, the backslash-character (`\`) is considered a path-separator
+ * - the `..`-segment denotes the parent segment, the `.` denotes the current segment
+ * - paths have a root which always remains, for instance on windows drive-letters are roots
+ * so that is true: `joinPath(Uri.file('file:///c:/root'), '../../other').fsPath === 'c:/other'`
+ *
+ * @param base An uri. Must have a path.
+ * @param pathSegments One more more path fragments
+ * @returns A new uri which path is joined with the given fragments
+ */
+ static joinPath(base: Uri, ...pathSegments: string[]): Uri;
+
+ /**
+ * Use the `file` and `parse` factory functions to create new `Uri` objects.
+ */
+ private constructor(scheme: string, authority: string, path: string, query: string, fragment: string);
+
+ /**
+ * Scheme is the `http` part of `http://www.msft.com/some/path?query#fragment`.
+ * The part before the first colon.
+ */
+ readonly scheme: 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.
+ */
+ readonly authority: string;
+
+ /**
+ * Path is the `/some/path` part of `http://www.msft.com/some/path?query#fragment`.
+ */
+ readonly path: string;
+
+ /**
+ * Query is the `query` part of `http://www.msft.com/some/path?query#fragment`.
+ */
+ readonly query: string;
+
+ /**
+ * Fragment is the `fragment` part of `http://www.msft.com/some/path?query#fragment`.
+ */
+ readonly fragment: 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.
+ * * The resulting string shall *not* be used for display purposes but
+ * for disk operations, like `readFile` et al.
+ *
+ * The *difference* to the {@link Uri.path `path`}-property is the use of the platform specific
+ * path separator and the handling of UNC paths. The sample below outlines the difference:
+ * ```ts
+ const u = URI.parse('file://server/c$/folder/file.txt')
+ u.authority === 'server'
+ u.path === '/shares/c$/file.txt'
+ u.fsPath === '\\server\c$\folder\file.txt'
+ ```
+ */
+ readonly fsPath: string;
+
+ /**
+ * Derive a new Uri from this Uri.
+ *
+ * ```ts
+ * let file = Uri.parse('before:some/file/path');
+ * let other = file.with({ scheme: 'after' });
+ * assert.ok(other.toString() === 'after:some/file/path');
+ * ```
+ *
+ * @param change An object that describes a change to this Uri. To unset components use `null` or
+ * the empty string.
+ * @return A new Uri that reflects the given change. Will return `this` Uri if the change
+ * is not changing anything.
+ */
+ with(change: { scheme?: string; authority?: string; path?: string; query?: string; fragment?: string }): Uri;
+
+ /**
+ * Returns a string representation of this Uri. The representation and normalization
+ * of a URI depends on the scheme.
+ *
+ * * The resulting string can be safely used with {@link Uri.parse}.
+ * * The resulting string shall *not* be used for display purposes.
+ *
+ * *Note* that the implementation will encode _aggressive_ which often leads to unexpected,
+ * but not incorrect, results. For instance, colons are encoded to `%3A` which might be unexpected
+ * in file-uri. Also `&` and `=` will be encoded which might be unexpected for http-uris. For stability
+ * reasons this cannot be changed anymore. If you suffer from too aggressive encoding you should use
+ * the `skipEncoding`-argument: `uri.toString(true)`.
+ *
+ * @param skipEncoding Do not percentage-encode the result, defaults to `false`. Note that
+ * the `#` and `?` characters occurring in the path will always be encoded.
+ * @returns A string representation of this Uri.
+ */
+ toString(skipEncoding?: boolean): string;
+
+ /**
+ * Returns a JSON representation of this Uri.
+ *
+ * @return An object.
+ */
+ toJSON(): any;
+ }
+
+ /**
+ * 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
+ * {@link CancellationTokenSource}.
+ */
+ export interface CancellationToken {
+
+ /**
+ * Is `true` when the token has been cancelled, `false` otherwise.
+ */
+ isCancellationRequested: boolean;
+
+ /**
+ * An {@link Event} which fires upon cancellation.
+ */
+ onCancellationRequested: Event;
+ }
+
+ /**
+ * A cancellation source creates and controls a {@link CancellationToken cancellation token}.
+ */
+ export class CancellationTokenSource {
+
+ /**
+ * The cancellation token of this source.
+ */
+ token: CancellationToken;
+
+ /**
+ * Signal cancellation on the token.
+ */
+ cancel(): void;
+
+ /**
+ * Dispose object and free resources.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * An error type that should be used to signal cancellation of an operation.
+ *
+ * This type can be used in response to a {@link CancellationToken cancellation token}
+ * being cancelled or when an operation is being cancelled by the
+ * executor of that operation.
+ */
+ export class CancellationError extends Error {
+
+ /**
+ * Creates a new cancellation error.
+ */
+ constructor();
+ }
+
+ /**
+ * Represents a type which can release resources, such
+ * as event listening or a timer.
+ */
+ export class Disposable {
+
+ /**
+ * Combine many disposable-likes into one. Use this method
+ * when having objects with a dispose function which are not
+ * instances of Disposable.
+ *
+ * @param disposableLikes Objects that have at least a `dispose`-function member.
+ * @return Returns a new disposable which, upon dispose, will
+ * dispose all provided disposables.
+ */
+ static from(...disposableLikes: { dispose: () => any }[]): Disposable;
+
+ /**
+ * Creates a new Disposable calling the provided function
+ * on dispose.
+ * @param callOnDispose Function that disposes something.
+ */
+ constructor(callOnDispose: Function);
+
+ /**
+ * Dispose this object.
+ */
+ dispose(): any;
+ }
+
+ /**
+ * Represents a typed event.
+ *
+ * A function that represents an event to which you subscribe by calling it with
+ * a listener function as argument.
+ *
+ * @example
+ * item.onDidChange(function(event) { console.log("Event happened: " + event); });
+ */
+ export interface Event {
+
+ /**
+ * A function that represents an event to which you subscribe by calling it with
+ * a listener function as argument.
+ *
+ * @param listener The listener function will be called when the event happens.
+ * @param thisArgs The `this`-argument which will be used when calling the event listener.
+ * @param disposables An array to which a {@link Disposable} will be added.
+ * @return A disposable which unsubscribes the event listener.
+ */
+ (listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable;
+ }
+
+ /**
+ * An event emitter can be used to create and manage an {@link 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 {@link TextDocumentContentProvider} or when providing
+ * API to other extensions.
+ */
+ export class EventEmitter {
+
+ /**
+ * The event listeners can subscribe to.
+ */
+ event: Event;
+
+ /**
+ * Notify all subscribers of the {@link EventEmitter.event event}. Failure
+ * of one or more listener will not fail this function call.
+ *
+ * @param data The event object.
+ */
+ fire(data: T): void;
+
+ /**
+ * Dispose this object and free resources.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * A file system watcher notifies about changes to files and folders
+ * on disk or from other {@link FileSystemProvider FileSystemProviders}.
+ *
+ * To get an instance of a `FileSystemWatcher` use
+ * {@link workspace.createFileSystemWatcher createFileSystemWatcher}.
+ */
+ export interface FileSystemWatcher extends Disposable {
+
+ /**
+ * true if this file system watcher has been created such that
+ * it ignores creation file system events.
+ */
+ ignoreCreateEvents: boolean;
+
+ /**
+ * true if this file system watcher has been created such that
+ * it ignores change file system events.
+ */
+ ignoreChangeEvents: boolean;
+
+ /**
+ * true if this file system watcher has been created such that
+ * it ignores delete file system events.
+ */
+ ignoreDeleteEvents: boolean;
+
+ /**
+ * An event which fires on file/folder creation.
+ */
+ onDidCreate: Event;
+
+ /**
+ * An event which fires on file/folder change.
+ */
+ onDidChange: Event;
+
+ /**
+ * An event which fires on file/folder deletion.
+ */
+ onDidDelete: Event;
+ }
+
+ /**
+ * 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 {@link workspace.registerTextDocumentContentProvider registered}
+ * for a {@link Uri.scheme uri-scheme}. When a uri with that scheme is to
+ * be {@link workspace.openTextDocument loaded} the content provider is
+ * asked.
+ */
+ export interface TextDocumentContentProvider {
+
+ /**
+ * An event to signal a resource has changed.
+ */
+ onDidChange?: Event;
+
+ /**
+ * Provide textual content for a given uri.
+ *
+ * The editor will use the returned string-content to create a readonly
+ * {@link TextDocument document}. Resources allocated should be released when
+ * the corresponding document has been {@link workspace.onDidCloseTextDocument closed}.
+ *
+ * **Note**: The contents of the created {@link TextDocument document} might not be
+ * identical to the provided text due to end-of-line-sequence normalization.
+ *
+ * @param uri An uri which scheme matches the scheme this provider was {@link workspace.registerTextDocumentContentProvider registered} for.
+ * @param token A cancellation token.
+ * @return A string or a thenable that resolves to such.
+ */
+ provideTextDocumentContent(uri: Uri, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Represents an item that can be selected from
+ * a list of items.
+ */
+ export interface QuickPickItem {
+
+ /**
+ * A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via
+ * the `$()`-syntax.
+ */
+ label: string;
+
+ /**
+ * A human-readable string which is rendered less prominent in the same line. Supports rendering of
+ * {@link ThemeIcon theme icons} via the `$()`-syntax.
+ */
+ description?: string;
+
+ /**
+ * A human-readable string which is rendered less prominent in a separate line. Supports rendering of
+ * {@link ThemeIcon theme icons} via the `$()`-syntax.
+ */
+ detail?: string;
+
+ /**
+ * Optional flag indicating if this item is picked initially.
+ * (Only honored when the picker allows multiple selections.)
+ *
+ * @see {@link QuickPickOptions.canPickMany}
+ */
+ picked?: boolean;
+
+ /**
+ * Always show this item.
+ */
+ alwaysShow?: boolean;
+ }
+
+ /**
+ * Options to configure the behavior of the quick pick UI.
+ */
+ export interface QuickPickOptions {
+
+ /**
+ * An optional string that represents the title of the quick pick.
+ */
+ title?: string;
+
+ /**
+ * An optional flag to include the description when filtering the picks.
+ */
+ matchOnDescription?: boolean;
+
+ /**
+ * An optional flag to include the detail when filtering the picks.
+ */
+ matchOnDetail?: boolean;
+
+ /**
+ * An optional string to show as placeholder in the input box to guide the user what to pick on.
+ */
+ placeHolder?: string;
+
+ /**
+ * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
+ */
+ ignoreFocusOut?: boolean;
+
+ /**
+ * An optional flag to make the picker accept multiple selections, if true the result is an array of picks.
+ */
+ canPickMany?: boolean;
+
+ /**
+ * An optional function that is invoked whenever an item is selected.
+ */
+ onDidSelectItem?(item: QuickPickItem | string): any;
+ }
+
+ /**
+ * Options to configure the behaviour of the {@link WorkspaceFolder workspace folder} pick UI.
+ */
+ export interface WorkspaceFolderPickOptions {
+
+ /**
+ * An optional string to show as placeholder in the input box to guide the user what to pick on.
+ */
+ placeHolder?: string;
+
+ /**
+ * Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
+ */
+ ignoreFocusOut?: boolean;
+ }
+
+ /**
+ * Options to configure the behaviour of a file open dialog.
+ *
+ * * Note 1: On Windows and Linux, a file dialog cannot be both a file selector and a folder selector, so if you
+ * set both `canSelectFiles` and `canSelectFolders` to `true` on these platforms, a folder selector will be shown.
+ * * Note 2: Explicitly setting `canSelectFiles` and `canSelectFolders` to `false` is futile
+ * and the editor then silently adjusts the options to select files.
+ */
+ export interface OpenDialogOptions {
+ /**
+ * The resource the dialog shows when opened.
+ */
+ defaultUri?: Uri;
+
+ /**
+ * A human-readable string for the open button.
+ */
+ openLabel?: string;
+
+ /**
+ * Allow to select files, defaults to `true`.
+ */
+ canSelectFiles?: boolean;
+
+ /**
+ * Allow to select folders, defaults to `false`.
+ */
+ canSelectFolders?: boolean;
+
+ /**
+ * Allow to select many files or folders.
+ */
+ canSelectMany?: boolean;
+
+ /**
+ * A set of file filters that are used by the dialog. Each entry is a human-readable label,
+ * like "TypeScript", and an array of extensions, e.g.
+ * ```ts
+ * {
+ * 'Images': ['png', 'jpg']
+ * 'TypeScript': ['ts', 'tsx']
+ * }
+ * ```
+ */
+ filters?: { [name: string]: string[] };
+
+ /**
+ * Dialog title.
+ *
+ * This parameter might be ignored, as not all operating systems display a title on open dialogs
+ * (for example, macOS).
+ */
+ title?: string;
+ }
+
+ /**
+ * Options to configure the behaviour of a file save dialog.
+ */
+ export interface SaveDialogOptions {
+ /**
+ * The resource the dialog shows when opened.
+ */
+ defaultUri?: Uri;
+
+ /**
+ * A human-readable string for the save button.
+ */
+ saveLabel?: string;
+
+ /**
+ * A set of file filters that are used by the dialog. Each entry is a human-readable label,
+ * like "TypeScript", and an array of extensions, e.g.
+ * ```ts
+ * {
+ * 'Images': ['png', 'jpg']
+ * 'TypeScript': ['ts', 'tsx']
+ * }
+ * ```
+ */
+ filters?: { [name: string]: string[] };
+
+ /**
+ * Dialog title.
+ *
+ * This parameter might be ignored, as not all operating systems display a title on save dialogs
+ * (for example, macOS).
+ */
+ title?: string;
+ }
+
+ /**
+ * Represents an action that is shown with an information, warning, or
+ * error message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ * @see {@link window.showWarningMessage showWarningMessage}
+ * @see {@link window.showErrorMessage showErrorMessage}
+ */
+ export interface MessageItem {
+
+ /**
+ * A short title like 'Retry', 'Open Log' etc.
+ */
+ title: string;
+
+ /**
+ * A hint for modal dialogs that the item should be triggered
+ * when the user cancels the dialog (e.g. by pressing the ESC
+ * key).
+ *
+ * Note: this option is ignored for non-modal messages.
+ */
+ isCloseAffordance?: boolean;
+ }
+
+ /**
+ * Options to configure the behavior of the message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ * @see {@link window.showWarningMessage showWarningMessage}
+ * @see {@link window.showErrorMessage showErrorMessage}
+ */
+ export interface MessageOptions {
+
+ /**
+ * Indicates that this message should be modal.
+ */
+ modal?: boolean;
+ }
+
+ /**
+ * Options to configure the behavior of the input box UI.
+ */
+ export interface InputBoxOptions {
+
+ /**
+ * An optional string that represents the title of the input box.
+ */
+ title?: string;
+
+ /**
+ * The value to prefill in the input box.
+ */
+ value?: string;
+
+ /**
+ * Selection of the prefilled {@link InputBoxOptions.value `value`}. Defined as tuple of two number where the
+ * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole
+ * word will be selected, when empty (start equals end) only the cursor will be set,
+ * otherwise the defined range will be selected.
+ */
+ valueSelection?: [number, number];
+
+ /**
+ * The text to display underneath the input box.
+ */
+ prompt?: string;
+
+ /**
+ * An optional string to show as placeholder in the input box to guide the user what to type.
+ */
+ placeHolder?: string;
+
+ /**
+ * Controls if a password input is shown. Password input hides the typed text.
+ */
+ password?: boolean;
+
+ /**
+ * Set to `true` to keep the input box open when focus moves to another part of the editor or to another window.
+ */
+ ignoreFocusOut?: boolean;
+
+ /**
+ * An optional function that will be called to validate input and to give a hint
+ * to the user.
+ *
+ * @param value The current value of the input box.
+ * @return A human-readable string which is presented as diagnostic message.
+ * Return `undefined`, `null`, or the empty string when 'value' is valid.
+ */
+ validateInput?(value: string): string | undefined | null | Thenable;
+ }
+
+ /**
+ * A relative pattern is a helper to construct glob patterns that are matched
+ * relatively to a base file path. The base path can either be an absolute file
+ * path as string or uri or a {@link WorkspaceFolder workspace folder}, which is the
+ * preferred way of creating the relative pattern.
+ */
+ export class RelativePattern {
+
+ /**
+ * A base file path to which this pattern will be matched against relatively.
+ */
+ base: string;
+
+ /**
+ * A file glob pattern like `*.{ts,js}` that will be matched on file paths
+ * relative to the base path.
+ *
+ * Example: Given a base of `/home/work/folder` and a file path of `/home/work/folder/index.js`,
+ * the file glob pattern will match on `index.js`.
+ */
+ pattern: string;
+
+ /**
+ * Creates a new relative pattern object with a base file path and pattern to match. This pattern
+ * will be matched on file paths relative to the base.
+ *
+ * Example:
+ * ```ts
+ * const folder = vscode.workspace.workspaceFolders?.[0];
+ * if (folder) {
+ *
+ * // Match any TypeScript file in the root of this workspace folder
+ * const pattern1 = new vscode.RelativePattern(folder, '*.ts');
+ *
+ * // Match any TypeScript file in `someFolder` inside this workspace folder
+ * const pattern2 = new vscode.RelativePattern(folder, 'someFolder/*.ts');
+ * }
+ * ```
+ *
+ * @param base A base to which this pattern will be matched against relatively. It is recommended
+ * to pass in a {@link WorkspaceFolder workspace folder} if the pattern should match inside the workspace.
+ * Otherwise, a uri or string should only be used if the pattern is for a file path outside the workspace.
+ * @param pattern A file glob pattern like `*.{ts,js}` that will be matched on paths relative to the base.
+ */
+ constructor(base: WorkspaceFolder | Uri | string, pattern: string)
+ }
+
+ /**
+ * A file glob pattern to match file paths against. This can either be a glob pattern string
+ * (like `**​/*.{ts,js}` or `*.{ts,js}`) or a {@link RelativePattern relative pattern}.
+ *
+ * Glob patterns can have the following syntax:
+ * * `*` to match one or more characters in a path segment
+ * * `?` to match on one character in a path segment
+ * * `**` to match any number of path segments, including none
+ * * `{}` to group conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and JavaScript files)
+ * * `[]` to declare a range of characters to match in a path segment (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …)
+ * * `[!...]` to negate a range of characters to match in a path segment (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not `example.0`)
+ *
+ * Note: a backslash (`\`) is not valid within a glob pattern. If you have an existing file
+ * path to match against, consider to use the {@link RelativePattern relative pattern} support
+ * that takes care of converting any backslash into slash. Otherwise, make sure to convert
+ * any backslash to slash when creating the glob pattern.
+ */
+ export type GlobPattern = string | RelativePattern;
+
+ /**
+ * A document filter denotes a document by different properties like
+ * the {@link TextDocument.languageId language}, the {@link Uri.scheme scheme} of
+ * its resource, or a glob-pattern that is applied to the {@link TextDocument.fileName path}.
+ *
+ * @example A language filter that applies to typescript files on disk
+ * { language: 'typescript', scheme: 'file' }
+ *
+ * @example A language filter that applies to all package.json paths
+ * { language: 'json', scheme: 'untitled', pattern: '**​/package.json' }
+ */
+ export interface DocumentFilter {
+
+ /**
+ * A language id, like `typescript`.
+ */
+ readonly language?: string;
+
+ /**
+ * A Uri {@link Uri.scheme scheme}, like `file` or `untitled`.
+ */
+ readonly scheme?: string;
+
+ /**
+ * A {@link GlobPattern glob pattern} that is matched on the absolute path of the document. Use a {@link RelativePattern relative pattern}
+ * to filter documents to a {@link WorkspaceFolder workspace folder}.
+ */
+ readonly pattern?: GlobPattern;
+ }
+
+ /**
+ * A language selector is the combination of one or many language identifiers
+ * and {@link DocumentFilter language filters}.
+ *
+ * *Note* that a document selector that is just a language identifier selects *all*
+ * documents, even those that are not saved on disk. Only use such selectors when
+ * a feature works without further context, e.g. without the need to resolve related
+ * 'files'.
+ *
+ * @example
+ * let sel:DocumentSelector = { scheme: 'file', language: 'typescript' };
+ */
+ export type DocumentSelector = DocumentFilter | string | ReadonlyArray;
+
+ /**
+ * A provider result represents the values a provider, like the {@link HoverProvider `HoverProvider`},
+ * may return. For once this is the actual result type `T`, like `Hover`, or a thenable that resolves
+ * to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a
+ * thenable.
+ *
+ * The snippets below are all valid implementations of the {@link HoverProvider `HoverProvider`}:
+ *
+ * ```ts
+ * let a: HoverProvider = {
+ * provideHover(doc, pos, token): ProviderResult {
+ * return new Hover('Hello World');
+ * }
+ * }
+ *
+ * let b: HoverProvider = {
+ * provideHover(doc, pos, token): ProviderResult {
+ * return new Promise(resolve => {
+ * resolve(new Hover('Hello World'));
+ * });
+ * }
+ * }
+ *
+ * let c: HoverProvider = {
+ * provideHover(doc, pos, token): ProviderResult {
+ * return; // undefined
+ * }
+ * }
+ * ```
+ */
+ export type ProviderResult = T | undefined | null | Thenable;
+
+ /**
+ * Kind of a code action.
+ *
+ * Kinds are a hierarchical list of identifiers separated by `.`, e.g. `"refactor.extract.function"`.
+ *
+ * Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users
+ * can also trigger code actions with a specific kind with the `editor.action.codeAction` command.
+ */
+ export class CodeActionKind {
+ /**
+ * Empty kind.
+ */
+ static readonly Empty: CodeActionKind;
+
+ /**
+ * Base kind for quickfix actions: `quickfix`.
+ *
+ * Quick fix actions address a problem in the code and are shown in the normal code action context menu.
+ */
+ static readonly QuickFix: CodeActionKind;
+
+ /**
+ * Base kind for refactoring actions: `refactor`
+ *
+ * Refactoring actions are shown in the refactoring context menu.
+ */
+ static readonly Refactor: CodeActionKind;
+
+ /**
+ * Base kind for refactoring extraction actions: `refactor.extract`
+ *
+ * Example extract actions:
+ *
+ * - Extract method
+ * - Extract function
+ * - Extract variable
+ * - Extract interface from class
+ * - ...
+ */
+ static readonly RefactorExtract: CodeActionKind;
+
+ /**
+ * Base kind for refactoring inline actions: `refactor.inline`
+ *
+ * Example inline actions:
+ *
+ * - Inline function
+ * - Inline variable
+ * - Inline constant
+ * - ...
+ */
+ static readonly RefactorInline: CodeActionKind;
+
+ /**
+ * Base kind for refactoring rewrite actions: `refactor.rewrite`
+ *
+ * Example rewrite actions:
+ *
+ * - Convert JavaScript function to class
+ * - Add or remove parameter
+ * - Encapsulate field
+ * - Make method static
+ * - Move method to base class
+ * - ...
+ */
+ static readonly RefactorRewrite: CodeActionKind;
+
+ /**
+ * Base kind for source actions: `source`
+ *
+ * Source code actions apply to the entire file. They must be explicitly requested and will not show in the
+ * normal [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) menu. Source actions
+ * can be run on save using `editor.codeActionsOnSave` and are also shown in the `source` context menu.
+ */
+ static readonly Source: CodeActionKind;
+
+ /**
+ * Base kind for an organize imports source action: `source.organizeImports`.
+ */
+ static readonly SourceOrganizeImports: CodeActionKind;
+
+ /**
+ * Base kind for auto-fix source actions: `source.fixAll`.
+ *
+ * Fix all actions automatically fix errors that have a clear fix that do not require user input.
+ * They should not suppress errors or perform unsafe fixes such as generating new types or classes.
+ */
+ static readonly SourceFixAll: CodeActionKind;
+
+ private constructor(value: string);
+
+ /**
+ * String value of the kind, e.g. `"refactor.extract.function"`.
+ */
+ readonly value: string;
+
+ /**
+ * Create a new kind by appending a more specific selector to the current kind.
+ *
+ * Does not modify the current kind.
+ */
+ append(parts: string): CodeActionKind;
+
+ /**
+ * Checks if this code action kind intersects `other`.
+ *
+ * The kind `"refactor.extract"` for example intersects `refactor`, `"refactor.extract"` and ``"refactor.extract.function"`,
+ * but not `"unicorn.refactor.extract"`, or `"refactor.extractAll"`.
+ *
+ * @param other Kind to check.
+ */
+ intersects(other: CodeActionKind): boolean;
+
+ /**
+ * Checks if `other` is a sub-kind of this `CodeActionKind`.
+ *
+ * The kind `"refactor.extract"` for example contains `"refactor.extract"` and ``"refactor.extract.function"`,
+ * but not `"unicorn.refactor.extract"`, or `"refactor.extractAll"` or `refactor`.
+ *
+ * @param other Kind to check.
+ */
+ contains(other: CodeActionKind): boolean;
+ }
+
+ /**
+ * The reason why code actions were requested.
+ */
+ export enum CodeActionTriggerKind {
+ /**
+ * Code actions were explicitly requested by the user or by an extension.
+ */
+ Invoke = 1,
+
+ /**
+ * Code actions were requested automatically.
+ *
+ * This typically happens when current selection in a file changes, but can
+ * also be triggered when file content changes.
+ */
+ Automatic = 2,
+ }
+
+ /**
+ * Contains additional diagnostic information about the context in which
+ * a {@link CodeActionProvider.provideCodeActions code action} is run.
+ */
+ export interface CodeActionContext {
+ /**
+ * The reason why code actions were requested.
+ */
+ readonly triggerKind: CodeActionTriggerKind;
+
+ /**
+ * An array of diagnostics.
+ */
+ readonly diagnostics: ReadonlyArray;
+
+ /**
+ * Requested kind of actions to return.
+ *
+ * Actions not of this kind are filtered out before being shown by the [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action).
+ */
+ readonly only?: CodeActionKind;
+ }
+
+ /**
+ * A code action represents a change that can be performed in code, e.g. to fix a problem or
+ * to refactor code.
+ *
+ * A CodeAction must set either {@link CodeAction.edit `edit`} and/or a {@link CodeAction.command `command`}. If both are supplied, the `edit` is applied first, then the command is executed.
+ */
+ export class CodeAction {
+
+ /**
+ * A short, human-readable, title for this code action.
+ */
+ title: string;
+
+ /**
+ * A {@link WorkspaceEdit workspace edit} this code action performs.
+ */
+ edit?: WorkspaceEdit;
+
+ /**
+ * {@link Diagnostic Diagnostics} that this code action resolves.
+ */
+ diagnostics?: Diagnostic[];
+
+ /**
+ * A {@link Command} this code action executes.
+ *
+ * If this command throws an exception, VS Code displays the exception message to users in the editor at the
+ * current cursor position.
+ */
+ command?: Command;
+
+ /**
+ * {@link CodeActionKind Kind} of the code action.
+ *
+ * Used to filter code actions.
+ */
+ kind?: CodeActionKind;
+
+ /**
+ * Marks this as a preferred action. Preferred actions are used by the `auto fix` command and can be targeted
+ * by keybindings.
+ *
+ * A quick fix should be marked preferred if it properly addresses the underlying error.
+ * A refactoring should be marked preferred if it is the most reasonable choice of actions to take.
+ */
+ isPreferred?: boolean;
+
+ /**
+ * Marks that the code action cannot currently be applied.
+ *
+ * - Disabled code actions are not shown in automatic [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action)
+ * code action menu.
+ *
+ * - Disabled actions are shown as faded out in the code action menu when the user request a more specific type
+ * of code action, such as refactorings.
+ *
+ * - If the user has a [keybinding](https://code.visualstudio.com/docs/editor/refactoring#_keybindings-for-code-actions)
+ * that auto applies a code action and only a disabled code actions are returned, VS Code will show the user an
+ * error message with `reason` in the editor.
+ */
+ disabled?: {
+ /**
+ * Human readable description of why the code action is currently disabled.
+ *
+ * This is displayed in the code actions UI.
+ */
+ readonly reason: string;
+ };
+
+ /**
+ * Creates a new code action.
+ *
+ * A code action must have at least a {@link CodeAction.title title} and {@link CodeAction.edit edits}
+ * and/or a {@link CodeAction.command command}.
+ *
+ * @param title The title of the code action.
+ * @param kind The kind of the code action.
+ */
+ constructor(title: string, kind?: CodeActionKind);
+ }
+
+ /**
+ * The code action interface defines the contract between extensions and
+ * the [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature.
+ *
+ * A code action can be any command that is {@link commands.getCommands known} to the system.
+ */
+ export interface CodeActionProvider {
+ /**
+ * Provide commands for the given document and range.
+ *
+ * @param document The document in which the command was invoked.
+ * @param range The selector or range for which the command was invoked. This will always be a selection if
+ * there is a currently active editor.
+ * @param context Context carrying additional information.
+ * @param token A cancellation token.
+ *
+ * @return An array of code actions, such as quick fixes or refactorings. The lack of a result can be signaled
+ * by returning `undefined`, `null`, or an empty array.
+ *
+ * We also support returning `Command` for legacy reasons, however all new extensions should return
+ * `CodeAction` object instead.
+ */
+ provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | T)[]>;
+
+ /**
+ * Given a code action fill in its {@link CodeAction.edit `edit`}-property. Changes to
+ * all other properties, like title, are ignored. A code action that has an edit
+ * will not be resolved.
+ *
+ * *Note* that a code action provider that returns commands, not code actions, cannot successfully
+ * implement this function. Returning commands is deprecated and instead code actions should be
+ * returned.
+ *
+ * @param codeAction A code action.
+ * @param token A cancellation token.
+ * @return The resolved code action or a thenable that resolves to such. It is OK to return the given
+ * `item`. When no result is returned, the given `item` will be used.
+ */
+ resolveCodeAction?(codeAction: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Metadata about the type of code actions that a {@link CodeActionProvider} provides.
+ */
+ export interface CodeActionProviderMetadata {
+ /**
+ * List of {@link CodeActionKind CodeActionKinds} that a {@link CodeActionProvider} may return.
+ *
+ * This list is used to determine if a given `CodeActionProvider` should be invoked or not.
+ * To avoid unnecessary computation, every `CodeActionProvider` should list use `providedCodeActionKinds`. The
+ * list of kinds may either be generic, such as `[CodeActionKind.Refactor]`, or list out every kind provided,
+ * such as `[CodeActionKind.Refactor.Extract.append('function'), CodeActionKind.Refactor.Extract.append('constant'), ...]`.
+ */
+ readonly providedCodeActionKinds?: ReadonlyArray;
+
+ /**
+ * Static documentation for a class of code actions.
+ *
+ * Documentation from the provider is shown in the code actions menu if either:
+ *
+ * - Code actions of `kind` are requested by VS Code. In this case, VS Code will show the documentation that
+ * most closely matches the requested code action kind. For example, if a provider has documentation for
+ * both `Refactor` and `RefactorExtract`, when the user requests code actions for `RefactorExtract`,
+ * VS Code will use the documentation for `RefactorExtract` instead of the documentation for `Refactor`.
+ *
+ * - Any code actions of `kind` are returned by the provider.
+ *
+ * At most one documentation entry will be shown per provider.
+ */
+ readonly documentation?: ReadonlyArray<{
+ /**
+ * The kind of the code action being documented.
+ *
+ * If the kind is generic, such as `CodeActionKind.Refactor`, the documentation will be shown whenever any
+ * refactorings are returned. If the kind if more specific, such as `CodeActionKind.RefactorExtract`, the
+ * documentation will only be shown when extract refactoring code actions are returned.
+ */
+ readonly kind: CodeActionKind;
+
+ /**
+ * Command that displays the documentation to the user.
+ *
+ * This can display the documentation directly in VS Code or open a website using {@link env.openExternal `env.openExternal`};
+ *
+ * The title of this documentation code action is taken from {@link Command.title `Command.title`}
+ */
+ readonly command: Command;
+ }>;
+ }
+
+ /**
+ * A code lens represents a {@link 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 {@link CodeLensProvider.provideCodeLenses}
+ * @see {@link CodeLensProvider.resolveCodeLens}
+ */
+ export class CodeLens {
+
+ /**
+ * The range in which this code lens is valid. Should only span a single line.
+ */
+ range: Range;
+
+ /**
+ * The command this code lens represents.
+ */
+ command?: Command;
+
+ /**
+ * `true` when there is a command associated.
+ */
+ readonly isResolved: boolean;
+
+ /**
+ * Creates a new code lens object.
+ *
+ * @param range The range to which this code lens applies.
+ * @param command The command associated to this code lens.
+ */
+ constructor(range: Range, command?: Command);
+ }
+
+ /**
+ * A code lens provider adds {@link Command commands} to source text. The commands will be shown
+ * as dedicated horizontal lines in between the source text.
+ */
+ export interface CodeLensProvider {
+
+ /**
+ * An optional event to signal that the code lenses from this provider have changed.
+ */
+ onDidChangeCodeLenses?: Event;
+
+ /**
+ * Compute a list of {@link CodeLens 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 {@link CodeLensProvider.resolveCodeLens resolve}.
+ *
+ * @param document The document in which the command was invoked.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult;
+
+ /**
+ * This function will be called for each visible code lens, usually when scrolling and after
+ * calls to {@link CodeLensProvider.provideCodeLenses compute}-lenses.
+ *
+ * @param codeLens Code lens that must be resolved.
+ * @param token A cancellation token.
+ * @return The given, resolved code lens or thenable that resolves to such.
+ */
+ resolveCodeLens?(codeLens: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Information about where a symbol is defined.
+ *
+ * Provides additional metadata over normal {@link Location} definitions, including the range of
+ * the defining symbol
+ */
+ export type DefinitionLink = LocationLink;
+
+ /**
+ * The definition of a symbol represented as one or many {@link Location locations}.
+ * For most programming languages there is only one location at which a symbol is
+ * defined.
+ */
+ export type Definition = Location | Location[];
+
+ /**
+ * The definition provider interface defines the contract between extensions and
+ * the [go to definition](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition)
+ * and peek definition features.
+ */
+ export interface DefinitionProvider {
+
+ /**
+ * Provide the definition of the symbol at the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return A definition or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The implementation provider interface defines the contract between extensions and
+ * the go to implementation feature.
+ */
+ export interface ImplementationProvider {
+
+ /**
+ * Provide the implementations of the symbol at the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return A definition or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The type definition provider defines the contract between extensions and
+ * the go to type definition feature.
+ */
+ export interface TypeDefinitionProvider {
+
+ /**
+ * Provide the type definition of the symbol at the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return A definition or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideTypeDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The declaration of a symbol representation as one or many {@link Location locations}
+ * or {@link LocationLink location links}.
+ */
+ export type Declaration = Location | Location[] | LocationLink[];
+
+ /**
+ * The declaration provider interface defines the contract between extensions and
+ * the go to declaration feature.
+ */
+ export interface DeclarationProvider {
+
+ /**
+ * Provide the declaration of the symbol at the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return A declaration or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideDeclaration(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The MarkdownString represents human-readable text that supports formatting via the
+ * markdown syntax. Standard markdown is supported, also tables, but no embedded html.
+ *
+ * When created with `supportThemeIcons` then rendering of {@link ThemeIcon theme icons} via
+ * the `$()`-syntax is supported.
+ */
+ export class MarkdownString {
+
+ /**
+ * The markdown string.
+ */
+ value: string;
+
+ /**
+ * Indicates that this markdown string is from a trusted source. Only *trusted*
+ * markdown supports links that execute commands, e.g. `[Run it](command:myCommandId)`.
+ */
+ isTrusted?: boolean;
+
+ /**
+ * Indicates that this markdown string can contain {@link ThemeIcon ThemeIcons}, e.g. `$(zap)`.
+ */
+ readonly supportThemeIcons?: boolean;
+
+ /**
+ * Creates a new markdown string with the given value.
+ *
+ * @param value Optional, initial value.
+ * @param supportThemeIcons Optional, Specifies whether {@link ThemeIcon ThemeIcons} are supported within the {@link MarkdownString `MarkdownString`}.
+ */
+ constructor(value?: string, supportThemeIcons?: boolean);
+
+ /**
+ * Appends and escapes the given string to this markdown string.
+ * @param value Plain text.
+ */
+ appendText(value: string): MarkdownString;
+
+ /**
+ * Appends the given string 'as is' to this markdown string. When {@link MarkdownString.supportThemeIcons `supportThemeIcons`} is `true`, {@link ThemeIcon ThemeIcons} in the `value` will be iconified.
+ * @param value Markdown string.
+ */
+ appendMarkdown(value: string): MarkdownString;
+
+ /**
+ * Appends the given string as codeblock using the provided language.
+ * @param value A code snippet.
+ * @param language An optional {@link languages.getLanguages language identifier}.
+ */
+ appendCodeblock(value: string, language?: string): MarkdownString;
+ }
+
+ /**
+ * 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.
+ *
+ * @deprecated This type is deprecated, please use {@link MarkdownString `MarkdownString`} instead.
+ */
+ export type MarkedString = MarkdownString | string | { language: string; value: string };
+
+ /**
+ * A hover represents additional information for a symbol or word. Hovers are
+ * rendered in a tooltip-like widget.
+ */
+ export class Hover {
+
+ /**
+ * The contents of this hover.
+ */
+ contents: MarkedString[];
+
+ /**
+ * The range to which this hover applies. When missing, the
+ * editor will use the range at the current position or the
+ * current position itself.
+ */
+ range?: Range;
+
+ /**
+ * Creates a new hover object.
+ *
+ * @param contents The contents of the hover.
+ * @param range The range to which the hover applies.
+ */
+ constructor(contents: MarkedString | MarkedString[], range?: Range);
+ }
+
+ /**
+ * The hover provider interface defines the contract between extensions and
+ * the [hover](https://code.visualstudio.com/docs/editor/intellisense)-feature.
+ */
+ export interface HoverProvider {
+
+ /**
+ * 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.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return A hover or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * An EvaluatableExpression represents an expression in a document that can be evaluated by an active debugger or runtime.
+ * The result of this evaluation is shown in a tooltip-like widget.
+ * If only a range is specified, the expression will be extracted from the underlying document.
+ * An optional expression can be used to override the extracted expression.
+ * In this case the range is still used to highlight the range in the document.
+ */
+ export class EvaluatableExpression {
+
+ /*
+ * The range is used to extract the evaluatable expression from the underlying document and to highlight it.
+ */
+ readonly range: Range;
+
+ /*
+ * If specified the expression overrides the extracted expression.
+ */
+ readonly expression?: string;
+
+ /**
+ * Creates a new evaluatable expression object.
+ *
+ * @param range The range in the underlying document from which the evaluatable expression is extracted.
+ * @param expression If specified overrides the extracted expression.
+ */
+ constructor(range: Range, expression?: string);
+ }
+
+ /**
+ * The evaluatable expression provider interface defines the contract between extensions and
+ * the debug hover. In this contract the provider returns an evaluatable expression for a given position
+ * in a document and VS Code evaluates this expression in the active debug session and shows the result in a debug hover.
+ */
+ export interface EvaluatableExpressionProvider {
+
+ /**
+ * Provide an evaluatable expression for the given document and position.
+ * VS Code will evaluate this expression in the active debug session and will show the result in the debug hover.
+ * The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression.
+ *
+ * @param document The document for which the debug hover is about to appear.
+ * @param position The line and character position in the document where the debug hover is about to appear.
+ * @param token A cancellation token.
+ * @return An EvaluatableExpression or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideEvaluatableExpression(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Provide inline value as text.
+ */
+ export class InlineValueText {
+ /**
+ * The document range for which the inline value applies.
+ */
+ readonly range: Range;
+ /**
+ * The text of the inline value.
+ */
+ readonly text: string;
+ /**
+ * Creates a new InlineValueText object.
+ *
+ * @param range The document line where to show the inline value.
+ * @param text The value to be shown for the line.
+ */
+ constructor(range: Range, text: string);
+ }
+
+ /**
+ * Provide inline value through a variable lookup.
+ * If only a range is specified, the variable name will be extracted from the underlying document.
+ * An optional variable name can be used to override the extracted name.
+ */
+ export class InlineValueVariableLookup {
+ /**
+ * The document range for which the inline value applies.
+ * The range is used to extract the variable name from the underlying document.
+ */
+ readonly range: Range;
+ /**
+ * If specified the name of the variable to look up.
+ */
+ readonly variableName?: string;
+ /**
+ * How to perform the lookup.
+ */
+ readonly caseSensitiveLookup: boolean;
+ /**
+ * Creates a new InlineValueVariableLookup object.
+ *
+ * @param range The document line where to show the inline value.
+ * @param variableName The name of the variable to look up.
+ * @param caseSensitiveLookup How to perform the lookup. If missing lookup is case sensitive.
+ */
+ constructor(range: Range, variableName?: string, caseSensitiveLookup?: boolean);
+ }
+
+ /**
+ * Provide an inline value through an expression evaluation.
+ * If only a range is specified, the expression will be extracted from the underlying document.
+ * An optional expression can be used to override the extracted expression.
+ */
+ export class InlineValueEvaluatableExpression {
+ /**
+ * The document range for which the inline value applies.
+ * The range is used to extract the evaluatable expression from the underlying document.
+ */
+ readonly range: Range;
+ /**
+ * If specified the expression overrides the extracted expression.
+ */
+ readonly expression?: string;
+ /**
+ * Creates a new InlineValueEvaluatableExpression object.
+ *
+ * @param range The range in the underlying document from which the evaluatable expression is extracted.
+ * @param expression If specified overrides the extracted expression.
+ */
+ constructor(range: Range, expression?: string);
+ }
+
+ /**
+ * Inline value information can be provided by different means:
+ * - directly as a text value (class InlineValueText).
+ * - as a name to use for a variable lookup (class InlineValueVariableLookup)
+ * - as an evaluatable expression (class InlineValueEvaluatableExpression)
+ * The InlineValue types combines all inline value types into one type.
+ */
+ export type InlineValue = InlineValueText | InlineValueVariableLookup | InlineValueEvaluatableExpression;
+
+ /**
+ * A value-object that contains contextual information when requesting inline values from a InlineValuesProvider.
+ */
+ export interface InlineValueContext {
+
+ /**
+ * The stack frame (as a DAP Id) where the execution has stopped.
+ */
+ readonly frameId: number;
+
+ /**
+ * The document range where execution has stopped.
+ * Typically the end position of the range denotes the line where the inline values are shown.
+ */
+ readonly stoppedLocation: Range;
+ }
+
+ /**
+ * The inline values provider interface defines the contract between extensions and the VS Code debugger inline values feature.
+ * In this contract the provider returns inline value information for a given document range
+ * and VS Code shows this information in the editor at the end of lines.
+ */
+ export interface InlineValuesProvider {
+
+ /**
+ * An optional event to signal that inline values have changed.
+ * @see {@link EventEmitter}
+ */
+ onDidChangeInlineValues?: Event | undefined;
+
+ /**
+ * Provide "inline value" information for a given document and range.
+ * VS Code calls this method whenever debugging stops in the given document.
+ * The returned inline values information is rendered in the editor at the end of lines.
+ *
+ * @param document The document for which the inline values information is needed.
+ * @param viewPort The visible document range for which inline values should be computed.
+ * @param context A bag containing contextual information like the current location.
+ * @param token A cancellation token.
+ * @return An array of InlineValueDescriptors or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideInlineValues(document: TextDocument, viewPort: Range, context: InlineValueContext, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A document highlight kind.
+ */
+ export enum DocumentHighlightKind {
+
+ /**
+ * A textual occurrence.
+ */
+ Text = 0,
+
+ /**
+ * Read-access of a symbol, like reading a variable.
+ */
+ Read = 1,
+
+ /**
+ * Write-access of a symbol, like writing to a variable.
+ */
+ Write = 2
+ }
+
+ /**
+ * 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.
+ */
+ export class DocumentHighlight {
+
+ /**
+ * The range this highlight applies to.
+ */
+ range: Range;
+
+ /**
+ * The highlight kind, default is {@link DocumentHighlightKind.Text text}.
+ */
+ kind?: DocumentHighlightKind;
+
+ /**
+ * Creates a new document highlight object.
+ *
+ * @param range The range the highlight applies to.
+ * @param kind The highlight kind, default is {@link DocumentHighlightKind.Text text}.
+ */
+ constructor(range: Range, kind?: DocumentHighlightKind);
+ }
+
+ /**
+ * The document highlight provider interface defines the contract between extensions and
+ * the word-highlight-feature.
+ */
+ export interface DocumentHighlightProvider {
+
+ /**
+ * Provide a set of document highlights, like all occurrences of a variable or
+ * all exit-points of a function.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A symbol kind.
+ */
+ export enum SymbolKind {
+ File = 0,
+ Module = 1,
+ Namespace = 2,
+ Package = 3,
+ Class = 4,
+ Method = 5,
+ Property = 6,
+ Field = 7,
+ Constructor = 8,
+ Enum = 9,
+ Interface = 10,
+ Function = 11,
+ Variable = 12,
+ Constant = 13,
+ String = 14,
+ Number = 15,
+ Boolean = 16,
+ Array = 17,
+ Object = 18,
+ Key = 19,
+ Null = 20,
+ EnumMember = 21,
+ Struct = 22,
+ Event = 23,
+ Operator = 24,
+ TypeParameter = 25
+ }
+
+ /**
+ * Symbol tags are extra annotations that tweak the rendering of a symbol.
+ */
+ export enum SymbolTag {
+
+ /**
+ * Render a symbol as obsolete, usually using a strike-out.
+ */
+ Deprecated = 1
+ }
+
+ /**
+ * Represents information about programming constructs like variables, classes,
+ * interfaces etc.
+ */
+ export class SymbolInformation {
+
+ /**
+ * The name of this symbol.
+ */
+ name: string;
+
+ /**
+ * The name of the symbol containing this symbol.
+ */
+ containerName: string;
+
+ /**
+ * The kind of this symbol.
+ */
+ kind: SymbolKind;
+
+ /**
+ * Tags for this symbol.
+ */
+ tags?: ReadonlyArray;
+
+ /**
+ * The location of this symbol.
+ */
+ location: Location;
+
+ /**
+ * Creates a new symbol information object.
+ *
+ * @param name The name of the symbol.
+ * @param kind The kind of the symbol.
+ * @param containerName The name of the symbol containing the symbol.
+ * @param location The location of the symbol.
+ */
+ constructor(name: string, kind: SymbolKind, containerName: string, location: Location);
+
+ /**
+ * Creates a new symbol information object.
+ *
+ * @deprecated Please use the constructor taking a {@link Location} object.
+ *
+ * @param name The name of the symbol.
+ * @param kind The kind of the symbol.
+ * @param range The range of the location of the symbol.
+ * @param uri The resource of the location of symbol, defaults to the current document.
+ * @param containerName The name of the symbol containing the symbol.
+ */
+ constructor(name: string, kind: SymbolKind, range: Range, uri?: Uri, containerName?: string);
+ }
+
+ /**
+ * Represents programming constructs like variables, classes, interfaces etc. that appear in a document. Document
+ * symbols can be hierarchical and they have two ranges: one that encloses its definition and one that points to
+ * its most interesting range, e.g. the range of an identifier.
+ */
+ export class DocumentSymbol {
+
+ /**
+ * The name of this symbol.
+ */
+ name: string;
+
+ /**
+ * More detail for this symbol, e.g. the signature of a function.
+ */
+ detail: string;
+
+ /**
+ * The kind of this symbol.
+ */
+ kind: SymbolKind;
+
+ /**
+ * Tags for this symbol.
+ */
+ tags?: ReadonlyArray;
+
+ /**
+ * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.
+ */
+ range: Range;
+
+ /**
+ * The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function.
+ * Must be contained by the {@link DocumentSymbol.range `range`}.
+ */
+ selectionRange: Range;
+
+ /**
+ * Children of this symbol, e.g. properties of a class.
+ */
+ children: DocumentSymbol[];
+
+ /**
+ * Creates a new document symbol.
+ *
+ * @param name The name of the symbol.
+ * @param detail Details for the symbol.
+ * @param kind The kind of the symbol.
+ * @param range The full range of the symbol.
+ * @param selectionRange The range that should be reveal.
+ */
+ constructor(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range);
+ }
+
+ /**
+ * The document symbol provider interface defines the contract between extensions and
+ * the [go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)-feature.
+ */
+ export interface DocumentSymbolProvider {
+
+ /**
+ * Provide symbol information for the given document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Metadata about a document symbol provider.
+ */
+ export interface DocumentSymbolProviderMetadata {
+ /**
+ * A human-readable string that is shown when multiple outlines trees show for one document.
+ */
+ label?: string;
+ }
+
+ /**
+ * The workspace symbol provider interface defines the contract between extensions and
+ * the [symbol search](https://code.visualstudio.com/docs/editor/editingevolved#_open-symbol-by-name)-feature.
+ */
+ export interface WorkspaceSymbolProvider {
+
+ /**
+ * Project-wide search for a symbol matching the given query string.
+ *
+ * The `query`-parameter should be interpreted in a *relaxed way* as the editor will apply its own highlighting
+ * and scoring on the results. A good rule of thumb is to match case-insensitive and to simply check that the
+ * characters of *query* appear in their order in a candidate symbol. Don't use prefix, substring, or similar
+ * strict matching.
+ *
+ * To improve performance implementors can implement `resolveWorkspaceSymbol` and then provide symbols with partial
+ * {@link SymbolInformation.location location}-objects, without a `range` defined. The editor will then call
+ * `resolveWorkspaceSymbol` for selected symbols only, e.g. when opening a workspace symbol.
+ *
+ * @param query A query string, can be the empty string in which case all symbols should be returned.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult;
+
+ /**
+ * Given a symbol fill in its {@link SymbolInformation.location location}. This method is called whenever a symbol
+ * is selected in the UI. Providers can implement this method and return incomplete symbols from
+ * {@link WorkspaceSymbolProvider.provideWorkspaceSymbols `provideWorkspaceSymbols`} which often helps to improve
+ * performance.
+ *
+ * @param symbol The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an
+ * earlier call to `provideWorkspaceSymbols`.
+ * @param token A cancellation token.
+ * @return The resolved symbol or a thenable that resolves to that. When no result is returned,
+ * the given `symbol` is used.
+ */
+ resolveWorkspaceSymbol?(symbol: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Value-object that contains additional information when
+ * requesting references.
+ */
+ export interface ReferenceContext {
+
+ /**
+ * Include the declaration of the current symbol.
+ */
+ includeDeclaration: boolean;
+ }
+
+ /**
+ * The reference provider interface defines the contract between extensions and
+ * the [find references](https://code.visualstudio.com/docs/editor/editingevolved#_peek)-feature.
+ */
+ export interface ReferenceProvider {
+
+ /**
+ * Provide a set of project-wide references for the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ *
+ * @return 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.
+ */
+ provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A text edit represents edits that should be applied
+ * to a document.
+ */
+ export class TextEdit {
+
+ /**
+ * Utility to create a replace edit.
+ *
+ * @param range A range.
+ * @param newText A string.
+ * @return A new text edit object.
+ */
+ static replace(range: Range, newText: string): TextEdit;
+
+ /**
+ * Utility to create an insert edit.
+ *
+ * @param position A position, will become an empty range.
+ * @param newText A string.
+ * @return A new text edit object.
+ */
+ static insert(position: Position, newText: string): TextEdit;
+
+ /**
+ * Utility to create a delete edit.
+ *
+ * @param range A range.
+ * @return A new text edit object.
+ */
+ static delete(range: Range): TextEdit;
+
+ /**
+ * Utility to create an eol-edit.
+ *
+ * @param eol An eol-sequence
+ * @return A new text edit object.
+ */
+ static setEndOfLine(eol: EndOfLine): TextEdit;
+
+ /**
+ * The range this edit applies to.
+ */
+ range: Range;
+
+ /**
+ * The string this edit will insert.
+ */
+ newText: string;
+
+ /**
+ * The eol-sequence used in the document.
+ *
+ * *Note* that the eol-sequence will be applied to the
+ * whole document.
+ */
+ newEol?: EndOfLine;
+
+ /**
+ * Create a new TextEdit.
+ *
+ * @param range A range.
+ * @param newText A string.
+ */
+ constructor(range: Range, newText: string);
+ }
+
+ /**
+ * Additional data for entries of a workspace edit. Supports to label entries and marks entries
+ * as needing confirmation by the user. The editor groups edits with equal labels into tree nodes,
+ * for instance all edits labelled with "Changes in Strings" would be a tree node.
+ */
+ export interface WorkspaceEditEntryMetadata {
+
+ /**
+ * A flag which indicates that user confirmation is needed.
+ */
+ needsConfirmation: boolean;
+
+ /**
+ * A human-readable string which is rendered prominent.
+ */
+ label: string;
+
+ /**
+ * A human-readable string which is rendered less prominent on the same line.
+ */
+ description?: string;
+
+ /**
+ * The icon path or {@link ThemeIcon} for the edit.
+ */
+ iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
+ }
+
+ /**
+ * A workspace edit is a collection of textual and files changes for
+ * multiple resources and documents.
+ *
+ * Use the {@link workspace.applyEdit applyEdit}-function to apply a workspace edit.
+ */
+ export class WorkspaceEdit {
+
+ /**
+ * The number of affected resources of textual or resource changes.
+ */
+ readonly size: number;
+
+ /**
+ * Replace the given range with given text for the given resource.
+ *
+ * @param uri A resource identifier.
+ * @param range A range.
+ * @param newText A string.
+ * @param metadata Optional metadata for the entry.
+ */
+ replace(uri: Uri, range: Range, newText: string, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Insert the given text at the given position.
+ *
+ * @param uri A resource identifier.
+ * @param position A position.
+ * @param newText A string.
+ * @param metadata Optional metadata for the entry.
+ */
+ insert(uri: Uri, position: Position, newText: string, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Delete the text at the given range.
+ *
+ * @param uri A resource identifier.
+ * @param range A range.
+ * @param metadata Optional metadata for the entry.
+ */
+ delete(uri: Uri, range: Range, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Check if a text edit for a resource exists.
+ *
+ * @param uri A resource identifier.
+ * @return `true` if the given resource will be touched by this edit.
+ */
+ has(uri: Uri): boolean;
+
+ /**
+ * Set (and replace) text edits for a resource.
+ *
+ * @param uri A resource identifier.
+ * @param edits An array of text edits.
+ */
+ set(uri: Uri, edits: TextEdit[]): void;
+
+ /**
+ * Get the text edits for a resource.
+ *
+ * @param uri A resource identifier.
+ * @return An array of text edits.
+ */
+ get(uri: Uri): TextEdit[];
+
+ /**
+ * Create a regular file.
+ *
+ * @param uri Uri of the new file..
+ * @param options Defines if an existing file should be overwritten or be
+ * ignored. When overwrite and ignoreIfExists are both set overwrite wins.
+ * When both are unset and when the file already exists then the edit cannot
+ * be applied successfully.
+ * @param metadata Optional metadata for the entry.
+ */
+ createFile(uri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Delete a file or folder.
+ *
+ * @param uri The uri of the file that is to be deleted.
+ * @param metadata Optional metadata for the entry.
+ */
+ deleteFile(uri: Uri, options?: { recursive?: boolean, ignoreIfNotExists?: boolean }, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Rename a file or folder.
+ *
+ * @param oldUri The existing file.
+ * @param newUri The new location.
+ * @param options Defines if existing files should be overwritten or be
+ * ignored. When overwrite and ignoreIfExists are both set overwrite wins.
+ * @param metadata Optional metadata for the entry.
+ */
+ renameFile(oldUri: Uri, newUri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }, metadata?: WorkspaceEditEntryMetadata): void;
+
+ /**
+ * Get all text edits grouped by resource.
+ *
+ * @return A shallow copy of `[Uri, TextEdit[]]`-tuples.
+ */
+ entries(): [Uri, TextEdit[]][];
+ }
+
+ /**
+ * A snippet string is a template which allows to insert text
+ * and to control the editor cursor when insertion happens.
+ *
+ * A snippet can define tab stops and placeholders with `$1`, `$2`
+ * and `${3:foo}`. `$0` defines the final tab stop, it defaults to
+ * the end of the snippet. Variables are defined with `$name` and
+ * `${name:default value}`. The full snippet syntax is documented
+ * [here](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_creating-your-own-snippets).
+ */
+ export class SnippetString {
+
+ /**
+ * The snippet string.
+ */
+ value: string;
+
+ constructor(value?: string);
+
+ /**
+ * Builder-function that appends the given string to
+ * the {@link SnippetString.value `value`} of this snippet string.
+ *
+ * @param string A value to append 'as given'. The string will be escaped.
+ * @return This snippet string.
+ */
+ appendText(string: string): SnippetString;
+
+ /**
+ * Builder-function that appends a tabstop (`$1`, `$2` etc) to
+ * the {@link SnippetString.value `value`} of this snippet string.
+ *
+ * @param number The number of this tabstop, defaults to an auto-increment
+ * value starting at 1.
+ * @return This snippet string.
+ */
+ appendTabstop(number?: number): SnippetString;
+
+ /**
+ * Builder-function that appends a placeholder (`${1:value}`) to
+ * the {@link SnippetString.value `value`} of this snippet string.
+ *
+ * @param value The value of this placeholder - either a string or a function
+ * with which a nested snippet can be created.
+ * @param number The number of this tabstop, defaults to an auto-increment
+ * value starting at 1.
+ * @return This snippet string.
+ */
+ appendPlaceholder(value: string | ((snippet: SnippetString) => any), number?: number): SnippetString;
+
+ /**
+ * Builder-function that appends a choice (`${1|a,b,c|}`) to
+ * the {@link SnippetString.value `value`} of this snippet string.
+ *
+ * @param values The values for choices - the array of strings
+ * @param number The number of this tabstop, defaults to an auto-increment
+ * value starting at 1.
+ * @return This snippet string.
+ */
+ appendChoice(values: string[], number?: number): SnippetString;
+
+ /**
+ * Builder-function that appends a variable (`${VAR}`) to
+ * the {@link SnippetString.value `value`} of this snippet string.
+ *
+ * @param name The name of the variable - excluding the `$`.
+ * @param defaultValue The default value which is used when the variable name cannot
+ * be resolved - either a string or a function with which a nested snippet can be created.
+ * @return This snippet string.
+ */
+ appendVariable(name: string, defaultValue: string | ((snippet: SnippetString) => any)): SnippetString;
+ }
+
+ /**
+ * The rename provider interface defines the contract between extensions and
+ * the [rename](https://code.visualstudio.com/docs/editor/editingevolved#_rename-symbol)-feature.
+ */
+ export interface RenameProvider {
+
+ /**
+ * Provide an edit that describes changes that have to be made to one
+ * or many resources to rename a symbol to a different name.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param newName The new name of the symbol. If the given name is not valid, the provider must return a rejected promise.
+ * @param token A cancellation token.
+ * @return A workspace edit or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): ProviderResult;
+
+ /**
+ * Optional function for resolving and validating a position *before* running rename. The result can
+ * be a range or a range and a placeholder text. The placeholder text should be the identifier of the symbol
+ * which is being renamed - when omitted the text in the returned range is used.
+ *
+ * *Note: * This function should throw an error or return a rejected thenable when the provided location
+ * doesn't allow for a rename.
+ *
+ * @param document The document in which rename will be invoked.
+ * @param position The position at which rename will be invoked.
+ * @param token A cancellation token.
+ * @return The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning `undefined` or `null`.
+ */
+ prepareRename?(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A semantic tokens legend contains the needed information to decipher
+ * the integer encoded representation of semantic tokens.
+ */
+ export class SemanticTokensLegend {
+ /**
+ * The possible token types.
+ */
+ readonly tokenTypes: string[];
+ /**
+ * The possible token modifiers.
+ */
+ readonly tokenModifiers: string[];
+
+ constructor(tokenTypes: string[], tokenModifiers?: string[]);
+ }
+
+ /**
+ * A semantic tokens builder can help with creating a `SemanticTokens` instance
+ * which contains delta encoded semantic tokens.
+ */
+ export class SemanticTokensBuilder {
+
+ constructor(legend?: SemanticTokensLegend);
+
+ /**
+ * Add another token.
+ *
+ * @param line The token start line number (absolute value).
+ * @param char The token start character (absolute value).
+ * @param length The token length in characters.
+ * @param tokenType The encoded token type.
+ * @param tokenModifiers The encoded token modifiers.
+ */
+ push(line: number, char: number, length: number, tokenType: number, tokenModifiers?: number): void;
+
+ /**
+ * Add another token. Use only when providing a legend.
+ *
+ * @param range The range of the token. Must be single-line.
+ * @param tokenType The token type.
+ * @param tokenModifiers The token modifiers.
+ */
+ push(range: Range, tokenType: string, tokenModifiers?: string[]): void;
+
+ /**
+ * Finish and create a `SemanticTokens` instance.
+ */
+ build(resultId?: string): SemanticTokens;
+ }
+
+ /**
+ * Represents semantic tokens, either in a range or in an entire document.
+ * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens} for an explanation of the format.
+ * @see {@link SemanticTokensBuilder} for a helper to create an instance.
+ */
+ export class SemanticTokens {
+ /**
+ * The result id of the tokens.
+ *
+ * This is the id that will be passed to `DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits` (if implemented).
+ */
+ readonly resultId?: string;
+ /**
+ * The actual tokens data.
+ * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens} for an explanation of the format.
+ */
+ readonly data: Uint32Array;
+
+ constructor(data: Uint32Array, resultId?: string);
+ }
+
+ /**
+ * Represents edits to semantic tokens.
+ * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits provideDocumentSemanticTokensEdits} for an explanation of the format.
+ */
+ export class SemanticTokensEdits {
+ /**
+ * The result id of the tokens.
+ *
+ * This is the id that will be passed to `DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits` (if implemented).
+ */
+ readonly resultId?: string;
+ /**
+ * The edits to the tokens data.
+ * All edits refer to the initial data state.
+ */
+ readonly edits: SemanticTokensEdit[];
+
+ constructor(edits: SemanticTokensEdit[], resultId?: string);
+ }
+
+ /**
+ * Represents an edit to semantic tokens.
+ * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits provideDocumentSemanticTokensEdits} for an explanation of the format.
+ */
+ export class SemanticTokensEdit {
+ /**
+ * The start offset of the edit.
+ */
+ readonly start: number;
+ /**
+ * The count of elements to remove.
+ */
+ readonly deleteCount: number;
+ /**
+ * The elements to insert.
+ */
+ readonly data?: Uint32Array;
+
+ constructor(start: number, deleteCount: number, data?: Uint32Array);
+ }
+
+ /**
+ * The document semantic tokens provider interface defines the contract between extensions and
+ * semantic tokens.
+ */
+ export interface DocumentSemanticTokensProvider {
+ /**
+ * An optional event to signal that the semantic tokens from this provider have changed.
+ */
+ onDidChangeSemanticTokens?: Event;
+
+ /**
+ * Tokens in a file are represented as an array of integers. The position of each token is expressed relative to
+ * the token before it, because most tokens remain stable relative to each other when edits are made in a file.
+ *
+ * ---
+ * In short, each token takes 5 integers to represent, so a specific token `i` in the file consists of the following array indices:
+ * - at index `5*i` - `deltaLine`: token line number, relative to the previous token
+ * - at index `5*i+1` - `deltaStart`: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line)
+ * - at index `5*i+2` - `length`: the length of the token. A token cannot be multiline.
+ * - at index `5*i+3` - `tokenType`: will be looked up in `SemanticTokensLegend.tokenTypes`. We currently ask that `tokenType` < 65536.
+ * - at index `5*i+4` - `tokenModifiers`: each set bit will be looked up in `SemanticTokensLegend.tokenModifiers`
+ *
+ * ---
+ * ### How to encode tokens
+ *
+ * Here is an example for encoding a file with 3 tokens in a uint32 array:
+ * ```
+ * { line: 2, startChar: 5, length: 3, tokenType: "property", tokenModifiers: ["private", "static"] },
+ * { line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] },
+ * { line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] }
+ * ```
+ *
+ * 1. First of all, a legend must be devised. This legend must be provided up-front and capture all possible token types.
+ * For this example, we will choose the following legend which must be passed in when registering the provider:
+ * ```
+ * tokenTypes: ['property', 'type', 'class'],
+ * tokenModifiers: ['private', 'static']
+ * ```
+ *
+ * 2. The first transformation step is to encode `tokenType` and `tokenModifiers` as integers using the legend. Token types are looked
+ * up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Multiple token modifiers can be set by using bit flags,
+ * so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because
+ * bits 0 and 1 are set. Using this legend, the tokens now are:
+ * ```
+ * { line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
+ * { line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 },
+ * { line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
+ * ```
+ *
+ * 3. The next step is to represent each token relative to the previous token in the file. In this case, the second token
+ * is on the same line as the first token, so the `startChar` of the second token is made relative to the `startChar`
+ * of the first token, so it will be `10 - 5`. The third token is on a different line than the second token, so the
+ * `startChar` of the third token will not be altered:
+ * ```
+ * { deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 },
+ * { deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 },
+ * { deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 }
+ * ```
+ *
+ * 4. Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation:
+ * ```
+ * // 1st token, 2nd token, 3rd token
+ * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
+ * ```
+ *
+ * @see {@link SemanticTokensBuilder} for a helper to encode tokens as integers.
+ * *NOTE*: When doing edits, it is possible that multiple edits occur until VS Code decides to invoke the semantic tokens provider.
+ * *NOTE*: If the provider cannot temporarily compute semantic tokens, it can indicate this by throwing an error with the message 'Busy'.
+ */
+ provideDocumentSemanticTokens(document: TextDocument, token: CancellationToken): ProviderResult;
+
+ /**
+ * Instead of always returning all the tokens in a file, it is possible for a `DocumentSemanticTokensProvider` to implement
+ * this method (`provideDocumentSemanticTokensEdits`) and then return incremental updates to the previously provided semantic tokens.
+ *
+ * ---
+ * ### How tokens change when the document changes
+ *
+ * Suppose that `provideDocumentSemanticTokens` has previously returned the following semantic tokens:
+ * ```
+ * // 1st token, 2nd token, 3rd token
+ * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
+ * ```
+ *
+ * Also suppose that after some edits, the new semantic tokens in a file are:
+ * ```
+ * // 1st token, 2nd token, 3rd token
+ * [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
+ * ```
+ * It is possible to express these new tokens in terms of an edit applied to the previous tokens:
+ * ```
+ * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // old tokens
+ * [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] // new tokens
+ *
+ * edit: { start: 0, deleteCount: 1, data: [3] } // replace integer at offset 0 with 3
+ * ```
+ *
+ * *NOTE*: If the provider cannot compute `SemanticTokensEdits`, it can "give up" and return all the tokens in the document again.
+ * *NOTE*: All edits in `SemanticTokensEdits` contain indices in the old integers array, so they all refer to the previous result state.
+ */
+ provideDocumentSemanticTokensEdits?(document: TextDocument, previousResultId: string, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The document range semantic tokens provider interface defines the contract between extensions and
+ * semantic tokens.
+ */
+ export interface DocumentRangeSemanticTokensProvider {
+ /**
+ * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens}.
+ */
+ provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Value-object describing what options formatting should use.
+ */
+ export interface FormattingOptions {
+
+ /**
+ * Size of a tab in spaces.
+ */
+ tabSize: number;
+
+ /**
+ * Prefer spaces over tabs.
+ */
+ insertSpaces: boolean;
+
+ /**
+ * Signature for further properties.
+ */
+ [key: string]: boolean | number | string;
+ }
+
+ /**
+ * The document formatting provider interface defines the contract between extensions and
+ * the formatting-feature.
+ */
+ export interface DocumentFormattingEditProvider {
+
+ /**
+ * Provide formatting edits for a whole document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param options Options controlling formatting.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The document formatting provider interface defines the contract between extensions and
+ * the formatting-feature.
+ */
+ export interface DocumentRangeFormattingEditProvider {
+
+ /**
+ * 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.
+ *
+ * @param document The document in which the command was invoked.
+ * @param range The range which should be formatted.
+ * @param options Options controlling formatting.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * The document formatting provider interface defines the contract between extensions and
+ * the formatting-feature.
+ */
+ export interface OnTypeFormattingEditProvider {
+
+ /**
+ * 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.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param ch The character that has been typed.
+ * @param options Options controlling formatting.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Represents a parameter of a callable-signature. A parameter can
+ * have a label and a doc-comment.
+ */
+ export class ParameterInformation {
+
+ /**
+ * The label of this signature.
+ *
+ * Either a string or inclusive start and exclusive end offsets within its containing
+ * {@link SignatureInformation.label signature label}. *Note*: A label of type string must be
+ * a substring of its containing signature information's {@link SignatureInformation.label label}.
+ */
+ label: string | [number, number];
+
+ /**
+ * The human-readable doc-comment of this signature. Will be shown
+ * in the UI but can be omitted.
+ */
+ documentation?: string | MarkdownString;
+
+ /**
+ * Creates a new parameter information object.
+ *
+ * @param label A label string or inclusive start and exclusive end offsets within its containing signature label.
+ * @param documentation A doc string.
+ */
+ constructor(label: string | [number, number], documentation?: string | MarkdownString);
+ }
+
+ /**
+ * Represents the signature of something callable. A signature
+ * can have a label, like a function-name, a doc-comment, and
+ * a set of parameters.
+ */
+ export class SignatureInformation {
+
+ /**
+ * The label of this signature. Will be shown in
+ * the UI.
+ */
+ label: string;
+
+ /**
+ * The human-readable doc-comment of this signature. Will be shown
+ * in the UI but can be omitted.
+ */
+ documentation?: string | MarkdownString;
+
+ /**
+ * The parameters of this signature.
+ */
+ parameters: ParameterInformation[];
+
+ /**
+ * The index of the active parameter.
+ *
+ * If provided, this is used in place of {@link SignatureHelp.activeSignature `SignatureHelp.activeSignature`}.
+ */
+ activeParameter?: number;
+
+ /**
+ * Creates a new signature information object.
+ *
+ * @param label A label string.
+ * @param documentation A doc string.
+ */
+ constructor(label: string, documentation?: string | MarkdownString);
+ }
+
+ /**
+ * Signature help represents the signature of something
+ * callable. There can be multiple signatures but only one
+ * active and only one active parameter.
+ */
+ export class SignatureHelp {
+
+ /**
+ * One or more signatures.
+ */
+ signatures: SignatureInformation[];
+
+ /**
+ * The active signature.
+ */
+ activeSignature: number;
+
+ /**
+ * The active parameter of the active signature.
+ */
+ activeParameter: number;
+ }
+
+ /**
+ * How a {@link SignatureHelpProvider `SignatureHelpProvider`} was triggered.
+ */
+ export enum SignatureHelpTriggerKind {
+ /**
+ * Signature help was invoked manually by the user or by a command.
+ */
+ Invoke = 1,
+
+ /**
+ * Signature help was triggered by a trigger character.
+ */
+ TriggerCharacter = 2,
+
+ /**
+ * Signature help was triggered by the cursor moving or by the document content changing.
+ */
+ ContentChange = 3,
+ }
+
+ /**
+ * Additional information about the context in which a
+ * {@link SignatureHelpProvider.provideSignatureHelp `SignatureHelpProvider`} was triggered.
+ */
+ export interface SignatureHelpContext {
+ /**
+ * Action that caused signature help to be triggered.
+ */
+ readonly triggerKind: SignatureHelpTriggerKind;
+
+ /**
+ * Character that caused signature help to be triggered.
+ *
+ * This is `undefined` when signature help is not triggered by typing, such as when manually invoking
+ * signature help or when moving the cursor.
+ */
+ readonly triggerCharacter?: string;
+
+ /**
+ * `true` if signature help was already showing when it was triggered.
+ *
+ * Retriggers occur when the signature help is already active and can be caused by actions such as
+ * typing a trigger character, a cursor move, or document content changes.
+ */
+ readonly isRetrigger: boolean;
+
+ /**
+ * The currently active {@link SignatureHelp `SignatureHelp`}.
+ *
+ * The `activeSignatureHelp` has its [`SignatureHelp.activeSignature`] field updated based on
+ * the user arrowing through available signatures.
+ */
+ readonly activeSignatureHelp?: SignatureHelp;
+ }
+
+ /**
+ * The signature help provider interface defines the contract between extensions and
+ * the [parameter hints](https://code.visualstudio.com/docs/editor/intellisense)-feature.
+ */
+ export interface SignatureHelpProvider {
+
+ /**
+ * Provide help for the signature at the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @param context Information about how signature help was triggered.
+ *
+ * @return Signature help or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken, context: SignatureHelpContext): ProviderResult;
+ }
+
+ /**
+ * Metadata about a registered {@link SignatureHelpProvider `SignatureHelpProvider`}.
+ */
+ export interface SignatureHelpProviderMetadata {
+ /**
+ * List of characters that trigger signature help.
+ */
+ readonly triggerCharacters: ReadonlyArray;
+
+ /**
+ * List of characters that re-trigger signature help.
+ *
+ * These trigger characters are only active when signature help is already showing. All trigger characters
+ * are also counted as re-trigger characters.
+ */
+ readonly retriggerCharacters: ReadonlyArray;
+ }
+
+ /**
+ * Completion item kinds.
+ */
+ export enum CompletionItemKind {
+ Text = 0,
+ Method = 1,
+ Function = 2,
+ Constructor = 3,
+ Field = 4,
+ Variable = 5,
+ Class = 6,
+ Interface = 7,
+ Module = 8,
+ Property = 9,
+ Unit = 10,
+ Value = 11,
+ Enum = 12,
+ Keyword = 13,
+ Snippet = 14,
+ Color = 15,
+ Reference = 17,
+ File = 16,
+ Folder = 18,
+ EnumMember = 19,
+ Constant = 20,
+ Struct = 21,
+ Event = 22,
+ Operator = 23,
+ TypeParameter = 24,
+ User = 25,
+ Issue = 26,
+ }
+
+ /**
+ * Completion item tags are extra annotations that tweak the rendering of a completion
+ * item.
+ */
+ export enum CompletionItemTag {
+ /**
+ * Render a completion as obsolete, usually using a strike-out.
+ */
+ Deprecated = 1
+ }
+
+ /**
+ * A completion item represents a text snippet that is proposed to complete text that is being typed.
+ *
+ * It is sufficient to create a completion item from just a {@link CompletionItem.label label}. In that
+ * case the completion item will replace the {@link TextDocument.getWordRangeAtPosition word}
+ * until the cursor with the given label or {@link CompletionItem.insertText insertText}. Otherwise the
+ * given {@link CompletionItem.textEdit edit} is used.
+ *
+ * When selecting a completion item in the editor its defined or synthesized text edit will be applied
+ * to *all* cursors/selections whereas {@link CompletionItem.additionalTextEdits additionalTextEdits} will be
+ * applied as provided.
+ *
+ * @see {@link CompletionItemProvider.provideCompletionItems}
+ * @see {@link CompletionItemProvider.resolveCompletionItem}
+ */
+ export class CompletionItem {
+
+ /**
+ * The label of this completion item. By default
+ * this is also the text that is inserted when selecting
+ * this completion.
+ */
+ label: string;
+
+ /**
+ * The kind of this completion item. Based on the kind
+ * an icon is chosen by the editor.
+ */
+ kind?: CompletionItemKind;
+
+ /**
+ * Tags for this completion item.
+ */
+ tags?: ReadonlyArray;
+
+ /**
+ * A human-readable string with additional information
+ * about this item, like type or symbol information.
+ */
+ detail?: string;
+
+ /**
+ * A human-readable string that represents a doc-comment.
+ */
+ documentation?: string | MarkdownString;
+
+ /**
+ * A string that should be used when comparing this item
+ * with other items. When `falsy` the {@link CompletionItem.label label}
+ * is used.
+ *
+ * Note that `sortText` is only used for the initial ordering of completion
+ * items. When having a leading word (prefix) ordering is based on how
+ * well completions match that prefix and the initial ordering is only used
+ * when completions match equally well. The prefix is defined by the
+ * {@link CompletionItem.range `range`}-property and can therefore be different
+ * for each completion.
+ */
+ sortText?: string;
+
+ /**
+ * A string that should be used when filtering a set of
+ * completion items. When `falsy` the {@link CompletionItem.label label}
+ * is used.
+ *
+ * Note that the filter text is matched against the leading word (prefix) which is defined
+ * by the {@link CompletionItem.range `range`}-property.
+ */
+ filterText?: string;
+
+ /**
+ * Select this item when showing. *Note* that only one completion item can be selected and
+ * that the editor decides which item that is. The rule is that the *first* item of those
+ * that match best is selected.
+ */
+ preselect?: boolean;
+
+ /**
+ * A string or snippet that should be inserted in a document when selecting
+ * this completion. When `falsy` the {@link CompletionItem.label label}
+ * is used.
+ */
+ insertText?: string | SnippetString;
+
+ /**
+ * A range or a insert and replace range selecting the text that should be replaced by this completion item.
+ *
+ * When omitted, the range of the {@link TextDocument.getWordRangeAtPosition current word} is used as replace-range
+ * and as insert-range the start of the {@link TextDocument.getWordRangeAtPosition current word} to the
+ * current position is used.
+ *
+ * *Note 1:* A range must be a {@link Range.isSingleLine single line} and it must
+ * {@link Range.contains contain} the position at which completion has been {@link CompletionItemProvider.provideCompletionItems requested}.
+ * *Note 2:* A insert range must be a prefix of a replace range, that means it must be contained and starting at the same position.
+ */
+ range?: Range | { inserting: Range; replacing: Range; };
+
+ /**
+ * An optional set of characters that when pressed while this completion is active will accept it first and
+ * then type that character. *Note* that all commit characters should have `length=1` and that superfluous
+ * characters will be ignored.
+ */
+ commitCharacters?: string[];
+
+ /**
+ * Keep whitespace of the {@link CompletionItem.insertText insertText} as is. By default, the editor adjusts leading
+ * whitespace of new lines so that they match the indentation of the line for which the item is accepted - setting
+ * this to `true` will prevent that.
+ */
+ keepWhitespace?: boolean;
+
+ /**
+ * @deprecated Use `CompletionItem.insertText` and `CompletionItem.range` instead.
+ *
+ * An {@link TextEdit edit} which is applied to a document when selecting
+ * this completion. When an edit is provided the value of
+ * {@link CompletionItem.insertText insertText} is ignored.
+ *
+ * The {@link Range} of the edit must be single-line and on the same
+ * line completions were {@link CompletionItemProvider.provideCompletionItems requested} at.
+ */
+ textEdit?: TextEdit;
+
+ /**
+ * An optional array of additional {@link TextEdit text edits} that are applied when
+ * selecting this completion. Edits must not overlap with the main {@link CompletionItem.textEdit edit}
+ * nor with themselves.
+ */
+ additionalTextEdits?: TextEdit[];
+
+ /**
+ * An optional {@link Command} that is executed *after* inserting this completion. *Note* that
+ * additional modifications to the current document should be described with the
+ * {@link CompletionItem.additionalTextEdits additionalTextEdits}-property.
+ */
+ command?: Command;
+
+ /**
+ * Creates a new completion item.
+ *
+ * Completion items must have at least a {@link CompletionItem.label label} which then
+ * will be used as insert text as well as for sorting and filtering.
+ *
+ * @param label The label of the completion.
+ * @param kind The {@link CompletionItemKind kind} of the completion.
+ */
+ constructor(label: string, kind?: CompletionItemKind);
+ }
+
+ /**
+ * Represents a collection of {@link CompletionItem completion items} to be presented
+ * in the editor.
+ */
+ export class CompletionList {
+
+ /**
+ * This list is not complete. Further typing should result in recomputing
+ * this list.
+ */
+ isIncomplete?: boolean;
+
+ /**
+ * The completion items.
+ */
+ items: T[];
+
+ /**
+ * Creates a new completion list.
+ *
+ * @param items The completion items.
+ * @param isIncomplete The list is not complete.
+ */
+ constructor(items?: T[], isIncomplete?: boolean);
+ }
+
+ /**
+ * How a {@link CompletionItemProvider completion provider} was triggered
+ */
+ export enum CompletionTriggerKind {
+ /**
+ * Completion was triggered normally.
+ */
+ Invoke = 0,
+ /**
+ * Completion was triggered by a trigger character.
+ */
+ TriggerCharacter = 1,
+ /**
+ * Completion was re-triggered as current completion list is incomplete
+ */
+ TriggerForIncompleteCompletions = 2
+ }
+
+ /**
+ * Contains additional information about the context in which
+ * {@link CompletionItemProvider.provideCompletionItems completion provider} is triggered.
+ */
+ export interface CompletionContext {
+ /**
+ * How the completion was triggered.
+ */
+ readonly triggerKind: CompletionTriggerKind;
+
+ /**
+ * Character that triggered the completion item provider.
+ *
+ * `undefined` if provider was not triggered by a character.
+ *
+ * The trigger character is already in the document when the completion provider is triggered.
+ */
+ readonly triggerCharacter?: string;
+ }
+
+ /**
+ * The completion item provider interface defines the contract between extensions and
+ * [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense).
+ *
+ * Providers can delay the computation of the {@link CompletionItem.detail `detail`}
+ * and {@link CompletionItem.documentation `documentation`} properties by implementing the
+ * {@link CompletionItemProvider.resolveCompletionItem `resolveCompletionItem`}-function. However, properties that
+ * are needed for the initial sorting and filtering, like `sortText`, `filterText`, `insertText`, and `range`, must
+ * not be changed during resolve.
+ *
+ * Providers are asked for completions either explicitly by a user gesture or -depending on the configuration-
+ * implicitly when typing words or trigger characters.
+ */
+ export interface CompletionItemProvider {
+
+ /**
+ * Provide completion items for the given position and document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @param context How the completion was triggered.
+ *
+ * @return An array of completions, a {@link CompletionList 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.
+ */
+ provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult>;
+
+ /**
+ * Given a completion item fill in more data, like {@link CompletionItem.documentation doc-comment}
+ * or {@link CompletionItem.detail details}.
+ *
+ * The editor will only resolve a completion item once.
+ *
+ * *Note* that this function is called when completion items are already showing in the UI or when an item has been
+ * selected for insertion. Because of that, no property that changes the presentation (label, sorting, filtering etc)
+ * or the (primary) insert behaviour ({@link CompletionItem.insertText insertText}) can be changed.
+ *
+ * This function may fill in {@link CompletionItem.additionalTextEdits additionalTextEdits}. However, that means an item might be
+ * inserted *before* resolving is done and in that case the editor will do a best effort to still apply those additional
+ * text edits.
+ *
+ * @param item A completion item currently active in the UI.
+ * @param token A cancellation token.
+ * @return 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.
+ */
+ resolveCompletionItem?(item: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A document link is a range in a text document that links to an internal or external resource, like another
+ * text document or a web site.
+ */
+ export class DocumentLink {
+
+ /**
+ * The range this link applies to.
+ */
+ range: Range;
+
+ /**
+ * The uri this link points to.
+ */
+ target?: Uri;
+
+ /**
+ * The tooltip text when you hover over this link.
+ *
+ * If a tooltip is provided, is will be displayed in a string that includes instructions on how to
+ * trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary depending on OS,
+ * user settings, and localization.
+ */
+ tooltip?: string;
+
+ /**
+ * Creates a new document link.
+ *
+ * @param range The range the document link applies to. Must not be empty.
+ * @param target The uri the document link points to.
+ */
+ constructor(range: Range, target?: Uri);
+ }
+
+ /**
+ * The document link provider defines the contract between extensions and feature of showing
+ * links in the editor.
+ */
+ export interface DocumentLinkProvider {
+
+ /**
+ * Provide links for the given document. Note that the editor ships with a default provider that detects
+ * `http(s)` and `file` links.
+ *
+ * @param document The document in which the command was invoked.
+ * @param token A cancellation token.
+ * @return An array of {@link DocumentLink document links} or a thenable that resolves to such. The lack of a result
+ * can be signaled by returning `undefined`, `null`, or an empty array.
+ */
+ provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult;
+
+ /**
+ * Given a link fill in its {@link DocumentLink.target target}. This method is called when an incomplete
+ * link is selected in the UI. Providers can implement this method and return incomplete links
+ * (without target) from the {@link DocumentLinkProvider.provideDocumentLinks `provideDocumentLinks`} method which
+ * often helps to improve performance.
+ *
+ * @param link The link that is to be resolved.
+ * @param token A cancellation token.
+ */
+ resolveDocumentLink?(link: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Represents a color in RGBA space.
+ */
+ export class Color {
+
+ /**
+ * The red component of this color in the range [0-1].
+ */
+ readonly red: number;
+
+ /**
+ * The green component of this color in the range [0-1].
+ */
+ readonly green: number;
+
+ /**
+ * The blue component of this color in the range [0-1].
+ */
+ readonly blue: number;
+
+ /**
+ * The alpha component of this color in the range [0-1].
+ */
+ readonly alpha: number;
+
+ /**
+ * Creates a new color instance.
+ *
+ * @param red The red component.
+ * @param green The green component.
+ * @param blue The blue component.
+ * @param alpha The alpha component.
+ */
+ constructor(red: number, green: number, blue: number, alpha: number);
+ }
+
+ /**
+ * Represents a color range from a document.
+ */
+ export class ColorInformation {
+
+ /**
+ * The range in the document where this color appears.
+ */
+ range: Range;
+
+ /**
+ * The actual color value for this color range.
+ */
+ color: Color;
+
+ /**
+ * Creates a new color range.
+ *
+ * @param range The range the color appears in. Must not be empty.
+ * @param color The value of the color.
+ * @param format The format in which this color is currently formatted.
+ */
+ constructor(range: Range, color: Color);
+ }
+
+ /**
+ * A color presentation object describes how a {@link Color `color`} should be represented as text and what
+ * edits are required to refer to it from source code.
+ *
+ * For some languages one color can have multiple presentations, e.g. css can represent the color red with
+ * the constant `Red`, the hex-value `#ff0000`, or in rgba and hsla forms. In csharp other representations
+ * apply, e.g. `System.Drawing.Color.Red`.
+ */
+ export class ColorPresentation {
+
+ /**
+ * The label of this color presentation. It will be shown on the color
+ * picker header. By default this is also the text that is inserted when selecting
+ * this color presentation.
+ */
+ label: string;
+
+ /**
+ * An {@link TextEdit edit} which is applied to a document when selecting
+ * this presentation for the color. When `falsy` the {@link ColorPresentation.label label}
+ * is used.
+ */
+ textEdit?: TextEdit;
+
+ /**
+ * An optional array of additional {@link TextEdit text edits} that are applied when
+ * selecting this color presentation. Edits must not overlap with the main {@link ColorPresentation.textEdit edit} nor with themselves.
+ */
+ additionalTextEdits?: TextEdit[];
+
+ /**
+ * Creates a new color presentation.
+ *
+ * @param label The label of this color presentation.
+ */
+ constructor(label: string);
+ }
+
+ /**
+ * The document color provider defines the contract between extensions and feature of
+ * picking and modifying colors in the editor.
+ */
+ export interface DocumentColorProvider {
+
+ /**
+ * Provide colors for the given document.
+ *
+ * @param document The document in which the command was invoked.
+ * @param token A cancellation token.
+ * @return An array of {@link ColorInformation color information} or a thenable that resolves to such. The lack of a result
+ * can be signaled by returning `undefined`, `null`, or an empty array.
+ */
+ provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult;
+
+ /**
+ * Provide {@link ColorPresentation representations} for a color.
+ *
+ * @param color The color to show and insert.
+ * @param context A context object with additional information
+ * @param token A cancellation token.
+ * @return An array of color presentations or a thenable that resolves to such. The lack of a result
+ * can be signaled by returning `undefined`, `null`, or an empty array.
+ */
+ provideColorPresentations(color: Color, context: { document: TextDocument, range: Range }, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A line based folding range. To be valid, start and end line must be bigger than zero and smaller than the number of lines in the document.
+ * Invalid ranges will be ignored.
+ */
+ export class FoldingRange {
+
+ /**
+ * The zero-based start line of the range to fold. The folded area starts after the line's last character.
+ * To be valid, the end must be zero or larger and smaller than the number of lines in the document.
+ */
+ start: number;
+
+ /**
+ * The zero-based end line of the range to fold. The folded area ends with the line's last character.
+ * To be valid, the end must be zero or larger and smaller than the number of lines in the document.
+ */
+ end: number;
+
+ /**
+ * Describes the {@link FoldingRangeKind Kind} of the folding range such as {@link FoldingRangeKind.Comment Comment} or
+ * {@link FoldingRangeKind.Region Region}. The kind is used to categorize folding ranges and used by commands
+ * like 'Fold all comments'. See
+ * {@link FoldingRangeKind} for an enumeration of all kinds.
+ * If not set, the range is originated from a syntax element.
+ */
+ kind?: FoldingRangeKind;
+
+ /**
+ * Creates a new folding range.
+ *
+ * @param start The start line of the folded range.
+ * @param end The end line of the folded range.
+ * @param kind The kind of the folding range.
+ */
+ constructor(start: number, end: number, kind?: FoldingRangeKind);
+ }
+
+ /**
+ * An enumeration of specific folding range kinds. The kind is an optional field of a {@link FoldingRange}
+ * and is used to distinguish specific folding ranges such as ranges originated from comments. The kind is used by commands like
+ * `Fold all comments` or `Fold all regions`.
+ * If the kind is not set on the range, the range originated from a syntax element other than comments, imports or region markers.
+ */
+ export enum FoldingRangeKind {
+ /**
+ * Kind for folding range representing a comment.
+ */
+ Comment = 1,
+ /**
+ * Kind for folding range representing a import.
+ */
+ Imports = 2,
+ /**
+ * Kind for folding range representing regions originating from folding markers like `#region` and `#endregion`.
+ */
+ Region = 3
+ }
+
+ /**
+ * Folding context (for future use)
+ */
+ export interface FoldingContext {
+ }
+
+ /**
+ * The folding range provider interface defines the contract between extensions and
+ * [Folding](https://code.visualstudio.com/docs/editor/codebasics#_folding) in the editor.
+ */
+ export interface FoldingRangeProvider {
+
+ /**
+ * An optional event to signal that the folding ranges from this provider have changed.
+ */
+ onDidChangeFoldingRanges?: Event;
+
+ /**
+ * Returns a list of folding ranges or null and undefined if the provider
+ * does not want to participate or was cancelled.
+ * @param document The document in which the command was invoked.
+ * @param context Additional context information (for future use)
+ * @param token A cancellation token.
+ */
+ provideFoldingRanges(document: TextDocument, context: FoldingContext, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A selection range represents a part of a selection hierarchy. A selection range
+ * may have a parent selection range that contains it.
+ */
+ export class SelectionRange {
+
+ /**
+ * The {@link Range} of this selection range.
+ */
+ range: Range;
+
+ /**
+ * The parent selection range containing this range.
+ */
+ parent?: SelectionRange;
+
+ /**
+ * Creates a new selection range.
+ *
+ * @param range The range of the selection range.
+ * @param parent The parent of the selection range.
+ */
+ constructor(range: Range, parent?: SelectionRange);
+ }
+
+ export interface SelectionRangeProvider {
+ /**
+ * Provide selection ranges for the given positions.
+ *
+ * Selection ranges should be computed individually and independent for each position. The editor will merge
+ * and deduplicate ranges but providers must return hierarchies of selection ranges so that a range
+ * is {@link Range.contains contained} by its parent.
+ *
+ * @param document The document in which the command was invoked.
+ * @param positions The positions at which the command was invoked.
+ * @param token A cancellation token.
+ * @return Selection ranges or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideSelectionRanges(document: TextDocument, positions: Position[], token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Represents programming constructs like functions or constructors in the context
+ * of call hierarchy.
+ */
+ export class CallHierarchyItem {
+ /**
+ * The name of this item.
+ */
+ name: string;
+
+ /**
+ * The kind of this item.
+ */
+ kind: SymbolKind;
+
+ /**
+ * Tags for this item.
+ */
+ tags?: ReadonlyArray;
+
+ /**
+ * More detail for this item, e.g. the signature of a function.
+ */
+ detail?: string;
+
+ /**
+ * The resource identifier of this item.
+ */
+ uri: Uri;
+
+ /**
+ * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code.
+ */
+ range: Range;
+
+ /**
+ * The range that should be selected and revealed when this symbol is being picked, e.g. the name of a function.
+ * Must be contained by the {@link CallHierarchyItem.range `range`}.
+ */
+ selectionRange: Range;
+
+ /**
+ * Creates a new call hierarchy item.
+ */
+ constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range);
+ }
+
+ /**
+ * Represents an incoming call, e.g. a caller of a method or constructor.
+ */
+ export class CallHierarchyIncomingCall {
+
+ /**
+ * The item that makes the call.
+ */
+ from: CallHierarchyItem;
+
+ /**
+ * The range at which at which the calls appears. This is relative to the caller
+ * denoted by {@link CallHierarchyIncomingCall.from `this.from`}.
+ */
+ fromRanges: Range[];
+
+ /**
+ * Create a new call object.
+ *
+ * @param item The item making the call.
+ * @param fromRanges The ranges at which the calls appear.
+ */
+ constructor(item: CallHierarchyItem, fromRanges: Range[]);
+ }
+
+ /**
+ * Represents an outgoing call, e.g. calling a getter from a method or a method from a constructor etc.
+ */
+ export class CallHierarchyOutgoingCall {
+
+ /**
+ * The item that is called.
+ */
+ to: CallHierarchyItem;
+
+ /**
+ * The range at which this item is called. This is the range relative to the caller, e.g the item
+ * passed to {@link CallHierarchyProvider.provideCallHierarchyOutgoingCalls `provideCallHierarchyOutgoingCalls`}
+ * and not {@link CallHierarchyOutgoingCall.to `this.to`}.
+ */
+ fromRanges: Range[];
+
+ /**
+ * Create a new call object.
+ *
+ * @param item The item being called
+ * @param fromRanges The ranges at which the calls appear.
+ */
+ constructor(item: CallHierarchyItem, fromRanges: Range[]);
+ }
+
+ /**
+ * The call hierarchy provider interface describes the contract between extensions
+ * and the call hierarchy feature which allows to browse calls and caller of function,
+ * methods, constructor etc.
+ */
+ export interface CallHierarchyProvider {
+
+ /**
+ * Bootstraps call hierarchy by returning the item that is denoted by the given document
+ * and position. This item will be used as entry into the call graph. Providers should
+ * return `undefined` or `null` when there is no item at the given location.
+ *
+ * @param document The document in which the command was invoked.
+ * @param position The position at which the command was invoked.
+ * @param token A cancellation token.
+ * @returns A call hierarchy item or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ prepareCallHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+
+ /**
+ * Provide all incoming calls for an item, e.g all callers for a method. In graph terms this describes directed
+ * and annotated edges inside the call graph, e.g the given item is the starting node and the result is the nodes
+ * that can be reached.
+ *
+ * @param item The hierarchy item for which incoming calls should be computed.
+ * @param token A cancellation token.
+ * @returns A set of incoming calls or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideCallHierarchyIncomingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult;
+
+ /**
+ * Provide all outgoing calls for an item, e.g call calls to functions, methods, or constructors from the given item. In
+ * graph terms this describes directed and annotated edges inside the call graph, e.g the given item is the starting
+ * node and the result is the nodes that can be reached.
+ *
+ * @param item The hierarchy item for which outgoing calls should be computed.
+ * @param token A cancellation token.
+ * @returns A set of outgoing calls or a thenable that resolves to such. The lack of a result can be
+ * signaled by returning `undefined` or `null`.
+ */
+ provideCallHierarchyOutgoingCalls(item: CallHierarchyItem, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * Represents a list of ranges that can be edited together along with a word pattern to describe valid range contents.
+ */
+ export class LinkedEditingRanges {
+ /**
+ * Create a new linked editing ranges object.
+ *
+ * @param ranges A list of ranges that can be edited together
+ * @param wordPattern An optional word pattern that describes valid contents for the given ranges
+ */
+ constructor(ranges: Range[], wordPattern?: RegExp);
+
+ /**
+ * A list of ranges that can be edited together. The ranges must have
+ * identical length and text content. The ranges cannot overlap.
+ */
+ readonly ranges: Range[];
+
+ /**
+ * An optional word pattern that describes valid contents for the given ranges.
+ * If no pattern is provided, the language configuration's word pattern will be used.
+ */
+ readonly wordPattern?: RegExp;
+ }
+
+ /**
+ * The linked editing range provider interface defines the contract between extensions and
+ * the linked editing feature.
+ */
+ export interface LinkedEditingRangeProvider {
+ /**
+ * For a given position in a document, returns the range of the symbol at the position and all ranges
+ * that have the same content. A change to one of the ranges can be applied to all other ranges if the new content
+ * is valid. An optional word pattern can be returned with the result to describe valid contents.
+ * If no result-specific word pattern is provided, the word pattern from the language configuration is used.
+ *
+ * @param document The document in which the provider was invoked.
+ * @param position The position at which the provider was invoked.
+ * @param token A cancellation token.
+ * @return A list of ranges that can be edited together
+ */
+ provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * A tuple of two characters, like a pair of
+ * opening and closing brackets.
+ */
+ export type CharacterPair = [string, string];
+
+ /**
+ * Describes how comments for a language work.
+ */
+ export interface CommentRule {
+
+ /**
+ * The line comment token, like `// this is a comment`
+ */
+ lineComment?: string;
+
+ /**
+ * The block comment character pair, like `/* block comment */`
+ */
+ blockComment?: CharacterPair;
+ }
+
+ /**
+ * Describes indentation rules for a language.
+ */
+ export interface IndentationRule {
+ /**
+ * If a line matches this pattern, then all the lines after it should be unindented once (until another rule matches).
+ */
+ decreaseIndentPattern: RegExp;
+ /**
+ * If a line matches this pattern, then all the lines after it should be indented once (until another rule matches).
+ */
+ increaseIndentPattern: RegExp;
+ /**
+ * If a line matches this pattern, then **only the next line** after it should be indented once.
+ */
+ indentNextLinePattern?: RegExp;
+ /**
+ * If a line matches this pattern, then its indentation should not be changed and it should not be evaluated against the other rules.
+ */
+ unIndentedLinePattern?: RegExp;
+ }
+
+ /**
+ * Describes what to do with the indentation when pressing Enter.
+ */
+ export enum IndentAction {
+ /**
+ * Insert new line and copy the previous line's indentation.
+ */
+ None = 0,
+ /**
+ * Insert new line and indent once (relative to the previous line's indentation).
+ */
+ Indent = 1,
+ /**
+ * Insert two new lines:
+ * - the first one indented which will hold the cursor
+ * - the second one at the same indentation level
+ */
+ IndentOutdent = 2,
+ /**
+ * Insert new line and outdent once (relative to the previous line's indentation).
+ */
+ Outdent = 3
+ }
+
+ /**
+ * Describes what to do when pressing Enter.
+ */
+ export interface EnterAction {
+ /**
+ * Describe what to do with the indentation.
+ */
+ indentAction: IndentAction;
+ /**
+ * Describes text to be appended after the new line and after the indentation.
+ */
+ appendText?: string;
+ /**
+ * Describes the number of characters to remove from the new line's indentation.
+ */
+ removeText?: number;
+ }
+
+ /**
+ * Describes a rule to be evaluated when pressing Enter.
+ */
+ export interface OnEnterRule {
+ /**
+ * This rule will only execute if the text before the cursor matches this regular expression.
+ */
+ beforeText: RegExp;
+ /**
+ * This rule will only execute if the text after the cursor matches this regular expression.
+ */
+ afterText?: RegExp;
+ /**
+ * This rule will only execute if the text above the current line matches this regular expression.
+ */
+ previousLineText?: RegExp;
+ /**
+ * The action to execute.
+ */
+ action: EnterAction;
+ }
+
+ /**
+ * The language configuration interfaces defines the contract between extensions
+ * and various editor features, like automatic bracket insertion, automatic indentation etc.
+ */
+ export interface LanguageConfiguration {
+ /**
+ * The language's comment settings.
+ */
+ comments?: CommentRule;
+ /**
+ * The language's brackets.
+ * This configuration implicitly affects pressing Enter around these brackets.
+ */
+ brackets?: CharacterPair[];
+ /**
+ * 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
+ */
+ wordPattern?: RegExp;
+ /**
+ * The language's indentation settings.
+ */
+ indentationRules?: IndentationRule;
+ /**
+ * The language's rules to be evaluated when pressing Enter.
+ */
+ onEnterRules?: OnEnterRule[];
+
+ /**
+ * **Deprecated** Do not use.
+ *
+ * @deprecated Will be replaced by a better API soon.
+ */
+ __electricCharacterSupport?: {
+ /**
+ * This property is deprecated and will be **ignored** from
+ * the editor.
+ * @deprecated
+ */
+ brackets?: any;
+ /**
+ * This property is deprecated and not fully supported anymore by
+ * the editor (scope and lineStart are ignored).
+ * Use the autoClosingPairs property in the language configuration file instead.
+ * @deprecated
+ */
+ docComment?: {
+ scope: string;
+ open: string;
+ lineStart: string;
+ close?: string;
+ };
+ };
+
+ /**
+ * **Deprecated** Do not use.
+ *
+ * @deprecated * Use the autoClosingPairs property in the language configuration file instead.
+ */
+ __characterPairSupport?: {
+ autoClosingPairs: {
+ open: string;
+ close: string;
+ notIn?: string[];
+ }[];
+ };
+ }
+
+ /**
+ * The configuration target
+ */
+ export enum ConfigurationTarget {
+ /**
+ * Global configuration
+ */
+ Global = 1,
+
+ /**
+ * Workspace configuration
+ */
+ Workspace = 2,
+
+ /**
+ * Workspace folder configuration
+ */
+ WorkspaceFolder = 3
+ }
+
+ /**
+ * Represents the configuration. It is a merged view of
+ *
+ * - *Default Settings*
+ * - *Global (User) Settings*
+ * - *Workspace settings*
+ * - *Workspace Folder settings* - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to.
+ * - *Language settings* - Settings defined under requested language.
+ *
+ * The *effective* value (returned by {@link WorkspaceConfiguration.get `get`}) is computed by overriding or merging the values in the following order.
+ *
+ * ```
+ * `defaultValue` (if defined in `package.json` otherwise derived from the value's type)
+ * `globalValue` (if defined)
+ * `workspaceValue` (if defined)
+ * `workspaceFolderValue` (if defined)
+ * `defaultLanguageValue` (if defined)
+ * `globalLanguageValue` (if defined)
+ * `workspaceLanguageValue` (if defined)
+ * `workspaceFolderLanguageValue` (if defined)
+ * ```
+ * **Note:** Only `object` value types are merged and all other value types are overridden.
+ *
+ * Example 1: Overriding
+ *
+ * ```ts
+ * defaultValue = 'on';
+ * globalValue = 'relative'
+ * workspaceFolderValue = 'off'
+ * value = 'off'
+ * ```
+ *
+ * Example 2: Language Values
+ *
+ * ```ts
+ * defaultValue = 'on';
+ * globalValue = 'relative'
+ * workspaceFolderValue = 'off'
+ * globalLanguageValue = 'on'
+ * value = 'on'
+ * ```
+ *
+ * Example 3: Object Values
+ *
+ * ```ts
+ * defaultValue = { "a": 1, "b": 2 };
+ * globalValue = { "b": 3, "c": 4 };
+ * value = { "a": 1, "b": 3, "c": 4 };
+ * ```
+ *
+ * *Note:* Workspace and Workspace Folder configurations contains `launch` and `tasks` settings. Their basename will be
+ * part of the section identifier. The following snippets shows how to retrieve all configurations
+ * from `launch.json`:
+ *
+ * ```ts
+ * // launch.json configuration
+ * const config = workspace.getConfiguration('launch', vscode.workspace.workspaceFolders[0].uri);
+ *
+ * // retrieve values
+ * const values = config.get('configurations');
+ * ```
+ *
+ * Refer to [Settings](https://code.visualstudio.com/docs/getstarted/settings) for more information.
+ */
+ export interface WorkspaceConfiguration {
+
+ /**
+ * Return a value from this configuration.
+ *
+ * @param section Configuration name, supports _dotted_ names.
+ * @return The value `section` denotes or `undefined`.
+ */
+ get(section: string): T | undefined;
+
+ /**
+ * Return a value from this configuration.
+ *
+ * @param section Configuration name, supports _dotted_ names.
+ * @param defaultValue A value should be returned when no value could be found, is `undefined`.
+ * @return The value `section` denotes or the default.
+ */
+ get(section: string, defaultValue: T): T;
+
+ /**
+ * Check if this configuration has a certain value.
+ *
+ * @param section Configuration name, supports _dotted_ names.
+ * @return `true` if the section doesn't resolve to `undefined`.
+ */
+ has(section: string): boolean;
+
+ /**
+ * Retrieve all information about a configuration setting. A configuration value
+ * often consists of a *default* value, a global or installation-wide value,
+ * a workspace-specific value, folder-specific value
+ * and language-specific values (if {@link WorkspaceConfiguration} is scoped to a language).
+ *
+ * Also provides all language ids under which the given configuration setting is defined.
+ *
+ * *Note:* The configuration name must denote a leaf in the configuration tree
+ * (`editor.fontSize` vs `editor`) otherwise no result is returned.
+ *
+ * @param section Configuration name, supports _dotted_ names.
+ * @return Information about a configuration setting or `undefined`.
+ */
+ inspect(section: string): {
+ key: string;
+
+ defaultValue?: T;
+ globalValue?: T;
+ workspaceValue?: T,
+ workspaceFolderValue?: T,
+
+ defaultLanguageValue?: T;
+ globalLanguageValue?: T;
+ workspaceLanguageValue?: T;
+ workspaceFolderLanguageValue?: T;
+
+ languageIds?: string[];
+
+ } | undefined;
+
+ /**
+ * Update a configuration value. The updated configuration values are persisted.
+ *
+ * A value can be changed in
+ *
+ * - {@link ConfigurationTarget.Global Global settings}: Changes the value for all instances of the editor.
+ * - {@link ConfigurationTarget.Workspace Workspace settings}: Changes the value for current workspace, if available.
+ * - {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings}: Changes the value for settings from one of the {@link workspace.workspaceFolders Workspace Folders} under which the requested resource belongs to.
+ * - Language settings: Changes the value for the requested languageId.
+ *
+ * *Note:* To remove a configuration value use `undefined`, like so: `config.update('somekey', undefined)`
+ *
+ * @param section Configuration name, supports _dotted_ names.
+ * @param value The new value.
+ * @param configurationTarget The {@link ConfigurationTarget configuration target} or a boolean value.
+ * - If `true` updates {@link ConfigurationTarget.Global Global settings}.
+ * - If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}.
+ * - If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific,
+ * otherwise to {@link ConfigurationTarget.Workspace Workspace settings}.
+ * @param overrideInLanguage Whether to update the value in the scope of requested languageId or not.
+ * - If `true` updates the value under the requested languageId.
+ * - If `undefined` updates the value under the requested languageId only if the configuration is defined for the language.
+ * @throws error while updating
+ * - configuration which is not registered.
+ * - window configuration to workspace folder
+ * - configuration to workspace or workspace folder when no workspace is opened.
+ * - configuration to workspace folder when there is no workspace folder settings.
+ * - configuration to workspace folder when {@link WorkspaceConfiguration} is not scoped to a resource.
+ */
+ update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable;
+
+ /**
+ * Readable dictionary that backs this configuration.
+ */
+ readonly [key: string]: any;
+ }
+
+ /**
+ * Represents a location inside a resource, such as a line
+ * inside a text file.
+ */
+ export class Location {
+
+ /**
+ * The resource identifier of this location.
+ */
+ uri: Uri;
+
+ /**
+ * The document range of this location.
+ */
+ range: Range;
+
+ /**
+ * Creates a new location object.
+ *
+ * @param uri The resource identifier.
+ * @param rangeOrPosition The range or position. Positions will be converted to an empty range.
+ */
+ constructor(uri: Uri, rangeOrPosition: Range | Position);
+ }
+
+ /**
+ * Represents the connection of two locations. Provides additional metadata over normal {@link Location locations},
+ * including an origin range.
+ */
+ export interface LocationLink {
+ /**
+ * Span of the origin of this link.
+ *
+ * Used as the underlined span for mouse definition hover. Defaults to the word range at
+ * the definition position.
+ */
+ originSelectionRange?: Range;
+
+ /**
+ * The target resource identifier of this link.
+ */
+ targetUri: Uri;
+
+ /**
+ * The full target range of this link.
+ */
+ targetRange: Range;
+
+ /**
+ * The span of this link.
+ */
+ targetSelectionRange?: Range;
+ }
+
+ /**
+ * The event that is fired when diagnostics change.
+ */
+ export interface DiagnosticChangeEvent {
+
+ /**
+ * An array of resources for which diagnostics have changed.
+ */
+ readonly uris: ReadonlyArray;
+ }
+
+ /**
+ * Represents the severity of diagnostics.
+ */
+ export enum DiagnosticSeverity {
+
+ /**
+ * Something not allowed by the rules of a language or other means.
+ */
+ Error = 0,
+
+ /**
+ * Something suspicious but allowed.
+ */
+ Warning = 1,
+
+ /**
+ * Something to inform about but not a problem.
+ */
+ Information = 2,
+
+ /**
+ * Something to hint to a better way of doing it, like proposing
+ * a refactoring.
+ */
+ Hint = 3
+ }
+
+ /**
+ * Represents a related message and source code location for a diagnostic. This should be
+ * used to point to code locations that cause or related to a diagnostics, e.g. when duplicating
+ * a symbol in a scope.
+ */
+ export class DiagnosticRelatedInformation {
+
+ /**
+ * The location of this related diagnostic information.
+ */
+ location: Location;
+
+ /**
+ * The message of this related diagnostic information.
+ */
+ message: string;
+
+ /**
+ * Creates a new related diagnostic information object.
+ *
+ * @param location The location.
+ * @param message The message.
+ */
+ constructor(location: Location, message: string);
+ }
+
+ /**
+ * Additional metadata about the type of a diagnostic.
+ */
+ export enum DiagnosticTag {
+ /**
+ * Unused or unnecessary code.
+ *
+ * Diagnostics with this tag are rendered faded out. The amount of fading
+ * is controlled by the `"editorUnnecessaryCode.opacity"` theme color. For
+ * example, `"editorUnnecessaryCode.opacity": "#000000c0"` will render the
+ * code with 75% opacity. For high contrast themes, use the
+ * `"editorUnnecessaryCode.border"` theme color to underline unnecessary code
+ * instead of fading it out.
+ */
+ Unnecessary = 1,
+
+ /**
+ * Deprecated or obsolete code.
+ *
+ * Diagnostics with this tag are rendered with a strike through.
+ */
+ Deprecated = 2,
+ }
+
+ /**
+ * Represents a diagnostic, such as a compiler error or warning. Diagnostic objects
+ * are only valid in the scope of a file.
+ */
+ export class Diagnostic {
+
+ /**
+ * The range to which this diagnostic applies.
+ */
+ range: Range;
+
+ /**
+ * The human-readable message.
+ */
+ message: string;
+
+ /**
+ * The severity, default is {@link DiagnosticSeverity.Error error}.
+ */
+ severity: DiagnosticSeverity;
+
+ /**
+ * A human-readable string describing the source of this
+ * diagnostic, e.g. 'typescript' or 'super lint'.
+ */
+ source?: string;
+
+ /**
+ * A code or identifier for this diagnostic.
+ * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}.
+ */
+ code?: string | number | {
+ /**
+ * A code or identifier for this diagnostic.
+ * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}.
+ */
+ value: string | number;
+
+ /**
+ * A target URI to open with more information about the diagnostic error.
+ */
+ target: Uri;
+ };
+
+ /**
+ * An array of related diagnostic information, e.g. when symbol-names within
+ * a scope collide all definitions can be marked via this property.
+ */
+ relatedInformation?: DiagnosticRelatedInformation[];
+
+ /**
+ * Additional metadata about the diagnostic.
+ */
+ tags?: DiagnosticTag[];
+
+ /**
+ * Creates a new diagnostic object.
+ *
+ * @param range The range to which this diagnostic applies.
+ * @param message The human-readable message.
+ * @param severity The severity, default is {@link DiagnosticSeverity.Error error}.
+ */
+ constructor(range: Range, message: string, severity?: DiagnosticSeverity);
+ }
+
+ /**
+ * A diagnostics collection is a container that manages a set of
+ * {@link Diagnostic diagnostics}. Diagnostics are always scopes to a
+ * diagnostics collection and a resource.
+ *
+ * To get an instance of a `DiagnosticCollection` use
+ * {@link languages.createDiagnosticCollection createDiagnosticCollection}.
+ */
+ export interface DiagnosticCollection {
+
+ /**
+ * 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](https://code.visualstudio.com/docs/editor/tasks#_defining-a-problem-matcher).
+ */
+ readonly name: string;
+
+ /**
+ * Assign diagnostics for given resource. Will replace
+ * existing diagnostics for that resource.
+ *
+ * @param uri A resource identifier.
+ * @param diagnostics Array of diagnostics or `undefined`
+ */
+ set(uri: Uri, diagnostics: ReadonlyArray | undefined): void;
+
+ /**
+ * Replace diagnostics for multiple resources in this collection.
+ *
+ * _Note_ that multiple tuples of the same uri will be merged, e.g
+ * `[[file1, [d1]], [file1, [d2]]]` is equivalent to `[[file1, [d1, d2]]]`.
+ * If a diagnostics item is `undefined` as in `[file1, undefined]`
+ * all previous but not subsequent diagnostics are removed.
+ *
+ * @param entries An array of tuples, like `[[file1, [d1, d2]], [file2, [d3, d4, d5]]]`, or `undefined`.
+ */
+ set(entries: ReadonlyArray<[Uri, ReadonlyArray | undefined]>): void;
+
+ /**
+ * Remove all diagnostics from this collection that belong
+ * to the provided `uri`. The same as `#set(uri, undefined)`.
+ *
+ * @param uri A resource identifier.
+ */
+ delete(uri: Uri): void;
+
+ /**
+ * Remove all diagnostics from this collection. The same
+ * as calling `#set(undefined)`;
+ */
+ clear(): void;
+
+ /**
+ * Iterate over each entry in this collection.
+ *
+ * @param callback Function to execute for each entry.
+ * @param thisArg The `this` context used when invoking the handler function.
+ */
+ forEach(callback: (uri: Uri, diagnostics: ReadonlyArray, collection: DiagnosticCollection) => any, thisArg?: any): void;
+
+ /**
+ * Get the diagnostics for a given resource. *Note* that you cannot
+ * modify the diagnostics-array returned from this call.
+ *
+ * @param uri A resource identifier.
+ * @returns An immutable array of {@link Diagnostic diagnostics} or `undefined`.
+ */
+ get(uri: Uri): ReadonlyArray | undefined;
+
+ /**
+ * Check if this collection contains diagnostics for a
+ * given resource.
+ *
+ * @param uri A resource identifier.
+ * @returns `true` if this collection has diagnostic for the given resource.
+ */
+ has(uri: Uri): boolean;
+
+ /**
+ * Dispose and free associated resources. Calls
+ * {@link DiagnosticCollection.clear clear}.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Denotes a location of an editor in the window. Editors can be arranged in a grid
+ * and each column represents one editor location in that grid by counting the editors
+ * in order of their appearance.
+ */
+ export enum ViewColumn {
+ /**
+ * A *symbolic* editor column representing the currently active column. This value
+ * can be used when opening editors, but the *resolved* {@link TextEditor.viewColumn viewColumn}-value
+ * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Active`.
+ */
+ Active = -1,
+ /**
+ * A *symbolic* editor column representing the column to the side of the active one. This value
+ * can be used when opening editors, but the *resolved* {@link TextEditor.viewColumn viewColumn}-value
+ * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Beside`.
+ */
+ Beside = -2,
+ /**
+ * The first editor column.
+ */
+ One = 1,
+ /**
+ * The second editor column.
+ */
+ Two = 2,
+ /**
+ * The third editor column.
+ */
+ Three = 3,
+ /**
+ * The fourth editor column.
+ */
+ Four = 4,
+ /**
+ * The fifth editor column.
+ */
+ Five = 5,
+ /**
+ * The sixth editor column.
+ */
+ Six = 6,
+ /**
+ * The seventh editor column.
+ */
+ Seven = 7,
+ /**
+ * The eighth editor column.
+ */
+ Eight = 8,
+ /**
+ * The ninth editor column.
+ */
+ Nine = 9
+ }
+
+ /**
+ * An output channel is a container for readonly textual information.
+ *
+ * To get an instance of an `OutputChannel` use
+ * {@link window.createOutputChannel createOutputChannel}.
+ */
+ export interface OutputChannel {
+
+ /**
+ * The human-readable name of this output channel.
+ */
+ readonly name: string;
+
+ /**
+ * Append the given value to the channel.
+ *
+ * @param value A string, falsy values will not be printed.
+ */
+ append(value: string): void;
+
+ /**
+ * Append the given value and a line feed character
+ * to the channel.
+ *
+ * @param value A string, falsy values will be printed.
+ */
+ appendLine(value: string): void;
+
+ /**
+ * Removes all output from the channel.
+ */
+ clear(): void;
+
+ /**
+ * Reveal this channel in the UI.
+ *
+ * @param preserveFocus When `true` the channel will not take focus.
+ */
+ show(preserveFocus?: boolean): void;
+
+ /**
+ * Reveal this channel in the UI.
+ *
+ * @deprecated Use the overload with just one parameter (`show(preserveFocus?: boolean): void`).
+ *
+ * @param column This argument is **deprecated** and will be ignored.
+ * @param preserveFocus When `true` the channel will not take focus.
+ */
+ show(column?: ViewColumn, preserveFocus?: boolean): void;
+
+ /**
+ * Hide this channel from the UI.
+ */
+ hide(): void;
+
+ /**
+ * Dispose and free associated resources.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Accessibility information which controls screen reader behavior.
+ */
+ export interface AccessibilityInformation {
+ /**
+ * Label to be read out by a screen reader once the item has focus.
+ */
+ label: string;
+
+ /**
+ * Role of the widget which defines how a screen reader interacts with it.
+ * The role should be set in special cases when for example a tree-like element behaves like a checkbox.
+ * If role is not specified VS Code will pick the appropriate role automatically.
+ * More about aria roles can be found here https://w3c.github.io/aria/#widget_roles
+ */
+ role?: string;
+ }
+
+ /**
+ * Represents the alignment of status bar items.
+ */
+ export enum StatusBarAlignment {
+
+ /**
+ * Aligned to the left side.
+ */
+ Left = 1,
+
+ /**
+ * Aligned to the right side.
+ */
+ Right = 2
+ }
+
+ /**
+ * A status bar item is a status bar contribution that can
+ * show text and icons and run a command on click.
+ */
+ export interface StatusBarItem {
+
+ /**
+ * The alignment of this item.
+ */
+ readonly alignment: StatusBarAlignment;
+
+ /**
+ * The priority of this item. Higher value means the item should
+ * be shown more to the left.
+ */
+ readonly priority?: number;
+
+ /**
+ * 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 ThemeIcon [icon set](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing), e.g.
+ * `light-bulb`, `thumbsup`, `zap` etc.
+ */
+ text: string;
+
+ /**
+ * The tooltip text when you hover over this entry.
+ */
+ tooltip: string | undefined;
+
+ /**
+ * The foreground color for this entry.
+ */
+ color: string | ThemeColor | undefined;
+
+ /**
+ * The background color for this entry.
+ *
+ * *Note*: only `new ThemeColor('statusBarItem.errorBackground')` is
+ * supported for now. More background colors may be supported in the
+ * future.
+ *
+ * *Note*: when a background color is set, the statusbar may override
+ * the `color` choice to ensure the entry is readable in all themes.
+ */
+ backgroundColor: ThemeColor | undefined;
+
+ /**
+ * {@link Command `Command`} or identifier of a command to run on click.
+ *
+ * The command must be {@link commands.getCommands known}.
+ *
+ * Note that if this is a {@link Command `Command`} object, only the {@link Command.command `command`} and {@link Command.arguments `arguments`}
+ * are used by VS Code.
+ */
+ command: string | Command | undefined;
+
+ /**
+ * Accessibility information used when screen reader interacts with this StatusBar item
+ */
+ accessibilityInformation?: AccessibilityInformation;
+
+ /**
+ * Shows the entry in the status bar.
+ */
+ show(): void;
+
+ /**
+ * Hide the entry in the status bar.
+ */
+ hide(): void;
+
+ /**
+ * Dispose and free associated resources. Call
+ * {@link StatusBarItem.hide hide}.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Defines a generalized way of reporting progress updates.
+ */
+ export interface Progress {
+
+ /**
+ * Report a progress update.
+ * @param value A progress item, like a message and/or an
+ * report on how much work finished
+ */
+ report(value: T): void;
+ }
+
+ /**
+ * An individual terminal instance within the integrated terminal.
+ */
+ export interface Terminal {
+
+ /**
+ * The name of the terminal.
+ */
+ readonly name: string;
+
+ /**
+ * The process ID of the shell process.
+ */
+ readonly processId: Thenable;
+
+ /**
+ * The object used to initialize the terminal, this is useful for example to detecting the
+ * shell type of when the terminal was not launched by this extension or for detecting what
+ * folder the shell was launched in.
+ */
+ readonly creationOptions: Readonly;
+
+ /**
+ * The exit status of the terminal, this will be undefined while the terminal is active.
+ *
+ * **Example:** Show a notification with the exit code when the terminal exits with a
+ * non-zero exit code.
+ * ```typescript
+ * window.onDidCloseTerminal(t => {
+ * if (t.exitStatus && t.exitStatus.code) {
+ * vscode.window.showInformationMessage(`Exit code: ${t.exitStatus.code}`);
+ * }
+ * });
+ * ```
+ */
+ readonly exitStatus: TerminalExitStatus | undefined;
+
+ /**
+ * Send text to the terminal. The text is written to the stdin of the underlying pty process
+ * (shell) of the terminal.
+ *
+ * @param text The text to send.
+ * @param addNewLine Whether to add a new line to the text being sent, this is normally
+ * required to run a command in the terminal. The character(s) added are \n or \r\n
+ * depending on the platform. This defaults to `true`.
+ */
+ sendText(text: string, addNewLine?: boolean): void;
+
+ /**
+ * Show the terminal panel and reveal this terminal in the UI.
+ *
+ * @param preserveFocus When `true` the terminal will not take focus.
+ */
+ show(preserveFocus?: boolean): void;
+
+ /**
+ * Hide the terminal panel if this terminal is currently showing.
+ */
+ hide(): void;
+
+ /**
+ * Dispose and free associated resources.
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Provides information on a line in a terminal in order to provide links for it.
+ */
+ export interface TerminalLinkContext {
+ /**
+ * This is the text from the unwrapped line in the terminal.
+ */
+ line: string;
+
+ /**
+ * The terminal the link belongs to.
+ */
+ terminal: Terminal;
+ }
+
+ /**
+ * A provider that enables detection and handling of links within terminals.
+ */
+ export interface TerminalLinkProvider {
+ /**
+ * Provide terminal links for the given context. Note that this can be called multiple times
+ * even before previous calls resolve, make sure to not share global objects (eg. `RegExp`)
+ * that could have problems when asynchronous usage may overlap.
+ * @param context Information about what links are being provided for.
+ * @param token A cancellation token.
+ * @return A list of terminal links for the given line.
+ */
+ provideTerminalLinks(context: TerminalLinkContext, token: CancellationToken): ProviderResult;
+
+ /**
+ * Handle an activated terminal link.
+ * @param link The link to handle.
+ */
+ handleTerminalLink(link: T): ProviderResult;
+ }
+
+ /**
+ * A link on a terminal line.
+ */
+ export interface TerminalLink {
+ /**
+ * The start index of the link on {@link TerminalLinkContext.line}.
+ */
+ startIndex: number;
+
+ /**
+ * The length of the link on {@link TerminalLinkContext.line}.
+ */
+ length: number;
+
+ /**
+ * The tooltip text when you hover over this link.
+ *
+ * If a tooltip is provided, is will be displayed in a string that includes instructions on
+ * how to trigger the link, such as `{0} (ctrl + click)`. The specific instructions vary
+ * depending on OS, user settings, and localization.
+ */
+ tooltip?: string;
+ }
+
+ /**
+ * A file decoration represents metadata that can be rendered with a file.
+ */
+ export class FileDecoration {
+
+ /**
+ * A very short string that represents this decoration.
+ */
+ badge?: string;
+
+ /**
+ * A human-readable tooltip for this decoration.
+ */
+ tooltip?: string;
+
+ /**
+ * The color of this decoration.
+ */
+ color?: ThemeColor;
+
+ /**
+ * A flag expressing that this decoration should be
+ * propagated to its parents.
+ */
+ propagate?: boolean;
+
+ /**
+ * Creates a new decoration.
+ *
+ * @param badge A letter that represents the decoration.
+ * @param tooltip The tooltip of the decoration.
+ * @param color The color of the decoration.
+ */
+ constructor(badge?: string, tooltip?: string, color?: ThemeColor);
+ }
+
+ /**
+ * The decoration provider interfaces defines the contract between extensions and
+ * file decorations.
+ */
+ export interface FileDecorationProvider {
+
+ /**
+ * An optional event to signal that decorations for one or many files have changed.
+ *
+ * *Note* that this event should be used to propagate information about children.
+ *
+ * @see {@link EventEmitter}
+ */
+ onDidChangeFileDecorations?: Event;
+
+ /**
+ * Provide decorations for a given uri.
+ *
+ * *Note* that this function is only called when a file gets rendered in the UI.
+ * This means a decoration from a descendent that propagates upwards must be signaled
+ * to the editor via the {@link FileDecorationProvider.onDidChangeFileDecorations onDidChangeFileDecorations}-event.
+ *
+ * @param uri The uri of the file to provide a decoration for.
+ * @param token A cancellation token.
+ * @returns A decoration or a thenable that resolves to such.
+ */
+ provideFileDecoration(uri: Uri, token: CancellationToken): ProviderResult;
+ }
+
+
+ /**
+ * In a remote window the extension kind describes if an extension
+ * runs where the UI (window) runs or if an extension runs remotely.
+ */
+ export enum ExtensionKind {
+
+ /**
+ * Extension runs where the UI runs.
+ */
+ UI = 1,
+
+ /**
+ * Extension runs where the remote extension host runs.
+ */
+ Workspace = 2
+ }
+
+ /**
+ * Represents an extension.
+ *
+ * To get an instance of an `Extension` use {@link extensions.getExtension getExtension}.
+ */
+ export interface Extension {
+
+ /**
+ * The canonical extension identifier in the form of: `publisher.name`.
+ */
+ readonly id: string;
+
+ /**
+ * The uri of the directory containing the extension.
+ */
+ readonly extensionUri: Uri;
+
+ /**
+ * The absolute file path of the directory containing this extension. Shorthand
+ * notation for {@link Extension.extensionUri Extension.extensionUri.fsPath} (independent of the uri scheme).
+ */
+ readonly extensionPath: string;
+
+ /**
+ * `true` if the extension has been activated.
+ */
+ readonly isActive: boolean;
+
+ /**
+ * The parsed contents of the extension's package.json.
+ */
+ readonly packageJSON: any;
+
+ /**
+ * The extension kind describes if an extension runs where the UI runs
+ * or if an extension runs where the remote extension host runs. The extension kind
+ * is defined in the `package.json`-file of extensions but can also be refined
+ * via the `remote.extensionKind`-setting. When no remote extension host exists,
+ * the value is {@link ExtensionKind.UI `ExtensionKind.UI`}.
+ */
+ extensionKind: ExtensionKind;
+
+ /**
+ * The public API exported by this extension. It is an invalid action
+ * to access this field before this extension has been activated.
+ */
+ readonly exports: T;
+
+ /**
+ * Activates this extension and returns its public API.
+ *
+ * @return A promise that will resolve when this extension has been activated.
+ */
+ activate(): Thenable;
+ }
+
+ /**
+ * The ExtensionMode is provided on the `ExtensionContext` and indicates the
+ * mode the specific extension is running in.
+ */
+ export enum ExtensionMode {
+ /**
+ * The extension is installed normally (for example, from the marketplace
+ * or VSIX) in VS Code.
+ */
+ Production = 1,
+
+ /**
+ * The extension is running from an `--extensionDevelopmentPath` provided
+ * when launching VS Code.
+ */
+ Development = 2,
+
+ /**
+ * The extension is running from an `--extensionTestsPath` and
+ * the extension host is running unit tests.
+ */
+ Test = 3,
+ }
+
+ /**
+ * 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.
+ */
+ export interface ExtensionContext {
+
+ /**
+ * An array to which disposables can be added. When this
+ * extension is deactivated the disposables will be disposed.
+ */
+ readonly subscriptions: { dispose(): any }[];
+
+ /**
+ * A memento object that stores state in the context
+ * of the currently opened {@link workspace.workspaceFolders workspace}.
+ */
+ readonly workspaceState: Memento;
+
+ /**
+ * A memento object that stores state independent
+ * of the current opened {@link workspace.workspaceFolders workspace}.
+ */
+ readonly globalState: Memento & {
+ /**
+ * Set the keys whose values should be synchronized across devices when synchronizing user-data
+ * like configuration, extensions, and mementos.
+ *
+ * Note that this function defines the whole set of keys whose values are synchronized:
+ * - calling it with an empty array stops synchronization for this memento
+ * - calling it with a non-empty array replaces all keys whose values are synchronized
+ *
+ * For any given set of keys this function needs to be called only once but there is no harm in
+ * repeatedly calling it.
+ *
+ * @param keys The set of keys whose values are synced.
+ */
+ setKeysForSync(keys: string[]): void;
+ };
+
+ /**
+ * A storage utility for secrets.
+ */
+ readonly secrets: SecretStorage;
+
+ /**
+ * The uri of the directory containing the extension.
+ */
+ readonly extensionUri: Uri;
+
+ /**
+ * The absolute file path of the directory containing the extension. Shorthand
+ * notation for {@link TextDocument.uri ExtensionContext.extensionUri.fsPath} (independent of the uri scheme).
+ */
+ readonly extensionPath: string;
+
+ /**
+ * Gets the extension's environment variable collection for this workspace, enabling changes
+ * to be applied to terminal environment variables.
+ */
+ readonly environmentVariableCollection: EnvironmentVariableCollection;
+
+ /**
+ * Get the absolute path of a resource contained in the extension.
+ *
+ * *Note* that an absolute uri can be constructed via {@link Uri.joinPath `Uri.joinPath`} and
+ * {@link ExtensionContext.extensionUri `extensionUri`}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);`
+ *
+ * @param relativePath A relative path to a resource contained in the extension.
+ * @return The absolute path of the resource.
+ */
+ asAbsolutePath(relativePath: string): string;
+
+ /**
+ * The uri of a workspace specific directory in which the extension
+ * can store private state. The directory might not exist and creation is
+ * up to the extension. However, the parent directory is guaranteed to be existent.
+ * The value is `undefined` when no workspace nor folder has been opened.
+ *
+ * Use {@link ExtensionContext.workspaceState `workspaceState`} or
+ * {@link ExtensionContext.globalState `globalState`} to store key value data.
+ *
+ * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from
+ * an uri.
+ */
+ readonly storageUri: Uri | undefined;
+
+ /**
+ * An absolute file path of a workspace specific directory in which the extension
+ * can store private state. The directory might not exist on disk and creation is
+ * up to the extension. However, the parent directory is guaranteed to be existent.
+ *
+ * Use {@link ExtensionContext.workspaceState `workspaceState`} or
+ * {@link ExtensionContext.globalState `globalState`} to store key value data.
+ *
+ * @deprecated Use {@link ExtensionContext.storageUri storageUri} instead.
+ */
+ readonly storagePath: string | undefined;
+
+ /**
+ * The uri of a directory in which the extension can store global state.
+ * The directory might not exist on disk and creation is
+ * up to the extension. However, the parent directory is guaranteed to be existent.
+ *
+ * Use {@link ExtensionContext.globalState `globalState`} to store key value data.
+ *
+ * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from
+ * an uri.
+ */
+ readonly globalStorageUri: Uri;
+
+ /**
+ * An absolute file path in which the extension can store global state.
+ * The directory might not exist on disk and creation is
+ * up to the extension. However, the parent directory is guaranteed to be existent.
+ *
+ * Use {@link ExtensionContext.globalState `globalState`} to store key value data.
+ *
+ * @deprecated Use {@link ExtensionContext.globalStorageUri globalStorageUri} instead.
+ */
+ readonly globalStoragePath: string;
+
+ /**
+ * The uri of a directory in which the extension can create log files.
+ * The directory might not exist on disk and creation is up to the extension. However,
+ * the parent directory is guaranteed to be existent.
+ *
+ * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from
+ * an uri.
+ */
+ readonly logUri: Uri;
+
+ /**
+ * An absolute file path of a directory in which the extension can create log files.
+ * The directory might not exist on disk and creation is up to the extension. However,
+ * the parent directory is guaranteed to be existent.
+ *
+ * @deprecated Use {@link ExtensionContext.logUri logUri} instead.
+ */
+ readonly logPath: string;
+
+ /**
+ * The mode the extension is running in. This is specific to the current
+ * extension. One extension may be in `ExtensionMode.Development` while
+ * other extensions in the host run in `ExtensionMode.Release`.
+ */
+ readonly extensionMode: ExtensionMode;
+
+ /**
+ * The current `Extension` instance.
+ */
+ readonly extension: Extension;
+ }
+
+ /**
+ * A memento represents a storage utility. It can store and retrieve
+ * values.
+ */
+ export interface Memento {
+
+ /**
+ * Return a value.
+ *
+ * @param key A string.
+ * @return The stored value or `undefined`.
+ */
+ get(key: string): T | undefined;
+
+ /**
+ * Return a value.
+ *
+ * @param key A string.
+ * @param defaultValue A value that should be returned when there is no
+ * value (`undefined`) with the given key.
+ * @return The stored value or the defaultValue.
+ */
+ get(key: string, defaultValue: T): T;
+
+ /**
+ * Store a value. The value must be JSON-stringifyable.
+ *
+ * @param key A string.
+ * @param value A value. MUST not contain cyclic references.
+ */
+ update(key: string, value: any): Thenable;
+ }
+
+ /**
+ * The event data that is fired when a secret is added or removed.
+ */
+ export interface SecretStorageChangeEvent {
+ /**
+ * The key of the secret that has changed.
+ */
+ readonly key: string;
+ }
+
+ /**
+ * Represents a storage utility for secrets, information that is
+ * sensitive.
+ */
+ export interface SecretStorage {
+ /**
+ * Retrieve a secret that was stored with key. Returns undefined if there
+ * is no password matching that key.
+ * @param key The key the secret was stored under.
+ * @returns The stored value or `undefined`.
+ */
+ get(key: string): Thenable;
+
+ /**
+ * Store a secret under a given key.
+ * @param key The key to store the secret under.
+ * @param value The secret.
+ */
+ store(key: string, value: string): Thenable;
+
+ /**
+ * Remove a secret from storage.
+ * @param key The key the secret was stored under.
+ */
+ delete(key: string): Thenable;
+
+ /**
+ * Fires when a secret is stored or deleted.
+ */
+ onDidChange: Event;
+ }
+
+ /**
+ * Represents a color theme kind.
+ */
+ export enum ColorThemeKind {
+ Light = 1,
+ Dark = 2,
+ HighContrast = 3
+ }
+
+ /**
+ * Represents a color theme.
+ */
+ export interface ColorTheme {
+
+ /**
+ * The kind of this color theme: light, dark or high contrast.
+ */
+ readonly kind: ColorThemeKind;
+ }
+
+ /**
+ * Controls the behaviour of the terminal's visibility.
+ */
+ export enum TaskRevealKind {
+ /**
+ * Always brings the terminal to front if the task is executed.
+ */
+ Always = 1,
+
+ /**
+ * Only brings the terminal to front if a problem is detected executing the task
+ * (e.g. the task couldn't be started because).
+ */
+ Silent = 2,
+
+ /**
+ * The terminal never comes to front when the task is executed.
+ */
+ Never = 3
+ }
+
+ /**
+ * Controls how the task channel is used between tasks
+ */
+ export enum TaskPanelKind {
+
+ /**
+ * Shares a panel with other tasks. This is the default.
+ */
+ Shared = 1,
+
+ /**
+ * Uses a dedicated panel for this tasks. The panel is not
+ * shared with other tasks.
+ */
+ Dedicated = 2,
+
+ /**
+ * Creates a new panel whenever this task is executed.
+ */
+ New = 3
+ }
+
+ /**
+ * Controls how the task is presented in the UI.
+ */
+ export interface TaskPresentationOptions {
+ /**
+ * Controls whether the task output is reveal in the user interface.
+ * Defaults to `RevealKind.Always`.
+ */
+ reveal?: TaskRevealKind;
+
+ /**
+ * Controls whether the command associated with the task is echoed
+ * in the user interface.
+ */
+ echo?: boolean;
+
+ /**
+ * Controls whether the panel showing the task output is taking focus.
+ */
+ focus?: boolean;
+
+ /**
+ * Controls if the task panel is used for this task only (dedicated),
+ * shared between tasks (shared) or if a new panel is created on
+ * every task execution (new). Defaults to `TaskInstanceKind.Shared`
+ */
+ panel?: TaskPanelKind;
+
+ /**
+ * Controls whether to show the "Terminal will be reused by tasks, press any key to close it" message.
+ */
+ showReuseMessage?: boolean;
+
+ /**
+ * Controls whether the terminal is cleared before executing the task.
+ */
+ clear?: boolean;
+ }
+
+ /**
+ * A grouping for tasks. The editor by default supports the
+ * 'Clean', 'Build', 'RebuildAll' and 'Test' group.
+ */
+ export class TaskGroup {
+
+ /**
+ * The clean task group;
+ */
+ static Clean: TaskGroup;
+
+ /**
+ * The build task group;
+ */
+ static Build: TaskGroup;
+
+ /**
+ * The rebuild all task group;
+ */
+ static Rebuild: TaskGroup;
+
+ /**
+ * The test all task group;
+ */
+ static Test: TaskGroup;
+
+ private constructor(id: string, label: string);
+ }
+
+ /**
+ * A structure that defines a task kind in the system.
+ * The value must be JSON-stringifyable.
+ */
+ export interface TaskDefinition {
+ /**
+ * The task definition describing the task provided by an extension.
+ * Usually a task provider defines more properties to identify
+ * a task. They need to be defined in the package.json of the
+ * extension under the 'taskDefinitions' extension point. The npm
+ * task definition for example looks like this
+ * ```typescript
+ * interface NpmTaskDefinition extends TaskDefinition {
+ * script: string;
+ * }
+ * ```
+ *
+ * Note that type identifier starting with a '$' are reserved for internal
+ * usages and shouldn't be used by extensions.
+ */
+ readonly type: string;
+
+ /**
+ * Additional attributes of a concrete task definition.
+ */
+ [name: string]: any;
+ }
+
+ /**
+ * Options for a process execution
+ */
+ export interface ProcessExecutionOptions {
+ /**
+ * The current working directory of the executed program or shell.
+ * If omitted the tools current workspace root is used.
+ */
+ cwd?: string;
+
+ /**
+ * The additional environment of the executed program or shell. If omitted
+ * the parent process' environment is used. If provided it is merged with
+ * the parent process' environment.
+ */
+ env?: { [key: string]: string };
+ }
+
+ /**
+ * The execution of a task happens as an external process
+ * without shell interaction.
+ */
+ export class ProcessExecution {
+
+ /**
+ * Creates a process execution.
+ *
+ * @param process The process to start.
+ * @param options Optional options for the started process.
+ */
+ constructor(process: string, options?: ProcessExecutionOptions);
+
+ /**
+ * Creates a process execution.
+ *
+ * @param process The process to start.
+ * @param args Arguments to be passed to the process.
+ * @param options Optional options for the started process.
+ */
+ constructor(process: string, args: string[], options?: ProcessExecutionOptions);
+
+ /**
+ * The process to be executed.
+ */
+ process: string;
+
+ /**
+ * The arguments passed to the process. Defaults to an empty array.
+ */
+ args: string[];
+
+ /**
+ * The process options used when the process is executed.
+ * Defaults to undefined.
+ */
+ options?: ProcessExecutionOptions;
+ }
+
+ /**
+ * The shell quoting options.
+ */
+ export interface ShellQuotingOptions {
+
+ /**
+ * The character used to do character escaping. If a string is provided only spaces
+ * are escaped. If a `{ escapeChar, charsToEscape }` literal is provide all characters
+ * in `charsToEscape` are escaped using the `escapeChar`.
+ */
+ escape?: string | {
+ /**
+ * The escape character.
+ */
+ escapeChar: string;
+ /**
+ * The characters to escape.
+ */
+ charsToEscape: string;
+ };
+
+ /**
+ * The character used for strong quoting. The string's length must be 1.
+ */
+ strong?: string;
+
+ /**
+ * The character used for weak quoting. The string's length must be 1.
+ */
+ weak?: string;
+ }
+
+ /**
+ * Options for a shell execution
+ */
+ export interface ShellExecutionOptions {
+ /**
+ * The shell executable.
+ */
+ executable?: string;
+
+ /**
+ * The arguments to be passed to the shell executable used to run the task. Most shells
+ * require special arguments to execute a command. For example `bash` requires the `-c`
+ * argument to execute a command, `PowerShell` requires `-Command` and `cmd` requires both
+ * `/d` and `/c`.
+ */
+ shellArgs?: string[];
+
+ /**
+ * The shell quotes supported by this shell.
+ */
+ shellQuoting?: ShellQuotingOptions;
+
+ /**
+ * The current working directory of the executed shell.
+ * If omitted the tools current workspace root is used.
+ */
+ cwd?: string;
+
+ /**
+ * The additional environment of the executed shell. If omitted
+ * the parent process' environment is used. If provided it is merged with
+ * the parent process' environment.
+ */
+ env?: { [key: string]: string };
+ }
+
+ /**
+ * Defines how an argument should be quoted if it contains
+ * spaces or unsupported characters.
+ */
+ export enum ShellQuoting {
+
+ /**
+ * Character escaping should be used. This for example
+ * uses \ on bash and ` on PowerShell.
+ */
+ Escape = 1,
+
+ /**
+ * Strong string quoting should be used. This for example
+ * uses " for Windows cmd and ' for bash and PowerShell.
+ * Strong quoting treats arguments as literal strings.
+ * Under PowerShell echo 'The value is $(2 * 3)' will
+ * print `The value is $(2 * 3)`
+ */
+ Strong = 2,
+
+ /**
+ * Weak string quoting should be used. This for example
+ * uses " for Windows cmd, bash and PowerShell. Weak quoting
+ * still performs some kind of evaluation inside the quoted
+ * string. Under PowerShell echo "The value is $(2 * 3)"
+ * will print `The value is 6`
+ */
+ Weak = 3
+ }
+
+ /**
+ * A string that will be quoted depending on the used shell.
+ */
+ export interface ShellQuotedString {
+ /**
+ * The actual string value.
+ */
+ value: string;
+
+ /**
+ * The quoting style to use.
+ */
+ quoting: ShellQuoting;
+ }
+
+ export class ShellExecution {
+ /**
+ * Creates a shell execution with a full command line.
+ *
+ * @param commandLine The command line to execute.
+ * @param options Optional options for the started the shell.
+ */
+ constructor(commandLine: string, options?: ShellExecutionOptions);
+
+ /**
+ * Creates a shell execution with a command and arguments. For the real execution VS Code will
+ * construct a command line from the command and the arguments. This is subject to interpretation
+ * especially when it comes to quoting. If full control over the command line is needed please
+ * use the constructor that creates a `ShellExecution` with the full command line.
+ *
+ * @param command The command to execute.
+ * @param args The command arguments.
+ * @param options Optional options for the started the shell.
+ */
+ constructor(command: string | ShellQuotedString, args: (string | ShellQuotedString)[], options?: ShellExecutionOptions);
+
+ /**
+ * The shell command line. Is `undefined` if created with a command and arguments.
+ */
+ commandLine: string | undefined;
+
+ /**
+ * The shell command. Is `undefined` if created with a full command line.
+ */
+ command: string | ShellQuotedString;
+
+ /**
+ * The shell args. Is `undefined` if created with a full command line.
+ */
+ args: (string | ShellQuotedString)[];
+
+ /**
+ * The shell options used when the command line is executed in a shell.
+ * Defaults to undefined.
+ */
+ options?: ShellExecutionOptions;
+ }
+
+ /**
+ * Class used to execute an extension callback as a task.
+ */
+ export class CustomExecution {
+ /**
+ * Constructs a CustomExecution task object. The callback will be executed when the task is run, at which point the
+ * extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until
+ * {@link Pseudoterminal.open} is called. Task cancellation should be handled using
+ * {@link Pseudoterminal.close}. When the task is complete fire
+ * {@link Pseudoterminal.onDidClose}.
+ * @param callback The callback that will be called when the task is started by a user. Any ${} style variables that
+ * were in the task definition will be resolved and passed into the callback as `resolvedDefinition`.
+ */
+ constructor(callback: (resolvedDefinition: TaskDefinition) => Thenable);
+ }
+
+ /**
+ * The scope of a task.
+ */
+ export enum TaskScope {
+ /**
+ * The task is a global task. Global tasks are currently not supported.
+ */
+ Global = 1,
+
+ /**
+ * The task is a workspace task
+ */
+ Workspace = 2
+ }
+
+ /**
+ * Run options for a task.
+ */
+ export interface RunOptions {
+ /**
+ * Controls whether task variables are re-evaluated on rerun.
+ */
+ reevaluateOnRerun?: boolean;
+ }
+
+ /**
+ * A task to execute
+ */
+ export class Task {
+
+ /**
+ * Creates a new task.
+ *
+ * @param definition The task definition as defined in the taskDefinitions extension point.
+ * @param scope Specifies the task's scope. It is either a global or a workspace task or a task for a specific workspace folder. Global tasks are currently not supported.
+ * @param name The task's name. Is presented in the user interface.
+ * @param source The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.
+ * @param execution The process or shell execution.
+ * @param problemMatchers the names of problem matchers to use, like '$tsc'
+ * or '$eslint'. Problem matchers can be contributed by an extension using
+ * the `problemMatchers` extension point.
+ */
+ constructor(taskDefinition: TaskDefinition, scope: WorkspaceFolder | TaskScope.Global | TaskScope.Workspace, name: string, source: string, execution?: ProcessExecution | ShellExecution | CustomExecution, problemMatchers?: string | string[]);
+
+ /**
+ * Creates a new task.
+ *
+ * @deprecated Use the new constructors that allow specifying a scope for the task.
+ *
+ * @param definition The task definition as defined in the taskDefinitions extension point.
+ * @param name The task's name. Is presented in the user interface.
+ * @param source The task's source (e.g. 'gulp', 'npm', ...). Is presented in the user interface.
+ * @param execution The process or shell execution.
+ * @param problemMatchers the names of problem matchers to use, like '$tsc'
+ * or '$eslint'. Problem matchers can be contributed by an extension using
+ * the `problemMatchers` extension point.
+ */
+ constructor(taskDefinition: TaskDefinition, name: string, source: string, execution?: ProcessExecution | ShellExecution, problemMatchers?: string | string[]);
+
+ /**
+ * The task's definition.
+ */
+ definition: TaskDefinition;
+
+ /**
+ * The task's scope.
+ */
+ readonly scope?: TaskScope.Global | TaskScope.Workspace | WorkspaceFolder;
+
+ /**
+ * The task's name
+ */
+ name: string;
+
+ /**
+ * A human-readable string which is rendered less prominently on a separate line in places
+ * where the task's name is displayed. Supports rendering of {@link ThemeIcon theme icons}
+ * via the `$()`-syntax.
+ */
+ detail?: string;
+
+ /**
+ * The task's execution engine
+ */
+ execution?: ProcessExecution | ShellExecution | CustomExecution;
+
+ /**
+ * Whether the task is a background task or not.
+ */
+ isBackground: boolean;
+
+ /**
+ * A human-readable string describing the source of this shell task, e.g. 'gulp'
+ * or 'npm'. Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax.
+ */
+ source: string;
+
+ /**
+ * The task group this tasks belongs to. See TaskGroup
+ * for a predefined set of available groups.
+ * Defaults to undefined meaning that the task doesn't
+ * belong to any special group.
+ */
+ group?: TaskGroup;
+
+ /**
+ * The presentation options. Defaults to an empty literal.
+ */
+ presentationOptions: TaskPresentationOptions;
+
+ /**
+ * The problem matchers attached to the task. Defaults to an empty
+ * array.
+ */
+ problemMatchers: string[];
+
+ /**
+ * Run options for the task
+ */
+ runOptions: RunOptions;
+ }
+
+ /**
+ * A task provider allows to add tasks to the task service.
+ * A task provider is registered via {@link tasks.registerTaskProvider}.
+ */
+ export interface TaskProvider {
+ /**
+ * Provides tasks.
+ * @param token A cancellation token.
+ * @return an array of tasks
+ */
+ provideTasks(token: CancellationToken): ProviderResult;
+
+ /**
+ * Resolves a task that has no {@link Task.execution `execution`} set. Tasks are
+ * often created from information found in the `tasks.json`-file. Such tasks miss
+ * the information on how to execute them and a task provider must fill in
+ * the missing information in the `resolveTask`-method. This method will not be
+ * called for tasks returned from the above `provideTasks` method since those
+ * tasks are always fully resolved. A valid default implementation for the
+ * `resolveTask` method is to return `undefined`.
+ *
+ * Note that when filling in the properties of `task`, you _must_ be sure to
+ * use the exact same `TaskDefinition` and not create a new one. Other properties
+ * may be changed.
+ *
+ * @param task The task to resolve.
+ * @param token A cancellation token.
+ * @return The resolved task
+ */
+ resolveTask(task: T, token: CancellationToken): ProviderResult;
+ }
+
+ /**
+ * An object representing an executed Task. It can be used
+ * to terminate a task.
+ *
+ * This interface is not intended to be implemented.
+ */
+ export interface TaskExecution {
+ /**
+ * The task that got started.
+ */
+ task: Task;
+
+ /**
+ * Terminates the task execution.
+ */
+ terminate(): void;
+ }
+
+ /**
+ * An event signaling the start of a task execution.
+ *
+ * This interface is not intended to be implemented.
+ */
+ interface TaskStartEvent {
+ /**
+ * The task item representing the task that got started.
+ */
+ readonly execution: TaskExecution;
+ }
+
+ /**
+ * An event signaling the end of an executed task.
+ *
+ * This interface is not intended to be implemented.
+ */
+ interface TaskEndEvent {
+ /**
+ * The task item representing the task that finished.
+ */
+ readonly execution: TaskExecution;
+ }
+
+ /**
+ * An event signaling the start of a process execution
+ * triggered through a task
+ */
+ export interface TaskProcessStartEvent {
+
+ /**
+ * The task execution for which the process got started.
+ */
+ readonly execution: TaskExecution;
+
+ /**
+ * The underlying process id.
+ */
+ readonly processId: number;
+ }
+
+ /**
+ * An event signaling the end of a process execution
+ * triggered through a task
+ */
+ export interface TaskProcessEndEvent {
+
+ /**
+ * The task execution for which the process got started.
+ */
+ readonly execution: TaskExecution;
+
+ /**
+ * The process's exit code. Will be `undefined` when the task is terminated.
+ */
+ readonly exitCode: number | undefined;
+ }
+
+ export interface TaskFilter {
+ /**
+ * The task version as used in the tasks.json file.
+ * The string support the package.json semver notation.
+ */
+ version?: string;
+
+ /**
+ * The task type to return;
+ */
+ type?: string;
+ }
+
+ /**
+ * Namespace for tasks functionality.
+ */
+ export namespace tasks {
+
+ /**
+ * Register a task provider.
+ *
+ * @param type The task kind type this provider is registered for.
+ * @param provider A task provider.
+ * @return A {@link Disposable} that unregisters this provider when being disposed.
+ */
+ export function registerTaskProvider(type: string, provider: TaskProvider): Disposable;
+
+ /**
+ * Fetches all tasks available in the systems. This includes tasks
+ * from `tasks.json` files as well as tasks from task providers
+ * contributed through extensions.
+ *
+ * @param filter Optional filter to select tasks of a certain type or version.
+ */
+ export function fetchTasks(filter?: TaskFilter): Thenable;
+
+ /**
+ * Executes a task that is managed by VS Code. The returned
+ * task execution can be used to terminate the task.
+ *
+ * @throws When running a ShellExecution or a ProcessExecution
+ * task in an environment where a new process cannot be started.
+ * In such an environment, only CustomExecution tasks can be run.
+ *
+ * @param task the task to execute
+ */
+ export function executeTask(task: Task): Thenable;
+
+ /**
+ * The currently active task executions or an empty array.
+ */
+ export const taskExecutions: ReadonlyArray;
+
+ /**
+ * Fires when a task starts.
+ */
+ export const onDidStartTask: Event;
+
+ /**
+ * Fires when a task ends.
+ */
+ export const onDidEndTask: Event;
+
+ /**
+ * Fires when the underlying process has been started.
+ * This event will not fire for tasks that don't
+ * execute an underlying process.
+ */
+ export const onDidStartTaskProcess: Event;
+
+ /**
+ * Fires when the underlying process has ended.
+ * This event will not fire for tasks that don't
+ * execute an underlying process.
+ */
+ export const onDidEndTaskProcess: Event;
+ }
+
+ /**
+ * Enumeration of file types. The types `File` and `Directory` can also be
+ * a symbolic links, in that case use `FileType.File | FileType.SymbolicLink` and
+ * `FileType.Directory | FileType.SymbolicLink`.
+ */
+ export enum FileType {
+ /**
+ * The file type is unknown.
+ */
+ Unknown = 0,
+ /**
+ * A regular file.
+ */
+ File = 1,
+ /**
+ * A directory.
+ */
+ Directory = 2,
+ /**
+ * A symbolic link to a file.
+ */
+ SymbolicLink = 64
+ }
+
+ /**
+ * The `FileStat`-type represents metadata about a file
+ */
+ export interface FileStat {
+ /**
+ * The type of the file, e.g. is a regular file, a directory, or symbolic link
+ * to a file.
+ *
+ * *Note:* This value might be a bitmask, e.g. `FileType.File | FileType.SymbolicLink`.
+ */
+ type: FileType;
+ /**
+ * The creation timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.
+ */
+ ctime: number;
+ /**
+ * The modification timestamp in milliseconds elapsed since January 1, 1970 00:00:00 UTC.
+ *
+ * *Note:* If the file changed, it is important to provide an updated `mtime` that advanced
+ * from the previous value. Otherwise there may be optimizations in place that will not show
+ * the updated file contents in an editor for example.
+ */
+ mtime: number;
+ /**
+ * The size in bytes.
+ *
+ * *Note:* If the file changed, it is important to provide an updated `size`. Otherwise there
+ * may be optimizations in place that will not show the updated file contents in an editor for
+ * example.
+ */
+ size: number;
+ }
+
+ /**
+ * A type that filesystem providers should use to signal errors.
+ *
+ * This class has factory methods for common error-cases, like `FileNotFound` when
+ * a file or folder doesn't exist, use them like so: `throw vscode.FileSystemError.FileNotFound(someUri);`
+ */
+ export class FileSystemError extends Error {
+
+ /**
+ * Create an error to signal that a file or folder wasn't found.
+ * @param messageOrUri Message or uri.
+ */
+ static FileNotFound(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Create an error to signal that a file or folder already exists, e.g. when
+ * creating but not overwriting a file.
+ * @param messageOrUri Message or uri.
+ */
+ static FileExists(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Create an error to signal that a file is not a folder.
+ * @param messageOrUri Message or uri.
+ */
+ static FileNotADirectory(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Create an error to signal that a file is a folder.
+ * @param messageOrUri Message or uri.
+ */
+ static FileIsADirectory(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Create an error to signal that an operation lacks required permissions.
+ * @param messageOrUri Message or uri.
+ */
+ static NoPermissions(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Create an error to signal that the file system is unavailable or too busy to
+ * complete a request.
+ * @param messageOrUri Message or uri.
+ */
+ static Unavailable(messageOrUri?: string | Uri): FileSystemError;
+
+ /**
+ * Creates a new filesystem error.
+ *
+ * @param messageOrUri Message or uri.
+ */
+ constructor(messageOrUri?: string | Uri);
+
+ /**
+ * A code that identifies this error.
+ *
+ * Possible values are names of errors, like {@link FileSystemError.FileNotFound `FileNotFound`},
+ * or `Unknown` for unspecified errors.
+ */
+ readonly code: string;
+ }
+
+ /**
+ * Enumeration of file change types.
+ */
+ export enum FileChangeType {
+
+ /**
+ * The contents or metadata of a file have changed.
+ */
+ Changed = 1,
+
+ /**
+ * A file has been created.
+ */
+ Created = 2,
+
+ /**
+ * A file has been deleted.
+ */
+ Deleted = 3,
+ }
+
+ /**
+ * The event filesystem providers must use to signal a file change.
+ */
+ export interface FileChangeEvent {
+
+ /**
+ * The type of change.
+ */
+ readonly type: FileChangeType;
+
+ /**
+ * The uri of the file that has changed.
+ */
+ readonly uri: Uri;
+ }
+
+ /**
+ * The filesystem provider defines what the editor needs to read, write, discover,
+ * and to manage files and folders. It allows extensions to serve files from remote places,
+ * like ftp-servers, and to seamlessly integrate those into the editor.
+ *
+ * * *Note 1:* The filesystem provider API works with {@link Uri uris} and assumes hierarchical
+ * paths, e.g. `foo:/my/path` is a child of `foo:/my/` and a parent of `foo:/my/path/deeper`.
+ * * *Note 2:* There is an activation event `onFileSystem:` that fires when a file
+ * or folder is being accessed.
+ * * *Note 3:* The word 'file' is often used to denote all {@link FileType kinds} of files, e.g.
+ * folders, symbolic links, and regular files.
+ */
+ export interface FileSystemProvider {
+
+ /**
+ * An event to signal that a resource has been created, changed, or deleted. This
+ * event should fire for resources that are being {@link FileSystemProvider.watch watched}
+ * by clients of this provider.
+ *
+ * *Note:* It is important that the metadata of the file that changed provides an
+ * updated `mtime` that advanced from the previous value in the {@link FileStat stat} and a
+ * correct `size` value. Otherwise there may be optimizations in place that will not show
+ * the change in an editor for example.
+ */
+ readonly onDidChangeFile: Event;
+
+ /**
+ * Subscribe to events in the file or folder denoted by `uri`.
+ *
+ * The editor will call this function for files and folders. In the latter case, the
+ * options differ from defaults, e.g. what files/folders to exclude from watching
+ * and if subfolders, sub-subfolder, etc. should be watched (`recursive`).
+ *
+ * @param uri The uri of the file to be watched.
+ * @param options Configures the watch.
+ * @returns A disposable that tells the provider to stop watching the `uri`.
+ */
+ watch(uri: Uri, options: { recursive: boolean; excludes: string[] }): Disposable;
+
+ /**
+ * Retrieve metadata about a file.
+ *
+ * Note that the metadata for symbolic links should be the metadata of the file they refer to.
+ * Still, the {@link FileType.SymbolicLink SymbolicLink}-type must be used in addition to the actual type, e.g.
+ * `FileType.SymbolicLink | FileType.Directory`.
+ *
+ * @param uri The uri of the file to retrieve metadata about.
+ * @return The file metadata about the file.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist.
+ */
+ stat(uri: Uri): FileStat | Thenable;
+
+ /**
+ * Retrieve all entries of a {@link FileType.Directory directory}.
+ *
+ * @param uri The uri of the folder.
+ * @return An array of name/type-tuples or a thenable that resolves to such.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist.
+ */
+ readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]>;
+
+ /**
+ * Create a new directory (Note, that new files are created via `write`-calls).
+ *
+ * @param uri The uri of the new folder.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required.
+ * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists.
+ * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient.
+ */
+ createDirectory(uri: Uri): void | Thenable;
+
+ /**
+ * Read the entire contents of a file.
+ *
+ * @param uri The uri of the file.
+ * @return An array of bytes or a thenable that resolves to such.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist.
+ */
+ readFile(uri: Uri): Uint8Array | Thenable;
+
+ /**
+ * Write data to a file, replacing its entire contents.
+ *
+ * @param uri The uri of the file.
+ * @param content The new content of the file.
+ * @param options Defines if missing files should or must be created.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist and `create` is not set.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required.
+ * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists, `create` is set but `overwrite` is not set.
+ * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient.
+ */
+ writeFile(uri: Uri, content: Uint8Array, options: { create: boolean, overwrite: boolean }): void | Thenable;
+
+ /**
+ * Delete a file.
+ *
+ * @param uri The resource that is to be deleted.
+ * @param options Defines if deletion of folders is recursive.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist.
+ * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient.
+ */
+ delete(uri: Uri, options: { recursive: boolean }): void | Thenable;
+
+ /**
+ * Rename a file or folder.
+ *
+ * @param oldUri The existing file.
+ * @param newUri The new location.
+ * @param options Defines if existing files should be overwritten.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `oldUri` doesn't exist.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required.
+ * @throws {@link FileSystemError.FileExists `FileExists`} when `newUri` exists and when the `overwrite` option is not `true`.
+ * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient.
+ */
+ rename(oldUri: Uri, newUri: Uri, options: { overwrite: boolean }): void | Thenable;
+
+ /**
+ * Copy files or folders. Implementing this function is optional but it will speedup
+ * the copy operation.
+ *
+ * @param source The existing file.
+ * @param destination The destination location.
+ * @param options Defines if existing files should be overwritten.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `source` doesn't exist.
+ * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `destination` doesn't exist, e.g. no mkdirp-logic required.
+ * @throws {@link FileSystemError.FileExists `FileExists`} when `destination` exists and when the `overwrite` option is not `true`.
+ * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient.
+ */
+ copy?(source: Uri, destination: Uri, options: { overwrite: boolean }): void | Thenable;
+ }
+
+ /**
+ * The file system interface exposes the editor's built-in and contributed
+ * {@link FileSystemProvider file system providers}. It allows extensions to work
+ * with files from the local disk as well as files from remote places, like the
+ * remote extension host or ftp-servers.
+ *
+ * *Note* that an instance of this interface is available as {@link workspace.fs `workspace.fs`}.
+ */
+ export interface FileSystem {
+
+ /**
+ * Retrieve metadata about a file.
+ *
+ * @param uri The uri of the file to retrieve metadata about.
+ * @return The file metadata about the file.
+ */
+ stat(uri: Uri): Thenable;
+
+ /**
+ * Retrieve all entries of a {@link FileType.Directory directory}.
+ *
+ * @param uri The uri of the folder.
+ * @return An array of name/type-tuples or a thenable that resolves to such.
+ */
+ readDirectory(uri: Uri): Thenable<[string, FileType][]>;
+
+ /**
+ * Create a new directory (Note, that new files are created via `write`-calls).
+ *
+ * *Note* that missing directories are created automatically, e.g this call has
+ * `mkdirp` semantics.
+ *
+ * @param uri The uri of the new folder.
+ */
+ createDirectory(uri: Uri): Thenable;
+
+ /**
+ * Read the entire contents of a file.
+ *
+ * @param uri The uri of the file.
+ * @return An array of bytes or a thenable that resolves to such.
+ */
+ readFile(uri: Uri): Thenable;
+
+ /**
+ * Write data to a file, replacing its entire contents.
+ *
+ * @param uri The uri of the file.
+ * @param content The new content of the file.
+ */
+ writeFile(uri: Uri, content: Uint8Array): Thenable;
+
+ /**
+ * Delete a file.
+ *
+ * @param uri The resource that is to be deleted.
+ * @param options Defines if trash can should be used and if deletion of folders is recursive
+ */
+ delete(uri: Uri, options?: { recursive?: boolean, useTrash?: boolean }): Thenable;
+
+ /**
+ * Rename a file or folder.
+ *
+ * @param oldUri The existing file.
+ * @param newUri The new location.
+ * @param options Defines if existing files should be overwritten.
+ */
+ rename(source: Uri, target: Uri, options?: { overwrite?: boolean }): Thenable;
+
+ /**
+ * Copy files or folders.
+ *
+ * @param source The existing file.
+ * @param destination The destination location.
+ * @param options Defines if existing files should be overwritten.
+ */
+ copy(source: Uri, target: Uri, options?: { overwrite?: boolean }): Thenable;
+
+ /**
+ * Check if a given file system supports writing files.
+ *
+ * Keep in mind that just because a file system supports writing, that does
+ * not mean that writes will always succeed. There may be permissions issues
+ * or other errors that prevent writing a file.
+ *
+ * @param scheme The scheme of the filesystem, for example `file` or `git`.
+ *
+ * @return `true` if the file system supports writing, `false` if it does not
+ * support writing (i.e. it is readonly), and `undefined` if VS Code does not
+ * know about the filesystem.
+ */
+ isWritableFileSystem(scheme: string): boolean | undefined;
+ }
+
+ /**
+ * Defines a port mapping used for localhost inside the webview.
+ */
+ export interface WebviewPortMapping {
+ /**
+ * Localhost port to remap inside the webview.
+ */
+ readonly webviewPort: number;
+
+ /**
+ * Destination port. The `webviewPort` is resolved to this port.
+ */
+ readonly extensionHostPort: number;
+ }
+
+ /**
+ * Content settings for a webview.
+ */
+ export interface WebviewOptions {
+ /**
+ * Controls whether scripts are enabled in the webview content or not.
+ *
+ * Defaults to false (scripts-disabled).
+ */
+ readonly enableScripts?: boolean;
+
+ /**
+ * Controls whether command uris are enabled in webview content or not.
+ *
+ * Defaults to false.
+ */
+ readonly enableCommandUris?: boolean;
+
+ /**
+ * Root paths from which the webview can load local (filesystem) resources using uris from `asWebviewUri`
+ *
+ * Default to the root folders of the current workspace plus the extension's install directory.
+ *
+ * Pass in an empty array to disallow access to any local resources.
+ */
+ readonly localResourceRoots?: ReadonlyArray;
+
+ /**
+ * Mappings of localhost ports used inside the webview.
+ *
+ * Port mapping allow webviews to transparently define how localhost ports are resolved. This can be used
+ * to allow using a static localhost port inside the webview that is resolved to random port that a service is
+ * running on.
+ *
+ * If a webview accesses localhost content, we recommend that you specify port mappings even if
+ * the `webviewPort` and `extensionHostPort` ports are the same.
+ *
+ * *Note* that port mappings only work for `http` or `https` urls. Websocket urls (e.g. `ws://localhost:3000`)
+ * cannot be mapped to another port.
+ */
+ readonly portMapping?: ReadonlyArray;
+ }
+
+ /**
+ * Displays html content, similarly to an iframe.
+ */
+ export interface Webview {
+ /**
+ * Content settings for the webview.
+ */
+ options: WebviewOptions;
+
+ /**
+ * HTML contents of the webview.
+ *
+ * This should be a complete, valid html document. Changing this property causes the webview to be reloaded.
+ *
+ * Webviews are sandboxed from normal extension process, so all communication with the webview must use
+ * message passing. To send a message from the extension to the webview, use {@link Webview.postMessage `postMessage`}.
+ * To send message from the webview back to an extension, use the `acquireVsCodeApi` function inside the webview
+ * to get a handle to VS Code's api and then call `.postMessage()`:
+ *
+ * ```html
+ *
+ * ```
+ *
+ * To load a resources from the workspace inside a webview, use the `{@link Webview.asWebviewUri asWebviewUri}` method
+ * and ensure the resource's directory is listed in {@link WebviewOptions.localResourceRoots `WebviewOptions.localResourceRoots`}.
+ *
+ * Keep in mind that even though webviews are sandboxed, they still allow running scripts and loading arbitrary content,
+ * so extensions must follow all standard web security best practices when working with webviews. This includes
+ * properly sanitizing all untrusted input (including content from the workspace) and
+ * setting a [content security policy](https://aka.ms/vscode-api-webview-csp).
+ */
+ html: string;
+
+ /**
+ * Fired when the webview content posts a message.
+ *
+ * Webview content can post strings or json serializable objects back to a VS Code extension. They cannot
+ * post `Blob`, `File`, `ImageData` and other DOM specific objects since the extension that receives the
+ * message does not run in a browser environment.
+ */
+ readonly onDidReceiveMessage: Event;
+
+ /**
+ * Post a message to the webview content.
+ *
+ * Messages are only delivered if the webview is live (either visible or in the
+ * background with `retainContextWhenHidden`).
+ *
+ * @param message Body of the message. This must be a string or other json serializable object.
+ *
+ * For older versions of vscode, if an `ArrayBuffer` is included in `message`,
+ * it will not be serialized properly and will not be received by the webview.
+ * Similarly any TypedArrays, such as a `Uint8Array`, will be very inefficiently
+ * serialized and will also not be recreated as a typed array inside the webview.
+ *
+ * However if your extension targets vscode 1.57+ in the `engines` field of its
+ * `package.json`, any `ArrayBuffer` values that appear in `message` will be more
+ * efficiently transferred to the webview and will also be correctly recreated inside
+ * of the webview.
+ */
+ postMessage(message: any): Thenable;
+
+ /**
+ * Convert a uri for the local file system to one that can be used inside webviews.
+ *
+ * Webviews cannot directly load resources from the workspace or local file system using `file:` uris. The
+ * `asWebviewUri` function takes a local `file:` uri and converts it into a uri that can be used inside of
+ * a webview to load the same resource:
+ *
+ * ```ts
+ * webview.html = `)})
`
+ * ```
+ */
+ asWebviewUri(localResource: Uri): Uri;
+
+ /**
+ * Content security policy source for webview resources.
+ *
+ * This is the origin that should be used in a content security policy rule:
+ *
+ * ```
+ * img-src https: ${webview.cspSource} ...;
+ * ```
+ */
+ readonly cspSource: string;
+ }
+
+ /**
+ * Content settings for a webview panel.
+ */
+ export interface WebviewPanelOptions {
+ /**
+ * Controls if the find widget is enabled in the panel.
+ *
+ * Defaults to false.
+ */
+ readonly enableFindWidget?: boolean;
+
+ /**
+ * Controls if the webview panel's content (iframe) is kept around even when the panel
+ * is no longer visible.
+ *
+ * Normally the webview panel's html context is created when the panel becomes visible
+ * and destroyed when it is hidden. Extensions that have complex state
+ * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
+ * context around, even when the webview moves to a background tab. When a webview using
+ * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
+ * When the panel becomes visible again, the context is automatically restored
+ * in the exact same state it was in originally. You cannot send messages to a
+ * hidden webview, even with `retainContextWhenHidden` enabled.
+ *
+ * `retainContextWhenHidden` has a high memory overhead and should only be used if
+ * your panel's context cannot be quickly saved and restored.
+ */
+ readonly retainContextWhenHidden?: boolean;
+ }
+
+ /**
+ * A panel that contains a webview.
+ */
+ interface WebviewPanel {
+ /**
+ * Identifies the type of the webview panel, such as `'markdown.preview'`.
+ */
+ readonly viewType: string;
+
+ /**
+ * Title of the panel shown in UI.
+ */
+ title: string;
+
+ /**
+ * Icon for the panel shown in UI.
+ */
+ iconPath?: Uri | { light: Uri; dark: Uri };
+
+ /**
+ * {@link Webview `Webview`} belonging to the panel.
+ */
+ readonly webview: Webview;
+
+ /**
+ * Content settings for the webview panel.
+ */
+ readonly options: WebviewPanelOptions;
+
+ /**
+ * Editor position of the panel. This property is only set if the webview is in
+ * one of the editor view columns.
+ */
+ readonly viewColumn?: ViewColumn;
+
+ /**
+ * Whether the panel is active (focused by the user).
+ */
+ readonly active: boolean;
+
+ /**
+ * Whether the panel is visible.
+ */
+ readonly visible: boolean;
+
+ /**
+ * Fired when the panel's view state changes.
+ */
+ readonly onDidChangeViewState: Event;
+
+ /**
+ * Fired when the panel is disposed.
+ *
+ * This may be because the user closed the panel or because `.dispose()` was
+ * called on it.
+ *
+ * Trying to use the panel after it has been disposed throws an exception.
+ */
+ readonly onDidDispose: Event;
+
+ /**
+ * Show the webview panel in a given column.
+ *
+ * A webview panel may only show in a single column at a time. If it is already showing, this
+ * method moves it to a new column.
+ *
+ * @param viewColumn View column to show the panel in. Shows in the current `viewColumn` if undefined.
+ * @param preserveFocus When `true`, the webview will not take focus.
+ */
+ reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void;
+
+ /**
+ * Dispose of the webview panel.
+ *
+ * This closes the panel if it showing and disposes of the resources owned by the webview.
+ * Webview panels are also disposed when the user closes the webview panel. Both cases
+ * fire the `onDispose` event.
+ */
+ dispose(): any;
+ }
+
+ /**
+ * Event fired when a webview panel's view state changes.
+ */
+ export interface WebviewPanelOnDidChangeViewStateEvent {
+ /**
+ * Webview panel whose view state changed.
+ */
+ readonly webviewPanel: WebviewPanel;
+ }
+
+ /**
+ * Restore webview panels that have been persisted when vscode shuts down.
+ *
+ * There are two types of webview persistence:
+ *
+ * - Persistence within a session.
+ * - Persistence across sessions (across restarts of VS Code).
+ *
+ * A `WebviewPanelSerializer` is only required for the second case: persisting a webview across sessions.
+ *
+ * Persistence within a session allows a webview to save its state when it becomes hidden
+ * and restore its content from this state when it becomes visible again. It is powered entirely
+ * by the webview content itself. To save off a persisted state, call `acquireVsCodeApi().setState()` with
+ * any json serializable object. To restore the state again, call `getState()`
+ *
+ * ```js
+ * // Within the webview
+ * const vscode = acquireVsCodeApi();
+ *
+ * // Get existing state
+ * const oldState = vscode.getState() || { value: 0 };
+ *
+ * // Update state
+ * setState({ value: oldState.value + 1 })
+ * ```
+ *
+ * A `WebviewPanelSerializer` extends this persistence across restarts of VS Code. When the editor is shutdown,
+ * VS Code will save off the state from `setState` of all webviews that have a serializer. When the
+ * webview first becomes visible after the restart, this state is passed to `deserializeWebviewPanel`.
+ * The extension can then restore the old `WebviewPanel` from this state.
+ *
+ * @param T Type of the webview's state.
+ */
+ interface WebviewPanelSerializer {
+ /**
+ * Restore a webview panel from its serialized `state`.
+ *
+ * Called when a serialized webview first becomes visible.
+ *
+ * @param webviewPanel Webview panel to restore. The serializer should take ownership of this panel. The
+ * serializer must restore the webview's `.html` and hook up all webview events.
+ * @param state Persisted state from the webview content.
+ *
+ * @return Thenable indicating that the webview has been fully restored.
+ */
+ deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable;
+ }
+
+ /**
+ * A webview based view.
+ */
+ export interface WebviewView {
+ /**
+ * Identifies the type of the webview view, such as `'hexEditor.dataView'`.
+ */
+ readonly viewType: string;
+
+ /**
+ * The underlying webview for the view.
+ */
+ readonly webview: Webview;
+
+ /**
+ * View title displayed in the UI.
+ *
+ * The view title is initially taken from the extension `package.json` contribution.
+ */
+ title?: string;
+
+ /**
+ * Human-readable string which is rendered less prominently in the title.
+ */
+ description?: string;
+
+ /**
+ * Event fired when the view is disposed.
+ *
+ * Views are disposed when they are explicitly hidden by a user (this happens when a user
+ * right clicks in a view and unchecks the webview view).
+ *
+ * Trying to use the view after it has been disposed throws an exception.
+ */
+ readonly onDidDispose: Event;
+
+ /**
+ * Tracks if the webview is currently visible.
+ *
+ * Views are visible when they are on the screen and expanded.
+ */
+ readonly visible: boolean;
+
+ /**
+ * Event fired when the visibility of the view changes.
+ *
+ * Actions that trigger a visibility change:
+ *
+ * - The view is collapsed or expanded.
+ * - The user switches to a different view group in the sidebar or panel.
+ *
+ * Note that hiding a view using the context menu instead disposes of the view and fires `onDidDispose`.
+ */
+ readonly onDidChangeVisibility: Event;
+
+ /**
+ * Reveal the view in the UI.
+ *
+ * If the view is collapsed, this will expand it.
+ *
+ * @param preserveFocus When `true` the view will not take focus.
+ */
+ show(preserveFocus?: boolean): void;
+ }
+
+ /**
+ * Additional information the webview view being resolved.
+ *
+ * @param T Type of the webview's state.
+ */
+ interface WebviewViewResolveContext {
+ /**
+ * Persisted state from the webview content.
+ *
+ * To save resources, VS Code normally deallocates webview documents (the iframe content) that are not visible.
+ * For example, when the user collapse a view or switches to another top level activity in the sidebar, the
+ * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when
+ * the view becomes visible again.
+ *
+ * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this
+ * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to
+ * save off a webview's state so that it can be quickly recreated as needed.
+ *
+ * To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with
+ * any json serializable object. To restore the state again, call `getState()`. For example:
+ *
+ * ```js
+ * // Within the webview
+ * const vscode = acquireVsCodeApi();
+ *
+ * // Get existing state
+ * const oldState = vscode.getState() || { value: 0 };
+ *
+ * // Update state
+ * setState({ value: oldState.value + 1 })
+ * ```
+ *
+ * VS Code ensures that the persisted state is saved correctly when a webview is hidden and across
+ * editor restarts.
+ */
+ readonly state: T | undefined;
+ }
+
+ /**
+ * Provider for creating `WebviewView` elements.
+ */
+ export interface WebviewViewProvider {
+ /**
+ * Revolves a webview view.
+ *
+ * `resolveWebviewView` is called when a view first becomes visible. This may happen when the view is
+ * first loaded or when the user hides and then shows a view again.
+ *
+ * @param webviewView Webview view to restore. The provider should take ownership of this view. The
+ * provider must set the webview's `.html` and hook up all webview events it is interested in.
+ * @param context Additional metadata about the view being resolved.
+ * @param token Cancellation token indicating that the view being provided is no longer needed.
+ *
+ * @return Optional thenable indicating that the view has been fully resolved.
+ */
+ resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable | void;
+ }
+
+ /**
+ * Provider for text based custom editors.
+ *
+ * Text based custom editors use a {@link TextDocument `TextDocument`} as their data model. This considerably simplifies
+ * implementing a custom editor as it allows VS Code to handle many common operations such as
+ * undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`.
+ */
+ export interface CustomTextEditorProvider {
+
+ /**
+ * Resolve a custom editor for a given text resource.
+ *
+ * This is called when a user first opens a resource for a `CustomTextEditorProvider`, or if they reopen an
+ * existing editor using this `CustomTextEditorProvider`.
+ *
+ *
+ * @param document Document for the resource to resolve.
+ *
+ * @param webviewPanel The webview panel used to display the editor UI for this resource.
+ *
+ * During resolve, the provider must fill in the initial html for the content webview panel and hook up all
+ * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to
+ * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details.
+ *
+ * @param token A cancellation token that indicates the result is no longer needed.
+ *
+ * @return Thenable indicating that the custom editor has been resolved.
+ */
+ resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel, token: CancellationToken): Thenable | void;
+ }
+
+ /**
+ * Represents a custom document used by a {@link CustomEditorProvider `CustomEditorProvider`}.
+ *
+ * Custom documents are only used within a given `CustomEditorProvider`. The lifecycle of a `CustomDocument` is
+ * managed by VS Code. When no more references remain to a `CustomDocument`, it is disposed of.
+ */
+ interface CustomDocument {
+ /**
+ * The associated uri for this document.
+ */
+ readonly uri: Uri;
+
+ /**
+ * Dispose of the custom document.
+ *
+ * This is invoked by VS Code when there are no more references to a given `CustomDocument` (for example when
+ * all editors associated with the document have been closed.)
+ */
+ dispose(): void;
+ }
+
+ /**
+ * Event triggered by extensions to signal to VS Code that an edit has occurred on an {@link CustomDocument `CustomDocument`}.
+ *
+ * @see {@link CustomDocumentProvider.onDidChangeCustomDocument `CustomDocumentProvider.onDidChangeCustomDocument`}.
+ */
+ interface CustomDocumentEditEvent {
+
+ /**
+ * The document that the edit is for.
+ */
+ readonly document: T;
+
+ /**
+ * Undo the edit operation.
+ *
+ * This is invoked by VS Code when the user undoes this edit. To implement `undo`, your
+ * extension should restore the document and editor to the state they were in just before this
+ * edit was added to VS Code's internal edit stack by `onDidChangeCustomDocument`.
+ */
+ undo(): Thenable | void;
+
+ /**
+ * Redo the edit operation.
+ *
+ * This is invoked by VS Code when the user redoes this edit. To implement `redo`, your
+ * extension should restore the document and editor to the state they were in just after this
+ * edit was added to VS Code's internal edit stack by `onDidChangeCustomDocument`.
+ */
+ redo(): Thenable | void;
+
+ /**
+ * Display name describing the edit.
+ *
+ * This will be shown to users in the UI for undo/redo operations.
+ */
+ readonly label?: string;
+ }
+
+ /**
+ * Event triggered by extensions to signal to VS Code that the content of a {@link CustomDocument `CustomDocument`}
+ * has changed.
+ *
+ * @see {@link CustomDocumentProvider.onDidChangeCustomDocument `CustomDocumentProvider.onDidChangeCustomDocument`}.
+ */
+ interface CustomDocumentContentChangeEvent {
+ /**
+ * The document that the change is for.
+ */
+ readonly document: T;
+ }
+
+ /**
+ * A backup for an {@link CustomDocument `CustomDocument`}.
+ */
+ interface CustomDocumentBackup {
+ /**
+ * Unique identifier for the backup.
+ *
+ * This id is passed back to your extension in `openCustomDocument` when opening a custom editor from a backup.
+ */
+ readonly id: string;
+
+ /**
+ * Delete the current backup.
+ *
+ * This is called by VS Code when it is clear the current backup is no longer needed, such as when a new backup
+ * is made or when the file is saved.
+ */
+ delete(): void;
+ }
+
+ /**
+ * Additional information used to implement {@link CustomEditableDocument.backup `CustomEditableDocument.backup`}.
+ */
+ interface CustomDocumentBackupContext {
+ /**
+ * Suggested file location to write the new backup.
+ *
+ * Note that your extension is free to ignore this and use its own strategy for backup.
+ *
+ * If the editor is for a resource from the current workspace, `destination` will point to a file inside
+ * `ExtensionContext.storagePath`. The parent folder of `destination` may not exist, so make sure to created it
+ * before writing the backup to this location.
+ */
+ readonly destination: Uri;
+ }
+
+ /**
+ * Additional information about the opening custom document.
+ */
+ interface CustomDocumentOpenContext {
+ /**
+ * The id of the backup to restore the document from or `undefined` if there is no backup.
+ *
+ * If this is provided, your extension should restore the editor from the backup instead of reading the file
+ * from the user's workspace.
+ */
+ readonly backupId?: string;
+
+ /**
+ * If the URI is an untitled file, this will be populated with the byte data of that file
+ *
+ * If this is provided, your extension should utilize this byte data rather than executing fs APIs on the URI passed in
+ */
+ readonly untitledDocumentData?: Uint8Array;
+ }
+
+ /**
+ * Provider for readonly custom editors that use a custom document model.
+ *
+ * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}.
+ *
+ * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple
+ * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead.
+ *
+ * @param T Type of the custom document returned by this provider.
+ */
+ export interface CustomReadonlyEditorProvider {
+
+ /**
+ * Create a new document for a given resource.
+ *
+ * `openCustomDocument` is called when the first time an editor for a given resource is opened. The opened
+ * document is then passed to `resolveCustomEditor` so that the editor can be shown to the user.
+ *
+ * Already opened `CustomDocument` are re-used if the user opened additional editors. When all editors for a
+ * given resource are closed, the `CustomDocument` is disposed of. Opening an editor at this point will
+ * trigger another call to `openCustomDocument`.
+ *
+ * @param uri Uri of the document to open.
+ * @param openContext Additional information about the opening custom document.
+ * @param token A cancellation token that indicates the result is no longer needed.
+ *
+ * @return The custom document.
+ */
+ openCustomDocument(uri: Uri, openContext: CustomDocumentOpenContext, token: CancellationToken): Thenable | T;
+
+ /**
+ * Resolve a custom editor for a given resource.
+ *
+ * This is called whenever the user opens a new editor for this `CustomEditorProvider`.
+ *
+ * @param document Document for the resource being resolved.
+ *
+ * @param webviewPanel The webview panel used to display the editor UI for this resource.
+ *
+ * During resolve, the provider must fill in the initial html for the content webview panel and hook up all
+ * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to
+ * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details.
+ *
+ * @param token A cancellation token that indicates the result is no longer needed.
+ *
+ * @return Optional thenable indicating that the custom editor has been resolved.
+ */
+ resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): Thenable | void;
+ }
+
+ /**
+ * Provider for editable custom editors that use a custom document model.
+ *
+ * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}.
+ * This gives extensions full control over actions such as edit, save, and backup.
+ *
+ * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple
+ * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead.
+ *
+ * @param T Type of the custom document returned by this provider.
+ */
+ export interface CustomEditorProvider extends CustomReadonlyEditorProvider {
+ /**
+ * Signal that an edit has occurred inside a custom editor.
+ *
+ * This event must be fired by your extension whenever an edit happens in a custom editor. An edit can be
+ * anything from changing some text, to cropping an image, to reordering a list. Your extension is free to
+ * define what an edit is and what data is stored on each edit.
+ *
+ * Firing `onDidChange` causes VS Code to mark the editors as being dirty. This is cleared when the user either
+ * saves or reverts the file.
+ *
+ * Editors that support undo/redo must fire a `CustomDocumentEditEvent` whenever an edit happens. This allows
+ * users to undo and redo the edit using VS Code's standard VS Code keyboard shortcuts. VS Code will also mark
+ * the editor as no longer being dirty if the user undoes all edits to the last saved state.
+ *
+ * Editors that support editing but cannot use VS Code's standard undo/redo mechanism must fire a `CustomDocumentContentChangeEvent`.
+ * The only way for a user to clear the dirty state of an editor that does not support undo/redo is to either
+ * `save` or `revert` the file.
+ *
+ * An editor should only ever fire `CustomDocumentEditEvent` events, or only ever fire `CustomDocumentContentChangeEvent` events.
+ */
+ readonly onDidChangeCustomDocument: Event> | Event>;
+
+ /**
+ * Save a custom document.
+ *
+ * This method is invoked by VS Code when the user saves a custom editor. This can happen when the user
+ * triggers save while the custom editor is active, by commands such as `save all`, or by auto save if enabled.
+ *
+ * To implement `save`, the implementer must persist the custom editor. This usually means writing the
+ * file data for the custom document to disk. After `save` completes, any associated editor instances will
+ * no longer be marked as dirty.
+ *
+ * @param document Document to save.
+ * @param cancellation Token that signals the save is no longer required (for example, if another save was triggered).
+ *
+ * @return Thenable signaling that saving has completed.
+ */
+ saveCustomDocument(document: T, cancellation: CancellationToken): Thenable;
+
+ /**
+ * Save a custom document to a different location.
+ *
+ * This method is invoked by VS Code when the user triggers 'save as' on a custom editor. The implementer must
+ * persist the custom editor to `destination`.
+ *
+ * When the user accepts save as, the current editor is be replaced by an non-dirty editor for the newly saved file.
+ *
+ * @param document Document to save.
+ * @param destination Location to save to.
+ * @param cancellation Token that signals the save is no longer required.
+ *
+ * @return Thenable signaling that saving has completed.
+ */
+ saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable;
+
+ /**
+ * Revert a custom document to its last saved state.
+ *
+ * This method is invoked by VS Code when the user triggers `File: Revert File` in a custom editor. (Note that
+ * this is only used using VS Code's `File: Revert File` command and not on a `git revert` of the file).
+ *
+ * To implement `revert`, the implementer must make sure all editor instances (webviews) for `document`
+ * are displaying the document in the same state is saved in. This usually means reloading the file from the
+ * workspace.
+ *
+ * @param document Document to revert.
+ * @param cancellation Token that signals the revert is no longer required.
+ *
+ * @return Thenable signaling that the change has completed.
+ */
+ revertCustomDocument(document: T, cancellation: CancellationToken): Thenable;
+
+ /**
+ * Back up a dirty custom document.
+ *
+ * Backups are used for hot exit and to prevent data loss. Your `backup` method should persist the resource in
+ * its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in
+ * the `ExtensionContext.storagePath`. When VS Code reloads and your custom editor is opened for a resource,
+ * your extension should first check to see if any backups exist for the resource. If there is a backup, your
+ * extension should load the file contents from there instead of from the resource in the workspace.
+ *
+ * `backup` is triggered approximately one second after the user stops editing the document. If the user
+ * rapidly edits the document, `backup` will not be invoked until the editing stops.
+ *
+ * `backup` is not invoked when `auto save` is enabled (since auto save already persists the resource).
+ *
+ * @param document Document to backup.
+ * @param context Information that can be used to backup the document.
+ * @param cancellation Token that signals the current backup since a new backup is coming in. It is up to your
+ * extension to decided how to respond to cancellation. If for example your extension is backing up a large file
+ * in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather
+ * than cancelling it to ensure that VS Code has some valid backup.
+ */
+ backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable;
+ }
+
+ /**
+ * The clipboard provides read and write access to the system's clipboard.
+ */
+ export interface Clipboard {
+
+ /**
+ * Read the current clipboard contents as text.
+ * @returns A thenable that resolves to a string.
+ */
+ readText(): Thenable;
+
+ /**
+ * Writes text into the clipboard.
+ * @returns A thenable that resolves when writing happened.
+ */
+ writeText(value: string): Thenable;
+ }
+
+ /**
+ * Possible kinds of UI that can use extensions.
+ */
+ export enum UIKind {
+
+ /**
+ * Extensions are accessed from a desktop application.
+ */
+ Desktop = 1,
+
+ /**
+ * Extensions are accessed from a web browser.
+ */
+ Web = 2
+ }
+
+ /**
+ * Namespace describing the environment the editor runs in.
+ */
+ export namespace env {
+
+ /**
+ * The application name of the editor, like 'VS Code'.
+ */
+ export const appName: string;
+
+ /**
+ * The application root folder from which the editor is running.
+ *
+ * *Note* that the value is the empty string when running in an
+ * environment that has no representation of an application root folder.
+ */
+ export const appRoot: string;
+
+ /**
+ * The custom uri scheme the editor registers to in the operating system.
+ */
+ export const uriScheme: string;
+
+ /**
+ * Represents the preferred user-language, like `de-CH`, `fr`, or `en-US`.
+ */
+ export const language: string;
+
+ /**
+ * The system clipboard.
+ */
+ export const clipboard: Clipboard;
+
+ /**
+ * A unique identifier for the computer.
+ */
+ export const machineId: string;
+
+ /**
+ * A unique identifier for the current session.
+ * Changes each time the editor is started.
+ */
+ export const sessionId: string;
+
+ /**
+ * Indicates that this is a fresh install of the application.
+ * `true` if within the first day of installation otherwise `false`.
+ */
+ export const isNewAppInstall: boolean;
+
+ /**
+ * Indicates whether the users has telemetry enabled.
+ * Can be observed to determine if the extension should send telemetry.
+ */
+ export const isTelemetryEnabled: boolean;
+
+ /**
+ * An {@link Event} which fires when the user enabled or disables telemetry.
+ * `true` if the user has enabled telemetry or `false` if the user has disabled telemetry.
+ */
+ export const onDidChangeTelemetryEnabled: Event;
+
+ /**
+ * The name of a remote. Defined by extensions, popular samples are `wsl` for the Windows
+ * Subsystem for Linux or `ssh-remote` for remotes using a secure shell.
+ *
+ * *Note* that the value is `undefined` when there is no remote extension host but that the
+ * value is defined in all extension hosts (local and remote) in case a remote extension host
+ * exists. Use {@link Extension.extensionKind} to know if
+ * a specific extension runs remote or not.
+ */
+ export const remoteName: string | undefined;
+
+ /**
+ * The detected default shell for the extension host, this is overridden by the
+ * `terminal.integrated.shell` setting for the extension host's platform. Note that in
+ * environments that do not support a shell the value is the empty string.
+ */
+ export const shell: string;
+
+ /**
+ * The UI kind property indicates from which UI extensions
+ * are accessed from. For example, extensions could be accessed
+ * from a desktop application or a web browser.
+ */
+ export const uiKind: UIKind;
+
+ /**
+ * Opens a link externally using the default application. Depending on the
+ * used scheme this can be:
+ * * a browser (`http:`, `https:`)
+ * * a mail client (`mailto:`)
+ * * VSCode itself (`vscode:` from `vscode.env.uriScheme`)
+ *
+ * *Note* that {@link window.showTextDocument `showTextDocument`} is the right
+ * way to open a text document inside the editor, not this function.
+ *
+ * @param target The uri that should be opened.
+ * @returns A promise indicating if open was successful.
+ */
+ export function openExternal(target: Uri): Thenable;
+
+ /**
+ * Resolves a uri to form that is accessible externally. Currently only supports `https:`, `http:` and
+ * `vscode.env.uriScheme` uris.
+ *
+ * #### `http:` or `https:` scheme
+ *
+ * Resolves an *external* uri, such as a `http:` or `https:` link, from where the extension is running to a
+ * uri to the same resource on the client machine.
+ *
+ * This is a no-op if the extension is running on the client machine.
+ *
+ * If the extension is running remotely, this function automatically establishes a port forwarding tunnel
+ * from the local machine to `target` on the remote and returns a local uri to the tunnel. The lifetime of
+ * the port forwarding tunnel is managed by VS Code and the tunnel can be closed by the user.
+ *
+ * *Note* that uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri` on them.
+ *
+ * #### `vscode.env.uriScheme`
+ *
+ * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered {@link UriHandler}
+ * to trigger.
+ *
+ * Extensions should not make any assumptions about the resulting uri and should not alter it in anyway.
+ * Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query
+ * argument to the server to authenticate to.
+ *
+ * *Note* that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it
+ * will appear in the uri that is passed to the {@link UriHandler}.
+ *
+ * **Example** of an authentication flow:
+ * ```typescript
+ * vscode.window.registerUriHandler({
+ * handleUri(uri: vscode.Uri): vscode.ProviderResult {
+ * if (uri.path === '/did-authenticate') {
+ * console.log(uri.toString());
+ * }
+ * }
+ * });
+ *
+ * const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(`${vscode.env.uriScheme}://my.extension/did-authenticate`));
+ * await vscode.env.openExternal(callableUri);
+ * ```
+ *
+ * *Note* that extensions should not cache the result of `asExternalUri` as the resolved uri may become invalid due to
+ * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by
+ * `asExternalUri`.
+ *
+ * @return A uri that can be used on the client machine.
+ */
+ export function asExternalUri(target: Uri): Thenable;
+ }
+
+ /**
+ * 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 {@link commands.registerCommand registerCommand}
+ * and {@link commands.registerTextEditorCommand registerTextEditorCommand} functions. Commands
+ * can be executed {@link commands.executeCommand 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](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
+ * * keybinding - Use the `keybindings`-section in `package.json` to enable
+ * [keybindings](https://code.visualstudio.com/docs/getstarted/keybindings#_customizing-shortcuts)
+ * 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 identifier `extension.sayHello`.
+ * ```javascript
+ * commands.registerCommand('extension.sayHello', () => {
+ * window.showInformationMessage('Hello World!');
+ * });
+ * ```
+ * Second, bind the command identifier to a title under which it will show in the palette (`package.json`).
+ * ```json
+ * {
+ * "contributes": {
+ * "commands": [{
+ * "command": "extension.sayHello",
+ * "title": "Hello World"
+ * }]
+ * }
+ * }
+ * ```
+ */
+ export namespace commands {
+
+ /**
+ * 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.
+ *
+ * @param command A unique identifier for the command.
+ * @param callback A command handler function.
+ * @param thisArg The `this` context used when invoking the handler function.
+ * @return Disposable which unregisters this command on disposal.
+ */
+ export function registerCommand(command: string, callback: (...args: any[]) => any, 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 {@link commands.registerCommand 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
+ * {@link TextEditorEdit edit}-builder. Note that the edit-builder is only valid while the
+ * callback executes.
+ *
+ * @param command A unique identifier for the command.
+ * @param callback A command handler function with access to an {@link TextEditor editor} and an {@link TextEditorEdit edit}.
+ * @param thisArg The `this` context used when invoking the handler function.
+ * @return Disposable which unregisters this command on disposal.
+ */
+ export function registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit, ...args: any[]) => void, thisArg?: any): Disposable;
+
+ /**
+ * Executes the command denoted by the given command identifier.
+ *
+ * * *Note 1:* 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 {@link Position `Position`}, {@link Range `Range`}, {@link Uri `Uri`} and {@link Location `Location`}.
+ * * *Note 2:* There are no restrictions when executing commands that have been contributed
+ * by extensions.
+ *
+ * @param command Identifier of the command to execute.
+ * @param rest Parameters passed to the command function.
+ * @return A thenable that resolves to the returned value of the given command. `undefined` when
+ * the command handler function doesn't return anything.
+ */
+ export function executeCommand(command: string, ...rest: any[]): Thenable;
+
+ /**
+ * Retrieve the list of all available commands. Commands starting with an underscore are
+ * treated as internal commands.
+ *
+ * @param filterInternal Set `true` to not see internal commands (starting with an underscore)
+ * @return Thenable that resolves to a list of command ids.
+ */
+ export function getCommands(filterInternal?: boolean): Thenable;
+ }
+
+ /**
+ * Represents the state of a window.
+ */
+ export interface WindowState {
+
+ /**
+ * Whether the current window is focused.
+ */
+ readonly focused: boolean;
+ }
+
+ /**
+ * A uri handler is responsible for handling system-wide {@link Uri uris}.
+ *
+ * @see {@link window.registerUriHandler}.
+ */
+ export interface UriHandler {
+
+ /**
+ * Handle the provided system-wide {@link Uri}.
+ *
+ * @see {@link window.registerUriHandler}.
+ */
+ handleUri(uri: Uri): ProviderResult;
+ }
+
+ /**
+ * 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.
+ */
+ export namespace window {
+
+ /**
+ * 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.
+ */
+ export let activeTextEditor: TextEditor | undefined;
+
+ /**
+ * The currently visible editors or an empty array.
+ */
+ export let visibleTextEditors: TextEditor[];
+
+ /**
+ * An {@link Event} which fires when the {@link window.activeTextEditor active editor}
+ * has changed. *Note* that the event also fires when the active editor changes
+ * to `undefined`.
+ */
+ export const onDidChangeActiveTextEditor: Event;
+
+ /**
+ * An {@link Event} which fires when the array of {@link window.visibleTextEditors visible editors}
+ * has changed.
+ */
+ export const onDidChangeVisibleTextEditors: Event;
+
+ /**
+ * An {@link Event} which fires when the selection in an editor has changed.
+ */
+ export const onDidChangeTextEditorSelection: Event;
+
+ /**
+ * An {@link Event} which fires when the visible ranges of an editor has changed.
+ */
+ export const onDidChangeTextEditorVisibleRanges: Event;
+
+ /**
+ * An {@link Event} which fires when the options of an editor have changed.
+ */
+ export const onDidChangeTextEditorOptions: Event;
+
+ /**
+ * An {@link Event} which fires when the view column of an editor has changed.
+ */
+ export const onDidChangeTextEditorViewColumn: Event;
+
+ /**
+ * The currently opened terminals or an empty array.
+ */
+ export const terminals: ReadonlyArray;
+
+ /**
+ * The currently active terminal or `undefined`. The active terminal is the one that
+ * currently has focus or most recently had focus.
+ */
+ export const activeTerminal: Terminal | undefined;
+
+ /**
+ * An {@link Event} which fires when the {@link window.activeTerminal active terminal}
+ * has changed. *Note* that the event also fires when the active terminal changes
+ * to `undefined`.
+ */
+ export const onDidChangeActiveTerminal: Event;
+
+ /**
+ * An {@link Event} which fires when a terminal has been created, either through the
+ * {@link window.createTerminal createTerminal} API or commands.
+ */
+ export const onDidOpenTerminal: Event;
+
+ /**
+ * An {@link Event} which fires when a terminal is disposed.
+ */
+ export const onDidCloseTerminal: Event;
+
+ /**
+ * Represents the current window's state.
+ */
+ export const state: WindowState;
+
+ /**
+ * An {@link Event} which fires when the focus state of the current window
+ * changes. The value of the event represents whether the window is focused.
+ */
+ export const onDidChangeWindowState: Event;
+
+ /**
+ * Show the given document in a text editor. A {@link ViewColumn column} can be provided
+ * to control where the editor is being shown. Might change the {@link window.activeTextEditor active editor}.
+ *
+ * @param document A text document to be shown.
+ * @param column A view column in which the {@link TextEditor editor} should be shown. The default is the {@link ViewColumn.Active active}, other values
+ * are adjusted to be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`}
+ * to open the editor to the side of the currently active one.
+ * @param preserveFocus When `true` the editor will not take focus.
+ * @return A promise that resolves to an {@link TextEditor editor}.
+ */
+ export function showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable;
+
+ /**
+ * Show the given document in a text editor. {@link TextDocumentShowOptions Options} can be provided
+ * to control options of the editor is being shown. Might change the {@link window.activeTextEditor active editor}.
+ *
+ * @param document A text document to be shown.
+ * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}.
+ * @return A promise that resolves to an {@link TextEditor editor}.
+ */
+ export function showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable;
+
+ /**
+ * A short-hand for `openTextDocument(uri).then(document => showTextDocument(document, options))`.
+ *
+ * @see {@link openTextDocument}
+ *
+ * @param uri A resource identifier.
+ * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}.
+ * @return A promise that resolves to an {@link TextEditor editor}.
+ */
+ export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable;
+
+ /**
+ * Create a TextEditorDecorationType that can be used to add decorations to text editors.
+ *
+ * @param options Rendering options for the decoration type.
+ * @return A new decoration type instance.
+ */
+ export function createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType;
+
+ /**
+ * Show an information message to users. Optionally provide an array of items which will be presented as
+ * clickable buttons.
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showInformationMessage(message: string, ...items: string[]): Thenable;
+
+ /**
+ * Show an information message to users. Optionally provide an array of items which will be presented as
+ * clickable buttons.
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showInformationMessage(message: string, options: MessageOptions, ...items: string[]): Thenable;
+
+ /**
+ * Show an information message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showInformationMessage(message: string, ...items: T[]): Thenable;
+
+ /**
+ * Show an information message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showInformationMessage(message: string, options: MessageOptions, ...items: T[]): Thenable;
+
+ /**
+ * Show a warning message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showWarningMessage(message: string, ...items: string[]): Thenable;
+
+ /**
+ * Show a warning message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable;
+
+ /**
+ * Show a warning message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showWarningMessage(message: string, ...items: T[]): Thenable;
+
+ /**
+ * Show a warning message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showWarningMessage(message: string, options: MessageOptions, ...items: T[]): Thenable;
+
+ /**
+ * Show an error message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showErrorMessage(message: string, ...items: string[]): Thenable;
+
+ /**
+ * Show an error message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable;
+
+ /**
+ * Show an error message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showErrorMessage(message: string, ...items: T[]): Thenable;
+
+ /**
+ * Show an error message.
+ *
+ * @see {@link window.showInformationMessage showInformationMessage}
+ *
+ * @param message The message to show.
+ * @param options Configures the behaviour of the message.
+ * @param items A set of items that will be rendered as actions in the message.
+ * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
+ */
+ export function showErrorMessage(message: string, options: MessageOptions, ...items: T[]): Thenable;
+
+ /**
+ * Shows a selection list allowing multiple selections.
+ *
+ * @param items An array of strings, or a promise that resolves to an array of strings.
+ * @param options Configures the behavior of the selection list.
+ * @param token A token that can be used to signal cancellation.
+ * @return A promise that resolves to the selected items or `undefined`.
+ */
+ export function showQuickPick(items: string[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable;
+
+ /**
+ * Shows a selection list.
+ *
+ * @param items An array of strings, or a promise that resolves to an array of strings.
+ * @param options Configures the behavior of the selection list.
+ * @param token A token that can be used to signal cancellation.
+ * @return A promise that resolves to the selection or `undefined`.
+ */
+ export function showQuickPick(items: string[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable;
+
+ /**
+ * Shows a selection list allowing multiple selections.
+ *
+ * @param items An array of items, or a promise that resolves to an array of items.
+ * @param options Configures the behavior of the selection list.
+ * @param token A token that can be used to signal cancellation.
+ * @return A promise that resolves to the selected items or `undefined`.
+ */
+ export function showQuickPick(items: T[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable;
+
+ /**
+ * Shows a selection list.
+ *
+ * @param items An array of items, or a promise that resolves to an array of items.
+ * @param options Configures the behavior of the selection list.
+ * @param token A token that can be used to signal cancellation.
+ * @return A promise that resolves to the selected item or `undefined`.
+ */
+ export function showQuickPick(items: T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable;
+
+ /**
+ * Shows a selection list of {@link workspace.workspaceFolders workspace folders} to pick from.
+ * Returns `undefined` if no folder is open.
+ *
+ * @param options Configures the behavior of the workspace folder list.
+ * @return A promise that resolves to the workspace folder or `undefined`.
+ */
+ export function showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable;
+
+ /**
+ * Shows a file open dialog to the user which allows to select a file
+ * for opening-purposes.
+ *
+ * @param options Options that control the dialog.
+ * @returns A promise that resolves to the selected resources or `undefined`.
+ */
+ export function showOpenDialog(options?: OpenDialogOptions): Thenable;
+
+ /**
+ * Shows a file save dialog to the user which allows to select a file
+ * for saving-purposes.
+ *
+ * @param options Options that control the dialog.
+ * @returns A promise that resolves to the selected resource or `undefined`.
+ */
+ export function showSaveDialog(options?: SaveDialogOptions): Thenable;
+
+ /**
+ * 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.
+ *
+ * @param options Configures the behavior of the input box.
+ * @param token A token that can be used to signal cancellation.
+ * @return A promise that resolves to a string the user provided or to `undefined` in case of dismissal.
+ */
+ export function showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable;
+
+ /**
+ * Creates a {@link QuickPick} to let the user pick an item from a list
+ * of items of type T.
+ *
+ * Note that in many cases the more convenient {@link window.showQuickPick}
+ * is easier to use. {@link window.createQuickPick} should be used
+ * when {@link window.showQuickPick} does not offer the required flexibility.
+ *
+ * @return A new {@link QuickPick}.
+ */
+ export function createQuickPick(): QuickPick;
+
+ /**
+ * Creates a {@link InputBox} to let the user enter some text input.
+ *
+ * Note that in many cases the more convenient {@link window.showInputBox}
+ * is easier to use. {@link window.createInputBox} should be used
+ * when {@link window.showInputBox} does not offer the required flexibility.
+ *
+ * @return A new {@link InputBox}.
+ */
+ export function createInputBox(): InputBox;
+
+ /**
+ * Creates a new {@link OutputChannel output channel} with the given name.
+ *
+ * @param name Human-readable string which will be used to represent the channel in the UI.
+ */
+ export function createOutputChannel(name: string): OutputChannel;
+
+ /**
+ * Create and show a new webview panel.
+ *
+ * @param viewType Identifies the type of the webview panel.
+ * @param title Title of the panel.
+ * @param showOptions Where to show the webview in the editor. If preserveFocus is set, the new webview will not take focus.
+ * @param options Settings for the new panel.
+ *
+ * @return New webview panel.
+ */
+ export function createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | { viewColumn: ViewColumn, preserveFocus?: boolean }, options?: WebviewPanelOptions & WebviewOptions): WebviewPanel;
+
+ /**
+ * Set a message to the status bar. This is a short hand for the more powerful
+ * status bar {@link window.createStatusBarItem items}.
+ *
+ * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}.
+ * @param hideAfterTimeout Timeout in milliseconds after which the message will be disposed.
+ * @return A disposable which hides the status bar message.
+ */
+ export function setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable;
+
+ /**
+ * Set a message to the status bar. This is a short hand for the more powerful
+ * status bar {@link window.createStatusBarItem items}.
+ *
+ * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}.
+ * @param hideWhenDone Thenable on which completion (resolve or reject) the message will be disposed.
+ * @return A disposable which hides the status bar message.
+ */
+ export function setStatusBarMessage(text: string, hideWhenDone: Thenable): Disposable;
+
+ /**
+ * Set a message to the status bar. This is a short hand for the more powerful
+ * status bar {@link window.createStatusBarItem items}.
+ *
+ * *Note* that status bar messages stack and that they must be disposed when no
+ * longer used.
+ *
+ * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}.
+ * @return A disposable which hides the status bar message.
+ */
+ export function setStatusBarMessage(text: string): Disposable;
+
+ /**
+ * Show progress in the Source Control viewlet while running the given callback and while
+ * its returned promise isn't resolve or rejected.
+ *
+ * @deprecated Use `withProgress` instead.
+ *
+ * @param task A callback returning a promise. Progress increments can be reported with
+ * the provided {@link Progress}-object.
+ * @return The thenable the task did return.
+ */
+ export function withScmProgress(task: (progress: Progress) => Thenable): Thenable;
+
+ /**
+ * Show progress in the editor. Progress is shown while running the given callback
+ * and while the promise it returned isn't resolved nor rejected. The location at which
+ * progress should show (and other details) is defined via the passed {@link ProgressOptions `ProgressOptions`}.
+ *
+ * @param task A callback returning a promise. Progress state can be reported with
+ * the provided {@link Progress}-object.
+ *
+ * To report discrete progress, use `increment` to indicate how much work has been completed. Each call with
+ * a `increment` value will be summed up and reflected as overall progress until 100% is reached (a value of
+ * e.g. `10` accounts for `10%` of work done).
+ * Note that currently only `ProgressLocation.Notification` is capable of showing discrete progress.
+ *
+ * To monitor if the operation has been cancelled by the user, use the provided {@link CancellationToken `CancellationToken`}.
+ * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the
+ * long running operation.
+ *
+ * @return The thenable the task-callback returned.
+ */
+ export function withProgress(options: ProgressOptions, task: (progress: Progress<{ message?: string; increment?: number }>, token: CancellationToken) => Thenable): Thenable;
+
+ /**
+ * Creates a status bar {@link StatusBarItem item}.
+ *
+ * @param alignment The alignment of the item.
+ * @param priority The priority of the item. Higher values mean the item should be shown more to the left.
+ * @return A new status bar item.
+ */
+ export function createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem;
+
+ /**
+ * Creates a {@link Terminal} with a backing shell process. The cwd of the terminal will be the workspace
+ * directory if it exists.
+ *
+ * @param name Optional human-readable string which will be used to represent the terminal in the UI.
+ * @param shellPath Optional path to a custom shell executable to be used in the terminal.
+ * @param shellArgs Optional args for the custom shell executable. A string can be used on Windows only which
+ * allows specifying shell args in
+ * [command-line format](https://msdn.microsoft.com/en-au/08dfcab2-eb6e-49a4-80eb-87d4076c98c6).
+ * @return A new Terminal.
+ * @throws When running in an environment where a new process cannot be started.
+ */
+ export function createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | string): Terminal;
+
+ /**
+ * Creates a {@link Terminal} with a backing shell process.
+ *
+ * @param options A TerminalOptions object describing the characteristics of the new terminal.
+ * @return A new Terminal.
+ * @throws When running in an environment where a new process cannot be started.
+ */
+ export function createTerminal(options: TerminalOptions): Terminal;
+
+ /**
+ * Creates a {@link Terminal} where an extension controls its input and output.
+ *
+ * @param options An {@link ExtensionTerminalOptions} object describing
+ * the characteristics of the new terminal.
+ * @return A new Terminal.
+ */
+ export function createTerminal(options: ExtensionTerminalOptions): Terminal;
+
+ /**
+ * Register a {@link TreeDataProvider} for the view contributed using the extension point `views`.
+ * This will allow you to contribute data to the {@link TreeView} and update if the data changes.
+ *
+ * **Note:** To get access to the {@link TreeView} and perform operations on it, use {@link window.createTreeView createTreeView}.
+ *
+ * @param viewId Id of the view contributed using the extension point `views`.
+ * @param treeDataProvider A {@link TreeDataProvider} that provides tree data for the view
+ */
+ export function registerTreeDataProvider(viewId: string, treeDataProvider: TreeDataProvider): Disposable;
+
+ /**
+ * Create a {@link TreeView} for the view contributed using the extension point `views`.
+ * @param viewId Id of the view contributed using the extension point `views`.
+ * @param options Options for creating the {@link TreeView}
+ * @returns a {@link TreeView}.
+ */
+ export function createTreeView(viewId: string, options: TreeViewOptions): TreeView;
+
+ /**
+ * Registers a {@link UriHandler uri handler} capable of handling system-wide {@link Uri uris}.
+ * In case there are multiple windows open, the topmost window will handle the uri.
+ * A uri handler is scoped to the extension it is contributed from; it will only
+ * be able to handle uris which are directed to the extension itself. A uri must respect
+ * the following rules:
+ *
+ * - The uri-scheme must be `vscode.env.uriScheme`;
+ * - The uri-authority must be the extension id (e.g. `my.extension`);
+ * - The uri-path, -query and -fragment parts are arbitrary.
+ *
+ * For example, if the `my.extension` extension registers a uri handler, it will only
+ * be allowed to handle uris with the prefix `product-name://my.extension`.
+ *
+ * An extension can only register a single uri handler in its entire activation lifetime.
+ *
+ * * *Note:* There is an activation event `onUri` that fires when a uri directed for
+ * the current extension is about to be handled.
+ *
+ * @param handler The uri handler to register for this extension.
+ */
+ export function registerUriHandler(handler: UriHandler): Disposable;
+
+ /**
+ * Registers a webview panel serializer.
+ *
+ * Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation event and
+ * make sure that {@link registerWebviewPanelSerializer} is called during activation.
+ *
+ * Only a single serializer may be registered at a time for a given `viewType`.
+ *
+ * @param viewType Type of the webview panel that can be serialized.
+ * @param serializer Webview serializer.
+ */
+ export function registerWebviewPanelSerializer(viewType: string, serializer: WebviewPanelSerializer): Disposable;
+
+ /**
+ * Register a new provider for webview views.
+ *
+ * @param viewId Unique id of the view. This should match the `id` from the
+ * `views` contribution in the package.json.
+ * @param provider Provider for the webview views.
+ *
+ * @return Disposable that unregisters the provider.
+ */
+ export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
+ /**
+ * Content settings for the webview created for this view.
+ */
+ readonly webviewOptions?: {
+ /**
+ * Controls if the webview element itself (iframe) is kept around even when the view
+ * is no longer visible.
+ *
+ * Normally the webview's html context is created when the view becomes visible
+ * and destroyed when it is hidden. Extensions that have complex state
+ * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview
+ * context around, even when the webview moves to a background tab. When a webview using
+ * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended.
+ * When the view becomes visible again, the context is automatically restored
+ * in the exact same state it was in originally. You cannot send messages to a
+ * hidden webview, even with `retainContextWhenHidden` enabled.
+ *
+ * `retainContextWhenHidden` has a high memory overhead and should only be used if
+ * your view's context cannot be quickly saved and restored.
+ */
+ readonly retainContextWhenHidden?: boolean;
+ };
+ }): Disposable;
+
+ /**
+ * Register a provider for custom editors for the `viewType` contributed by the `customEditors` extension point.
+ *
+ * When a custom editor is opened, VS Code fires an `onCustomEditor:viewType` activation event. Your extension
+ * must register a {@link CustomTextEditorProvider `CustomTextEditorProvider`}, {@link CustomReadonlyEditorProvider `CustomReadonlyEditorProvider`},
+ * {@link CustomEditorProvider `CustomEditorProvider`}for `viewType` as part of activation.
+ *
+ * @param viewType Unique identifier for the custom editor provider. This should match the `viewType` from the
+ * `customEditors` contribution point.
+ * @param provider Provider that resolves custom editors.
+ * @param options Options for the provider.
+ *
+ * @return Disposable that unregisters the provider.
+ */
+ export function registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider | CustomReadonlyEditorProvider | CustomEditorProvider, options?: {
+ /**
+ * Content settings for the webview panels created for this custom editor.
+ */
+ readonly webviewOptions?: WebviewPanelOptions;
+
+ /**
+ * Only applies to `CustomReadonlyEditorProvider | CustomEditorProvider`.
+ *
+ * Indicates that the provider allows multiple editor instances to be open at the same time for
+ * the same resource.
+ *
+ * By default, VS Code only allows one editor instance to be open at a time for each resource. If the
+ * user tries to open a second editor instance for the resource, the first one is instead moved to where
+ * the second one was to be opened.
+ *
+ * When `supportsMultipleEditorsPerDocument` is enabled, users can split and create copies of the custom
+ * editor. In this case, the custom editor must make sure it can properly synchronize the states of all
+ * editor instances for a resource so that they are consistent.
+ */
+ readonly supportsMultipleEditorsPerDocument?: boolean;
+ }): Disposable;
+
+ /**
+ * Register provider that enables the detection and handling of links within the terminal.
+ * @param provider The provider that provides the terminal links.
+ * @return Disposable that unregisters the provider.
+ */
+ export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable;
+
+ /**
+ * Register a file decoration provider.
+ *
+ * @param provider A {@link FileDecorationProvider}.
+ * @return A {@link Disposable} that unregisters the provider.
+ */
+ export function registerFileDecorationProvider(provider: FileDecorationProvider): Disposable;
+
+ /**
+ * The currently active color theme as configured in the settings. The active
+ * theme can be changed via the `workbench.colorTheme` setting.
+ */
+ export let activeColorTheme: ColorTheme;
+
+ /**
+ * An {@link Event} which fires when the active color theme is changed or has changes.
+ */
+ export const onDidChangeActiveColorTheme: Event;
+ }
+
+ /**
+ * Options for creating a {@link TreeView}
+ */
+ export interface TreeViewOptions {
+
+ /**
+ * A data provider that provides tree data.
+ */
+ treeDataProvider: TreeDataProvider;
+
+ /**
+ * Whether to show collapse all action or not.
+ */
+ showCollapseAll?: boolean;
+
+ /**
+ * Whether the tree supports multi-select. When the tree supports multi-select and a command is executed from the tree,
+ * the first argument to the command is the tree item that the command was executed on and the second argument is an
+ * array containing all selected tree items.
+ */
+ canSelectMany?: boolean;
+ }
+
+ /**
+ * The event that is fired when an element in the {@link TreeView} is expanded or collapsed
+ */
+ export interface TreeViewExpansionEvent {
+
+ /**
+ * Element that is expanded or collapsed.
+ */
+ readonly element: T;
+
+ }
+
+ /**
+ * The event that is fired when there is a change in {@link TreeView.selection tree view's selection}
+ */
+ export interface TreeViewSelectionChangeEvent {
+
+ /**
+ * Selected elements.
+ */
+ readonly selection: T[];
+
+ }
+
+ /**
+ * The event that is fired when there is a change in {@link TreeView.visible tree view's visibility}
+ */
+ export interface TreeViewVisibilityChangeEvent {
+
+ /**
+ * `true` if the {@link TreeView tree view} is visible otherwise `false`.
+ */
+ readonly visible: boolean;
+
+ }
+
+ /**
+ * Represents a Tree view
+ */
+ export interface TreeView extends Disposable {
+
+ /**
+ * Event that is fired when an element is expanded
+ */
+ readonly onDidExpandElement: Event>;
+
+ /**
+ * Event that is fired when an element is collapsed
+ */
+ readonly onDidCollapseElement: Event>;
+
+ /**
+ * Currently selected elements.
+ */
+ readonly selection: T[];
+
+ /**
+ * Event that is fired when the {@link TreeView.selection selection} has changed
+ */
+ readonly onDidChangeSelection: Event>;
+
+ /**
+ * `true` if the {@link TreeView tree view} is visible otherwise `false`.
+ */
+ readonly visible: boolean;
+
+ /**
+ * Event that is fired when {@link TreeView.visible visibility} has changed
+ */
+ readonly onDidChangeVisibility: Event;
+
+ /**
+ * An optional human-readable message that will be rendered in the view.
+ * Setting the message to null, undefined, or empty string will remove the message from the view.
+ */
+ message?: string;
+
+ /**
+ * The tree view title is initially taken from the extension package.json
+ * Changes to the title property will be properly reflected in the UI in the title of the view.
+ */
+ title?: string;
+
+ /**
+ * An optional human-readable description which is rendered less prominently in the title of the view.
+ * Setting the title description to null, undefined, or empty string will remove the description from the view.
+ */
+ description?: string;
+
+ /**
+ * Reveals the given element in the tree view.
+ * If the tree view is not visible then the tree view is shown and element is revealed.
+ *
+ * By default revealed element is selected.
+ * In order to not to select, set the option `select` to `false`.
+ * In order to focus, set the option `focus` to `true`.
+ * In order to expand the revealed element, set the option `expand` to `true`. To expand recursively set `expand` to the number of levels to expand.
+ * **NOTE:** You can expand only to 3 levels maximum.
+ *
+ * **NOTE:** The {@link TreeDataProvider} that the `TreeView` {@link window.createTreeView is registered with} with must implement {@link TreeDataProvider.getParent getParent} method to access this API.
+ */
+ reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): Thenable;
+ }
+
+ /**
+ * A data provider that provides tree data
+ */
+ export interface TreeDataProvider {
+ /**
+ * An optional event to signal that an element or root has changed.
+ * This will trigger the view to update the changed element/root and its children recursively (if shown).
+ * To signal that root has changed, do not pass any argument or pass `undefined` or `null`.
+ */
+ onDidChangeTreeData?: Event;
+
+ /**
+ * Get {@link TreeItem} representation of the `element`
+ *
+ * @param element The element for which {@link TreeItem} representation is asked for.
+ * @return {@link TreeItem} representation of the element
+ */
+ getTreeItem(element: T): TreeItem | Thenable;
+
+ /**
+ * Get the children of `element` or root if no element is passed.
+ *
+ * @param element The element from which the provider gets children. Can be `undefined`.
+ * @return Children of `element` or root if no element is passed.
+ */
+ getChildren(element?: T): ProviderResult