TextBuffer Extended

A mutable text container with undo/redo support and the ability to annotate logical regions in the text.

Observing Changes

You can observe changes in a TextBuffer using methods like ::onDidChange, ::onDidStopChanging, and ::getChangesSinceCheckpoint. These methods report aggregated buffer updates as arrays of change objects containing the following fields: oldRange, newRange, oldText, and newText. The oldText, newText, and newRange fields are self-explanatory, but the interepretation of oldRange is more nuanced:

The reported oldRange is the range of the replaced text in the original contents of the buffer irrespective of the spatial impact of any other reported change. So, for example, if you wanted to apply all the changes made in a transaction to a clone of the observed buffer, the easiest approach would be to apply the changes in reverse:

buffer1.onDidChange(([changes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/changes)) => {
  for (const {oldRange, newText} of changes.reverse()) {
    buffer2.setTextInRange(oldRange, newText)
  }
})

If you needed to apply the changes in the forwards order, you would need to incorporate the impact of preceding changes into the range passed to ::setTextInRange, as follows:

buffer1.onDidChange(([changes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/changes)) => {
  for (const {oldRange, newRange, newText} of changes) {
    const rangeToReplace = Range(
      newRange.start,
      newRange.start.traverse(oldRange.getExtent())
    )
    buffer2.setTextInRange(rangeToReplace, newText)
  }
})

Construction

.load(source, params)

Create a new buffer backed by the given file path.

Argument	Description
`source`	Either a String path to a local file or (experimentally) a file Object as described by the ::setFile method.
`params`	An Object with the following properties:
`encoding`	optional String The file’s encoding.
`shouldDestroyOnFileDelete`	optional A Function that returns a Boolean indicating whether the buffer should be destroyed if its file is deleted.

Return values
Returns a Promise that resolves with a TextBuffer instance.

.loadSync(filePath, params)

Create a new buffer backed by the given file path. For better performance, use {TextBuffer.load} instead.

Argument	Description
`filePath`	The String file path.
`params`	An Object with the following properties:
`encoding`	optional String The file’s encoding.
`shouldDestroyOnFileDelete`	optional A Function that returns a Boolean indicating whether the buffer should be destroyed if its file is deleted.

Return values
Returns a TextBuffer instance.

.deserialize(params)

Restore a TextBuffer based on an earlier state created using the TextBuffer::serialize method.

Argument	Description
`params`	An Object returned from TextBuffer::serialize

Return values
Returns a Promise that resolves with a TextBuffer instance.

::constructor(params)

Create a new buffer with the given params.

Argument	Description
`params`	Object or String of text
`text`	The initial String text of the buffer.
`shouldDestroyOnFileDelete`	A Function that returns a Boolean indicating whether the buffer should be destroyed if its file is deleted.

Event Subscription

::onWillChange(callback)

Invoke the given callback synchronously before the content of the buffer changes.

Because observers are invoked synchronously, it’s important not to perform any expensive operations via this method.

Argument	Description
`callback`	Function to be called when the buffer changes.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChange(callback)

Invoke the given callback synchronously when a transaction finishes with a list of all the changes in the transaction.

Argument	Description
`callback`	Function to be called when a transaction in which textual changes occurred is completed.
`event`	Object with the following keys:
`oldRange`	The smallest combined Range containing all of the old text.
`newRange`	The smallest combined Range containing all of the new text.
`changes`	Array of Objects summarizing the aggregated changes that occurred during the transaction. See Working With Aggregated Changes in the description of the TextBuffer class for details.
`oldRange`	The Range of the deleted text in the contents of the buffer as it existed before the batch of changes reported by this event.
`newRange`	The Range of the inserted text in the current contents of the buffer.
`oldText`	A String representing the deleted text.
`newText`	A String representing the inserted text.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeText()

This is now identical to ::onDidChange.

::onDidStopChanging(callback)

Invoke the given callback asynchronously following one or more changes after ::getStoppedChangingDelay milliseconds elapse without an additional change.

This method can be used to perform potentially expensive operations that don’t need to be performed synchronously. If you need to run your callback synchronously, use ::onDidChange instead.

