@theia/plugin 1.27.0-next.9 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.27.0-next.9+53a272e1138",
+  "version": "1.27.0",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -27,10 +27,10 @@
     "watch": "theiaext watch"
   },
   "devDependencies": {
-    "@theia/ext-scripts": "1.26.0"
+    "@theia/ext-scripts": "1.27.0"
   },
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "53a272e113890174c8b3049b8d1a74999dee0cd4"
+  "gitHead": "b952ad743a97821dee94787e946f5a288174d4e8"
 }

package/src/theia-proposed.d.ts

@@ -161,7 +161,7 @@ export module '@theia/plugin' {
          * Get the keybindings associated to commandId.
          * @param commandId The ID of the command for which we are looking for keybindings.
          */
-        export function getKeyBinding(commandId: string): PromiseLike<CommandKeyBinding[] | undefined>;
+        export function getKeyBinding(commandId: string): Thenable<CommandKeyBinding[] | undefined>;
 
         /**
          * Registers a diff information command that can be invoked via a keyboard shortcut,
@@ -210,7 +210,7 @@ export module '@theia/plugin' {
          * Returns the type of the operating system on the client side (like browser'OS if using browser mode). If it is neither [Windows](isWindows) nor [OS X](isOSX), then
          * it always return with the `Linux` OS type.
          */
-        export function getClientOperatingSystem(): PromiseLike<OperatingSystem>;
+        export function getClientOperatingSystem(): Thenable<OperatingSystem>;
 
     }
 
@@ -321,41 +321,6 @@ export module '@theia/plugin' {
 
     // #endregion
 
-    // #region Tree View
-    // copied from https://github.com/microsoft/vscode/blob/3ea5c9ddbebd8ec68e3b821f9c39c3ec785fde97/src/vs/vscode.proposed.d.ts#L1447-L1476
-    /**
-     * Label describing the [Tree item](#TreeItem)
-     */
-    export interface TreeItemLabel {
-
-        /**
-         * A human-readable string describing the [Tree item](#TreeItem).
-         */
-        label: string;
-
-        /**
-         * Ranges in the label to highlight. A range is defined as a tuple of two number where the
-         * first is the inclusive start index and the second the exclusive end index
-         */
-        // TODO highlights?: [number, number][];
-
-    }
-
-    export class TreeItem2 extends TreeItem {
-        /**
-         * Label describing this item. When `falsy`, it is derived from [resourceUri](#TreeItem.resourceUri).
-         */
-        label?: string | TreeItemLabel | /* for compilation */ any;
-
-        /**
-         * @param label Label describing this item
-         * @param collapsibleState [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item.
-         * Default is [TreeItemCollapsibleState.None](#TreeItemCollapsibleState.None)
-         */
-        constructor(label: TreeItemLabel, collapsibleState?: TreeItemCollapsibleState);
-    }
-    // #endregion
-
     // #region search in workspace
     /**
      * The parameters of a query for text search.

package/src/theia.d.ts

@@ -112,7 +112,7 @@ export module '@theia/plugin' {
          *
          * @return A promise that will resolve when this plug-in has been activated.
          */
-        activate(): PromiseLike<T>;
+        activate(): Thenable<T>;
     }
 
     /**
@@ -1182,7 +1182,7 @@ export module '@theia/plugin' {
          * @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; }): PromiseLike<boolean>;
+        edit(callback: (editBuilder: TextEditorEdit) => void, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable<boolean>;
 
         /**
          * Insert a [snippet](#SnippetString) and put the editor into snippet mode. "Snippet mode"
@@ -1195,7 +1195,7 @@ export module '@theia/plugin' {
          * @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 | Position[] | Range[], options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): PromiseLike<boolean>;
+        insertSnippet(snippet: SnippetString, location?: Position | Range | Position[] | Range[], options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable<boolean>;
 
         /**
          * Adds a set of decorations to the text editor. If a set of decorations already exists with
@@ -1215,6 +1215,22 @@ export module '@theia/plugin' {
          * @param revealType The scrolling strategy for revealing `range`.
          */
         revealRange(range: Range, revealType?: TextEditorRevealType): void;
