diff --git a/types/vscode/index.d.ts b/types/vscode/index.d.ts index f3b14af250..53cfe9c7bb 100644 --- a/types/vscode/index.d.ts +++ b/types/vscode/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Visual Studio Code 1.45 +// Type definitions for Visual Studio Code 1.46 // Project: https://github.com/microsoft/vscode // Definitions by: Visual Studio Code Team, Microsoft // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -10,7 +10,7 @@ *--------------------------------------------------------------------------------------------*/ /** - * Type Definition for Visual Studio Code 1.45 Extension API + * Type Definition for Visual Studio Code 1.46 Extension API * See https://code.visualstudio.com/api for more information */ @@ -1301,7 +1301,7 @@ declare module 'vscode' { * 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 segement + * - 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'` * @@ -2227,7 +2227,7 @@ declare module 'vscode' { } /** - * Metadata about the type of code actions that a [CodeActionProvider](#CodeActionProvider) providers. + * Metadata about the type of code actions that a [CodeActionProvider](#CodeActionProvider) provides. */ export interface CodeActionProviderMetadata { /** @@ -2281,7 +2281,7 @@ declare module 'vscode' { * A code lens provider adds [commands](#Command) to source text. The commands will be shown * as dedicated horizontal lines in between the source text. */ - export interface CodeLensProvider { + export interface CodeLensProvider { /** * An optional event to signal that the code lenses from this provider have changed. @@ -2298,17 +2298,17 @@ declare module 'vscode' { * @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; + provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult; /** * This function will be called for each visible code lens, usually when scrolling and after * calls to [compute](#CodeLensProvider.provideCodeLenses)-lenses. * - * @param codeLens code lens that must be resolved. + * @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: CodeLens, token: CancellationToken): ProviderResult; + resolveCodeLens?(codeLens: T, token: CancellationToken): ProviderResult; } /** @@ -2656,7 +2656,6 @@ declare module 'vscode' { TypeParameter = 25 } - /** * Symbol tags are extra annotations that tweak the rendering of a symbol. */ @@ -2809,7 +2808,7 @@ declare module 'vscode' { * 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 { + export interface WorkspaceSymbolProvider { /** * Project-wide search for a symbol matching the given query string. @@ -2828,7 +2827,7 @@ declare module 'vscode' { * @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; + provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult; /** * Given a symbol fill in its [location](#SymbolInformation.location). This method is called whenever a symbol @@ -2842,7 +2841,7 @@ declare module 'vscode' { * @return The resolved symbol or a thenable that resolves to that. When no result is returned, * the given `symbol` is used. */ - resolveWorkspaceSymbol?(symbol: SymbolInformation, token: CancellationToken): ProviderResult; + resolveWorkspaceSymbol?(symbol: T, token: CancellationToken): ProviderResult; } /** @@ -3066,7 +3065,6 @@ declare module 'vscode' { */ renameFile(oldUri: Uri, newUri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }, metadata?: WorkspaceEditEntryMetadata): void; - /** * Get all text edits grouped by resource. * @@ -3869,7 +3867,7 @@ declare module 'vscode' { * Represents a collection of [completion items](#CompletionItem) to be presented * in the editor. */ - export class CompletionList { + export class CompletionList { /** * This list is not complete. Further typing should result in recomputing @@ -3880,7 +3878,7 @@ declare module 'vscode' { /** * The completion items. */ - items: CompletionItem[]; + items: T[]; /** * Creates a new completion list. @@ -3888,7 +3886,7 @@ declare module 'vscode' { * @param items The completion items. * @param isIncomplete The list is not complete. */ - constructor(items?: CompletionItem[], isIncomplete?: boolean); + constructor(items?: T[], isIncomplete?: boolean); } /** @@ -3942,7 +3940,7 @@ declare module 'vscode' { * 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 { + export interface CompletionItemProvider { /** * Provide completion items for the given position and document. @@ -3955,7 +3953,7 @@ declare module 'vscode' { * @return An array of completions, a [completion list](#CompletionList), 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; + provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult>; /** * Given a completion item fill in more data, like [doc-comment](#CompletionItem.documentation) @@ -3963,19 +3961,22 @@ declare module 'vscode' { * * The editor will only resolve a completion item once. * - * *Note* that accepting a completion item will not wait for it to be resolved. Because of that [`insertText`](#CompletionItem.insertText), - * [`additionalTextEdits`](#CompletionItem.additionalTextEdits), and [`command`](#CompletionItem.command) should not - * be changed when resolving an item. + * *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 ([insertText](#CompletionItem.insertText)) can be changed. + * + * This function may fill in [additionalTextEdits](#CompletionItem.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: CompletionItem, token: CancellationToken): ProviderResult; + 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. @@ -4014,7 +4015,7 @@ declare module 'vscode' { * The document link provider defines the contract between extensions and feature of showing * links in the editor. */ - export interface DocumentLinkProvider { + export interface DocumentLinkProvider { /** * Provide links for the given document. Note that the editor ships with a default provider that detects @@ -4025,7 +4026,7 @@ declare module 'vscode' { * @return An array of [document links](#DocumentLink) 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; + provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult; /** * Given a link fill in its [target](#DocumentLink.target). This method is called when an incomplete @@ -4036,7 +4037,7 @@ declare module 'vscode' { * @param link The link that is to be resolved. * @param token A cancellation token. */ - resolveDocumentLink?(link: DocumentLink, token: CancellationToken): ProviderResult; + resolveDocumentLink?(link: T, token: CancellationToken): ProviderResult; } /** @@ -4386,7 +4387,7 @@ declare module 'vscode' { } /** - * The call hierarchy provider interface describes the constract between extensions + * 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. */ @@ -5463,6 +5464,12 @@ declare module 'vscode' { */ 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. * @@ -5662,7 +5669,6 @@ declare module 'vscode' { private constructor(id: string, label: string); } - /** * A structure that defines a task kind in the system. * The value must be JSON-stringifyable. @@ -5927,7 +5933,7 @@ declare module 'vscode' { */ export enum TaskScope { /** - * The task is a global task. Global tasks are currrently not supported. + * The task is a global task. Global tasks are currently not supported. */ Global = 1, @@ -6041,13 +6047,13 @@ declare module 'vscode' { * A task provider allows to add tasks to the task service. * A task provider is registered via #tasks.registerTaskProvider. */ - export interface TaskProvider { + export interface TaskProvider { /** * Provides tasks. * @param token A cancellation token. * @return an array of tasks */ - provideTasks(token?: CancellationToken): ProviderResult; + provideTasks(token?: CancellationToken): ProviderResult; /** * Resolves a task that has no [`execution`](#Task.execution) set. Tasks are @@ -6062,7 +6068,7 @@ declare module 'vscode' { * @param token A cancellation token. * @return The resolved task */ - resolveTask(task: Task, token?: CancellationToken): ProviderResult; + resolveTask(task: T, token?: CancellationToken): ProviderResult; } /** @@ -6615,7 +6621,7 @@ declare module 'vscode' { readonly enableCommandUris?: boolean; /** - * Root paths from which the webview can load local (filesystem) resources using the `vscode-resource:` scheme. + * 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. * @@ -6901,12 +6907,15 @@ declare module 'vscode' { * This is called when a user first opens a resource for a `CustomTextEditorProvider`, or if they reopen an * existing editor using this `CustomTextEditorProvider`. * - * To resolve a custom editor, the provider must fill in its initial html content and hook up all - * the event listeners it is interested it. The provider can also hold onto the `WebviewPanel` to use later, - * for example in a command. See [`WebviewPanel`](#WebviewPanel) for additional details. * * @param document Document for the resource to resolve. - * @param webviewPanel Webview 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 [`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. @@ -6914,6 +6923,285 @@ declare module 'vscode' { resolveCustomTextEditor(document: TextDocument, webviewPanel: WebviewPanel, token: CancellationToken): Thenable | void; } + /** + * Represents a custom document used by a [`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 [`CustomDocument`](#CustomDocument). + * + * @see [`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 [`CustomDocument`](#CustomDocument) + * has changed. + * + * @see [`CustomDocumentProvider.onDidChangeCustomDocument`](#CustomDocumentProvider.onDidChangeCustomDocument). + */ + interface CustomDocumentContentChangeEvent { + /** + * The document that the change is for. + */ + readonly document: T; + } + + /** + * A backup for an [`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 [`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; + } + + /** + * Provider for readonly custom editors that use a custom document model. + * + * Custom editors use [`CustomDocument`](#CustomDocument) as their document model instead of a [`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 [`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 [`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 [`CustomDocument`](#CustomDocument) as their document model instead of a [`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 [`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 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. */ @@ -7041,7 +7329,7 @@ declare module 'vscode' { * * 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 fowarding tunnel is managed by VS Code and the tunnel can be closed by the user. + * 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. * @@ -7755,7 +8043,8 @@ declare module 'vscode' { * 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 [`CustomTextEditorProvider`](#CustomTextEditorProvider) for `viewType` as part of activation. + * must register a [`CustomTextEditorProvider`](#CustomTextEditorProvider), [`CustomReadonlyEditorProvider`](#CustomReadonlyEditorProvider), + * [`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. @@ -7764,7 +8053,28 @@ declare module 'vscode' { * * @return Disposable that unregisters the provider. */ - export function registerCustomEditorProvider(viewType: string, provider: CustomTextEditorProvider, options?: { readonly webviewOptions?: WebviewPanelOptions; }): Disposable; + 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; /** * The currently active color theme as configured in the settings. The active @@ -7894,7 +8204,7 @@ declare module 'vscode' { * 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:** [TreeDataProvider](#TreeDataProvider) is required to implement [getParent](#TreeDataProvider.getParent) method to access this API. + * **NOTE:** The [TreeDataProvider](#TreeDataProvider) that the `TreeView` [is registered with](#window.createTreeView) with must implement [getParent](#TreeDataProvider.getParent) method to access this API. */ reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): Thenable; } @@ -8268,6 +8578,113 @@ declare module 'vscode' { readonly code: number | undefined; } + /** + * A type of mutation that can be applied to an environment variable. + */ + export enum EnvironmentVariableMutatorType { + /** + * Replace the variable's existing value. + */ + Replace = 1, + /** + * Append to the end of the variable's existing value. + */ + Append = 2, + /** + * Prepend to the start of the variable's existing value. + */ + Prepend = 3 + } + + /** + * A type of mutation and its value to be applied to an environment variable. + */ + export interface EnvironmentVariableMutator { + /** + * The type of mutation that will occur to the variable. + */ + readonly type: EnvironmentVariableMutatorType; + + /** + * The value to use for the variable. + */ + readonly value: string; + } + + /** + * A collection of mutations that an extension can apply to a process environment. + */ + export interface EnvironmentVariableCollection { + /** + * Whether the collection should be cached for the workspace and applied to the terminal + * across window reloads. When true the collection will be active immediately such when the + * window reloads. Additionally, this API will return the cached version if it exists. The + * collection will be invalidated when the extension is uninstalled or when the collection + * is cleared. Defaults to true. + */ + persistent: boolean; + + /** + * Replace an environment variable with a value. + * + * Note that an extension can only make a single change to any one variable, so this will + * overwrite any previous calls to replace, append or prepend. + * + * @param variable The variable to replace. + * @param value The value to replace the variable with. + */ + replace(variable: string, value: string): void; + + /** + * Append a value to an environment variable. + * + * Note that an extension can only make a single change to any one variable, so this will + * overwrite any previous calls to replace, append or prepend. + * + * @param variable The variable to append to. + * @param value The value to append to the variable. + */ + append(variable: string, value: string): void; + + /** + * Prepend a value to an environment variable. + * + * Note that an extension can only make a single change to any one variable, so this will + * overwrite any previous calls to replace, append or prepend. + * + * @param variable The variable to prepend. + * @param value The value to prepend to the variable. + */ + prepend(variable: string, value: string): void; + + /** + * Gets the mutator that this collection applies to a variable, if any. + * + * @param variable The variable to get the mutator for. + */ + get(variable: string): EnvironmentVariableMutator | undefined; + + /** + * Iterate over each mutator in this collection. + * + * @param callback Function to execute for each entry. + * @param thisArg The `this` context used when invoking the handler function. + */ + forEach(callback: (variable: string, mutator: EnvironmentVariableMutator, collection: EnvironmentVariableCollection) => any, thisArg?: any): void; + + /** + * Deletes this collection's mutator for a variable. + * + * @param variable The variable to delete the mutator for. + */ + delete(variable: string): void; + + /** + * Clears all mutators from this collection. + */ + clear(): void; + } + /** * A location in the editor at which progress information can be shown. It depends on the * location how progress is visually represented. @@ -8855,7 +9272,6 @@ declare module 'vscode' { readonly files: ReadonlyArray<{ oldUri: Uri, newUri: Uri }>; } - /** * An event describing a change to the set of [workspace folders](#workspace.workspaceFolders). */ @@ -9172,9 +9588,11 @@ declare module 'vscode' { * An event that is emitted when a [text document](#TextDocument) is disposed or when the language id * of a text document [has been changed](#languages.setTextDocumentLanguage). * - * To add an event listener when a visible text document is closed, use the [TextEditor](#TextEditor) events in the - * [window](#window) namespace. Note that this event is not emitted when a [TextEditor](#TextEditor) is closed - * but the document remains open in another [visible text editor](#window.visibleTextEditors). + * *Note 1:* There is no guarantee that this event fires when an editor tab is closed, use the + * [`onDidChangeVisibleTextEditors`](#window.onDidChangeVisibleTextEditors)-event to know when editors change. + * + * *Note 2:* A document can be open but not shown in an editor which means this event can fire + * for a document that has not been shown in an editor. */ export const onDidCloseTextDocument: Event; @@ -9213,7 +9631,7 @@ declare module 'vscode' { * files change on disk, e.g triggered by another application, or when using the * [`workspace.fs`](#FileSystem)-api. * - * *Note 2:* When this event is fired, edits to files thare are being created cannot be applied. + * *Note 2:* When this event is fired, edits to files that are are being created cannot be applied. */ export const onWillCreateFiles: Event; @@ -9282,7 +9700,7 @@ declare module 'vscode' { * is returned. Dots in the section-identifier are interpreted as child-access, * like `{ myExt: { setting: { doIt: true }}}` and `getConfiguration('myExt.setting').get('doIt') === true`. * - * When a scope is provided configuraiton confined to that scope is returned. Scope can be a resource or a language identifier or both. + * When a scope is provided configuration confined to that scope is returned. Scope can be a resource or a language identifier or both. * * @param section A dot-separated identifier. * @param scope A scope for which the configuration is asked for. @@ -9490,7 +9908,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A code action provider. - * @param metadata Metadata about the kind of code actions the provider providers. + * @param metadata Metadata about the kind of code actions the provider provides. * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ export function registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider, metadata?: CodeActionProviderMetadata): Disposable; @@ -9641,8 +10059,8 @@ declare module 'vscode' { * Register a rename provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure - * of the selected provider will cause a failure of the whole operation. + * by their [score](#languages.match) and asked in sequence. The first provider producing a result + * defines the result of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A rename provider. @@ -10497,6 +10915,23 @@ declare module 'vscode' { // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). } + /** + * A DebugConfigurationProviderTriggerKind specifies when the `provideDebugConfigurations` method of a `DebugConfigurationProvider` is triggered. + * Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or + * to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command). + * A trigger kind is used when registering a `DebugConfigurationProvider` with #debug.registerDebugConfigurationProvider. + */ + export enum DebugConfigurationProviderTriggerKind { + /** + * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide the initial debug configurations for a newly created launch.json. + */ + Initial = 1, + /** + * `DebugConfigurationProvider.provideDebugConfigurations` is called to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command). + */ + Dynamic = 2 + } + /** * Namespace for debug functionality. */ @@ -10520,7 +10955,6 @@ declare module 'vscode' { */ export let breakpoints: Breakpoint[]; - /** * An [event](#Event) which fires when the [active debug session](#debug.activeDebugSession) * has changed. *Note* that the event also fires when the active debug session changes @@ -10550,13 +10984,19 @@ declare module 'vscode' { /** * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type. + * The optional [triggerKind](#DebugConfigurationProviderTriggerKind) can be used to specify when the `provideDebugConfigurations` method of the provider is triggered. + * Currently two trigger kinds are possible: with the value `Initial` (or if no trigger kind argument is given) the `provideDebugConfigurations` method is used to provide the initial debug configurations to be copied into a newly created launch.json. + * With the trigger kind `Dynamic` the `provideDebugConfigurations` method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json). + * Please note that the `triggerKind` argument only applies to the `provideDebugConfigurations` method: so the `resolveDebugConfiguration` methods are not affected at all. + * Registering a single provider with resolve methods for different trigger kinds, results in the same resolve methods called multiple times. * More than one provider can be registered for the same type. * * @param type The debug type for which the provider is registered. * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register. + * @param triggerKind The [trigger](#DebugConfigurationProviderTrigger) for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed. * @return A [disposable](#Disposable) that unregisters this provider when being disposed. */ - export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider): Disposable; + export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable; /** * Register a [debug adapter descriptor factory](#DebugAdapterDescriptorFactory) for a specific debug type. @@ -10586,7 +11026,7 @@ declare module 'vscode' { * Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder. * @param folder The [workspace folder](#WorkspaceFolder) for looking up named configurations and resolving variables or `undefined` for a non-folder setup. * @param nameOrConfiguration Either the name of a debug or compound configuration or a [DebugConfiguration](#DebugConfiguration) object. - * @param parentSessionOrOptions Debug sesison options. When passed a parent [debug session](#DebugSession), assumes options with just this parent session. + * @param parentSessionOrOptions Debug session options. When passed a parent [debug session](#DebugSession), 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): Thenable; @@ -10765,7 +11205,7 @@ declare module 'vscode' { /** * Dispose this comment thread. * - * Once disposed, this comment thread will be removed from visible editors and Comment Panel when approriate. + * Once disposed, this comment thread will be removed from visible editors and Comment Panel when appropriate. */ dispose(): void; } @@ -10886,6 +11326,21 @@ declare module 'vscode' { provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult; } + /** + * Represents a [comment controller](#CommentController)'s [options](#CommentController.options). + */ + export interface CommentOptions { + /** + * An optional string to show on the comment input box when it's collapsed. + */ + prompt?: string; + + /** + * An optional string to show as placeholder in the comment input box when it's focused. + */ + placeHolder?: string; + } + /** * A comment controller is able to provide [comments](#CommentThread) support to the editor and * provide users various ways to interact with comments. @@ -10901,6 +11356,11 @@ declare module 'vscode' { */ readonly label: string; + /** + * Comment controller options + */ + options?: CommentOptions; + /** * Optional commenting range provider. Provide a list [ranges](#Range) which support commenting to any given resource uri. *