@pulsar-edit/types 1.128.1

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

@@ -0,0 +1,207 @@
+import { Disposable } from "../../../index";
+import { Point, PointCompatible, Range, RangeCompatible } from "./text-buffer";
+
+/**
+ * Represents a buffer annotation that remains logically stationary even as the
+ * buffer changes.
+ */
+export interface Marker {
+  /** The identifier for this Marker. */
+  readonly id: number;
+
+  // Lifecycle
+  /**
+   * Creates and returns a new Marker with the same properties as this
+   * marker.
+   */
+  copy(options?: CopyMarkerOptions): Marker;
+
+  /** Destroys the marker, causing it to emit the "destroyed" event. */
+  destroy(): void;
+
+  // Event Subscription
+  /** Invoke the given callback when the marker is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  /** Invoke the given callback when the state of the marker changes. */
+  onDidChange(callback: (event: MarkerChangedEvent) => void): Disposable;
+
+  // Marker Details
+  /** Returns the current range of the marker. The range is immutable. */
+  getRange(): Range;
+
+  /** Returns a point representing the marker's current head position. */
+  getHeadPosition(): Point;
+
+  /** Returns a point representing the marker's current tail position. */
+  getTailPosition(): Point;
+
+  /**
+   * Returns a point representing the start position of the marker, which could
+   * be the head or tail position, depending on its orientation.
+   */
+  getStartPosition(): Point;
+
+  /**
+   * Returns a point representing the end position of the marker, which could
+   * be the head or tail position, depending on its orientation.
+   */
+  getEndPosition(): Point;
+
+  /** Returns a boolean indicating whether the head precedes the tail. */
+  isReversed(): boolean;
+
+  /** Returns a boolean indicating whether the marker has a tail. */
+  hasTail(): boolean;
+
+  /** Is the marker valid? */
+  isValid(): boolean;
+
+  /** Is the marker destroyed? */
+  isDestroyed(): 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. */
+  getInvalidationStrategy(): string;
+
+  // Mutating Markers
+  /**
+   * Sets the range of the marker.
+   *
+   * Returns a boolean indicating whether or not the marker was updated.
+   */
+  setRange(
+    range: RangeCompatible,
+    params?: { reversed?: boolean | undefined; exclusive?: boolean | undefined },
+  ): boolean;
+
+  /**
+   * Sets the head position of the marker.
+   *
+   * Returns a boolean indicating whether or not the marker was updated.
+   */
+  setHeadPosition(position: PointCompatible): boolean;
+
+  /**
+   * Sets the tail position of the marker.
+   *
+   * Returns a boolean indicating whether or not the marker was updated.
+   */
+  setTailPosition(position: PointCompatible): boolean;
+
+  /**
+   * Removes the marker's tail.
+   *
+   * Returns a boolean indicating whether or not the marker was updated.
+   */
+  clearTail(): boolean;
+
+  /**
+   * Plants the marker's tail at the current head position.
+   *
+   * Returns a boolean indicating whether or not the marker was updated.
+   */
+  plantTail(): boolean;
+
+  // Comparison
+  /**
+   * Returns a boolean indicating whether this marker is equivalent to another
+   * marker, meaning they have the same range and options.
+   */
+  isEqual(other: Marker): boolean;
+
+  /**
+   *  Compares this marker to another based on their ranges.
+   *
+   *  Returns `-1` if this marker precedes the argument.
+   *
+   *  Returns `0` if this marker is equivalent to the argument.
+   *
+   *  Returns `1` if this marker follows the argument.
+   */
+  compare(other: Marker): number;
+
+  /**
+   * Merge an object containing new properties into the marker's existing
+   * properties. Use this to set custom data on your markers.
+   */
+  setProperties(properties: Record<string, unknown>);
+
+  /**
+   * Retrieve an object of key/value pairs that you set earlier via
+   * {@link setProperties}.
+   */
+  getProperties(): Record<string, unknown>;
+}
+
+export interface CopyMarkerOptions {
+  /** Whether or not the marker should be tailed. */
+  tailed?: boolean | undefined;
+
+  /** Creates the marker in a reversed orientation. */
+  reversed?: boolean | undefined;
+
+  /**
+   * Determines the rules by which changes to the buffer invalidate the marker.
+   */
+  invalidate?: "never" | "surround" | "overlap" | "inside" | "touch" | undefined;
+
+  /**
+   * Indicates whether insertions at the start or end of the marked range
+   * should be interpreted as happening outside the marker.
+   */
+  exclusive?: boolean | undefined;
+
+  /** Custom properties to be associated with the marker. */
+  properties?: object | undefined;
+}
+
+export interface MarkerChangedEvent {
+  /** Point representing the former head position. */
+  oldHeadPosition: Point;
+
+  /** Point representing the new head position. */
+  newHeadPosition: Point;
+
+  /** Point representing the former tail position. */
+  oldTailPosition: Point;
+
+  /** Point representing the new tail position. */
+  newTailPosition: 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/point.d.ts

@@ -0,0 +1,102 @@
+/** Represents a point in a buffer in row/column coordinates. */
+export class Point {
+  // Properties
+  /** A zero-indexed number representing the row of the Point. */
+  row: number;
+
+  /** A zero-indexed number representing the column of the Point. */
+  column: number;
+
+  // Construction
+  /**
+  *  Create a Point from an array containing two numbers representing the
+  *  row and column.
+  */
+  static fromObject(object: PointCompatible, copy?: boolean): Point;
+
+  /** Construct a Point object */
+  constructor(row?: number, column?: number);
+
+  /** Returns a new Point with the same row and column. */
+  copy(): Point;
+
+  /** Returns a new Point with the row and column negated. */
+  negate(): Point;
+
+  // Comparison
+  /** Returns the given Point that is earlier in the buffer. */
+  static min(point1: PointCompatible, point2: PointCompatible): Point;
+
+  /**
+   * Compare another Point to this Point instance.
+   *
+   * Returns `-1` if this point precedes the argument.
+   *
+   * Returns `0` if this point is equivalent to the argument.
+   *
+   * Returns `1` if this point follows the argument.
+   */
+  compare(other: PointCompatible): number;
+
+  /**
+   * Returns a boolean indicating whether this point has the same row and column
+   * as the given Point.
+   */
+  isEqual(other: PointCompatible): boolean;
+
+  /**
+   * Returns a Boolean indicating whether this point precedes the given Point.
+   */
+  isLessThan(other: PointCompatible): boolean;
+
+  /**
+   * Returns whether this point precedes or is equal to the given Point.
+   */
+  isLessThanOrEqual(other: PointCompatible): boolean;
+
+  /** Returns a Boolean indicating whether this point follows the given Point. */
+  isGreaterThan(other: PointCompatible): boolean;
+
+  /**
+  *  Returns a Boolean indicating whether this point follows or is equal to
+  *  the given Point.
+  */
+  isGreaterThanOrEqual(other: PointCompatible): boolean;
+
+  // Operations
+  /** Makes this point immutable and returns itself. */
+  freeze(): Readonly<Point>;
+
+  /**
+   * Build and return a new point by adding the rows and columns of the given
+   * point.
+   */
+  translate(other: PointCompatible): Point;
+
+  /**
+   * Build and return a new Point by traversing the rows and columns specified
+   * by the given point.
+   */
+  traverse(other: PointCompatible): Point;
+
+  /** Returns an array of this point's row and column. */
+  toArray(): [number, number];
+
+  /** Returns an array of this point's row and column. */
+  serialize(): [number, number];
+
+  /** Returns a string representation of the point. */
+  toString(): string;
+}
+
+/** The interface that should be implemented for all "point-compatible" objects. */
+export interface PointLike {
+  /** A zero-indexed number representing the row of the Point. */
+  row: number;
+
+  /** A zero-indexed number representing the column of the Point. */
+  column: number;
+}
+
+/** The types usable when constructing a point via the Point::fromObject method. */
+export type PointCompatible = PointLike | [number, number];

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

@@ -0,0 +1,141 @@
+import { Point, PointCompatible, PointLike } from "./text-buffer";
+
+/** Represents a region in a buffer in row/column coordinates. */
+export class Range {
+  // Properties
+  /** A Point representing the start of the Range. */
+  start: Point;
+
+  /** A Point representing the end of the Range. */
+  end: Point;
+
+  // Construction
+  /** Convert any range-compatible object to a Range. */
+  static fromObject(object: RangeCompatible, copy?: boolean): Range;
+
+  /** Construct a Range object. */
+  constructor(pointA?: PointCompatible, pointB?: PointCompatible);
+
+  /** Call this with the result of Range::serialize to construct a new Range. */
+  static deserialize(array: object): Range;
+
+  /** Returns a new range with the same start and end positions. */
+  copy(): Range;
+
+  /** Returns a new range with the start and end positions negated. */
+  negate(): Range;
+
+  // Serialization and Deserialization
+  /** Returns a plain javascript object representation of the Range. */
+  serialize(): number[][];
+
+  // Range Details
+  /** Is the start position of this range equal to the end position? */
+  isEmpty(): boolean;
+
+  /**
+  * Returns a boolean indicating whether this range starts and ends on the same
+  * row.
+  */
+  isSingleLine(): boolean;
+
+  /** Get the number of rows in this range. */
+  getRowCount(): number;
+
+  /** Returns an array of all rows in the range. */
+  getRows(): number[];
+
+  // Operations
+  /**
+  * Freezes the range and its start and end point so it becomes immutable and
+  * returns itself.
+  */
+  freeze(): Readonly<Range>;
+
+  // NOTE: this function doesn't actually take a range-compatible parameter.
+  /** Returns a new range that contains this range and the given range. */
+  union(other: RangeLike): Range;
+
+  /**
+  * Build and return a new range by translating this range's start and end
+  * points by the given delta(s).
+  */
+  translate(startDelta: PointCompatible, endDelta?: PointCompatible): Range;
+
+  /**
+  * Build and return a new range by traversing this range's start and end
+  * points by the given delta.
+  */
+  traverse(delta: PointCompatible): Range;
+
+  // Comparison
+  /**
+   * Compare two Ranges.
+   *
+   * Returns `-1` if this range starts before the argument or contains it.
+   *
+   * Returns `0` if this range is equivalent to the argument.
+   *
+   * Returns `1` if this range starts after the argument or is contained by it.
+   */
+  compare(otherRange: RangeCompatible): number;
+
+  /**
+   * Returns a Boolean indicating whether this range has the same start and end
+   * points as the given Range.
+   */
+  isEqual(otherRange: RangeCompatible): boolean;
+
+  // NOTE: this function doesn't actually take a range-compatible parameter.
+  /**
+   * Returns a Boolean indicating whether this range starts and ends on the
+   * same row as the argument.
+   */
+  coversSameRows(otherRange: RangeLike): boolean;
+
+  // NOTE: this function doesn't actually take a range-compatible parameter.
+  /** Determines whether this range intersects with the argument. */
+  intersectsWith(otherRange: RangeLike, exclusive?: boolean): boolean;
+
+  /** Returns a boolean indicating whether this range contains the given range. */
+  containsRange(otherRange: RangeCompatible, exclusive?: boolean): boolean;
+
+  /** Returns a boolean indicating whether this range contains the given point. */
+  containsPoint(point: PointCompatible, exclusive?: boolean): boolean;
+
+  /**
+   * Returns a boolean indicating whether this range intersects the given row
+   * number.
+   */
+  intersectsRow(row: number): boolean;
+
+  /**
+   * Returns a boolean indicating whether this range intersects the row range
+   * indicated by the given startRow and endRow numbers.
+   */
+  intersectsRowRange(startRow: number, endRow: number): boolean;
+
+  // Conversion
+  /** Returns a string representation of the range. */
+  toString(): string;
+}
+
+/**
+ * The types usable when constructing a range via the {@link Range#fromObject}
+ * method.
+ */
+export type RangeCompatible =
+  | RangeLike
+  | [PointLike, PointLike]
+  | [PointLike, [number, number]]
+  | [[number, number], PointLike]
+  | [[number, number], [number, number]];
+
+/** The interface that should be implemented for all "range-compatible" objects. */
+export interface RangeLike {
+  /** A Point representing the start of the Range. */
+  start: PointLike;
+
+  /** A Point representing the end of the Range. */
+  end: PointLike;
+}