@codingame/monaco-vscode-api 20.1.1 → 20.2.1

package/vscode/src/vs/editor/common/core/range.d.ts

@@ -1,54 +1,194 @@
 import { IPosition, Position } from "./position.js";
+/**
+ * A range in the editor. This interface is suitable for serialization.
+ */
 export interface IRange {
+    /**
+     * Line number on which the range starts (starts at 1).
+     */
     readonly startLineNumber: number;
+    /**
+     * Column on which the range starts in line `startLineNumber` (starts at 1).
+     */
     readonly startColumn: number;
+    /**
+     * Line number on which the range ends.
+     */
     readonly endLineNumber: number;
+    /**
+     * Column on which the range ends in line `endLineNumber`.
+     */
     readonly endColumn: number;
 }
+/**
+ * A range in the editor. (startLineNumber,startColumn) is <= (endLineNumber,endColumn)
+ */
 export declare class Range {
+    /**
+     * Line number on which the range starts (starts at 1).
+     */
     readonly startLineNumber: number;
+    /**
+     * Column on which the range starts in line `startLineNumber` (starts at 1).
+     */
     readonly startColumn: number;
+    /**
+     * Line number on which the range ends.
+     */
     readonly endLineNumber: number;
+    /**
+     * Column on which the range ends in line `endLineNumber`.
+     */
     readonly endColumn: number;
     constructor(startLineNumber: number, startColumn: number, endLineNumber: number, endColumn: number);
+    /**
+     * Test if this range is empty.
+     */
     isEmpty(): boolean;
+    /**
+     * Test if `range` is empty.
+     */
     static isEmpty(range: IRange): boolean;
+    /**
+     * Test if position is in this range. If the position is at the edges, will return true.
+     */
     containsPosition(position: IPosition): boolean;
+    /**
+     * Test if `position` is in `range`. If the position is at the edges, will return true.
+     */
     static containsPosition(range: IRange, position: IPosition): boolean;
+    /**
+     * Test if `position` is in `range`. If the position is at the edges, will return false.
+     * @internal
+     */
     static strictContainsPosition(range: IRange, position: IPosition): boolean;
+    /**
+     * Test if range is in this range. If the range is equal to this range, will return true.
+     */
     containsRange(range: IRange): boolean;
+    /**
+     * Test if `otherRange` is in `range`. If the ranges are equal, will return true.
+     */
     static containsRange(range: IRange, otherRange: IRange): boolean;
+    /**
+     * Test if `range` is strictly in this range. `range` must start after and end before this range for the result to be true.
+     */
     strictContainsRange(range: IRange): boolean;
+    /**
+     * Test if `otherRange` is strictly in `range` (must start after, and end before). If the ranges are equal, will return false.
+     */
     static strictContainsRange(range: IRange, otherRange: IRange): boolean;
+    /**
+     * A reunion of the two ranges.
+     * The smallest position will be used as the start point, and the largest one as the end point.
+     */
     plusRange(range: IRange): Range;
+    /**
+     * A reunion of the two ranges.
+     * The smallest position will be used as the start point, and the largest one as the end point.
+     */
     static plusRange(a: IRange, b: IRange): Range;
+    /**
+     * A intersection of the two ranges.
+     */
     intersectRanges(range: IRange): Range | null;
+    /**
+     * A intersection of the two ranges.
+     */
     static intersectRanges(a: IRange, b: IRange): Range | null;
+    /**
+     * Test if this range equals other.
+     */
     equalsRange(other: IRange | null | undefined): boolean;
+    /**
+     * Test if range `a` equals `b`.
+     */
     static equalsRange(a: IRange | null | undefined, b: IRange | null | undefined): boolean;
+    /**
+     * Return the end position (which will be after or equal to the start position)
+     */
     getEndPosition(): Position;
+    /**
+     * Return the end position (which will be after or equal to the start position)
+     */
     static getEndPosition(range: IRange): Position;
+    /**
+     * Return the start position (which will be before or equal to the end position)
+     */
     getStartPosition(): Position;
+    /**
+     * Return the start position (which will be before or equal to the end position)
+     */
     static getStartPosition(range: IRange): Position;
+    /**
+     * Transform to a user presentable string representation.
+     */
     toString(): string;
+    /**
+     * Create a new range using this range's start position, and using endLineNumber and endColumn as the end position.
+     */
     setEndPosition(endLineNumber: number, endColumn: number): Range;
+    /**
+     * Create a new range using this range's end position, and using startLineNumber and startColumn as the start position.
+     */
     setStartPosition(startLineNumber: number, startColumn: number): Range;
+    /**
+     * Create a new empty range using this range's start position.
+     */
     collapseToStart(): Range;
+    /**
+     * Create a new empty range using this range's start position.
+     */
     static collapseToStart(range: IRange): Range;
+    /**
+     * Create a new empty range using this range's end position.
+     */
     collapseToEnd(): Range;
+    /**
+     * Create a new empty range using this range's end position.
+     */
     static collapseToEnd(range: IRange): Range;
+    /**
+     * Moves the range by the given amount of lines.
+     */
     delta(lineCount: number): Range;
     isSingleLine(): boolean;
     static fromPositions(start: IPosition, end?: IPosition): Range;
+    /**
+     * Create a `Range` from an `IRange`.
+     */
     static lift(range: undefined | null): null;
     static lift(range: IRange): Range;
     static lift(range: IRange | undefined | null): Range | null;
+    /**
+     * Test if `obj` is an `IRange`.
+     */
     static isIRange(obj: any): obj is IRange;
+    /**
+     * Test if the two ranges are touching in any way.
+     */
     static areIntersectingOrTouching(a: IRange, b: IRange): boolean;
+    /**
+     * Test if the two ranges are intersecting. If the ranges are touching it returns true.
+     */
     static areIntersecting(a: IRange, b: IRange): boolean;
+    /**
+     * Test if the two ranges are intersecting, but not touching at all.
+     */
     static areOnlyIntersecting(a: IRange, b: IRange): boolean;
+    /**
+     * A function that compares ranges, useful for sorting ranges
+     * It will first compare ranges on the startPosition and then on the endPosition
+     */
     static compareRangesUsingStarts(a: IRange | null | undefined, b: IRange | null | undefined): number;
+    /**
+     * A function that compares ranges, useful for sorting ranges
+     * It will first compare ranges on the endPosition and then on the startPosition
+     */
     static compareRangesUsingEnds(a: IRange, b: IRange): number;
+    /**
+     * Test if the range spans multiple lines.
+     */
     static spansMultipleLines(range: IRange): boolean;
     toJSON(): IRange;
 }

