DefinitelyTyped/types/text-buffer/index.d.ts

// Type definitions for text-buffer 13.x
// Project: https://github.com/atom/text-buffer
// Definitions by: GlenCFL <https://github.com/GlenCFL>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// TypeScript Version: 2.2

/// <reference types="event-kit" />
/// <reference types="pathwatcher" />

declare global {
	namespace TextBuffer {
		/** Objects that appear as parameters to callbacks. */
		namespace Events {
			interface BufferWatchError {
				/** The error object. */
				error: Error;

				/** Call this function to indicate you have handled the error.
				 *  The error will not be thrown if this function is called.
				 */
				handle(): void;
			}

			interface FileSaved {
				/** The path to which the buffer was saved. */
				path: string;
			}

			interface MarkerChanged {
				/** 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;

				/** -DEPRECATED- Object containing the marker's custom properties before the change.
				 *  @deprecated
				 */
				oldProperties: object;

				/** -DEPRECATED- 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;
			}

			interface DisplayMarkerChanged {
				/** 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;

				/** -DEPRECATED- Object containing the marker's custom properties before the change.
				 *  @deprecated
				 */
				oldProperties: object;

				/** -DEPRECATED- 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;
			}

			interface BufferChanging {
				/** Range of the old text. */
				oldRange: Range;
			}

			interface BufferChanged {
				/** 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;
			}

			interface BufferStoppedChanging {
				changes: Structures.TextChange[];
			}
		}

		/** Objects that appear as parameters to functions. */
		namespace Options {
			interface BufferLoad {
				/** The file's encoding. */
				encoding?: string;

				/** A function that returns a boolean indicating whether the buffer should
				 *  be destroyed if its file is deleted.
				 */
				shouldDestroyOnFileDelete?(): boolean;
			}

			interface FindMarker {
				/** Only include markers that start at the given Point. */
				startPosition?: PointLike|[number, number];

				/** Only include markers that end at the given Point. */
				endPosition?: PointLike|[number, number];

				/** Only include markers that start inside the given Range. */
				startsInRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers that end inside the given Range. */
				endsInRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers that contain the given Point, inclusive. */
				containsPoint?: PointLike|[number, number];

				/** Only include markers that contain the given Range, inclusive. */
				containsRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];

				/** Only include markers that start at the given row number. */
				startRow?: number;

				/** Only include markers that end at the given row number. */
				endRow?: number;

				/** Only include markers that intersect the given row number. */
				intersectsRow?: number;
			}

			interface FindDisplayMarker {
				/** Only include markers starting at this Point in buffer coordinates. */
				startBufferPosition?: PointLike|[number, number];

				/** Only include markers ending at this Point in buffer coordinates. */
				endBufferPosition?: PointLike|[number, number];

				/** Only include markers starting at this Point in screen coordinates. */
				startScreenPosition?: PointLike|[number, number];

				/** Only include markers ending at this Point in screen coordinates. */
				endScreenPosition?: PointLike|[number, number];

				/** Only include markers starting inside this Range in buffer coordinates. */
				startsInBufferRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers ending inside this Range in buffer coordinates. */
				endsInBufferRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers starting inside this Range in screen coordinates. */
				startsInScreenRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers ending inside this Range in screen coordinates. */
				endsInScreenRange?: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
					[[number, number], PointLike]|[[number, number], [number, number]];

				/** Only include markers starting at this row in buffer coordinates. */
				startBufferRow?: number;

				/** Only include markers ending at this row in buffer coordinates. */
				endBufferRow?: number;

				/** Only include markers starting at this row in screen coordinates. */
				startScreenRow?: number;

				/** Only include markers ending at this row in screen coordinates. */
				endScreenRow?: number;

				/** Only include markers intersecting this Array of [startRow, endRow] in
				 *  buffer coordinates.
				 */
				intersectsBufferRowRange?: [number, number];

				/** Only include markers intersecting this Array of [startRow, endRow] in
				 *  screen coordinates.
				 */
				intersectsScreenRowRange?: [number, number];

				/** Only include markers containing this Range in buffer coordinates. */
				containsBufferRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];

				/** Only include markers containing this Point in buffer coordinates. */
				containsBufferPosition?: PointLike|[number, number];

				/** Only include markers contained in this Range in buffer coordinates. */
				containedInBufferRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];

				/** Only include markers contained in this Range in screen coordinates. */
				containedInScreenRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];

				/** Only include markers intersecting this Range in buffer coordinates. */
				intersectsBufferRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];

				/** Only include markers intersecting this Range in screen coordinates. */
				intersectsScreenRange?: RangeLike|[PointLike, PointLike]|
					[PointLike, [number, number]]|[[number, number], PointLike]|
					[[number, number], [number, number]];
			}

			interface CopyMarker {
				/** Whether or not the marker should be tailed. */
				tailed?: boolean;

				/** Creates the marker in a reversed orientation. */
				reversed?: boolean;

				/** Determines the rules by which changes to the buffer invalidate the marker. */
				invalidate?: "never"|"surround"|"overlap"|"inside"|"touch";

				/** Indicates whether insertions at the start or end of the marked range should
				 *  be interpreted as happening outside the marker.
				 */
				exclusive?: boolean;

				/** -DEPRECATED- Custom properties to be associated with the marker. */
				properties?: object;
			}

			interface ScanContext {
				/** The number of lines before the matched line to include in the results object. */
				leadingContextLineCount?: number;

				/** The number of lines after the matched line to include in the results object. */
				trailingContextLineCount?: number;
			}
		}

		/** The static side to each exported class. Should generally only be used internally. */
		namespace Statics {
			/* tslint:disable:no-unnecessary-qualifier */
			/** The static side to the Point class. */
			interface Point {
				/** Create a Point from an array containing two numbers representing the
				 *  row and column.
				 */
				fromObject(object: [number, number]): TextBuffer.Point;

				/** Create a Point from an existing object which implements PointLike. */
				fromObject(object: TextBuffer.PointLike, copy?: boolean): TextBuffer.Point;

				/** Construct a Point object */
				new (row?: number, column?: number): TextBuffer.Point;

				/** Returns the given Point that is earlier in the buffer. */
				min(point1: TextBuffer.PointLike|[number, number], point2: TextBuffer.PointLike|
					[number, number]): TextBuffer.Point;
			}

			/** The static side to the Range class. */
			interface Range {
				/** Convert any range-compatible object to a Range. */
				fromObject(object: TextBuffer.RangeLike|[TextBuffer.PointLike, TextBuffer.PointLike]|
					[TextBuffer.PointLike, [number, number]]|[[number, number], TextBuffer.PointLike]|
					[[number, number], [number, number]], copy?: boolean): TextBuffer.Range;

				/** Construct a Range object. */
				new (pointA?: TextBuffer.PointLike|[number, number], pointB?: TextBuffer.PointLike|
					[number, number]): TextBuffer.Range;

				/** Call this with the result of Range::serialize to construct a new Range. */
				deserialize(array: object): TextBuffer.Range;
			}

			/** The static side to the TextBuffer class. */
			interface TextBuffer {
				Point: TextBuffer.Statics.Point;
				Range: TextBuffer.Statics.Range;

				/** Create a new buffer with the given starting text. */
				new (text: string): TextBuffer.TextBuffer;
				/** Create a new buffer with the given params. */
				new (params?: {
					/** The initial string text of the buffer. */
					text?: string
					/** A function that returns a Boolean indicating whether the buffer should
					 *  be destroyed if its file is deleted.
					 */
					shouldDestroyOnFileDelete?(): boolean
				}): TextBuffer.TextBuffer;

				/** Create a new buffer backed by the given file path. */
				load(source: string, params?: TextBuffer.Options.BufferLoad):
					Promise<TextBuffer.TextBuffer>;

				/** Create a new buffer backed by the given file path. For better performance,
				 *  use TextBuffer.load instead.
				 */
				loadSync(filePath: string, params?: TextBuffer.Options.BufferLoad):
					TextBuffer.TextBuffer;

				/** Restore a TextBuffer based on an earlier state created using the TextBuffer::serialize
				 *  method.
				 */
				deserialize(params: object): Promise<TextBuffer.TextBuffer>;
			}
			/* tslint:enable:no-unnecessary-qualifier */
		}

		/** Data structures that are used within classes. */
		namespace Structures {
			interface TextChange {
				newExtent: Point;
				oldExtent: Point;
				newRange: Range;
				oldRange: Range;
				newText: string;
				oldText: string;
				start: Point;
			}

			interface BufferScanResult {
				buffer: TextBuffer;
				lineText: string;
				match: RegExpExecArray;
				matchText: string;
				range: Range;
				replace(replacementText: string): void;
				stop(): void;
				stopped: boolean;
			}

			interface ContextualBufferScanResult extends BufferScanResult {
				leadingContextLines: string[];
				trailingContextLines: string[];
			}
		}

		/** The interface that should be implemented for all "point-compatible" objects. */
		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;
		}

		/** Represents a point in a buffer in row/column coordinates. */
		interface Point extends PointLike {
			// 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
			/** 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
			/** 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: PointLike|[number, number]): number;

			/** Returns a boolean indicating whether this point has the same row and
			 *  column as the given Point.
			 */
			isEqual(other: PointLike|[number, number]): boolean;

			/** Returns a Boolean indicating whether this point precedes the given Point. */
			isLessThan(other: PointLike|[number, number]): boolean;

			/** Returns a Boolean indicating whether this point precedes or is equal to
			 *  the given Point.
			 */
			isLessThanOrEqual(other: PointLike|[number, number]): boolean;

			/** Returns a Boolean indicating whether this point follows the given Point. */
			isGreaterThan(other: PointLike|[number, number]): boolean;

			/** Returns a Boolean indicating whether this point follows or is equal to
			 *  the given Point.
			 */
			isGreaterThanOrEqual(other: PointLike|[number, number]): 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: PointLike|[number, number]): Point;

			/** Build and return a new Point by traversing the rows and columns
			 *  specified by the given point.
			 */
			traverse(other: PointLike|[number, number]): 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 "range-compatible" objects. */
		interface RangeLike {
			/** A Point representing the start of the Range. */
			start: PointLike;

			/** A Point representing the end of the Range. */
			end: PointLike;
		}

		/** Represents a region in a buffer in row/column coordinates. */
		interface Range extends RangeLike {
			// Properties
			/** A Point representing the start of the Range. */
			start: PointLike;

			/** A Point representing the end of the Range. */
			end: PointLike;

			// Construction
			/** 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: PointLike|[number, number], endDelta?: PointLike|
				[number, number]): Range;

			/** Build and return a new range by traversing this range's start and end
			 *  points by the given delta.
			 */
			traverse(delta: PointLike|[number, number]): 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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]]): number;

			/** Returns a Boolean indicating whether this range has the same start and
			 *  end points as the given Range.
			 */
			isEqual(otherRange: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]]): 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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], exclusive?:
				boolean): boolean;

			/** Returns a boolean indicating whether this range contains the given point. */
			containsPoint(point: PointLike|[number, number], 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;
		}

		/** Represents a buffer annotation that remains logically stationary even as
		 *  the buffer changes.
		 */
		interface Marker {
			// Properties
			id: number;
			tailed: boolean;
			reversed: boolean;
			valid: boolean;
			invalidate: string;
			properties: object;

			// Lifecycle
			/** Creates and returns a new Marker with the same properties as this
			 *  marker.
			 */
			copy(options?: Options.CopyMarker): 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): EventKit.Disposable;

			/** Invoke the given callback when the state of the marker changes. */
			onDidChange(callback: (event: Events.MarkerChanged) => void):
				EventKit.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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], params?: {
				reversed?: boolean, exclusive?: boolean }): boolean;

			/** Sets the head position of the marker.
			 *  Returns a boolean indicating whether or not the marker was updated.
			 */
			setHeadPosition(position: PointLike|[number, number]): boolean;

			/** Sets the tail position of the marker.
			 *  Returns a boolean indicating whether or not the marker was updated.
			 */
			setTailPosition(position: PointLike|[number, number]): 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;
		}

		/** Experimental: A container for a related set of markers. */
		interface MarkerLayer {
			// 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: Options.FindMarker): Marker[];

			// Marker Creation
			/** Create a marker with the given range. */
			markRange(range: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], options?:
				{ reversed?: boolean, invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean }): Marker;

			/** Create a marker at with its head at the given position with no tail. */
			markPosition(position: PointLike|[number, number], options?: {
				invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean
			}): Marker;

			// Event Subscription
			/** Subscribe to be notified asynchronously whenever markers are created,
			 *  updated, or destroyed on this layer.
			 */
			onDidUpdate(callback: () => void): EventKit.Disposable;

			/** Subscribe to be notified synchronously whenever markers are created on
			 *  this layer.
			 */
			onDidCreateMarker(callback: (marker: Marker) => void): EventKit.Disposable;

			/** Subscribe to be notified synchronously when this layer is destroyed. */
			onDidDestroy(callback: () => void): EventKit.Disposable;
		}

		/** A mutable text container with undo/redo support and the ability to
		 *  annotate logical regions in the text.
		 */
		interface TextBuffer {
			// Properties
			file: PathWatcher.File;
			lines: string[];
			lineEndings: string[];
			stoppedChangingDelay: number;
			conflict: boolean;
			loaded: boolean;
			destroyed: boolean;
			refcount: number;
			id: string;

			/** Schedules a 'did-stop-changing' emission. The event will be emitted between
			 *  now and TextBuffer::stoppedChangingDelay milliseconds in the future.
			 */
			debouncedEmitDidStopChangingEvent(): void;

			// Lifecycle
			/** Destroys the buffer, emitting the 'did-destroy' prior to doing so. */
			destroy(): void;

			/** Returns whether or not the given buffer is alive. */
			isAlive(): boolean;

			/** Returns whether or not the given buffer has been destroyed. */
			isDestroyed(): boolean;

			/** Returns whether or not this text buffer is currently retained. */
			isRetained(): boolean;

			/** Retains the text buffer, preventing its destruction via TextBuffer::release. */
			retain(): TextBuffer;

			/** Release the text buffer, destroying it if there are no other retainers. */
			release(): TextBuffer;

			// Event Subscription
			/** Invoke the given callback synchronously before the content of the buffer
			 *  changes.
			 */
			onWillChange(callback: (event: Events.BufferChanging) => void):
				EventKit.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: Events.BufferChanged) => void):
				EventKit.Disposable;

			/** Invoke the given callback synchronously when a transaction finishes with
			 *  a list of all the changes in the transaction.
			 */
			onDidChangeText(callback: (event: Events.BufferStoppedChanging) => void):
				EventKit.Disposable;

			/** Invoke the given callback asynchronously following one or more changes after
			 *  ::getStoppedChangingDelay milliseconds elapse without an additional change.
			 */
			onDidStopChanging(callback: (event: Events.BufferStoppedChanging) => void):
				EventKit.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): EventKit.Disposable;

			/** Invoke the given callback if the value of ::isModified changes. */
			onDidChangeModified(callback: (modified: boolean) => void):
				EventKit.Disposable;

			/** Invoke the given callback when all marker ::onDidChange observers have been
			 *  notified following a change to the buffer.
			 */
			onDidUpdateMarkers(callback: () => void): EventKit.Disposable;

			onDidCreateMarker(callback: (marker: Marker) => void):
				EventKit.Disposable;

			/** Invoke the given callback when the value of ::getPath changes. */
			onDidChangePath(callback: (path: string) => void): EventKit.Disposable;

			/** Invoke the given callback when the value of ::getEncoding changes. */
			onDidChangeEncoding(callback: (encoding: string) => void):
				EventKit.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): EventKit.Disposable;

			/** Invoke the given callback after the buffer is saved to disk. */
			onDidSave(callback: (event: Events.FileSaved) => void):
				EventKit.Disposable;

			/** Invoke the given callback after the file backing the buffer is deleted. */
			onDidDelete(callback: () => void): EventKit.Disposable;

			/** Invoke the given callback before the buffer is reloaded from the contents
			 *  of its file on disk.
			 */
			onWillReload(callback: () => void): EventKit.Disposable;

			/** Invoke the given callback after the buffer is reloaded from the contents
			 *  of its file on disk.
			 */
			onDidReload(callback: () => void): EventKit.Disposable;

			/** Invoke the given callback when the buffer is destroyed. */
			onDidDestroy(callback: () => void): EventKit.Disposable;

			/** Invoke the given callback when there is an error in watching the file. */
			onWillThrowWatchError(callback: (errorObject: Events.BufferWatchError) =>
				void): EventKit.Disposable;

			/** Get the number of milliseconds that will elapse without a change before
			 *  ::onDidStopChanging observers are invoked following a change.
			 */
			getStoppedChangingDelay(): number;

			/** Performs the necessary work, then emits the 'did-stop-changing' event. */
			emitDidStopChangingEvent(): void;

			// 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;

			/** 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;

			/** Identifies if the buffer belongs to multiple editors. */
			hasMultipleEditors(): boolean;

			// Reading Text
			/** Determine whether the buffer is empty. */
			isEmpty(): boolean;

			/** Get the entire text of the buffer. */
			getText(): string;

			/** Get the text in a range. */
			getTextInRange(range: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]]): 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 row, without its line ending. */
			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;

			// 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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], text: string,
				options?: { normalizeLineEndings?: boolean, undo?: "skip" }): Range;

			/** Insert text at the given position. */
			insert(position: PointLike|[number, number], text: string, options?: {
				normalizeLineEndings?: boolean,
				undo?: "skip"
			}): Range;

			/** Append text to the end of the buffer. */
			append(text: string, options?: {
				normalizeLineEndings?: boolean,
				undo?: "skip"
			}): Range;

			/** Delete the text in the given range. */
			delete(range: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]]): Range;

			/** Delete the line associated with a specified row. */
			deleteRow(row: number): Range;

			/** Delete the lines associated with the specified row range. */
			deleteRows(startRow: number, endRow: number): Range;

			// Markers
			/** Create a layer to contain a set of related markers. */
			addMarkerLayer(options?: {
				maintainHistory?: boolean,
				persistent?: boolean
			}): MarkerLayer;

			/** Get a MarkerLayer by id.
			 *  Returns a MarkerLayer or `` 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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], properties?:
				{ reversed?: boolean, invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean }): Marker;

			/** Create a marker at the given position with no tail in the default marker layer. */
			markPosition(position: PointLike|[number, number], options?: {
				invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean
			}): 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: Options.FindMarker): 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. */
			undo(): boolean;

			/** Redo the last operation. */
			redo(): boolean;

			/** Batch multiple operations as a single undo/redo step. */
			transact<T>(groupingInterval: number, fn: () => T): T;
			transact<T>(fn: () => T): T;

			/** Call within a transaction to terminate the function's execution and
			 *  revert any changes performed up to the abortion.
			 */
			abortTransaction(): void;

			/** Clear the undo stack. When calling this method within a transaction,
			 *  the ::onDidChangeText event will not be triggered because the information
			 *  describing the changes is lost.
			 */
			clearUndoStack(): void;

			/** Create a pointer to the current state of the buffer for use with
			 *  ::revertToCheckpoint and ::groupChangesSinceCheckpoint.
			 */
			createCheckpoint(): number;

			/** Revert the buffer to the state it was in when the given checkpoint was created.
			 *  Returns a boolean indicating whether the operation succeeded.
			 */
			revertToCheckpoint(checkpoint: number): boolean;

			/** Group all changes since the given checkpoint into a single transaction for
			 *  purposes of undo/redo.
			 *  Returns a boolean indicating whether the operation succeeded.
			 */
			groupChangesSinceCheckpoint(checkpoint: number): 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: Structures.BufferScanResult) => void): void;
			/** Scan regular expression matches in the entire buffer, calling the given
			 *  iterator function on each match.
			 */
			scan(regex: RegExp, options: Options.ScanContext, iterator: (params:
				Structures.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: Structures.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: Options.ScanContext, iterator: (params:
				Structures.ContextualBufferScanResult) => void): void;

			/** Scan regular expression matches in a given range , calling the given
			 *  iterator function on each match.
			 */
			scanInRange(regex: RegExp, range: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				iterator: (params: Structures.BufferScanResult) => void): void;
			/** Scan regular expression matches in a given range , calling the given
			 *  iterator function on each match.
			 */
			scanInRange(regex: RegExp, range: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				options: Options.ScanContext, iterator: (params:
				Structures.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: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				iterator: (params: Structures.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: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				options: Options.ScanContext, iterator: (params:
				Structures.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 in characters. */
			getMaxCharacterIndex(): number;

			/** Get the range for the given row. */
			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: Point|[number, number]): 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: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]]): Range;

			/** Clip the given point so it is at a valid position in the buffer. */
			clipPosition(position: PointLike|[number, number]): 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;
		}

		/** 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.
		 */
		interface DisplayMarker {
			// 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?: Options.CopyMarker): DisplayMarker;

			// Event Subscription
			/** Invoke the given callback when the state of the marker changes. */
			onDidChange(callback: (event: Events.DisplayMarkerChanged) => void):
				EventKit.Disposable;

			/** Invoke the given callback when the marker is destroyed. */
			onDidDestroy(callback: () => void): EventKit.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: Options.FindDisplayMarker): 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: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				properties?: { reversed: boolean }): void;

			/** Modifies the screen range of this marker. */
			setScreenRange(screenRange: RangeLike|[PointLike, PointLike]|[PointLike,
				[number, number]]|[[number, number], PointLike]|[[number, number], [number, number]],
				options?: { reversed?: boolean, clipDirection?: "backward"|"forward"|"closest" }): 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 DisplayMarker::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: PointLike|[number, number]): 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: PointLike|[number, number], 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: PointLike|[number, number]): 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: PointLike|[number, number], 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;
		}

		/** 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.
		 */
		interface DisplayMarkerLayer {
			// 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): EventKit.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): EventKit.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): EventKit.Disposable;

			// Marker creation
			/** Create a marker with the given screen range. */
			markScreenRange(range: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], options?:
				{ reversed?: boolean, invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean, clipDirection?: "backward"|"forward"|"closest" }): DisplayMarker;

			/** Create a marker on this layer with its head at the given screen position
			 *  and no tail.
			 */
			markScreenPosition(screenPosition: PointLike|[number, number], options?: {
				invalidate?: "never"|"surround"|"overlap"|"inside"|"touch", exclusive?: boolean,
				clipDirection?: "backward"|"forward"|"closest" }): DisplayMarker;

			/** Create a marker with the given buffer range. */
			markBufferRange(range: RangeLike|[PointLike, PointLike]|[PointLike, [number, number]]|
				[[number, number], PointLike]|[[number, number], [number, number]], options?: {
				reversed?: boolean, invalidate?: "never"|"surround"|"overlap"|"inside"|"touch",
				exclusive?: boolean }): DisplayMarker;

			/** Create a marker on this layer with its head at the given buffer position and no tail. */
			markBufferPosition(bufferPosition: PointLike|[number, number], options?: { invalidate?:
				"never"|"surround"|"overlap"|"inside"|"touch", exclusive?: boolean }): 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: Options.FindDisplayMarker): DisplayMarker[];
		}
	}
}

declare let tb: TextBuffer.Statics.TextBuffer;
export = tb;