+
+        /**
+         * Shows this text editor. A [column](#ViewColumn) can be provided to control where the editor is being shown. Might change the [active editor](#window.activeTextEditor).
+         *
+         * @deprecated use [window.showTextDocument](#Window.showTextDocument) instead.
+         *
+         * @param column A [view column](#ViewColumn) in which this editor should be shown.
+         */
+        show(column?: ViewColumn): void;
+
+        /**
+         * Hides this text editor.
+         *
+         * @deprecated use 'workbench.action.closeActiveEditor' command instead.
+         */
+        hide(): void;
     }
 
     /**
@@ -1658,7 +1674,7 @@ export module '@theia/plugin' {
          *
          * @param thenable A thenable that resolves to [pre-save-edits](#TextEdit).
          */
-        waitUntil(thenable: PromiseLike<TextEdit[]>): void;
+        waitUntil(thenable: Thenable<TextEdit[]>): void;
 
         /**
          * Allows to pause the event loop until the provided thenable resolved.
@@ -1667,7 +1683,7 @@ export module '@theia/plugin' {
          *
          * @param thenable A thenable that delays saving.
          */
-        waitUntil(thenable: PromiseLike<any>): void;
+        waitUntil(thenable: Thenable<any>): void;
     }
 
     /**
@@ -2455,7 +2471,7 @@ export module '@theia/plugin' {
          *
          * Reject if a command cannot be executed.
          */
-        export function executeCommand<T>(commandId: string, ...args: any[]): PromiseLike<T | undefined>;
+        export function executeCommand<T>(commandId: string, ...args: any[]): Thenable<T | undefined>;
 
         /**
          * Retrieve the list of all available commands. Commands starting an underscore are
@@ -2464,7 +2480,7 @@ export module '@theia/plugin' {
          * @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): PromiseLike<string[]>;
+        export function getCommands(filterInternal?: boolean): Thenable<string[]>;
     }
 
     /**
@@ -2652,7 +2668,22 @@ export module '@theia/plugin' {
          */
         static readonly Folder: ThemeIcon;
 
-        private constructor(public id: string);
+        /**
+         * 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 | undefined;
+
+        /**
+         * 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}.
+         */
+        private constructor(public id: string, public color?: ThemeColor);
     }
 
     /**
@@ -2831,7 +2862,7 @@ export module '@theia/plugin' {
         /**
          * Terminal id.
          */
-        readonly processId: PromiseLike<number>;
+        readonly processId: Thenable<number>;
 
         /**
          * The exit status of the terminal, this will be undefined while the terminal is active.
@@ -3450,7 +3481,7 @@ export module '@theia/plugin' {
          * @param key A string.
          * @param value A value. MUST not contain cyclic references.
          */
-        update(key: string, value: any): PromiseLike<void>;
+        update(key: string, value: any): Thenable<void>;
     }
 
     /**
@@ -3581,7 +3612,7 @@ export module '@theia/plugin' {
          *
          * @param message Body of the message.
          */
-        postMessage(message: any): PromiseLike<boolean>;
+        postMessage(message: any): Thenable<boolean>;
 
         /**
          * Convert a uri for the local file system to one that can be used inside webviews.
@@ -3816,9 +3847,9 @@ export module '@theia/plugin' {
          * serializer must restore the webview's `.html` and hook up all webview events.
          * @param state Persisted state from the webview content.
          *
-         * @return PromiseLike indicating that the webview has been fully restored.
+         * @return Thenable indicating that the webview has been fully restored.
          */
-        deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): PromiseLike<void>;
+        deserializeWebviewPanel(webviewPanel: WebviewPanel, state: T): Thenable<void>;
     }
 
     /**
@@ -3830,13 +3861,13 @@ export module '@theia/plugin' {
          * Read the current clipboard contents as text.
          * @returns A thenable that resolves to a string.
          */
-        readText(): PromiseLike<string>;
+        readText(): Thenable<string>;
 
         /**
          * Writes text into the clipboard.
          * @returns A thenable that resolves when writing happened.
          */
