TextBuffer

Description

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

API documentation

Construction

::constructor(params)

Create a new buffer with the given params.

Argument Description
params

Object or String of text
load

A Boolean, true to asynchronously load the buffer from disk after initialization.
text

The initial String text of the buffer.

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.
event

Object with the following keys:
oldRange

Range of the old text.
newRange

Range of the new text.
oldText

String containing the text that was replaced.
newText

String containing the text that was inserted.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidChange(callback)

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

Because observers are invoked synchronously, it's important not to perform any expensive operations via this method. Consider TextBuffer::onDidStopChanging to delay expensive operations until after changes stop occurring.

Argument Description
callback

Function to be called when the buffer changes.
event

Object with the following keys:
oldRange

Range of the old text.
newRange

Range of the new text.
oldText

String containing the text that was replaced.
newText

String containing the text that was inserted.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidStopChanging(callback)

Invoke the given callback asynchronously following one or more changes after TextBuffer::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 TextBuffer::onDidChange instead.

Argument Description
callback

Function to be called when the buffer stops changing.
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 the value of TextBuffer::isModified changes.

Argument Description
callback

Function to be called when TextBuffer::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 TextBuffer::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 TextBuffer::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.
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 TextBuffer::onDidStopChanging observers are invoked following a change.

Return values

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

::isInConflict()

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

Return values

::getPath()

Get the path of the associated file.

Return values

::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

Reading Text

::isEmpty()

Determine whether the buffer is empty.

Return values

::getText()

Get the entire text of the buffer.

Return values

::getTextInRange(range)

Get the text in a range.

Argument Description
range

A Range
Return values

::getLines()

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

Return values

::getLastLine()

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

Return values

::lineForRow(row)

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

Argument Description
row

A Number representing a 0-indexed row.
Return values

::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', '\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

::isRowBlank(row)

Determine if the given row contains only whitespace.

Argument Description
row

A Number representing a 0-indexed row.
Return values

::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.

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

String 'skip' will skip the undo system
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

String 'skip' will skip the undo system
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

String 'skip' will skip the undo system
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 row.

Argument Description
row

A Number representing the 0-indexed row to delete.
Return values

  • Returns the Range of the deleted text.

::deleteRows(startRow, endRow)

Delete the lines associated with the specified row range.

If the row range is out of bounds, it will be clipped. If the startRow is greater than the end row, 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

::markRange(range, properties)

Create a marker with the given range. 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

A hash of key-value pairs to associate with the marker. There are also reserved property names that have marker-specific meaning.
reversed optional

Creates the marker in a reversed orientation. (default: false)
persistent optional

Whether to include this marker when serializing the buffer. (default: true)
invalidate optional

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.
Return values

::markPosition(position, properties)

Create a marker at the given position with no tail.

Argument Description
position

Point or point-compatible Array
properties

This is the same as the properties parameter in TextBuffer::markRange
Return values

::getMarkers()

Get all existing markers on the buffer.

Return values

::getMarker(id)

Get an existing marker by its id.

Argument Description
id

Number id of the marker to retrieve
Return values

::findMarkers(params)

Find markers conforming to the given parameters.

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.
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

::getMarkerCount()

Get the number of markers in the buffer.

Return values

History

::undo()

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

::redo()

Redo the last operation

::transact(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 TextBuffer::abortTransaction to terminate the function's execution and revert any changes performed up to the abortion.

Argument Description
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.

::clearUndoStack()

Clear the undo stack.

::createCheckpoint()

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

Return values

  • Returns a checkpoint value.

::revertToCheckpoint()

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.

Return values

  • Returns a Boolean indicating whether the operation succeeded.

::groupChangesSinceCheckpoint()

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.

Return values

  • Returns a Boolean indicating whether the operation succeeded.

Search And Replace

::scan(regex, 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 TextBuffer::backwardsScan to avoid tripping over your own changes.

Argument Description
regex

A RegExp to search for.
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.

::backwardsScan(regex, 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.
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.

::scanInRange(regex, range, iterator)

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.
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.

::backwardsScanInRange(regex, range, 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.
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 TextBuffer::getEndPosition.

Return values

::getLineCount()

Get the number of lines in the buffer.

Return values

::getLastRow()

Get the last 0-indexed row in the buffer.

Return values

::getFirstPosition()

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

Return values

::getEndPosition()

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

Return values

::getMaxCharacterIndex()

Get the length of the buffer in characters.

Return values

::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.
Return values

::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.
Return values

::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

::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.

::saveAs(filePath)

Save the buffer at a specific path.

Argument Description
filePath

The path to save at.

::reload()

Reload the buffer's contents from disk.

Sets the buffer's content to the cached disk contents