Maintain public API and update coding convention

This seeks to keep the public API in-tact while improving method names
within ace by keeping the old methods as wrappers around the new
better-named methods.

For example, document.insert() now simply calls document.insertText()
and warns the caller via a console.log() that they are using a
deprecated method.

I've also updated the coding style of my changes (where I noticed
discrepancies) to match the rest of Ace.

lib/ace/anchor.js

@@ -117,33 +117,29 @@ var Anchor = exports.Anchor = function(doc, row, column) {
             var deltaEnd      = (deltaIsInsert ? deltaStart : delta.range.end); // Collapse insert range.
             
             // DELTA AFTER POINT: No change needed.
-            if (_pointsInOrder(point, deltaStart, moveIfEqual))
+            if (_pointsInOrder(point, deltaStart, moveIfEqual)) {
-            {
+                return {
-                return (
-                {
                     row: point.row,
                     column: point.column
-                });
+                };
             }
             
             // DELTA BEFORE POINT: Move point by delta shift.
-            if (_pointsInOrder(deltaEnd, point, !moveIfEqual))
+            if (_pointsInOrder(deltaEnd, point, !moveIfEqual)) {
-            {
+                return {
-                return (
-                {
                     row: point.row + deltaRowShift,
                     column: point.column + (point.row == deltaEnd.row ? deltaColShift : 0)
-                });
+                };
             }
             
             // DELTA ENVELOPS POINT (delete only): Move point to delta start.
             if (delta.action != 'delete')
                 throw 'Delete action expected.';
-            return (
+            
-            {
+            return {
                 row: deltaStart.row,
                 column: deltaStart.column
-            });            
+            };
         }
         
         var delta = e.data;

lib/ace/anchor_test.js

@@ -70,7 +70,7 @@ module.exports = {
         var doc = new Document("juhu\nkinners");
         var anchor = new Anchor(doc, 1, 4);
         
-        doc.insertLines({row: 0, column: 0}, ['', '']);
+        doc.insertMergedLines({row: 0, column: 0}, ['', '']);
         assert.position(anchor.getPosition(), 2, 4);    
     },
     
@@ -78,7 +78,7 @@ module.exports = {
         var doc = new Document("juhu\nkinners");
         var anchor = new Anchor(doc, 1, 4);
         
-        doc.insertLines({row: 1, column: 2}, ['', '']);
+        doc.insertMergedLines({row: 1, column: 2}, ['', '']);
         assert.position(anchor.getPosition(), 2, 2);
     },
     

lib/ace/document.js

@@ -59,7 +59,7 @@ var Document = function(textOrLines) {
     if (textOrLines.length == 0) {
         this.$lines = [""];
     } else if (Array.isArray(textOrLines)) {
-        this.insertLines({row: 0, column: 0}, textOrLines);
+        this.insertMergedLines({row: 0, column: 0}, textOrLines);
     } else {
         this.insertText({row: 0, column:0}, textOrLines);
     }
@@ -230,13 +230,10 @@ var Document = function(textOrLines) {
     this.$clipPosition = function(position) {
         
         var length = this.getLength();
-        if (position.row >= length)
+        if (position.row >= length) {
-        {
             position.row = Math.max(0, length - 1);
             position.column = this.getLine(length - 1).length;
-        }
+        } else {
-        else
-        {
             position.row = Math.max(0, position.row);
             position.column = Math.min(Math.max(position.column, 0), this.getLine(position.row).length);
         }
@@ -264,16 +261,15 @@ var Document = function(textOrLines) {
             throw errorText;
         }
         
+        // Validate lines.
         if (!delta.lines instanceof Array)
-        {
             fnThrow('Delta object lines must be an array');
-        }
         
+        // Validate range type.
         if (!delta.range instanceof Range)
-        {
             fnThrow('Range object is not an instance of the Range class');
-        }
         
+        // Validate start point.
         var start = delta.range.start;
         if (Math.min(Math.max(start.row,    0), this.getLength() - 1         ) != start.row ||
             Math.min(Math.max(start.column, 0), this.$lines[start.row].length) != start.column)
@@ -281,16 +277,37 @@ var Document = function(textOrLines) {
             fnThrow('Range start point not contained in document');
         }
         
+        // Validate ending row offset.
         if (delta.lines.length - 1 != delta.range.end.row - delta.range.start.row)
-        {
             fnThrow('Range row offsets does not match delta lines');
-        }
         
-        // TODO: Validate that the ending column offset matches the lines.
+        // TODO:
-        // TODO: Validate for deletions that the lines deleted match the lines
+        //   - Validate that the ending column offset matches the lines.
-        //       in the document.
+        //   - Validate the deleted lines match the lines in the document.
     },
 
+    // Deprecated methods retained for backwards compatibility.
+    this.insert = function(position, text){
+        console.log('Warning: document.insert is deprecated. Use the insertText method instead.');
+        return this.insertText(position, text);
+    }
+    this.insertLines = function(row, lines) {
+        console.log('Warning: document.insertLines is deprecated. Use the insertFullLines method instead.');
+        return this.insertFullLines(row, lines);
+    }
+    this.removeLines = function(firstRow, lastRow) {
+        console.log('Warning: document.removeLines is deprecated. Use the removeFullLines method instead.');
+        return this.removeFullLines(firstRow, lastRow);
+    }
+    this.insertNewLine = function(position) {
+        console.log('Warning: document.insertNewLine is deprecated. Use insertMergedLines(position, [\'\', \'\']) instead.');
+        return this.insertMergedLines(position, ['', '']);
+    }
+    this.insertInLine = function(position, text) {
+        console.log('Warning: document.insertInLine is deprecated. Use insertText instead.');
+        return this.insertText(position, text);
+    }
+
     /**
     * Inserts a block of `text` at the indicated `position`.
     * @param {Object} position The position to start inserting at; it's an object that looks like `{ row: row, column: column}`
@@ -304,9 +321,9 @@ var Document = function(textOrLines) {
         if (this.getLength() <= 1)
             this.$detectNewLine(text);
         
-        return this.insertLines(position, this.$split(text));
+        return this.insertMergedLines(position, this.$split(text));
     };
-
+    
     /**
     * Fires whenever the document changes.
     *
@@ -338,28 +355,26 @@ var Document = function(textOrLines) {
     *   ```
     *
     **/
-    this.insertFullLines = function(row, lines)
+    this.insertFullLines = function(row, lines) {
-    {
         // Clip to document.
         // Allow one past the document end.
         row = Math.min(Math.max(row, 0), this.getLength());
         
         // Calculate insertion point.
         var column = 0;
-        if (row < this.getLength()) // Insert before the specified row.
+        if (row < this.getLength()) {
-        {
+            // Insert before the specified row.
             lines = lines.concat(['']);
             column = 0;
-        }
+        } else {
-        else // Insert after the last row in the document.
+            // Insert after the last row in the document.
-        {
             lines = [''].concat(lines);
             row--;
             var column = this.$lines[row].length;
         }
         
         // Insert.
-        this.insertLines({row: row, column: column}, lines);
+        this.insertMergedLines({row: row, column: column}, lines);
     },
 
     /**
@@ -376,7 +391,7 @@ var Document = function(textOrLines) {
     *   ```
     *
     **/    
-    this.insertLines = function(position, lines){
+    this.insertMergedLines = function(position, lines) {
 
         // Calculate insertion range end point.
         this.$clipPosition(position);
@@ -405,8 +420,7 @@ var Document = function(textOrLines) {
         
         // Apply delta (emits change).
         range = this.$getClippedRange(range);
-        this.applyDelta(
+        this.applyDelta({
-        {
             action: 'delete',
             range: range,
             lines: this._getLinesForRange(range),
@@ -483,14 +497,13 @@ var Document = function(textOrLines) {
     **/
     this.removeNewLine = function(row) {
         
-        if (row < this.getLength() - 1 && row >= 0)
+        if (row < this.getLength() - 1 && row >= 0) {
-        {
             // Apply delta (emits change).
             this.applyDelta({
                 action: "delete",
                 range: new Range(row, this.getLine(row).length, row + 1, 0),
                 lines: ['', '']
-            });            
+            });
         }
     };
 
@@ -558,8 +571,7 @@ var Document = function(textOrLines) {
         {
             case 'insert':
                 splitLine(this.$lines, delta.range.start);
-                for (var i = 0; i < delta.lines.length; i++)
+                for (var i = 0; i < delta.lines.length; i++) {
-                {
                     var row = delta.range.start.row + 1 + i;
                     this.$lines.splice(row, 0, delta.lines[i]);
                 }
@@ -571,7 +583,7 @@ var Document = function(textOrLines) {
                 splitLine(this.$lines, delta.range.end);
                 splitLine(this.$lines, delta.range.start);
                 this.$lines.splice(
-                    delta.range.start.row + 1,                    // Where to start deleting
+                    delta.range.start.row + 1,                       // Where to start deleting
                     delta.range.end.row - delta.range.start.row + 1  // Num lines to delete.
                 );
                 joinLineWithNext(this.$lines, delta.range.start.row);

lib/ace/document_test.js

@@ -65,7 +65,7 @@ module.exports = {
         var deltas = [];
         doc.on("change", function(e) { deltas.push(e.data); });
 
-        doc.insertLines({row: 0, column: 1}, ['', '']);
+        doc.insertMergedLines({row: 0, column: 1}, ['', '']);
         assert.equal(doc.getValue(), ["1", "2", "34"].join("\n"));
 
         var d = deltas.concat();

lib/ace/edit_session.js

@@ -1127,6 +1127,12 @@ var EditSession = function(text, mode) {
     this.getTextRange = function(range) {
         return this.doc.getTextRange(range || this.selection.getRange());
     };
+    
+    // Deprecated method retained for backwards compatibility.
+    this.insert = function(position, text){
+        console.log('Warning: editsession.insert is deprecated. Use the insertText method instead.');
+        return this.insertText(position, text)
+    }
 
     /**
      * Inserts a block of `text` and the indicated `position`.

lib/ace/edit_session_test.js

@@ -430,11 +430,11 @@ module.exports = {
         session.setTabSize(4);
         assert.equal(session.getScreenWidth(), 2);
 
-        session.doc.insertLines({row: 0, column: Infinity}, ['', '']);
+        session.doc.insertMergedLines({row: 0, column: Infinity}, ['', '']);
         session.doc.insertFullLines(1, ["123"]);
         assert.equal(session.getScreenWidth(), 3);
 
-        session.doc.insertLines({row: 0, column: Infinity}, ['', '']);
+        session.doc.insertMergedLines({row: 0, column: Infinity}, ['', '']);
         session.doc.insertFullLines(1, ["\t\t"]);
 
         assert.equal(session.getScreenWidth(), 8);

lib/ace/editor.js

@@ -825,6 +825,12 @@ var Editor = function(renderer, session) {
     this.execCommand = function(command, args) {
         this.commands.exec(command, this, args);
     };
+    
+    // Deprecated method retained for backwards compatibility.
+    this.insert = function(text){
+        console.log('Warning: editor.insert is deprecated. Use the insertText method instead.');
+        return this.insertText(text)
+    }
 
     /**
      * Inserts `text` into wherever the cursor is pointing.

lib/ace/placeholder.js

@@ -167,7 +167,7 @@ var PlaceHolder = function(session, length, pos, others, mainClass, othersClass)
                         var newPos = {row: otherPos.row, column: otherPos.column + distanceFromStart};
                         if(otherPos.row === range.start.row && range.start.column < otherPos.column)
                             newPos.column += lengthDiff;
-                        this.doc.insertLines(newPos, delta.lines);
+                        this.doc.insertMergedLines(newPos, delta.lines);
                     }
                 } else if(delta.action === "delete") {
                     for (var i = this.others.length - 1; i >= 0; i--) {