-        writeText(value: string): PromiseLike<void>;
+        writeText(value: string): Thenable<void>;
     }
 
     /**
@@ -4268,6 +4299,44 @@ export module '@theia/plugin' {
         resolveWebviewView(webviewView: WebviewView, context: WebviewViewResolveContext, token: CancellationToken): Thenable<void> | void;
     }
 
+    /**
+     * Additional information the webview view being resolved.
+     *
+     * @param T Type of the webview's state.
+     */
+    interface WebviewViewResolveContext<T = unknown> {
+        /**
+         * 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;
+    }
+
     /**
      * Common namespace for dealing with window and editor, showing messages and user input.
      */
@@ -4346,7 +4415,7 @@ export module '@theia/plugin' {
          * @param preserveFocus When `true` the editor will not take focus.
          * @return A promise that resolves to an [editor](#TextEditor).
          */
-        export function showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): PromiseLike<TextEditor>;
+        export function showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable<TextEditor>;
 
         /**
          * Show the given document in a text editor. [Options](#TextDocumentShowOptions) can be provided
@@ -4356,7 +4425,7 @@ export module '@theia/plugin' {
          * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor).
          * @return A promise that resolves to an [editor](#TextEditor).
          */
-        export function showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): PromiseLike<TextEditor>;
+        export function showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable<TextEditor>;
 
         /**
          * A short-hand for `openTextDocument(uri).then(document => showTextDocument(document, options))`.
@@ -4367,7 +4436,7 @@ export module '@theia/plugin' {
          * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor).
          * @return A promise that resolves to an [editor](#TextEditor).
          */
-        export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): PromiseLike<TextEditor>;
+        export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable<TextEditor>;
 
         /**
          * Shows a selection list.
@@ -4377,7 +4446,7 @@ export module '@theia/plugin' {
          * @param token A token that can be used to signal cancellation.
          * @return A promise that resolves to the selection or `undefined`.
          */
