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

First dump of doc stuff

Browse source
This commit is contained in:
Garen Torikian 2012-02-02 17:00:18 -08:00
commit 79886c3e07
83 changed files with 8598 additions and 554 deletions
Download patch file Download diff file Expand all files Collapse all files

304
lib/ace/document.js
View file

@ -43,6 +43,21 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter;
var Range = require("./range").Range;
var Anchor = require("./anchor").Anchor;
/**
* class Document
*
* Documentation about Document. Is this recursion? TODO
*
*
**/
/**
* new Document(text)
* - text (String | Array): The starting text
*
* Creates a new `Document`. TODO
*
**/
var Document = function(text) {
this.$lines = [];
@ -62,20 +77,48 @@ var Document = function(text) {
oop.implement(this, EventEmitter);
this.setValue = function(text) {
/**
* Document.setValue(text) -> Void
* - text (String): The value to set
*
*
**/
this.setValue = function(text) {
var len = this.getLength();
this.remove(new Range(0, 0, len, this.getLine(len-1).length));
this.insert({row: 0, column:0}, text);
};
this.getValue = function() {
/**
* Document.getValue() -> String
*
* Returns all the lines in the document, split by the new line character.
**/
this.getValue = function() {
return this.getAllLines().join(this.getNewLineCharacter());
};
this.createAnchor = function(row, column) {
/**
* Document.createAnchor(row, column) -> Anchor
*
*
**/
this.createAnchor = function(row, column) {
return new Anchor(this, row, column);
};
/**
* Document.$split(text) -> Array
* - text (String): The text to work with
*
* Splits a string of text on any newline (`\n`) or carriage-return ('\r') characters.
*
* #### Returns
*
* A String array, with each index containing a piece of the original `text` string.
*
**/
// check for IE split bug
if ("aaa".split(/a/).length == 0)
this.$split = function(text) {
@ -87,7 +130,12 @@ var Document = function(text) {
};
this.$detectNewLine = function(text) {
/**
* Document.$detectNewLine(text) -> Void
*
*
**/
this.$detectNewLine = function(text) {
var match = text.match(/^.*?(\r\n|\r|\n)/m);
if (match) {
this.$autoNewLine = match[1];
@ -96,7 +144,20 @@ var Document = function(text) {
}
};
this.getNewLineCharacter = function() {
/**
* Document.getNewLineCharacter() -> String
*
* Returns the new line character that's being used, depending on the value of `newLineMode`.
*
* #### Returns
*
* If `newLineMode == windows`, `\r\n` is returned.
* If `newLineMode == unix`, `\n` is returned.
* If `newLineMode == auto`, the value of `autoNewLine` is returned.
*
*
**/
this.getNewLineCharacter = function() {
switch (this.$newLineMode) {
case "windows":
return "\r\n";
@ -111,45 +172,88 @@ var Document = function(text) {
this.$autoNewLine = "\n";
this.$newLineMode = "auto";
this.setNewLineMode = function(newLineMode) {
/**
* Document.setNewLineMode(newLineMode) -> Void
* - newLineMode(String): The newline mode to use; can be either `windows`, `unix`, or `auto`
*
* Sets the new line mode.
**/
this.setNewLineMode = function(newLineMode) {
if (this.$newLineMode === newLineMode)
return;
this.$newLineMode = newLineMode;
};
this.getNewLineMode = function() {
/**
* Document.getNewLineMode() -> String
*
* Returns the type of newlines being used; either `windows`, `unix`, or `auto`
*
**/
this.getNewLineMode = function() {
return this.$newLineMode;
};
this.isNewLine = function(text) {
/**
* Document.isNewLine(text) -> Boolean
* - text (String): The text to check
*
* Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).
*
**/
this.isNewLine = function(text) {
return (text == "\r\n" || text == "\r" || text == "\n");
};
/**
* Get a verbatim copy of the given line as it is in the document
*/
this.getLine = function(row) {
* Document.getLine(row) -> String
* - row (Number): The row index to retrieve
*
* Returns a verbatim copy of the given line as it is in the document
*
**/
this.getLine = function(row) {
return this.$lines[row] || "";
};
this.getLines = function(firstRow, lastRow) {
/**
* Document.getLines(firstRow, lastRow) -> Array
* - firstRow (Number): The first row index to retrieve
* - lastRow (Number): 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) {
return this.$lines.slice(firstRow, lastRow + 1);
};
/**
* Returns all lines in the document as string array. Warning: The caller
* should not modify this array!
*/
this.getAllLines = function() {
* Document.getAllLines() -> Array
*
* Returns all lines in the document as string array. <Warning>The caller should not modify this array!</Warning>
**/
this.getAllLines = function() {
return this.getLines(0, this.getLength());
};
this.getLength = function() {
/**
* Document.getLength() -> Number
*
* Returns the number of rows in the document.
**/
this.getLength = function() {
return this.$lines.length;
};
this.getTextRange = function(range) {
/**
* Document.getTextRange(range) -> Array
* - range (String): blah
*
* TODO
**/
this.getTextRange = function(range) {
if (range.start.row == range.end.row) {
return this.$lines[range.start.row].substring(range.start.column,
range.end.column);
@ -163,7 +267,13 @@ var Document = function(text) {
}
};
this.$clipPosition = function(position) {
/**
* Document.$clipPosition(position) -> Number
* - position (Number): blah
*
* TODO
**/
this.$clipPosition = function(position) {
var length = this.getLength();
if (position.row >= length) {
position.row = Math.max(0, length - 1);
@ -172,7 +282,19 @@ var Document = function(text) {
return position;
};
this.insert = function(position, text) {
/**
* Document.insert(position, text) -> Number
* - position (Number): The position to start inserting at
* - text (String): A chunk of text to insert
*
* Inserts a block of `text` and the indicated `position`.
*
* #### Returns
*
* Returns the position of the last line of `text`. If the length of `text` is 0, this function simply returns `position`.
*
**/
this.insert = function(position, text) {
if (text.length == 0)
return position;
@ -194,7 +316,25 @@ var Document = function(text) {
return position;
};
this.insertLines = function(row, lines) {
/**
* Document.insertLines(row, lines) -> Object
* - row (Number): The index of the row to insert at
* - lines (Array): An array of strings
*
* Inserts the elements in `lines` into the document, starting at the row index given by `row`. This method also triggers the `'change'` event.
*
* #### Returns
*
* Returns an object containing 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}
*
**/
this.insertLines = function(row, lines) {
if (lines.length == 0)
return {row: row, column: 0};
@ -212,7 +352,20 @@ var Document = function(text) {
return range.end;
};
this.insertNewLine = function(position) {
/**
* Document.insertNewLine(position) -> Object
* - position (String): The position to insert at
*
* Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event.
*
* #### Returns
*
* Returns an object containing the final row and column, like this:
*
* {row: endRow, column: 0}
*
**/
this.insertNewLine = function(position) {
position = this.$clipPosition(position);
var line = this.$lines[position.row] || "";
@ -234,7 +387,23 @@ var Document = function(text) {
return end;
};
this.insertInLine = function(position, text) {
/**
* Document.insertInLine(position, text) -> Object | Integer
* - position (Number): The position to insert at
* - text (String): A chunk of text
*
* Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.
*
* #### Returns
*
* Returns an object containing the final row and column, like this:
*
* {row: endRow, column: 0}
*
* If `text` is empty, this function returns the value of `position`.
*
**/
this.insertInLine = function(position, text) {
if (text.length == 0)
return position;
@ -258,7 +427,17 @@ var Document = function(text) {
return end;
};
this.remove = function(range) {
/**
* Document.remove(range) -> Object
* - range (Range): A specified Range to remove
*
* Removes the `range` from the document.
*
* #### Returns
*
* 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`.
**/
this.remove = function(range) {
// clip to document
range.start = this.$clipPosition(range.start);
range.end = this.$clipPosition(range.end);
@ -290,7 +469,19 @@ var Document = function(text) {
return range.start;
};
this.removeInLine = function(row, startColumn, endColumn) {
/**
* Document.removeInLine(row, startColumn, endColumn) -> Object | Void
* - row (Number): The row to remove from
* - startColumn (Number): The column to start removing at
* - endColumn (Number): The column to stop removing at
*
* Removes the specified columns from the `row`. This method also triggers the `'change'` event.
*
* #### Returns
*
* Returns an object containing `startRow` and `startColumn`, indicating the new row and column values. If `startColumn` is equal to `endColumn`, this function returns nothing.
**/
this.removeInLine = function(row, startColumn, endColumn) {
if (startColumn == endColumn)
return;
@ -310,13 +501,19 @@ var Document = function(text) {
};
/**
* Removes a range of full lines
*
* @param firstRow {Integer} The first row to be removed
* @param lastRow {Integer} The last row to be removed
* @return {String[]} The removed lines
*/
this.removeLines = function(firstRow, lastRow) {
* Document.removeLines(firstRow, lastRow) -> Array
* - firstRow (Number): The first row to be removed
* - lastRow (Number): The last row to be removed
*
* Removes a range of full lines. This method also triggers the `'change'` event.
*
*
* #### Returns
*
* Returns all the removed lines.
*
**/
this.removeLines = function(firstRow, lastRow) {
var range = new Range(firstRow, 0, lastRow + 1, 0);
var removed = this.$lines.splice(firstRow, lastRow - firstRow + 1);
@ -330,7 +527,14 @@ var Document = function(text) {
return removed;
};
this.removeNewLine = function(row) {
/**
* Document.removeNewLine(row) -> Void
* - row (Number): The row to be removed
*
* TODO Removes the row from the document. This method also triggers the `'change'` event.
*
**/
this.removeNewLine = function(row) {
var firstLine = this.getLine(row);
var secondLine = this.getLine(row+1);
@ -347,7 +551,25 @@ var Document = function(text) {
this._emit("change", { data: delta });
};
this.replace = function(range, text) {
/**
* Document.replace(range, text) -> Object
* - range (Range): A specified Range to replace
* - text (String): The new text to use as a replacement
*
* Replaces a range in the document with the new `text`.
*
* #### Returns
*
* 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.
*
**/
this.replace = function(range, text) {
if (text.length == 0 && range.isEmpty())
return range.start;
@ -367,7 +589,12 @@ var Document = function(text) {
return end;
};
this.applyDeltas = function(deltas) {
/**
* Document.applyDeltas(deltas) -> Void
*
* TODO
**/
this.applyDeltas = function(deltas) {
for (var i=0; i<deltas.length; i++) {
var delta = deltas[i];
var range = Range.fromPoints(delta.range.start, delta.range.end);
@ -383,7 +610,12 @@ var Document = function(text) {
}
};
this.revertDeltas = function(deltas) {
/**
* Document.revertDeltas(deltas) -> Void
*
* TODO
**/
this.revertDeltas = function(deltas) {
for (var i=deltas.length-1; i>=0; i--) {
var delta = deltas[i];