@types/vscode/index.d.ts

TypeScript definitions for vscode

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *  Licensed under the MIT License.
 *  See License.txt in the project root for license information.
 *--------------------------------------------------------------------------------------------*/

/**
 * Type Definition for Visual Studio Code 1.104 Extension API
 * See https://code.visualstudio.com/api for more information
 */

declare module 'vscode' {

	/**
	 * The version of the editor.
	 */
	export const version: string;

	/**
	 * Represents a reference to a command. Provides a title which
	 * will be used to represent a command in the UI and, optionally,
	 * an array of arguments which will be passed to the command handler
	 * function when invoked.
	 */
	export interface Command {
		/**
		 * Title of the command, like `save`.
		 */
		title: string;

		/**
		 * The identifier of the actual command handler.
		 * @see {@link commands.registerCommand}
		 */
		command: string;

		/**
		 * A tooltip for the command, when represented in the UI.
		 */
		tooltip?: string;

		/**
		 * Arguments that the command handler should be
		 * invoked with.
		 */
		arguments?: any[];
	}

	/**
	 * Represents a line of text, such as a line of source code.
	 *
	 * TextLine objects are __immutable__. When a {@link TextDocument document} changes,
	 * previously retrieved lines will not represent the latest state.
	 */
	export interface TextLine {

		/**
		 * The zero-based line number.
		 */
		readonly lineNumber: number;

		/**
		 * The text of this line without the line separator characters.
		 */
		readonly text: string;

		/**
		 * The range this line covers without the line separator characters.
		 */
		readonly range: Range;

		/**
		 * The range this line covers with the line separator characters.
		 */
		readonly rangeIncludingLineBreak: Range;

		/**
		 * The offset of the first character which is not a whitespace character as defined
		 * by `/\s/`. **Note** that if a line is all whitespace the length of the line is returned.
		 */
		readonly firstNonWhitespaceCharacterIndex: number;

		/**
		 * Whether this line is whitespace only, shorthand
		 * for {@link TextLine.firstNonWhitespaceCharacterIndex} === {@link TextLine.text TextLine.text.length}.
		 */
		readonly isEmptyOrWhitespace: boolean;
	}

	/**
	 * Represents a text document, such as a source file. Text documents have
	 * {@link TextLine lines} and knowledge about an underlying resource like a file.
	 */
	export interface TextDocument {

		/**
		 * The associated uri for this document.
		 *
		 * *Note* that most documents use the `file`-scheme, which means they are files on disk. However, **not** all documents are
		 * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk.
		 *
		 * @see {@link FileSystemProvider}
		 * @see {@link TextDocumentContentProvider}
		 */
		readonly uri: Uri;

		/**
		 * The file system path of the associated resource. Shorthand
		 * notation for {@link TextDocument.uri TextDocument.uri.fsPath}. Independent of the uri scheme.
		 */
		readonly fileName: string;

		/**
		 * Is this document representing an untitled file which has never been saved yet. *Note* that
		 * this does not mean the document will be saved to disk, use {@linkcode Uri.scheme}
		 * to figure out where a document will be {@link FileSystemProvider saved}, e.g. `file`, `ftp` etc.
		 */
		readonly isUntitled: boolean;

		/**
		 * The identifier of the language associated with this document.
		 */
		readonly languageId: string;

		/**
		 * The file encoding of this document that will be used when the document is saved.
		 *
		 * Use the {@link workspace.onDidChangeTextDocument onDidChangeTextDocument}-event to
		 * get notified when the document encoding changes.
		 *
		 * Note that the possible encoding values are currently defined as any of the following:
		 * 'utf8', 'utf8bom', 'utf16le', 'utf16be', 'windows1252', 'iso88591', 'iso88593',
		 * 'iso885915', 'macroman', 'cp437', 'windows1256', 'iso88596', 'windows1257',
		 * 'iso88594', 'iso885914', 'windows1250', 'iso88592', 'cp852', 'windows1251',
		 * 'cp866', 'cp1125', 'iso88595', 'koi8r', 'koi8u', 'iso885913', 'windows1253',
		 * 'iso88597', 'windows1255', 'iso88598', 'iso885910', 'iso885916', 'windows1254',
		 * 'iso88599', 'windows1258', 'gbk', 'gb18030', 'cp950', 'big5hkscs', 'shiftjis',
		 * 'eucjp', 'euckr', 'windows874', 'iso885911', 'koi8ru', 'koi8t', 'gb2312',
		 * 'cp865', 'cp850'.
		 */
		readonly encoding: string;

		/**
		 * The version number of this document (it will strictly increase after each
		 * change, including undo/redo).
		 */
		readonly version: number;

		/**
		 * `true` if there are unpersisted changes.
		 */
		readonly isDirty: boolean;

		/**
		 * `true` if the document has been closed. A closed document isn't synchronized anymore
		 * and won't be re-used when the same resource is opened again.
		 */
		readonly isClosed: boolean;

