@pulsar-edit/types 1.128.1

package/src/git-repository.d.ts

@@ -0,0 +1,174 @@
+import { Config, Disposable, Project } from "../index";
+
+/** Represents the underlying git operations performed by Atom. */
+export class GitRepository {
+  // Construction
+  /** Creates a new GitRepository instance. */
+  static open(path: string, options?: { refreshOnWindowFocus?: boolean | undefined }): GitRepository;
+
+  constructor(
+    path: string,
+    options?: {
+      refreshOnWindowFocus?: boolean | undefined;
+      config?: Config | undefined;
+      project?: Project | undefined;
+    },
+  );
+
+  // Lifecycle
+  /** Destroy this GitRepository object. */
+  destroy(): void;
+
+  /** Returns a boolean indicating if this repository has been destroyed. */
+  isDestroyed(): boolean;
+
+  // Event Subscription
+  /**
+   *  Invoke the given callback when this GitRepository's destroy() method is
+   *  invoked.
+   */
+  onDidDestroy(callback: () => void): Disposable;
+
+  /**
+   * Invoke the given callback when a specific file's status has changed. When
+   * a file is updated, reloaded, etc., and the status changes, this will be
+   * fired.
+   */
+  onDidChangeStatus(callback: (event: RepoStatusChangedEvent) => void): Disposable;
+
+  /** Invoke the given callback when a multiple files' statuses have changed. */
+  onDidChangeStatuses(callback: () => void): Disposable;
+
+  /**
+   * Refreshes the current git status in an outside process and asynchronously
+   * updates the relevant properties.
+   *
+   * If this results in a status change, will fire any callbacks registered via
+   * {@link onDidChangeStatuses}.
+   */
+  refreshStatus(): Promise<void>;
+
+  // Repository Details
+  /** A string indicating the type of version control system used by this repository. */
+  getType(): "git";
+
+  /** Returns the string path of the repository. */
+  getPath(): string;
+
+  /** Returns the string working directory path of the repository. */
+  getWorkingDirectory(): string;
+
+  /** Returns true if at the root, false if in a subfolder of the repository. */
+  isProjectAtRoot(): boolean;
+
+  /** Makes a path relative to the repository's working directory. */
+  relativize(): string;
+
+  /** Returns true if the given branch exists. */
+  hasBranch(branch: string): boolean;
+
+  /** Retrieves a shortened version of the HEAD reference value. */
+  getShortHead(path?: string): string;
+
+  /** Is the given path a submodule in the repository? */
+  isSubmodule(path: string): boolean;
+
+  /**
+   * Returns the number of commits behind the current branch is from the its
+   * upstream remote branch. The default reference is the HEAD.
+   *
+   * @param reference The branch reference name.
+   * @param path The path in the repository to get this ifnromation for, only
+   *   needed if the repository contains submodules.
+   * @return The number of commits behind the current branch is from its
+   *   upstream remote branch.
+   */
+  getAheadBehindCount(reference: string, path?: string): { ahead: number; behind: number };
+
+  /**
+   * Get the cached ahead/behind commit counts for the current branch's
+   * upstream branch.
+   */
+  getCachedUpstreamAheadBehindCount(path?: string): { ahead: number; behind: number };
+
+  /** Returns the git configuration value specified by the key. */
+  getConfigValue(key: string, path?: string): string;
+
+  /** Returns the origin url of the repository. */
+  getOriginURL(path?: string): string;
+
+  /**
+   * Returns the upstream branch for the current HEAD, or null if there is no
+   * upstream branch for the current HEAD.
+   */
+  getUpstreamBranch(path?: string): string | null;
+
+  /** Gets all the local and remote references. */
+  getReferences(path?: string): { heads: string[]; remotes: string[]; tags: string[] };
+
+  /** Returns the current string SHA for the given reference. */
+  getReferenceTarget(reference: string, path?: string): string;
+
+  // Reading Status
+  /** Returns true if the given path is modified. */
+  isPathModified(path: string): boolean;
+
+  /** Returns true if the given path is new. */
+  isPathNew(path: string): boolean;
+
+  /** Is the given path ignored? */
+  isPathIgnored(path: string): boolean;
+
+  /** Get the status of a directory in the repository's working directory. */
+  getDirectoryStatus(path: string): number;
+
+  /** Get the status of a single path in the repository. */
+  getPathStatus(path: string): number;
+
+  /** Get the cached status for the given path. */
+  getCachedPathStatus(path: string): number | null;
+
+  /** Returns `true` if the given status indicates modification. */
+  isStatusModified(status: number): boolean;
+
+  /** Returns `true` if the given status indicates a new path. */
+  isStatusNew(status: number): boolean;
+
+  // Retrieving Diffs
+  /**
+   * Retrieve the number of lines added and removed to a path.
+   *
+   * This compares the working directory contents of the path to the HEAD
+   * version.
+   */
+  getDiffStats(path: string): { added: number; deleted: number };
+
+  /**
+   * Retrieve the line diffs comparing the HEAD version of the given path and
+   * the given text.
+   */
+  getLineDiffs(
+    path: string,
+    text: string,
+  ): Array<{ oldStart: number; newStart: number; oldLines: number; newLines: number }>;
+
+  // Checking Out
+  /**
+   *  Restore the contents of a path in the working directory and index to the
+   *  version at HEAD.
+   */
+  checkoutHead(path: string): boolean;
+
+  /** Check out a branch in your repository. */
+  checkoutReference(reference: string, create: boolean): boolean;
+}
+
+export interface RepoStatusChangedEvent {
+  path: string;
+
+  /**
+   * This value can be passed to {@link GitRepository#isStatusModified} or
+   * {@link GitRepository#isStatusNew} to get more information.
+   */
+  pathStatus: number;
+}

