@types/atom

import { ReadStream, WriteStream } from "fs"; import { Disposable, FileSavedEvent, HandleableErrorEvent, HistoryTransactionOptions, HistoryTraversalOptions, 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 TextBuffer.load instead. */ static loadSync(filePath: string, params?: BufferLoadOptions): TextBuffer; /** * Restore a TextBuffer based on an earlier state created using the * 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 /** * Invoke the given callback synchronously before the content of the buffer * changes. */ onWillChange(callback: (event: BufferChangingEvent) => void): Disposable; /** * Invoke the given callback synchronously when the content of the buffer * changes. You should probably not be using this in packages. */ onDidChange(callback: (event: BufferChangedEvent) => void): Disposable; /** * Invoke the given callback synchronously when a transaction finishes with * a list of all the changes in the transaction. */ onDidChangeText(callback: (event: BufferStoppedChangingEvent) => void): Disposable; /** * Invoke the given callback asynchronously following one or more changes after * ::getStoppedChangingDelay milliseconds elapse without an additional change. */ onDidStopChanging(callback: (event: BufferStoppedChangingEvent) => void): Disposable; /** * Invoke 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; /** Invoke the given callback if the value of ::isModified changes. */ onDidChangeModified(callback: (modified: boolean) => void): Disposable; /** * Invoke the given callback when all marker ::onDidChange observers have been * notified following a change to the buffer. */ onDidUpdateMarkers(callback: () => void): Disposable; onDidCreateMarker(callback: (marker: Marker) => void): Disposable; /** Invoke the given callback when the value of ::getPath changes. */ onDidChangePath(callback: (path: string) => void): Disposable; /** Invoke the given callback when the value of ::getEncoding changes. */ onDidChangeEncoding(callback: (encoding: string) => void): Disposable; /** * Invoke 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; /** Invoke the given callback after the buffer is saved to disk. */ onDidSave(callback: (event: FileSavedEvent) => void): Disposable; /** Invoke the given callback after the file backing the buffer is deleted. */ onDidDelete(callback: () => void): Disposable; /** * Invoke the given callback before the buffer is reloaded from the contents * of its file on disk. */ onWillReload(callback: () => void): Disposable; /** * Invoke the given callback after the buffer is reloaded from the contents * of its file on disk. */ onDidReload(callback: () => void): Disposable; /** Invoke the given callback when the buffer is destroyed. */ onDidDestroy(callback: () => void): Disposable; /** Invoke 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 * ::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 {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 `::transact`. */ abortTransaction(): void; /** Clear the undo stack. */ clearUndoStack(): void; /** * Create a pointer to the current state of the buffer for use with * `::revertToCheckpoint` and `::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 ::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; } export interface TextBufferFileBackend { /** A {Function} that returns the {String} path to the file. */ getPath(): string; /** * A {Function} that returns a `Readable` stream * that can be used to load the file's content. */ createReadStream(): ReadStream; /** * A {Function} that returns a `Writable` stream * that can be used to save content to the file. */ createWriteStream(): WriteStream; /** A {Function} that returns a {Boolean}, true if the file exists, false otherwise. */ existsSync(): boolean; /** * A {Function} that invokes its callback argument * when the file changes. The method should return a {Disposable} that * can be used to prevent further calls to the callback. */ onDidChange?(callback: () => void): Disposable; /** * A {Function} that invokes its callback argument * when the file is deleted. The method should return a {Disposable} that * can be used to prevent further calls to the callback. */ onDidDelete?(callback: () => void): Disposable; /** * A {Function} that invokes its callback argument * when the file is renamed. The method should return a {Disposable} that * can be used to prevent further calls to the callback. */ onDidRename?(callback: () => void): Disposable; } export interface BufferChangingEvent { /** Range of the old text. */ oldRange: Range; } 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; } export interface BufferStoppedChangingEvent { changes: TextChange[]; } 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; } export interface BufferScanResult { buffer: TextBuffer; lineText: string; match: RegExpExecArray; matchText: string; range: Range; replace(replacementText: string): void; stop(): void; stopped: boolean; } export interface ContextualBufferScanResult extends BufferScanResult { leadingContextLines: string[]; trailingContextLines: string[]; } 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; }