gollum 2.4.4 → 2.4.5

data/lib/gollum/frontend/public/gollum/livepreview/js/ace/lib/ace/document.js

@@ -1,37 +1,30 @@
 /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+ * Distributed under the BSD license:
  *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Ajax.org Code Editor (ACE).
- *
- * The Initial Developer of the Original Code is
- * Ajax.org B.V.
- * Portions created by the Initial Developer are Copyright (C) 2010
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *      Fabian Jakobs <fabian AT ajax DOT org>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
+ * Copyright (c) 2010, Ajax.org B.V.
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of Ajax.org B.V. nor the
+ *       names of its contributors may be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL AJAX.ORG B.V. BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * ***** END LICENSE BLOCK ***** */
 
@@ -44,20 +37,20 @@ var Range = require("./range").Range;
 var Anchor = require("./anchor").Anchor;
 
 /**
- * class Document
- *
- * Contains the text of the document. Documents are controlled by a single [[EditSession `EditSession`]]. 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.
  *
+ * @class Document
  **/
 
  /**
- * new Document([text])
- * - text (String | Array): 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) {
     this.$lines = [];
 
@@ -77,10 +70,9 @@ var Document = function(text) {
     oop.implement(this, EventEmitter);
 
     /**
-    * Document.setValue(text) -> Void
-    * - text (String): 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();
@@ -89,8 +81,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() {
@@ -98,23 +88,23 @@ var Document = function(text) {
     };
 
     /** 
-    * Document.createAnchor(row, column) -> Anchor
-    * - row (Number): The row number to use
-    * - column (Number): The column number to use
-    *
     * 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
+    *
+    *
     **/
     this.createAnchor = function(row, column) {
         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.
-    * 
+    /** 
     * 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.
+    *
     *
     **/
 
@@ -129,11 +119,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) {
@@ -144,12 +130,11 @@ var Document = function(text) {
     };
 
     /**
-    * Document.getNewLineCharacter() -> String
-    * + (String): If `newLineMode == windows`, `\r\n` is returned.<br/>
-    *  If `newLineMode == unix`, `\n` is returned.<br/>
+    * 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`. 
     *
     * 
     * 
@@ -170,10 +155,10 @@ 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}
-     * 
      * [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}
+     * 
+     *
      **/
     this.setNewLineMode = function(newLineMode) {
         if (this.$newLineMode === newLineMode)
@@ -183,20 +168,18 @@ var Document = function(text) {
     };
 
     /**
-    * Document.getNewLineMode() -> String
-    * 
     * [Returns the type of newlines being used; either `windows`, `unix`, or `auto`]{: #Document.getNewLineMode}
-    *
+    * @returns String
     **/
     this.getNewLineMode = function() {
         return this.$newLineMode;
     };
 
     /**
-    * Document.isNewLine(text) -> Boolean
-    * - text (String): The text to check
-    *
     * Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).
+    * @param {String} text The text to check
+    *
+    * 
     *
     **/
     this.isNewLine = function(text) {
@@ -204,10 +187,10 @@ var Document = function(text) {
     };
 
     /**
-    * 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
+    * @param {Number} row The row index to retrieve
+    *
+    * 
     *
     **/
     this.getLine = function(row) {
@@ -215,11 +198,11 @@ 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
-    * 
     * 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
+    *
+    * 
     *
     **/
     this.getLines = function(firstRow, lastRow) {
@@ -227,8 +210,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() {
@@ -236,8 +217,6 @@ var Document = function(text) {
     };
 
     /**
-    * Document.getLength() -> Number
-    * 
     * Returns the number of rows in the document.
     **/
     this.getLength = function() {
@@ -245,10 +224,10 @@ var Document = function(text) {
     };
 
     /**
-    * Document.getTextRange(range) -> String
-    * - 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}
+    * @param {Range} range The range to work with
+    * 
+    * 
     **/
     this.getTextRange = function(range) {
         if (range.start.row == range.end.row) {
@@ -263,11 +242,6 @@ var Document = function(text) {
         }
     };
 
-    /** internal, hide
-    * Document.$clipPosition(position) -> Number
-    * 
-    * 
-    **/
     this.$clipPosition = function(position) {
         var length = this.getLength();
         if (position.row >= length) {
@@ -278,13 +252,11 @@ 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`. 
     * Inserts a block of `text` and the indicated `position`.
+    * @param {Object} position The position to start inserting at 
+    * @param {String} text A chunk of text to insert
+    * @returns {Object} The position ({row, column}) 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 || text.length === 0)
@@ -310,15 +282,42 @@ 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}```
-    *
+     * 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:
+     *
+     *  * `"insertLines"` (emitted by [[Document.insertLines]])
+     *    * `range`: the [[Range]] of the change within the document
+     *    * `lines`: the lines in the document that are changing
+     *  * `"insertText"` (emitted by [[Document.insertNewLine]])
+     *    * `range`: the [[Range]] of the change within the document
+     *    * `text`: the text that's being added
+     *  * `"removeLines"` (emitted by [[Document.insertLines]])
+     *    * `range`: the [[Range]] of the change within the document
+     *    * `lines`: the lines in the document that were removed
+     *    * `nl`: the new line character (as defined by [[Document.getNewLineCharacter]])
+     *  * `"removeText"` (emitted by [[Document.removeInLine]] and [[Document.removeNewLine]])
+     *    * `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:  
+    *   ```
+    *   {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}
+    *   ```
+    *
+    * 
     *
     *
     **/
@@ -348,14 +347,12 @@ 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}```
-    * 
     * Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event. 
-    *
-    *   
+    * @param {Object} position The position to insert at
+    * @returns {Object} Returns an object containing the final row and column, like this:<br/>
+    *    ```
+    *    {row: endRow, column: 0}
+    *    ```
     *
     **/
     this.insertNewLine = function(position) {
@@ -381,16 +378,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`
-    * 
     * Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.
-    *
-    *
+    * @param {Object} 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}
+    *     ```
     *
     **/
     this.insertInLine = function(position, text) {
@@ -418,11 +412,9 @@ 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`.
-    * 
     * 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`.
     *
     *
     **/
@@ -459,13 +451,11 @@ 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.
-    *
     * 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.
     *
     * 
     **/
@@ -489,12 +479,10 @@ 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.
-    * 
     * 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.
     * 
     *
     **/
@@ -513,10 +501,8 @@ var Document = function(text) {
     };
 
     /**
-    * Document.removeNewLine(row) -> Void
-    * - row (Number): The row to check
-    * 
     * 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
     *
     **/
     this.removeNewLine = function(row) {
@@ -537,15 +523,14 @@ 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:
+    * 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:
     *     {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.
     *
-    * Replaces a range in the document with the new `text`.
     *
     **/
     this.replace = function(range, text) {
@@ -569,8 +554,6 @@ var Document = function(text) {
     };
 
     /**
-    * Document.applyDeltas(deltas) -> Void
-    * 
     * Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
     **/
     this.applyDeltas = function(deltas) {
@@ -590,8 +573,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) {