		/**
		 * Save the underlying file.
		 *
		 * @returns A promise that will resolve to `true` when the file
		 * has been saved. If the save failed, will return `false`.
		 */
		save(): Thenable<boolean>;

		/**
		 * The {@link EndOfLine end of line} sequence that is predominately
		 * used in this document.
		 */
		readonly eol: EndOfLine;

		/**
		 * The number of lines in this document.
		 */
		readonly lineCount: number;

		/**
		 * Returns a text line denoted by the line number. Note
		 * that the returned object is *not* live and changes to the
		 * document are not reflected.
		 *
		 * @param line A line number in `[0, lineCount)`.
		 * @returns A {@link TextLine line}.
		 */
		lineAt(line: number): TextLine;

		/**
		 * Returns a text line denoted by the position. Note
		 * that the returned object is *not* live and changes to the
		 * document are not reflected.
		 *
		 * The position will be {@link TextDocument.validatePosition adjusted}.
		 *
		 * @see {@link TextDocument.lineAt}
		 *
		 * @param position A position.
		 * @returns A {@link TextLine line}.
		 */
		lineAt(position: Position): TextLine;

		/**
		 * Converts the position to a zero-based offset.
		 *
		 * The position will be {@link TextDocument.validatePosition adjusted}.
		 *
		 * @param position A position.
		 * @returns A valid zero-based offset in UTF-16 [code units](https://developer.mozilla.org/en-US/docs/Glossary/Code_unit).
		 */
		offsetAt(position: Position): number;

		/**
		 * Converts a zero-based offset to a position.
		 *
		 * @param offset A zero-based offset into the document. This offset is in UTF-16 [code units](https://developer.mozilla.org/en-US/docs/Glossary/Code_unit).
		 * @returns A valid {@link Position}.
		 */
		positionAt(offset: number): Position;

		/**
		 * Get the text of this document. A substring can be retrieved by providing
		 * a range. The range will be {@link TextDocument.validateRange adjusted}.
		 *
		 * @param range Include only the text included by the range.
		 * @returns The text inside the provided range or the entire text.
		 */
		getText(range?: Range): string;

		/**
		 * Get a word-range at the given position. By default words are defined by
		 * common separators, like space, -, _, etc. In addition, per language custom
		 * [word definitions] can be defined. It
		 * is also possible to provide a custom regular expression.
		 *
		 * * *Note 1:* A custom regular expression must not match the empty string and
		 * if it does, it will be ignored.
		 * * *Note 2:* A custom regular expression will fail to match multiline strings
		 * and in the name of speed regular expressions should not match words with
		 * spaces. Use {@linkcode TextLine.text} for more complex, non-wordy, scenarios.
		 *
		 * The position will be {@link TextDocument.validatePosition adjusted}.
		 *
		 * @param position A position.
		 * @param regex Optional regular expression that describes what a word is.
		 * @returns 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.
		 * @returns 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.
		 * @returns The given position or a new, adjusted position.
		 */
		validatePosition(position: Position): Position;
	}

	/**
	 * Represents a line and character position, such as
	 * the position of the cursor.
	 *
	 * Position objects are __immutable__. Use the {@link Position.with with} or
	 * {@link Position.translate translate} methods to derive new positions
	 * from an existing position.
	 */
	export class Position {

		/**
		 * The zero-based line value.
		 */
		readonly line: number;

		/**
		 * The zero-based character value.
		 *
		 * Character offsets are expressed using UTF-16 [code units](https://developer.mozilla.org/en-US/docs/Glossary/Code_unit).
		 */
		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.
		 * @returns `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.
		 * @returns `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.
		 * @returns `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.
		 * @returns `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.
		 * @returns `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.
		 * @returns 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`.
		 * @returns 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.
		 * @returns A position that reflects the given delta. Will return `this` position if the change
		 * is not changing anything.
		 */
		translate(change: {
			/**
			 * Delta value for the line value, default is `0`.
			 */
			lineDelta?: number;
			/**
			 * Delta value for the character value, default is `0`.
			 */
			characterDelta?: number;
		}): Position;

		/**
		 * Create a new position derived from this position.
		 *
		 * @param line Value that should be used as line value, default is the {@link Position.line existing value}
		 * @param character Value that should be used as character value, default is the {@link Position.character existing value}
		 * @returns 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.
		 * @returns A position that reflects the given change. Will return `this` position if the change
		 * is not changing anything.
		 */
		with(change: {
			/**
			 * New line value, defaults the line value of `this`.
			 */
			line?: number;
			/**
			 * New character value, defaults the character value of `this`.
			 */
			character?: number;
		}): Position;
	}

