@pulsar-edit/types 1.128.1

package/dependencies/text-buffer/src/display-marker-layer.d.ts

@@ -0,0 +1,182 @@
+import { Disposable } from "../../../index";
+import {
+  DisplayMarker,
+  Marker,
+  PointCompatible,
+  RangeCompatible
+} from "./text-buffer";
+
+/**
+ * Experimental: A container for a related set of markers at the DisplayLayer
+ * level. Wraps an underlying MarkerLayer on the TextBuffer.
+ *
+ * This API is experimental and subject to change on any release.
+ */
+export interface DisplayMarkerLayer {
+  /** The identifier for the underlying MarkerLayer. */
+  readonly id: string;
+
+  // Lifecycle
+  /** Destroy this layer. */
+  destroy(): void;
+
+  /** Destroy all markers in this layer. */
+  clear(): void;
+
+  /** Determine whether this layer has been destroyed. */
+  isDestroyed(): boolean;
+
+  // Event Subscription
+  /** Subscribe to be notified synchronously when this layer is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  /**
+   * Subscribe to be notified asynchronously whenever markers are created,
+   * updated, or destroyed on this layer. Prefer this method for optimal
+   * performance when interacting with layers that could contain large numbers
+   * of markers.
+   */
+  onDidUpdate(callback: () => void): Disposable;
+
+  /**
+   * Subscribe to be notified synchronously whenever markers are created on
+   * this layer. Avoid this method for optimal performance when interacting
+   * with layers that could contain large numbers of markers.
+   */
+  onDidCreateMarker(callback: (marker: DisplayMarker | Marker) => void): Disposable;
+
+  // Marker creation
+  /** Create a marker with the given screen range. */
+  markScreenRange(
+    range: RangeCompatible,
+    options?: {
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+      clipDirection?: "backward" | "forward" | "closest" | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Create a marker on this layer with its head at the given screen position
+   * and no tail.
+   */
+  markScreenPosition(
+    screenPosition: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+      clipDirection?: "backward" | "forward" | "closest" | undefined;
+    },
+  ): DisplayMarker;
+
+  /** Create a marker with the given buffer range. */
+  markBufferRange(
+    range: RangeCompatible,
+    options?: {
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): DisplayMarker;
+
+  /**
+   * Create a marker on this layer with its head at the given buffer position
+   * and no tail.
+   */
+  markBufferPosition(
+    bufferPosition: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): DisplayMarker;
+
+  // Querying
+  /** Get an existing marker by its id. */
+  getMarker(id: number): DisplayMarker;
+
+  /** Get all markers in the layer. */
+  getMarkers(): DisplayMarker[];
+
+  /** Get the number of markers in the marker layer. */
+  getMarkerCount(): number;
+
+  /**
+   * Find markers in the layer conforming to the given parameters.
+   *
+   * 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[];
+}
+
+export interface FindDisplayMarkerOptions {
+  /** Only include markers starting at this Point in buffer coordinates. */
+  startBufferPosition?: PointCompatible | undefined;
+
+  /** Only include markers ending at this Point in buffer coordinates. */
+  endBufferPosition?: PointCompatible | undefined;
+
+  /** Only include markers starting at this Point in screen coordinates. */
+  startScreenPosition?: PointCompatible | undefined;
+
+  /** Only include markers ending at this Point in screen coordinates. */
+  endScreenPosition?: PointCompatible | undefined;
+
+  /** Only include markers starting inside this Range in buffer coordinates. */
+  startsInBufferRange?: RangeCompatible | undefined;
+
+  /** Only include markers ending inside this Range in buffer coordinates. */
+  endsInBufferRange?: RangeCompatible | undefined;
+
+  /** Only include markers starting inside this Range in screen coordinates. */
+  startsInScreenRange?: RangeCompatible | undefined;
+
+  /** Only include markers ending inside this Range in screen coordinates. */
+  endsInScreenRange?: RangeCompatible | undefined;
+
+  /** Only include markers starting at this row in buffer coordinates. */
+  startBufferRow?: number | undefined;
+
+  /** Only include markers ending at this row in buffer coordinates. */
+  endBufferRow?: number | undefined;
+
+  /** Only include markers starting at this row in screen coordinates. */
+  startScreenRow?: number | undefined;
+
+  /** Only include markers ending at this row in screen coordinates. */
+  endScreenRow?: number | undefined;
+
+  /**
+   * Only include markers intersecting this Array of [startRow, endRow] in
+   * buffer coordinates.
+   */
+  intersectsBufferRowRange?: [number, number] | undefined;
+
+  /**
+   * Only include markers intersecting this Array of [startRow, endRow] in
+   * screen coordinates.
+   */
+  intersectsScreenRowRange?: [number, number] | undefined;
+
+  /** Only include markers containing this Range in buffer coordinates. */
+  containsBufferRange?: RangeCompatible | undefined;
+
+  /** Only include markers containing this Point in buffer coordinates. */
+  containsBufferPosition?: PointCompatible | undefined;
+
+  /** Only include markers contained in this Range in buffer coordinates. */
+  containedInBufferRange?: RangeCompatible | undefined;
+
+  /** Only include markers contained in this Range in screen coordinates. */
+  containedInScreenRange?: RangeCompatible | undefined;
+
+  /** Only include markers intersecting this Range in buffer coordinates. */
+  intersectsBufferRange?: RangeCompatible | undefined;
+
+  /** Only include markers intersecting this Range in screen coordinates. */
+  intersectsScreenRange?: RangeCompatible | undefined;
+}

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

@@ -0,0 +1,232 @@
+import { Disposable } from "../../../index";
+import {
+  CopyMarkerOptions,
+  FindDisplayMarkerOptions,
+  Point,
+  PointCompatible,
+  Range,
+  RangeCompatible,
+} from "./text-buffer";
+
+/**
+ * Represents a buffer annotation that remains logically stationary even as the
+ * buffer changes. This is used to represent cursors, folds, snippet targets,
+ * misspelled words, and anything else that needs to track a logical location
+ * in the buffer over time.
+ */
+export interface DisplayMarker {
+  id: string;
+
+  // Construction and Destruction
+  /**
+   * Destroys the marker, causing it to emit the 'destroyed' event. Once
+   * destroyed, a marker cannot be restored by undo/redo operations.
+   */
+  destroy(): void;
+
+  /**
+   * Creates and returns a new DisplayMarker with the same properties as this
+   * marker.
+   */
+  copy(options?: CopyMarkerOptions): DisplayMarker;
+
+  // Event Subscription
+  /** Invoke the given callback when the state of the marker changes. */
+  onDidChange(callback: (event: DisplayMarkerChangedEvent) => void): Disposable;
+
+  /** Invoke the given callback when the marker is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  // TextEditorMarker Details
+  /**
+   * Returns a boolean indicating whether the marker is valid. Markers can be
+   * invalidated when a region surrounding them in the buffer is changed.
+   */
+  isValid(): boolean;
+
+  /**
+   * Returns a boolean indicating whether the marker has been destroyed. A
+   * marker can be invalid without being destroyed, in which case undoing the
+   * invalidating operation would restore the marker.
+   */
+  isDestroyed(): boolean;
+
+  /** Returns a boolean indicating whether the head precedes the tail. */
+  isReversed(): boolean;
+
+  /**
+   * Returns a boolean indicating whether changes that occur exactly at the
+   * marker's head or tail cause it to move.
+   */
+  isExclusive(): boolean;
+
+  /**
+   * Get the invalidation strategy for this marker.
+   *
+   * Valid values include: never, surround, overlap, inside, and touch.
+   */
+  getInvalidationStrategy(): string;
+
+  /** Returns an Object containing any custom properties associated with the marker. */
+  getProperties(): object;
+
+  /** Merges an Object containing new properties into the marker's existing properties. */
+  setProperties(properties: object): void;
+
+  /** Returns whether this marker matches the given parameters. */
+  matchesProperties(attributes: FindDisplayMarkerOptions): boolean;
+
+  // Comparing to other markers
+  /** Compares this marker to another based on their ranges. */
+  compare(other: DisplayMarker): number;
+
+  /**
+   * Returns a boolean indicating whether this marker is equivalent to another
+   * marker, meaning they have the same range and options.
+   */
+  isEqual(other: DisplayMarker): boolean;
+
+  // Managing the marker's range
+  /** Gets the buffer range of this marker. */
+  getBufferRange(): Range;
+
+  /** Gets the screen range of this marker. */
+  getScreenRange(): Range;
+
+  /** Modifies the buffer range of this marker. */
+  setBufferRange(bufferRange: RangeCompatible, properties?: { reversed: boolean }): void;
+
+  /** Modifies the screen range of this marker. */
+  setScreenRange(
+    screenRange: RangeCompatible,
+    options?: { reversed?: boolean | undefined; clipDirection?: "backward" | "forward" | "closest" | undefined },
+  ): void;
+
+  /**
+   * Retrieves the screen position of the marker's start. This will always be
+   * less than or equal to the result of DisplayMarker::getEndScreenPosition.
+   */
+  getStartScreenPosition(options?: { clipDirection: "backward" | "forward" | "closest" }): Point;
+
+  /**
+   * Retrieves the screen position of the marker's end. This will always be
+   * greater than or equal to the result of {@link getStartScreenPosition}.
+   */
+  getEndScreenPosition(options?: { clipDirection: "backward" | "forward" | "closest" }): Point;
+
+  /** Retrieves the buffer position of the marker's head. */
+  getHeadBufferPosition(): Point;
+
+  /** Sets the buffer position of the marker's head. */
+  setHeadBufferPosition(bufferPosition: PointCompatible): void;
+
+  /** Retrieves the screen position of the marker's head. */
+  getHeadScreenPosition(options?: { clipDirection: "backward" | "forward" | "closest" }): Point;
+
+  /** Sets the screen position of the marker's head. */
+  setHeadScreenPosition(
+    screenPosition: PointCompatible,
+    options?: { clipDirection: "backward" | "forward" | "closest" },
+  ): void;
+
+  /** Retrieves the buffer position of the marker's tail. */
+  getTailBufferPosition(): Point;
+
+  /** Sets the buffer position of the marker's tail. */
+  setTailBufferPosition(bufferPosition: PointCompatible): void;
+
+  /** Retrieves the screen position of the marker's tail. */
+  getTailScreenPosition(options?: { clipDirection: "backward" | "forward" | "closest" }): Point;
+
+  /** Sets the screen position of the marker's tail. */
+  setTailScreenPosition(
+    screenPosition: PointCompatible,
+    options?: { clipDirection: "backward" | "forward" | "closest" },
+  ): void;
+
+  /**
+   * Retrieves the buffer position of the marker's start. This will always be
+   * less than or equal to the result of DisplayMarker::getEndBufferPosition.
+   */
+  getStartBufferPosition(): Point;
+
+  /**
+   * Retrieves the buffer position of the marker's end. This will always be
+   * greater than or equal to the result of
+   * DisplayMarker::getStartBufferPosition.
+   */
+  getEndBufferPosition(): Point;
+
+  /** Returns a boolean indicating whether the marker has a tail. */
+  hasTail(): boolean;
+
+  /**
+   * Plants the marker's tail at the current head position. After calling the
+   * marker's tail position will be its head position at the time of the call,
+   * regardless of where the marker's head is moved.
+   */
+  plantTail(): void;
+
+  /**
+   * Removes the marker's tail. After calling the marker's head position will
+   * be reported as its current tail position until the tail is planted again.
+   */
+  clearTail(): void;
+}
+
+export interface DisplayMarkerChangedEvent {
+  /** Point representing the former head buffer position. */
+  oldHeadBufferPosition: Point;
+
+  /** Point representing the new head buffer position. */
+  newHeadBufferPosition: Point;
+
+  // Point representing the former tail buffer position. */
+  oldTailBufferPosition: Point;
+
+  /** Point representing the new tail buffer position. */
+  newTailBufferPosition: Point;
+
+  /** Point representing the former head screen position. */
+  oldHeadScreenPosition: Point;
+
+  /** Point representing the new head screen position. */
+  newHeadScreenPosition: Point;
+
+  /** Point representing the former tail screen position. */
+  oldTailScreenPosition: Point;
+
+  /** Point representing the new tail screen position. */
+  newTailScreenPosition: Point;
+
+  /** Boolean indicating whether the marker was valid before the change. */
+  wasValid: boolean;
+
+  /** Boolean indicating whether the marker is now valid. */
+  isValid: boolean;
+
+  /** Boolean indicating whether the marker had a tail before the change. */
+  hadTail: boolean;
+
+  /** Boolean indicating whether the marker now has a tail */
+  hasTail: boolean;
+
+  /**
+   *  Object containing the marker's custom properties before the change.
+   *  @deprecated
+   */
+  oldProperties: object;
+
+  /**
+   * Object containing the marker's custom properties after the change.
+   * @deprecated
+   */
+  newProperties: object;
+
+  /**
+   * Boolean indicating whether this change was caused by a textual change to
+   * the buffer or whether the marker was manipulated directly via its public
+   * API.
+   */
+  textChanged: boolean;
+}

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

@@ -0,0 +1,11 @@
+import { Point, Range } from "./text-buffer";
+
+export interface TextChange {
+  newExtent: Point;
+  oldExtent: Point;
+  newRange: Range;
+  oldRange: Range;
+  newText: string;
+  oldText: string;
+  start: Point;
+}

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

@@ -0,0 +1,117 @@
+import { Disposable } from "../../../index";
+import { Marker, PointCompatible, RangeCompatible } from "./text-buffer";
+
+/** Experimental: A container for a related set of markers. */
+export interface MarkerLayer {
+  /** The identifier for this MarkerLayer. */
+  readonly id: string;
+
+  // Lifecycle
+  /** Create a copy of this layer with markers in the same state and locations. */
+  copy(): MarkerLayer;
+
+  /** Destroy this layer. */
+  destroy(): boolean;
+
+  /** Remove all markers from this layer. */
+  clear(): void;
+
+  /** Determine whether this layer has been destroyed. */
+  isDestroyed(): boolean;
+
+  // Querying
+  /** Get an existing marker by its id. */
+  getMarker(id: number): Marker | undefined;
+
+  /** Get all existing markers on the marker layer. */
+  getMarkers(): Marker[];
+
+  /** Get the number of markers in the marker layer. */
+  getMarkerCount(): number;
+
+  /** Find markers in the layer conforming to the given parameters. */
+  findMarkers(params: FindMarkerOptions): Marker[];
+
+  /** Get the role of the marker layer e.g. "atom.selection". */
+  getRole(): string | undefined;
+
+  // Marker Creation
+  /** Create a marker with the given range. */
+  markRange(
+    range: RangeCompatible,
+    options?: {
+      reversed?: boolean | undefined;
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): Marker;
+
+  /** Create a marker at with its head at the given position with no tail. */
+  markPosition(
+    position: PointCompatible,
+    options?: {
+      invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+      exclusive?: boolean | undefined;
+    },
+  ): Marker;
+
+  // Event Subscription
+  /**
+   *  Subscribe to be notified asynchronously whenever markers are created,
+   *  updated, or destroyed on this layer.
+   */
+  onDidUpdate(callback: () => void): Disposable;
+
+  /**
+   *  Subscribe to be notified synchronously whenever markers are created on
+   *  this layer.
+   */
+  onDidCreateMarker(callback: (marker: Marker) => void): Disposable;
+
+  /** Subscribe to be notified synchronously when this layer is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+}
+
+export interface FindMarkerOptions {
+  /** Only include markers that start at the given Point. */
+  startPosition?: PointCompatible | undefined;
+
+  /** Only include markers that end at the given Point. */
+  endPosition?: PointCompatible | undefined;
+
+  /** Only include markers that start inside the given Range. */
+  startsInRange?: RangeCompatible | undefined;
+
+  /** Only include markers that end inside the given Range. */
+  endsInRange?: RangeCompatible | undefined;
+
+  /** Only include markers that contain the given Point, inclusive. */
+  containsPoint?: PointCompatible | undefined;
+  containsPosition?: PointCompatible | undefined;
+
+  /** Only include markers that contain the given {@link Range}, inclusive. */
+  containsRange?: RangeCompatible | undefined;
+
+  /** Only include markers that intersect the given {@link Range}. */
+  intersectsRange?: RangeCompatible | undefined;
+
+  /** Only include markers that start at the given row number. */
+  startRow?: number | undefined;
+
+  /** Only include markers that end at the given row number. */
+  endRow?: number | undefined;
+
+  /** Only include markers that intersect the given row number. */
+  intersectsRow?: number | undefined;
+
+  /**
+   * Only include markers that intersect the given range of rows (given a
+   * two-item tuple describing the starting and ending rows).
+   */
+  intersectsRowRange?: [number, number] | undefined;
+
+  /**
+   * Only include markers that are completely contained by the specified range.
+   */
+  containedInRange?: RangeCompatible | undefined;
+}