src/cursor.js
const { Point, Range } = require('text-buffer');
const { Emitter } = require('event-kit');
const _ = require('underscore-plus');
const Model = require('./model');
const EmptyLineRegExp = /(\r\n[\t ]*\r\n)|(\n[\t ]*\n)/g;
// Extended: The `Cursor` class represents the little blinking line identifying
// where text can be inserted.
//
// Cursors belong to {TextEditor}s and have some metadata attached in the form
// of a {DisplayMarker}.
module.exports = class Cursor extends Model {
// Instantiated by a {TextEditor}
constructor(params) {
super(params);
this.editor = params.editor;
this.marker = params.marker;
this.emitter = new Emitter();
}
destroy() {
this.marker.destroy();
}
/*
Section: Event Subscription
*/
// Public: Calls your `callback` when the cursor has been moved.
//
// * `callback` {Function}
// * `event` {Object}
// * `oldBufferPosition` {Point}
// * `oldScreenPosition` {Point}
// * `newBufferPosition` {Point}
// * `newScreenPosition` {Point}
// * `textChanged` {Boolean}
// * `cursor` {Cursor} that triggered the event
//
// Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidChangePosition(callback) {
return this.emitter.on('did-change-position', callback);
}
// Public: Calls your `callback` when the cursor is destroyed
//
// * `callback` {Function}
//
// Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
onDidDestroy(callback) {
return this.emitter.once('did-destroy', callback);
}
/*
Section: Managing Cursor Position
*/
// Public: Moves a cursor to a given screen position.
//
// * `screenPosition` {Array} of two numbers: the screen row, and the screen column.
// * `options` (optional) {Object} with the following keys:
// * `autoscroll` A Boolean which, if `true`, scrolls the {TextEditor} to wherever
// the cursor moves to.
setScreenPosition(screenPosition, options = {}) {
this.changePosition(options, () => {
this.marker.setHeadScreenPosition(screenPosition, options);
});
}
// Public: Returns the screen position of the cursor as a {Point}.
getScreenPosition() {
return this.marker.getHeadScreenPosition();
}
// Public: Moves a cursor to a given buffer position.
//
// * `bufferPosition` {Array} of two numbers: the buffer row, and the buffer column.
// * `options` (optional) {Object} with the following keys:
// * `autoscroll` {Boolean} indicating whether to autoscroll to the new
// position. Defaults to `true` if this is the most recently added cursor,
// `false` otherwise.
setBufferPosition(bufferPosition, options = {}) {
this.changePosition(options, () => {
this.marker.setHeadBufferPosition(bufferPosition, options);
});
}
// Public: Returns the current buffer position as an Array.
getBufferPosition() {
return this.marker.getHeadBufferPosition();
}
// Public: Returns the cursor's current screen row.
getScreenRow() {
return this.getScreenPosition().row;
}
// Public: Returns the cursor's current screen column.
getScreenColumn() {
return this.getScreenPosition().column;
}
// Public: Retrieves the cursor's current buffer row.
getBufferRow() {
return this.getBufferPosition().row;
}
// Public: Returns the cursor's current buffer column.
getBufferColumn() {
return this.getBufferPosition().column;
}
// Public: Returns the cursor's current buffer row of text excluding its line
// ending.
getCurrentBufferLine() {
return this.editor.lineTextForBufferRow(this.getBufferRow());
}
// Public: Returns whether the cursor is at the start of a line.
isAtBeginningOfLine() {
return this.getBufferPosition().column === 0;
}
// Public: Returns whether the cursor is on the line return character.
isAtEndOfLine() {
return this.getBufferPosition().isEqual(
this.getCurrentLineBufferRange().end
);
}
/*
Section: Cursor Position Details
*/
// Public: Returns the underlying {DisplayMarker} for the cursor.
// Useful with overlay {Decoration}s.
getMarker() {
return this.marker;
}
// Public: Identifies if the cursor is surrounded by whitespace.
//
// "Surrounded" here means that the character directly before and after the
// cursor are both whitespace.
//
// Returns a {Boolean}.
isSurroundedByWhitespace() {
const { row, column } = this.getBufferPosition();
const range = [[row, column - 1], [row, column + 1]];
return /^\s+$/.test(this.editor.getTextInBufferRange(range));
}
// Public: Returns whether the cursor is currently between a word and non-word
// character. The non-word characters are defined by the
// `editor.nonWordCharacters` config value.
//
// This method returns false if the character before or after the cursor is
// whitespace.
//
// Returns a Boolean.
isBetweenWordAndNonWord() {
if (this.isAtBeginningOfLine() || this.isAtEndOfLine()) return false;
const { row, column } = this.getBufferPosition();
const range = [[row, column - 1], [row, column + 1]];
const text = this.editor.getTextInBufferRange(range);
if (/\s/.test(text[0]) || /\s/.test(text[1])) return false;
const nonWordCharacters = this.getNonWordCharacters();
return (
nonWordCharacters.includes(text[0]) !==
nonWordCharacters.includes(text[1])
);
}
// Public: Returns whether this cursor is between a word's start and end.
//
// * `options` (optional) {Object}
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp}).
//
// Returns a {Boolean}
isInsideWord(options) {
const { row, column } = this.getBufferPosition();
const range = [[row, column], [row, Infinity]];
const text = this.editor.getTextInBufferRange(range);
return (
text.search((options && options.wordRegex) || this.wordRegExp()) === 0
);
}
// Public: Returns the indentation level of the current line.
getIndentLevel() {
if (this.editor.getSoftTabs()) {
return this.getBufferColumn() / this.editor.getTabLength();
} else {
return this.getBufferColumn();
}
}
// Public: Retrieves the scope descriptor for the cursor's current position.
//
// Returns a {ScopeDescriptor}
getScopeDescriptor() {
return this.editor.scopeDescriptorForBufferPosition(
this.getBufferPosition()
);
}
// Public: Retrieves the syntax tree scope descriptor for the cursor's current position.
//
// Returns a {ScopeDescriptor}
getSyntaxTreeScopeDescriptor() {
return this.editor.syntaxTreeScopeDescriptorForBufferPosition(
this.getBufferPosition()
);
}
// Public: Returns true if this cursor has no non-whitespace characters before
// its current position.
hasPrecedingCharactersOnLine() {
const bufferPosition = this.getBufferPosition();
const line = this.editor.lineTextForBufferRow(bufferPosition.row);
const firstCharacterColumn = line.search(/\S/);
if (firstCharacterColumn === -1) {
return false;
} else {
return bufferPosition.column > firstCharacterColumn;
}
}
// Public: Identifies if this cursor is the last in the {TextEditor}.
//
// "Last" is defined as the most recently added cursor.
//
// Returns a {Boolean}.
isLastCursor() {
return this === this.editor.getLastCursor();
}
/*
Section: Moving the Cursor
*/
// Public: Moves the cursor up one screen row.
//
// * `rowCount` (optional) {Number} number of rows to move (default: 1)
// * `options` (optional) {Object} with the following keys:
// * `moveToEndOfSelection` if true, move to the left of the selection if a
// selection exists.
moveUp(rowCount = 1, { moveToEndOfSelection } = {}) {
let row, column;
const range = this.marker.getScreenRange();
if (moveToEndOfSelection && !range.isEmpty()) {
({ row, column } = range.start);
} else {
({ row, column } = this.getScreenPosition());
}
if (this.goalColumn != null) column = this.goalColumn;
this.setScreenPosition(
{ row: row - rowCount, column },
{ skipSoftWrapIndentation: true }
);
this.goalColumn = column;
}
// Public: Moves the cursor down one screen row.
//
// * `rowCount` (optional) {Number} number of rows to move (default: 1)
// * `options` (optional) {Object} with the following keys:
// * `moveToEndOfSelection` if true, move to the left of the selection if a
// selection exists.
moveDown(rowCount = 1, { moveToEndOfSelection } = {}) {
let row, column;
const range = this.marker.getScreenRange();
if (moveToEndOfSelection && !range.isEmpty()) {
({ row, column } = range.end);
} else {
({ row, column } = this.getScreenPosition());
}
if (this.goalColumn != null) column = this.goalColumn;
this.setScreenPosition(
{ row: row + rowCount, column },
{ skipSoftWrapIndentation: true }
);
this.goalColumn = column;
}
// Public: Moves the cursor left one screen column.
//
// * `columnCount` (optional) {Number} number of columns to move (default: 1)
// * `options` (optional) {Object} with the following keys:
// * `moveToEndOfSelection` if true, move to the left of the selection if a
// selection exists.
moveLeft(columnCount = 1, { moveToEndOfSelection } = {}) {
const range = this.marker.getScreenRange();
if (moveToEndOfSelection && !range.isEmpty()) {
this.setScreenPosition(range.start);
} else {
let { row, column } = this.getScreenPosition();
while (columnCount > column && row > 0) {
columnCount -= column;
column = this.editor.lineLengthForScreenRow(--row);
columnCount--; // subtract 1 for the row move
}
column = column - columnCount;
this.setScreenPosition({ row, column }, { clipDirection: 'backward' });
}
}
// Public: Moves the cursor right one screen column.
//
// * `columnCount` (optional) {Number} number of columns to move (default: 1)
// * `options` (optional) {Object} with the following keys:
// * `moveToEndOfSelection` if true, move to the right of the selection if a
// selection exists.
moveRight(columnCount = 1, { moveToEndOfSelection } = {}) {
const range = this.marker.getScreenRange();
if (moveToEndOfSelection && !range.isEmpty()) {
this.setScreenPosition(range.end);
} else {
let { row, column } = this.getScreenPosition();
const maxLines = this.editor.getScreenLineCount();
let rowLength = this.editor.lineLengthForScreenRow(row);
let columnsRemainingInLine = rowLength - column;
while (columnCount > columnsRemainingInLine && row < maxLines - 1) {
columnCount -= columnsRemainingInLine;
columnCount--; // subtract 1 for the row move
column = 0;
rowLength = this.editor.lineLengthForScreenRow(++row);
columnsRemainingInLine = rowLength;
}
column = column + columnCount;
this.setScreenPosition({ row, column }, { clipDirection: 'forward' });
}
}
// Public: Moves the cursor to the top of the buffer.
moveToTop() {
this.setBufferPosition([0, 0]);
}
// Public: Moves the cursor to the bottom of the buffer.
moveToBottom() {
const column = this.goalColumn;
this.setBufferPosition(this.editor.getEofBufferPosition());
this.goalColumn = column;
}
// Public: Moves the cursor to the beginning of the line.
moveToBeginningOfScreenLine() {
this.setScreenPosition([this.getScreenRow(), 0]);
}
// Public: Moves the cursor to the beginning of the buffer line.
moveToBeginningOfLine() {
this.setBufferPosition([this.getBufferRow(), 0]);
}
// Public: Moves the cursor to the beginning of the first character in the
// line.
moveToFirstCharacterOfLine() {
let targetBufferColumn;
const screenRow = this.getScreenRow();
const screenLineStart = this.editor.clipScreenPosition([screenRow, 0], {
skipSoftWrapIndentation: true
});
const screenLineEnd = [screenRow, Infinity];
const screenLineBufferRange = this.editor.bufferRangeForScreenRange([
screenLineStart,
screenLineEnd
]);
let firstCharacterColumn = null;
this.editor.scanInBufferRange(
/\S/,
screenLineBufferRange,
({ range, stop }) => {
firstCharacterColumn = range.start.column;
stop();
}
);
if (
firstCharacterColumn != null &&
firstCharacterColumn !== this.getBufferColumn()
) {
targetBufferColumn = firstCharacterColumn;
} else {
targetBufferColumn = screenLineBufferRange.start.column;
}
this.setBufferPosition([
screenLineBufferRange.start.row,
targetBufferColumn
]);
}
// Public: Moves the cursor to the end of the line.
moveToEndOfScreenLine() {
this.setScreenPosition([this.getScreenRow(), Infinity]);
}
// Public: Moves the cursor to the end of the buffer line.
moveToEndOfLine() {
this.setBufferPosition([this.getBufferRow(), Infinity]);
}
// Public: Moves the cursor to the beginning of the word.
moveToBeginningOfWord() {
this.setBufferPosition(this.getBeginningOfCurrentWordBufferPosition());
}
// Public: Moves the cursor to the end of the word.
moveToEndOfWord() {
const position = this.getEndOfCurrentWordBufferPosition();
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the beginning of the next word.
moveToBeginningOfNextWord() {
const position = this.getBeginningOfNextWordBufferPosition();
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the previous word boundary.
moveToPreviousWordBoundary() {
const position = this.getPreviousWordBoundaryBufferPosition();
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the next word boundary.
moveToNextWordBoundary() {
const position = this.getNextWordBoundaryBufferPosition();
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the previous subword boundary.
moveToPreviousSubwordBoundary() {
const options = { wordRegex: this.subwordRegExp({ backwards: true }) };
const position = this.getPreviousWordBoundaryBufferPosition(options);
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the next subword boundary.
moveToNextSubwordBoundary() {
const options = { wordRegex: this.subwordRegExp() };
const position = this.getNextWordBoundaryBufferPosition(options);
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the beginning of the buffer line, skipping all
// whitespace.
skipLeadingWhitespace() {
const position = this.getBufferPosition();
const scanRange = this.getCurrentLineBufferRange();
let endOfLeadingWhitespace = null;
this.editor.scanInBufferRange(/^[ \t]*/, scanRange, ({ range }) => {
endOfLeadingWhitespace = range.end;
});
if (endOfLeadingWhitespace.isGreaterThan(position))
this.setBufferPosition(endOfLeadingWhitespace);
}
// Public: Moves the cursor to the beginning of the next paragraph
moveToBeginningOfNextParagraph() {
const position = this.getBeginningOfNextParagraphBufferPosition();
if (position) this.setBufferPosition(position);
}
// Public: Moves the cursor to the beginning of the previous paragraph
moveToBeginningOfPreviousParagraph() {
const position = this.getBeginningOfPreviousParagraphBufferPosition();
if (position) this.setBufferPosition(position);
}
/*
Section: Local Positions and Ranges
*/
// Public: Returns buffer position of previous word boundary. It might be on
// the current word, or the previous word.
//
// * `options` (optional) {Object} with the following keys:
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp})
getPreviousWordBoundaryBufferPosition(options = {}) {
const currentBufferPosition = this.getBufferPosition();
const previousNonBlankRow = this.editor.buffer.previousNonBlankRow(
currentBufferPosition.row
);
const scanRange = Range(
Point(previousNonBlankRow || 0, 0),
currentBufferPosition
);
const ranges = this.editor.buffer.findAllInRangeSync(
options.wordRegex || this.wordRegExp(),
scanRange
);
const range = ranges[ranges.length - 1];
if (range) {
if (
range.start.row < currentBufferPosition.row &&
currentBufferPosition.column > 0
) {
return Point(currentBufferPosition.row, 0);
} else if (currentBufferPosition.isGreaterThan(range.end)) {
return Point.fromObject(range.end);
} else {
return Point.fromObject(range.start);
}
} else {
return currentBufferPosition;
}
}
// Public: Returns buffer position of the next word boundary. It might be on
// the current word, or the previous word.
//
// * `options` (optional) {Object} with the following keys:
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp})
getNextWordBoundaryBufferPosition(options = {}) {
const currentBufferPosition = this.getBufferPosition();
const scanRange = Range(
currentBufferPosition,
this.editor.getEofBufferPosition()
);
const range = this.editor.buffer.findInRangeSync(
options.wordRegex || this.wordRegExp(),
scanRange
);
if (range) {
if (range.start.row > currentBufferPosition.row) {
return Point(range.start.row, 0);
} else if (currentBufferPosition.isLessThan(range.start)) {
return Point.fromObject(range.start);
} else {
return Point.fromObject(range.end);
}
} else {
return currentBufferPosition;
}
}
// Public: Retrieves the buffer position of where the current word starts.
//
// * `options` (optional) An {Object} with the following keys:
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp}).
// * `includeNonWordCharacters` A {Boolean} indicating whether to include
// non-word characters in the default word regex.
// Has no effect if wordRegex is set.
// * `allowPrevious` A {Boolean} indicating whether the beginning of the
// previous word can be returned.
//
// Returns a {Range}.
getBeginningOfCurrentWordBufferPosition(options = {}) {
const allowPrevious = options.allowPrevious !== false;
const position = this.getBufferPosition();
const scanRange = allowPrevious
? new Range(new Point(position.row - 1, 0), position)
: new Range(new Point(position.row, 0), position);
const ranges = this.editor.buffer.findAllInRangeSync(
options.wordRegex || this.wordRegExp(options),
scanRange
);
let result;
for (let range of ranges) {
if (position.isLessThanOrEqual(range.start)) break;
if (allowPrevious || position.isLessThanOrEqual(range.end))
result = Point.fromObject(range.start);
}
return result || (allowPrevious ? new Point(0, 0) : position);
}
// Public: Retrieves the buffer position of where the current word ends.
//
// * `options` (optional) {Object} with the following keys:
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp})
// * `includeNonWordCharacters` A Boolean indicating whether to include
// non-word characters in the default word regex. Has no effect if
// wordRegex is set.
//
// Returns a {Range}.
getEndOfCurrentWordBufferPosition(options = {}) {
const allowNext = options.allowNext !== false;
const position = this.getBufferPosition();
const scanRange = allowNext
? new Range(position, new Point(position.row + 2, 0))
: new Range(position, new Point(position.row, Infinity));
const ranges = this.editor.buffer.findAllInRangeSync(
options.wordRegex || this.wordRegExp(options),
scanRange
);
for (let range of ranges) {
if (position.isLessThan(range.start) && !allowNext) break;
if (position.isLessThan(range.end)) return Point.fromObject(range.end);
}
return allowNext ? this.editor.getEofBufferPosition() : position;
}
// Public: Retrieves the buffer position of where the next word starts.
//
// * `options` (optional) {Object}
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp}).
//
// Returns a {Range}
getBeginningOfNextWordBufferPosition(options = {}) {
const currentBufferPosition = this.getBufferPosition();
const start = this.isInsideWord(options)
? this.getEndOfCurrentWordBufferPosition(options)
: currentBufferPosition;
const scanRange = [start, this.editor.getEofBufferPosition()];
let beginningOfNextWordPosition;
this.editor.scanInBufferRange(
options.wordRegex || this.wordRegExp(),
scanRange,
({ range, stop }) => {
beginningOfNextWordPosition = range.start;
stop();
}
);
return beginningOfNextWordPosition || currentBufferPosition;
}
// Public: Returns the buffer Range occupied by the word located under the cursor.
//
// * `options` (optional) {Object}
// * `wordRegex` A {RegExp} indicating what constitutes a "word"
// (default: {::wordRegExp}).
getCurrentWordBufferRange(options = {}) {
const position = this.getBufferPosition();
const ranges = this.editor.buffer.findAllInRangeSync(
options.wordRegex || this.wordRegExp(options),
new Range(new Point(position.row, 0), new Point(position.row, Infinity))
);
const range = ranges.find(
range =>
range.end.column >= position.column &&
range.start.column <= position.column
);
return range ? Range.fromObject(range) : new Range(position, position);
}
// Public: Returns the buffer Range for the current line.
//
// * `options` (optional) {Object}
// * `includeNewline` A {Boolean} which controls whether the Range should
// include the newline.
getCurrentLineBufferRange(options) {
return this.editor.bufferRangeForBufferRow(this.getBufferRow(), options);
}
// Public: Retrieves the range for the current paragraph.
//
// A paragraph is defined as a block of text surrounded by empty lines or comments.
//
// Returns a {Range}.
getCurrentParagraphBufferRange() {
return this.editor.rowRangeForParagraphAtBufferRow(this.getBufferRow());
}
// Public: Returns the characters preceding the cursor in the current word.
getCurrentWordPrefix() {
return this.editor.getTextInBufferRange([
this.getBeginningOfCurrentWordBufferPosition(),
this.getBufferPosition()
]);
}
/*
Section: Visibility
*/
/*
Section: Comparing to another cursor
*/
// Public: Compare this cursor's buffer position to another cursor's buffer position.
//
// See {Point::compare} for more details.
//
// * `otherCursor`{Cursor} to compare against
compare(otherCursor) {
return this.getBufferPosition().compare(otherCursor.getBufferPosition());
}
/*
Section: Utilities
*/
// Public: Deselects the current selection.
clearSelection(options) {
if (this.selection) this.selection.clear(options);
}
// Public: Get the RegExp used by the cursor to determine what a "word" is.
//
// * `options` (optional) {Object} with the following keys:
// * `includeNonWordCharacters` A {Boolean} indicating whether to include
// non-word characters in the regex. (default: true)
//
// Returns a {RegExp}.
wordRegExp(options) {
const nonWordCharacters = _.escapeRegExp(this.getNonWordCharacters());
let source = `^[\t ]*$|[^\\s${nonWordCharacters}]+`;
if (!options || options.includeNonWordCharacters !== false) {
source += `|${`[${nonWordCharacters}]+`}`;
}
return new RegExp(source, 'g');
}
// Public: Get the RegExp used by the cursor to determine what a "subword" is.
//
// * `options` (optional) {Object} with the following keys:
// * `backwards` A {Boolean} indicating whether to look forwards or backwards
// for the next subword. (default: false)
//
// Returns a {RegExp}.
subwordRegExp(options = {}) {
const nonWordCharacters = this.getNonWordCharacters();
const lowercaseLetters = 'a-z\\u00DF-\\u00F6\\u00F8-\\u00FF';
const uppercaseLetters = 'A-Z\\u00C0-\\u00D6\\u00D8-\\u00DE';
const snakeCamelSegment = `[${uppercaseLetters}]?[${lowercaseLetters}]+`;
const segments = [
'^[\t ]+',
'[\t ]+$',
`[${uppercaseLetters}]+(?![${lowercaseLetters}])`,
'\\d+'
];
if (options.backwards) {
segments.push(`${snakeCamelSegment}_*`);
segments.push(`[${_.escapeRegExp(nonWordCharacters)}]+\\s*`);
} else {
segments.push(`_*${snakeCamelSegment}`);
segments.push(`\\s*[${_.escapeRegExp(nonWordCharacters)}]+`);
}
segments.push('_+');
return new RegExp(segments.join('|'), 'g');
}
/*
Section: Private
*/
getNonWordCharacters() {
return this.editor.getNonWordCharacters(this.getBufferPosition());
}
changePosition(options, fn) {
this.clearSelection({ autoscroll: false });
fn();
this.goalColumn = null;
const autoscroll =
options && options.autoscroll != null
? options.autoscroll
: this.isLastCursor();
if (autoscroll) this.autoscroll();
}
getScreenRange() {
const { row, column } = this.getScreenPosition();
return new Range(new Point(row, column), new Point(row, column + 1));
}
autoscroll(options = {}) {
options.clip = false;
this.editor.scrollToScreenRange(this.getScreenRange(), options);
}
getBeginningOfNextParagraphBufferPosition() {
const start = this.getBufferPosition();
const eof = this.editor.getEofBufferPosition();
const scanRange = [start, eof];
const { row, column } = eof;
let position = new Point(row, column - 1);
this.editor.scanInBufferRange(
EmptyLineRegExp,
scanRange,
({ range, stop }) => {
position = range.start.traverse(Point(1, 0));
if (!position.isEqual(start)) stop();
}
);
return position;
}
getBeginningOfPreviousParagraphBufferPosition() {
const start = this.getBufferPosition();
const { row, column } = start;
const scanRange = [[row - 1, column], [0, 0]];
let position = new Point(0, 0);
this.editor.backwardsScanInBufferRange(
EmptyLineRegExp,
scanRange,
({ range, stop }) => {
position = range.start.traverse(Point(1, 0));
if (!position.isEqual(start)) stop();
}
);
return position;
}
};