	/**
	 * A range represents an ordered pair of two positions.
	 * It is guaranteed that {@link Range.start start}.isBeforeOrEqual({@link Range.end end})
	 *
	 * Range objects are __immutable__. Use the {@link Range.with with},
	 * {@link Range.intersection intersection}, or {@link Range.union union} methods
	 * to derive new ranges from an existing range.
	 */
	export class Range {

		/**
		 * The start position. It is before or equal to {@link Range.end end}.
		 */
		readonly start: Position;

		/**
		 * The end position. It is after or equal to {@link Range.start start}.
		 */
		readonly end: Position;

		/**
		 * Create a new range from two positions. If `start` is not
		 * before or equal to `end`, the values will be swapped.
		 *
		 * @param start A position.
		 * @param end A position.
		 */
		constructor(start: Position, end: Position);

		/**
		 * Create a new range from number coordinates. It is a shorter equivalent of
		 * using `new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))`
		 *
		 * @param startLine A zero-based line value.
		 * @param startCharacter A zero-based character value.
		 * @param endLine A zero-based line value.
		 * @param endCharacter A zero-based character value.
		 */
		constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number);

		/**
		 * `true` if `start` and `end` are equal.
		 */
		isEmpty: boolean;

		/**
		 * `true` if `start.line` and `end.line` are equal.
		 */
		isSingleLine: boolean;

		/**
		 * Check if a position or a range is contained in this range.
		 *
		 * @param positionOrRange A position or a range.
		 * @returns `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.
		 * @returns `true` when start and end are {@link Position.isEqual equal} to
		 * start and end of this range.
		 */
		isEqual(other: Range): boolean;

		/**
		 * Intersect `range` with this range and returns a new range or `undefined`
		 * if the ranges have no overlap.
		 *
		 * @param range A range.
		 * @returns 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.
		 * @returns A range of smaller start position and the greater end position.
		 */
		union(other: Range): Range;