package/vscode/src/vs/editor/common/core/ranges/columnRange.d.ts

@@ -1,10 +1,17 @@
 import { OffsetRange } from "./offsetRange.js";
 import { Range } from "../range.js";
+/**
+ * Represents a 1-based range of columns.
+ * Use {@lik OffsetRange} to represent a 0-based range.
+*/
 export declare class ColumnRange {
+    /** 1-based */
     readonly startColumn: number;
     readonly endColumnExclusive: number;
     static fromOffsetRange(offsetRange: OffsetRange): ColumnRange;
-    constructor(startColumn: number, endColumnExclusive: number);
+    constructor(
+    /** 1-based */
+    startColumn: number, endColumnExclusive: number);
     toRange(lineNumber: number): Range;
     equals(other: ColumnRange): boolean;
     toZeroBasedOffsetRange(): OffsetRange;

package/vscode/src/vs/editor/common/core/ranges/lineRange.d.ts

@@ -1,35 +1,79 @@
 import { OffsetRange } from "./offsetRange.js";
 import { Range } from "../range.js";
 import { Comparator } from "../../../../base/common/arrays.js";
+/**
+ * A range of lines (1-based).
+ */
 export declare class LineRange {
     static ofLength(startLineNumber: number, length: number): LineRange;
     static fromRange(range: Range): LineRange;
     static fromRangeInclusive(range: Range): LineRange;
     static readonly compareByStart: Comparator<LineRange>;
     static subtract(a: LineRange, b: LineRange | undefined): LineRange[];
+    /**
+     * @param lineRanges An array of arrays of of sorted line ranges.
+     */
     static joinMany(lineRanges: readonly (readonly LineRange[])[]): readonly LineRange[];
     static join(lineRanges: LineRange[]): LineRange;
+    /**
+     * @internal
+     */
     static deserialize(lineRange: ISerializedLineRange): LineRange;
+    /**
+     * The start line number.
+     */
     readonly startLineNumber: number;
+    /**
+     * The end line number (exclusive).
+     */
     readonly endLineNumberExclusive: number;
     constructor(startLineNumber: number, endLineNumberExclusive: number);
+    /**
+     * Indicates if this line range contains the given line number.
+     */
     contains(lineNumber: number): boolean;
     containsRange(range: LineRange): boolean;
+    /**
+     * Indicates if this line range is empty.
+     */
     get isEmpty(): boolean;
+    /**
+     * Moves this line range by the given offset of line numbers.
+     */
     delta(offset: number): LineRange;
     deltaLength(offset: number): LineRange;
+    /**
+     * The number of lines this line range spans.
+     */
     get length(): number;
+    /**
+     * Creates a line range that combines this and the given line range.
+     */
     join(other: LineRange): LineRange;
     toString(): string;
+    /**
+     * The resulting range is empty if the ranges do not intersect, but touch.
+     * If the ranges don't even touch, the result is undefined.
+     */
     intersect(other: LineRange): LineRange | undefined;
     intersectsStrict(other: LineRange): boolean;
     intersectsOrTouches(other: LineRange): boolean;
     equals(b: LineRange): boolean;
     toInclusiveRange(): Range | null;
+    /**
+     * @deprecated Using this function is discouraged because it might lead to bugs: The end position is not guaranteed to be a valid position!
+    */
     toExclusiveRange(): Range;
     mapToLineArray<T>(f: (lineNumber: number) => T): T[];
     forEach(f: (lineNumber: number) => void): void;
+    /**
+     * @internal
+     */
     serialize(): ISerializedLineRange;
+    /**
+     * Converts this 1-based line range to a 0-based offset range (subtracts 1!).
+     * @internal
+     */
     toOffsetRange(): OffsetRange;
     distanceToRange(other: LineRange): number;
     distanceToLine(lineNumber: number): number;
@@ -40,13 +84,25 @@ export type ISerializedLineRange = [
     endLineNumberExclusive: number
 ];
 export declare class LineRangeSet {
+    /**
+     * Sorted by start line number.
+     * No two line ranges are touching or intersecting.
+     */
     private readonly _normalizedRanges;
-    constructor(_normalizedRanges?: LineRange[]);
+    constructor(
+    /**
+     * Sorted by start line number.
+     * No two line ranges are touching or intersecting.
+     */
+    _normalizedRanges?: LineRange[]);
     get ranges(): readonly LineRange[];
     addRange(range: LineRange): void;
     contains(lineNumber: number): boolean;
     intersects(range: LineRange): boolean;
     getUnion(other: LineRangeSet): LineRangeSet;
+    /**
+     * Subtracts all ranges in this set from `range` and returns the result.
+     */
     subtractFrom(range: LineRange): LineRangeSet;
     toString(): string;
     getIntersection(other: LineRangeSet): LineRangeSet;

package/vscode/src/vs/editor/common/core/ranges/offsetRange.d.ts

@@ -2,6 +2,9 @@ export interface IOffsetRange {
     readonly start: number;
     readonly endExclusive: number;
 }
+/**
+ * A range of offsets (0-based).
+*/
 export declare class OffsetRange implements IOffsetRange {
     readonly start: number;
     readonly endExclusive: number;
@@ -21,7 +24,17 @@ export declare class OffsetRange implements IOffsetRange {
     equals(other: OffsetRange): boolean;
     containsRange(other: OffsetRange): boolean;
     contains(offset: number): boolean;
+    /**
+     * for all numbers n: range1.contains(n) or range2.contains(n) => range1.join(range2).contains(n)
+     * The joined range is the smallest range that contains both ranges.
+     */
     join(other: OffsetRange): OffsetRange;
+    /**
+     * for all numbers n: range1.contains(n) and range2.contains(n) <=> range1.intersect(range2).contains(n)
+     *
+     * The resulting range is empty if the ranges do not intersect, but touch.
+     * If the ranges don't even touch, the result is undefined.
+     */
     intersect(other: OffsetRange): OffsetRange | undefined;
     intersectionLength(range: OffsetRange): number;
     intersects(other: OffsetRange): boolean;
@@ -30,10 +43,24 @@ export declare class OffsetRange implements IOffsetRange {
     isAfter(other: OffsetRange): boolean;
     slice<T>(arr: readonly T[]): T[];
     substring(str: string): string;
+    /**
+     * Returns the given value if it is contained in this instance, otherwise the closest value that is contained.
+     * The range must not be empty.
+     */
     clip(value: number): number;
+    /**
+     * Returns `r := value + k * length` such that `r` is contained in this range.
+     * The range must not be empty.
+     *
+     * E.g. `[5, 10).clipCyclic(10) === 5`, `[5, 10).clipCyclic(11) === 6` and `[5, 10).clipCyclic(4) === 9`.
+     */
     clipCyclic(value: number): number;
     map<T>(f: (offset: number) => T): T[];
     forEach(f: (offset: number) => void): void;
+    /**
+     * this: [ 5, 10), range: [10, 15) => [5, 15)]
+     * Throws if the ranges are not touching.
+    */
     joinRightTouching(range: OffsetRange): OffsetRange;
 }
 export declare class OffsetRangeSet {
@@ -41,6 +68,9 @@ export declare class OffsetRangeSet {
     get ranges(): OffsetRange[];
     addRange(range: OffsetRange): void;
     toString(): string;
+    /**
+     * Returns of there is a value that is contained in this instance and the given range.
+     */
     intersectsStrict(other: OffsetRange): boolean;
     intersectWithRange(other: OffsetRange): OffsetRangeSet;
     intersectWithRangeLength(other: OffsetRange): number;

package/vscode/src/vs/editor/common/core/ranges/rangeSingleLine.d.ts

@@ -1,9 +1,15 @@
 import { ColumnRange } from "./columnRange.js";
 import { Range } from "../range.js";
+/**
+ * Represents a column range in a single line.
+*/
 export declare class RangeSingleLine {
+    /** 1-based */
     readonly lineNumber: number;
     readonly columnRange: ColumnRange;
     static fromRange(range: Range): RangeSingleLine | undefined;
-    constructor(lineNumber: number, columnRange: ColumnRange);
+    constructor(
+    /** 1-based */
+    lineNumber: number, columnRange: ColumnRange);
     toRange(): Range;
 }

package/vscode/src/vs/editor/common/core/selection.d.ts

@@ -1,33 +1,116 @@
 import { IPosition, Position } from "./position.js";
 import { Range } from "./range.js";
+/**
+ * A selection in the editor.
+ * The selection is a range that has an orientation.
+ */
 export interface ISelection {
+    /**
+     * The line number on which the selection has started.
+     */
     readonly selectionStartLineNumber: number;
+    /**
+     * The column on `selectionStartLineNumber` where the selection has started.
+     */
     readonly selectionStartColumn: number;
+    /**
+     * The line number on which the selection has ended.
+     */
     readonly positionLineNumber: number;
+    /**
+     * The column on `positionLineNumber` where the selection has ended.
+     */
     readonly positionColumn: number;
 }
+/**
+ * The direction of a selection.
+ */
 export declare enum SelectionDirection {
+    /**
+     * The selection starts above where it ends.
+     */
     LTR = 0,
+    /**
+     * The selection starts below where it ends.
+     */
     RTL = 1
 }
+/**
+ * A selection in the editor.
+ * The selection is a range that has an orientation.
+ */
 export declare class Selection extends Range {
+    /**
+     * The line number on which the selection has started.
+     */
     readonly selectionStartLineNumber: number;
+    /**
+     * The column on `selectionStartLineNumber` where the selection has started.
+     */
     readonly selectionStartColumn: number;
+    /**
+     * The line number on which the selection has ended.
+     */
     readonly positionLineNumber: number;
+    /**
+     * The column on `positionLineNumber` where the selection has ended.
+     */
     readonly positionColumn: number;
     constructor(selectionStartLineNumber: number, selectionStartColumn: number, positionLineNumber: number, positionColumn: number);
+    /**
+     * Transform to a human-readable representation.
+     */
     toString(): string;
+    /**
+     * Test if equals other selection.
+     */
     equalsSelection(other: ISelection): boolean;
+    /**
+     * Test if the two selections are equal.
+     */
     static selectionsEqual(a: ISelection, b: ISelection): boolean;
+    /**
+     * Get directions (LTR or RTL).
+     */
     getDirection(): SelectionDirection;
+    /**
+     * Create a new selection with a different `positionLineNumber` and `positionColumn`.
+     */
     setEndPosition(endLineNumber: number, endColumn: number): Selection;
+    /**
+     * Get the position at `positionLineNumber` and `positionColumn`.
+     */
     getPosition(): Position;
+    /**
+     * Get the position at the start of the selection.
+    */
     getSelectionStart(): Position;
+    /**
+     * Create a new selection with a different `selectionStartLineNumber` and `selectionStartColumn`.
+     */
     setStartPosition(startLineNumber: number, startColumn: number): Selection;
+    /**
+     * Create a `Selection` from one or two positions
+     */
     static fromPositions(start: IPosition, end?: IPosition): Selection;
+    /**
+     * Creates a `Selection` from a range, given a direction.
+     */
     static fromRange(range: Range, direction: SelectionDirection): Selection;
+    /**
+     * Create a `Selection` from an `ISelection`.
+     */
     static liftSelection(sel: ISelection): Selection;
+    /**
+     * `a` equals `b`.
+     */
     static selectionsArrEqual(a: ISelection[], b: ISelection[]): boolean;
+    /**
+     * Test if `obj` is an `ISelection`.
+     */
     static isISelection(obj: any): obj is ISelection;
+    /**
+     * Create with a direction.
+     */
     static createWithDirection(startLineNumber: number, startColumn: number, endLineNumber: number, endColumn: number, direction: SelectionDirection): Selection;
 }

package/vscode/src/vs/editor/common/core/stringBuilder.d.ts

@@ -10,7 +10,13 @@ export declare class StringBuilder {
     build(): string;
     private _buildBuffer;
     private _flushBuffer;
+    /**
+     * Append a char code (<2^16)
+     */
     appendCharCode(charCode: number): void;
+    /**
+     * Append an ASCII char code (<2^8)
+     */
     appendASCIICharCode(charCode: number): void;
     appendString(str: string): void;
 }

package/vscode/src/vs/editor/common/core/text/positionToOffsetImpl.d.ts

@@ -21,6 +21,7 @@ interface IDeps {
     TextEdit: typeof TextEdit;
     TextLength: typeof TextLength;
 }
+/** This is to break circular module dependencies. */
 export declare function _setPositionOffsetTransformerDependencies(deps: IDeps): void;
 export declare class PositionOffsetTransformer extends PositionOffsetTransformerBase {
     readonly text: string;

package/vscode/src/vs/editor/common/core/text/textLength.d.ts

@@ -1,6 +1,9 @@
 import { LineRange } from "../ranges/lineRange.js";
 import { Position } from "../position.js";
 import { Range } from "../range.js";
+/**
+ * Represents a non-negative length of text in terms of line and column count.
+*/
 export declare class TextLength {
     readonly lineCount: number;
     readonly columnCount: number;

package/vscode/src/vs/editor/common/core/wordHelper.d.ts

@@ -1,7 +1,19 @@
 export declare const USUAL_WORD_SEPARATORS = "`~!@#$%^&*()-=+[{]}\\|;:'\",.<>/?";
+/**
+ * Word inside a model.
+ */
 export interface IWordAtPosition {
+    /**
+     * The word.
+     */
     readonly word: string;
+    /**
+     * The column where the word starts.
+     */
     readonly startColumn: number;
+    /**
+     * The column where the word ends.
+     */
     readonly endColumn: number;
 }
 export declare const DEFAULT_WORD_REGEXP: RegExp;

package/vscode/src/vs/editor/common/cursor/cursorAtomicMoveOperations.d.ts

@@ -4,10 +4,25 @@ export declare enum Direction {
     Nearest = 2
 }
 export declare class AtomicTabMoveOperations {
+    /**
+     * Get the visible column at the position. If we get to a non-whitespace character first
+     * or past the end of string then return -1.
+     *
+     * **Note** `position` and the return value are 0-based.
+     */
     static whitespaceVisibleColumn(lineContent: string, position: number, tabSize: number): [
         number,
         number,
         number
     ];
+    /**
+     * Return the position that should result from a move left, right or to the
+     * nearest tab, if atomic tabs are enabled. Left and right are used for the
+     * arrow key movements, nearest is used for mouse selection. It returns
+     * -1 if atomic tabs are not relevant and you should fall back to normal
+     * behaviour.
+     *
+     * **Note**: `position` and the return value are 0-based.
+     */
     static atomicPosition(lineContent: string, position: number, tabSize: number, direction: Direction): number;
 }

package/vscode/src/vs/editor/common/cursor/cursorCollection.d.ts

@@ -4,6 +4,10 @@ import { Position } from "../core/position.js";
 import { ISelection, Selection } from "../core/selection.js";
 export declare class CursorCollection {
     private context;
+    /**
+     * `cursors[0]` is the primary cursor, thus `cursors.length >= 1` is always true.
+     * `cursors.slice(1)` are secondary cursors.
+    */
     private cursors;
     private lastAddedCursorIndex;
     constructor(context: CursorContext);
@@ -22,6 +26,9 @@ export declare class CursorCollection {
     setSelections(selections: ISelection[]): void;
     getPrimaryCursor(): CursorState;
     setStates(states: PartialCursorState[] | null): void;
+    /**
+     * Creates or disposes secondary cursors as necessary to match the number of `secondarySelections`.
+     */
     private _setSecondaryStates;
     killSecondaryCursors(): void;
     private _addSecondaryCursor;

package/vscode/src/vs/editor/common/cursor/cursorMoveCommands.d.ts

@@ -25,7 +25,13 @@ export declare class CursorMoveCommands {
     static simpleMove(viewModel: IViewModel, cursors: CursorState[], direction: CursorMove.SimpleMoveDirection, inSelectionMode: boolean, value: number, unit: CursorMove.Unit): PartialCursorState[] | null;
     static viewportMove(viewModel: IViewModel, cursors: CursorState[], direction: CursorMove.ViewportDirection, inSelectionMode: boolean, value: number): PartialCursorState[] | null;
     static findPositionInViewportIfOutside(viewModel: IViewModel, cursor: CursorState, visibleViewRange: Range, inSelectionMode: boolean): PartialCursorState;
+    /**
+     * Find the nth line start included in the range (from the start).
+     */
     private static _firstLineNumberInRange;
+    /**
+     * Find the nth line start included in the range (from the end).
+     */
     private static _lastLineNumberInRange;
     private static _moveLeft;
     private static _moveHalfLineLeft;
@@ -45,6 +51,9 @@ export declare class CursorMoveCommands {
 }
 export declare namespace CursorMove {
     const metadata: ICommandMetadata;
+    /**
+     * Positions in the view for cursor move command.
+     */
     const RawDirection: {
         Left: string;
         Right: string;
@@ -62,12 +71,18 @@ export declare namespace CursorMove {
         ViewPortBottom: string;
         ViewPortIfOutside: string;
     };
+    /**
+     * Units for Cursor move 'by' argument
+     */
     const RawUnit: {
         Line: string;
         WrappedLine: string;
         Character: string;
         HalfLine: string;
     };
+    /**
+     * Arguments for Cursor move command
+     */
     interface RawArguments {
         to: string;
         select?: boolean;

package/vscode/src/vs/editor/common/cursor/cursorMoveOperations.d.ts

@@ -12,7 +12,14 @@ export declare class MoveOperations {
     static leftPosition(model: ICursorSimpleModel, position: Position): Position;
     private static leftPositionAtomicSoftTabs;
     private static left;
+    /**
+     * @param noOfColumns Must be either `1`
+     * or `Math.round(viewModel.getLineContent(viewLineNumber).length / 2)` (for half lines).
+    */
     static moveLeft(config: CursorConfiguration, model: ICursorSimpleModel, cursor: SingleCursorState, inSelectionMode: boolean, noOfColumns: number): SingleCursorState;
+    /**
+     * Adjusts the column so that it is within min/max of the line.
+    */
     private static clipPositionColumn;
     private static clipRange;
     static rightPosition(model: ICursorSimpleModel, lineNumber: number, column: number): Position;