Argument	Description
`callback`	Function to be called when the buffer stops changing.
`event`	Object with the following keys:
`changes`	An Array containing Objects summarizing the aggregated changes. See Working With Aggregated Changes in the description of the TextBuffer class for details.
`oldRange`	The Range of the deleted text in the contents of the buffer as it existed before the batch of changes reported by this event.
`newRange`	The Range of the inserted text in the current contents of the buffer.
`oldText`	A String representing the deleted text.
`newText`	A String representing the inserted text.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidConflict(callback)

Invoke the given callback when the in-memory contents of the buffer become in conflict with the contents of the file on disk.

Argument	Description
`callback`	Function to be called when the buffer enters conflict.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeModified(callback)

Invoke the given callback if the value of ::isModified changes.

Argument	Description
`callback`	Function to be called when ::isModified changes.
`modified`	Boolean indicating whether the buffer is modified.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidUpdateMarkers(callback)

Invoke the given callback when all marker ::onDidChange observers have been notified following a change to the buffer.

The order of events following a buffer change is as follows:

The text of the buffer is changed
All markers are updated accordingly, but their ::onDidChange observers are not notified.
TextBuffer::onDidChange observers are notified.
Marker::onDidChange observers are notified.
TextBuffer::onDidUpdateMarkers observers are notified.

Basically, this method gives you a way to take action after both a buffer change and all associated marker changes.

Argument	Description
`callback`	Function to be called after markers are updated.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidCreateMarker(callback)

Invoke the given callback when a marker is created.

Argument	Description
`callback`	Function to be called when a marker is created.
`marker`	Marker that was created.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangePath(callback)

Invoke the given callback when the value of ::getPath changes.

Argument	Description
`callback`	Function to be called when the path changes.
`path`	String representing the buffer’s current path on disk.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidChangeEncoding(callback)

Invoke the given callback when the value of ::getEncoding changes.

Argument	Description
`callback`	Function to be called when the encoding changes.
`encoding`	String character set encoding of the buffer.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillSave(callback)

Invoke the given callback before the buffer is saved to disk.

Argument	Description
`callback`	Function to be called before the buffer is saved. If this function returns a Promise, then the buffer will not be saved until the promise resolves.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidSave(callback)

Invoke the given callback after the buffer is saved to disk.

Argument	Description
`callback`	Function to be called after the buffer is saved.
`event`	Object with the following keys:
`path`	The path to which the buffer was saved.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidDelete(callback)

Invoke the given callback after the file backing the buffer is deleted.

Argument	Description
`callback`	Function to be called after the buffer is deleted.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillReload(callback)

Invoke the given callback before the buffer is reloaded from the contents of its file on disk.

Argument	Description
`callback`	Function to be called before the buffer is reloaded.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidReload(callback)

Invoke the given callback after the buffer is reloaded from the contents of its file on disk.

Argument	Description
`callback`	Function to be called after the buffer is reloaded.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onDidDestroy(callback)

Invoke the given callback when the buffer is destroyed.

Argument	Description
`callback`	Function to be called when the buffer is destroyed.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::onWillThrowWatchError(callback)

Invoke the given callback when there is an error in watching the file.

Argument	Description
`callback`	Function callback
`errorObject`	Object
`error`	Object the error object
`handle`	Function call this to indicate you have handled the error. The error will not be thrown if this function is called.

Return values
Returns a Disposable on which `.dispose()` can be called to unsubscribe.

::getStoppedChangingDelay()

Get the number of milliseconds that will elapse without a change before ::onDidStopChanging observers are invoked following a change.

Return values
Returns a Number.

File Details

::isModified()

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.

Return values
Returns a Boolean.

::isInConflict()

Determine if the in-memory contents of the buffer conflict with the on-disk contents of its associated file.

Return values
Returns a Boolean.

::getPath()

Get the path of the associated file.

Return values
Returns a String.

::setPath(filePath)

Set the path for the buffer’s associated file.

Argument	Description
`filePath`	A String representing the new file path

::setEncoding(encoding)

Sets the character set encoding for this buffer.

Argument	Description
`encoding`	The String encoding to use (default: ‘utf8’).

::getEncoding()

Return values
Returns the String encoding of this buffer.

::getUri()

Get the path of the associated file.

Return values
Returns a String.

Reading Text

::isEmpty()

Determine whether the buffer is empty.

Return values
Returns a Boolean.

::getText()