-        export function showQuickPick(readonly items: string[] | PromiseLike<readonly string[]>, options: QuickPickOptions, token?: CancellationToken): PromiseLike<string | undefined>;
+        export function showQuickPick(readonly items: string[] | Thenable<readonly string[]>, options: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>;
 
         /**
          * Shows a selection list allowing multiple selections.
@@ -4387,7 +4456,7 @@ export module '@theia/plugin' {
          * @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(readonly items: string[] | PromiseLike<readonly string[]>, options: QuickPickOptions & { canPickMany: true }, token?: CancellationToken): PromiseLike<string[] | undefined>;
+        export function showQuickPick(readonly items: string[] | Thenable<readonly string[]>, options: QuickPickOptions & { canPickMany: true }, token?: CancellationToken): Thenable<string[] | undefined>;
 
         /**
          * Shows a selection list.
@@ -4397,7 +4466,7 @@ export module '@theia/plugin' {
          * @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<T extends QuickPickItem>(items: readonly T[] | PromiseLike<readonly T[]>, options: QuickPickOptions, token?: CancellationToken): PromiseLike<T | undefined>;
+        export function showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>;
 
         /**
          * Shows a selection list allowing multiple selections.
@@ -4407,7 +4476,7 @@ export module '@theia/plugin' {
          * @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<T extends QuickPickItem>(items: readonly T[] | PromiseLike<readonly T[]>, options: QuickPickOptions & { canPickMany: true }, token?: CancellationToken): PromiseLike<T[] | undefined>;
+        export function showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options: QuickPickOptions & { canPickMany: true }, token?: CancellationToken): Thenable<T[] | undefined>;
 
         /**
          * Creates a [QuickPick](#QuickPick) to let the user pick an item from a list
@@ -4428,7 +4497,7 @@ export module '@theia/plugin' {
          * @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): PromiseLike<WorkspaceFolder | undefined>;
+        export function showWorkspaceFolderPick(options?: WorkspaceFolderPickOptions): Thenable<WorkspaceFolder | undefined>;
 
         /**
          * Show an information message.
@@ -4437,7 +4506,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage(message: string, ...items: string[]): PromiseLike<string | undefined>;
+        export function showInformationMessage(message: string, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show an information message.
@@ -4447,7 +4516,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage(message: string, options: MessageOptions, ...items: string[]): PromiseLike<string | undefined>;
+        export function showInformationMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show an information message.
@@ -4456,7 +4525,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): PromiseLike<T | undefined>;
+        export function showInformationMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an information message.
@@ -4466,7 +4535,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): PromiseLike<T | undefined>;
+        export function showInformationMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show a warning message.
@@ -4475,7 +4544,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage(message: string, ...items: string[]): PromiseLike<string | undefined>;
+        export function showWarningMessage(message: string, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show a warning message.
@@ -4485,7 +4554,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage(message: string, options: MessageOptions, ...items: string[]): PromiseLike<string | undefined>;
+        export function showWarningMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show a warning message.
@@ -4494,7 +4563,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): PromiseLike<T | undefined>;
+        export function showWarningMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show a warning message.
@@ -4504,7 +4573,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): PromiseLike<T | undefined>;
+        export function showWarningMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an error message.
@@ -4513,7 +4582,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage(message: string, ...items: string[]): PromiseLike<string | undefined>;
+        export function showErrorMessage(message: string, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show an error message.
@@ -4523,7 +4592,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage(message: string, options: MessageOptions, ...items: string[]): PromiseLike<string | undefined>;
+        export function showErrorMessage(message: string, options: MessageOptions, ...items: string[]): Thenable<string | undefined>;
 
         /**
          * Show an error message.
@@ -4532,7 +4601,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): PromiseLike<T | undefined>;
+        export function showErrorMessage<T extends MessageItem>(message: string, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Show an error message.
@@ -4542,7 +4611,7 @@ export module '@theia/plugin' {
          * @param items A set of items that will be rendered as actions in the message.
          * @return A promise that resolves to the selected item or `undefined` when being dismissed.
          */
-        export function showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): PromiseLike<T | undefined>;
+        export function showErrorMessage<T extends MessageItem>(message: string, options: MessageOptions, ...items: T[]): Thenable<T | undefined>;
 
         /**
          * Opens an input box to ask the user for input.
@@ -4555,7 +4624,7 @@ export module '@theia/plugin' {
          * @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): PromiseLike<string | undefined>;
+        export function showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined>;
 
         /**
          * Shows a file open dialog to the user which allows to select a file
@@ -4564,7 +4633,7 @@ export module '@theia/plugin' {
          * @param options Options that control the dialog.
          * @returns A promise that resolves to the selected resources or `undefined`.
          */
-        export function showOpenDialog(options: OpenDialogOptions): PromiseLike<Uri[] | undefined>;
+        export function showOpenDialog(options: OpenDialogOptions): Thenable<Uri[] | undefined>;
 
         /**
          * Shows a file save dialog to the user which allows to select a file
@@ -4573,7 +4642,7 @@ export module '@theia/plugin' {
          * @param options Options that control the dialog.
          * @returns A promise that resolves to the selected resource or `undefined`.
          */
-        export function showSaveDialog(options: SaveDialogOptions): PromiseLike<Uri | undefined>;
+        export function showSaveDialog(options: SaveDialogOptions): Thenable<Uri | undefined>;
 
         /**
          * Shows a file upload dialog to the user which allows to upload files
@@ -4582,7 +4651,7 @@ export module '@theia/plugin' {
          * @param options Options, that control the dialog.
          * @returns A promise that resolves the paths of uploaded files or `undefined`.
          */
-        export function showUploadDialog(options: UploadDialogOptions): PromiseLike<Uri[] | undefined>;
+        export function showUploadDialog(options: UploadDialogOptions): Thenable<Uri[] | undefined>;
 
         /**
          * Create and show a new webview panel.
@@ -4609,44 +4678,6 @@ export module '@theia/plugin' {
          * @param serializer Webview serializer.
          */
 
