@pulsar-edit/types 1.128.1

package/src/text-editor.d.ts

@@ -0,0 +1,1416 @@
+import {
+  BufferScanResult,
+  BufferStoppedChangingEvent,
+  ContextualBufferScanResult,
+  Cursor,
+  CursorPositionChangedEvent,
+  Decoration,
+  DecorationLayerOptions,
+  DecorationOptions,
+  DisplayMarker,
+  DisplayMarkerLayer,
+  Disposable,
+  EditorChangedEvent,
+  FindDisplayMarkerOptions,
+  Grammar,
+  Gutter,
+  GutterOptions,
+  LayerDecoration,
+  MarkerLayer,
+  Point,
+  PointCompatible,
+  Range,
+  RangeCompatible,
+  RangeLike,
+  ReadonlyEditOptions,
+  ScanContextOptions,
+  ScopeDescriptor,
+  Selection,
+  SelectionChangedEvent,
+  TextBuffer,
+  TextEditOptions,
+  TextEditorElement,
+  TextInsertionOptions,
+} from "../index";
+import { CommentDelimiterSpec } from "./wasm-tree-sitter-grammar";
+
+/**
+ *  This class represents all essential editing state for a single TextBuffer,
+ *  including cursor and selection positions, folds, and soft wraps.
+ */
+export class TextEditor {
+  readonly id: number;
+
+  // NOTE: Undocumented within the public API. Don't go down the rabbit hole.
+  constructor(options?: object);
+
+  /** Get the custom HTML element for the editor. */
+  getElement(): TextEditorElement;
+
+  /**
+   * Private: update various properties on the editor instance after creation.
+   *
+   * Returns a promise that resolves when the view layer is updated as a result
+   * of these property changes.
+   */
+  update(params: object): Promise<void>;
+
+  // Event Subscription
+  /** Calls your callback when the buffer's title has changed. */
+  onDidChangeTitle(callback: (title: string) => void): Disposable;
+
+  /** Calls your callback when the buffer's path, and therefore title, has changed. */
+  onDidChangePath(callback: (path: string) => void): Disposable;
+
+  /**
+   * Invoke the given callback synchronously when the content of the buffer
+   * changes.
+   */
+  onDidChange(callback: (event: EditorChangedEvent[]) => void): Disposable;
+
+  /**
+   * Invoke callback when the buffer's contents change. It is emit
+   * asynchronously 300ms after the last buffer change. This is a good place
+   * to handle changes to the buffer without compromising typing performance.
+   */
+  onDidStopChanging(callback: (event: BufferStoppedChangingEvent) => void): Disposable;
+
+  /**
+   * Calls your callback when a Cursor is moved. If there are multiple cursors,
+   * your callback will be called for each cursor.
+   */
+  onDidChangeCursorPosition(callback: (event: CursorPositionChangedEvent) => void): Disposable;
+
+  /** Calls your callback when a selection's screen range changes. */
+  onDidChangeSelectionRange(callback: (event: SelectionChangedEvent) => void): Disposable;
+
+  /** Invoke the given callback after the buffer is saved to disk. */
+  onDidSave(callback: (event: { path: string }) => void): Disposable;
+
+  /** Invoke the given callback when the editor is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  /** Retrieves the current TextBuffer. */
+  getBuffer(): TextBuffer;
+
+  /** Sets the read-only state for the editor. */
+  setReadOnly(readonly: boolean): void;
+
+  /** Whether or not this editor is in read-only mode. */
+  isReadOnly(): boolean;
+
+  /**
+   * Calls your callback when a Gutter is added to the editor. Immediately calls
+   * your callback for each existing gutter.
+   */
+  observeGutters(callback: (gutter: Gutter) => void): Disposable;
+
+  /** Calls your callback when a Gutter is added to the editor. */
+  onDidAddGutter(callback: (gutter: Gutter) => void): Disposable;
+
+  /** Calls your callback when a Gutter is removed from the editor. */
+  onDidRemoveGutter(callback: (name: string) => void): Disposable;
+
+  /** Calls your callback when soft wrap was enabled or disabled. */
+  onDidChangeSoftWrapped(callback: (softWrapped: boolean) => void): Disposable;
+
+  /** Calls your callback when the buffer's encoding has changed. */
+  onDidChangeEncoding(callback: (encoding: string) => void): Disposable;
+
+  /**
+   * Calls your callback when the grammar that interprets and colorizes the text
+   * has been changed. Immediately calls your callback with the current grammar.
+   */
+  observeGrammar(callback: (grammar: Grammar) => void): Disposable;
+
+  /**
+   * Calls your callback when the grammar that interprets and colorizes the text
+   * has been changed.
+   */
+  onDidChangeGrammar(callback: (grammar: Grammar) => void): Disposable;
+
+  /** Calls your callback when the result of ::isModified changes. */
+  onDidChangeModified(callback: (modified: boolean) => void): Disposable;
+
+  /**
+   * Calls your callback when the buffer's underlying file changes on disk at a
+   * moment when the result of ::isModified is true.
+   */
+  onDidConflict(callback: () => void): Disposable;
+
+  /** Calls your callback before text has been inserted. */
+  onWillInsertText(callback: (event: { text: string; cancel(): void }) => void): Disposable;
+
+  /** Calls your callback after text has been inserted. */
+  onDidInsertText(callback: (event: { text: string }) => void): Disposable;
+
+  /**
+   * Calls your callback when a Cursor is added to the editor. Immediately calls
+   * your callback for each existing cursor.
+   */
+  observeCursors(callback: (cursor: Cursor) => void): Disposable;
+
+  /** Calls your callback when a Cursor is added to the editor. */
+  onDidAddCursor(callback: (cursor: Cursor) => void): Disposable;
+
+  /** Calls your callback when a Cursor is removed from the editor. */
+  onDidRemoveCursor(callback: (cursor: Cursor) => void): Disposable;
+
+  /**
+   * Calls your callback when a Selection is added to the editor. Immediately
+   * calls your callback for each existing selection.
+   */
+  observeSelections(callback: (selection: Selection) => void): Disposable;
+
+  /** Calls your callback when a Selection is added to the editor. */
+  onDidAddSelection(callback: (selection: Selection) => void): Disposable;
+
+  /** Calls your callback when a Selection is removed from the editor. */
+  onDidRemoveSelection(callback: (selection: Selection) => void): Disposable;
+
+  /**
+   * Calls your callback with each Decoration added to the editor. Calls your
+   * callback immediately for any existing decorations.
+   */
+  observeDecorations(callback: (decoration: Decoration) => void): Disposable;
+
+  /** Calls your callback when a Decoration is added to the editor. */
+  onDidAddDecoration(callback: (decoration: Decoration) => void): Disposable;
+
+  /** Calls your callback when a Decoration is removed from the editor. */
+  onDidRemoveDecoration(callback: (decoration: Decoration) => void): Disposable;
+
+  /** Calls your callback when the placeholder text is changed. */
+  onDidChangePlaceholderText(callback: (placeholderText: string) => void): Disposable;
+
+  // File Details
+  /**
+   * Get the editor's title for display in other parts of the UI such as the
+   * tabs.
+   *
+   * If the editor's buffer is saved, its title is the file name. If it is
+   * unsaved, its title is "untitled".
+   */
+  getTitle(): string;
+
+  /**
+   * Get unique title for display in other parts of the UI, such as the window
+   * title.
+   *
+   * If the editor's buffer is unsaved, its title is "untitled."
+   *
+   * If the editor's buffer is saved, its unique title is formatted as one of
+   * the following:
+   *
+   *  "" when it is the only editing buffer with this file name.
+   *  " — " when other buffers have this file name.
+   */
+  getLongTitle(): string;
+
+  /** Return the string path of this editor's text buffer. */
+  getPath(): string | undefined;
+
+  /** Return boolean true if this editor has been modified. */
+  isModified(): boolean;
+
+  /** Return boolean true if this editor has no content. */
+  isEmpty(): boolean;
+
+  /** Return true if this editor has not yet been destroyed. */
+  isAlive(): boolean;
+
+  /** Returns the string character set encoding of this editor's text buffer. */
+  getEncoding(): string;
+
+  /** Set the character set encoding to use in this editor's text buffer. */
+  setEncoding(encoding: string): void;
+
+  // File Operations
+  /**
+   * Saves the editor's text buffer.
+   *
+   * See {@link TextBuffer#save}.
+   */
+  save(): Promise<void>;
+
+  /**
+   * Saves the editor's text buffer as the given path.
+   *
+   * See {@link TextBuffer#saveAs} for more details.
+   */
+  saveAs(filePath: string): Promise<void>;
+
+  // Reading Text
+  /** Returns a string representing the entire contents of the editor. */
+  getText(): string;
+
+  /** Get the text in the given range in buffer coordinates. */
+  getTextInBufferRange(range: RangeCompatible): string;
+
+  /** Returns a number representing the number of lines in the buffer. */
+  getLineCount(): number;
+
+  /**
+   * Returns a number representing the number of screen lines in the editor.
+   *
+   * This accounts for folds.
+   */
+  getScreenLineCount(): number;
+
+  /**
+   * Returns a number representing the last zero-indexed buffer row number of
+   * the editor.
+   */
+  getLastBufferRow(): number;
+
+  /**
+   * Returns a number representing the last zero-indexed screen row number of
+   * the editor.
+   */
+  getLastScreenRow(): number;
+
+  /**
+   * Returns a string representing the contents of the line at the given
+   * buffer row.
+   */
+  lineTextForBufferRow(bufferRow: number): string;
+
+  /**
+   * Returns a string representing the contents of the line at the given
+   * screen row.
+   */
+  lineTextForScreenRow(screenRow: number): string;
+
+  /**
+   * Get the range of the paragraph surrounding the most recently added cursor.
+   */
+  getCurrentParagraphBufferRange(): Range;
+
+  // Mutating Text
+  /** Replaces the entire contents of the buffer with the given string. */
+  setText(text: string, options?: ReadonlyEditOptions): void;
+
+  /** Set the text in the given Range in buffer coordinates. */
+  setTextInBufferRange(range: RangeCompatible, text: string, options?: TextEditOptions & ReadonlyEditOptions): Range;
+
+  /** For each selection, replace the selected text with the given text. */
+  insertText(text: string, options?: TextInsertionOptions & ReadonlyEditOptions): Range | false;
+
+  /** For each selection, replace the selected text with a newline. */
+  insertNewline(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete the character
+   * following the cursor. Otherwise delete the selected text.
+   */
+  delete(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete the character
+   * preceding the cursor. Otherwise delete the selected text.
+   */
+  backspace(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Mutate the text of all the selections in a single transaction. All the
+   * changes made inside the given function can be reverted with a single call
+   * to {@link undo}.
+   */
+  mutateSelectedText(fn: (selection: Selection, index: number) => void): void;
+
+  /**
+   * For each selection, transpose the selected text.
+   * If the selection is empty, the characters preceding and following the cursor
+   * are swapped. Otherwise, the selected characters are reversed.
+   */
+  transpose(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Convert the selected text to upper case.
+   * For each selection, if the selection is empty, converts the containing word
+   * to upper case. Otherwise convert the selected text to upper case.
+   */
+  upperCase(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Convert the selected text to lower case.
+   * For each selection, if the selection is empty, converts the containing word
+   * to upper case. Otherwise convert the selected text to upper case.
+   */
+  lowerCase(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Toggle line comments for rows intersecting selections.
+   * If the current grammar doesn't support comments, does nothing.
+   */
+  toggleLineCommentsInSelection(options?: ReadonlyEditOptions): void;
+
+  /** For each cursor, insert a newline at beginning the following line. */
+  insertNewlineBelow(options?: ReadonlyEditOptions): void;
+
+  /** For each cursor, insert a newline at the end of the preceding line. */
+  insertNewlineAbove(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete all characters of the
+   * containing word that precede the cursor. Otherwise delete the selected text.
+   */
+  deleteToBeginningOfWord(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Similar to {@link deleteToBeginningOfWord}, but deletes only back to the
+   * previous word boundary.
+   */
+  deleteToPreviousWordBoundary(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Similar to {@link deleteToEndOfWord}, but deletes only up to the next word
+   * boundary.
+   */
+  deleteToNextWordBoundary(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete all characters of
+   * the containing subword following the cursor. Otherwise delete the selected
+   * text.
+   */
+  deleteToBeginningOfSubword(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete all characters of
+   * the containing subword following the cursor. Otherwise delete the selected
+   * text.
+   */
+  deleteToEndOfSubword(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete all characters of
+   * the containing line that precede the cursor. Otherwise delete the selected
+   * text.
+   */
+  deleteToBeginningOfLine(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is not empty, deletes the selection
+   * otherwise, deletes all characters of the containing line following the
+   * cursor.
+   *
+   * If the cursor is already at the end of the line, deletes the following
+   * newline.
+   */
+  deleteToEndOfLine(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, delete all characters of
+   * the containing word following the cursor. Otherwise delete the selected
+   * text.
+   */
+  deleteToEndOfWord(options?: ReadonlyEditOptions): void;
+
+  /** Delete all lines intersecting selections. */
+  deleteLine(options?: ReadonlyEditOptions): void;
+
+  // History
+  /** Undo the last change. */
+  undo(options?: ReadonlyEditOptions): void;
+
+  /** Redo the last change. */
+  redo(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Batch multiple operations as a single undo/redo step.
+   *
+   * Any group of operations that are logically grouped from the perspective of
+   * undoing and redoing should be performed in a transaction. If you want to
+   * abort the transaction, call {@link abortTransaction} to terminate the
+   * function's execution and revert any changes performed up to the abortion.
+   */
+  transact(fn: () => void): void;
+  /**
+   * Batch multiple operations as a single undo/redo step.
+   *
+   * Any group of operations that are logically grouped from the perspective of
+   * undoing and redoing should be performed in a transaction. If you want to
+   * abort the transaction, call {@link abortTransaction} to terminate the
+   * function's execution and revert any changes performed up to the abortion.
+   */
+  transact(groupingInterval: number, fn: () => void): void;
+
+  /**
+   * Abort an open transaction, undoing any operations performed so far within
+   * the transaction.
+   */
+  abortTransaction(): void;
+
+  /**
+   * Create a pointer to the current state of the buffer for use with
+   * {@link revertToCheckpoint} and {@link groupChangesSinceCheckpoint}.
+   */
+  createCheckpoint(): number;
+
+  /**
+   * Revert the buffer to the state it was in when the given checkpoint was
+   * created.
+   *
+   * The redo stack will be empty following this operation, so changes since
+   * the checkpoint will be lost. If the given checkpoint is no longer present
+   * in the undo history, no changes will be made to the buffer and this method
+   * will return `false`.
+   */
+  revertToCheckpoint(checkpoint: number): boolean;
+
+  /**
+   * Group all changes since the given checkpoint into a single transaction for
+   * purposes of undo/redo.
+   *
+   * If the given checkpoint is no longer present in the undo history, no
+   * grouping will be performed and this method will return false.
+   */
+  groupChangesSinceCheckpoint(checkpoint: number): boolean;
+
+  // TextEditor Coordinates
+  /** Convert a position in buffer-coordinates to screen-coordinates. */
+  screenPositionForBufferPosition(
+    bufferPosition: PointCompatible,
+    options?: { clipDirection?: "backward" | "forward" | "closest" | undefined },
+  ): Point;
+
+  /** Convert a position in screen-coordinates to buffer-coordinates. */
+  bufferPositionForScreenPosition(
+    bufferPosition: PointCompatible,
+    options?: { clipDirection?: "backward" | "forward" | "closest" | undefined },
+  ): Point;
+
+  /** Convert a range in buffer-coordinates to screen-coordinates. */
+  screenRangeForBufferRange(bufferRange: RangeCompatible): Range;
+
+  /** Convert a range in screen-coordinates to buffer-coordinates. */
+  bufferRangeForScreenRange(screenRange: RangeCompatible): Range;
+
+  /** Clip the given Point to a valid position in the buffer. */
+  clipBufferPosition(bufferPosition: PointCompatible): Point;
+
+  /**
+   * Clip the start and end of the given range to valid positions in the
+   * buffer. See {@link clipBufferPosition} for more information.
+   */
+  clipBufferRange(range: RangeCompatible): Range;
+
+  /** Clip the given Point to a valid position on screen. */
+  clipScreenPosition(
+    screenPosition: PointCompatible,
+    options?: { clipDirection?: "backward" | "forward" | "closest" | undefined },
+  ): Point;
+
+  /**
+   * Clip the start and end of the given range to valid positions on screen.
+   * See {@link clipScreenPosition} for more information.
+   */
+  clipScreenRange(
+    range: RangeCompatible,
+    options?: { clipDirection?: "backward" | "forward" | "closest" | undefined },
+  ): Range;
+
+  // Decorations
+  /**
+   * Add a decoration that tracks a DisplayMarker. When the marker moves, is
+   * invalidated, or is destroyed, the decoration will be updated to reflect
+   * the marker's state.
+   */
+  decorateMarker(marker: DisplayMarker, decorationParams: DecorationOptions): Decoration;
+
+  /**
+   * Add a decoration to every marker in the given marker layer. Can be used to
+   * decorate a large number of markers without having to create and manage
+   * many individual decorations.
+   */
+  decorateMarkerLayer(
+    markerLayer: MarkerLayer | DisplayMarkerLayer,
+    decorationParams: DecorationLayerOptions,
+  ): LayerDecoration;
+
+  /** Get all decorations. */
+  getDecorations(propertyFilter?: DecorationOptions): Decoration[];
+
+  /** Get all decorations of type 'line'. */
+  getLineDecorations(propertyFilter?: DecorationOptions): Decoration[];
+
+  /** Get all decorations of type 'line-number'. */
+  getLineNumberDecorations(propertyFilter?: DecorationOptions): Decoration[];
+
+  /** Get all decorations of type 'highlight'. */
+  getHighlightDecorations(propertyFilter?: DecorationOptions): Decoration[];
+
+  /** Get all decorations of type 'overlay'. */
+  getOverlayDecorations(propertyFilter?: DecorationOptions): Decoration[];
+
+  // Markers
+  /**
+   * Create a marker on the default marker layer with the given range in buffer
+   * coordinates.
+   *
+   * This marker will maintain its logical location as the buffer is changed,
+   * so if you mark a particular word, the marker will remain over that word
+   * even if the word's location in the buffer changes.
+   */
+  markBufferRange(
+    range: RangeCompatible,
+    properties?: {
+      maintainHistory?: boolean | undefined;
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Create a marker on the default marker layer with the given range in screen
+   * coordinates.
+   *
+   * This marker will maintain its logical location as the buffer is changed,
+   * so if you mark a particular word, the marker will remain over that word
+   * even if the word's location in the buffer changes.
+   */
+  markScreenRange(
+    range: RangeCompatible,
+    properties?: {
+      maintainHistory?: boolean | undefined;
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Create a marker on the default marker layer with the given buffer position
+   * and no tail. To group multiple markers together in their own private
+   * layer, see {@link addMarkerLayer}.
+   */
+  markBufferPosition(
+    bufferPosition: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Create a marker on the default marker layer with the given screen position
+   * and no tail. To group multiple markers together in their own private
+   * layer, see {@link addMarkerLayer}.
+   */
+  markScreenPosition(
+    screenPosition: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      clipDirection?: "backward" | "forward" | "closest" | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Find all DisplayMarkers on the default marker layer that match the given properties.
+   *
+   * This method finds markers based on the given properties. Markers can be
+   * associated with custom properties that will be compared with basic
+   * equality. In addition, there are several special properties that will be
+   * compared with the range of the markers rather than their properties.
+   */
+  findMarkers(properties: FindDisplayMarkerOptions): DisplayMarker[];
+
+  /** Create a marker layer to group related markers. */
+  addMarkerLayer(
+    options?: { maintainHistory?: boolean | undefined; persistent?: boolean | undefined },
+  ): DisplayMarkerLayer;
+
+  /** Get a DisplayMarkerLayer by id. */
+  getMarkerLayer(id: number): DisplayMarkerLayer | undefined;
+
+  /**
+   * Get the default DisplayMarkerLayer.
+   *
+   * All marker APIs not tied to an explicit layer interact with this default
+   * layer.
+   */
+  getDefaultMarkerLayer(): DisplayMarkerLayer;
+
+  /** Get the DisplayMarker on the default layer for the given marker id. */
+  getMarker(id: number): DisplayMarker;
+
+  /**
+   * Get all DisplayMarkers on the default marker layer.
+   *
+   * Consider using {@link findMarkers}.
+   */
+  getMarkers(): DisplayMarker[];
+
+  /** Get the number of markers in the default marker layer. */
+  getMarkerCount(): number;
+
+  // Cursors
+  /**
+   * Get the position of the most recently added cursor in buffer coordinates.
+   */
+  getCursorBufferPosition(): Point;
+
+  /** Get the position of all the cursor positions in buffer coordinates. */
+  getCursorBufferPositions(): Point[];
+
+  /**
+   * Move the cursor to the given position in buffer coordinates.
+   *
+   * If there are multiple cursors, they will be consolidated to a single
+   * cursor.
+   */
+  setCursorBufferPosition(position: PointCompatible, options?: { autoscroll?: boolean | undefined }): void;
+
+  /** Get a {@link Cursor} at the given screen coordinates, if one exists. */
+  getCursorAtScreenPosition(position: PointCompatible): Cursor | undefined;
+
+  /**
+   * Get the position of the most recently added cursor in screen coordinates.
+   */
+  getCursorScreenPosition(): Point;
+
+  /** Get the positions of all the cursors in screen coordinates. */
+  getCursorScreenPositions(): Point[];
+
+  /**
+   * Move the cursor to the given position in screen coordinates.
+   *
+   * If there are multiple cursors, they will be consolidated to a single
+   * cursor.
+   */
+  setCursorScreenPosition(position: PointCompatible, options?: { autoscroll?: boolean | undefined }): void;
+
+  /** Add a cursor at the given position in buffer coordinates. */
+  addCursorAtBufferPosition(bufferPosition: PointCompatible, options?: { autoscroll?: boolean | undefined }): Cursor;
+
+  /** Add a cursor at the position in screen coordinates. */
+  addCursorAtScreenPosition(screenPosition: PointCompatible): Cursor;
+
+  /** Returns a boolean indicating whether or not there are multiple cursors. */
+  hasMultipleCursors(): boolean;
+
+  /** Move every cursor up one row in screen coordinates. */
+  moveUp(lineCount?: number): void;
+
+  /** Move every cursor down one row in screen coordinates. */
+  moveDown(lineCount?: number): void;
+
+  /** Move every cursor left one column. */
+  moveLeft(columnCount?: number): void;
+
+  /** Move every cursor right one column. */
+  moveRight(columnCount?: number): void;
+
+  /** Move every cursor to the beginning of its line in buffer coordinates. */
+  moveToBeginningOfLine(): void;
+
+  /** Move every cursor to the beginning of its line in screen coordinates. */
+  moveToBeginningOfScreenLine(): void;
+
+  /** Move every cursor to the first non-whitespace character of its line. */
+  moveToFirstCharacterOfLine(): void;
+
+  /** Move every cursor to the end of its line in buffer coordinates. */
+  moveToEndOfLine(): void;
+
+  /** Move every cursor to the end of its line in screen coordinates. */
+  moveToEndOfScreenLine(): void;
+
+  /** Move every cursor to the beginning of its surrounding word. */
+  moveToBeginningOfWord(): void;
+
+  /** Move every cursor to the end of its surrounding word. */
+  moveToEndOfWord(): void;
+
+  /**
+   * Move every cursor to the top of the buffer.
+   *
+   * If there are multiple cursors, they will be merged into a single cursor.
+   */
+  moveToTop(): void;
+
+  /**
+   * Move every cursor to the bottom of the buffer.
+   *
+   * If there are multiple cursors, they will be merged into a single cursor.
+   */
+  moveToBottom(): void;
+
+  /** Move every cursor to the beginning of the next word. */
+  moveToBeginningOfNextWord(): void;
+
+  /** Move every cursor to the previous word boundary. */
+  moveToPreviousWordBoundary(): void;
+
+  /** Move every cursor to the next word boundary. */
+  moveToNextWordBoundary(): void;
+
+  /** Move every cursor to the previous subword boundary. */
+  moveToPreviousSubwordBoundary(): void;
+
+  /** Move every cursor to the next subword boundary. */
+  moveToNextSubwordBoundary(): void;
+
+  /** Move every cursor to the beginning of the next paragraph. */
+  moveToBeginningOfNextParagraph(): void;
+
+  /** Move every cursor to the beginning of the previous paragraph. */
+  moveToBeginningOfPreviousParagraph(): void;
+
+  /** Returns the most recently added Cursor. */
+  getLastCursor(): Cursor;
+
+  /** Returns the word surrounding the most recently added cursor. */
+  getWordUnderCursor(options?: {
+    wordRegex?: RegExp | undefined;
+    includeNonWordCharacters?: boolean | undefined;
+    allowPrevious?: boolean | undefined;
+  }): string;
+
+  /** Get an Array of all Cursors. */
+  getCursors(): Cursor[];
+
+  /**
+   * Get all cursors, ordered by their position in the buffer instead of the
+   * order in which they were added.
+   */
+  getCursorsOrderedByBufferPosition(): Cursor[];
+
+  // Selections
+  /** Get the selected text of the most recently added selection. */
+  getSelectedText(): string;
+
+  /**
+   * Get the {@link Range} of the most recently added selection in buffer
+   * coordinates.
+   */
+  getSelectedBufferRange(): Range;
+
+  /**
+   * Get the {@link Range}s of all selections in buffer coordinates.
+   *
+   * The ranges are sorted by when the selections were added, most recent at
+   * the end.
+   */
+  getSelectedBufferRanges(): Range[];
+
+  /**
+   * Set the selected range in buffer coordinates. If there are multiple
+   * selections, they are reduced to a single selection with the given range.
+   */
+  setSelectedBufferRange(
+    bufferRange: RangeCompatible,
+    options?: { reversed?: boolean | undefined; preserveFolds?: boolean | undefined },
+  ): void;
+
+  /**
+   * Set the selected ranges in buffer coordinates. If there are multiple
+   * selections, they are replaced by new selections with the given ranges.
+   */
+  setSelectedBufferRanges(
+    bufferRanges: readonly RangeCompatible[],
+    options?: { reversed?: boolean | undefined; preserveFolds?: boolean | undefined },
+  ): void;
+
+  /**
+   * Get the {@link Range} of the most recently added selection in screen
+   * coordinates.
+   */
+  getSelectedScreenRange(): Range;
+
+  /**
+   * Get the {@link Range}s of all selections in screen coordinates.
+   *
+   * The ranges are sorted by when the selections were added, most recent at
+   * the end.
+   */
+  getSelectedScreenRanges(): Range[];
+
+  /**
+   * Set the selected range in screen coordinates.
+   *
+   * If there are multiple selections, they are reduced to a single selection
+   * with the given range.
+   */
+  setSelectedScreenRange(screenRange: RangeCompatible, options?: { reversed?: boolean | undefined }): void;
+
+  /**
+   * Set the selected ranges in screen coordinates.
+   *
+   * If there are multiple selections, they are replaced by new selections with
+   * the given ranges.
+   */
+  setSelectedScreenRanges(
+    screenRanges: readonly RangeCompatible[],
+    options?: { reversed?: boolean | undefined },
+  ): void;
+
+  /** Add a selection for the given range in buffer coordinates. */
+  addSelectionForBufferRange(
+    bufferRange: RangeCompatible,
+    options?: { reversed?: boolean | undefined; preserveFolds?: boolean | undefined },
+  ): Selection;
+
+  /** Add a selection for the given range in screen coordinates. */
+  addSelectionForScreenRange(
+    screenRange: RangeCompatible,
+    options?: { reversed?: boolean | undefined; preserveFolds?: boolean | undefined },
+  ): Selection;
+
+  /**
+   * Select from the current cursor position to the given position in buffer
+   * coordinates.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToBufferPosition(position: PointCompatible): void;
+
+  /**
+   * Select from the current cursor position to the given position in screen
+   * coordinates.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToScreenPosition(position: PointCompatible): void;
+
+  /**
+   * Move the cursor of each selection one character upward while preserving
+   * the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectUp(rowCount?: number): void;
+
+  /**
+   * Move the cursor of each selection one character downward while preserving
+   * the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectDown(rowCount?: number): void;
+
+  /**
+   * Move the cursor of each selection one character leftward while preserving
+   * the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectLeft(columnCount?: number): void;
+
+  /**
+   * Move the cursor of each selection one character rightward while preserving
+   * the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectRight(columnCount?: number): void;
+
+  /**
+   * Select from the top of the buffer to the end of the last selection in the
+   * buffer.
+   *
+   * This method merges multiple selections into a single selection.
+   */
+  selectToTop(): void;
+
+  /**
+   * Selects from the top of the first selection in the buffer to the end of
+   * the buffer.
+   *
+   * This method merges multiple selections into a single selection.
+   */
+  selectToBottom(): void;
+
+  /**
+   * Select all text in the buffer.
+   *
+   * This method merges multiple selections into a single selection.
+   */
+  selectAll(): void;
+
+  /**
+   * Move the cursor of each selection to the beginning of its line while
+   * preserving the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToBeginningOfLine(): void;
+
+  /**
+   * Move the cursor of each selection to the first non-whitespace character of
+   * its line while preserving the selection's tail position.
+   *
+   * If the cursor is already on the first character of the line, move it to
+   * the beginning of the line. This method may merge selections that end up
+   * intersecting.
+   */
+  selectToFirstCharacterOfLine(): void;
+
+  /**
+   * Move the cursor of each selection to the end of its line while preserving
+   * the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToEndOfLine(): void;
+
+  /**
+   * Expand selections to the beginning of their containing word.
+   *
+   * Operates on all selections. Moves the cursor to the beginning of the
+   * containing word while preserving the selection's tail position.
+   */
+  selectToBeginningOfWord(): void;
+
+  /**
+   * Expand selections to the end of their containing word.
+   *
+   * Operates on all selections. Moves the cursor to the end of the containing
+   * word while preserving the selection's tail position.
+   */
+  selectToEndOfWord(): void;
+
+  /**
+   * For each cursor, select the containing line.
+   *
+   * This method merges selections on successive lines.
+   */
+  selectLinesContainingCursors(): void;
+
+  /** Select the word surrounding each cursor. */
+  selectWordsContainingCursors(): void;
+
+  /**
+   * For each selection, move its cursor to the preceding subword boundary
+   * while maintaining the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToPreviousSubwordBoundary(): void;
+
+  /**
+   * For each selection, move its cursor to the next subword boundary while
+   * maintaining the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToNextSubwordBoundary(): void;
+
+  /**
+   * For each selection, move its cursor to the preceding word boundary while
+   * maintaining the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToPreviousWordBoundary(): void;
+
+  /**
+   * For each selection, move its cursor to the next word boundary while
+   * maintaining the selection's tail position.
+   *
+   * This method may merge selections that end up intersecting.
+   */
+  selectToNextWordBoundary(): void;
+
+  /**
+   * Expand selections to the beginning of the next word.
+   *
+   * Operates on all selections. Moves the cursor to the beginning of the next
+   * word while preserving the selection's tail position.
+   */
+  selectToBeginningOfNextWord(): void;
+
+  /**
+   * Expand selections to the beginning of the next paragraph.
+   *
+   * Operates on all selections. Moves the cursor to the beginning of the next
+   * paragraph while preserving the selection's tail position.
+   */
+  selectToBeginningOfNextParagraph(): void;
+
+  /**
+   * Expand selections to the beginning of the next paragraph.
+   *
+   * Operates on all selections. Moves the cursor to the beginning of the next
+   * paragraph while preserving the selection's tail position.
+   */
+  selectToBeginningOfPreviousParagraph(): void;
+
+  /** For each selection, select the syntax node that contains that selection. */
+  selectLargerSyntaxNode(): void;
+
+  /**
+   * Undo the effect of a preceding call to {@link selectLargerSyntaxNode},
+   * narrowing the selection in the process.
+   */
+  selectSmallerSyntaxNode(): void;
+
+  /** Select the range of the given marker if it is valid. */
+  selectMarker(marker: DisplayMarker): Range | undefined;
+
+  /** Get the most recently added Selection. */
+  getLastSelection(): Selection;
+
+  /** Get current Selections. */
+  getSelections(): Selection[];
+
+  /**
+   * Get all Selections, ordered by their position in the buffer instead of the
+   * order in which they were added.
+   */
+  getSelectionsOrderedByBufferPosition(): Selection[];
+
+  // NOTE: this calls into Selection::intersectsBufferRange, which itself calls
+  // into Range::intersectsWith. Range::intersectsWith is one of the few functions
+  // which does NOT take a range-compatible array.
+  /** Determine if a given range in buffer coordinates intersects a selection. */
+  selectionIntersectsBufferRange(bufferRange: RangeLike): boolean;
+
+  // Searching and Replacing
+  /**
+   * Scan regular expression matches in the entire buffer, calling the given
+   * iterator function on each match.
+   *
+   * ::scan functions as the replace method as well via the replace.
+   */
+  scan(regex: RegExp, options: ScanContextOptions, iterator: (params: ContextualBufferScanResult) => void): void;
+
+  /**
+   * Scan regular expression matches in the entire buffer, calling the given
+   * iterator function on each match.
+   *
+   * ::scan functions as the replace method as well via the replace.
+   */
+  scan(regex: RegExp, iterator: (params: BufferScanResult) => void): void;
+
+  /**
+   * Scan regular expression matches in a given range, calling the given
+   * iterator. function on each match.
+   */
+  scanInBufferRange(regex: RegExp, range: RangeCompatible, iterator: (params: BufferScanResult) => void): void;
+
+  /**
+   * Scan regular expression matches in a given range in reverse order, calling
+   * the given iterator function on each match.
+   */
+  backwardsScanInBufferRange(
+    regex: RegExp,
+    range: RangeCompatible,
+    iterator: (params: BufferScanResult) => void,
+  ): void;
+
+  // Tab Behavior
+  /** Return whether soft tabs are enabled for this editor. */
+  getSoftTabs(): boolean;
+
+  /** Enable or disable soft tabs for this editor. */
+  setSoftTabs(softTabs: boolean): void;
+
+  /** Toggle soft tabs for this editor. */
+  toggleSoftTabs(): boolean;
+
+  /** Get the on-screen length of tab characters. */
+  getTabLength(): number;
+
+  /**
+   * Set the on-screen length of tab characters. Setting this to a number will
+   * override the editor.tabLength setting.
+   */
+  setTabLength(tabLength: number): void;
+
+  /** Determine if the buffer uses hard or soft tabs. */
+  usesSoftTabs(): boolean | undefined;
+
+  /**
+   * Get the text representing a single level of indent.
+   *
+   * If soft tabs are enabled, the text is composed of N spaces, where N is the
+   * tab length. Otherwise the text is a tab character (`\t`).
+   */
+  getTabText(): string;
+
+  // Soft Wrap Behavior
+  /** Return whether lines in this editor are soft-wrapped. */
+  isSoftWrapped(): boolean;
+
+  /** Enable or disable soft wrapping for this editor. */
+  setSoftWrapped(softWrapped: boolean): boolean;
+
+  /** Toggle soft wrapping for this editor. */
+  toggleSoftWrapped(): boolean;
+
+  /** Gets the column at which column will soft wrap. */
+  getSoftWrapColumn(): number;
+
+  // Indentation
+  /**
+   * Get the indentation level of the given buffer row.
+   *
+   * Determines how deeply the given row is indented based on the soft tabs and
+   * tab length settings of this editor. Note that if soft tabs are enabled and
+   * the tab length is 2, a row with 4 leading spaces would have an indentation
+   * level of 2.
+   */
+  indentationForBufferRow(bufferRow: number): number;
+
+  /**
+   * Set the indentation level for the given buffer row.
+   *
+   * Inserts or removes hard tabs or spaces based on the soft tabs and tab
+   * length settings of this editor in order to bring it to the given
+   * indentation level. Note that if soft tabs are enabled and the tab length
+   * is 2, a row with 4 leading spaces would have an indentation level of 2.
+   */
+  setIndentationForBufferRow(
+    bufferRow: number,
+    newLevel: number,
+    options?: { preserveLeadingWhitespace?: boolean | undefined },
+  ): void;
+
+  /** Indent rows intersecting selections by one level. */
+  indentSelectedRows(options?: ReadonlyEditOptions): void;
+
+  /** Outdent rows intersecting selections by one level. */
+  outdentSelectedRows(options?: ReadonlyEditOptions): void;
+
+  /**
+   * Get the indentation level of the given line of text.
+   *
+   * Determines how deeply the given line is indented based on the soft tabs
+   * and tab length settings of this editor. Note that if soft tabs are enabled
+   * and the tab length is 2, a row with 4 leading spaces would have an
+   * indentation level of 2.
+   */
+  indentLevelForLine(line: string): number;
+
+  /**
+   * Indent rows intersecting selections based on the grammar's suggested
+   * indent level.
+   */
+  autoIndentSelectedRows(options?: ReadonlyEditOptions): void;
+
+  // Grammars
+  /** Get the current {@link Grammar} of this editor. */
+  getGrammar(): Grammar;
+
+  /**
+   * Set the current {@link Grammar} of this editor.
+   *
+   * Assigning a grammar will cause the editor to re-tokenize based on the new
+   * grammar.
+   *
+   * @deprecated Assign a language mode from {@link TextBuffer}.
+   */
+  setGrammar(grammar: Grammar): void;
+
+  // Managing Syntax Scopes
+  /**
+   *  Returns a ScopeDescriptor that includes this editor's language.
+   *  e.g. [".source.ruby"], or [".source.coffee"].
+   */
+  getRootScopeDescriptor(): ScopeDescriptor;
+
+  /**
+   * Get the syntactic scope descriptor for the given position in buffer
+   * coordinates.
+   */
+  scopeDescriptorForBufferPosition(bufferPosition: PointCompatible): ScopeDescriptor;
+
+  /**
+   * If using a Tree-sitter language mode, returns a scope descriptor where
+   * the "scopes" are Tree-sitter node names.
+   *
+   * If using a TextMate language mode, falls back to
+   * {@link scopeDescriptorForBufferPosition}.
+   */
+  syntaxTreeScopeDescriptorForBufferPosition(bufferPosition: PointCompatible): ScopeDescriptor;
+
+  /**
+   * Get the range in buffer coordinates of all tokens surrounding the cursor
+   * that match the given scope selector.
+   */
+  bufferRangeForScopeAtCursor(scopeSelector: string): Range;
+
+  /** Determine if the given row is entirely a comment. */
+  isBufferRowCommented(bufferRow: number): boolean;
+
+  // Clipboard Operations
+  /** For each selection, copy the selected text. */
+  copySelectedText(): void;
+
+  /** For each selection, cut the selected text. */
+  cutSelectedText(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, replace the selected text with the contents of the
+   * clipboard.
+   *
+   * If the clipboard contains the same number of selections as the current
+   * editor, each selection will be replaced with the content of the
+   * corresponding clipboard selection text.
+   */
+  pasteText(options?: TextInsertionOptions & ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, cut all characters of the
+   * containing screen line following the cursor; otherwise cut the selected
+   * text.
+   */
+  cutToEndOfLine(options?: ReadonlyEditOptions): void;
+
+  /**
+   * For each selection, if the selection is empty, cut all characters of the
+   * containing buffer line following the cursor; otherwise cut the selected
+   * text.
+   */
+  cutToEndOfBufferLine(options?: ReadonlyEditOptions): void;
+
+  // Folds
+  /**
+   * Fold the most recent cursor's row based on its indentation level.
+   *
+   * The fold will extend from the nearest preceding line with a lower
+   * indentation level up to the nearest following row with a lower indentation
+   * level.
+   */
+  foldCurrentRow(): void;
+
+  /** Unfold the most recent cursor's row by one level. */
+  unfoldCurrentRow(): void;
+
+  /**
+   * Fold the given row in buffer coordinates based on its indentation level.
+   *
+   * If the given row is foldable, the fold will begin there. Otherwise, it
+   * will begin at the first foldable row preceding the given row.
+   */
+  foldBufferRow(bufferRow: number): void;
+
+  /** Unfold all folds containing the given row in buffer coordinates. */
+  unfoldBufferRow(bufferRow: number): void;
+
+  /** For each selection, fold the rows it intersects. */
+  foldSelectedLines(): void;
+
+  /** Fold all foldable lines. */
+  foldAll(): void;
+
+  /** Unfold all existing folds. */
+  unfoldAll(): void;
+
+  /**
+   * Fold all foldable lines at the given indent level.
+   *
+   * @param level A zero-indexed number.
+   */
+  foldAllAtIndentLevel(level: number): void;
+
+  /**
+   * Determine whether the given row in buffer coordinates is foldable.
+   *
+   * A foldable row is a row that starts a row range that can be folded.
+   */
+  isFoldableAtBufferRow(bufferRow: number): boolean;
+
+  /**
+   * Determine whether the given row in screen coordinates is foldable.
+   *
+   * A foldable row is a row that starts a row range that can be folded.
+   */
+  isFoldableAtScreenRow(bufferRow: number): boolean;
+
+  /**
+   * Fold the given buffer row if it isn't currently folded, and unfold it
+   * otherwise.
+   */
+  toggleFoldAtBufferRow(bufferRow: number): void;
+
+  /** Determine whether the most recently added cursor's row is folded. */
+  isFoldedAtCursorRow(): boolean;
+
+  /** Determine whether the given row in buffer coordinates is folded. */
+  isFoldedAtBufferRow(bufferRow: number): boolean;
+
+  /** Determine whether the given row in screen coordinates is folded. */
+  isFoldedAtScreenRow(screenRow: number): boolean;
+
+  // Gutters
+  /** Add a custom Gutter. */
+  addGutter(options: GutterOptions): Gutter;
+
+  /** Get this editor's gutters. */
+  getGutters(): Gutter[];
+
+  /** Get the gutter with the given name. */
+  gutterWithName(name: string): Gutter | null;
+
+  // Scrolling the TextEditor
+  /**
+   * Scroll the editor to reveal the most recently added cursor if it is
+   * off-screen.
+   */
+  scrollToCursorPosition(options?: { center?: boolean | undefined }): void;
+
+  /** Scrolls the editor to the given buffer position. */
+  scrollToBufferPosition(
+    bufferPosition: PointCompatible,
+    options?: { center?: boolean | undefined }
+  ): void;
+
+  /** Scrolls the editor to the given screen position. */
+  scrollToScreenPosition(
+    screenPosition: PointCompatible,
+    options?: { center?: boolean | undefined }
+  ): void;
+
+  // TextEditor Rendering
+  /** Retrieves the rendered line height in pixels. */
+  getLineHeightInPixels(): number;
+
+  /** Retrieves the greyed out placeholder of a mini editor. */
+  getPlaceholderText(): string;
+
+  /**
+   * Set the greyed out placeholder of a mini editor.
+   *
+   * Placeholder text will be displayed when the editor has no content.
+   */
+  setPlaceholderText(placeholderText: string): void;
+
+  /** Undocumented: Buffer range for syntax scope at position */
+  bufferRangeForScopeAtPosition(scope: string, point: PointCompatible): Range;
+
+  /** Undocumented: Get syntax token at buffer position */
+  tokenForBufferPosition(pos: PointCompatible): { value: string; scopes: string[] };
+
+  /**
+   * Experimental: Get the characters that are *not* considered part of
+   * words, for the purpose of word-based cursor movements.
+   */
+  getNonWordCharacters(pos: PointCompatible): string;
+
+  /** Undocumented: Destroy the editor. */
+  destroy(): void;
+
+  /** Undocumented: Return whether the editor is destroyed. */
+  isDestroyed(): boolean;
+
+  /**
+   * Given a point in the buffer, retrieves the correct comment delimiters for
+   * that context.
+   *
+   * Pulsar allows language bundles to define comment delimiters in several
+   * places. For instance, a grammar author may place delimiter metadata in the
+   * grammar definition file, or as scope-specific settings in the ordinary
+   * config system — or a combination of the two.
+   *
+   * In some languages, comment delimiters vary based on context. (For
+   * instance, line comments cannot always be used in JavaScript JSX blocks, so
+   * block comments are much safer.) This method will look for any such
+   * overrides and return what it thinks are the best delimiters to use at a
+   * given point.
+   *
+   * Some languages don't specify all their delimiters in their configuration,
+   * but this method will return all the information that it can discern.
+   */
+  getCommentDelimitersForBufferPosition(pos: PointCompatible): CommentDelimiterSpec;
+}