package/src/grammar-registry.d.ts

@@ -0,0 +1,241 @@
+import {
+  Disposable,
+  Grammar as TextMateGrammar,
+  GrammarToken,
+  TextBuffer
+} from "../index";
+import {
+  InjectionPoint,
+  WASMTreeSitterGrammar,
+  WASMTreeSitterGrammarParams
+} from "./wasm-tree-sitter-grammar";
+
+type GenericGrammar = TextMateGrammar | WASMTreeSitterGrammar
+
+type GrammarType = 'modern-tree-sitter' | 'textmate'
+
+type TextMateGrammarParams = {
+  maxTokensPerLine?: number
+  maxLineLength?: number
+  limitLineLength?: boolean
+  name: string
+  fileTypes?: string[]
+  scopeName: string
+  foldingStopMarker?: string
+
+  injections?: unknown[]
+  injectionSelector?: string
+
+  patterns?: unknown[]
+  repository?: unknown
+  firstLineMatch?: string
+  contentRegex?: string
+}
+
+type GrammarConstructorParams = WASMTreeSitterGrammarParams | TextMateGrammarParams
+
+type CreateGrammarParams = {
+  type: 'modern-tree-sitter',
+  params: GrammarConstructorParams
+} | {
+  params: TextMateGrammarParams
+}
+
+type LanguageScopeFunction = (
+  grammar: WASMTreeSitterGrammar,
+  buffer: TextBuffer,
+  range: Range
+) => string | null
+
+
+/** Registry containing one or more grammars. */
+export interface GrammarRegistry {
+  // Event Subscription
+  /**
+   *  Invoke the given callback when a grammar is added to the registry.
+   *
+   * @param callback The callback to be invoked whenever a grammar is added.
+   * @return A Disposable on which `.dispose()` can be called to unsubscribe.
+   */
+  onDidAddGrammar(callback: (grammar: GenericGrammar) => void): Disposable;
+
+  /**
+   *  Invoke the given callback when a grammar is updated due to a grammar it
+   *  depends on being added or removed from the registry.
+   *
+   * @param callback The callback to be invoked whenever a grammar is updated.
+   * @return A Disposable on which `.dispose()` can be called to unsubscribe.
+   */
+  onDidUpdateGrammar(callback: (grammar: GenericGrammar) => void): Disposable;
+
+  /**
+   *  Invoke the given callback when a grammar is removed from the registry.
+   *
+   * @param callback The callback to be invoked whenever a grammar is removed.
+   * @return A Disposable on which `.dispose()` can be called to unsubscribe.
+   */
+  onDidRemoveGrammar(callback: (grammar: GenericGrammar) => void): Disposable;
+
+  // Managing Grammars
+  /**
+   *  Get all the grammars in this registry.
+   *
+   * @param options When `includeTreeSitterGrammars` is `true`, will return
+   *   both `Grammar`s and `WASMTreeSitterGrammar`s. Defaults to `false`.
+   * @return A non-empty array of `Grammar` instances.
+   */
+  getGrammars(options?: { includeTreeSitterGrammars?: boolean }): GenericGrammar[];
+
+  /**
+   * Get a grammar with the given scope name.
+   *
+   * If there is more than one kind of grammar for the given scope name, will
+   * return the grammar that matches the preferred grammar type for the given
+   * language as configured by the user.
+   *
+   * @param scopeName A string such as `source.js`.
+   * @return A Grammar or undefined.
+   */
+  grammarForScopeName(scopeName: string): GenericGrammar | undefined;
+
+  /**
+   *  Add a grammar to this registry.
+   *
+   *  A 'grammar-added' event is emitted after the grammar is added.
+   *
+   *  @param grammar The Grammar to add. This should be a value previously
+   *    returned from {@link readGrammar} or {@link readGrammarSync}.
+   *  @return Returns a Disposable on which `.dispose()` can be called to
+   *    remove the grammar.
+   */
+  addGrammar(grammar: GenericGrammar): Disposable;
+
+  /**
+   *  Remove the given grammar from this registry.
+   *
+   *  @param grammar The grammar to remove. This should be a grammar previously
+   *    added to the registry from {@link addGrammar}.
+   */
+  removeGrammar(grammar: GenericGrammar): void;
+
+  /**
+   * Create a grammar of the type indicated by `params.type` — or a
+   * TextMate-style `Grammar` by default.
+   *
+   * @param grammarPath The path to the grammar configuration file.
+   * @param params Parameters to pass to the constructor. If `params.type`
+   *   is `'modern-tree-sitter'`, will create a `WASMTreeSitterGrammar`;
+   *   otherwise will create a `Grammar`.
+   */
+  createGrammar(grammarPath: string, params: CreateGrammarParams): GenericGrammar;
+
+  /**
+   *  Remove the grammar with the given scope name.
+   *
+   * @param scopeName A string such as `source.js`.
+   * @return Returns the removed Grammar or undefined.
+   */
+  removeGrammarForScopeName(scopeName: string): TextMateGrammar | undefined;
+
+  /**
+   * Read a grammar synchronously but don't add it to the registry.
+   *
+   * @param grammarPath The absolute file path to a grammar.
+   * @return The newly loaded Grammar.
+   */
+  readGrammarSync(grammarPath: string): GenericGrammar;
+
+  /**
+   * Read a grammar asynchronously but don't add it to the registry.
+   *
+   * @param grammarPath The absolute file path to the grammar.
+   * @param callback The function to be invoked once the Grammar has been
+   *   read in.
+   */
+  readGrammar(grammarPath: string, callback: (error: Error | null, grammar?: GenericGrammar) => void): void;
+
+  /**
+   * Read a grammar synchronously and add it to this registry.
+   *
+   * @param grammarPath The absolute file path to the grammar.
+   * @return The newly loaded Grammar.
+   */
+  loadGrammarSync(grammarPath: string): GenericGrammar;
+
+  /**
+   * Read a grammar asynchronously and add it to the registry.
+   *
+   * @param grammarPath The absolute file path to the grammar.
+   * @param callback The function to be invoked once the Grammar has been read
+   *   in and added to the registry.
+   */
+  loadGrammar(grammarPath: string, callback: (error: Error | null, grammar?: GenericGrammar) => void): void;
+
+  /**
+   * Convert compact tags representation into convenient, space-inefficient
+   * tokens.
+   *
+   * @param lineText The text of the tokenized line.
+   * @param tags The tags returned from a call to Grammar::tokenizeLine().
+   * @return An array of GrammarToken instances decoded from the given tags.
+   */
+  decodeTokens(lineText: string, tags: Array<number | string>): GrammarToken[];
+
+  /**
+   * Set a TextBuffer's language mode based on its path and content, and
+   * continue to update its language mode as grammars are added or updated,
+   * or the buffer's file path changes.
+   *
+   * @param buffer The buffer whose language mode will be maintained.
+   * @return A {@link Disposable} that can be used to stop updating the
+   *   buffer's language mode.
+   */
+  maintainLanguageMode(buffer: TextBuffer): Disposable;
+
+  /**
+   * Force a {@link TextBuffer} to use a different grammar than the one that
+   * would otherwise be selected for it.
+   *
+   * @param buffer The buffer whose grammar will be set.
+   * @param languageId The identifier of the desired language.
+   * @return Returns a boolean that indicates whether the language was
+   *   successfully found.
+   */
+  assignLanguageMode(buffer: TextBuffer, languageId: string): boolean;
+
+  /**
+   * Remove any language mode override that has been set for the given
+   * TextBuffer. This will assign to the buffer the best language mode
+   * available.
+   */
+  autoAssignLanguageMode(buffer: TextBuffer): void;
+
+  /**
+   * Select a grammar for the given file path and file contents.
+   *
+   * This picks the best match by checking the file path and contents against
+   * each grammar.
+   *
+   * @param filePath A string file path.
+   * @param fileContents A string of text for that file path.
+   */
+  selectGrammar(filePath: string, fileContents: string): GenericGrammar;
+
+  /**
+   * Returns a number representing how well the grammar matches the `filePath`
+   * and `contents`.
+   *
+   * @param grammar The grammar to score.
+   * @param filePath A string file path.
+   * @param contents A string of text for that file path.
+   */
+  getGrammarScore(grammar: GenericGrammar, filePath: string, contents: string): number;
+
+  /**
+   * Specify a type of syntax node that may embed other languages.
+   *
+   * Returns a {@link Disposable} that, when disposed, will remove the
+   * injection point.
+   */
+  addInjectionPoint(scopeName: string, injectionPoint: InjectionPoint): Disposable;
+}