-        /**
-         * Additional information the webview view being resolved.
-         *
-         * @param T Type of the webview's state.
-         */
-        interface WebviewViewResolveContext<T = unknown> {
-            /**
-             * 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;
-        }
-
         export function registerWebviewViewProvider(viewId: string, provider: WebviewViewProvider, options?: {
             /**
              * Content settings for the webview created for this view.
@@ -4753,10 +4784,10 @@ export module '@theia/plugin' {
          * Set a message to the status bar.
          *
          * @param text The message to show, supports icon substitution as in status bar.
-         * @param hideWhenDone PromiseLike on which completion (resolve or reject) the message will be disposed.
+         * @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: PromiseLike<any>): Disposable;
+        export function setStatusBarMessage(text: string, hideWhenDone: Thenable<any>): Disposable;
 
         /**
          * Creates a status bar {@link StatusBarItem item}.
@@ -4886,7 +4917,7 @@ export module '@theia/plugin' {
          *
          * @return The thenable the task-callback returned.
          */
-        export function withProgress<R>(options: ProgressOptions, task: (progress: Progress<{ message?: string; increment?: number }>, token: CancellationToken) => PromiseLike<R>): PromiseLike<R>;
+        export function withProgress<R>(options: ProgressOptions, task: (progress: Progress<{ message?: string; increment?: number }>, token: CancellationToken) => Thenable<R>): Thenable<R>;
 
         /**
          * Creates a [InputBox](#InputBox) to let the user enter some text input.
@@ -5288,7 +5319,7 @@ export module '@theia/plugin' {
          *
          * **NOTE:** [TreeDataProvider](#TreeDataProvider) is required to implement [getParent](#TreeDataProvider.getParent) method to access this API.
          */
-        reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): PromiseLike<void>;
+        reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): Thenable<void>;
     }
 
     /**
@@ -5308,7 +5339,7 @@ export module '@theia/plugin' {
          * @param element The element for which [TreeItem](#TreeItem) representation is asked for.
          * @return [TreeItem](#TreeItem) representation of the element
          */
-        getTreeItem(element: T): TreeItem | PromiseLike<TreeItem>;
+        getTreeItem(element: T): TreeItem | Thenable<TreeItem>;
 
         /**
          * Get the children of `element` or root if no element is passed.
@@ -5334,7 +5365,7 @@ export module '@theia/plugin' {
         /**
          * A human-readable string describing this item. When `falsy`, it is derived from [resourceUri](#TreeItem.resourceUri).
          */
-        label?: string;
+        label?: string | TreeItemLabel;
 
         /**
          * Optional id for the tree item that has to be unique across tree. The id is used to preserve the selection and expansion state of the tree item.
@@ -5410,7 +5441,7 @@ export module '@theia/plugin' {
          * @param label A human-readable string describing this item
          * @param collapsibleState [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item. Default is [TreeItemCollapsibleState.None](#TreeItemCollapsibleState.None)
          */
-        constructor(label: string, collapsibleState?: TreeItemCollapsibleState);
+        constructor(label: string | TreeItemLabel, collapsibleState?: TreeItemCollapsibleState);
 
         /**
          * @param resourceUri The [uri](#Uri) of the resource representing this item.
@@ -5437,6 +5468,23 @@ export module '@theia/plugin' {
         Expanded = 2
     }
 
+    /**
+     * Label describing the {@link TreeItem Tree item}
+     */
+    export interface TreeItemLabel {
+
+        /**
+         * A human-readable string describing the {@link TreeItem Tree item}.
+         */
+        label: string;
+
+        /**
+         * Ranges in the label to highlight. A range is defined as a tuple of two numbers where the
+         * first is the inclusive start index and the second the exclusive end index
+         */
+        highlights?: [number, number][];
+    }
+
     /**
      * Represents the configuration. It is a merged view of
      *
@@ -5545,7 +5593,7 @@ export module '@theia/plugin' {
          * `ConfigurationTarget.WorkspaceFolder` when configuration is resource specific
          * `ConfigurationTarget.Workspace` otherwise.
          */
-        update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean): PromiseLike<void>;
+        update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean): Thenable<void>;
 
         /**
          * Readable dictionary that backs this configuration.
@@ -6212,7 +6260,7 @@ export module '@theia/plugin' {
          * @param uri Identifies the resource to open.
          * @return A promise that resolves to a [document](#TextDocument).
          */