Get the entire text of the buffer. Avoid using this unless you know that the buffer’s text is reasonably short.

Return values
Returns a String.

::getTextInRange(range)

Get the text in a range.

Argument	Description
`range`	A Range

Return values
Returns a String

::getLines()

Get the text of all lines in the buffer, without their line endings.

Return values
Returns an Array of Strings.

::getLastLine()

Get the text of the last line of the buffer, without its line ending.

Return values
Returns a String.

::lineForRow(row)

Get the text of the line at the given 0-indexed row, without its line ending.

Argument	Description
`row`	A Number representing the row.

Return values
Returns a String.

::lineEndingForRow(row)

Get the line ending for the given 0-indexed row.

Argument	Description
`row`	A Number indicating the row.

Return values
Returns a String. The returned newline is represented as a literal string: `'\n'`, `'\r\n'`, or `''` for the last line of the buffer, which doesn’t end in a newline.

::lineLengthForRow(row)

Get the length of the line for the given 0-indexed row, without its line ending.

Argument	Description
`row`	A Number indicating the row.

Return values
Returns a Number.

::isRowBlank(row)

Determine if the given row contains only whitespace.

Argument	Description
`row`	A Number representing a 0-indexed row.

Return values
Returns a Boolean.

::previousNonBlankRow(startRow)

Given a row, find the first preceding row that’s not blank.

Argument	Description
`startRow`	A Number identifying the row to start checking at.

Return values
Returns a Number or `null` if there’s no preceding non-blank row.

::nextNonBlankRow(startRow)

Given a row, find the next row that’s not blank.

Argument	Description
`startRow`	A Number identifying the row to start checking at.

Return values
Returns a Number or `null` if there’s no next non-blank row.

Extended Methods

::hasAstral()

Return true if the buffer contains any astral-plane Unicode characters that are encoded as surrogate pairs.

Return values
Returns a Boolean.

Mutating Text

::setText(text)

Replace the entire contents of the buffer with the given text.

Argument	Description
`text`	A String

Return values
Returns a Range spanning the new buffer contents.

::setTextViaDiff(text)

Replace the current buffer contents by applying a diff based on the given text.

Argument	Description
`text`	A String containing the new buffer contents.

::setTextInRange(range, text, options)

Set the text in the given range.

Argument	Description
`range`	A Range
`text`	A String
`options`	optional Object
`normalizeLineEndings`	optional Boolean (default: true)
`undo`	optional Deprecated String ‘skip’ will cause this change to be grouped with the preceding change for the purposes of undo and redo. This property is deprecated. Call groupLastChanges() on the buffer after instead.

Return values
Returns the Range of the inserted text.

::insert(position, text, options)

Insert text at the given position.

Argument	Description
`position`	A Point representing the insertion location. The position is clipped before insertion.
`text`	A String representing the text to insert.
`options`	optional Object
`normalizeLineEndings`	optional Boolean (default: true)
`undo`	optional Deprecated String ‘skip’ will skip the undo system. This property is deprecated. Call groupLastChanges() on the TextBuffer afterward instead.

Return values
Returns the Range of the inserted text.

::append(text, options)

Append text to the end of the buffer.

Argument	Description
`text`	A String representing the text text to append.
`options`	optional Object
`normalizeLineEndings`	optional Boolean (default: true)
`undo`	optional Deprecated String ‘skip’ will skip the undo system. This property is deprecated. Call groupLastChanges() on the TextBuffer afterward instead.

Return values
Returns the Range of the inserted text

::delete(range)

Delete the text in the given range.

Argument	Description
`range`	A Range in which to delete. The range is clipped before deleting.

Return values
Returns an empty Range starting at the start of deleted range.

::deleteRow(row)

Delete the line associated with a specified 0-indexed row.

Argument	Description
`row`	A Number representing the row to delete.

Return values
Returns the Range of the deleted text.

::deleteRows(startRow, endRow)

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.

Argument	Description
`startRow`	A Number representing the first row to delete.
`endRow`	A Number representing the last row to delete, inclusive.

Return values
Returns the Range of the deleted text.

Markers

::addMarkerLayer(options)

Create a layer to contain a set of related markers.

