From 1e8ef3bb6af45110001294b3ab70d80955b7f6fc Mon Sep 17 00:00:00 2001 From: Constantin Jucovschi Date: Sun, 26 Feb 2012 10:27:56 +0000 Subject: [PATCH 1/4] commented general functions --- static/js/Changeset.js | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/static/js/Changeset.js b/static/js/Changeset.js index 715836d5f..78066e29f 100644 --- a/static/js/Changeset.js +++ b/static/js/Changeset.js @@ -29,12 +29,17 @@ var AttributePoolFactory = require("/AttributePoolFactory"); var _opt = null; -//var exports = {}; +// ==================== General Util Functions ======================= + +// This method is called whenever there is an error in the sync process exports.error = function error(msg) { var e = new Error(msg); e.easysync = true; throw e; }; + +// This method is user for assertions with Messages +// if assert fails, the error function called. exports.assert = function assert(b, msgParts) { if (!b) { var msg = Array.prototype.slice.call(arguments, 1).join(''); @@ -42,12 +47,17 @@ exports.assert = function assert(b, msgParts) { } }; +// Parses a number from string base 36 exports.parseNum = function (str) { return parseInt(str, 36); }; + +// Writes a number in base 36 and puts it in a string exports.numToString = function (num) { return num.toString(36).toLowerCase(); }; + +// Converts stuff before $ to base 10 exports.toBaseTen = function (cs) { var dollarIndex = cs.indexOf('$'); var beforeDollar = cs.substring(0, dollarIndex); @@ -57,6 +67,9 @@ exports.toBaseTen = function (cs) { }) + fromDollar; }; + +// ==================== Changeset Functions ======================= + exports.oldLen = function (cs) { return exports.unpack(cs).oldLen; }; From 3abdd3416085bab5b0d598bc5ae52f2939513a56 Mon Sep 17 00:00:00 2001 From: Constantin Jucovschi Date: Sun, 26 Feb 2012 11:22:46 +0000 Subject: [PATCH 2/4] writing in jsdoc syntax --- static/js/Changeset.js | 56 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/static/js/Changeset.js b/static/js/Changeset.js index 78066e29f..e6f92b202 100644 --- a/static/js/Changeset.js +++ b/static/js/Changeset.js @@ -29,17 +29,26 @@ var AttributePoolFactory = require("/AttributePoolFactory"); var _opt = null; -// ==================== General Util Functions ======================= +/** + * ==================== General Util Functions ======================= + */ -// This method is called whenever there is an error in the sync process +/** + * This method is called whenever there is an error in the sync process + * @param msg {string} Just some message + */ exports.error = function error(msg) { var e = new Error(msg); e.easysync = true; throw e; }; -// This method is user for assertions with Messages -// if assert fails, the error function called. +/** + * This method is user for assertions with Messages + * if assert fails, the error function called. + * @param b {boolean} assertion condition + * @param msgParts {string} error to be passed if it fails + */ exports.assert = function assert(b, msgParts) { if (!b) { var msg = Array.prototype.slice.call(arguments, 1).join(''); @@ -47,17 +56,30 @@ exports.assert = function assert(b, msgParts) { } }; -// Parses a number from string base 36 +/** + * Parses a number from string base 36 + * @param str {string} string of the number in base 36 + * @returns {int} number + */ exports.parseNum = function (str) { return parseInt(str, 36); }; -// Writes a number in base 36 and puts it in a string +/** + * Writes a number in base 36 and puts it in a string + * @param num {int} number + * @returns {string} string + */ exports.numToString = function (num) { return num.toString(36).toLowerCase(); }; -// Converts stuff before $ to base 10 +/** + * Converts stuff before $ to base 10 + * @obsolete not really used anywhere?? + * @param cs {string} the string + * @return integer + */ exports.toBaseTen = function (cs) { var dollarIndex = cs.indexOf('$'); var beforeDollar = cs.substring(0, dollarIndex); @@ -68,15 +90,33 @@ exports.toBaseTen = function (cs) { }; -// ==================== Changeset Functions ======================= +/** + * ==================== Changeset Functions ======================= + */ +/** + * returns the required length of the text before changeset + * can be applied + * @param cs {string} String representation of the Changeset + */ exports.oldLen = function (cs) { return exports.unpack(cs).oldLen; }; + +/** + * returns the length of the text after changeset is applied + * @param cs {string} String representation of the Changeset + */ exports.newLen = function (cs) { return exports.unpack(cs).newLen; }; +/** + * this function creates an iterator which decodes string changeset operations + * @param opsStr {string} String encoding of the change operations to be performed + * @param optStartIndex {int} from where in the string should the iterator start + * @return {Op} type object iterator + */ exports.opIterator = function (opsStr, optStartIndex) { //print(opsStr); var regex = /((?:\*[0-9a-z]+)*)(?:\|([0-9a-z]+))?([-+=])([0-9a-z]+)|\?|/g; From ac86535cdf0e6f6282385e246725334a826d2acc Mon Sep 17 00:00:00 2001 From: Constantin Jucovschi Date: Sun, 26 Feb 2012 11:34:06 +0000 Subject: [PATCH 3/4] more docs --- static/js/Changeset.js | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/static/js/Changeset.js b/static/js/Changeset.js index e6f92b202..ee99e76c1 100644 --- a/static/js/Changeset.js +++ b/static/js/Changeset.js @@ -182,12 +182,21 @@ exports.opIterator = function (opsStr, optStartIndex) { }; }; +/** + * Cleans an Op object + * @param {Op} object to be cleared + */ exports.clearOp = function (op) { op.opcode = ''; op.chars = 0; op.lines = 0; op.attribs = ''; }; + +/** + * Creates a new Op object + * @param optOpcode the type operation of the Op object + */ exports.newOp = function (optOpcode) { return { opcode: (optOpcode || ''), @@ -196,6 +205,11 @@ exports.newOp = function (optOpcode) { attribs: '' }; }; + +/** + * Clones an Op + * @param op Op to be cloned + */ exports.cloneOp = function (op) { return { opcode: op.opcode, @@ -204,12 +218,22 @@ exports.cloneOp = function (op) { attribs: op.attribs }; }; + +/** + * Copies op1 to op2 + * @param op1 src Op + * @param op2 dest Op + */ exports.copyOp = function (op1, op2) { op2.opcode = op1.opcode; op2.chars = op1.chars; op2.lines = op1.lines; op2.attribs = op1.attribs; }; + +/** + * Writes the Op in a string the way that changesets need it + */ exports.opString = function (op) { // just for debugging if (!op.opcode) return 'null'; @@ -217,11 +241,19 @@ exports.opString = function (op) { assem.append(op); return assem.toString(); }; + +/** + * Used just for debugging + */ exports.stringOp = function (str) { // just for debugging return exports.opIterator(str).next(); }; +/** + * Used to check if a Changeset if valid + * @param cs {Changeset} Changeset to be checked + */ exports.checkRep = function (cs) { // doesn't check things that require access to attrib pool (e.g. attribute order) // or original string (e.g. newline positions) @@ -271,6 +303,10 @@ exports.checkRep = function (cs) { return cs; } + +/** + * ==================== Changeset Functions ======================= + */ exports.smartOpAssembler = function () { // Like opAssembler but able to produce conforming exportss // from slightly looser input, at the cost of speed. From e318e3d4cb59c9be2ee5831bb03f2787f3c0371a Mon Sep 17 00:00:00 2001 From: Constantin Jucovschi Date: Sun, 26 Feb 2012 12:18:17 +0000 Subject: [PATCH 4/4] some new docs --- static/js/Changeset.js | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/static/js/Changeset.js b/static/js/Changeset.js index ee99e76c1..42a8f0dc1 100644 --- a/static/js/Changeset.js +++ b/static/js/Changeset.js @@ -305,7 +305,12 @@ exports.checkRep = function (cs) { /** - * ==================== Changeset Functions ======================= + * ==================== Util Functions ======================= + */ + +/** + * creates an object that allows you to append operations (type Op) and also + * compresses them if possible */ exports.smartOpAssembler = function () { // Like opAssembler but able to produce conforming exportss @@ -563,6 +568,10 @@ if (_opt) { }; } +/** + * A custom made String Iterator + * @param str {string} String to be iterated over + */ exports.stringIterator = function (str) { var curIndex = 0; @@ -599,6 +608,9 @@ exports.stringIterator = function (str) { }; }; +/** + * A custom made StringBuffer + */ exports.stringAssembler = function () { var pieces = []; @@ -891,6 +903,11 @@ exports.applyZip = function (in1, idx1, in2, idx2, func) { return assem.toString(); }; +/** + * Unpacks a string encoded Changeset into a proper Changeset object + * @params cs {string} String encoded Changeset + * @returns {Changeset} a Changeset class + */ exports.unpack = function (cs) { var headerRegex = /Z:([0-9a-z]+)([><])([0-9a-z]+)|/; var headerMatch = headerRegex.exec(cs); @@ -912,6 +929,14 @@ exports.unpack = function (cs) { }; }; +/** + * Packs Changeset object into a string + * @params oldLen {int} Old length of the Changeset + * @params newLen {int] New length of the Changeset + * @params opsStr {string} String encoding of the changes to be made + * @params bank {string} Charbank of the Changeset + * @returns {Changeset} a Changeset class + */ exports.pack = function (oldLen, newLen, opsStr, bank) { var lenDiff = newLen - oldLen; var lenDiffStr = (lenDiff >= 0 ? '>' + exports.numToString(lenDiff) : '<' + exports.numToString(-lenDiff)); @@ -920,6 +945,11 @@ exports.pack = function (oldLen, newLen, opsStr, bank) { return a.join(''); }; +/** + * Applies a Changeset to a string + * @params cs {string} String encoded Changeset + * @params str {string} String to which a Changeset should be applied + */ exports.applyToText = function (cs, str) { var unpacked = exports.unpack(cs); exports.assert(str.length == unpacked.oldLen, "mismatched apply: ", str.length, " / ", unpacked.oldLen); @@ -1499,6 +1529,12 @@ exports.mapAttribNumbers = function (cs, func) { return newUpToDollar + cs.substring(dollarPos); }; +/** + * Create a Changeset going from Identity to a certain state + * @params text {string} text of the final change + * @attribs attribs {string} optional, operations which insert + * the text and also puts the right attributes + */ exports.makeAText = function (text, attribs) { return { text: text,