Chapter 1: Getting Started

Chapter 2: Using Atom

Chapter 3: Hacking Atom

Chapter 4: Behind Atom

Reference: API

Appendix A: Resources

Appendix B: FAQ

Appendix C: Shadow DOM

Appendix D: Upgrading to 1.0 APIs

Appendix E: Atom server-side APIs

TextBuffer Extended

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

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

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 row, without its line ending.

Argument Description

row

A Number representing a 0-indexed 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', '\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.

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

::addMarkerLayer(options)

Experimental: Create a layer to contain a set of related markers.

This API is experimental and subject to change on any release.

Argument Description

options

An object contaning the following keys:

maintainHistory

A Boolean indicating whether or not the state of this layer should be restored on undo/redo operations. Defaults to false.
Return values

Returns a MarkerLayer.

::getMarkerLayer(id)

Experimental: Get a MarkerLayer by id.

This API is experimental and subject to change on any release.

Argument Description

id

The id of the marker layer to retrieve.
Return values

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

::getDefaultMarkerLayer()

Experimental: Get the default MarkerLayer.

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

This API is experimental and subject to change on any release.

Return values

Returns a MarkerLayer.

::markRange(range, properties)

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

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

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

persistent

 optional

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

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

Returns a Marker.

::markPosition(position, properties)

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

Argument Description

position

Point or point-compatible Array

properties

This is the same as the properties parameter in ::markRange
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.

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()

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 ::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. When calling this method within a transaction, the ::onDidChangeText event will not be triggered because the information describing the changes is lost.

::createCheckpoint()

Create a pointer to the current state of the buffer for use with ::revertToCheckpoint and ::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.

::getChangesSinceCheckpoint()

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.

Returns an Array containing the following change Objects:

  • start A Point representing where the change started.
  • oldExtent A Point representing the replaced extent.
  • newExtent: A Point representing the replacement extent.
  • newText: A String representing the replacement text.

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

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

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