PR feedback: moved crawler and its constituent parts into coerce

Author: monfera

src/lib/coerce.js

@@ -12,12 +12,17 @@
 var isNumeric = require('fast-isnumeric');
 var tinycolor = require('tinycolor2');
 var nestedProperty = require('./nested_property');
+var isPlainObject = require('./is_plain_object');
 
 var getColorscale = require('../components/colorscale/get_scale');
 var colorscaleNames = Object.keys(require('../components/colorscale/scales'));
 
 var idRegex = /^([2-9]|[1-9][0-9]+)$/;
 
+function isValObject(obj) {
+    return obj && obj.valType !== undefined;
+}
+
 exports.valObjects = {
     data_array: {
         // You can use *dflt=[] to force said array to exist though.
@@ -359,6 +364,48 @@ exports.validate = function(value, opts) {
 /*
  * returns true for a valid value object and false for tree nodes in the attribute hierarchy
  */
-exports.isValObject = function(obj) {
-    return obj && obj.valType !== undefined;
+exports.isValObject = isValObject;
+
+exports.IS_SUBPLOT_OBJ = '_isSubplotObj';
+exports.IS_LINKED_TO_ARRAY = '_isLinkedToArray';
+exports.DEPRECATED = '_deprecated';
+
+// list of underscore attributes to keep in schema as is
+exports.UNDERSCORE_ATTRS = [exports.IS_SUBPLOT_OBJ, exports.IS_LINKED_TO_ARRAY, exports.DEPRECATED];
+
+/**
+ * Crawl the attribute tree, recursively calling a callback function
+ *
+ * @param {object} attrs
+ *  The node of the attribute tree (e.g. the root) from which recursion originates
+ * @param {Function} callback
+ *  A callback function with the signature:
+ *          @callback callback
+ *          @param {object} attr an attribute
+ *          @param {String} attrName name string
+ *          @param {object[]} attrs all the attributes
+ *          @param {Number} level the recursion level, 0 at the root
+ * @param {Number} [specifiedLevel]
+ *  The level in the tree, in order to let the callback function detect descend or backtrack,
+ *  typically unsupplied (implied 0), just used by the self-recursive call.
+ *  The necessity arises because the tree traversal is not controlled by callback return values.
+ *  The decision to not use callback return values for controlling tree pruning arose from
+ *  the goal of keeping the crawler backwards compatible. Observe that one of the pruning conditions
+ *  precedes the callback call.
+ *
+ * @return {object} transformOut
+ *  copy of transformIn that contains attribute defaults
+ */
+exports.crawl = function(attrs, callback, specifiedLevel) {
+    var level = specifiedLevel || 0;
+    Object.keys(attrs).forEach(function(attrName) {
+        var attr = attrs[attrName];
+
+        if(exports.UNDERSCORE_ATTRS.indexOf(attrName) !== -1) return;
+
+        callback(attr, attrName, attrs, level);
+
+        if(isValObject(attr)) return;
+        if(isPlainObject(attr)) exports.crawl(attr, callback, level + 1);
+    });
 };

src/lib/index.js

@@ -24,6 +24,11 @@ lib.coerce2 = coerceModule.coerce2;
 lib.coerceFont = coerceModule.coerceFont;
 lib.validate = coerceModule.validate;
 lib.isValObject = coerceModule.isValObject;
+lib.crawl = coerceModule.crawl;
+lib.IS_SUBPLOT_OBJ = coerceModule.IS_SUBPLOT_OBJ;
+lib.IS_LINKED_TO_ARRAY = coerceModule.IS_LINKED_TO_ARRAY;
+lib.DEPRECATED = coerceModule.DEPRECATED;
+lib.UNDERSCORE_ATTRS = coerceModule.UNDERSCORE_ATTRS;
 
 var datesModule = require('./dates');
 lib.dateTime2ms = datesModule.dateTime2ms;

src/plot_api/crawler.js

@@ -13,7 +13,6 @@ var Plotly = require('../plotly');
 var Registry = require('../registry');
 var Plots = require('../plots/plots');
 var Lib = require('../lib');
-var crawler = require('./crawler');
 
 // FIXME polar attribute are not part of Plotly yet
 var polarAreaAttrs = require('../plots/polar/area_attributes');
@@ -51,7 +50,7 @@ PlotSchema.get = function() {
     return plotSchema;
 };
 
-PlotSchema.crawl = crawler.crawl;
+PlotSchema.crawl = Lib.crawl;
 
 PlotSchema.isValObject = Lib.isValObject;
 
@@ -140,7 +139,7 @@ function getTransformAttributes(name) {
 function getDefs() {
     plotSchema.defs = {
         valObjects: Lib.valObjects,
-        metaKeys: crawler.UNDERSCORE_ATTRS.concat(['description', 'role'])
+        metaKeys: Lib.UNDERSCORE_ATTRS.concat(['description', 'role'])
     };
 }
 
@@ -223,7 +222,7 @@ function mergeValTypeAndRole(attrs) {
         }
     }
 
-    crawler.crawl(attrs, callback);
+    Lib.crawl(attrs, callback);
 }
 
 // helper methods
@@ -249,7 +248,7 @@ function getModule(arg) {
 function removeUnderscoreAttrs(attributes) {
     Object.keys(attributes).forEach(function(k) {
         if(k.charAt(0) === '_' &&
-            crawler.UNDERSCORE_ATTRS.indexOf(k) === -1) delete attributes[k];
+            Lib.UNDERSCORE_ATTRS.indexOf(k) === -1) delete attributes[k];
     });
     return attributes;
 }
@@ -303,7 +302,7 @@ function handleSubplotObjs(layoutAttributes) {
                 isSubplotObj = subplotRegistry.attrRegex.test(k);
             }
 
-            if(isSubplotObj) layoutAttributes[k][crawler.IS_SUBPLOT_OBJ] = true;
+            if(isSubplotObj) layoutAttributes[k][Lib.IS_SUBPLOT_OBJ] = true;
         });
     });
 
