Permalink
Switch branches/tags
Find file Copy path
8505 lines (7488 sloc) 273 KB
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
declare module 'vscode' {
/**
* The version of the editor.
*/
export const version: string;
/**
* Represents a reference to a command. Provides a title which
* will be used to represent a command in the UI and, optionally,
* an array of arguments which will be passed to the command handler
* function when invoked.
*/
export interface Command {
/**
* Title of the command, like `save`.
*/
title: string;
/**
* The identifier of the actual command handler.
* @see [commands.registerCommand](#commands.registerCommand).
*/
command: string;
/**
* A tooltip for the command, when represented in the UI.
*/
tooltip?: string;
/**
* Arguments that the command handler should be
* invoked with.
*/
arguments?: any[];
}
/**
* Represents a line of text, such as a line of source code.
*
* TextLine objects are __immutable__. When a [document](#TextDocument) changes,
* previously retrieved lines will not represent the latest state.
*/
export interface TextLine {
/**
* The zero-based line number.
*/
readonly lineNumber: number;
/**
* The text of this line without the line separator characters.
*/
readonly text: string;
/**
* The range this line covers without the line separator characters.
*/
readonly range: Range;
/**
* The range this line covers with the line separator characters.
*/
readonly rangeIncludingLineBreak: Range;
/**
* The offset of the first character which is not a whitespace character as defined
* by `/\s/`. **Note** that if a line is all whitespaces the length of the line is returned.
*/
readonly firstNonWhitespaceCharacterIndex: number;
/**
* Whether this line is whitespace only, shorthand
* for [TextLine.firstNonWhitespaceCharacterIndex](#TextLine.firstNonWhitespaceCharacterIndex) === [TextLine.text.length](#TextLine.text).
*/
readonly isEmptyOrWhitespace: boolean;
}
/**
* Represents a text document, such as a source file. Text documents have
* [lines](#TextLine) and knowledge about an underlying resource like a file.
*/
export interface TextDocument {
/**
* The associated uri for this document.
*
* *Note* that most documents use the `file`-scheme, which means they are files on disk. However, **not** all documents are
* saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk.
*
* @see [FileSystemProvider](#FileSystemProvider)
* @see [TextDocumentContentProvider](#TextDocumentContentProvider)
*/
readonly uri: Uri;
/**
* The file system path of the associated resource. Shorthand
* notation for [TextDocument.uri.fsPath](#TextDocument.uri). Independent of the uri scheme.
*/
readonly fileName: string;
/**
* Is this document representing an untitled file which has never been saved yet. *Note* that
* this does not mean the document will be saved to disk, use [`uri.scheme`](#Uri.scheme)
* to figure out where a document will be [saved](#FileSystemProvider), e.g. `file`, `ftp` etc.
*/
readonly isUntitled: boolean;
/**
* The identifier of the language associated with this document.
*/
readonly languageId: string;
/**
* The version number of this document (it will strictly increase after each
* change, including undo/redo).
*/
readonly version: number;
/**
* `true` if there are unpersisted changes.
*/
readonly isDirty: boolean;
/**
* `true` if the document have been closed. A closed document isn't synchronized anymore
* and won't be re-used when the same resource is opened again.
*/
readonly isClosed: boolean;
/**
* Save the underlying file.
*
* @return A promise that will resolve to true when the file
* has been saved. If the file was not dirty or the save failed,
* will return false.
*/
save(): Thenable<boolean>;
/**
* The [end of line](#EndOfLine) sequence that is predominately
* used in this document.
*/
readonly eol: EndOfLine;
/**
* The number of lines in this document.
*/
readonly lineCount: number;
/**
* Returns a text line denoted by the line number. Note
* that the returned object is *not* live and changes to the
* document are not reflected.
*
* @param line A line number in [0, lineCount).
* @return A [line](#TextLine).
*/
lineAt(line: number): TextLine;
/**
* Returns a text line denoted by the position. Note
* that the returned object is *not* live and changes to the
* document are not reflected.
*
* The position will be [adjusted](#TextDocument.validatePosition).
*
* @see [TextDocument.lineAt](#TextDocument.lineAt)
* @param position A position.
* @return A [line](#TextLine).
*/
lineAt(position: Position): TextLine;
/**
* Converts the position to a zero-based offset.
*
* The position will be [adjusted](#TextDocument.validatePosition).
*
* @param position A position.
* @return A valid zero-based offset.
*/
offsetAt(position: Position): number;
/**
* Converts a zero-based offset to a position.
*
* @param offset A zero-based offset.
* @return A valid [position](#Position).
*/
positionAt(offset: number): Position;
/**
* Get the text of this document. A substring can be retrieved by providing
* a range. The range will be [adjusted](#TextDocument.validateRange).
*
* @param range Include only the text included by the range.
* @return The text inside the provided range or the entire text.
*/
getText(range?: Range): string;
/**
* Get a word-range at the given position. By default words are defined by
* common separators, like space, -, _, etc. In addition, per language custom
* [word definitions](#LanguageConfiguration.wordPattern) can be defined. It
* is also possible to provide a custom regular expression.
*
* * *Note 1:* A custom regular expression must not match the empty string and
* if it does, it will be ignored.
* * *Note 2:* A custom regular expression will fail to match multiline strings
* and in the name of speed regular expressions should not match words with
* spaces. Use [`TextLine.text`](#TextLine.text) for more complex, non-wordy, scenarios.
*
* The position will be [adjusted](#TextDocument.validatePosition).
*
* @param position A position.
* @param regex Optional regular expression that describes what a word is.
* @return A range spanning a word, or `undefined`.
*/
getWordRangeAtPosition(position: Position, regex?: RegExp): Range | undefined;
/**
* Ensure a range is completely contained in this document.
*
* @param range A range.
* @return The given range or a new, adjusted range.
*/
validateRange(range: Range): Range;
/**
* Ensure a position is contained in the range of this document.
*
* @param position A position.
* @return The given position or a new, adjusted position.
*/
validatePosition(position: Position): Position;
}
/**
* Represents a line and character position, such as
* the position of the cursor.
*
* Position objects are __immutable__. Use the [with](#Position.with) or
* [translate](#Position.translate) methods to derive new positions
* from an existing position.
*/
export class Position {
/**
* The zero-based line value.
*/
readonly line: number;
/**
* The zero-based character value.
*/
readonly character: number;
/**
* @param line A zero-based line value.
* @param character A zero-based character value.
*/
constructor(line: number, character: number);
/**
* Check if this position is before `other`.
*
* @param other A position.
* @return `true` if position is on a smaller line
* or on the same line on a smaller character.
*/
isBefore(other: Position): boolean;
/**
* Check if this position is before or equal to `other`.
*
* @param other A position.
* @return `true` if position is on a smaller line
* or on the same line on a smaller or equal character.
*/
isBeforeOrEqual(other: Position): boolean;
/**
* Check if this position is after `other`.
*
* @param other A position.
* @return `true` if position is on a greater line
* or on the same line on a greater character.
*/
isAfter(other: Position): boolean;
/**
* Check if this position is after or equal to `other`.
*
* @param other A position.
* @return `true` if position is on a greater line
* or on the same line on a greater or equal character.
*/
isAfterOrEqual(other: Position): boolean;
/**
* Check if this position is equal to `other`.
*
* @param other A position.
* @return `true` if the line and character of the given position are equal to
* the line and character of this position.
*/
isEqual(other: Position): boolean;
/**
* Compare this to `other`.
*
* @param other A position.
* @return A number smaller than zero if this position is before the given position,
* a number greater than zero if this position is after the given position, or zero when
* this and the given position are equal.
*/
compareTo(other: Position): number;
/**
* Create a new position relative to this position.
*
* @param lineDelta Delta value for the line value, default is `0`.
* @param characterDelta Delta value for the character value, default is `0`.
* @return A position which line and character is the sum of the current line and
* character and the corresponding deltas.
*/
translate(lineDelta?: number, characterDelta?: number): Position;
/**
* Derived a new position relative to this position.
*
* @param change An object that describes a delta to this position.
* @return A position that reflects the given delta. Will return `this` position if the change
* is not changing anything.
*/
translate(change: { lineDelta?: number; characterDelta?: number; }): Position;
/**
* Create a new position derived from this position.
*
* @param line Value that should be used as line value, default is the [existing value](#Position.line)
* @param character Value that should be used as character value, default is the [existing value](#Position.character)
* @return A position where line and character are replaced by the given values.
*/
with(line?: number, character?: number): Position;
/**
* Derived a new position from this position.
*
* @param change An object that describes a change to this position.
* @return A position that reflects the given change. Will return `this` position if the change
* is not changing anything.
*/
with(change: { line?: number; character?: number; }): Position;
}
/**
* A range represents an ordered pair of two positions.
* It is guaranteed that [start](#Range.start).isBeforeOrEqual([end](#Range.end))
*
* Range objects are __immutable__. Use the [with](#Range.with),
* [intersection](#Range.intersection), or [union](#Range.union) methods
* to derive new ranges from an existing range.
*/
export class Range {
/**
* The start position. It is before or equal to [end](#Range.end).
*/
readonly start: Position;
/**
* The end position. It is after or equal to [start](#Range.start).
*/
readonly end: Position;
/**
* Create a new range from two positions. If `start` is not
* before or equal to `end`, the values will be swapped.
*
* @param start A position.
* @param end A position.
*/
constructor(start: Position, end: Position);
/**
* Create a new range from number coordinates. It is a shorter equivalent of
* using `new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))`
*
* @param startLine A zero-based line value.
* @param startCharacter A zero-based character value.
* @param endLine A zero-based line value.
* @param endCharacter A zero-based character value.
*/
constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number);
/**
* `true` if `start` and `end` are equal.
*/
isEmpty: boolean;
/**
* `true` if `start.line` and `end.line` are equal.
*/
isSingleLine: boolean;
/**
* Check if a position or a range is contained in this range.
*
* @param positionOrRange A position or a range.
* @return `true` if the position or range is inside or equal
* to this range.
*/
contains(positionOrRange: Position | Range): boolean;
/**
* Check if `other` equals this range.
*
* @param other A range.
* @return `true` when start and end are [equal](#Position.isEqual) to
* start and end of this range.
*/
isEqual(other: Range): boolean;
/**
* Intersect `range` with this range and returns a new range or `undefined`
* if the ranges have no overlap.
*
* @param range A range.
* @return A range of the greater start and smaller end positions. Will
* return undefined when there is no overlap.
*/
intersection(range: Range): Range | undefined;
/**
* Compute the union of `other` with this range.
*
* @param other A range.
* @return A range of smaller start position and the greater end position.
*/
union(other: Range): Range;
/**
* Derived a new range from this range.
*
* @param start A position that should be used as start. The default value is the [current start](#Range.start).
* @param end A position that should be used as end. The default value is the [current end](#Range.end).
* @return A range derived from this range with the given start and end position.
* If start and end are not different `this` range will be returned.
*/
with(start?: Position, end?: Position): Range;
/**
* Derived a new range from this range.
*
* @param change An object that describes a change to this range.
* @return A range that reflects the given change. Will return `this` range if the change
* is not changing anything.
*/
with(change: { start?: Position, end?: Position }): Range;
}
/**
* Represents a text selection in an editor.
*/
export class Selection extends Range {
/**
* The position at which the selection starts.
* This position might be before or after [active](#Selection.active).
*/
anchor: Position;
/**
* The position of the cursor.
* This position might be before or after [anchor](#Selection.anchor).
*/
active: Position;
/**
* Create a selection from two positions.
*
* @param anchor A position.
* @param active A position.
*/
constructor(anchor: Position, active: Position);
/**
* Create a selection from four coordinates.
*
* @param anchorLine A zero-based line value.
* @param anchorCharacter A zero-based character value.
* @param activeLine A zero-based line value.
* @param activeCharacter A zero-based character value.
*/
constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number);
/**
* A selection is reversed if [active](#Selection.active).isBefore([anchor](#Selection.anchor)).
*/
isReversed: boolean;
}
/**
* Represents sources that can cause [selection change events](#window.onDidChangeTextEditorSelection).
*/
export enum TextEditorSelectionChangeKind {
/**
* Selection changed due to typing in the editor.
*/
Keyboard = 1,
/**
* Selection change due to clicking in the editor.
*/
Mouse = 2,
/**
* Selection changed because a command ran.
*/
Command = 3
}
/**
* Represents an event describing the change in a [text editor's selections](#TextEditor.selections).
*/
export interface TextEditorSelectionChangeEvent {
/**
* The [text editor](#TextEditor) for which the selections have changed.
*/
textEditor: TextEditor;
/**
* The new value for the [text editor's selections](#TextEditor.selections).
*/
selections: Selection[];
/**
* The [change kind](#TextEditorSelectionChangeKind) which has triggered this
* event. Can be `undefined`.
*/
kind?: TextEditorSelectionChangeKind;
}
/**
* Represents an event describing the change in a [text editor's visible ranges](#TextEditor.visibleRanges).
*/
export interface TextEditorVisibleRangesChangeEvent {
/**
* The [text editor](#TextEditor) for which the visible ranges have changed.
*/
textEditor: TextEditor;
/**
* The new value for the [text editor's visible ranges](#TextEditor.visibleRanges).
*/
visibleRanges: Range[];
}
/**
* Represents an event describing the change in a [text editor's options](#TextEditor.options).
*/
export interface TextEditorOptionsChangeEvent {
/**
* The [text editor](#TextEditor) for which the options have changed.
*/
textEditor: TextEditor;
/**
* The new value for the [text editor's options](#TextEditor.options).
*/
options: TextEditorOptions;
}
/**
* Represents an event describing the change of a [text editor's view column](#TextEditor.viewColumn).
*/
export interface TextEditorViewColumnChangeEvent {
/**
* The [text editor](#TextEditor) for which the view column has changed.
*/
textEditor: TextEditor;
/**
* The new value for the [text editor's view column](#TextEditor.viewColumn).
*/
viewColumn: ViewColumn;
}
/**
* Rendering style of the cursor.
*/
export enum TextEditorCursorStyle {
/**
* Render the cursor as a vertical thick line.
*/
Line = 1,
/**
* Render the cursor as a block filled.
*/
Block = 2,
/**
* Render the cursor as a thick horizontal line.
*/
Underline = 3,
/**
* Render the cursor as a vertical thin line.
*/
LineThin = 4,
/**
* Render the cursor as a block outlined.
*/
BlockOutline = 5,
/**
* Render the cursor as a thin horizontal line.
*/
UnderlineThin = 6
}
/**
* Rendering style of the line numbers.
*/
export enum TextEditorLineNumbersStyle {
/**
* Do not render the line numbers.
*/
Off = 0,
/**
* Render the line numbers.
*/
On = 1,
/**
* Render the line numbers with values relative to the primary cursor location.
*/
Relative = 2
}
/**
* Represents a [text editor](#TextEditor)'s [options](#TextEditor.options).
*/
export interface TextEditorOptions {
/**
* The size in spaces a tab takes. This is used for two purposes:
* - the rendering width of a tab character;
* - the number of spaces to insert when [insertSpaces](#TextEditorOptions.insertSpaces) is true.
*
* When getting a text editor's options, this property will always be a number (resolved).
* When setting a text editor's options, this property is optional and it can be a number or `"auto"`.
*/
tabSize?: number | string;
/**
* When pressing Tab insert [n](#TextEditorOptions.tabSize) spaces.
* When getting a text editor's options, this property will always be a boolean (resolved).
* When setting a text editor's options, this property is optional and it can be a boolean or `"auto"`.
*/
insertSpaces?: boolean | string;
/**
* The rendering style of the cursor in this editor.
* When getting a text editor's options, this property will always be present.
* When setting a text editor's options, this property is optional.
*/
cursorStyle?: TextEditorCursorStyle;
/**
* Render relative line numbers w.r.t. the current line number.
* When getting a text editor's options, this property will always be present.
* When setting a text editor's options, this property is optional.
*/
lineNumbers?: TextEditorLineNumbersStyle;
}
/**
* Represents a handle to a set of decorations
* sharing the same [styling options](#DecorationRenderOptions) in a [text editor](#TextEditor).
*
* To get an instance of a `TextEditorDecorationType` use
* [createTextEditorDecorationType](#window.createTextEditorDecorationType).
*/
export interface TextEditorDecorationType {
/**
* Internal representation of the handle.
*/
readonly key: string;
/**
* Remove this decoration type and all decorations on all text editors using it.
*/
dispose(): void;
}
/**
* Represents different [reveal](#TextEditor.revealRange) strategies in a text editor.
*/
export enum TextEditorRevealType {
/**
* The range will be revealed with as little scrolling as possible.
*/
Default = 0,
/**
* The range will always be revealed in the center of the viewport.
*/
InCenter = 1,
/**
* If the range is outside the viewport, it will be revealed in the center of the viewport.
* Otherwise, it will be revealed with as little scrolling as possible.
*/
InCenterIfOutsideViewport = 2,
/**
* The range will always be revealed at the top of the viewport.
*/
AtTop = 3
}
/**
* Represents different positions for rendering a decoration in an [overview ruler](#DecorationRenderOptions.overviewRulerLane).
* The overview ruler supports three lanes.
*/
export enum OverviewRulerLane {
Left = 1,
Center = 2,
Right = 4,
Full = 7
}
/**
* Describes the behavior of decorations when typing/editing at their edges.
*/
export enum DecorationRangeBehavior {
/**
* The decoration's range will widen when edits occur at the start or end.
*/
OpenOpen = 0,
/**
* The decoration's range will not widen when edits occur at the start of end.
*/
ClosedClosed = 1,
/**
* The decoration's range will widen when edits occur at the start, but not at the end.
*/
OpenClosed = 2,
/**
* The decoration's range will widen when edits occur at the end, but not at the start.
*/
ClosedOpen = 3
}
/**
* Represents options to configure the behavior of showing a [document](#TextDocument) in an [editor](#TextEditor).
*/
export interface TextDocumentShowOptions {
/**
* An optional view column in which the [editor](#TextEditor) should be shown.
* The default is the [active](#ViewColumn.Active), other values are adjusted to
* be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is
* not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) to open the
* editor to the side of the currently active one.
*/
viewColumn?: ViewColumn;
/**
* An optional flag that when `true` will stop the [editor](#TextEditor) from taking focus.
*/
preserveFocus?: boolean;
/**
* An optional flag that controls if an [editor](#TextEditor)-tab will be replaced
* with the next editor or if it will be kept.
*/
preview?: boolean;
/**
* An optional selection to apply for the document in the [editor](#TextEditor).
*/
selection?: Range;
}
/**
* A reference to one of the workbench colors as defined in https://code.visualstudio.com/docs/getstarted/theme-color-reference.
* Using a theme color is preferred over a custom color as it gives theme authors and users the possibility to change the color.
*/
export class ThemeColor {
/**
* Creates a reference to a theme color.
* @param id of the color. The available colors are listed in https://code.visualstudio.com/docs/getstarted/theme-color-reference.
*/
constructor(id: string);
}
/**
* A reference to a named icon. Currently only [File](#ThemeIcon.File) and [Folder](#ThemeIcon.Folder) are supported.
* Using a theme icon is preferred over a custom icon as it gives theme authors the possibility to change the icons.
*/
export class ThemeIcon {
/**
* Reference to a icon representing a file. The icon is taken from the current file icon theme or a placeholder icon.
*/
static readonly File: ThemeIcon;
/**
* Reference to a icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon.
*/
static readonly Folder: ThemeIcon;
private constructor(id: string);
}
/**
* Represents theme specific rendering styles for a [text editor decoration](#TextEditorDecorationType).
*/
export interface ThemableDecorationRenderOptions {
/**
* Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations.
* Alternatively a color from the color registry can be [referenced](#ThemeColor).
*/
backgroundColor?: string | ThemeColor;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
outline?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'outline' for setting one or more of the individual outline properties.
*/
outlineColor?: string | ThemeColor;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'outline' for setting one or more of the individual outline properties.
*/
outlineStyle?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'outline' for setting one or more of the individual outline properties.
*/
outlineWidth?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
border?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'border' for setting one or more of the individual border properties.
*/
borderColor?: string | ThemeColor;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'border' for setting one or more of the individual border properties.
*/
borderRadius?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'border' for setting one or more of the individual border properties.
*/
borderSpacing?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'border' for setting one or more of the individual border properties.
*/
borderStyle?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
* Better use 'border' for setting one or more of the individual border properties.
*/
borderWidth?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
fontStyle?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
fontWeight?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
textDecoration?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
cursor?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
color?: string | ThemeColor;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
opacity?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
letterSpacing?: string;
/**
* An **absolute path** or an URI to an image to be rendered in the gutter.
*/
gutterIconPath?: string | Uri;
/**
* Specifies the size of the gutter icon.
* Available values are 'auto', 'contain', 'cover' and any percentage value.
* For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx
*/
gutterIconSize?: string;
/**
* The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.
*/
overviewRulerColor?: string | ThemeColor;
/**
* Defines the rendering options of the attachment that is inserted before the decorated text.
*/
before?: ThemableDecorationAttachmentRenderOptions;
/**
* Defines the rendering options of the attachment that is inserted after the decorated text.
*/
after?: ThemableDecorationAttachmentRenderOptions;
}
export interface ThemableDecorationAttachmentRenderOptions {
/**
* Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.
*/
contentText?: string;
/**
* An **absolute path** or an URI to an image to be rendered in the attachment. Either an icon
* or a text can be shown, but not both.
*/
contentIconPath?: string | Uri;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
border?: string;
/**
* CSS styling property that will be applied to text enclosed by a decoration.
*/
borderColor?: string | ThemeColor;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
fontStyle?: string;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
fontWeight?: string;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
textDecoration?: string;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
color?: string | ThemeColor;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
backgroundColor?: string | ThemeColor;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
margin?: string;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
width?: string;
/**
* CSS styling property that will be applied to the decoration attachment.
*/
height?: string;
}
/**
* Represents rendering styles for a [text editor decoration](#TextEditorDecorationType).
*/
export interface DecorationRenderOptions extends ThemableDecorationRenderOptions {
/**
* Should the decoration be rendered also on the whitespace after the line text.
* Defaults to `false`.
*/
isWholeLine?: boolean;
/**
* Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range.
* Defaults to `DecorationRangeBehavior.OpenOpen`.
*/
rangeBehavior?: DecorationRangeBehavior;
/**
* The position in the overview ruler where the decoration should be rendered.
*/
overviewRulerLane?: OverviewRulerLane;
/**
* Overwrite options for light themes.
*/
light?: ThemableDecorationRenderOptions;
/**
* Overwrite options for dark themes.
*/
dark?: ThemableDecorationRenderOptions;
}
/**
* Represents options for a specific decoration in a [decoration set](#TextEditorDecorationType).
*/
export interface DecorationOptions {
/**
* Range to which this decoration is applied. The range must not be empty.
*/
range: Range;
/**
* A message that should be rendered when hovering over the decoration.
*/
hoverMessage?: MarkedString | MarkedString[];
/**
* Render options applied to the current decoration. For performance reasons, keep the
* number of decoration specific options small, and use decoration types wherever possible.
*/
renderOptions?: DecorationInstanceRenderOptions;
}
export interface ThemableDecorationInstanceRenderOptions {
/**
* Defines the rendering options of the attachment that is inserted before the decorated text.
*/
before?: ThemableDecorationAttachmentRenderOptions;
/**
* Defines the rendering options of the attachment that is inserted after the decorated text.
*/
after?: ThemableDecorationAttachmentRenderOptions;
}
export interface DecorationInstanceRenderOptions extends ThemableDecorationInstanceRenderOptions {
/**
* Overwrite options for light themes.
*/
light?: ThemableDecorationInstanceRenderOptions;
/**
* Overwrite options for dark themes.
*/
dark?: ThemableDecorationInstanceRenderOptions;
}
/**
* Represents an editor that is attached to a [document](#TextDocument).
*/
export interface TextEditor {
/**
* The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.
*/
readonly document: TextDocument;
/**
* The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`.
*/
selection: Selection;
/**
* The selections in this text editor. The primary selection is always at index 0.
*/
selections: Selection[];
/**
* The current visible ranges in the editor (vertically).
* This accounts only for vertical scrolling, and not for horizontal scrolling.
*/
readonly visibleRanges: Range[];
/**
* Text editor options.
*/
options: TextEditorOptions;
/**
* The column in which this editor shows. Will be `undefined` in case this
* isn't one of the main editors, e.g an embedded editor, or when the editor
* column is larger than three.
*/
viewColumn?: ViewColumn;
/**
* Perform an edit on the document associated with this text editor.
*
* The given callback-function is invoked with an [edit-builder](#TextEditorEdit) which must
* be used to make edits. Note that the edit-builder is only valid while the
* callback executes.
*
* @param callback A function which can create edits using an [edit-builder](#TextEditorEdit).
* @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
* @return A promise that resolves with a value indicating if the edits could be applied.
*/
edit(callback: (editBuilder: TextEditorEdit) => void, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable<boolean>;
/**
* Insert a [snippet](#SnippetString) and put the editor into snippet mode. "Snippet mode"
* means the editor adds placeholders and additional cursors so that the user can complete
* or accept the snippet.
*
* @param snippet The snippet to insert in this edit.
* @param location Position or range at which to insert the snippet, defaults to the current editor selection or selections.
* @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
* @return A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal
* that the snippet is completely filled-in or accepted.
*/
insertSnippet(snippet: SnippetString, location?: Position | Range | Position[] | Range[], options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable<boolean>;
/**
* Adds a set of decorations to the text editor. If a set of decorations already exists with
* the given [decoration type](#TextEditorDecorationType), they will be replaced.
*
* @see [createTextEditorDecorationType](#window.createTextEditorDecorationType).
*
* @param decorationType A decoration type.
* @param rangesOrOptions Either [ranges](#Range) or more detailed [options](#DecorationOptions).
*/
setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void;
/**
* Scroll as indicated by `revealType` in order to reveal the given range.
*
* @param range A range.
* @param revealType The scrolling strategy for revealing `range`.
*/
revealRange(range: Range, revealType?: TextEditorRevealType): void;
/**
* ~~Show the text editor.~~
*
* @deprecated Use [window.showTextDocument](#window.showTextDocument) instead.
*
* @param column The [column](#ViewColumn) in which to show this editor.
* This method shows unexpected behavior and will be removed in the next major update.
*/
show(column?: ViewColumn): void;
/**
* ~~Hide the text editor.~~
*
* @deprecated Use the command `workbench.action.closeActiveEditor` instead.
* This method shows unexpected behavior and will be removed in the next major update.
*/
hide(): void;
}
/**
* Represents an end of line character sequence in a [document](#TextDocument).
*/
export enum EndOfLine {
/**
* The line feed `\n` character.
*/
LF = 1,
/**
* The carriage return line feed `\r\n` sequence.
*/
CRLF = 2
}
/**
* A complex edit that will be applied in one transaction on a TextEditor.
* This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.)
* they can be applied on a [document](#TextDocument) associated with a [text editor](#TextEditor).
*
*/
export interface TextEditorEdit {
/**
* Replace a certain text region with a new value.
* You can use \r\n or \n in `value` and they will be normalized to the current [document](#TextDocument).
*
* @param location The range this operation should remove.
* @param value The new text this operation should insert after removing `location`.
*/
replace(location: Position | Range | Selection, value: string): void;
/**
* Insert text at a location.
* You can use \r\n or \n in `value` and they will be normalized to the current [document](#TextDocument).
* Although the equivalent text edit can be made with [replace](#TextEditorEdit.replace), `insert` will produce a different resulting selection (it will get moved).
*
* @param location The position where the new text should be inserted.
* @param value The new text this operation should insert.
*/
insert(location: Position, value: string): void;
/**
* Delete a certain text region.
*
* @param location The range this operation should remove.
*/
delete(location: Range | Selection): void;
/**
* Set the end of line sequence.
*
* @param endOfLine The new end of line for the [document](#TextDocument).
*/
setEndOfLine(endOfLine: EndOfLine): void;
}
/**
* A universal resource identifier representing either a file on disk
* or another resource, like untitled resources.
*/
export class Uri {
/**
* Create an URI from a string, e.g. `http://www.msft.com/some/path`,
* `file:///usr/home`, or `scheme:with/path`.
*
* @see [Uri.toString](#Uri.toString)
* @param value The string value of an Uri.
* @return A new Uri instance.
*/
static parse(value: string): Uri;
/**
* Create an URI from a file system path. The [scheme](#Uri.scheme)
* will be `file`.
*
* The *difference* between `Uri#parse` and `Uri#file` is that the latter treats the argument
* as path, not as stringified-uri. E.g. `Uri.file(path)` is *not* the same as
* `Uri.parse('file://' + path)` because the path might contain characters that are
* interpreted (# and ?). See the following sample:
* ```ts
const good = URI.file('/coding/c#/project1');
good.scheme === 'file';
good.path === '/coding/c#/project1';
good.fragment === '';
const bad = URI.parse('file://' + '/coding/c#/project1');
bad.scheme === 'file';
bad.path === '/coding/c'; // path is now broken
bad.fragment === '/project1';
```
*
* @param path A file system or UNC path.
* @return A new Uri instance.
*/
static file(path: string): Uri;
/**
* Use the `file` and `parse` factory functions to create new `Uri` objects.
*/
private constructor(scheme: string, authority: string, path: string, query: string, fragment: string);
/**
* Scheme is the `http` part of `http://www.msft.com/some/path?query#fragment`.
* The part before the first colon.
*/
readonly scheme: string;
/**
* Authority is the `www.msft.com` part of `http://www.msft.com/some/path?query#fragment`.
* The part between the first double slashes and the next slash.
*/
readonly authority: string;
/**
* Path is the `/some/path` part of `http://www.msft.com/some/path?query#fragment`.
*/
readonly path: string;
/**
* Query is the `query` part of `http://www.msft.com/some/path?query#fragment`.
*/
readonly query: string;
/**
* Fragment is the `fragment` part of `http://www.msft.com/some/path?query#fragment`.
*/
readonly fragment: string;
/**
* The string representing the corresponding file system path of this Uri.
*
* Will handle UNC paths and normalize windows drive letters to lower-case. Also
* uses the platform specific path separator.
*
* * Will *not* validate the path for invalid characters and semantics.
* * Will *not* look at the scheme of this Uri.
* * The resulting string shall *not* be used for display purposes but
* for disk operations, like `readFile` et al.
*
* The *difference* to the [`path`](#Uri.path)-property is the use of the platform specific
* path separator and the handling of UNC paths. The sample below outlines the difference:
* ```ts
const u = URI.parse('file://server/c$/folder/file.txt')
u.authority === 'server'
u.path === '/shares/c$/file.txt'
u.fsPath === '\\server\c$\folder\file.txt'
```
*/
readonly fsPath: string;
/**
* Derive a new Uri from this Uri.
*
* ```ts
* let file = Uri.parse('before:some/file/path');
* let other = file.with({ scheme: 'after' });
* assert.ok(other.toString() === 'after:some/file/path');
* ```
*
* @param change An object that describes a change to this Uri. To unset components use `null` or
* the empty string.
* @return A new Uri that reflects the given change. Will return `this` Uri if the change
* is not changing anything.
*/
with(change: { scheme?: string; authority?: string; path?: string; query?: string; fragment?: string }): Uri;
/**
* Returns a string representation of this Uri. The representation and normalization
* of a URI depends on the scheme.
*
* * The resulting string can be safely used with [Uri.parse](#Uri.parse).
* * The resulting string shall *not* be used for display purposes.
*
* *Note* that the implementation will encode _aggressive_ which often leads to unexpected,
* but not incorrect, results. For instance, colons are encoded to `%3A` which might be unexpected
* in file-uri. Also `&` and `=` will be encoded which might be unexpected for http-uris. For stability
* reasons this cannot be changed anymore. If you suffer from too aggressive encoding you should use
* the `skipEncoding`-argument: `uri.toString(true)`.
*
* @param skipEncoding Do not percentage-encode the result, defaults to `false`. Note that
* the `#` and `?` characters occurring in the path will always be encoded.
* @returns A string representation of this Uri.
*/
toString(skipEncoding?: boolean): string;
/**
* Returns a JSON representation of this Uri.
*
* @return An object.
*/
toJSON(): any;
}
/**
* A cancellation token is passed to an asynchronous or long running
* operation to request cancellation, like cancelling a request
* for completion items because the user continued to type.
*
* To get an instance of a `CancellationToken` use a
* [CancellationTokenSource](#CancellationTokenSource).
*/
export interface CancellationToken {
/**
* Is `true` when the token has been cancelled, `false` otherwise.
*/
isCancellationRequested: boolean;
/**
* An [event](#Event) which fires upon cancellation.
*/
onCancellationRequested: Event<any>;
}
/**
* A cancellation source creates and controls a [cancellation token](#CancellationToken).
*/
export class CancellationTokenSource {
/**
* The cancellation token of this source.
*/
token: CancellationToken;
/**
* Signal cancellation on the token.
*/
cancel(): void;
/**
* Dispose object and free resources.
*/
dispose(): void;
}
/**
* Represents a type which can release resources, such
* as event listening or a timer.
*/
export class Disposable {
/**
* Combine many disposable-likes into one. Use this method
* when having objects with a dispose function which are not
* instances of Disposable.
*
* @param disposableLikes Objects that have at least a `dispose`-function member.
* @return Returns a new disposable which, upon dispose, will
* dispose all provided disposables.
*/
static from(...disposableLikes: { dispose: () => any }[]): Disposable;
/**
* Creates a new Disposable calling the provided function
* on dispose.
* @param callOnDispose Function that disposes something.
*/
constructor(callOnDispose: Function);
/**
* Dispose this object.
*/
dispose(): any;
}
/**
* Represents a typed event.
*
* A function that represents an event to which you subscribe by calling it with
* a listener function as argument.
*
* @sample `item.onDidChange(function(event) { console.log("Event happened: " + event); });`
*/
export interface Event<T> {
/**
* A function that represents an event to which you subscribe by calling it with
* a listener function as argument.
*
* @param listener The listener function will be called when the event happens.
* @param thisArgs The `this`-argument which will be used when calling the event listener.
* @param disposables An array to which a [disposable](#Disposable) will be added.
* @return A disposable which unsubscribes the event listener.
*/
(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable;
}
/**
* An event emitter can be used to create and manage an [event](#Event) for others
* to subscribe to. One emitter always owns one event.
*
* Use this class if you want to provide event from within your extension, for instance
* inside a [TextDocumentContentProvider](#TextDocumentContentProvider) or when providing
* API to other extensions.
*/
export class EventEmitter<T> {
/**
* The event listeners can subscribe to.
*/
event: Event<T>;
/**
* Notify all subscribers of the [event](#EventEmitter.event). Failure
* of one or more listener will not fail this function call.
*
* @param data The event object.
*/
fire(data?: T): void;
/**
* Dispose this object and free resources.
*/
dispose(): void;
}
/**
* A file system watcher notifies about changes to files and folders
* on disk.
*
* To get an instance of a `FileSystemWatcher` use
* [createFileSystemWatcher](#workspace.createFileSystemWatcher).
*/
export interface FileSystemWatcher extends Disposable {
/**
* true if this file system watcher has been created such that
* it ignores creation file system events.
*/
ignoreCreateEvents: boolean;
/**
* true if this file system watcher has been created such that
* it ignores change file system events.
*/
ignoreChangeEvents: boolean;
/**
* true if this file system watcher has been created such that
* it ignores delete file system events.
*/
ignoreDeleteEvents: boolean;
/**
* An event which fires on file/folder creation.
*/
onDidCreate: Event<Uri>;
/**
* An event which fires on file/folder change.
*/
onDidChange: Event<Uri>;
/**
* An event which fires on file/folder deletion.
*/
onDidDelete: Event<Uri>;
}
/**
* A text document content provider allows to add readonly documents
* to the editor, such as source from a dll or generated html from md.
*
* Content providers are [registered](#workspace.registerTextDocumentContentProvider)
* for a [uri-scheme](#Uri.scheme). When a uri with that scheme is to
* be [loaded](#workspace.openTextDocument) the content provider is
* asked.
*/
export interface TextDocumentContentProvider {
/**
* An event to signal a resource has changed.
*/
onDidChange?: Event<Uri>;
/**
* Provide textual content for a given uri.
*
* The editor will use the returned string-content to create a readonly
* [document](#TextDocument). Resources allocated should be released when
* the corresponding document has been [closed](#workspace.onDidCloseTextDocument).
*
* **Note**: The contents of the created [document](#TextDocument) might not be
* identical to the provided text due to end-of-line-sequence normalization.
*
* @param uri An uri which scheme matches the scheme this provider was [registered](#workspace.registerTextDocumentContentProvider) for.
* @param token A cancellation token.
* @return A string or a thenable that resolves to such.
*/
provideTextDocumentContent(uri: Uri, token: CancellationToken): ProviderResult<string>;
}
/**
* Represents an item that can be selected from
* a list of items.
*/
export interface QuickPickItem {
/**
* A human readable string which is rendered prominent.
*/
label: string;
/**
* A human readable string which is rendered less prominent.
*/
description?: string;
/**
* A human readable string which is rendered less prominent.
*/
detail?: string;
/**
* Optional flag indicating if this item is picked initially.
* (Only honored when the picker allows multiple selections.)
*
* @see [QuickPickOptions.canPickMany](#QuickPickOptions.canPickMany)
*/
picked?: boolean;
/**
* Always show this item.
*/
alwaysShow?: boolean;
}
/**
* Options to configure the behavior of the quick pick UI.
*/
export interface QuickPickOptions {
/**
* An optional flag to include the description when filtering the picks.
*/
matchOnDescription?: boolean;
/**
* An optional flag to include the detail when filtering the picks.
*/
matchOnDetail?: boolean;
/**
* An optional string to show as place holder in the input box to guide the user what to pick on.
*/
placeHolder?: string;
/**
* Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
*/
ignoreFocusOut?: boolean;
/**
* An optional flag to make the picker accept multiple selections, if true the result is an array of picks.
*/
canPickMany?: boolean;
/**
* An optional function that is invoked whenever an item is selected.
*/
onDidSelectItem?(item: QuickPickItem | string): any;
}
/**
* Options to configure the behaviour of the [workspace folder](#WorkspaceFolder) pick UI.
*/
export interface WorkspaceFolderPickOptions {
/**
* An optional string to show as place holder in the input box to guide the user what to pick on.
*/
placeHolder?: string;
/**
* Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
*/
ignoreFocusOut?: boolean;
}
/**
* Options to configure the behaviour of a file open dialog.
*
* * Note 1: A dialog can select files, folders, or both. This is not true for Windows
* which enforces to open either files or folder, but *not both*.
* * Note 2: Explicitly setting `canSelectFiles` and `canSelectFolders` to `false` is futile
* and the editor then silently adjusts the options to select files.
*/
export interface OpenDialogOptions {
/**
* The resource the dialog shows when opened.
*/
defaultUri?: Uri;
/**
* A human-readable string for the open button.
*/
openLabel?: string;
/**
* Allow to select files, defaults to `true`.
*/
canSelectFiles?: boolean;
/**
* Allow to select folders, defaults to `false`.
*/
canSelectFolders?: boolean;
/**
* Allow to select many files or folders.
*/
canSelectMany?: boolean;
/**
* A set of file filters that are used by the dialog. Each entry is a human readable label,
* like "TypeScript", and an array of extensions, e.g.
* ```ts
* {
* 'Images': ['png', 'jpg']
* 'TypeScript': ['ts', 'tsx']
* }
* ```
*/
filters?: { [name: string]: string[] };
}
/**
* Options to configure the behaviour of a file save dialog.
*/
export interface SaveDialogOptions {
/**
* The resource the dialog shows when opened.
*/
defaultUri?: Uri;
/**
* A human-readable string for the save button.
*/
saveLabel?: string;
/**
* A set of file filters that are used by the dialog. Each entry is a human readable label,
* like "TypeScript", and an array of extensions, e.g.
* ```ts
* {
* 'Images': ['png', 'jpg']
* 'TypeScript': ['ts', 'tsx']
* }
* ```
*/
filters?: { [name: string]: string[] };
}
/**
* Represents an action that is shown with an information, warning, or
* error message.
*
* @see [showInformationMessage](#window.showInformationMessage)
* @see [showWarningMessage](#window.showWarningMessage)
* @see [showErrorMessage](#window.showErrorMessage)
*/
export interface MessageItem {
/**
* A short title like 'Retry', 'Open Log' etc.
*/
title: string;
/**
* A hint for modal dialogs that the item should be triggered
* when the user cancels the dialog (e.g. by pressing the ESC
* key).
*
* Note: this option is ignored for non-modal messages.
*/
isCloseAffordance?: boolean;
}
/**
* Options to configure the behavior of the message.
*
* @see [showInformationMessage](#window.showInformationMessage)
* @see [showWarningMessage](#window.showWarningMessage)
* @see [showErrorMessage](#window.showErrorMessage)
*/
export interface MessageOptions {
/**
* Indicates that this message should be modal.
*/
modal?: boolean;
}
/**
* Options to configure the behavior of the input box UI.
*/
export interface InputBoxOptions {
/**
* The value to prefill in the input box.
*/
value?: string;
/**
* Selection of the prefilled [`value`](#InputBoxOptions.value). Defined as tuple of two number where the
* first is the inclusive start index and the second the exclusive end index. When `undefined` the whole
* word will be selected, when empty (start equals end) only the cursor will be set,
* otherwise the defined range will be selected.
*/
valueSelection?: [number, number];
/**
* The text to display underneath the input box.
*/
prompt?: string;
/**
* An optional string to show as place holder in the input box to guide the user what to type.
*/
placeHolder?: string;
/**
* Set to `true` to show a password prompt that will not show the typed value.
*/
password?: boolean;
/**
* Set to `true` to keep the input box open when focus moves to another part of the editor or to another window.
*/
ignoreFocusOut?: boolean;
/**
* An optional function that will be called to validate input and to give a hint
* to the user.
*
* @param value The current value of the input box.
* @return A human readable string which is presented as diagnostic message.
* Return `undefined`, `null`, or the empty string when 'value' is valid.
*/
validateInput?(value: string): string | undefined | null | Thenable<string | undefined | null>;
}
/**
* A relative pattern is a helper to construct glob patterns that are matched
* relatively to a base path. The base path can either be an absolute file path
* or a [workspace folder](#WorkspaceFolder).
*/
export class RelativePattern {
/**
* A base file path to which this pattern will be matched against relatively.
*/
base: string;
/**
* A file glob pattern like `*.{ts,js}` that will be matched on file paths
* relative to the base path.
*
* Example: Given a base of `/home/work/folder` and a file path of `/home/work/folder/index.js`,
* the file glob pattern will match on `index.js`.
*/
pattern: string;
/**
* Creates a new relative pattern object with a base path and pattern to match. This pattern
* will be matched on file paths relative to the base path.
*
* @param base A base file path to which this pattern will be matched against relatively.
* @param pattern A file glob pattern like `*.{ts,js}` that will be matched on file paths
* relative to the base path.
*/
constructor(base: WorkspaceFolder | string, pattern: string)
}
/**
* A file glob pattern to match file paths against. This can either be a glob pattern string
* (like `**​/*.{ts,js}` or `*.{ts,js}`) or a [relative pattern](#RelativePattern).
*
* Glob patterns can have the following syntax:
* * `*` to match one or more characters in a path segment
* * `?` to match on one character in a path segment
* * `**` to match any number of path segments, including none
* * `{}` to group conditions (e.g. `**​/*.{ts,js}` matches all TypeScript and JavaScript files)
* * `[]` to declare a range of characters to match in a path segment (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …)
* * `[!...]` to negate a range of characters to match in a path segment (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not `example.0`)
*/
export type GlobPattern = string | RelativePattern;
/**
* A document filter denotes a document by different properties like
* the [language](#TextDocument.languageId), the [scheme](#Uri.scheme) of
* its resource, or a glob-pattern that is applied to the [path](#TextDocument.fileName).
*
* @sample A language filter that applies to typescript files on disk: `{ language: 'typescript', scheme: 'file' }`
* @sample A language filter that applies to all package.json paths: `{ language: 'json', scheme: 'untitled', pattern: '**​/package.json' }`
*/
export interface DocumentFilter {
/**
* A language id, like `typescript`.
*/
language?: string;
/**
* A Uri [scheme](#Uri.scheme), like `file` or `untitled`.
*/
scheme?: string;
/**
* A [glob pattern](#GlobPattern) that is matched on the absolute path of the document. Use a [relative pattern](#RelativePattern)
* to filter documents to a [workspace folder](#WorkspaceFolder).
*/
pattern?: GlobPattern;
}
/**
* A language selector is the combination of one or many language identifiers
* and [language filters](#DocumentFilter).
*
* *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'.
*
* @sample `let sel:DocumentSelector = { scheme: 'file', language: 'typescript' }`;
*/
export type DocumentSelector = DocumentFilter | string | Array<DocumentFilter | string>;
/**
* A provider result represents the values a provider, like the [`HoverProvider`](#HoverProvider),
* may return. For once this is the actual result type `T`, like `Hover`, or a thenable that resolves
* to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a
* thenable.
*
* The snippets below are all valid implementations of the [`HoverProvider`](#HoverProvider):
*
* ```ts
* let a: HoverProvider = {
* provideHover(doc, pos, token): ProviderResult<Hover> {
* return new Hover('Hello World');
* }
* }
*
* let b: HoverProvider = {
* provideHover(doc, pos, token): ProviderResult<Hover> {
* return new Promise(resolve => {
* resolve(new Hover('Hello World'));
* });
* }
* }
*
* let c: HoverProvider = {
* provideHover(doc, pos, token): ProviderResult<Hover> {
* return; // undefined
* }
* }
* ```
*/
export type ProviderResult<T> = T | undefined | null | Thenable<T | undefined | null>;
/**
* Kind of a code action.
*
* Kinds are a hierarchical list of identifiers separated by `.`, e.g. `"refactor.extract.function"`.
*
* Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users
* can also trigger code actions with a specific kind with the `editor.action.codeAction` command.
*/
export class CodeActionKind {
/**
* Empty kind.
*/
static readonly Empty: CodeActionKind;
/**
* Base kind for quickfix actions: `quickfix`.
*
* Quick fix actions address a problem in the code and are shown in the normal code action context menu.
*/
static readonly QuickFix: CodeActionKind;
/**
* Base kind for refactoring actions: `refactor`
*
* Refactoring actions are shown in the refactoring context menu.
*/
static readonly Refactor: CodeActionKind;
/**
* Base kind for refactoring extraction actions: `refactor.extract`
*
* Example extract actions:
*
* - Extract method
* - Extract function
* - Extract variable
* - Extract interface from class
* - ...
*/
static readonly RefactorExtract: CodeActionKind;
/**
* Base kind for refactoring inline actions: `refactor.inline`
*
* Example inline actions:
*
* - Inline function
* - Inline variable
* - Inline constant
* - ...
*/
static readonly RefactorInline: CodeActionKind;
/**
* Base kind for refactoring rewrite actions: `refactor.rewrite`
*
* Example rewrite actions:
*
* - Convert JavaScript function to class
* - Add or remove parameter
* - Encapsulate field
* - Make method static
* - Move method to base class
* - ...
*/
static readonly RefactorRewrite: CodeActionKind;
/**
* Base kind for source actions: `source`
*
* Source code actions apply to the entire file and can be run on save
* using `editor.codeActionsOnSave`. They also are shown in `source` context menu.
*/
static readonly Source: CodeActionKind;
/**
* Base kind for an organize imports source action: `source.organizeImports`.
*/
static readonly SourceOrganizeImports: CodeActionKind;
private constructor(value: string);
/**
* String value of the kind, e.g. `"refactor.extract.function"`.
*/
readonly value?: string;
/**
* Create a new kind by appending a more specific selector to the current kind.
*
* Does not modify the current kind.
*/
append(parts: string): CodeActionKind;
/**
* Does this kind contain `other`?
*
* The kind `"refactor"` for example contains `"refactor.extract"` and ``"refactor.extract.function"`, but not `"unicorn.refactor.extract"` or `"refactory.extract"`
*
* @param other Kind to check.
*/
contains(other: CodeActionKind): boolean;
}
/**
* Contains additional diagnostic information about the context in which
* a [code action](#CodeActionProvider.provideCodeActions) is run.
*/
export interface CodeActionContext {
/**
* An array of diagnostics.
*/
readonly diagnostics: Diagnostic[];
/**
* Requested kind of actions to return.
*
* Actions not of this kind are filtered out before being shown by the lightbulb.
*/
readonly only?: CodeActionKind;
}
/**
* A code action represents a change that can be performed in code, e.g. to fix a problem or
* to refactor code.
*
* A CodeAction must set either [`edit`](#CodeAction.edit) and/or a [`command`](#CodeAction.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 [workspace edit](#WorkspaceEdit) this code action performs.
*/
edit?: WorkspaceEdit;
/**
* [Diagnostics](#Diagnostic) that this code action resolves.
*/
diagnostics?: Diagnostic[];
/**
* A [command](#Command) this code action executes.
*/
command?: Command;
/**
* [Kind](#CodeActionKind) of the code action.
*
* Used to filter code actions.
*/
kind?: CodeActionKind;
/**
* Creates a new code action.
*
* A code action must have at least a [title](#CodeAction.title) and [edits](#CodeAction.edit)
* and/or a [command](#CodeAction.command).
*
* @param title The title of the code action.
* @param kind The kind of the code action.
*/
constructor(title: string, kind?: CodeActionKind);
}
/**
* The code action interface defines the contract between extensions and
* the [light bulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature.
*
* A code action can be any command that is [known](#commands.getCommands) to the system.
*/
export interface CodeActionProvider {
/**
* Provide commands for the given document and range.
*
* @param document The document in which the command was invoked.
* @param range The selector or range for which the command was invoked. This will always be a selection if
* there is a currently active editor.
* @param context Context carrying additional information.
* @param token A cancellation token.
* @return An array of commands, quick fixes, or refactorings or a thenable of such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | CodeAction)[]>;
}
/**
* Metadata about the type of code actions that a [CodeActionProvider](#CodeActionProvider) providers
*/
export interface CodeActionProviderMetadata {
/**
* [CodeActionKinds](#CodeActionKind) that this provider may return.
*
* The list of kinds may be generic, such as `CodeActionKind.Refactor`, or the provider
* may list our every specific kind they provide, such as `CodeActionKind.Refactor.Extract.append('function`)`
*/
readonly providedCodeActionKinds?: ReadonlyArray<CodeActionKind>;
}
/**
* A code lens represents a [command](#Command) that should be shown along with
* source text, like the number of references, a way to run tests, etc.
*
* A code lens is _unresolved_ when no command is associated to it. For performance
* reasons the creation of a code lens and resolving should be done to two stages.
*
* @see [CodeLensProvider.provideCodeLenses](#CodeLensProvider.provideCodeLenses)
* @see [CodeLensProvider.resolveCodeLens](#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 [commands](#Command) 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<void>;
/**
* Compute a list of [lenses](#CodeLens). This call should return as fast as possible and if
* computing the commands is expensive implementors should only return code lens objects with the
* range set and implement [resolve](#CodeLensProvider.resolveCodeLens).
*
* @param document The document in which the command was invoked.
* @param token A cancellation token.
* @return An array of code lenses or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideCodeLenses(document: TextDocument, token: CancellationToken): ProviderResult<CodeLens[]>;
/**
* This function will be called for each visible code lens, usually when scrolling and after
* calls to [compute](#CodeLensProvider.provideCodeLenses)-lenses.
*
* @param codeLens code lens that must be resolved.
* @param token A cancellation token.
* @return The given, resolved code lens or thenable that resolves to such.
*/
resolveCodeLens?(codeLens: CodeLens, token: CancellationToken): ProviderResult<CodeLens>;
}
/**
* Information about where a symbol is defined.
*
* Provides additional metadata over normal [location](#Location) definitions, including the range of
* the defining symbol
*/
export type DefinitionLink = LocationLink;
/**
* The definition of a symbol represented as one or many [locations](#Location).
* For most programming languages there is only one location at which a symbol is
* defined.
*/
export type Definition = Location | Location[];
/**
* The definition provider interface defines the contract between extensions and
* the [go to definition](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-definition)
* and peek definition features.
*/
export interface DefinitionProvider {
/**
* Provide the definition of the symbol at the given position and document.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param token A cancellation token.
* @return A definition or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined` or `null`.
*/
provideDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]>;
}
/**
* The implementation provider interface defines the contract between extensions and
* the go to implementation feature.
*/
export interface ImplementationProvider {
/**
* Provide the implementations of the symbol at the given position and document.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param token A cancellation token.
* @return A definition or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined` or `null`.
*/
provideImplementation(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]>;
}
/**
* The type definition provider defines the contract between extensions and
* the go to type definition feature.
*/
export interface TypeDefinitionProvider {
/**
* Provide the type definition of the symbol at the given position and document.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param token A cancellation token.
* @return A definition or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined` or `null`.
*/
provideTypeDefinition(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Definition | DefinitionLink[]>;
}
/**
* The MarkdownString represents human readable text that supports formatting via the
* markdown syntax. Standard markdown is supported, also tables, but no embedded html.
*/
export class MarkdownString {
/**
* The markdown string.
*/
value: string;
/**
* Indicates that this markdown string is from a trusted source. Only *trusted*
* markdown supports links that execute commands, e.g. `[Run it](command:myCommandId)`.
*/
isTrusted?: boolean;
/**
* Creates a new markdown string with the given value.
*
* @param value Optional, initial value.
*/
constructor(value?: string);
/**
* 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.
* @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 [language identifier](#languages.getLanguages).
*/
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 [`MarkdownString`](#MarkdownString) instead.
*/
export type MarkedString = MarkdownString | string | { language: string; value: string };
/**
* A hover represents additional information for a symbol or word. Hovers are
* rendered in a tooltip-like widget.
*/
export class Hover {
/**
* The contents of this hover.
*/
contents: MarkedString[];
/**
* The range to which this hover applies. When missing, the
* editor will use the range at the current position or the
* current position itself.
*/
range?: Range;
/**
* Creates a new hover object.
*
* @param contents The contents of the hover.
* @param range The range to which the hover applies.
*/
constructor(contents: MarkedString | MarkedString[], range?: Range);
}
/**
* The hover provider interface defines the contract between extensions and
* the [hover](https://code.visualstudio.com/docs/editor/intellisense)-feature.
*/
export interface HoverProvider {
/**
* Provide a hover for the given position and document. Multiple hovers at the same
* position will be merged by the editor. A hover can have a range which defaults
* to the word range at the position when omitted.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param token A cancellation token.
* @return A hover or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined` or `null`.
*/
provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Hover>;
}
/**
* 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 [text](#DocumentHighlightKind.Text).
*/
kind?: DocumentHighlightKind;
/**
* Creates a new document highlight object.
*
* @param range The range the highlight applies to.
* @param kind The highlight kind, default is [text](#DocumentHighlightKind.Text).
*/
constructor(range: Range, kind?: DocumentHighlightKind);
}
/**
* The document highlight provider interface defines the contract between extensions and
* the word-highlight-feature.
*/
export interface DocumentHighlightProvider {
/**
* Provide a set of document highlights, like all occurrences of a variable or
* all exit-points of a function.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param token A cancellation token.
* @return An array of document highlights or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideDocumentHighlights(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<DocumentHighlight[]>;
}
/**
* A symbol kind.
*/
export enum SymbolKind {
File = 0,
Module = 1,
Namespace = 2,
Package = 3,
Class = 4,
Method = 5,
Property = 6,
Field = 7,
Constructor = 8,
Enum = 9,
Interface = 10,
Function = 11,
Variable = 12,
Constant = 13,
String = 14,
Number = 15,
Boolean = 16,
Array = 17,
Object = 18,
Key = 19,
Null = 20,
EnumMember = 21,
Struct = 22,
Event = 23,
Operator = 24,
TypeParameter = 25
}
/**
* 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;
/**
* 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 [location](#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;
/**
* 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 [`range`](#DocumentSymbol.range).
*/
selectionRange: Range;
/**
* Children of this symbol, e.g. properties of a class.
*/
children: DocumentSymbol[];
/**
* Creates a new document symbol.
*
* @param name The name of the symbol.
* @param detail Details for the symbol.
* @param kind The kind of the symbol.
* @param range The full range of the symbol.
* @param selectionRange The range that should be reveal.
*/
constructor(name: string, detail: string, kind: SymbolKind, range: Range, selectionRange: Range);
}
/**
* The document symbol provider interface defines the contract between extensions and
* the [go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)-feature.
*/
export interface DocumentSymbolProvider {
/**
* Provide symbol information for the given document.
*
* @param document The document in which the command was invoked.
* @param token A cancellation token.
* @return An array of document highlights or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideDocumentSymbols(document: TextDocument, token: CancellationToken): ProviderResult<SymbolInformation[] | DocumentSymbol[]>;
}
/**
* 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
* [location](#SymbolInformation.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 non-empty query string.
* @param token A cancellation token.
* @return An array of document highlights or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult<SymbolInformation[]>;
/**
* Given a symbol fill in its [location](#SymbolInformation.location). This method is called whenever a symbol
* is selected in the UI. Providers can implement this method and return incomplete symbols from
* [`provideWorkspaceSymbols`](#WorkspaceSymbolProvider.provideWorkspaceSymbols) which often helps to improve
* performance.
*
* @param symbol The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an
* earlier call to `provideWorkspaceSymbols`.
* @param token A cancellation token.
* @return The resolved symbol or a thenable that resolves to that. When no result is returned,
* the given `symbol` is used.
*/
resolveWorkspaceSymbol?(symbol: SymbolInformation, token: CancellationToken): ProviderResult<SymbolInformation>;
}
/**
* Value-object that contains additional information when
* requesting references.
*/
export interface ReferenceContext {
/**
* Include the declaration of the current symbol.
*/
includeDeclaration: boolean;
}
/**
* The reference provider interface defines the contract between extensions and
* the [find references](https://code.visualstudio.com/docs/editor/editingevolved#_peek)-feature.
*/
export interface ReferenceProvider {
/**
* Provide a set of project-wide references for the given position and document.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param context
* @param token A cancellation token.
* @return An array of locations or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideReferences(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken): ProviderResult<Location[]>;
}
/**
* A text edit represents edits that should be applied
* to a document.
*/
export class TextEdit {
/**
* Utility to create a replace edit.
*
* @param range A range.
* @param newText A string.
* @return A new text edit object.
*/
static replace(range: Range, newText: string): TextEdit;
/**
* Utility to create an insert edit.
*
* @param position A position, will become an empty range.
* @param newText A string.
* @return A new text edit object.
*/
static insert(position: Position, newText: string): TextEdit;
/**
* Utility to create a delete edit.
*
* @param range A range.
* @return A new text edit object.
*/
static delete(range: Range): TextEdit;
/**
* Utility to create an eol-edit.
*
* @param eol An eol-sequence
* @return A new text edit object.
*/
static setEndOfLine(eol: EndOfLine): TextEdit;
/**
* The range this edit applies to.
*/
range: Range;
/**
* The string this edit will insert.
*/
newText: string;
/**
* The eol-sequence used in the document.
*
* *Note* that the eol-sequence will be applied to the
* whole document.
*/
newEol: EndOfLine;
/**
* Create a new TextEdit.
*
* @param range A range.
* @param newText A string.
*/
constructor(range: Range, newText: string);
}
/**
* A workspace edit is a collection of textual and files changes for
* multiple resources and documents.
*
* Use the [applyEdit](#workspace.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.
*/
replace(uri: Uri, range: Range, newText: string): void;
/**
* Insert the given text at the given position.
*
* @param uri A resource identifier.
* @param position A position.
* @param newText A string.
*/
insert(uri: Uri, position: Position, newText: string): void;
/**
* Delete the text at the given range.
*
* @param uri A resource identifier.
* @param range A range.
*/
delete(uri: Uri, range: Range): void;
/**
* Check if a text edit for a resource exists.
*
* @param uri A resource identifier.
* @return `true` if the given resource will be touched by this edit.
*/
has(uri: Uri): boolean;
/**
* Set (and replace) text edits for a resource.
*
* @param uri A resource identifier.
* @param edits An array of text edits.
*/
set(uri: Uri, edits: TextEdit[]): void;
/**
* Get the text edits for a resource.
*
* @param uri A resource identifier.
* @return An array of text edits.
*/
get(uri: Uri): TextEdit[];
/**
* Create a regular file.
*
* @param uri Uri of the new file..
* @param options Defines if an existing file should be overwritten or be
* ignored. When overwrite and ignoreIfExists are both set overwrite wins.
*/
createFile(uri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }): void;
/**
* Delete a file or folder.
*
* @param uri The uri of the file that is to be deleted.
*/
deleteFile(uri: Uri, options?: { recursive?: boolean, ignoreIfNotExists?: boolean }): 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.
*/
renameFile(oldUri: Uri, newUri: Uri, options?: { overwrite?: boolean, ignoreIfExists?: boolean }): void;
/**
* Get all text edits grouped by resource.
*
* @return A shallow copy of `[Uri, TextEdit[]]`-tuples.
*/
entries(): [Uri, TextEdit[]][];
}
/**
* A snippet string is a template which allows to insert text
* and to control the editor cursor when insertion happens.
*
* A snippet can define tab stops and placeholders with `$1`, `$2`
* and `${3:foo}`. `$0` defines the final tab stop, it defaults to
* the end of the snippet. Variables are defined with `$name` and
* `${name:default value}`. The full snippet syntax is documented
* [here](http://code.visualstudio.com/docs/editor/userdefinedsnippets#_creating-your-own-snippets).
*/
export class SnippetString {
/**
* The snippet string.
*/
value: string;
constructor(value?: string);
/**
* Builder-function that appends the given string to
* the [`value`](#SnippetString.value) of this snippet string.
*
* @param string A value to append 'as given'. The string will be escaped.
* @return This snippet string.
*/
appendText(string: string): SnippetString;
/**
* Builder-function that appends a tabstop (`$1`, `$2` etc) to
* the [`value`](#SnippetString.value) of this snippet string.
*
* @param number The number of this tabstop, defaults to an auto-increment
* value starting at 1.
* @return This snippet string.
*/
appendTabstop(number?: number): SnippetString;
/**
* Builder-function that appends a placeholder (`${1:value}`) to
* the [`value`](#SnippetString.value) of this snippet string.
*
* @param value The value of this placeholder - either a string or a function
* with which a nested snippet can be created.
* @param number The number of this tabstop, defaults to an auto-increment
* value starting at 1.
* @return This snippet string.
*/
appendPlaceholder(value: string | ((snippet: SnippetString) => any), number?: number): SnippetString;
/**
* Builder-function that appends a variable (`${VAR}`) to
* the [`value`](#SnippetString.value) of this snippet string.
*
* @param name The name of the variable - excluding the `$`.
* @param defaultValue The default value which is used when the variable name cannot
* be resolved - either a string or a function with which a nested snippet can be created.
* @return This snippet string.
*/
appendVariable(name: string, defaultValue: string | ((snippet: SnippetString) => any)): SnippetString;
}
/**
* The rename provider interface defines the contract between extensions and
* the [rename](https://code.visualstudio.com/docs/editor/editingevolved#_rename-symbol)-feature.
*/
export interface RenameProvider {
/**
* Provide an edit that describes changes that have to be made to one
* or many resources to rename a symbol to a different name.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param newName The new name of the symbol. If the given name is not valid, the provider must return a rejected promise.
* @param token A cancellation token.
* @return A workspace edit or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined` or `null`.
*/
provideRenameEdits(document: TextDocument, position: Position, newName: string, token: CancellationToken): ProviderResult<WorkspaceEdit>;
/**
* 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.
*
* @param document The document in which rename will be invoked.
* @param position The position at which rename will be invoked.
* @param token A cancellation token.
* @return The range or range and placeholder text of the identifier that is to be renamed. The lack of a result can signaled by returning `undefined` or `null`.
*/
prepareRename?(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Range | { range: Range, placeholder: string }>;
}
/**
* Value-object describing what options formatting should use.
*/
export interface FormattingOptions {
/**
* Size of a tab in spaces.
*/
tabSize: number;
/**
* Prefer spaces over tabs.
*/
insertSpaces: boolean;
/**
* Signature for further properties.
*/
[key: string]: boolean | number | string;
}
/**
* The document formatting provider interface defines the contract between extensions and
* the formatting-feature.
*/
export interface DocumentFormattingEditProvider {
/**
* Provide formatting edits for a whole document.
*
* @param document The document in which the command was invoked.
* @param options Options controlling formatting.
* @param token A cancellation token.
* @return A set of text edits or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideDocumentFormattingEdits(document: TextDocument, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>;
}
/**
* The document formatting provider interface defines the contract between extensions and
* the formatting-feature.
*/
export interface DocumentRangeFormattingEditProvider {
/**
* Provide formatting edits for a range in a document.
*
* The given range is a hint and providers can decide to format a smaller
* or larger range. Often this is done by adjusting the start and end
* of the range to full syntax nodes.
*
* @param document The document in which the command was invoked.
* @param range The range which should be formatted.
* @param options Options controlling formatting.
* @param token A cancellation token.
* @return A set of text edits or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideDocumentRangeFormattingEdits(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>;
}
/**
* The document formatting provider interface defines the contract between extensions and
* the formatting-feature.
*/
export interface OnTypeFormattingEditProvider {
/**
* Provide formatting edits after a character has been typed.
*
* The given position and character should hint to the provider
* what range the position to expand to, like find the matching `{`
* when `}` has been entered.
*
* @param document The document in which the command was invoked.
* @param position The position at which the command was invoked.
* @param ch The character that has been typed.
* @param options Options controlling formatting.
* @param token A cancellation token.
* @return A set of text edits or a thenable that resolves to such. The lack of a result can be
* signaled by returning `undefined`, `null`, or an empty array.
*/
provideOnTypeFormattingEdits(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken): ProviderResult<TextEdit[]>;
}
/**
* 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
* [signature label](#SignatureInformation.label). *Note*: A label of type string must be
* a substring of its containing signature information's [label](#SignatureInformation.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.
* @param documentation A doc string.
*/
constructor(label: string, 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[];
/**
* 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 {
/**