		/**
		 * Derived a new range from this range.
		 *
		 * @param start A position that should be used as start. The default value is the {@link Range.start current start}.
		 * @param end A position that should be used as end. The default value is the {@link Range.end current end}.
		 * @returns 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.
		 * @returns A range that reflects the given change. Will return `this` range if the change
		 * is not changing anything.
		 */
		with(change: {
			/**
			 * New start position, defaults to {@link Range.start current start}
			 */
			start?: Position;
			/**
			 * New end position, defaults to {@link Range.end current end}
			 */
			end?: Position;
		}): Range;
	}

	/**
	 * Represents a text selection in an editor.
	 */
	export class Selection extends Range {

		/**
		 * The position at which the selection starts.
		 * This position might be before or after {@link Selection.active active}.
		 */
		readonly anchor: Position;

		/**
		 * The position of the cursor.
		 * This position might be before or after {@link Selection.anchor anchor}.
		 */
		readonly 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 its {@link Selection.anchor anchor} is the {@link Selection.end end} position.
		 */
		readonly isReversed: boolean;
	}

	/**
	 * Represents sources that can cause {@link window.onDidChangeTextEditorSelection selection change events}.
	 */
	export enum TextEditorSelectionChangeKind {
		/**
		 * Selection changed due to typing in the editor.
		 */
		Keyboard = 1,
		/**
		 * Selection change due to clicking in the editor.
		 */
		Mouse = 2,
		/**
		 * Selection changed because a command ran.
		 */
		Command = 3
	}

	/**
	 * Represents an event describing the change in a {@link TextEditor.selections text editor's selections}.
	 */
	export interface TextEditorSelectionChangeEvent {
		/**
		 * The {@link TextEditor text editor} for which the selections have changed.
		 */
		readonly textEditor: TextEditor;
		/**
		 * The new value for the {@link TextEditor.selections text editor's selections}.
		 */
		readonly selections: readonly Selection[];
		/**
		 * The {@link TextEditorSelectionChangeKind change kind} which has triggered this
		 * event. Can be `undefined`.
		 */
		readonly kind: TextEditorSelectionChangeKind | undefined;
	}

	/**
	 * Represents an event describing the change in a {@link TextEditor.visibleRanges text editor's visible ranges}.
	 */
	export interface TextEditorVisibleRangesChangeEvent {
		/**
		 * The {@link TextEditor text editor} for which the visible ranges have changed.
		 */
		readonly textEditor: TextEditor;
		/**
		 * The new value for the {@link TextEditor.visibleRanges text editor's visible ranges}.
		 */
		readonly visibleRanges: readonly Range[];
	}

	/**
	 * Represents an event describing the change in a {@link TextEditor.options text editor's options}.
	 */
	export interface TextEditorOptionsChangeEvent {
		/**
		 * The {@link TextEditor text editor} for which the options have changed.
		 */
		readonly textEditor: TextEditor;
		/**
		 * The new value for the {@link TextEditor.options text editor's options}.
		 */
		readonly options: TextEditorOptions;
	}

	/**
	 * Represents an event describing the change of a {@link TextEditor.viewColumn text editor's view column}.
	 */
	export interface TextEditorViewColumnChangeEvent {
		/**
		 * The {@link TextEditor text editor} for which the view column has changed.
		 */
		readonly textEditor: TextEditor;
		/**
		 * The new value for the {@link TextEditor.viewColumn text editor's view column}.
		 */
		readonly viewColumn: ViewColumn;
	}

	/**
	 * Rendering style of the cursor.
	 */
	export enum TextEditorCursorStyle {
		/**
		 * Render the cursor as a vertical thick line.
		 */
		Line = 1,
		/**
		 * Render the cursor as a block filled.
		 */
		Block = 2,
		/**
		 * Render the cursor as a thick horizontal line.
		 */
		Underline = 3,
		/**
		 * Render the cursor as a vertical thin line.
		 */
		LineThin = 4,
		/**
		 * Render the cursor as a block outlined.
		 */
		BlockOutline = 5,
		/**
		 * Render the cursor as a thin horizontal line.
		 */
		UnderlineThin = 6
	}

	/**
	 * Rendering style of the line numbers.
	 */
	export enum TextEditorLineNumbersStyle {
		/**
		 * Do not render the line numbers.
		 */
		Off = 0,
		/**
		 * Render the line numbers.
		 */
		On = 1,
		/**
		 * Render the line numbers with values relative to the primary cursor location.
		 */
		Relative = 2,
		/**
		 * Render the line numbers on every 10th line number.
		 */
		Interval = 3,
	}

	/**
	 * Represents a {@link TextEditor text editor}'s {@link TextEditor.options options}.
	 */
	export interface TextEditorOptions {

		/**
		 * The size in spaces a tab takes. This is used for two purposes:
		 *  - the rendering width of a tab character;
		 *  - the number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true
		 *    and `indentSize` is set to `"tabSize"`.
		 *
		 * 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;

		/**
		 * The number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true.
		 *
		 * When getting a text editor's options, this property will always be a number (resolved).
		 * When setting a text editor's options, this property is optional and it can be a number or `"tabSize"`.
		 */
		indentSize?: number | string;

		/**
		 * When pressing Tab insert {@link TextEditorOptions.tabSize n} spaces.
		 * When getting a text editor's options, this property will always be a boolean (resolved).
		 * When setting a text editor's options, this property is optional and it can be a boolean or `"auto"`.
		 */
		insertSpaces?: boolean | string;

		/**
		 * The rendering style of the cursor in this editor.
		 * When getting a text editor's options, this property will always be present.
		 * When setting a text editor's options, this property is optional.
		 */
		cursorStyle?: TextEditorCursorStyle;

		/**
		 * Render relative line numbers w.r.t. the current line number.
		 * When getting a text editor's options, this property will always be present.
		 * When setting a text editor's options, this property is optional.
		 */
		lineNumbers?: TextEditorLineNumbersStyle;
	}

	/**
	 * Represents a handle to a set of decorations
	 * sharing the same {@link DecorationRenderOptions styling options} in a {@link TextEditor text editor}.
	 *
	 * To get an instance of a `TextEditorDecorationType` use
	 * {@link window.createTextEditorDecorationType createTextEditorDecorationType}.
	 */
	export interface TextEditorDecorationType {

		/**
		 * Internal representation of the handle.
		 */
		readonly key: string;

		/**
		 * Remove this decoration type and all decorations on all text editors using it.
		 */
		dispose(): void;
	}

	/**
	 * Represents different {@link TextEditor.revealRange reveal} strategies in a text editor.
	 */
	export enum TextEditorRevealType {
		/**
		 * The range will be revealed with as little scrolling as possible.
		 */
		Default = 0,
		/**
		 * The range will always be revealed in the center of the viewport.
		 */
		InCenter = 1,
		/**
		 * If the range is outside the viewport, it will be revealed in the center of the viewport.
		 * Otherwise, it will be revealed with as little scrolling as possible.
		 */
		InCenterIfOutsideViewport = 2,
		/**
		 * The range will always be revealed at the top of the viewport.
		 */
		AtTop = 3
	}

	/**
	 * Represents different positions for rendering a decoration in an {@link DecorationRenderOptions.overviewRulerLane overview ruler}.
	 * The overview ruler supports three lanes.
	 */
	export enum OverviewRulerLane {
		/**
		 * The left lane of the overview ruler.
		 */
		Left = 1,
		/**
		 * The center lane of the overview ruler.
		 */
		Center = 2,
		/**
		 * The right lane of the overview ruler.
		 */
		Right = 4,
		/**
		 * All lanes of the overview ruler.
		 */
		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 or end.
		 */
		ClosedClosed = 1,
		/**
		 * The decoration's range will widen when edits occur at the start, but not at the end.
		 */
		OpenClosed = 2,
		/**
		 * The decoration's range will widen when edits occur at the end, but not at the start.
		 */
		ClosedOpen = 3
	}

	/**
	 * Represents options to configure the behavior of showing a {@link TextDocument document} in an {@link TextEditor editor}.
	 */
	export interface TextDocumentShowOptions {
		/**
		 * An optional view column in which the {@link TextEditor editor} should be shown.
		 * The default is the {@link ViewColumn.Active active}. 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 TextEditor editor} from taking focus.
		 */
		preserveFocus?: boolean;

		/**
		 * An optional flag that controls if an {@link TextEditor editor}-tab shows as preview. Preview tabs will
		 * be replaced and reused until set to stay - either explicitly or through editing.
		 *
		 * *Note* that the flag is ignored if a user has disabled preview editors in settings.
		 */
		preview?: boolean;

		/**
		 * An optional selection to apply for the document in the {@link TextEditor editor}.
		 */
		selection?: Range;
	}

	/**
	 * Represents an event describing the change in a {@link NotebookEditor.selections notebook editor's selections}.
	 */
	export interface NotebookEditorSelectionChangeEvent {
		/**
		 * The {@link NotebookEditor notebook editor} for which the selections have changed.
		 */
		readonly notebookEditor: NotebookEditor;

		/**
		 * The new value for the {@link NotebookEditor.selections notebook editor's selections}.
		 */
		readonly selections: readonly NotebookRange[];
	}

	/**
	 * Represents an event describing the change in a {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}.
	 */
	export interface NotebookEditorVisibleRangesChangeEvent {
		/**
		 * The {@link NotebookEditor notebook editor} for which the visible ranges have changed.
		 */
		readonly notebookEditor: NotebookEditor;

		/**
		 * The new value for the {@link NotebookEditor.visibleRanges notebook editor's visibleRanges}.
		 */
		readonly visibleRanges: readonly NotebookRange[];
	}

	/**
	 * Represents options to configure the behavior of showing a {@link NotebookDocument notebook document} in an {@link NotebookEditor notebook editor}.
	 */
	export interface NotebookDocumentShowOptions {
		/**
		 * An optional view column in which the {@link NotebookEditor notebook 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.
		 */
		readonly viewColumn?: ViewColumn;

		/**
		 * An optional flag that when `true` will stop the {@link NotebookEditor notebook editor} from taking focus.
		 */
		readonly preserveFocus?: boolean;

		/**
		 * An optional flag that controls if an {@link NotebookEditor notebook editor}-tab shows as preview. Preview tabs will
		 * be replaced and reused until set to stay - either explicitly or through editing. The default behaviour depends
		 * on the `workbench.editor.enablePreview`-setting.
		 */
		readonly preview?: boolean;

		/**
		 * An optional selection to apply for the document in the {@link NotebookEditor notebook editor}.
		 */
		readonly selections?: readonly NotebookRange[];
	}

	/**
	 * A reference to one of the workbench colors as defined in https://code.visualstudio.com/api/references/theme-color.
	 * 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 {

		/**
		 * The id of this color.
		 */
		readonly id: string;

		/**
		 * Creates a reference to a theme color.
		 * @param id of the color. The available colors are listed in https://code.visualstudio.com/api/references/theme-color.
		 */
		constructor(id: string);
	}

	/**
	 * A reference to a named icon. Currently, {@link ThemeIcon.File File}, {@link ThemeIcon.Folder Folder},
	 * and [ThemeIcon ids](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing) are supported.
	 * Using a theme icon is preferred over a custom icon as it gives product theme authors the possibility to change the icons.
	 *
	 * *Note* that theme icons can also be rendered inside labels and descriptions. Places that support theme icons spell this out
	 * and they use the `$(<name>)`-syntax, for instance `quickPick.label = "Hello World $(globe)"`.
	 */
	export class ThemeIcon {
		/**
		 * Reference to an icon representing a file. The icon is taken from the current file icon theme or a placeholder icon is used.
		 */
		static readonly File: ThemeIcon;

		/**
		 * Reference to an icon representing a folder. The icon is taken from the current file icon theme or a placeholder icon is used.
		 */
		static readonly Folder: ThemeIcon;

		/**
		 * The id of the icon. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing.
		 */
		readonly id: string;

		/**
		 * The optional ThemeColor of the icon. The color is currently only used in {@link TreeItem}.
		 */
		readonly color?: ThemeColor | undefined;

		/**
		 * Creates a reference to a theme icon.
		 * @param id id of the icon. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing.
		 * @param color optional `ThemeColor` for the icon. The color is currently only used in {@link TreeItem}.
		 */
		constructor(id: string, color?: ThemeColor);
	}

	/**
	 * Represents an icon in the UI. This is either an uri, separate uris for the light- and dark-themes,
	 * or a {@link ThemeIcon theme icon}.
	 */
	export type IconPath = Uri | {
		/**
		 * The icon path for the light theme.
		 */
		light: Uri;
		/**
		 * The icon path for the dark theme.
		 */
		dark: Uri;
	} | ThemeIcon;

	/**
	 * Represents theme specific rendering styles for a {@link TextEditorDecorationType text editor decoration}.
	 */
	export interface ThemableDecorationRenderOptions {
		/**
		 * Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations.
		 * Alternatively a color from the color registry can be {@link ThemeColor referenced}.
		 */
		backgroundColor?: string | ThemeColor;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		outline?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'outline' for setting one or more of the individual outline properties.
		 */
		outlineColor?: string | ThemeColor;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'outline' for setting one or more of the individual outline properties.
		 */
		outlineStyle?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'outline' for setting one or more of the individual outline properties.
		 */
		outlineWidth?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		border?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'border' for setting one or more of the individual border properties.
		 */
		borderColor?: string | ThemeColor;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'border' for setting one or more of the individual border properties.
		 */
		borderRadius?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'border' for setting one or more of the individual border properties.
		 */
		borderSpacing?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'border' for setting one or more of the individual border properties.
		 */
		borderStyle?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 * Better use 'border' for setting one or more of the individual border properties.
		 */
		borderWidth?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		fontStyle?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		fontWeight?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		textDecoration?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		cursor?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		color?: string | ThemeColor;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		opacity?: string;

		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		letterSpacing?: string;

		/**
		 * An **absolute path** or an URI to an image to be rendered in the gutter.
		 */
		gutterIconPath?: string | Uri;

		/**
		 * Specifies the size of the gutter icon.
		 * Available values are 'auto', 'contain', 'cover' and any percentage value.
		 * For further information: https://msdn.microsoft.com/en-us/library/jj127316(v=vs.85).aspx
		 */
		gutterIconSize?: string;

		/**
		 * The color of the decoration in the overview ruler. Use rgba() and define transparent colors to play well with other decorations.
		 */
		overviewRulerColor?: string | ThemeColor;

		/**
		 * Defines the rendering options of the attachment that is inserted before the decorated text.
		 */
		before?: ThemableDecorationAttachmentRenderOptions;

		/**
		 * Defines the rendering options of the attachment that is inserted after the decorated text.
		 */
		after?: ThemableDecorationAttachmentRenderOptions;
	}

	/**
	 * Represents theme specific rendering styles for {@link ThemableDecorationRenderOptions.before before} and
	 * {@link ThemableDecorationRenderOptions.after after} the content of text decorations.
	 */
	export interface ThemableDecorationAttachmentRenderOptions {
		/**
		 * Defines a text content that is shown in the attachment. Either an icon or a text can be shown, but not both.
		 */
		contentText?: string;
		/**
		 * An **absolute path** or an URI to an image to be rendered in the attachment. Either an icon
		 * or a text can be shown, but not both.
		 */
		contentIconPath?: string | Uri;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		border?: string;
		/**
		 * CSS styling property that will be applied to text enclosed by a decoration.
		 */
		borderColor?: string | ThemeColor;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		fontStyle?: string;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		fontWeight?: string;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		textDecoration?: string;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		color?: string | ThemeColor;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		backgroundColor?: string | ThemeColor;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		margin?: string;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		width?: string;
		/**
		 * CSS styling property that will be applied to the decoration attachment.
		 */
		height?: string;
	}

	/**
	 * Represents rendering styles for a {@link TextEditorDecorationType text editor decoration}.
	 */
	export interface DecorationRenderOptions extends ThemableDecorationRenderOptions {
		/**
		 * Should the decoration be rendered also on the whitespace after the line text.
		 * Defaults to `false`.
		 */
		isWholeLine?: boolean;

		/**
		 * Customize the growing behavior of the decoration when edits occur at the edges of the decoration's range.
		 * Defaults to `DecorationRangeBehavior.OpenOpen`.
		 */
		rangeBehavior?: DecorationRangeBehavior;

		/**
		 * The position in the overview ruler where the decoration should be rendered.
		 */
		overviewRulerLane?: OverviewRulerLane;

		/**
		 * Overwrite options for light themes.
		 */
		light?: ThemableDecorationRenderOptions;

		/**
		 * Overwrite options for dark themes.
		 */
		dark?: ThemableDecorationRenderOptions;
	}

	/**
	 * Represents options for a specific decoration in a {@link TextEditorDecorationType decoration set}.
	 */
	export interface DecorationOptions {

		/**
		 * Range to which this decoration is applied. The range must not be empty.
		 */
		range: Range;

		/**
		 * A message that should be rendered when hovering over the decoration.
		 */
		hoverMessage?: MarkdownString | MarkedString | Array<MarkdownString | 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;
	}

	/**
	 * Represents themable render options for decoration instances.
	 */
	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;
	}

	/**
	 * Represents render options for decoration instances. See {@link DecorationOptions.renderOptions}.
	 */
	export interface DecorationInstanceRenderOptions extends ThemableDecorationInstanceRenderOptions {
		/**
		 * Overwrite options for light themes.
		 */
		light?: ThemableDecorationInstanceRenderOptions;

		/**
		 * Overwrite options for dark themes.
		 */
		dark?: ThemableDecorationInstanceRenderOptions;
	}

	/**
	 * Represents an editor that is attached to a {@link TextDocument document}.
	 */
	export interface TextEditor {

		/**
		 * The document associated with this text editor. The document will be the same for the entire lifetime of this text editor.
		 */
		readonly document: TextDocument;

		/**
		 * The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`.
		 */
		selection: Selection;

		/**
		 * The selections in this text editor. The primary selection is always at index 0.
		 */
		selections: readonly Selection[];

		/**
		 * The current visible ranges in the editor (vertically).
		 * This accounts only for vertical scrolling, and not for horizontal scrolling.
		 */
		readonly visibleRanges: readonly Range[];

		/**
		 * Text editor options.
		 */
		options: TextEditorOptions;

		/**
		 * The column in which this editor shows. Will be `undefined` in case this
		 * isn't one of the main editors, e.g. an embedded editor, or when the editor
		 * column is larger than three.
		 */
		readonly viewColumn: ViewColumn | undefined;

		/**
		 * Perform an edit on the document associated with this text editor.
		 *
		 * The given callback-function is invoked with an {@link TextEditorEdit edit-builder} which must
		 * be used to make edits. Note that the edit-builder is only valid while the
		 * callback executes.
		 *
		 * @param callback A function which can create edits using an {@link TextEditorEdit edit-builder}.
		 * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
		 * @returns A promise that resolves with a value indicating if the edits could be applied.
		 */
		edit(callback: (editBuilder: TextEditorEdit) => void, options?: {
			/**
			 * Add undo stop before making the edits.
			 */
			readonly undoStopBefore: boolean;
			/**
			 * Add undo stop after making the edits.
			 */
			readonly undoStopAfter: boolean;
		}): Thenable<boolean>;

		/**
		 * Insert a {@link SnippetString snippet} and put the editor into snippet mode. "Snippet mode"
		 * means the editor adds placeholders and additional cursors so that the user can complete
		 * or accept the snippet.
		 *
		 * @param snippet The snippet to insert in this edit.
		 * @param location Position or range at which to insert the snippet, defaults to the current editor selection or selections.
		 * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit.
		 * @returns 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 | readonly Position[] | readonly Range[], options?: {
			/**
			 * Add undo stop before making the edits.
			 */
			readonly undoStopBefore: boolean;
			/**
			 * Add undo stop after making the edits.
			 */
			readonly undoStopAfter: boolean;
			/**
			 * Keep whitespace of the {@link SnippetString.value} as is.
			 */
			readonly keepWhitespace?: boolean;
		}): Thenable<boolean>;

		/**
		 * Adds a set of decorations to the text editor. If a set of decorations already exists with
		 * the given {@link TextEditorDecorationType decoration type}, they will be replaced. If
		 * `rangesOrOptions` is empty, the existing decorations with the given {@link TextEditorDecorationType decoration type}
		 * will be removed.
		 *
		 * @see {@link window.createTextEditorDecorationType createTextEditorDecorationType}.
		 *
		 * @param decorationType A decoration type.
		 * @param rangesOrOptions Either {@link Range ranges} or more detailed {@link DecorationOptions options}.
		 */
		setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: readonly Range[] | readonly DecorationOptions[]): void;

		/**
		 * Scroll as indicated by `revealType` in order to reveal the given range.
		 *
		 * @param range A range.
		 * @param revealType The scrolling strategy for revealing `range`.
		 */
		revealRange(range: Range, revealType?: TextEditorRevealType): void;

		/**
		 * Show the text editor.
		 *
		 * @deprecated Use {@link window.showTextDocument} instead.
		 *
		 * @param column The {@link ViewColumn column} in which to show this editor.
		 * This method shows unexpected behavior and will be removed in the next major update.
		 */
		show(column?: ViewColumn): void;

		/**
		 * Hide the text editor.
		 *
		 * @deprecated Use the command `workbench.action.closeActiveEditor` instead.
		 * This method shows unexpected behavior and will be removed in the next major update.
		 */
		hide(): void;
	}

	/**
	 * Represents an end of line character sequence in a {@link TextDocument document}.
	 */
	export enum EndOfLine {
		/**
		 * The line feed `\n` character.
		 */
		LF = 1,
		/**
		 * The carriage return line feed `\r\n` sequence.
		 */
		CRLF = 2
	}

	/**
	 * A complex edit that will be applied in one transaction on a TextEditor.
	 * This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.)
	 * they can be applied on a {@link TextDocument document} associated with a {@link TextEditor text editor}.
	 */
	export interface TextEditorEdit {
		/**
		 * Replace a certain text region with a new value.
		 * You can use `\r\n` or `\n` in `value` and they will be normalized to the current {@link TextDocument document}.
		 *
		 * @param location The range this operation should remove.
		 * @param value The new text this operation should insert after removing `location`.
		 */
		replace(location: Position | Range | Selection, value: string): void;

		/**
		 * Insert text at a location.
		 * You can use `\r\n` or `\n` in `value` and they will be normalized to the current {@link TextDocument document}.
		 * Although the equivalent text edit can be made with {@link TextEditorEdit.replace replace}, `insert` will produce a different resulting selection (it will get moved).
		 *
		 * @param location The position where the new text should be inserted.
		 * @param value The new text this operation should insert.
		 */
		insert(location: Position, value: string): void;

		/**
		 * Delete a certain text region.
		 *
		 * @param location The range this operation should remove.
		 */
		delete(location: Range | Selection): void;

		/**
		 * Set the end of line sequence.
		 *
		 * @param endOfLine The new end of line for the {@link TextDocument document}.
		 */
		setEndOfLine(endOfLine: EndOfLine): void;
	}

	/**
	 * A universal resource identifier representing either a file on disk
	 * or another resource, like untitled resources.
	 */
	export class Uri {

		/**
		 * Create an URI from a string, e.g. `http://www.example.com/some/path`,
		 * `file:///usr/home`, or `scheme:with/path`.
		 *
		 * *Note* that for a while uris without a `scheme` were accepted. That is not correct
		 * as all uris should have a scheme. To avoid breakage of existing code the optional
		 * `strict`-argument has been added. We *strongly* advise to use it, e.g. `Uri.parse('my:uri', true)`
		 *
		 * @see {@link Uri.toString}
		 * @param value The string value of an Uri.
		 * @param strict Throw an error when `value` is empty or when no `scheme` can be parsed.
		 * @returns A new Uri instance.
		 */
		static parse(value: string, strict?: boolean): Uri;

		/**
		 * Create an URI from a file system path. The {@link Uri.scheme scheme}
		 * will be `file`.
		 *
		 * The *difference* between {@link Uri.parse} and {@link Uri.file} is that the latter treats the argument
		 * as path, not as stringified-uri. E.g. `Uri.file(path)` is *not* the same as
		 * `Uri.parse('file://' + path)` because the path might contain characters that are
		 * interpreted (# and ?). See the following sample:
		 * ```ts
		 * const good = URI.file('/coding/c#/project1');
		 * good.scheme === 'file';
		 * good.path === '/coding/c#/project1';
		 * good.fragment === '';
		 *
		 * const bad = URI.parse('file://' + '/coding/c#/project1');
		 * bad.scheme === 'file';
		 * bad.path === '/coding/c'; // path is now broken
		 * bad.fragment === '/project1';
		 * ```
		 *
		 * @param path A file system or UNC path.
		 * @returns A new Uri instance.
		 */
		static file(path: string): Uri;

		/**
		 * Create a new uri which path is the result of joining
		 * the path of the base uri with the provided path segments.
		 *
		 * - Note 1: `joinPath` only affects the path component
		 * and all other components (scheme, authority, query, and fragment) are
		 * left as they are.
		 * - Note 2: The base uri must have a path; an error is thrown otherwise.
		 *
		 * The path segments are normalized in the following ways:
		 * - sequences of path separators (`/` or `\`) are replaced with a single separator
		 * - for `file`-uris on windows, the backslash-character (`\`) is considered a path-separator
		 * - the `..`-segment denotes the parent segment, the `.` denotes the current segment
		 * - paths have a root which always remains, for instance on windows drive-letters are roots
		 * so that is true: `joinPath(Uri.file('file:///c:/root'), '../../other').fsPath === 'c:/other'`
		 *
		 * @param base An uri. Must have a path.
		 * @param pathSegments One more more path fragments
		 * @returns A new uri which path is joined with the given fragments
		 */
		static joinPath(base: Uri, ...pathSegments: string[]): Uri;

		/**
		 * Create an URI from its component parts
		 *
		 * @see {@link Uri.toString}
		 * @param components The component parts of an Uri.
		 * @returns A new Uri instance.
		 */
		static from(components: {
			/**
			 * The scheme of the uri
			 */
			readonly scheme: string;
			/**
			 * The authority of the uri
			 */
			readonly authority?: string;
			/**
			 * The path of the uri
			 */
			readonly path?: string;
			/**
			 * The query string of the uri
			 */
			readonly query?: string;
			/**
			 * The fragment identifier of the uri
			 */
			readonly fragment?: 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.example.com/some/path?query#fragment`.
		 * The part before the first colon.
		 */
		readonly scheme: string;

		/**
		 * Authority is the `www.example.com` part of `http://www.example.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.example.com/some/path?query#fragment`.
		 */
		readonly path: string;

		/**
		 * Query is the `query` part of `http://www.example.com/some/path?query#fragment`.