-        export function openTextDocument(uri: Uri): PromiseLike<TextDocument | undefined>;
+        export function openTextDocument(uri: Uri): Thenable<TextDocument | undefined>;
 
         /**
          * A short-hand for `openTextDocument(Uri.file(fileName))`.
@@ -6221,7 +6269,7 @@ export module '@theia/plugin' {
          * @param fileName A name of a file on disk.
          * @return A promise that resolves to a [document](#TextDocument).
          */
-        export function openTextDocument(fileName: string): PromiseLike<TextDocument | undefined>;
+        export function openTextDocument(fileName: string): Thenable<TextDocument | undefined>;
 
         /**
          * Opens an untitled text document. The editor will prompt the user for a file
@@ -6231,7 +6279,7 @@ export module '@theia/plugin' {
          * @param options Options to control how the document will be created.
          * @return A promise that resolves to a [document](#TextDocument).
          */
-        export function openTextDocument(options?: { language?: string; content?: string; }): PromiseLike<TextDocument | undefined>;
+        export function openTextDocument(options?: { language?: string; content?: string; }): Thenable<TextDocument | undefined>;
 
         /**
          * Get a workspace configuration object.
@@ -6290,7 +6338,7 @@ export module '@theia/plugin' {
          * @return A thenable that resolves to an array of resource identifiers. Will return no results if no
          * [workspace folders](#workspace.workspaceFolders) are opened.
          */
-        export function findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): PromiseLike<Uri[]>;
+        export function findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable<Uri[]>;
 
         /**
          * Find text in files across all [workspace folders] in the workspace
@@ -6308,7 +6356,7 @@ export module '@theia/plugin' {
          * @param includeUntitled Also save files that have been created during this session.
          * @return A thenable that resolves when the files have been saved.
          */
-        export function saveAll(includeUntitled?: boolean): PromiseLike<boolean>;
+        export function saveAll(includeUntitled?: boolean): Thenable<boolean>;
 
         /**
          * Make changes to one or many resources or create, delete, and rename resources as defined by the given
@@ -6326,7 +6374,7 @@ export module '@theia/plugin' {
          * @param edit A workspace edit.
          * @return A thenable that resolves when the edit could be applied.
          */
-        export function applyEdit(edit: WorkspaceEdit): PromiseLike<boolean>;
+        export function applyEdit(edit: WorkspaceEdit): Thenable<boolean>;
 
         /**
          * Register a filesystem provider for a given scheme, e.g. `ftp`.
@@ -6448,7 +6496,7 @@ export module '@theia/plugin' {
          * @param envVarName name of environment variable to get
          * @returns value of the given environment variable name or undefined if there is no such variable.
          */
-        export function getEnvVariable(envVarName: string): PromiseLike<string | undefined>;
+        export function getEnvVariable(envVarName: string): Thenable<string | undefined>;
 
         /**
          * Gets query parameter value by name.
@@ -6521,7 +6569,7 @@ export module '@theia/plugin' {
          * @param target The uri that should be opened.
          * @returns A promise indicating if open was successful.
          */
-        export function openExternal(target: Uri): PromiseLike<boolean>;
+        export function openExternal(target: Uri): Thenable<boolean>;
 
         /**
          * Resolves an *external* uri, such as a `http:` or `https:` link, from where the extension is running to a
@@ -6535,7 +6583,7 @@ export module '@theia/plugin' {
          * the port forwarding tunnel is managed by VS Code and the tunnel can be closed by the user.
          *
          * 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
+         * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel
          * that was opened by `asExternalUri`.
          *
          * *Note* that uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri`
@@ -6543,7 +6591,7 @@ export module '@theia/plugin' {
          *
          * @return A uri that can be used on the client machine.
          */
-        export function asExternalUri(target: Uri): PromiseLike<Uri>;
+        export function asExternalUri(target: Uri): Thenable<Uri>;
 
     }
 