Argument	Description
`options`	optional An Object contaning the following keys:
`maintainHistory`	optional A Boolean indicating whether or not the state of this layer should be restored on undo/redo operations. Defaults to `false`.
`persistent`	optional A Boolean indicating whether or not this marker layer should be serialized and deserialized along with the rest of the buffer. Defaults to `false`. If `true`, the marker layer’s id will be maintained across the serialization boundary, allowing you to retrieve it via ::getMarkerLayer.
`role`	optional A String indicating role of this marker layer

Return values
Returns a MarkerLayer.

::getMarkerLayer(id)

Get a MarkerLayer by id.

Argument	Description
`id`	The id of the marker layer to retrieve.

Return values
Returns a MarkerLayer or `undefined` if no layer exists with the given id.

::getDefaultMarkerLayer()

Get the default MarkerLayer.

All Marker APIs not tied to an explicit layer interact with this default layer.

Return values
Returns a MarkerLayer.

::markRange(range, properties)

Create a Marker with the given range in the default MarkerLayer. This marker will maintain its logical location as the buffer is changed, so if you mark a particular word, the marker will remain over that word even if the word’s location in the buffer changes.

Argument	Description
`range`	A Range or range-compatible Array
`properties`	optional A hash of key-value pairs to associate with the marker. There are also reserved property names that have marker-specific meaning.
`reversed`	optional Boolean Creates the marker in a reversed orientation. (default: false)
`invalidate`	optional String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of fragility: never: The marker is never marked as invalid. This is a good choice for markers representing selections in an editor. surround: The marker is invalidated by changes that completely surround it. overlap: The marker is invalidated by changes that surround the start or end of the marker. This is the default. inside: The marker is invalidated by changes that extend into the inside of the marker. Changes that end at the marker’s start or start at the marker’s end do not invalidate the marker. touch: The marker is invalidated by a change that touches the marked region in any way, including changes that end at the marker’s start or start at the marker’s end. This is the most fragile strategy.
`exclusive`	optional Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to `false`, except when using the `inside` invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.

Return values
Returns a Marker.

::markPosition(position, options)

Create a Marker at the given position with no tail in the default marker layer.

Argument	Description
`position`	Point or point-compatible Array
`options`	optional An Object with the following keys:
`invalidate`	optional String Determines the rules by which changes to the buffer invalidate the marker. (default: ‘overlap’) It can be any of the following strategies, in order of fragility: never: The marker is never marked as invalid. This is a good choice for markers representing selections in an editor. surround: The marker is invalidated by changes that completely surround it. overlap: The marker is invalidated by changes that surround the start or end of the marker. This is the default. inside: The marker is invalidated by changes that extend into the inside of the marker. Changes that end at the marker’s start or start at the marker’s end do not invalidate the marker. touch: The marker is invalidated by a change that touches the marked region in any way, including changes that end at the marker’s start or start at the marker’s end. This is the most fragile strategy.
`exclusive`	optional Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to `false`, except when using the `inside` invalidation strategy or when when the marker has no tail, in which case it defaults to true. Explicitly assigning this option overrides behavior in all circumstances.

Return values
Returns a Marker.

::getMarkers()

Get all existing markers on the default marker layer.

Return values
Returns an Array of Markers.

::getMarker(id)

Get an existing marker by its id from the default marker layer.

Argument	Description
`id`	Number id of the marker to retrieve

Return values
Returns a Marker.

::findMarkers(params)

Find markers conforming to the given parameters in the default marker layer.

Markers are sorted based on their position in the buffer. If two markers start at the same position, the larger marker comes first.

Argument	Description
`params`	A hash of key-value pairs constraining the set of returned markers. You can query against custom marker properties by listing the desired key-value pairs here. In addition, the following keys are reserved and have special semantics:
`startPosition`	Only include markers that start at the given Point.
`endPosition`	Only include markers that end at the given Point.
`startsInRange`	Only include markers that start inside the given Range.
`endsInRange`	Only include markers that end inside the given Range.
`containsPoint`	Only include markers that contain the given Point, inclusive.
`containsRange`	Only include markers that contain the given Range, inclusive.
`startRow`	Only include markers that start at the given row Number.
`endRow`	Only include markers that end at the given row Number.
`intersectsRow`	Only include markers that intersect the given row Number.

Return values
Returns an Array of Markers.

::getMarkerCount()

Get the number of markers in the default marker layer.