@@ -313,17 +312,17 @@ function handleSubplotObjs(layoutAttributes) {
 function handleLinkedToArray(layoutAttributes) {
 
     function callback(attr, attrName, attrs) {
-        if(attr[crawler.IS_LINKED_TO_ARRAY] !== true) return;
+        if(attr[Lib.IS_LINKED_TO_ARRAY] !== true) return;
 
         // TODO more robust logic
         var itemName = attrName.substr(0, attrName.length - 1);
 
-        delete attr[crawler.IS_LINKED_TO_ARRAY];
+        delete attr[Lib.IS_LINKED_TO_ARRAY];
 
         attrs[attrName] = { items: {} };
         attrs[attrName].items[itemName] = attr;
         attrs[attrName].role = 'object';
     }
 
-    crawler.crawl(layoutAttributes, callback);
+    Lib.crawl(layoutAttributes, callback);
 }

src/plot_api/plot_schema.js

@@ -9,7 +9,6 @@
 
 'use strict';
 
-var crawler = require('./../plot_api/crawler');
 var d3 = require('d3');
 var isNumeric = require('fast-isnumeric');
 
@@ -815,7 +814,7 @@ function applyTransforms(fullTrace, fullData, layout) {
             }
         }
 
-        crawler.crawl(trace._module.attributes, callback);
+        Lib.crawl(trace._module.attributes, callback);
 
         return arraySplitAttributes;
     });

src/plots/plots.js

@@ -10,7 +10,7 @@ Plotly.register([
     require('@src/transforms/groupby')
 ]);
 
-fdescribe('groupby', function() {
+describe('groupby', function() {
 
     describe('one-to-many transforms:', function() {
         'use strict';
@@ -511,15 +511,15 @@ fdescribe('groupby', function() {
         it('passes with lots of attributes and heterogenous attrib presence', test(mockData2));
 
         it('passes with group styles partially overriding top level aesthetics', test(mockData3));
-        it('passes extended tests with group styles partially overriding top level aesthetics', function (done) {
+        it('passes extended tests with group styles partially overriding top level aesthetics', function(done) {
             var data = Lib.extendDeep([], mockData3);
             var gd = createGraphDiv();
             Plotly.plot(gd, data).then(function() {
                 expect(gd._fullData[0].marker.line.color).toEqual(['orange', 'red', 'cyan', 'pink']);
                 expect(gd._fullData[1].marker.line.color).toEqual('yellow');
                 done();
             });
-        }        );
+        });
 
         it('passes with no explicit styling for the individual group', test(mockData4));
 
@@ -542,12 +542,12 @@ fdescribe('groupby', function() {
             marker: {size: 20, line: {width: [4, 2, 4, 2, 2, 3, 3]}},
             transforms: [{
                 type: 'groupby',
-                //groups: ['a', 'a', 'b', 'a', 'b', 'b', 'a'],
+                // groups: ['a', 'a', 'b', 'a', 'b', 'b', 'a'],
                 style: { a: {marker: {color: 'red'}}, b: {marker: {color: 'blue'}} }
             }]
         }];
 
-        it("passes", function(done) {
+        it('passes', function(done) {
             var data = Lib.extendDeep([], mockData);
 
             var gd = createGraphDiv();