jyapayne/ace
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Save changes

Browse source
This commit is contained in:
Garen Torikian 2012-11-02 15:34:25 -07:00 • committed by nightwing
commit eb955fa90d
18 changed files with 15484 additions and 1283 deletions
Download patch file Download diff file Expand all files Collapse all files

87
lib/ace/document.js
View file

@ -37,21 +37,18 @@ var Range = require("./range").Range;
var Anchor = require("./anchor").Anchor;
/**
* @class Document
*
* Contains the text of the document. Document can be attached to several [[EditSession `EditSession`]]s.
*
* At its core, `Document`s are just an array of strings, with each row in the document matching up to the array index.
*
*
* @class Document
**/
/**
* new Document([text])
* @param {String | Array} text The starting text
*
*
* Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.
*
* @param {String | Array} text The starting text
* @constructor
**/
var Document = function(text) {
@ -73,9 +70,9 @@ var Document = function(text) {
oop.implement(this, EventEmitter);
/**
* @param {String} text The text to use
*
* Replaces all the lines in the current `Document` with the value of `text`.
*
* @param {String} text The text to use
**/
this.setValue = function(text) {
var len = this.getLength();
@ -91,21 +88,23 @@ var Document = function(text) {
};
/**
* Creates a new `Anchor` to define a floating point in the document.
* @param {Number} row The row number to use
* @param {Number} column The column number to use
*
* Creates a new `Anchor` to define a floating point in the document.
*
**/
this.createAnchor = function(row, column) {
return new Anchor(this, row, column);
};
/**
* @param {String} text The text to work with
* @returns String A String array, with each index containing a piece of the original `text` string.
*
* Splits a string of text on any newline (`\n`) or carriage-return ('\r') characters.
*
* @method $split
* @param {String} text The text to work with
* @returns {String} A String array, with each index containing a piece of the original `text` string.
*
*
**/
@ -131,12 +130,12 @@ var Document = function(text) {
};
/**
* Document.getNewLineCharacter() -> String
* Returns the newline character that's being used, depending on the value of `newLineMode`.
* @returns {String} If `newLineMode == windows`, `\r\n` is returned.
* If `newLineMode == unix`, `\n` is returned.
* If `newLineMode == auto`, the value of `autoNewLine` is returned.
*
* Returns the newline character that's being used, depending on the value of `newLineMode`.
*
*
*
**/
@ -156,9 +155,10 @@ var Document = function(text) {
this.$autoNewLine = "\n";
this.$newLineMode = "auto";
/**
* [Sets the new line mode.]{: #Document.setNewLineMode.desc}
* @param {String} newLineMode [The newline mode to use; can be either `windows`, `unix`, or `auto`]{: #Document.setNewLineMode.param}
*
* [Sets the new line mode.]{: #Document.setNewLineMode.desc}
*
**/
this.setNewLineMode = function(newLineMode) {
if (this.$newLineMode === newLineMode)
@ -169,16 +169,17 @@ var Document = function(text) {
/**
* [Returns the type of newlines being used; either `windows`, `unix`, or `auto`]{: #Document.getNewLineMode}
*
* @returns String
**/
this.getNewLineMode = function() {
return this.$newLineMode;
};
/**
* Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).
* @param {String} text The text to check
*
* Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).
*
*
**/
this.isNewLine = function(text) {
@ -186,9 +187,10 @@ var Document = function(text) {
};
/**
* Returns a verbatim copy of the given line as it is in the document
* @param {Number} row The row index to retrieve
*
* Returns a verbatim copy of the given line as it is in the document
*
*
**/
this.getLine = function(row) {
@ -196,10 +198,11 @@ var Document = function(text) {
};
/**
* Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.
* @param {Number} firstRow The first row index to retrieve
* @param {Number} lastRow The final row index to retrieve
*
* Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.
*
*
**/
this.getLines = function(firstRow, lastRow) {
@ -221,9 +224,10 @@ var Document = function(text) {
};
/**
* [Given a range within the document, this function returns all the text within that range as a single string.]{: #Document.getTextRange.desc}
* @param {Range} range The range to work with
*
* [Given a range within the document, this function returns all the text within that range as a single string.]{: #Document.getTextRange.desc}
*
**/
this.getTextRange = function(range) {
if (range.start.row == range.end.row) {
@ -248,11 +252,12 @@ var Document = function(text) {
};
/**
* Inserts a block of `text` and the indicated `position`.
* @param {Number} position The position to start inserting at
* @param {String} text A chunk of text to insert
* @returns {Number} The position of the last line of `text`. If the length of `text` is 0, this function simply returns `position`.
*
* Inserts a block of `text` and the indicated `position`.
*
*
**/
this.insert = function(position, text) {
@ -279,9 +284,6 @@ var Document = function(text) {
};
/**
* @event change
* @param {Object} e Contains at least one property called `"action"`. `"action"` indicates the action that triggered the change. Each action also has a set of additional properties.
*
* Fires whenever the document changes.
*
* Several methods trigger different `"change"` events. Below is a list of each action type, followed by each property that's also available:
@ -300,11 +302,15 @@ var Document = function(text) {
* * `range`: the [[Range]] of the change within the document
* * `text`: the text that's being removed
*
* @event change
* @param {Object} e Contains at least one property called `"action"`. `"action"` indicates the action that triggered the change. Each action also has a set of additional properties.
*
**/
/**
* Inserts the elements in `lines` into the document, starting at the row index given by `row`. This method also triggers the `'change'` event.
* @param {Number} row The index of the row to insert at
* @param {Array} lines An array of strings
* @returns Object Contains the final row and column, like this:
* @returns {Object} Contains the final row and column, like this:
* ```
* {row: endRow, column: 0}
* ```
@ -313,7 +319,7 @@ var Document = function(text) {
* {row: row, column: 0}
* ```
*
* Inserts the elements in `lines` into the document, starting at the row index given by `row`. This method also triggers the `'change'` event.
*
*
*
**/
@ -343,16 +349,13 @@ var Document = function(text) {
};
/**
* Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event.
* @param {String} position The position to insert at
* @returns {Object} Returns an object containing the final row and column, like this:<br/>
* ```
* {row: endRow, column: 0}
* ```
*
* Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event.
*
*
*
**/
this.insertNewLine = function(position) {
position = this.$clipPosition(position);
@ -377,6 +380,7 @@ var Document = function(text) {
};
/**
* Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.
* @param {Number} position The position to insert at
* @param {String} text A chunk of text
* @returns {Object} Returns an object containing the final row and column, like this:
@ -385,10 +389,7 @@ var Document = function(text) {
* ```
* @returns {Number} If `text` is empty, this function returns the value of `position`
*
* Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.
*
*
*
*
**/
this.insertInLine = function(position, text) {
if (text.length == 0)
@ -415,11 +416,10 @@ var Document = function(text) {
};
/**
* Removes the `range` from the document.
* @param {Range} range A specified Range to remove
* @returns {Object} Returns the new `start` property of the range, which contains `startRow` and `startColumn`. If `range` is empty, this function returns the unmodified value of `range.start`.
*
* Removes the `range` from the document.
*
*
**/
this.remove = function(range) {
@ -455,13 +455,12 @@ var Document = function(text) {
};
/**
* Removes the specified columns from the `row`. This method also triggers the `'change'` event.
* @param {Number} row The row to remove from
* @param {Number} startColumn The column to start removing at
* @param {Number} endColumn The column to stop removing at
* @returns {Object} Returns an object containing `startRow` and `startColumn`, indicating the new row and column values.<br/>If `startColumn` is equal to `endColumn`, this function returns nothing.
*
* Removes the specified columns from the `row`. This method also triggers the `'change'` event.
*
*
**/
this.removeInLine = function(row, startColumn, endColumn) {
@ -484,12 +483,11 @@ var Document = function(text) {
};
/**
* Removes a range of full lines. This method also triggers the `'change'` event.
* @param {Number} firstRow The first row to be removed
* @param {Number} lastRow The last row to be removed
* @returns {[String]} Returns all the removed lines.
*
* Removes a range of full lines. This method also triggers the `'change'` event.
*
*
**/
this.removeLines = function(firstRow, lastRow) {
@ -507,10 +505,9 @@ var Document = function(text) {
};
/**
* Removes the new line between `row` and the row immediately following it. This method also triggers the `'change'` event.
* @param {Number} row The row to check
*
* Removes the new line between `row` and the row immediately following it. This method also triggers the `'change'` event.
*
**/
this.removeNewLine = function(row) {
var firstLine = this.getLine(row);
@ -530,6 +527,7 @@ var Document = function(text) {
};
/**
* Replaces a range in the document with the new `text`.
* @param {Range} range A specified Range to replace
* @param {String} text The new text to use as a replacement
* @returns {Object} Returns an object containing the final row and column, like this:
@ -537,7 +535,6 @@ var Document = function(text) {
* If the text and range are empty, this function returns an object containing the current `range.start` value.
* If the text is the exact same as what currently exists, this function returns an object containing the current `range.end` value.
*
* Replaces a range in the document with the new `text`.
*
**/
this.replace = function(range, text) {
@ -561,7 +558,7 @@ var Document = function(text) {
};
/**
* =Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
* Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
**/
this.applyDeltas = function(deltas) {
for (var i=0; i<deltas.length; i++) {