Return values
Returns a Number.

History

::undo(options)

Undo the last operation. If a transaction is in progress, aborts it.

Argument	Description
`options`	optional Object
`selectionsMarkerLayer`	optional Restore snapshot of selections marker layer to given selectionsMarkerLayer.

Return values
Returns a Boolean of whether or not a change was made.

::redo(options)

Redo the last operation

Argument	Description
`options`	optional Object
`selectionsMarkerLayer`	optional Restore snapshot of selections marker layer to given selectionsMarkerLayer.

Return values
Returns a Boolean of whether or not a change was made.

::transact(options, groupingInterval, fn)

Batch multiple operations as a single undo/redo step.

Any group of operations that are logically grouped from the perspective of undoing and redoing should be performed in a transaction. If you want to abort the transaction, call ::abortTransaction to terminate the function’s execution and revert any changes performed up to the abortion.

Argument	Description
`options`	optional Object
`groupingInterval`	optional The Number of milliseconds for which this transaction should be considered ‘open for grouping’ after it begins. If a transaction with a positive `groupingInterval` is committed while the previous transaction is still open for grouping, the two transactions are merged with respect to undo and redo.
`selectionsMarkerLayer`	optional When provided, skip taking snapshot for other selections markerLayers except given one.
`groupingInterval`	optional The Number of milliseconds for which this transaction should be considered ‘open for grouping’ after it begins. If a transaction with a positive `groupingInterval` is committed while the previous transaction is still open for grouping, the two transactions are merged with respect to undo and redo.
`fn`	A Function to call inside the transaction.

::abortTransaction()

Abort the currently running transaction

Only intended to be called within the fn option to ::transact

::clearUndoStack()

Clear the undo stack.

::createCheckpoint(options)

Create a pointer to the current state of the buffer for use with ::revertToCheckpoint and ::groupChangesSinceCheckpoint.

Argument	Description
`options`	optional Object
`selectionsMarkerLayer`	optional When provided, skip taking snapshot for other selections markerLayers except given one.

Return values
Returns a checkpoint id value.

::revertToCheckpoint(checkpoint, options)

Revert the buffer to the state it was in when the given checkpoint was created.

The redo stack will be empty following this operation, so changes since the checkpoint will be lost. If the given checkpoint is no longer present in the undo history, no changes will be made to the buffer and this method will return false.

Argument	Description
`checkpoint`	Number id of the checkpoint to revert to.
`options`	optional Object
`selectionsMarkerLayer`	optional Restore snapshot of selections marker layer to given selectionsMarkerLayer.

Return values
Returns a Boolean indicating whether the operation succeeded.

::groupChangesSinceCheckpoint(checkpoint, options)

Group all changes since the given checkpoint into a single transaction for purposes of undo/redo.

If the given checkpoint is no longer present in the undo history, no grouping will be performed and this method will return false.

Argument	Description
`checkpoint`	Number id of the checkpoint to group changes since.
`options`	optional Object
`selectionsMarkerLayer`	optional When provided, skip taking snapshot for other selections markerLayers except given one.

Return values
Returns a Boolean indicating whether the operation succeeded.

::groupLastChanges()

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 values
Returns a Boolean indicating whether the operation succeeded.

::getChangesSinceCheckpoint(checkpoint)

If the given checkpoint is no longer present in the undo history, this method will return an empty Array.

Argument	Description
`checkpoint`	Number id of the checkpoint to get changes since.

Return values

Returns a list of changes since the given checkpoint.

Returns an Array of Objects with the following fields that summarize the aggregated changes since the checkpoint. See Working With Aggregated Changes in the description of the TextBuffer class for details.

oldRange The Range of the deleted text in the text as it existed when the checkpoint was created.
newRange: The Range of the inserted text in the current text.
oldText: A String representing the deleted text.
newText: A String representing the inserted text.

Search And Replace

::scan(regex, options, iterator)

Scan regular expression matches in the entire buffer, calling the given iterator function on each match.

If you’re programmatically modifying the results, you may want to try ::backwardsScan to avoid tripping over your own changes.

Argument	Description
`regex`	A RegExp to search for.
`options`	optional Object
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`iterator`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.
`leadingContextLines`	An Array with `leadingContextLineCount` lines before the match.
`trailingContextLines`	An Array with `trailingContextLineCount` lines after the match.