package/src/gutter.d.ts

@@ -0,0 +1,118 @@
+import { Decoration, DecorationOptions, DisplayMarker, Disposable } from "../index";
+
+/** Represents a gutter within a TextEditor. */
+export interface Gutter {
+  /** Undocumented: The name of the gutter. */
+  name?: string;
+
+  // Gutter Destruction
+  /** Destroys the gutter. */
+  destroy(): void;
+
+  // Event Subscription
+  /** Calls your callback when the gutter's visibility changes. */
+  onDidChangeVisible(callback: (gutter: Gutter) => void): Disposable;
+
+  /** Calls your callback when the gutter is destroyed. */
+  onDidDestroy(callback: () => void): Disposable;
+
+  // Visibility
+  /** Hide the gutter. */
+  hide(): void;
+
+  /** Show the gutter. */
+  show(): void;
+
+  /** Determine whether the gutter is visible. */
+  isVisible(): boolean;
+
+  /**
+   * 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;
+}
+
+export interface GutterOptions {
+  /** (required) A unique String to identify this gutter. */
+  name: string;
+
+  /**
+   * A Number that determines stacking order between gutters.
+   *
+   * Lower priority items are forced closer to the edges of the window.
+   *
+   * Defaults to `-100`.
+   */
+  priority?: number | undefined;
+
+  /**
+   * Boolean specifying whether the gutter is visible initially after being
+   * created.
+   *
+   * Defaults to `true`.
+   */
+  visible?: boolean | undefined;
+
+  /**
+   * String specifying the type of gutter to create.
+   *
+   * 'decorated' gutters are useful as a destination for decorations created
+   * with {@link Gutter#decorateMarker}.
+   */
+  type?: "decorated" | "line-number" | undefined;
+
+  /** String added to the CSS classnames of the gutter's root DOM element. */
+  class?: string | undefined;
+
+  /**
+   * Function called by a 'line-number' gutter to generate the label for each
+   * line number element. Should return a String that will be used to label the
+   * corresponding line.
+   */
+  labelFn?: ((lineData: LineDataExtended) => string) | undefined;
+
+  /**
+   * Function to be called when a mousedown event is received by a line-number
+   * element within this type: 'line-number' Gutter. If unspecified, the default
+   * behavior is to select the clicked buffer row.
+   */
+  onMouseDown?: ((lineData: LineDataEvent) => void) | undefined;
+
+  /**
+   * Function to be called when a mousemove event occurs on a line-number
+   * element within within this type: 'line-number' Gutter.
+   */
+  onMouseMove?: ((lineData: LineDataEvent) => void) | undefined;
+}
+
+
+export interface LineData {
+  /** Number indicating the zero-indexed buffer index of a line. */
+  bufferRow: number;
+
+  /** Number indicating the zero-indexed screen index. */
+  screenRow: number;
+}
+
+/**
+ * The event delivered to all {@link GutterOptions['onMouseDown']} and
+ * {@link GutterOptions['onMouseMove']} callbacks. Contains line data as well
+ * as a reference to the underlying mouse event.
+ */
+export interface LineDataEvent extends LineData {
+  domEvent: MouseEvent;
+}
+
+/** Object containing information about each line to label. */
+export interface LineDataExtended extends LineData {
+  /** Boolean that is true if a fold may be created here. */
+  foldable: boolean;
+
+  /** Boolean if this screen row is the soft-wrapped continuation of the same buffer row. */
+  softWrapped: boolean;
+
+  /** Number the maximum number of digits necessary to represent any known screen row. */
+  maxDigits: number;
+}

package/src/history-manager.d.ts

@@ -0,0 +1,28 @@
+import { Disposable } from "../index";
+
+/**
+ * History manager for remembering which projects have been opened.
+ *
+ * An instance of this class is always available as the atom.history global.
+ * The project history is used to enable the 'Reopen Project' menu.
+ */
+export interface HistoryManager {
+  /** Obtain a list of previously opened projects. */
+  getProjects(): ProjectHistory[];
+
+  /**
+   * Clear all projects from the history.
+   *
+   * Note: This is not a privacy function. Other traces will still exist —
+   * e.g., window state.
+   */
+  clearProjects(): void;
+
+  /** Invoke the given callback when the list of projects changes. */
+  onDidChangeProjects(callback: (args: { reloaded: boolean }) => void): Disposable;
+}
+
+export interface ProjectHistory {
+  paths: string[];
+  lastOpened: Date;
+}