@@ -6709,6 +6757,10 @@ export module '@theia/plugin' {
          * 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.
          */
@@ -8966,7 +9018,7 @@ export module '@theia/plugin' {
          * Return the identifiers of all known languages.
          * @return Promise resolving to an array of identifier strings.
          */
-        export function getLanguages(): PromiseLike<string[]>;
+        export function getLanguages(): Thenable<string[]>;
 
         /**
          * Set (and change) the [language](#TextDocument.languageId) that is associated
@@ -8979,7 +9031,7 @@ export module '@theia/plugin' {
          * @param languageId The new language identifier.
          * @returns A thenable that resolves with the updated document.
          */
-        export function setTextDocumentLanguage(document: TextDocument, languageId: string): PromiseLike<TextDocument>;
+        export function setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable<TextDocument>;
 
         /**
          * Compute the match between a document [selector](#DocumentSelector) and a document. Values
@@ -9850,7 +9902,7 @@ export module '@theia/plugin' {
         /**
          * Send a custom request to the debug adapter.
          */
-        customRequest(command: string, args?: any): PromiseLike<any>;
+        customRequest(command: string, args?: any): Thenable<any>;
     }
 
     /**
@@ -10363,13 +10415,13 @@ export module '@theia/plugin' {
          * @param parentSessionOrOptions Debug session options. When passed a parent debug session, assumes options with just this parent session.
          * @return A thenable that resolves when debugging could be successfully started.
          */
-        export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): PromiseLike<boolean>;
+        export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable<boolean>;
 
         /**
          * Stop the given debug session or stop all debug sessions if session is omitted.
          * @param session The [debug session](#DebugSession) to stop; if omitted all sessions are stopped.
          */
-        export function stopDebugging(session?: DebugSession): PromiseLike<void>;
+        export function stopDebugging(session?: DebugSession): Thenable<void>;
 
         /**
          * Add breakpoints.
@@ -10715,6 +10767,9 @@ export module '@theia/plugin' {
 
         /** 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;
     }
 
     export class Task {
@@ -10937,7 +10992,7 @@ export module '@theia/plugin' {
          *
          * @param filter a filter to filter the return tasks.
          */
-        export function fetchTasks(filter?: TaskFilter): PromiseLike<Task[]>;
+        export function fetchTasks(filter?: TaskFilter): Thenable<Task[]>;
 
         /**
          * Executes a task that is managed by VS Code. The returned
@@ -10945,7 +11000,7 @@ export module '@theia/plugin' {
          *
          * @param task the task to execute
          */
-        export function executeTask(task: Task): PromiseLike<TaskExecution>;
+        export function executeTask(task: Task): Thenable<TaskExecution>;
 
         /**
          * The currently active task executions or an empty array.
@@ -11003,7 +11058,7 @@ export module '@theia/plugin' {
          * @param key A string.
          * @param value A value. MUST not contain cyclic references.
          */
-        update(key: string, value: any): PromiseLike<void>;
+        update(key: string, value: any): Thenable<void>;
     }
 
     /* The workspace symbol provider interface defines the contract between extensions
@@ -11838,3 +11893,21 @@ export module '@theia/plugin' {
 
     }
 }
+
+/**
+ * Thenable is a common denominator between ES6 promises, Q, jquery.Deferred, WinJS.Promise,
+ * and others. This API makes no assumption about what promise library is being used which
+ * enables reusing existing code without migrating to a specific promise implementation. Still,
+ * we recommend the use of native promises which are available in this editor.
+ */
+interface Thenable<T> {
+    /**
+     * Attaches callbacks for the resolution and/or rejection of the Promise.
+     * @param onfulfilled The callback to execute when the Promise is resolved.
+     * @param onrejected The callback to execute when the Promise is rejected.
+     * @returns A Promise for the completion of which ever callback is executed.
+     */
+    then<TResult>(onfulfilled?: (value: T) => TResult | Thenable<TResult>, onrejected?: (reason: any) => TResult | Thenable<TResult>): Thenable<TResult>;
+    then<TResult>(onfulfilled?: (value: T) => TResult | Thenable<TResult>, onrejected?: (reason: any) => void): Thenable<TResult>;
+}
+