::backwardsScan(regex, options, iterator)

Scan regular expression matches in the entire buffer in reverse order, calling the given iterator function on each match.

Argument	Description
`regex`	A RegExp to search for.
`options`	optional Object
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`iterator`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.
`leadingContextLines`	An Array with `leadingContextLineCount` lines before the match.
`trailingContextLines`	An Array with `trailingContextLineCount` lines after the match.

::scanInRange(regex, range, options, callback)

Scan regular expression matches in a given range , calling the given iterator function on each match.

Argument	Description
`regex`	A RegExp to search for.
`range`	A Range in which to search.
`options`	optional Object
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`callback`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.
`leadingContextLines`	An Array with `leadingContextLineCount` lines before the match.
`trailingContextLines`	An Array with `trailingContextLineCount` lines after the match.

::backwardsScanInRange(regex, range, options, iterator)

Scan regular expression matches in a given range in reverse order, calling the given iterator function on each match.

Argument	Description
`regex`	A RegExp to search for.
`range`	A Range in which to search.
`options`	optional Object
`leadingContextLineCount`	Number default `0`; The number of lines before the matched line to include in the results object.
`trailingContextLineCount`	Number default `0`; The number of lines after the matched line to include in the results object.
`iterator`	A Function that’s called on each match with an Object containing the following keys:
`match`	The current regular expression match.
`matchText`	A String with the text of the match.
`range`	The Range of the match.
`stop`	Call this Function to terminate the scan.
`replace`	Call this Function with a String to replace the match.

::replace(regex, replacementText)

Replace all regular expression matches in the entire buffer.

Argument	Description
`regex`	A RegExp representing the matches to be replaced.
`replacementText`	A String representing the text to replace each match.

Return values
Returns a Number representing the number of replacements made.

Buffer Range Details

::getRange()

Get the range spanning from [0, 0] to ::getEndPosition.

Return values
Returns a Range.

::getLineCount()

Get the number of lines in the buffer.

Return values
Returns a Number.

::getLastRow()

Get the last 0-indexed row in the buffer.

Return values
Returns a Number.

::getFirstPosition()

Get the first position in the buffer, which is always [0, 0].

Return values
Returns a Point.

::getEndPosition()

Get the maximal position in the buffer, where new text would be appended.

Return values
Returns a Point.

::getLength()

Get the length of the buffer’s text.

::getMaxCharacterIndex()

Get the length of the buffer in characters.

Return values
Returns a Number.

::rangeForRow(row, includeNewline)

Get the range for the given row

Argument	Description
`row`	A Number representing a 0-indexed row.
`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`)

Return values
Returns a Range.

::characterIndexForPosition(position)

Convert a position in the buffer in row/column coordinates to an absolute character offset, inclusive of line ending characters.

The position is clipped prior to translating.

Argument	Description
`position`	A Point or point-compatible Array.

Return values
Returns a Number.

::positionForCharacterIndex(offset)

Convert an absolute character offset, inclusive of newlines, to a position in the buffer in row/column coordinates.

The offset is clipped prior to translating.

Argument	Description
`offset`	A Number.

Return values
Returns a Point.

::clipRange(range)

Clip the given range so it starts and ends at valid positions.

For example, the position [1, 100] is out of bounds if the line at row 1 is only 10 characters long, and it would be clipped to (1, 10).

Argument	Description
`range`	A Range or range-compatible Array to clip.

Return values
Returns the given Range if it is already in bounds, or a new clipped Range if the given range is out-of-bounds.

::clipPosition(position)

Clip the given point so it is at a valid position in the buffer.

For example, the position (1, 100) is out of bounds if the line at row 1 is only 10 characters long, and it would be clipped to (1, 10)

Argument	Description
`position`	A Point or point-compatible Array.

Return values
Returns a new Point if the given position is invalid, otherwise returns the given position.

Buffer Operations

::save()

Save the buffer.

Return values
Returns a Promise that resolves when the save has completed.

::saveAs(filePath)

Save the buffer at a specific path.

Argument	Description
`filePath`	The path to save at.

Return values
Returns a Promise that resolves when the save has completed.

::reload()

Reload the file’s content from disk.

Return values
Returns a Promise that resolves when the load is complete.