@pulsar-edit/types 1.128.1

package/dependencies/text-buffer/src/text-buffer.d.ts

@@ -0,0 +1,759 @@
+import { ReadStream, WriteStream } from "fs";
+import {
+  Disposable,
+  FileSavedEvent,
+  HandleableErrorEvent,
+  HistoryTransactionOptions,
+  HistoryTraversalOptions,
+  LanguageMode,
+  TextEditOptions
+} from "../../../index";
+import {
+  FindMarkerOptions,
+  Marker,
+  MarkerLayer,
+  Point,
+  PointCompatible,
+  Range,
+  RangeCompatible,
+  TextChange,
+} from "./text-buffer";
+
+export * from "./display-marker";
+export * from "./display-marker-layer";
+export * from "./helpers";
+export * from "./marker";
+export * from "./marker-layer";
+export * from "./point";
+export * from "./range";
+
+/**
+ * A mutable text container with undo/redo support and the ability to annotate
+ * logical regions in the text.
+ */
+export class TextBuffer {
+  /** The unique identifier for this buffer. */
+  readonly id: string;
+
+  /** The number of retainers for the buffer. */
+  readonly refcount: number;
+
+  /** Whether or not the bufffer has been destroyed. */
+  readonly destroyed: boolean;
+
+  /** Create a new buffer backed by the given file path. */
+  static load(filePath: string | TextBufferFileBackend, params?: BufferLoadOptions): Promise<TextBuffer>;
+
+  /**
+   * Create a new buffer backed by the given file path.
+   *
+   * For better performance, use {@link TextBuffer.load} instead.
+   */
+  static loadSync(filePath: string, params?: BufferLoadOptions): TextBuffer;
+
+  /**
+   * Restore a TextBuffer based on an earlier state created using the
+   * {@link TextBuffer#serialize} method.
+   */
+  static deserialize(params: object): Promise<TextBuffer>;
+
+  /** Create a new buffer with the given starting text. */
+  constructor(text: string);
+  /** Create a new buffer with the given params. */
+  constructor(params?: {
+    /** The initial string text of the buffer. */
+    text?: string | undefined;
+    /**
+     * A function that returns a Boolean indicating whether the buffer should
+     * be destroyed if its file is deleted.
+     */
+    shouldDestroyOnFileDelete?(): boolean;
+  });
+
+  /** Returns a plain JavaScript object representation of the TextBuffer. */
+  serialize(options?: { markerLayers?: boolean | undefined; history?: boolean | undefined }): object;
+
+  /** Returns the unique identifier for this buffer. */
+  getId(): string;
+
+  // Event Subscription
+  /**
+   * Invokes the given callback synchronously before the content of the buffer
+   * changes.
+   */
+  onWillChange(callback: (event: BufferChangingEvent) => void): Disposable;
+
+  /**
+   * Invokes the given callback synchronously when the content of the buffer
+   * changes. Fires after every single change, even within a transaction.
+   *
+   * Do not use this in your package unless you absolutely must — and, if so,
+   * try very hard to minimize the work done within your callback. It is much
+   * better to subscribe to {@link onDidChangeText} (which operates at the
+   * transaction level) or, better yet, {@link onDidStopChanging} (which waits
+   * until the user has stopped typing for a small amount of time).
+   */
+  onDidChange(callback: (event: BufferChangedEvent) => void): Disposable;
+
+  /**
+   * Invokes the given callback synchronously when a transaction finishes with a
+   * list of all the changes in the transaction.
+   */
+  onDidChangeText(callback: (event: BufferStoppedChangingEvent) => void): Disposable;
+
+  /**
+   * Invokes the given callback asynchronously following one or more changes
+   * after {@link getStoppedChangingDelay} milliseconds elapse without an
+   * additional change.
+   */
+  onDidStopChanging(callback: (event: BufferStoppedChangingEvent) => void): Disposable;
+
+  /**
+   * Invokes the given callback when the in-memory contents of the buffer
+   * become in conflict with the contents of the file on disk.
+   */
+  onDidConflict(callback: () => void): Disposable;
+
+  /** Invokes the given callback if the value of {@link isModified} changes. */
+  onDidChangeModified(callback: (modified: boolean) => void): Disposable;
+
+  /**
+   * Invokes the given callback when all marker {@link onDidChange} observers
+   * have been notified following a change to the buffer.
+   */
+  onDidUpdateMarkers(callback: () => void): Disposable;
+
+  /**
+   * Invokes the given callback when a marker is created.
+   */
+  onDidCreateMarker(callback: (marker: Marker) => void): Disposable;
+
+  /** Invokes the given callback when the value of {@link getPath} changes. */
+  onDidChangePath(callback: (path: string) => void): Disposable;
+
+  /**
+   * Invokes the given callback when the value of {@link getEncoding} changes.
+   */
+  onDidChangeEncoding(callback: (encoding: string) => void): Disposable;
+
+  /**
+   * Invokes the given callback before the buffer is saved to disk. If the given
+   * callback returns a promise, then the buffer will not be saved until the
+   * promise resolves.
+   */
+  onWillSave(callback: () => Promise<void> | void): Disposable;
+
+  /** Invokes the given callback after the buffer is saved to disk. */
+  onDidSave(callback: (event: FileSavedEvent) => void): Disposable;
+
+  /**
+   * Invokes the given callback after the file backing the buffer is deleted.
+   */
+  onDidDelete(callback: () => void): Disposable;
+
+  /**
+   * Invokes the given callback before the buffer is reloaded from the contents
+   * of its file on disk.
+   */
+  onWillReload(callback: () => void): Disposable;
+
+  /**
+   * Invokes the given callback after the buffer is reloaded from the contents
+   * of its file on disk.
+   */
+  onDidReload(callback: () => void): Disposable;
+
+  /** Invokes the given callback when the buffer is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  /** Invokes the given callback when there is an error in watching the file. */
+  onWillThrowWatchError(callback: (errorObject: HandleableErrorEvent) => void): Disposable;
+
+  /**
+   * Get the number of milliseconds that will elapse without a change before
+   * {@link onDidStopChanging} observers are invoked following a change.
+   */
+  getStoppedChangingDelay(): number;
+
+  // File Details
+
+  /**
+   * Determine if the in-memory contents of the buffer differ from its contents
+   * on disk.
+   *
+   * If the buffer is unsaved, always returns true unless the buffer is empty.
+   */
+  isModified(): boolean;
+
+  /**
+   * Determine if the in-memory contents of the buffer conflict with the
+   * on-disk contents of its associated file.
+   */
+  isInConflict(): boolean;
+
+  /** Get the path of the associated file. */
+  getPath(): string | undefined;
+
+  /** Set the path for the buffer's associated file. */
+  setPath(filePath: string): void;
+
+  /**
+   * Experimental: Set a custom {@link TextBufferFileBackend} object as the
+   * buffer's backing store.
+   */
+  setFile(fileBackend: TextBufferFileBackend): void;
+
+  /** Sets the character set encoding for this buffer. */
+  setEncoding(encoding: string): void;
+
+  /** Returns the string encoding of this buffer. */
+  getEncoding(): string;
+
+  /** Get the path of the associated file. */
+  getUri(): string;
+
+  // Reading Text
+  /** Determine whether the buffer is empty. */
+  isEmpty(): boolean;
+
+  /**
+   * Get the entire text of the buffer. Avoid using this unless you know that
+   * the buffer's text is reasonably short.
+   */
+  getText(): string;
+
+  /** Get the text in a range. */
+  getTextInRange(range: RangeCompatible): string;
+
+  /** Get the text of all lines in the buffer, without their line endings. */
+  getLines(): string[];
+
+  /** Get the text of the last line of the buffer, without its line ending. */
+  getLastLine(): string;
+
+  /**
+   * Get the text of the line at the given 0-indexed row, without its line
+   * ending.
+   *
+   * @param row A number representing the row.
+   */
+  lineForRow(row: number): string | undefined;
+
+  /** Get the line ending for the given 0-indexed row. */
+  lineEndingForRow(row: number): string | undefined;
+
+  /**
+   * Get the length of the line for the given 0-indexed row _without_ its line
+   * ending.
+   */
+  lineLengthForRow(row: number): number;
+
+  /** Determine if the given row contains only whitespace. */
+  isRowBlank(row: number): boolean;
+
+  /**
+   * Given a row, find the first preceding row that's not blank.
+   *
+   * Returns a number or `null` if there's no preceding non-blank row.
+   */
+  previousNonBlankRow(startRow: number): number | null;
+
+  /**
+   * Given a row, find the next row that's not blank.
+   *
+   * Returns a number or `null` if there's no next non-blank row.
+   */
+  nextNonBlankRow(startRow: number): number | null;
+
+  /**
+   * Return `true` if the buffer contains any astral-plane Unicode characters
+   * that are encoded as surrogate pairs.
+   */
+  hasAstral(): boolean;
+
+  // Mutating Text
+
+  /** Replace the entire contents of the buffer with the given text. */
+  setText(text: string): Range;
+
+  /**
+   * Replace the current buffer contents by applying a diff based on the given
+   * text.
+   */
+  setTextViaDiff(text: string): void;
+
+  /** Set the text in the given range. */
+  setTextInRange(range: RangeCompatible, text: string, options?: TextEditOptions): Range;
+
+  /** Insert text at the given position. */
+  insert(position: PointCompatible, text: string, options?: TextEditOptions): Range;
+
+  /** Append text to the end of the buffer. */
+  append(text: string, options?: TextEditOptions): Range;
+
+  /** Delete the text in the given range. */
+  delete(range: RangeCompatible): Range;
+
+  /**
+   * Delete the line associated with a specified 0-indexed row.
+   *
+   * @param row A number representing the row to delete.
+   */
+  deleteRow(row: number): Range;
+
+  /**
+   * Delete the lines associated with the specified 0-indexed row range.
+   *
+   * If the row range is out of bounds, it will be clipped. If the `startRow`
+   * is greater than the `endRow`, they will be reordered.
+   */
+  deleteRows(startRow: number, endRow: number): Range;
+
+  // Markers
+
+  /** Create a layer to contain a set of related markers. */
+  addMarkerLayer(
+    options?: {
+      maintainHistory?: boolean | undefined;
+      persistent?: boolean | undefined;
+      role?: string | undefined;
+    },
+  ): MarkerLayer;
+
+  /**
+   * Get a MarkerLayer by ID.
+   *
+   * Returns a MarkerLayer or `undefined` if no layer exists with the given ID.
+   */
+  getMarkerLayer(id: string): MarkerLayer | undefined;
+
+  /** Get the default MarkerLayer. */
+  getDefaultMarkerLayer(): MarkerLayer;
+
+  /** Create a marker with the given range in the default marker layer. */
+  markRange(
+    range: RangeCompatible,
+    properties?: {
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): Marker;
+
+  /**
+   * Create a marker at the given position with no tail in the default marker
+   * layer.
+   */
+  markPosition(
+    position: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): Marker;
+
+  /** Get all existing markers on the default marker layer. */
+  getMarkers(): Marker[];
+
+  /** Get an existing marker by its id from the default marker layer. */
+  getMarker(id: number): Marker;
+
+  /**
+   * Find markers conforming to the given parameters in the default marker
+   * layer.
+   */
+  findMarkers(params: FindMarkerOptions): Marker[];
+
+  /** Get the number of markers in the default marker layer. */
+  getMarkerCount(): number;
+
+  // History
+
+  /**
+   * Undo the last operation. If a transaction is in progress, aborts it.
+   *
+   * @return A boolean of whether or not a change was made.
+   */
+  undo(options?: HistoryTraversalOptions): boolean;
+
+  /**
+   * Redo the last operation.
+   *
+   * @return A boolean of whether or not a change was made.
+   */
+  redo(options?: HistoryTraversalOptions): boolean;
+
+  /** Batch multiple operations as a single undo/redo step. */
+  transact<T>(
+    optionsOrInterval: number | ({ groupingInterval?: number | undefined } & HistoryTransactionOptions),
+    fn: () => T,
+  ): T;
+  /** Batch multiple operations as a single undo/redo step. */
+  transact<T>(fn: () => T): T;
+
+  /**
+   * Abort the currently running transaction.
+   *
+   * Only intended to be called within the `fn` option to {@link transact}.
+   */
+  abortTransaction(): void;
+
+  /** Clear the undo stack. */
+  clearUndoStack(): void;
+
+  /**
+   * Create a pointer to the current state of the buffer for use with
+   * {@link revertToCheckpoint} and {@link groupChangesSinceCheckpoint}.
+   *
+   * @return A checkpoint ID value.
+   */
+  createCheckpoint(options?: HistoryTransactionOptions): number;
+
+  /**
+   * Revert the buffer to the state it was in when the given checkpoint was
+   * created.
+   *
+   * @return A boolean indicating whether the operation succeeded.
+   */
+  revertToCheckpoint(checkpoint: number, options?: HistoryTraversalOptions): boolean;
+
+  /**
+   * Group all changes since the given checkpoint into a single transaction for
+   * purposes of undo/redo.
+   *
+   * @return A boolean indicating whether the operation succeeded.
+   */
+  groupChangesSinceCheckpoint(checkpoint: number, options?: HistoryTransactionOptions): boolean;
+
+  /**
+   * Group the last two text changes for purposes of undo/redo.
+   *
+   * This operation will only succeed if there are two changes on the undo
+   * stack. It will not group past the beginning of an open transaction.
+   *
+   * @return A boolean indicating whether the operation succeeded.
+   */
+  groupLastChanges(): boolean;
+
+  /**
+   * Returns a list of changes since the given checkpoint.
+   *
+   * If the given checkpoint is no longer present in the undo history, this
+   * method will return an empty Array.
+   */
+  getChangesSinceCheckpoint(
+    checkpoint: number,
+  ): Array<{
+    /** A Point representing where the change started. */
+    start: Point;
+
+    /** A Point representing the replaced extent. */
+    oldExtent: Point;
+
+    /** A Point representing the replacement extent. */
+    newExtent: Point;
+
+    /** A String representing the replacement text. */
+    newText: string;
+  }>;
+
+  // Search and Replace
+
+  /**
+   * Scan regular expression matches in the entire buffer, calling the given
+   * iterator function on each match.
+   */
+  scan(regex: RegExp, iterator: (params: BufferScanResult) => void): void;
+  /**
+   * Scan regular expression matches in the entire buffer, calling the given
+   * iterator function on each match.
+   */
+  scan(regex: RegExp, options: ScanContextOptions, iterator: (params: ContextualBufferScanResult) => void): void;
+
+  /**
+   * Scan regular expression matches in the entire buffer in reverse order,
+   * calling the given iterator function on each match.
+   */
+  backwardsScan(regex: RegExp, iterator: (params: BufferScanResult) => void): void;
+  /**
+   * Scan regular expression matches in the entire buffer in reverse order,
+   * calling the given iterator function on each match.
+   */
+  backwardsScan(
+    regex: RegExp,
+    options: ScanContextOptions,
+    iterator: (params: ContextualBufferScanResult) => void,
+  ): void;
+
+  /**
+   * Scan regular expression matches in a given range , calling the given
+   * iterator function on each match.
+   */
+  scanInRange(regex: RegExp, range: RangeCompatible, iterator: (params: BufferScanResult) => void): void;
+  /**
+   * Scan regular expression matches in a given range , calling the given
+   * iterator function on each match.
+   */
+  scanInRange(
+    regex: RegExp,
+    range: RangeCompatible,
+    options: ScanContextOptions,
+    iterator: (params: ContextualBufferScanResult) => void,
+  ): void;
+
+  /**
+   * Scan regular expression matches in a given range in reverse order, calling
+   * the given iterator function on each match.
+   */
+  backwardsScanInRange(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.
+   */
+  backwardsScanInRange(
+    regex: RegExp,
+    range: RangeCompatible,
+    options: ScanContextOptions,
+    iterator: (params: ContextualBufferScanResult) => void,
+  ): void;
+
+  /** Replace all regular expression matches in the entire buffer. */
+  replace(regex: RegExp, replacementText: string): number;
+
+  // Buffer Range Details
+  /** Get the range spanning from [0, 0] to ::getEndPosition. */
+  getRange(): Range;
+
+  /** Get the number of lines in the buffer. */
+  getLineCount(): number;
+
+  /** Get the last 0-indexed row in the buffer. */
+  getLastRow(): number;
+
+  /** Get the first position in the buffer, which is always [0, 0]. */
+  getFirstPosition(): Point;
+
+  /**
+   * Get the maximal position in the buffer, where new text would be appended.
+   */
+  getEndPosition(): Point;
+
+  /** Get the length of the buffer's text. */
+  getLength(): number;
+
+  /** Get the length of the buffer in characters. */
+  getMaxCharacterIndex(): number;
+
+  /**
+   * Get the range for the given row.
+   *
+   * @param row A number representing a 0-indexed row.
+   * @param includeNewline A boolean indicating whether or not to include the
+   *   newline, which results in a range that extends to the start of the next
+   *   line. (default: `false`)
+   */
+  rangeForRow(row: number, includeNewline?: boolean): Range;
+
+  /**
+   * Convert a position in the buffer in row/column coordinates to an absolute
+   * character offset, inclusive of line ending characters.
+   */
+  characterIndexForPosition(position: PointCompatible): number;
+
+  /**
+   * Convert an absolute character offset, inclusive of newlines, to a position
+   * in the buffer in row/column coordinates.
+   */
+  positionForCharacterIndex(offset: number): Point;
+
+  /** Clip the given range so it starts and ends at valid positions. */
+  clipRange(range: RangeCompatible): Range;
+
+  /** Clip the given point so it is at a valid position in the buffer. */
+  clipPosition(position: PointCompatible): Point;
+
+  // Buffer Operations
+  /** Save the buffer. */
+  save(): Promise<void>;
+
+  /** Save the buffer at a specific path. */
+  saveAs(filePath: string): Promise<void>;
+
+  /** Reload the buffer's contents from disk. */
+  reload(): void;
+
+  /** Destroy the buffer, even if there are retainers for it. */
+  destroy(): void;
+
+  /** Returns whether or not this buffer is alive. */
+  isAlive(): boolean;
+
+  /** Returns whether or not this buffer has been destroyed. */
+  isDestroyed(): boolean;
+
+  /** Returns whether or not this buffer has a retainer. */
+  isRetained(): boolean;
+
+  /**
+   * Places a retainer on the buffer, preventing its destruction until the
+   * final retainer has called {@link release}.
+   */
+  retain(): TextBuffer;
+
+  /**
+   * Releases a retainer on the buffer, destroying the buffer if there are no
+   * additional retainers.
+   */
+  release(): TextBuffer;
+
+  /** Identifies if the buffer belongs to multiple editors. */
+  hasMultipleEditors(): boolean;
+
+  // Language modes
+
+  /** Returns the current {@link LanguageMode} for the buffer. */
+  getLanguageMode(): LanguageMode;
+
+  /** Sets the buffer's {@link LanguageMode}. */
+  setLanguageMode(languageMode: LanguageMode): void;
+
+  /**
+   * Invokes the given callback when the buffer's {@link LanguageMode} changes.
+   */
+  onDidChangeLanguageMode(
+    callback: (languageMode: LanguageMode) => unknown
+  ): Disposable;
+}
+
+export interface TextBufferFileBackend {
+  /** A {Function} that returns the {String} path to the file. */
+  getPath(): string;
+
+  /**
+   * Returns a `Readable` stream that can be used to load the file's content.
+   */
+  createReadStream(): ReadStream;
+
+  /**
+   * Returns a `Writable` stream that can be used to save content to the file.
+   */
+  createWriteStream(): WriteStream;
+
+  /** Returns `true` if the file exists, `false` otherwise. */
+  existsSync(): boolean;
+
+  /**
+   * Add a listener that will be called when the file changes.
+   */
+  onDidChange?(callback: () => void): Disposable;
+
+  /**
+   * Add a listener that will be called when the file is deleted.
+   */
+  onDidDelete?(callback: () => void): Disposable;
+
+  /**
+   * Add a listener that will be called when the file is renamed.
+   */
+  onDidRename?(callback: () => void): Disposable;
+}
+
+/** The event associated with {@link TextBuffer#onWillChange}. */
+export interface BufferChangingEvent {
+  /** Range of the old text. */
+  oldRange: Range;
+}
+
+/** The event associated with {@link TextBuffer#onDidChange}. */
+export interface BufferChangedEvent {
+  /**
+   * An array of objects summarizing the aggregated changes that occurred
+   * during the transaction.
+   */
+  changes: Array<{
+    /**
+     * The Range of the deleted text in the contents of the buffer as it
+     * existed before the batch of changes reported by this event.
+     */
+    oldRange: Range;
+
+    /** The Range of the inserted text in the current contents of the buffer. */
+    newRange: Range;
+  }>;
+
+  /** Range of the old text. */
+  oldRange: Range;
+
+  /** Range of the new text. */
+  newRange: Range;
+
+  /** String containing the text that was replaced. */
+  oldText: string;
+
+  /** String containing the text that was inserted. */
+  newText: string;
+}
+
+/** The event associated with {@link TextBuffer#onDidStopChanging}. */
+export interface BufferStoppedChangingEvent {
+  changes: TextChange[];
+}
+
+/**
+ * The options that may be passed to {@link TextBuffer.load} and
+ * {@link TextBuffer.loadSync}.
+ */
+export interface BufferLoadOptions {
+  /** The file's encoding. */
+  encoding?: string | undefined;
+
+  /**
+   * A function that returns a boolean indicating whether the buffer should be
+   * destroyed if its file is deleted.
+   */
+  shouldDestroyOnFileDelete?(): boolean;
+}
+
+/**
+ * The result object given during {@link TextBuffer#scan} and
+ * {@link TextBuffer#scanInRange}, as well as the "backwards" versions of those
+ * methods.
+ */
+export interface BufferScanResult {
+  buffer: TextBuffer;
+  lineText: string;
+  match: RegExpExecArray;
+  matchText: string;
+  range: Range;
+  replace(replacementText: string): void;
+  stop(): void;
+  stopped: boolean;
+}
+
+/**
+ * Additional properties that are included in {@link BufferScanResult} if the
+ * contextual options in {@link ScanContextOptions} were specified.
+ */
+export interface ContextualBufferScanResult extends BufferScanResult {
+  leadingContextLines: string[];
+  trailingContextLines: string[];
+}
+
+/**
+ * Additional options that may be passed to {@link TextBuffer#scan} and
+ * {@link TextBuffer#scanInRange}, as well as the "backwards" versions of those
+ * methods.
+ */
+export interface ScanContextOptions {
+  /**
+   * The number of lines before the matched line to include in the results
+   * object.
+   */
+  leadingContextLineCount?: number | undefined;
+
+  /**
+   * The number of lines after the matched line to include in the results
+   * object.
+   */
+  trailingContextLineCount?: number | undefined;
+}