A language filter that applies to all package.json paths
- * { language: 'json', pattern: '**/package.json' }
- */
- export interface DocumentFilter {
-
- /**
- * A language id, like `typescript`.
- */
- readonly language?: string;
-
- /**
- * The {@link NotebookDocument.notebookType type} of a notebook, like `jupyter-notebook`. This allows
- * to narrow down on the type of a notebook that a {@link NotebookCell.document cell document} belongs to.
- *
- * *Note* that setting the `notebookType`-property changes how `scheme` and `pattern` are interpreted. When set
- * they are evaluated against the {@link NotebookDocument.uri notebook uri}, not the document uri.
- *
- * @example
Match python document inside jupyter notebook that aren't stored yet (`untitled`)
- * { language: 'python', notebookType: 'jupyter-notebook', scheme: 'untitled' }
- */
- readonly notebookType?: 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 {@linkcode 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 {@linkcode 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 the editor 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 move actions: `refactor.move`
- *
- * Example move actions:
- *
- * - Move a function to a new file
- * - Move a property between classes
- * - Move method to base class
- * - ...
- */
- static readonly RefactorMove: 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
- * - ...
- */
- 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;
-
- /**
- * Base kind for all code actions applying to the enitre notebook's scope. CodeActionKinds using
- * this should always begin with `notebook.`
- *
- * This requires that new CodeActions be created for it and contributed via extensions.
- * Pre-existing kinds can not just have the new `notebook.` prefix added to them, as the functionality
- * is unique to the full-notebook scope.
- *
- * Notebook CodeActionKinds can be initialized as either of the following (both resulting in `notebook.source.xyz`):
- * - `const newKind = CodeActionKind.Notebook.append(CodeActionKind.Source.append('xyz').value)`
- * - `const newKind = CodeActionKind.Notebook.append('source.xyz')`
- *
- * Example Kinds/Actions:
- * - `notebook.source.organizeImports` (might move all imports to a new top cell)
- * - `notebook.source.normalizeVariableNames` (might rename all variables to a standardized casing format)
- */
- static readonly Notebook: CodeActionKind;
-
- /**
- * Private constructor, use statix `CodeActionKind.XYZ` to derive from an existing code action kind.
- *
- * @param value The value of the kind, such as `refactor.extract.function`.
- */
- 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: readonly Diagnostic[];
-
- /**
- * 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 | undefined;
- }
-
- /**
- * 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 {@linkcode CodeAction.edit edit} and/or a {@linkcode 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, the editor 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, the editor 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);
- }
-
- /**
- * Provides contextual actions for code. Code actions typically either fix problems or beautify/refactor code.
- *
- * Code actions are surfaced to users in a few different ways:
- *
- * - The [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature, which shows
- * a list of code actions at the current cursor position. The lightbulb's list of actions includes both quick fixes
- * and refactorings.
- * - As commands that users can run, such as `Refactor`. Users can run these from the command palette or with keybindings.
- * - As source actions, such `Organize Imports`.
- * - {@link CodeActionKind.QuickFix Quick fixes} are shown in the problems view.
- * - Change applied on save by the `editor.codeActionsOnSave` setting.
- */
- export interface CodeActionProvider {
- /**
- * Get code actions for a given range in a document.
- *
- * Only return code actions that are relevant to user for the requested range. Also keep in mind how the
- * returned code actions will appear in the UI. The lightbulb widget and `Refactor` commands for instance show
- * returned code actions as a list, so do not return a large number of code actions that will overwhelm the user.
- *
- * @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
- * {@link Selection selection} if the actions are being requested in the currently active editor.
- * @param context Provides additional information about what code actions are being requested. You can use this
- * to see what specific type of code actions are being requested by the editor in order to return more relevant
- * actions and avoid returning irrelevant code actions that the editor will discard.
- * @param token A cancellation token.
- *
- * @returns 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 {@linkcode 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.
- * @returns 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?: readonly CodeActionKind[];
-
- /**
- * 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 the editor. In this case, the editor 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`,
- * the editor 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 the editor or open a website using {@linkcode env.openExternal};
- *
- * The title of this documentation code action is taken from {@linkcode 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.
- * @returns 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.
- * @returns 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.
- * @returns 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.
- * @returns 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.
- * @returns 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.
- * @returns 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;
- }
-
- /**
- * Human-readable text that supports formatting via the [markdown syntax](https://commonmark.org).
- *
- * Rendering of {@link ThemeIcon theme icons} via the `$()`-syntax is supported
- * when the {@linkcode supportThemeIcons} is set to `true`.
- *
- * Rendering of embedded html is supported when {@linkcode supportHtml} is set to `true`.
- */
- 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)`.
- *
- * Defaults to `false` (commands are disabled).
- */
- isTrusted?: boolean | {
- /**
- * A set of commend ids that are allowed to be executed by this markdown string.
- */
- readonly enabledCommands: readonly string[];
- };
-
- /**
- * Indicates that this markdown string can contain {@link ThemeIcon ThemeIcons}, e.g. `$(zap)`.
- */
- supportThemeIcons?: boolean;
-
- /**
- * Indicates that this markdown string can contain raw html tags. Defaults to `false`.
- *
- * When `supportHtml` is false, the markdown renderer will strip out any raw html tags
- * that appear in the markdown text. This means you can only use markdown syntax for rendering.
- *
- * When `supportHtml` is true, the markdown render will also allow a safe subset of html tags
- * and attributes to be rendered. See https://github.com/microsoft/vscode/blob/6d2920473c6f13759c978dd89104c4270a83422d/src/vs/base/browser/markdownRenderer.ts#L296
- * for a list of all supported tags and attributes.
- */
- supportHtml?: boolean;
-
- /**
- * Uri that relative paths are resolved relative to.
- *
- * If the `baseUri` ends with `/`, it is considered a directory and relative paths in the markdown are resolved relative to that directory:
- *
- * ```ts
- * const md = new vscode.MarkdownString(`[link](./file.js)`);
- * md.baseUri = vscode.Uri.file('/path/to/dir/');
- * // Here 'link' in the rendered markdown resolves to '/path/to/dir/file.js'
- * ```
- *
- * If the `baseUri` is a file, relative paths in the markdown are resolved relative to the parent dir of that file:
- *
- * ```ts
- * const md = new vscode.MarkdownString(`[link](./file.js)`);
- * md.baseUri = vscode.Uri.file('/path/to/otherFile.js');
- * // Here 'link' in the rendered markdown resolves to '/path/to/file.js'
- * ```
- */
- baseUri?: Uri;
-
- /**
- * 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 {@linkcode 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 {@linkcode 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 {@linkcode MarkdownString} instead.
- */
- export type MarkedString = string | {
- /**
- * The language of a markdown code block
- * @deprecated please use {@linkcode MarkdownString} instead
- */
- language: string;
- /**
- * The code snippet of a markdown code block.
- * @deprecated please use {@linkcode MarkdownString} instead
- */
- 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: Array;
-
- /**
- * 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: MarkdownString | MarkedString | Array, 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.
- * @returns 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 | undefined;
-
- /**
- * 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 the editor 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.
- * The editor 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.
- * @returns 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 | undefined;
- /**
- * 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 | undefined;
- /**
- * 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 editor's debugger inline values feature.
- * In this contract the provider returns inline value information for a given document range
- * and the editor 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.
- * The editor 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.
- * @returns 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.
- * @returns 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 {
- /**
- * The `File` symbol kind.
- */
- File = 0,
- /**
- * The `Module` symbol kind.
- */
- Module = 1,
- /**
- * The `Namespace` symbol kind.
- */
- Namespace = 2,
- /**
- * The `Package` symbol kind.
- */
- Package = 3,
- /**
- * The `Class` symbol kind.
- */
- Class = 4,
- /**
- * The `Method` symbol kind.
- */
- Method = 5,
- /**
- * The `Property` symbol kind.
- */
- Property = 6,
- /**
- * The `Field` symbol kind.
- */
- Field = 7,
- /**
- * The `Constructor` symbol kind.
- */
- Constructor = 8,
- /**
- * The `Enum` symbol kind.
- */
- Enum = 9,
- /**
- * The `Interface` symbol kind.
- */
- Interface = 10,
- /**
- * The `Function` symbol kind.
- */
- Function = 11,
- /**
- * The `Variable` symbol kind.
- */
- Variable = 12,
- /**
- * The `Constant` symbol kind.
- */
- Constant = 13,
- /**
- * The `String` symbol kind.
- */
- String = 14,
- /**
- * The `Number` symbol kind.
- */
- Number = 15,
- /**
- * The `Boolean` symbol kind.
- */
- Boolean = 16,
- /**
- * The `Array` symbol kind.
- */
- Array = 17,
- /**
- * The `Object` symbol kind.
- */
- Object = 18,
- /**
- * The `Key` symbol kind.
- */
- Key = 19,
- /**
- * The `Null` symbol kind.
- */
- Null = 20,
- /**
- * The `EnumMember` symbol kind.
- */
- EnumMember = 21,
- /**
- * The `Struct` symbol kind.
- */
- Struct = 22,
- /**
- * The `Event` symbol kind.
- */
- Event = 23,
- /**
- * The `Operator` symbol kind.
- */
- Operator = 24,
- /**
- * The `TypeParameter` symbol kind.
- */
- 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?: readonly SymbolTag[];
-
- /**
- * 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?: readonly SymbolTag[];
-
- /**
- * 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 {@linkcode 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.
- * @returns 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.
- * @returns 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
- * {@linkcode 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.
- * @returns 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.
- */
- readonly 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.
- *
- * @returns 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.
- * @returns 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.
- * @returns A new text edit object.
- */
- static insert(position: Position, newText: string): TextEdit;
-
- /**
- * Utility to create a delete edit.
- *
- * @param range A range.
- * @returns A new text edit object.
- */
- static delete(range: Range): TextEdit;
-
- /**
- * Utility to create an eol-edit.
- *
- * @param eol An eol-sequence
- * @returns 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);
- }
-
- /**
- * A snippet edit represents an interactive edit that is performed by
- * the editor.
- *
- * *Note* that a snippet edit can always be performed as a normal {@link TextEdit text edit}.
- * This will happen when no matching editor is open or when a {@link WorkspaceEdit workspace edit}
- * contains snippet edits for multiple files. In that case only those that match the active editor
- * will be performed as snippet edits and the others as normal text edits.
- */
- export class SnippetTextEdit {
-
- /**
- * Utility to create a replace snippet edit.
- *
- * @param range A range.
- * @param snippet A snippet string.
- * @returns A new snippet edit object.
- */
- static replace(range: Range, snippet: SnippetString): SnippetTextEdit;
-
- /**
- * Utility to create an insert snippet edit.
- *
- * @param position A position, will become an empty range.
- * @param snippet A snippet string.
- * @returns A new snippet edit object.
- */
- static insert(position: Position, snippet: SnippetString): SnippetTextEdit;
-
- /**
- * The range this edit applies to.
- */
- range: Range;
-
- /**
- * The {@link SnippetString snippet} this edit will perform.
- */
- snippet: SnippetString;
-
- /**
- * Create a new snippet edit.
- *
- * @param range A range.
- * @param snippet A snippet string.
- */
- constructor(range: Range, snippet: SnippetString);
- }
-
- /**
- * A notebook edit represents edits that should be applied to the contents of a notebook.
- */
- export class NotebookEdit {
-
- /**
- * Utility to create a edit that replaces cells in a notebook.
- *
- * @param range The range of cells to replace
- * @param newCells The new notebook cells.
- */
- static replaceCells(range: NotebookRange, newCells: NotebookCellData[]): NotebookEdit;
-
- /**
- * Utility to create an edit that replaces cells in a notebook.
- *
- * @param index The index to insert cells at.
- * @param newCells The new notebook cells.
- */
- static insertCells(index: number, newCells: NotebookCellData[]): NotebookEdit;
-
- /**
- * Utility to create an edit that deletes cells in a notebook.
- *
- * @param range The range of cells to delete.
- */
- static deleteCells(range: NotebookRange): NotebookEdit;
-
- /**
- * Utility to create an edit that update a cell's metadata.
- *
- * @param index The index of the cell to update.
- * @param newCellMetadata The new metadata for the cell.
- */
- static updateCellMetadata(index: number, newCellMetadata: { [key: string]: any }): NotebookEdit;
-
- /**
- * Utility to create an edit that updates the notebook's metadata.
- *
- * @param newNotebookMetadata The new metadata for the notebook.
- */
- static updateNotebookMetadata(newNotebookMetadata: { [key: string]: any }): NotebookEdit;
-
- /**
- * Range of the cells being edited. May be empty.
- */
- range: NotebookRange;
-
- /**
- * New cells being inserted. May be empty.
- */
- newCells: NotebookCellData[];
-
- /**
- * Optional new metadata for the cells.
- */
- newCellMetadata?: { [key: string]: any };
-
- /**
- * Optional new metadata for the notebook.
- */
- newNotebookMetadata?: { [key: string]: any };
-
- /**
- * Create a new notebook edit.
- *
- * @param range A notebook range.
- * @param newCells An array of new cell data.
- */
- constructor(range: NotebookRange, newCells: NotebookCellData[]);
- }
-
- /**
- * 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 | {
- /**
- * The icon path for the light theme.
- */
- light: Uri;
- /**
- * The icon path for the dark theme.
- */
- dark: Uri;
- } | ThemeIcon;
- }
-
- /**
- * Additional data about a workspace edit.
- */
- export interface WorkspaceEditMetadata {
- /**
- * Signal to the editor that this edit is a refactoring.
- */
- isRefactoring?: boolean;
- }
-
- /**
- * 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.
- * @returns `true` if the given resource will be touched by this edit.
- */
- has(uri: Uri): boolean;
-
- /**
- * Set (and replace) text edits or snippet edits for a resource.
- *
- * @param uri A resource identifier.
- * @param edits An array of edits.
- */
- set(uri: Uri, edits: ReadonlyArray): void;
-
- /**
- * Set (and replace) text edits or snippet edits with metadata for a resource.
- *
- * @param uri A resource identifier.
- * @param edits An array of edits.
- */
- set(uri: Uri, edits: ReadonlyArray<[TextEdit | SnippetTextEdit, WorkspaceEditEntryMetadata]>): void;
-
- /**
- * Set (and replace) notebook edits for a resource.
- *
- * @param uri A resource identifier.
- * @param edits An array of edits.
- */
- set(uri: Uri, edits: readonly NotebookEdit[]): void;
-
- /**
- * Set (and replace) notebook edits with metadata for a resource.
- *
- * @param uri A resource identifier.
- * @param edits An array of edits.
- */
- set(uri: Uri, edits: ReadonlyArray<[NotebookEdit, WorkspaceEditEntryMetadata]>): void;
-
- /**
- * Get the text edits for a resource.
- *
- * @param uri A resource identifier.
- * @returns 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. The `content`-property allows to set the initial contents
- * the file is being created with.
- * @param metadata Optional metadata for the entry.
- */
- createFile(uri: Uri, options?: {
- /**
- * Overwrite existing file. Overwrite wins over `ignoreIfExists`
- */
- readonly overwrite?: boolean;
- /**
- * Do nothing if a file with `uri` exists already.
- */
- readonly ignoreIfExists?: boolean;
- /**
- * The initial contents of the new file.
- *
- * If creating a file from a {@link DocumentDropEditProvider drop operation}, you can
- * pass in a {@link DataTransferFile} to improve performance by avoiding extra data copying.
- */
- readonly contents?: Uint8Array | DataTransferFile;
- }, 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?: {
- /**
- * Delete the content recursively if a folder is denoted.
- */
- readonly recursive?: boolean;
- /**
- * Do nothing if a file with `uri` exists already.
- */
- readonly 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 existing file. Overwrite wins over `ignoreIfExists`
- */
- readonly overwrite?: boolean;
- /**
- * Do nothing if a file with `uri` exists already.
- */
- readonly ignoreIfExists?: boolean;
- }, metadata?: WorkspaceEditEntryMetadata): void;
-
- /**
- * Get all text edits grouped by resource.
- *
- * @returns 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}`. Also see
- * [the full snippet syntax](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets).
- */
- export class SnippetString {
-
- /**
- * The snippet string.
- */
- value: string;
-
- /**
- * Create a new snippet string.
- *
- * @param value A snippet string.
- */
- constructor(value?: string);
-
- /**
- * Builder-function that appends the given string to
- * the {@linkcode SnippetString.value value} of this snippet string.
- *
- * @param string A value to append 'as given'. The string will be escaped.
- * @returns This snippet string.
- */
- appendText(string: string): SnippetString;
-
- /**
- * Builder-function that appends a tabstop (`$1`, `$2` etc) to
- * the {@linkcode SnippetString.value value} of this snippet string.
- *
- * @param number The number of this tabstop, defaults to an auto-increment
- * value starting at 1.
- * @returns This snippet string.
- */
- appendTabstop(number?: number): SnippetString;
-
- /**
- * Builder-function that appends a placeholder (`${1:value}`) to
- * the {@linkcode 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.
- * @returns This snippet string.
- */
- appendPlaceholder(value: string | ((snippet: SnippetString) => any), number?: number): SnippetString;
-
- /**
- * Builder-function that appends a choice (`${1|a,b,c|}`) to
- * the {@linkcode 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.
- * @returns This snippet string.
- */
- appendChoice(values: readonly string[], number?: number): SnippetString;
-
- /**
- * Builder-function that appends a variable (`${VAR}`) to
- * the {@linkcode 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.
- * @returns 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.
- * @returns 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.
- * @returns 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[];
-
- /**
- * Creates a semantic tokens legend.
- *
- * @param tokenTypes An array of token types.
- * @param tokenModifiers An array of token modifiers.
- */
- 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 {
-
- /**
- * Creates a semantic tokens builder.
- *
- * @param legend A semantic tokens legent.
- */
- 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?: readonly 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 | undefined;
- /**
- * The actual tokens data.
- * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens} for an explanation of the format.
- */
- readonly data: Uint32Array;
-
- /**
- * Create new semantic tokens.
- *
- * @param data Token data.
- * @param resultId Result identifier.
- */
- 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 | undefined;
- /**
- * The edits to the tokens data.
- * All edits refer to the initial data state.
- */
- readonly edits: SemanticTokensEdit[];
-
- /**
- * Create new semantic tokens edits.
- *
- * @param edits An array of semantic token edits
- * @param resultId Result identifier.
- */
- 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 | undefined;
-
- /**
- * Create a semantic token edit.
- *
- * @param start Start offset
- * @param deleteCount Number of elements to remove.
- * @param data Elements to insert
- */
- 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 the editor 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.
- * @returns 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.
- * @returns 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;
-
-
- /**
- * Provide formatting edits for multiple ranges in a document.
- *
- * This function is optional but allows a formatter to perform faster when formatting only modified ranges or when
- * formatting a large number of selections.
- *
- * The given ranges are hints 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 ranges The ranges which should be formatted.
- * @param options Options controlling formatting.
- * @param token A cancellation token.
- * @returns 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.
- */
- provideDocumentRangesFormattingEdits?(document: TextDocument, ranges: 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.
- * @returns 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 {@linkcode SignatureHelp.activeParameter}.
- */
- 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 {@linkcode 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
- * {@linkcode 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 | undefined;
-
- /**
- * `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 {@linkcode SignatureHelp}.
- *
- * The `activeSignatureHelp` has its [`SignatureHelp.activeSignature`] field updated based on
- * the user arrowing through available signatures.
- */
- readonly activeSignatureHelp: SignatureHelp | undefined;
- }
-
- /**
- * 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.
- *
- * @returns 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 {@linkcode SignatureHelpProvider}.
- */
- export interface SignatureHelpProviderMetadata {
- /**
- * List of characters that trigger signature help.
- */
- readonly triggerCharacters: readonly string[];
-
- /**
- * 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: readonly string[];
- }
-
- /**
- * A structured label for a {@link CompletionItem completion item}.
- */
- export interface CompletionItemLabel {
-
- /**
- * The label of this completion item.
- *
- * By default this is also the text that is inserted when this completion is selected.
- */
- label: string;
-
- /**
- * An optional string which is rendered less prominently directly after {@link CompletionItemLabel.label label},
- * without any spacing. Should be used for function signatures or type annotations.
- */
- detail?: string;
-
- /**
- * An optional string which is rendered less prominently after {@link CompletionItemLabel.detail}. Should be used
- * for fully qualified names or file path.
- */
- description?: string;
- }
-
- /**
- * Completion item kinds.
- */
- export enum CompletionItemKind {
- /**
- * The `Text` completion item kind.
- */
- Text = 0,
- /**
- * The `Method` completion item kind.
- */
- Method = 1,
- /**
- * The `Function` completion item kind.
- */
- Function = 2,
- /**
- * The `Constructor` completion item kind.
- */
- Constructor = 3,
- /**
- * The `Field` completion item kind.
- */
- Field = 4,
- /**
- * The `Variable` completion item kind.
- */
- Variable = 5,
- /**
- * The `Class` completion item kind.
- */
- Class = 6,
- /**
- * The `Interface` completion item kind.
- */
- Interface = 7,
- /**
- * The `Module` completion item kind.
- */
- Module = 8,
- /**
- * The `Property` completion item kind.
- */
- Property = 9,
- /**
- * The `Unit` completion item kind.
- */
- Unit = 10,
- /**
- * The `Value` completion item kind.
- */
- Value = 11,
- /**
- * The `Enum` completion item kind.
- */
- Enum = 12,
- /**
- * The `Keyword` completion item kind.
- */
- Keyword = 13,
- /**
- * The `Snippet` completion item kind.
- */
- Snippet = 14,
- /**
- * The `Color` completion item kind.
- */
- Color = 15,
- /**
- * The `Reference` completion item kind.
- */
- Reference = 17,
- /**
- * The `File` completion item kind.
- */
- File = 16,
- /**
- * The `Folder` completion item kind.
- */
- Folder = 18,
- /**
- * The `EnumMember` completion item kind.
- */
- EnumMember = 19,
- /**
- * The `Constant` completion item kind.
- */
- Constant = 20,
- /**
- * The `Struct` completion item kind.
- */
- Struct = 21,
- /**
- * The `Event` completion item kind.
- */
- Event = 22,
- /**
- * The `Operator` completion item kind.
- */
- Operator = 23,
- /**
- * The `TypeParameter` completion item kind.
- */
- TypeParameter = 24,
- /**
- * The `User` completion item kind.
- */
- User = 25,
- /**
- * The `Issue` completion item kind.
- */
- 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 | CompletionItemLabel;
-
- /**
- * 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?: readonly CompletionItemTag[];
-
- /**
- * 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
- * {@linkcode 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 {@linkcode 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 | {
- /**
- * The range that should be used when insert-accepting a completion. Must be a prefix of `replaceRange`.
- */
- inserting: Range;
- /**
- * The range that should be used when replace-accepting a completion.
- */
- 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 | CompletionItemLabel, 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 the provider was not triggered by a character.
- *
- * The trigger character is already in the document when the completion provider is triggered.
- */
- readonly triggerCharacter: string | undefined;
- }
-
- /**
- * 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 {@linkcode CompletionItem.detail detail}
- * and {@linkcode CompletionItem.documentation documentation} properties by implementing the
- * {@linkcode 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.
- *
- * @returns 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.
- * @returns 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;
- }
-
-
- /**
- * The inline completion item provider interface defines the contract between extensions and
- * the inline completion feature.
- *
- * Providers are asked for completions either explicitly by a user gesture or implicitly when typing.
- */
- export interface InlineCompletionItemProvider {
-
- /**
- * Provides inline completion items for the given position and document.
- * If inline completions are enabled, this method will be called whenever the user stopped typing.
- * It will also be called when the user explicitly triggers inline completions or explicitly asks for the next or previous inline completion.
- * In that case, all available inline completions should be returned.
- * `context.triggerKind` can be used to distinguish between these scenarios.
- *
- * @param document The document inline completions are requested for.
- * @param position The position inline completions are requested for.
- * @param context A context object with additional information.
- * @param token A cancellation token.
- * @returns An array of completion items or a thenable that resolves to an array of completion items.
- */
- provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult;
- }
-
- /**
- * Represents a collection of {@link InlineCompletionItem inline completion items} to be presented
- * in the editor.
- */
- export class InlineCompletionList {
- /**
- * The inline completion items.
- */
- items: InlineCompletionItem[];
-
- /**
- * Creates a new list of inline completion items.
- */
- constructor(items: InlineCompletionItem[]);
- }
-
- /**
- * Provides information about the context in which an inline completion was requested.
- */
- export interface InlineCompletionContext {
- /**
- * Describes how the inline completion was triggered.
- */
- readonly triggerKind: InlineCompletionTriggerKind;
-
- /**
- * Provides information about the currently selected item in the autocomplete widget if it is visible.
- *
- * If set, provided inline completions must extend the text of the selected item
- * and use the same range, otherwise they are not shown as preview.
- * As an example, if the document text is `console.` and the selected item is `.log` replacing the `.` in the document,
- * the inline completion must also replace `.` and start with `.log`, for example `.log()`.
- *
- * Inline completion providers are requested again whenever the selected item changes.
- */
- readonly selectedCompletionInfo: SelectedCompletionInfo | undefined;
- }
-
- /**
- * Describes the currently selected completion item.
- */
- export interface SelectedCompletionInfo {
- /**
- * The range that will be replaced if this completion item is accepted.
- */
- readonly range: Range;
-
- /**
- * The text the range will be replaced with if this completion is accepted.
- */
- readonly text: string;
- }
-
- /**
- * Describes how an {@link InlineCompletionItemProvider inline completion provider} was triggered.
- */
- export enum InlineCompletionTriggerKind {
- /**
- * Completion was triggered explicitly by a user gesture.
- * Return multiple completion items to enable cycling through them.
- */
- Invoke = 0,
-
- /**
- * Completion was triggered automatically while editing.
- * It is sufficient to return a single completion item in this case.
- */
- Automatic = 1,
- }
-
- /**
- * An inline completion item represents a text snippet that is proposed inline to complete text that is being typed.
- *
- * @see {@link InlineCompletionItemProvider.provideInlineCompletionItems}
- */
- export class InlineCompletionItem {
- /**
- * The text to replace the range with. Must be set.
- * Is used both for the preview and the accept operation.
- */
- insertText: string | SnippetString;
-
- /**
- * A text that is used to decide if this inline completion should be shown. When `falsy`
- * the {@link InlineCompletionItem.insertText} is used.
- *
- * An inline completion is shown if the text to replace is a prefix of the filter text.
- */
- filterText?: string;
-
- /**
- * The range to replace.
- * Must begin and end on the same line.
- *
- * Prefer replacements over insertions to provide a better experience when the user deletes typed text.
- */
- range?: Range;
-
- /**
- * An optional {@link Command} that is executed *after* inserting this completion.
- */
- command?: Command;
-
- /**
- * Creates a new inline completion item.
- *
- * @param insertText The text to replace the range with.
- * @param range The range to replace. If not set, the word at the requested position will be used.
- * @param command An optional {@link Command} that is executed *after* inserting this completion.
- */
- constructor(insertText: string | SnippetString, range?: Range, command?: Command);
- }
-
- /**
- * 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.
- * @returns 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 {@linkcode 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.
- */
- constructor(range: Range, color: Color);
- }
-
- /**
- * A color presentation object describes how a {@linkcode 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.
- * @returns 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.
- * @returns 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: {
- /**
- * The text document that contains the color
- */
- readonly document: TextDocument;
- /**
- * The range in the document where the color is located.
- */
- readonly range: Range;
- }, token: CancellationToken): ProviderResult;
- }
-
- /**
- * Inlay hint kinds.
- *
- * The kind of an inline hint defines its appearance, e.g the corresponding foreground and background colors are being
- * used.
- */
- export enum InlayHintKind {
- /**
- * An inlay hint that for a type annotation.
- */
- Type = 1,
- /**
- * An inlay hint that is for a parameter.
- */
- Parameter = 2,
- }
-
- /**
- * An inlay hint label part allows for interactive and composite labels of inlay hints.
- */
- export class InlayHintLabelPart {
-
- /**
- * The value of this label part.
- */
- value: string;
-
- /**
- * The tooltip text when you hover over this label part.
- *
- * *Note* that this property can be set late during
- * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
- */
- tooltip?: string | MarkdownString | undefined;
-
- /**
- * An optional {@link Location source code location} that represents this label
- * part.
- *
- * The editor will use this location for the hover and for code navigation features: This
- * part will become a clickable link that resolves to the definition of the symbol at the
- * given location (not necessarily the location itself), it shows the hover that shows at
- * the given location, and it shows a context menu with further code navigation commands.
- *
- * *Note* that this property can be set late during
- * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
- */
- location?: Location | undefined;
-
- /**
- * An optional command for this label part.
- *
- * The editor renders parts with commands as clickable links. The command is added to the context menu
- * when a label part defines {@link InlayHintLabelPart.location location} and {@link InlayHintLabelPart.command command} .
- *
- * *Note* that this property can be set late during
- * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
- */
- command?: Command | undefined;
-
- /**
- * Creates a new inlay hint label part.
- *
- * @param value The value of the part.
- */
- constructor(value: string);
- }
-
- /**
- * Inlay hint information.
- */
- export class InlayHint {
-
- /**
- * The position of this hint.
- */
- position: Position;
-
- /**
- * The label of this hint. A human readable string or an array of {@link InlayHintLabelPart label parts}.
- *
- * *Note* that neither the string nor the label part can be empty.
- */
- label: string | InlayHintLabelPart[];
-
- /**
- * The tooltip text when you hover over this item.
- *
- * *Note* that this property can be set late during
- * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
- */
- tooltip?: string | MarkdownString | undefined;
-
- /**
- * The kind of this hint. The inlay hint kind defines the appearance of this inlay hint.
- */
- kind?: InlayHintKind;
-
- /**
- * Optional {@link TextEdit text edits} that are performed when accepting this inlay hint. The default
- * gesture for accepting an inlay hint is the double click.
- *
- * *Note* that edits are expected to change the document so that the inlay hint (or its nearest variant) is
- * now part of the document and the inlay hint itself is now obsolete.
- *
- * *Note* that this property can be set late during
- * {@link InlayHintsProvider.resolveInlayHint resolving} of inlay hints.
- */
- textEdits?: TextEdit[];
-
- /**
- * Render padding before the hint. Padding will use the editor's background color,
- * not the background color of the hint itself. That means padding can be used to visually
- * align/separate an inlay hint.
- */
- paddingLeft?: boolean;
-
- /**
- * Render padding after the hint. Padding will use the editor's background color,
- * not the background color of the hint itself. That means padding can be used to visually
- * align/separate an inlay hint.
- */
- paddingRight?: boolean;
-
- /**
- * Creates a new inlay hint.
- *
- * @param position The position of the hint.
- * @param label The label of the hint.
- * @param kind The {@link InlayHintKind kind} of the hint.
- */
- constructor(position: Position, label: string | InlayHintLabelPart[], kind?: InlayHintKind);
- }
-
- /**
- * The inlay hints provider interface defines the contract between extensions and
- * the inlay hints feature.
- */
- export interface InlayHintsProvider {
-
- /**
- * An optional event to signal that inlay hints from this provider have changed.
- */
- onDidChangeInlayHints?: Event;
-
- /**
- * Provide inlay hints for the given range and document.
- *
- * *Note* that inlay hints that are not {@link Range.contains contained} by the given range are ignored.
- *
- * @param document The document in which the command was invoked.
- * @param range The range for which inlay hints should be computed.
- * @param token A cancellation token.
- * @returns An array of inlay hints or a thenable that resolves to such.
- */
- provideInlayHints(document: TextDocument, range: Range, token: CancellationToken): ProviderResult;
-
- /**
- * Given an inlay hint fill in {@link InlayHint.tooltip tooltip}, {@link InlayHint.textEdits text edits},
- * or complete label {@link InlayHintLabelPart parts}.
- *
- * *Note* that the editor will resolve an inlay hint at most once.
- *
- * @param hint An inlay hint.
- * @param token A cancellation token.
- * @returns The resolved inlay hint 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.
- */
- resolveInlayHint?(hint: T, 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);
- }
-
- /**
- * The selection range provider interface defines the contract between extensions and the "Expand and Shrink Selection" feature.
- */
- 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.
- * @returns 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: readonly 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?: readonly SymbolTag[];
-
- /**
- * 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 {@linkcode 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 {@linkcode 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 {@linkcode CallHierarchyProvider.provideCallHierarchyOutgoingCalls provideCallHierarchyOutgoingCalls}
- * and not {@linkcode 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 One or multiple call hierarchy items or a thenable that resolves to such. The lack of a result can be
- * signaled by returning `undefined`, `null`, or an empty array.
- */
- 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 an item of a type hierarchy, like a class or an interface.
- */
- export class TypeHierarchyItem {
- /**
- * 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 class. Must be contained by the {@link TypeHierarchyItem.range range}-property.
- */
- selectionRange: Range;
-
- /**
- * Creates a new type hierarchy item.
- *
- * @param kind The kind of the item.
- * @param name The name of the item.
- * @param detail The details of the item.
- * @param uri The Uri of the item.
- * @param range The whole range of the item.
- * @param selectionRange The selection range of the item.
- */
- constructor(kind: SymbolKind, name: string, detail: string, uri: Uri, range: Range, selectionRange: Range);
- }
-
- /**
- * The type hierarchy provider interface describes the contract between extensions
- * and the type hierarchy feature.
- */
- export interface TypeHierarchyProvider {
-
- /**
- * Bootstraps type hierarchy by returning the item that is denoted by the given document
- * and position. This item will be used as entry into the type 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 One or multiple type hierarchy items or a thenable that resolves to such. The lack of a result can be
- * signaled by returning `undefined`, `null`, or an empty array.
- */
- prepareTypeHierarchy(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
-
- /**
- * Provide all supertypes for an item, e.g all types from which a type is derived/inherited. In graph terms this describes directed
- * and annotated edges inside the type 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 super types should be computed.
- * @param token A cancellation token.
- * @returns A set of direct supertypes or a thenable that resolves to such. The lack of a result can be
- * signaled by returning `undefined` or `null`.
- */
- provideTypeHierarchySupertypes(item: TypeHierarchyItem, token: CancellationToken): ProviderResult;
-
- /**
- * Provide all subtypes for an item, e.g all types which are derived/inherited from the given item. In
- * graph terms this describes directed and annotated edges inside the type 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 subtypes should be computed.
- * @param token A cancellation token.
- * @returns A set of direct subtypes or a thenable that resolves to such. The lack of a result can be
- * signaled by returning `undefined` or `null`.
- */
- provideTypeHierarchySubtypes(item: TypeHierarchyItem, 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 | undefined;
- }
-
- /**
- * 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.
- * @returns A list of ranges that can be edited together
- */
- provideLinkedEditingRanges(document: TextDocument, position: Position, token: CancellationToken): ProviderResult;
- }
-
- /**
- * An edit operation applied {@link DocumentDropEditProvider on drop}.
- */
- export class DocumentDropEdit {
- /**
- * The text or snippet to insert at the drop location.
- */
- insertText: string | SnippetString;
-
- /**
- * An optional additional edit to apply on drop.
- */
- additionalEdit?: WorkspaceEdit;
-
- /**
- * @param insertText The text or snippet to insert at the drop location.
- */
- constructor(insertText: string | SnippetString);
- }
-
- /**
- * Provider which handles dropping of resources into a text editor.
- *
- * This allows users to drag and drop resources (including resources from external apps) into the editor. While dragging
- * and dropping files, users can hold down `shift` to drop the file into the editor instead of opening it.
- * Requires `editor.dropIntoEditor.enabled` to be on.
- */
- export interface DocumentDropEditProvider {
- /**
- * Provide edits which inserts the content being dragged and dropped into the document.
- *
- * @param document The document in which the drop occurred.
- * @param position The position in the document where the drop occurred.
- * @param dataTransfer A {@link DataTransfer} object that holds data about what is being dragged and dropped.
- * @param token A cancellation token.
- *
- * @returns A {@link DocumentDropEdit} or a thenable that resolves to such. The lack of a result can be
- * signaled by returning `undefined` or `null`.
- */
- provideDocumentDropEdits(document: TextDocument, position: Position, dataTransfer: DataTransfer, 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;
- }
-
- /**
- * Enumeration of commonly encountered syntax token types.
- */
- export enum SyntaxTokenType {
- /**
- * Everything except tokens that are part of comments, string literals and regular expressions.
- */
- Other = 0,
- /**
- * A comment.
- */
- Comment = 1,
- /**
- * A string literal.
- */
- String = 2,
- /**
- * A regular expression.
- */
- RegEx = 3
- }
-
- /**
- * Describes pairs of strings where the close string will be automatically inserted when typing the opening string.
- */
- export interface AutoClosingPair {
- /**
- * The string that will trigger the automatic insertion of the closing string.
- */
- open: string;
- /**
- * The closing string that will be automatically inserted when typing the opening string.
- */
- close: string;
- /**
- * A set of tokens where the pair should not be auto closed.
- */
- notIn?: SyntaxTokenType[];
- }
-
- /**
- * 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[];
- /**
- * The language's auto closing pairs.
- */
- autoClosingPairs?: AutoClosingPair[];
-
- /**
- * **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?: {
- /**
- * @deprecated
- */
- scope: string;
- /**
- * @deprecated
- */
- open: string;
- /**
- * @deprecated
- */
- lineStart: string;
- /**
- * @deprecated
- */
- close?: string;
- };
- };
-
- /**
- * **Deprecated** Do not use.
- *
- * @deprecated * Use the autoClosingPairs property in the language configuration file instead.
- */
- __characterPairSupport?: {
- /**
- * @deprecated
- */
- autoClosingPairs: {
- /**
- * @deprecated
- */
- open: string;
- /**
- * @deprecated
- */
- close: string;
- /**
- * @deprecated
- */
- 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 {@linkcode WorkspaceConfiguration.get get}) is computed by overriding or merging the values in the following order:
- *
- * 1. `defaultValue` (if defined in `package.json` otherwise derived from the value's type)
- * 1. `globalValue` (if defined)
- * 1. `workspaceValue` (if defined)
- * 1. `workspaceFolderValue` (if defined)
- * 1. `defaultLanguageValue` (if defined)
- * 1. `globalLanguageValue` (if defined)
- * 1. `workspaceLanguageValue` (if defined)
- * 1. `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.
- * @returns 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`.
- * @returns 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.
- * @returns `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.
- * @returns Information about a configuration setting or `undefined`.
- */
- inspect(section: string): {
-
- /**
- * The fully qualified key of the configuration value
- */
- key: string;
-
- /**
- * The default value which is used when no other value is defined
- */
- defaultValue?: T;
-
- /**
- * The global or installation-wide value.
- */
- globalValue?: T;
-
- /**
- * The workspace-specific value.
- */
- workspaceValue?: T;
-
- /**
- * The workpace-folder-specific value.
- */
- workspaceFolderValue?: T;
-
- /**
- * Language specific default value when this configuration value is created for a {@link ConfigurationScope language scope}.
- */
- defaultLanguageValue?: T;
-
- /**
- * Language specific global value when this configuration value is created for a {@link ConfigurationScope language scope}.
- */
- globalLanguageValue?: T;
-
- /**
- * Language specific workspace value when this configuration value is created for a {@link ConfigurationScope language scope}.
- */
- workspaceLanguageValue?: T;
-
- /**
- * Language specific workspace-folder value when this configuration value is created for a {@link ConfigurationScope language scope}.
- */
- workspaceFolderLanguageValue?: T;
-
- /**
- * All language identifiers for which this configuration is defined.
- */
- 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 | null, 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: readonly Uri[];
- }
-
- /**
- * 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 extends Iterable<[uri: Uri, diagnostics: readonly Diagnostic[]]> {
-
- /**
- * 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: readonly Diagnostic[] | 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, readonly Diagnostic[] | 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: readonly Diagnostic[], 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): readonly Diagnostic[] | 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;
- }
-
- /**
- * Represents the severity of a language status item.
- */
- /**
- * Represents the severity level of a language status.
- */
- export enum LanguageStatusSeverity {
- /**
- * Informational severity level.
- */
- Information = 0,
- /**
- * Warning severity level.
- */
- Warning = 1,
- /**
- * Error severity level.
- */
- Error = 2
- }
-
- /**
- * A language status item is the preferred way to present language status reports for the active text editors,
- * such as selected linter or notifying about a configuration problem.
- */
- export interface LanguageStatusItem {
-
- /**
- * The identifier of this item.
- */
- readonly id: string;
-
- /**
- * The short name of this item, like 'Java Language Status', etc.
- */
- name: string | undefined;
-
- /**
- * A {@link DocumentSelector selector} that defines for what editors
- * this item shows.
- */
- selector: DocumentSelector;
-
- /**
- * The severity of this item.
- *
- * Defaults to {@link LanguageStatusSeverity.Information information}. You can use this property to
- * signal to users that there is a problem that needs attention, like a missing executable or an
- * invalid configuration.
- */
- severity: LanguageStatusSeverity;
-
- /**
- * 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;
-
- /**
- * Optional, human-readable details for this item.
- */
- detail?: string;
-
- /**
- * Controls whether the item is shown as "busy". Defaults to `false`.
- */
- busy: boolean;
-
- /**
- * A {@linkcode Command command} for this item.
- */
- command: Command | undefined;
-
- /**
- * Accessibility information used when a screen reader interacts with this item
- */
- accessibilityInformation?: AccessibilityInformation;
-
- /**
- * Dispose and free associated resources.
- */
- 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;
-
- /**
- * Replaces all output from the channel with the given value.
- *
- * @param value A string, falsy values will not be printed.
- */
- replace(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;
- }
-
- /**
- * A channel for containing log output.
- *
- * To get an instance of a `LogOutputChannel` use
- * {@link window.createOutputChannel createOutputChannel}.
- */
- export interface LogOutputChannel extends OutputChannel {
-
- /**
- * The current log level of the channel. Defaults to {@link env.logLevel editor log level}.
- */
- readonly logLevel: LogLevel;
-
- /**
- * An {@link Event} which fires when the log level of the channel changes.
- */
- readonly onDidChangeLogLevel: Event;
-
- /**
- * Outputs the given trace message to the channel. Use this method to log verbose information.
- *
- * The message is only logged if the channel is configured to display {@link LogLevel.Trace trace} log level.
- *
- * @param message trace message to log
- */
- trace(message: string, ...args: any[]): void;
-
- /**
- * Outputs the given debug message to the channel.
- *
- * The message is only logged if the channel is configured to display {@link LogLevel.Debug debug} log level or lower.
- *
- * @param message debug message to log
- */
- debug(message: string, ...args: any[]): void;
-
- /**
- * Outputs the given information message to the channel.
- *
- * The message is only logged if the channel is configured to display {@link LogLevel.Info info} log level or lower.
- *
- * @param message info message to log
- */
- info(message: string, ...args: any[]): void;
-
- /**
- * Outputs the given warning message to the channel.
- *
- * The message is only logged if the channel is configured to display {@link LogLevel.Warning warning} log level or lower.
- *
- * @param message warning message to log
- */
- warn(message: string, ...args: any[]): void;
-
- /**
- * Outputs the given error or error message to the channel.
- *
- * The message is only logged if the channel is configured to display {@link LogLevel.Error error} log level or lower.
- *
- * @param error Error or error message to log
- */
- error(error: string | Error, ...args: any[]): 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.
- */
- readonly 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 the editor will pick the appropriate role automatically.
- * More about aria roles can be found here https://w3c.github.io/aria/#widget_roles
- */
- readonly 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 identifier of this item.
- *
- * *Note*: if no identifier was provided by the {@linkcode window.createStatusBarItem}
- * method, the identifier will match the {@link Extension.id extension identifier}.
- */
- readonly id: string;
-
- /**
- * 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 | undefined;
-
- /**
- * The name of the entry, like 'Python Language Indicator', 'Git Status' etc.
- * Try to keep the length of the name short, yet descriptive enough that
- * users can understand what the status bar item is about.
- */
- name: string | undefined;
-
- /**
- * 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 | MarkdownString | undefined;
-
- /**
- * The foreground color for this entry.
- */
- color: string | ThemeColor | undefined;
-
- /**
- * The background color for this entry.
- *
- * *Note*: only the following colors are supported:
- * * `new ThemeColor('statusBarItem.errorBackground')`
- * * `new ThemeColor('statusBarItem.warningBackground')`
- *
- * 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;
-
- /**
- * {@linkcode Command} or identifier of a command to run on click.
- *
- * The command must be {@link commands.getCommands known}.
- *
- * Note that if this is a {@linkcode Command} object, only the {@linkcode Command.command command} and {@linkcode Command.arguments arguments}
- * are used by the editor.
- */
- command: string | Command | undefined;
-
- /**
- * Accessibility information used when a screen reader interacts with this StatusBar item
- */
- accessibilityInformation: AccessibilityInformation | undefined;
-
- /**
- * 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;
-
- /**
- * The current state of the {@link Terminal}.
- */
- readonly state: TerminalState;
-
- /**
- * 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 shouldExecute Indicates that the text being sent should be executed rather than just inserted in the terminal.
- * The character(s) added are \n or \r\n, depending on the platform. This defaults to `true`.
- */
- sendText(text: string, shouldExecute?: 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;
- }
-
- /**
- * The location of the terminal.
- */
- export enum TerminalLocation {
- /**
- * In the terminal view
- */
- Panel = 1,
- /**
- * In the editor area
- */
- Editor = 2,
- }
-
- /**
- * Assumes a {@link TerminalLocation} of editor and allows specifying a {@link ViewColumn} and
- * {@link TerminalEditorLocationOptions.preserveFocus preserveFocus } property
- */
- export interface TerminalEditorLocationOptions {
- /**
- * A view column in which the {@link Terminal terminal} should be shown in the editor area.
- * The default is the {@link ViewColumn.Active active}. Columns that do not exist
- * will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}.
- * Use {@linkcode 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 Terminal} from taking focus.
- */
- preserveFocus?: boolean;
- }
-
- /**
- * Uses the parent {@link Terminal}'s location for the terminal
- */
- export interface TerminalSplitLocationOptions {
- /**
- * The parent terminal to split this terminal beside. This works whether the parent terminal
- * is in the panel or the editor area.
- */
- parentTerminal: Terminal;
- }
-
- /**
- * Represents the state of a {@link Terminal}.
- */
- export interface TerminalState {
- /**
- * Whether the {@link Terminal} has been interacted with. Interaction means that the
- * terminal has sent data to the process which depending on the terminal's _mode_. By
- * default input is sent when a key is pressed or when a command or extension sends text,
- * but based on the terminal's mode it can also happen on:
- *
- * - a pointer click event
- * - a pointer scroll event
- * - a pointer move event
- * - terminal focus in/out
- *
- * For more information on events that can send data see "DEC Private Mode Set (DECSET)" on
- * https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- */
- readonly isInteractedWith: boolean;
- }
-
- /**
- * 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.
- * @returns 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 class 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;
-
- /**
- * Creates a new terminal link.
- * @param startIndex The start index of the link on {@link TerminalLinkContext.line}.
- * @param length The length of the link on {@link TerminalLinkContext.line}.
- * @param tooltip 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.
- */
- constructor(startIndex: number, length: number, tooltip?: string);
- }
-
- /**
- * Provides a terminal profile for the contributed terminal profile when launched via the UI or
- * command.
- */
- export interface TerminalProfileProvider {
- /**
- * Provide the terminal profile.
- * @param token A cancellation token that indicates the result is no longer needed.
- * @returns The terminal profile.
- */
- provideTerminalProfile(token: CancellationToken): ProviderResult;
- }
-
- /**
- * A terminal profile defines how a terminal will be launched.
- */
- export class TerminalProfile {
- /**
- * The options that the terminal will launch with.
- */
- options: TerminalOptions | ExtensionTerminalOptions;
-
- /**
- * Creates a new terminal profile.
- * @param options The options that the terminal will launch with.
- */
- constructor(options: TerminalOptions | ExtensionTerminalOptions);
- }
-
- /**
- * 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 {@linkcode ExtensionKind.UI}.
- */
- extensionKind: ExtensionKind;
-
- /**
- * The public API exported by this extension (return value of `activate`).
- * 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.
- *
- * @returns 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 the editor.
- */
- Production = 1,
-
- /**
- * The extension is running from an `--extensionDevelopmentPath` provided
- * when launching the editor.
- */
- 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.
- *
- * *Note* that asynchronous dispose-functions aren't awaited.
- */
- readonly subscriptions: {
- /**
- * Function to clean up resources.
- */
- 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: readonly string[]): void;
- };
-
- /**
- * A storage utility for secrets. Secrets are persisted across reloads and are independent of the
- * current opened {@link workspace.workspaceFolders workspace}.
- */
- 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 global environment variable collection for this workspace, enabling changes to be
- * applied to terminal environment variables.
- */
- readonly environmentVariableCollection: GlobalEnvironmentVariableCollection;
-
- /**
- * Get the absolute path of a resource contained in the extension.
- *
- * *Note* that an absolute uri can be constructed via {@linkcode Uri.joinPath} and
- * {@linkcode ExtensionContext.extensionUri extensionUri}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);`
- *
- * @param relativePath A relative path to a resource contained in the extension.
- * @returns 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 {@linkcode ExtensionContext.workspaceState workspaceState} or
- * {@linkcode ExtensionContext.globalState globalState} to store key value data.
- *
- * @see {@linkcode 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 {@linkcode ExtensionContext.workspaceState workspaceState} or
- * {@linkcode 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 {@linkcode ExtensionContext.globalState globalState} to store key value data.
- *
- * @see {@linkcode 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 {@linkcode 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 {@linkcode 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. See {@link ExtensionMode}
- * for possible values and scenarios.
- */
- 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 {
-
- /**
- * Returns the stored keys.
- *
- * @returns The stored keys.
- */
- keys(): readonly string[];
-
- /**
- * Return a value.
- *
- * @param key A string.
- * @returns 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.
- * @returns The stored value or the defaultValue.
- */
- get(key: string, defaultValue: T): T;
-
- /**
- * Store a value. The value must be JSON-stringifyable.
- *
- * *Note* that using `undefined` as value removes the key from the underlying
- * storage.
- *
- * @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 {
- /**
- * A light color theme.
- */
- Light = 1,
- /**
- * A dark color theme.
- */
- Dark = 2,
- /**
- * A dark high contrast color theme.
- */
- HighContrast = 3,
- /**
- * A light high contrast color theme.
- */
- HighContrastLight = 4
- }
-
- /**
- * Represents a color theme.
- */
- export interface ColorTheme {
-
- /**
- * The kind of this color theme: light, dark, high contrast dark and high contrast light.
- */
- 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;
-
- /**
- * Controls whether the terminal is closed after executing the task.
- */
- close?: 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;
-
- /**
- * Whether the task that is part of this group is the default for the group.
- * This property cannot be set through API, and is controlled by a user's task configurations.
- */
- readonly isDefault: boolean | undefined;
-
- /**
- * The ID of the task group. Is one of TaskGroup.Clean.id, TaskGroup.Build.id, TaskGroup.Rebuild.id, or TaskGroup.Test.id.
- */
- readonly id: string;
-
- /**
- * Private constructor
- *
- * @param id Identifier of a task group.
- * @param label The human-readable name of a task group.
- */
- 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;
- }
-
- /**
- * Represents a task execution that happens inside a shell.
- */
- 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 the editor 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 taskDefinition 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 taskDefinition 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 | undefined;
-
- /**
- * 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.
- * @returns an array of tasks
- */
- provideTasks(token: CancellationToken): ProviderResult;
-
- /**
- * Resolves a task that has no {@linkcode 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.
- * @returns 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;
- }
-
- /**
- * A task filter denotes tasks by their version and types
- */
- 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.
- * @returns 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.
- * @returns A thenable that resolves to an array of tasks.
- */
- export function fetchTasks(filter?: TaskFilter): Thenable;
-
- /**
- * Executes a task that is managed by the editor. 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
- * @returns A thenable that resolves to a task execution.
- */
- export function executeTask(task: Task): Thenable;
-
- /**
- * The currently active task executions or an empty array.
- */
- export const taskExecutions: readonly TaskExecution[];
-
- /**
- * 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
- }
-
- /**
- * Permissions of a file.
- */
- export enum FilePermission {
- /**
- * The file is readonly.
- *
- * *Note:* All `FileStat` from a `FileSystemProvider` that is registered with
- * the option `isReadonly: true` will be implicitly handled as if `FilePermission.Readonly`
- * is set. As a consequence, it is not possible to have a readonly file system provider
- * registered where some `FileStat` are not readonly.
- */
- Readonly = 1
- }
-
- /**
- * 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;
- /**
- * The permissions of the file, e.g. whether the file is readonly.
- *
- * *Note:* This value might be a bitmask, e.g. `FilePermission.Readonly | FilePermission.Other`.
- */
- permissions?: FilePermission;
- }
-
- /**
- * 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 {@linkcode 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;
-
- /**
- * Subscribes to file change events in the file or folder denoted by `uri`. For folders,
- * the option `recursive` indicates whether subfolders, sub-subfolders, etc. should
- * be watched for file changes as well. With `recursive: false`, only changes to the
- * files that are direct children of the folder should trigger an event.
- *
- * The `excludes` array is used to indicate paths that should be excluded from file
- * watching. It is typically derived from the `files.watcherExclude` setting that
- * is configurable by the user. Each entry can be be:
- * - the absolute path to exclude
- * - a relative path to exclude (for example `build/output`)
- * - a simple glob pattern (for example `**/build`, `output/**`)
- *
- * It is the file system provider's job to call {@linkcode FileSystemProvider.onDidChangeFile onDidChangeFile}
- * for every change given these rules. No event should be emitted for files that match any of the provided
- * excludes.
- *
- * @param uri The uri of the file or folder to be watched.
- * @param options Configures the watch.
- * @returns A disposable that tells the provider to stop watching the `uri`.
- */
- watch(uri: Uri, options: {
- /**
- * When enabled also watch subfolders.
- */
- readonly recursive: boolean;
- /**
- * A list of paths and pattern to exclude from watching.
- */
- readonly excludes: readonly 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.
- * @returns The file metadata about the file.
- * @throws {@linkcode 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.
- * @returns An array of name/type-tuples or a thenable that resolves to such.
- * @throws {@linkcode 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 {@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required.
- * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists.
- * @throws {@linkcode 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.
- * @returns An array of bytes or a thenable that resolves to such.
- * @throws {@linkcode 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 {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist and `create` is not set.
- * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required.
- * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists, `create` is set but `overwrite` is not set.
- * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
- */
- writeFile(uri: Uri, content: Uint8Array, options: {
- /**
- * Create the file if it does not exist already.
- */
- readonly create: boolean;
- /**
- * Overwrite the file if it does exist.
- */
- readonly 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 {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist.
- * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
- */
- delete(uri: Uri, options: {
- /**
- * Delete the content recursively if a folder is denoted.
- */
- readonly 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 {@linkcode FileSystemError.FileNotFound FileNotFound} when `oldUri` doesn't exist.
- * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required.
- * @throws {@linkcode FileSystemError.FileExists FileExists} when `newUri` exists and when the `overwrite` option is not `true`.
- * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
- */
- rename(oldUri: Uri, newUri: Uri, options: {
- /**
- * Overwrite the file if it does exist.
- */
- readonly 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 {@linkcode FileSystemError.FileNotFound FileNotFound} when `source` doesn't exist.
- * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when parent of `destination` doesn't exist, e.g. no mkdirp-logic required.
- * @throws {@linkcode FileSystemError.FileExists FileExists} when `destination` exists and when the `overwrite` option is not `true`.
- * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
- */
- copy?(source: Uri, destination: Uri, options: {
- /**
- * Overwrite the file if it does exist.
- */
- readonly 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 {@linkcode workspace.fs}.
- */
- export interface FileSystem {
-
- /**
- * Retrieve metadata about a file.
- *
- * @param uri The uri of the file to retrieve metadata about.
- * @returns 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.
- * @returns 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.
- * @returns 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?: {
- /**
- * Delete the content recursively if a folder is denoted.
- */
- recursive?: boolean;
- /**
- * Use the os's trashcan instead of permanently deleting files whenever possible.
- */
- useTrash?: boolean;
- }): Thenable;
-
- /**
- * Rename a file or folder.
- *
- * @param source The existing file.
- * @param target The new location.
- * @param options Defines if existing files should be overwritten.
- */
- rename(source: Uri, target: Uri, options?: {
- /**
- * Overwrite the file if it does exist.
- */
- overwrite?: boolean;
- }): Thenable;
-
- /**
- * Copy files or folders.
- *
- * @param source The existing file.
- * @param target The destination location.
- * @param options Defines if existing files should be overwritten.
- */
- copy(source: Uri, target: Uri, options?: {
- /**
- * Overwrite the file if it does exist.
- */
- 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`.
- *
- * @returns `true` if the file system supports writing, `false` if it does not
- * support writing (i.e. it is readonly), and `undefined` if the editor 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 forms are enabled in the webview content or not.
- *
- * Defaults to true if {@link WebviewOptions.enableScripts scripts are enabled}. Otherwise defaults to false.
- * Explicitly setting this property to either true or false overrides the default.
- */
- readonly enableForms?: boolean;
-
- /**
- * Controls whether command uris are enabled in webview content or not.
- *
- * Defaults to `false` (command uris are disabled).
- *
- * If you pass in an array, only the commands in the array are allowed.
- */
- readonly enableCommandUris?: boolean | readonly string[];
-
- /**
- * 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?: readonly Uri[];
-
- /**
- * 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?: readonly WebviewPortMapping[];
- }
-
- /**
- * 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 {@linkcode 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 the editor's api and then call `.postMessage()`:
- *
- * ```html
- *
- * ```
- *
- * To load a resources from the workspace inside a webview, use the {@linkcode Webview.asWebviewUri asWebviewUri} method
- * and ensure the resource's directory is listed in {@linkcode 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 an 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.
- *
- * @returns A promise that resolves when the message is posted to a webview or when it is
- * dropped because the message was not deliverable.
- *
- * Returns `true` if the message was posted to the webview. Messages can only be posted to
- * live webviews (i.e. either visible webviews or hidden webviews that set `retainContextWhenHidden`).
- *
- * A response of `true` does not mean that the message was actually received by the webview.
- * For example, no message listeners may be have been hooked up inside the webview or the webview may
- * have been destroyed after the message was posted but before it was received.
- *
- * If you want confirm that a message as actually received, you can try having your webview posting a
- * confirmation message back to your extension.
- */
- 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:
- *
- * ```ts
- * `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 the editor 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 | {
- /**
- * The icon path for the light theme.
- */
- readonly light: Uri;
- /**
- * The icon path for the dark theme.
- */
- readonly dark: Uri;
- };
-
- /**
- * {@linkcode 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 | undefined;
-
- /**
- * 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 the editor).
- *
- * 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 the editor. When the editor is shutdown,
- * it 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.
- *
- * @returns 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;
-
- /**
- * The badge to display for this webview view.
- * To remove the badge, set to undefined.
- */
- badge?: ViewBadge | undefined;
-
- /**
- * 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, the editor 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 })
- * ```
- *
- * The editor 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.
- *
- * @returns 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 {@linkcode TextDocument} as their data model. This considerably simplifies
- * implementing a custom editor as it allows the editor 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 {@linkcode WebviewPanel} for additional details.
- *
- * @param token A cancellation token that indicates the result is no longer needed.
- *
- * @returns 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 {@linkcode CustomEditorProvider}.
- *
- * Custom documents are only used within a given `CustomEditorProvider`. The lifecycle of a `CustomDocument` is
- * managed by the editor. 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 the editor 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 the editor that an edit has occurred on an {@linkcode CustomDocument}.
- *
- * @see {@linkcode CustomEditorProvider.onDidChangeCustomDocument}.
- */
- interface CustomDocumentEditEvent {
-
- /**
- * The document that the edit is for.
- */
- readonly document: T;
-
- /**
- * Undo the edit operation.
- *
- * This is invoked by the editor 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 the editor's internal edit stack by `onDidChangeCustomDocument`.
- */
- undo(): Thenable | void;
-
- /**
- * Redo the edit operation.
- *
- * This is invoked by the editor 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 the editor'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 the editor that the content of a {@linkcode CustomDocument}
- * has changed.
- *
- * @see {@linkcode CustomEditorProvider.onDidChangeCustomDocument}.
- */
- interface CustomDocumentContentChangeEvent {
- /**
- * The document that the change is for.
- */
- readonly document: T;
- }
-
- /**
- * A backup for an {@linkcode 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 the editor 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 {@linkcode CustomDocumentBackup}.
- */
- 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 | undefined;
-
- /**
- * 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 | undefined;
- }
-
- /**
- * Provider for readonly custom editors that use a custom document model.
- *
- * Custom editors use {@linkcode CustomDocument} as their document model instead of a {@linkcode TextDocument}.
- *
- * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple
- * text based documents, use {@linkcode 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.
- *
- * @returns 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 {@linkcode WebviewPanel} for additional details.
- *
- * @param token A cancellation token that indicates the result is no longer needed.
- *
- * @returns 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 {@linkcode CustomDocument} as their document model instead of a {@linkcode 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 {@linkcode 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 the editors to be marked 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 the editor's standard keyboard shortcuts. The editor 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 the editor'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 the editor 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).
- *
- * @returns 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 the editor 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.
- *
- * @returns 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 the editor when the user triggers `File: Revert File` in a custom editor. (Note that
- * this is only used using the editor'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.
- *
- * @returns 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 the editor 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 the editor 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
- }
-
- /**
- * Log levels
- */
- export enum LogLevel {
-
- /**
- * No messages are logged with this level.
- */
- Off = 0,
-
- /**
- * All messages are logged with this level.
- */
- Trace = 1,
-
- /**
- * Messages with debug and higher log level are logged with this level.
- */
- Debug = 2,
-
- /**
- * Messages with info and higher log level are logged with this level.
- */
- Info = 3,
-
- /**
- * Messages with warning and higher log level are logged with this level.
- */
- Warning = 4,
-
- /**
- * Only error messages are logged with this level.
- */
- Error = 5
- }
-
- /**
- * 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 hosted location of the application
- * On desktop this is 'desktop'
- * In the web this is the specified embedder i.e. 'github.dev', 'codespaces', or 'web' if the embedder
- * does not provide that information
- */
- export const appHost: 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;
-
- /**
- * An {@link Event} which fires when the default shell changes. This fires with the new
- * shell path.
- */
- export const onDidChangeShell: Event;
-
- /**
- * Creates a new {@link TelemetryLogger telemetry logger}.
- *
- * @param sender The telemetry sender that is used by the telemetry logger.
- * @param options Options for the telemetry logger.
- * @returns A new telemetry logger
- */
- export function createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger;
-
- /**
- * 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.defaultProfile` 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 {@linkcode 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 a form that is accessible externally.
- *
- * #### `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 the editor 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 any way.
- * 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`.
- *
- * #### Any other scheme
- *
- * Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return
- * a URI which, when handled, will make the editor open the workspace.
- *
- * @returns A uri that can be used on the client machine.
- */
- export function asExternalUri(target: Uri): Thenable;
-
- /**
- * The current log level of the editor.
- */
- export const logLevel: LogLevel;
-
- /**
- * An {@link Event} which fires when the log level of the editor changes.
- */
- export const onDidChangeLogLevel: Event;
- }
-
- /**
- * 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#_advanced-customization)
- * 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.
- * @returns 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.
- * @returns 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 {@linkcode Position}, {@linkcode Range}, {@linkcode Uri} and {@linkcode 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.
- * @returns A thenable that resolves to the returned value of the given command. Returns `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)
- * @returns 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 {
-
- /**
- * Represents the grid widget within the main editor area
- */
- export const tabGroups: TabGroups;
-
- /**
- * 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: readonly 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 visible {@link NotebookEditor notebook editors} or an empty array.
- */
- export const visibleNotebookEditors: readonly NotebookEditor[];
-
- /**
- * An {@link Event} which fires when the {@link window.visibleNotebookEditors visible notebook editors}
- * has changed.
- */
- export const onDidChangeVisibleNotebookEditors: Event;
-
- /**
- * The currently active {@link NotebookEditor notebook 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 const activeNotebookEditor: NotebookEditor | undefined;
-
- /**
- * An {@link Event} which fires when the {@link window.activeNotebookEditor active notebook editor}
- * has changed. *Note* that the event also fires when the active editor changes
- * to `undefined`.
- */
- export const onDidChangeActiveNotebookEditor: Event;
-
- /**
- * An {@link Event} which fires when the {@link NotebookEditor.selections notebook editor selections}
- * have changed.
- */
- export const onDidChangeNotebookEditorSelection: Event;
-
- /**
- * An {@link Event} which fires when the {@link NotebookEditor.visibleRanges notebook editor visible ranges}
- * have changed.
- */
- export const onDidChangeNotebookEditorVisibleRanges: Event;
-
- /**
- * The currently opened terminals or an empty array.
- */
- export const terminals: readonly Terminal[];
-
- /**
- * 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;
-
- /**
- * An {@link Event} which fires when a {@link Terminal.state terminal's state} has changed.
- */
- export const onDidChangeTerminalState: 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}.
- * Columns that do not exist will be created as needed up to the maximum of {@linkcode ViewColumn.Nine}. Use {@linkcode ViewColumn.Beside}
- * to open the editor to the side of the currently active one.
- * @param preserveFocus When `true` the editor will not take focus.
- * @returns 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}.
- * @returns 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 workspace.openTextDocument}
- *
- * @param uri A resource identifier.
- * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}.
- * @returns A promise that resolves to an {@link TextEditor editor}.
- */
- export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable;
-
- /**
- * Show the given {@link NotebookDocument} in a {@link NotebookEditor notebook editor}.
- *
- * @param document A text document to be shown.
- * @param options {@link NotebookDocumentShowOptions Editor options} to configure the behavior of showing the {@link NotebookEditor notebook editor}.
- *
- * @returns A promise that resolves to an {@link NotebookEditor notebook editor}.
- */
- export function showNotebookDocument(document: NotebookDocument, options?: NotebookDocumentShowOptions): Thenable;
-
- /**
- * Create a TextEditorDecorationType that can be used to add decorations to text editors.
- *
- * @param options Rendering options for the decoration type.
- * @returns 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.
- * @returns 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 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.
- * @returns A thenable that resolves to the selected item or `undefined` when being dismissed.
- */
- export function showInformationMessage(message: string, options: MessageOptions, ...items: T[]): 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.
- * @returns 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.
- * @returns 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.
- * @returns 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.
- * @returns A thenable that resolves to the selected item or `undefined` when being dismissed.
- */
- export function showWarningMessage(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.
- * @returns 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.
- * @returns 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.
- * @returns 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.
- * @returns A thenable that resolves to the selected item or `undefined` when being dismissed.
- */
- export function showErrorMessage(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.
- * @returns 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.
- * @returns 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.
- * @returns A promise that resolves to the selected items or `undefined`.
- */
- export function showQuickPick(items: readonly string[] | Thenable, options: QuickPickOptions & { /** literal-type defines return type */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.
- * @returns A promise that resolves to the selection or `undefined`.
- */
- export function showQuickPick(items: readonly 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.
- * @returns A promise that resolves to the selected items or `undefined`.
- */
- export function showQuickPick(items: readonly T[] | Thenable, options: QuickPickOptions & { /** literal-type defines return type */ 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.
- * @returns A promise that resolves to the selected item or `undefined`.
- */
- export function showQuickPick(items: readonly 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.
- * @returns 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.
- * @returns 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.
- *
- * @returns 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.
- *
- * @returns A new {@link InputBox}.
- */
- export function createInputBox(): InputBox;
-
- /**
- * Creates a new {@link OutputChannel output channel} with the given name and language id
- * If language id is not provided, then **Log** is used as default language id.
- *
- * You can access the visible or active output channel as a {@link TextDocument text document} from {@link window.visibleTextEditors visible editors} or {@link window.activeTextEditor active editor}
- * and use the language id to contribute language features like syntax coloring, code lens etc.,
- *
- * @param name Human-readable string which will be used to represent the channel in the UI.
- * @param languageId The identifier of the language associated with the channel.
- * @returns A new output channel.
- */
- export function createOutputChannel(name: string, languageId?: string): OutputChannel;
-
- /**
- * Creates a new {@link LogOutputChannel log output channel} with the given name.
- *
- * @param name Human-readable string which will be used to represent the channel in the UI.
- * @param options Options for the log output channel.
- * @returns A new log output channel.
- */
- export function createOutputChannel(name: string, options: { /** literal-type defines return type */log: true }): LogOutputChannel;
-
- /**
- * 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.
- *
- * @returns New webview panel.
- */
- export function createWebviewPanel(viewType: string, title: string, showOptions: ViewColumn | {
- /**
- * The view column in which the {@link WebviewPanel} should be shown.
- */
- readonly viewColumn: ViewColumn;
- /**
- * An optional flag that when `true` will stop the panel from taking focus.
- */
- readonly 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.
- * @returns 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.
- * @returns 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}.
- * @returns 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.
- * @returns 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 {@linkcode ProgressOptions}.
- *
- * @param options A {@linkcode ProgressOptions}-object describing the options to use for showing progress, like its location
- * @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 {@linkcode CancellationToken}.
- * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the
- * long running operation.
- *
- * @returns The thenable the task-callback returned.
- */
- export function withProgress(options: ProgressOptions, task: (progress: Progress<{
- /**
- * A progress message that represents a chunk of work
- */
- message?: string;
- /**
- * An increment for discrete progress. Increments will be summed up until 100% is reached
- */
- increment?: number;
- }>, token: CancellationToken) => Thenable): Thenable;
-
- /**
- * Creates a status bar {@link StatusBarItem item}.
- *
- * @param id The identifier of the item. Must be unique within the extension.
- * @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.
- * @returns A new status bar item.
- */
- export function createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem;
-
- /**
- * Creates a status bar {@link StatusBarItem item}.
- *
- * @see {@link createStatusBarItem} for creating a status bar item with an identifier.
- * @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.
- * @returns 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).
- * @returns A new Terminal.
- * @throws When running in an environment where a new process cannot be started.
- */
- export function createTerminal(name?: string, shellPath?: string, shellArgs?: readonly string[] | string): Terminal;
-
- /**
- * Creates a {@link Terminal} with a backing shell process.
- *
- * @param options A TerminalOptions object describing the characteristics of the new terminal.
- * @returns 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.
- * @returns 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
- * @returns A {@link Disposable disposable} that unregisters the {@link TreeDataProvider}.
- */
- 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.
- * @returns A {@link Disposable disposable} that unregisters the handler.
- */
- 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 `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.
- * @returns A {@link Disposable disposable} that unregisters the 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.
- *
- * @returns 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 the editor 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, an `onCustomEditor:viewType` activation event is fired. Your extension
- * must register a {@linkcode CustomTextEditorProvider}, {@linkcode CustomReadonlyEditorProvider},
- * {@linkcode 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.
- *
- * @returns 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, the editor 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.
- * @returns Disposable that unregisters the provider.
- */
- export function registerTerminalLinkProvider(provider: TerminalLinkProvider): Disposable;
-
- /**
- * Registers a provider for a contributed terminal profile.
- *
- * @param id The ID of the contributed terminal profile.
- * @param provider The terminal profile provider.
- * @returns A {@link Disposable disposable} that unregisters the provider.
- */
- export function registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable;
- /**
- * Register a file decoration provider.
- *
- * @param provider A {@link FileDecorationProvider}.
- * @returns 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
)})
`
- * ```
- */
- 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:
- *
- * ```ts
- * `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 the editor 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 | {
- /**
- * The icon path for the light theme.
- */
- readonly light: Uri;
- /**
- * The icon path for the dark theme.
- */
- readonly dark: Uri;
- };
-
- /**
- * {@linkcode 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 | undefined;
-
- /**
- * 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