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

Transition to JSD

Browse source
This commit is contained in:
Garen Torikian 2012-10-22 13:38:25 -07:00 • committed by nightwing
commit 0739444f87
68 changed files with 404 additions and 5458 deletions
Download patch file Download diff file Expand all files Collapse all files

167
lib/ace/document.js
View file

@ -37,16 +37,18 @@ var Range = require("./range").Range;
var Anchor = require("./anchor").Anchor;
/**
* class Document
* @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.
* 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.
*
*
**/
/**
* new Document([text])
* - text (String | Array): The starting 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.
*
@ -71,8 +73,7 @@ var Document = function(text) {
oop.implement(this, EventEmitter);
/**
* Document.setValue(text) -> Void
* - text (String): The text to use
* @param {String} text The text to use
*
* Replaces all the lines in the current `Document` with the value of `text`.
**/
@ -83,8 +84,6 @@ var Document = function(text) {
};
/**
* Document.getValue() -> String
*
* Returns all the lines in the document as a single string, split by the new line character.
**/
this.getValue = function() {
@ -92,9 +91,8 @@ var Document = function(text) {
};
/**
* Document.createAnchor(row, column) -> Anchor
* - row (Number): The row number to use
* - column (Number): The column number to use
* @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.
**/
@ -102,13 +100,12 @@ var Document = function(text) {
return new Anchor(this, row, column);
};
/** internal, hide
* Document.$split(text) -> [String]
* - text (String): The text to work with
* + ([String]): A String array, with each index containing a piece of the original `text` string.
/**
* @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
*
**/
@ -123,11 +120,7 @@ var Document = function(text) {
};
/** internal, hide
* Document.$detectNewLine(text) -> Void
*
*
**/
this.$detectNewLine = function(text) {
var match = text.match(/^.*?(\r\n|\r|\n)/m);
if (match) {
@ -139,14 +132,13 @@ var Document = function(text) {
/**
* Document.getNewLineCharacter() -> String
* + (String): If `newLineMode == windows`, `\r\n` is returned.<br/>
* If `newLineMode == unix`, `\n` is returned.<br/>
* @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`.
*
*
*
**/
this.getNewLineCharacter = function() {
switch (this.$newLineMode) {
@ -164,8 +156,7 @@ var Document = function(text) {
this.$autoNewLine = "\n";
this.$newLineMode = "auto";
/**
* Document.setNewLineMode(newLineMode) -> Void
* - newLineMode(String): [The newline mode to use; can be either `windows`, `unix`, or `auto`]{: #Document.setNewLineMode.param}
* @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}
**/
@ -177,8 +168,6 @@ var Document = function(text) {
};
/**
* Document.getNewLineMode() -> String
*
* [Returns the type of newlines being used; either `windows`, `unix`, or `auto`]{: #Document.getNewLineMode}
*
**/
@ -187,8 +176,7 @@ var Document = function(text) {
};
/**
* Document.isNewLine(text) -> Boolean
* - text (String): The text to check
* @param {String} text The text to check
*
* Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).
*
@ -198,8 +186,7 @@ var Document = function(text) {
};
/**
* Document.getLine(row) -> String
* - row (Number): The row index to retrieve
* @param {Number} row The row index to retrieve
*
* Returns a verbatim copy of the given line as it is in the document
*
@ -209,9 +196,8 @@ var Document = function(text) {
};
/**
* Document.getLines(firstRow, lastRow) -> [String]
* - firstRow (Number): The first row index to retrieve
* - lastRow (Number): The final row index to retrieve
* @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`.
*
@ -221,8 +207,6 @@ var Document = function(text) {
};
/**
* Document.getAllLines() -> [String]
*
* Returns all lines in the document as string array. Warning: The caller should not modify this array!
**/
this.getAllLines = function() {
@ -230,8 +214,6 @@ var Document = function(text) {
};
/**
* Document.getLength() -> Number
*
* Returns the number of rows in the document.
**/
this.getLength = function() {
@ -239,8 +221,7 @@ var Document = function(text) {
};
/**
* Document.getTextRange(range) -> String
* - range (Range): The range to work with
* @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}
**/
@ -257,11 +238,6 @@ var Document = function(text) {
}
};
/** internal, hide
* Document.$clipPosition(position) -> Number
*
*
**/
this.$clipPosition = function(position) {
var length = this.getLength();
if (position.row >= length) {
@ -272,13 +248,12 @@ var Document = function(text) {
};
/**
* Document.insert(position, text) -> Number
* - position (Number): The position to start inserting at
* - text (String): A chunk of text to insert
* + (Number): The position of the last line of `text`. If the length of `text` is 0, this function simply returns `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) {
if (!text || text.length === 0)
@ -304,21 +279,8 @@ var Document = function(text) {
};
/**
* Document.insertLines(row, lines) -> Object
* - row (Number): The index of the row to insert at
* - lines (Array): An array of strings
* + (Object): Returns an object containing the final row and column, like this:<br/>
* ```{row: endRow, column: 0}```<br/>
* If `lines` is empty, this function returns an object containing the current row, and column, like this:<br/>
* ```{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.
*
*
**/
/**
* Document@change(e)
* - e (Object): Contains at least one property called `"action"`. `"action"` indicates the action that triggered the change. Each action also has a set of additional properties.
* @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.
*
@ -339,6 +301,22 @@ var Document = function(text) {
* * `text`: the text that's being removed
*
**/
/**
* @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:
* ```
* {row: endRow, column: 0}
* ```
* If `lines` is empty, this function returns an object containing the current row, and column, like this:
* ```
* {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.
*
*
**/
this.insertLines = function(row, lines) {
if (lines.length == 0)
return {row: row, column: 0};
@ -365,10 +343,11 @@ var Document = function(text) {
};
/**
* Document.insertNewLine(position) -> Object
* - position (String): The position to insert at
* + (Object): Returns an object containing the final row and column, like this:<br/>
* ```{row: endRow, column: 0}```
* @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.
*
@ -398,12 +377,13 @@ var Document = function(text) {
};
/**
* Document.insertInLine(position, text) -> Object | Number
* - position (Number): The position to insert at
* - text (String): A chunk of text
* + (Object): Returns an object containing the final row and column, like this:<br/>
* ```{row: endRow, column: 0}```
* + (Number): If `text` is empty, this function returns the value of `position`
* @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:
* ```
* {row: endRow, column: 0}
* ```
* @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.
*
@ -435,9 +415,8 @@ var Document = function(text) {
};
/**
* Document.remove(range) -> Object
* - range (Range): A specified Range to remove
* + (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`.
* @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.
*
@ -476,11 +455,10 @@ var Document = function(text) {
};
/**
* Document.removeInLine(row, startColumn, endColumn) -> Object
* - row (Number): The row to remove from
* - startColumn (Number): The column to start removing at
* - endColumn (Number): The column to stop removing at
* + (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.
* @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.
*
@ -506,10 +484,9 @@ var Document = function(text) {
};
/**
* Document.removeLines(firstRow, lastRow) -> [String]
* - firstRow (Number): The first row to be removed
* - lastRow (Number): The last row to be removed
* + ([String]): Returns all the removed lines.
* @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.
*
@ -530,8 +507,7 @@ var Document = function(text) {
};
/**
* Document.removeNewLine(row) -> Void
* - row (Number): The row to check
* @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.
*
@ -554,10 +530,9 @@ var Document = function(text) {
};
/**
* Document.replace(range, text) -> Object
* - range (Range): A specified Range to replace
* - text (String): The new text to use as a replacement
* + (Object): Returns an object containing the final row and column, like this:
* @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:
* {row: endRow, column: 0}
* 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.
@ -586,9 +561,7 @@ var Document = function(text) {
};
/**
* Document.applyDeltas(deltas) -> Void
*
* 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++) {
@ -607,8 +580,6 @@ var Document = function(text) {
};
/**
* Document.revertDeltas(deltas) -> Void
*
* Reverts any changes previously applied. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
**/
this.revertDeltas = function(deltas) {