A mutable text container with undo/redo support and the ability to annotate logical regions in the text.
Create a new buffer with the given params.
Argument | Description |
---|---|
|
|
|
A Boolean, |
|
The initial String text of the buffer. |
|
A Function that returns a Boolean indicating whether the buffer should be destroyed if its file is deleted. |
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 |
---|---|
|
Function to be called when the buffer changes. |
|
Object with the following keys: |
|
Range of the old text. |
|
Range of the new text. |
|
String containing the text that was replaced. |
|
String containing the text that was inserted. |
Return values |
---|
Returns a Disposable on which |
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 ::onDidStopChanging to delay expensive operations until after changes stop occurring.
Argument | Description |
---|---|
|
Function to be called when the buffer changes. |
|
Object with the following keys: |
|
Range of the old text. |
|
Range of the new text. |
|
String containing the text that was replaced. |
|
String containing the text that was inserted. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called when the buffer stops changing. |
Return values |
---|
Returns a Disposable on which |
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 |
---|---|
|
Function to be called when the buffer enters conflict. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback if the value of ::isModified changes.
Argument | Description |
---|---|
|
Function to be called when ::isModified changes. |
|
Boolean indicating whether the buffer is modified. |
Return values |
---|
Returns a Disposable on which |
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:
::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 |
---|---|
|
Function to be called after markers are updated. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when a marker is created.
Argument | Description |
---|---|
|
Function to be called when a marker is created. |
|
Marker that was created. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when the value of ::getPath changes.
Argument | Description |
---|---|
|
Function to be called when the path changes. |
|
String representing the buffer’s current path on disk. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when the value of ::getEncoding changes.
Argument | Description |
---|---|
|
Function to be called when the encoding changes. |
|
String character set encoding of the buffer. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback before the buffer is saved to disk.
Argument | Description |
---|---|
|
Function to be called before the buffer is saved. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback after the buffer is saved to disk.
Argument | Description |
---|---|
|
Function to be called after the buffer is saved. |
|
Object with the following keys: |
|
The path to which the buffer was saved. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback after the file backing the buffer is deleted.
Argument | Description |
---|---|
|
Function to be called after the buffer is deleted. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback before the buffer is reloaded from the contents of its file on disk.
Argument | Description |
---|---|
|
Function to be called before the buffer is reloaded. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback after the buffer is reloaded from the contents of its file on disk.
Argument | Description |
---|---|
|
Function to be called after the buffer is reloaded. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when the buffer is destroyed.
Argument | Description |
---|---|
|
Function to be called when the buffer is destroyed. |
Return values |
---|
Returns a Disposable on which |
Invoke the given callback when there is an error in watching the file.
Argument | Description |
---|---|
|
Function callback |
|
|
|
Object the error object |
|
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 |
Get the number of milliseconds that will elapse without a change before ::onDidStopChanging observers are invoked following a change.
Return values |
---|
Returns a Number. |
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. |
Determine if the in-memory contents of the buffer conflict with the on-disk contents of its associated file.
Return values |
---|
Returns a Boolean. |
Set the path for the buffer’s associated file.
Argument | Description |
---|---|
|
A String representing the new file path |
Sets the character set encoding for this buffer.
Argument | Description |
---|---|
|
The String encoding to use (default: ‘utf8’). |
Get the text of the last line of the buffer, without its line ending.
Return values |
---|
Returns a String. |
Replace the current buffer contents by applying a diff based on the given text.
Argument | Description |
---|---|
|
A String containing the new buffer contents. |
Insert text at the given position.
Argument | Description |
---|---|
|
A Point representing the insertion location. The position is clipped before insertion. |
|
A String representing the text to insert. |
|
optional |
|
optional
Boolean (default: true) |
|
optional
String ‘skip’ will skip the undo system |
Return values |
---|
Returns the Range of the inserted text. |
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 |
---|---|
|
A Number representing the first row to delete. |
|
A Number representing the last row to delete, inclusive. |
Return values |
---|
Returns the Range of the deleted text. |
Create a layer to contain a set of related markers.
Argument | Description |
---|---|
|
An object contaning the following keys: |
|
A Boolean indicating whether or not the state of this layer should be restored on undo/redo operations. Defaults to |
|
A Boolean indicating whether or not this marker layer should be serialized and deserialized along with the rest of the buffer. Defaults to |
Return values |
---|
Returns a MarkerLayer. |
Get a MarkerLayer by id.
Argument | Description |
---|---|
|
The id of the marker layer to retrieve. |
Return values |
---|
Returns a MarkerLayer or `` if no layer exists with the given id. |
Get the default MarkerLayer.
All marker APIs not tied to an explicit layer interact with this default layer.
Return values |
---|
Returns a MarkerLayer. |
Create a marker with the given range in the default marker layer. 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 |
---|---|
|
|
|
A hash of key-value pairs to associate with the marker. There are also reserved property names that have marker-specific meaning. |
|
optional
Boolean Creates the marker in a reversed orientation. (default: false) |
|
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:
|
|
Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to |
Return values |
---|
Returns a Marker. |
Create a marker at the given position with no tail in the default marker layer.
Argument | Description |
---|---|
|
|
|
optional
An Object with the following keys: |
|
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:
|
|
Boolean indicating whether insertions at the start or end of the marked range should be interpreted as happening outside the marker. Defaults to |
Return values |
---|
Returns a Marker. |
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 |
---|---|
|
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: |
|
Only include markers that start at the given Point. |
|
Only include markers that end at the given Point. |
|
Only include markers that contain the given Point, inclusive. |
|
Only include markers that contain the given Range, inclusive. |
|
Only include markers that start at the given row Number. |
|
Only include markers that end at the given row Number. |
|
Only include markers that intersect the given row Number. |
Return values |
---|
Undo the last operation. If a transaction is in progress, aborts it.
Redo the last operation
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 |
---|---|
|
optional
The Number of milliseconds for which this transaction should be considered ‘open for grouping’ after it begins. If a transaction with a positive |
|
A Function to call inside the transaction. |
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.
Create a pointer to the current state of the buffer for use with ::revertToCheckpoint and ::groupChangesSinceCheckpoint.
Return values |
---|
Returns a checkpoint value. |
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. |
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. |
If the given checkpoint is no longer present in the undo history, this method will return an empty Array.
Return values |
---|
Returns a list of changes since the given checkpoint. |
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 |
---|---|
|
A RegExp to search for. |
|
A Function that’s called on each match with an Object containing the following keys: |
|
The current regular expression match. |
|
A String with the text of the match. |
|
The Range of the match. |
|
Call this Function to terminate the scan. |
|
Scan regular expression matches in the entire buffer in reverse order, calling the given iterator function on each match.
Argument | Description |
---|---|
|
A RegExp to search for. |
|
A Function that’s called on each match with an Object containing the following keys: |
|
The current regular expression match. |
|
A String with the text of the match. |
|
The Range of the match. |
|
Call this Function to terminate the scan. |
|
Scan regular expression matches in a given range , calling the given iterator function on each match.
Argument | Description |
---|---|
|
A RegExp to search for. |
|
A Range in which to search. |
|
A Function that’s called on each match with an Object containing the following keys: |
|
The current regular expression match. |
|
A String with the text of the match. |
|
The Range of the match. |
|
Call this Function to terminate the scan. |
|
Scan regular expression matches in a given range in reverse order, calling the given iterator function on each match.
Argument | Description |
---|---|
|
A RegExp to search for. |
|
A Range in which to search. |
|
A Function that’s called on each match with an Object containing the following keys: |
|
The current regular expression match. |
|
A String with the text of the match. |
|
The Range of the match. |
|
Call this Function to terminate the scan. |
|
Get the maximal position in the buffer, where new text would be appended.
Return values |
---|
Returns a Point. |
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 |
---|---|
|
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. |
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 |
---|---|
|
Return values |
---|
Returns a new Point if the given position is invalid, otherwise returns the given position. |
Save the buffer.
Save the buffer at a specific path.
Argument | Description |
---|---|
|
The path to save at. |
Reload the buffer’s contents from disk.
Sets the buffer’s content to the cached disk contents