From 90fdaab9d79841a7ba4598755c3528967068ac2a Mon Sep 17 00:00:00 2001 From: Tom MacWright Date: Wed, 2 Feb 2011 16:47:33 -0500 Subject: [PATCH] Document tree items as well, fix up a few of their documentations --- Makefile | 2 +- lib/mess/tree/definition.js | 36 +++++++++++++++++++++++++----------- lib/mess/tree/element.js | 21 +++++++++------------ lib/mess/tree/filter.js | 10 ++++++---- lib/mess/tree/zoom.js | 14 ++++++++++---- 5 files changed, 51 insertions(+), 32 deletions(-) diff --git a/Makefile b/Makefile index 7ce1e89..ab44b13 100644 --- a/Makefile +++ b/Makefile @@ -11,6 +11,6 @@ test: endif doc: - docco lib/mess/*.js + docco lib/mess/*.js lib/mess/tree/*.js .PHONY: test diff --git a/lib/mess/tree/definition.js b/lib/mess/tree/definition.js index c5f6fca..8249484 100644 --- a/lib/mess/tree/definition.js +++ b/lib/mess/tree/definition.js @@ -12,11 +12,9 @@ tree.Definition.prototype.clone = function() { return obj; }; -/** - * Return a copy of this ruleset with only - * rules related to a specific symbolizer, but otherwise identical - * selectors. - */ +// Return a copy of this ruleset with only +// rules related to a specific symbolizer, but otherwise identical +// selectors. tree.Definition.prototype.filterSymbolizer = function(symbolizer) { var newDefinition = this.clone(); newDefinition.rules = newDefinition.rules.filter(function(rule) { @@ -25,6 +23,9 @@ tree.Definition.prototype.filterSymbolizer = function(symbolizer) { return newDefinition; }; +// Get a list of all of the symbolizer types +// that this definition will affect as a result of +// its rules. tree.Definition.prototype.symbolizers = function() { // reduce used to make the result of this // an array of unique values. @@ -36,10 +37,8 @@ tree.Definition.prototype.symbolizers = function() { }, []); }; -/** - * Find a rule by name within this ruleset, - * returning it if possible. Otherwise not returning. - */ +// Find a rule by name within this ruleset, +// returning it if possible. Otherwise not returning. tree.Definition.prototype.hasRule = function(name) { this.rules_cache = (!this.dirty && this.rules_cache) ? this.rules_cache @@ -50,6 +49,9 @@ tree.Definition.prototype.hasRule = function(name) { return this.rules_cache[name]; }; +// Take all of the rules from a given definition that +// this definition doesn't have already, and add them to this +// definition. tree.Definition.prototype.inheritFrom = function(definition) { for (var i = 0; i < definition.rules.length; i++) { if (!this.hasRule(definition.rules[i].name)) { @@ -59,6 +61,9 @@ tree.Definition.prototype.inheritFrom = function(definition) { } }; +// Get all of the unique rules in this definition, in +// specificity order. Mapnik doesn't allow multiple attributes +// in Symbolizers. tree.Definition.prototype.unique_rules = function() { if (this.unique_rules_cache) return this.unique_rules_cache; var rules = {}, @@ -73,6 +78,7 @@ tree.Definition.prototype.unique_rules = function() { }; tree.Definition.prototype.toXML = function(env) { + // Return a cached compilation if one is available. if (this._xml) return this._xml; var sym = this.symbolizers(); @@ -86,17 +92,25 @@ tree.Definition.prototype.toXML = function(env) { } if (sym) { + // Some Mapnik symbolizers, like TextSymbolizer, don't + // have defaults for all properties and will fail if they + // aren't given. Thus, at the last minute check that these + // are satisfied. if (reqfail = tree.Reference.requiredProperties( sym, this.unique_rules())) { env.error({ message: reqfail, - index: this.unique_rules()[0] && this.unique_rules()[0].index, - index: this.unique_rules()[0] && this.unique_rules()[0].filename + index: this.unique_rules()[0] && + this.unique_rules()[0].index, + index: this.unique_rules()[0] && + this.unique_rules()[0].filename }); } } + // Come up with a symbolizer name based on the name from + // Reference. var symname = sym ? sym.charAt(0).toUpperCase() + sym.slice(1).replace(/\-./, function(str) { return str[1].toUpperCase(); diff --git a/lib/mess/tree/element.js b/lib/mess/tree/element.js index de8d8a0..4cc778f 100644 --- a/lib/mess/tree/element.js +++ b/lib/mess/tree/element.js @@ -1,13 +1,12 @@ (function(tree) { +// An element is an id or class selector tree.Element = function Element(value) { this.value = value.trim(); }; -/** - * Determine the 'specificity matrix' of this - * specific selector - */ +// Determine the 'specificity matrix' of this +// specific selector tree.Element.prototype.specificity = function() { return [ (this.value[0] == '#') ? 1 : 0, // a @@ -19,14 +18,12 @@ tree.Element.prototype.toString = function() { return this.value; }; -/** - * Determine whether this element matches an id or classes. - * An element is a single id or class, or check whether the given - * array of classes contains this, or the id is equal to this. - * - * Takes a plain string for id and plain strings in the array of - * classes. - */ +// Determine whether this element matches an id or classes. +// An element is a single id or class, or check whether the given +// array of classes contains this, or the id is equal to this. +// +// Takes a plain string for id and plain strings in the array of +// classes. tree.Element.prototype.matches = function(id, classes) { return (classes.indexOf(this.value.replace(/^\./, '')) !== -1) || (this.value.replace(/^#/, '') == id); diff --git a/lib/mess/tree/filter.js b/lib/mess/tree/filter.js index 0e6e583..751542c 100644 --- a/lib/mess/tree/filter.js +++ b/lib/mess/tree/filter.js @@ -17,6 +17,7 @@ tree.Filter = function Filter(key, op, val, index) { }; +// XML-safe versions of comparators var opXML = { '<': '<', '>': '>', @@ -26,6 +27,7 @@ var opXML = { '>=': '>=' }; +// inverses of comparators var opNegate = { '<': '>=', '<=': '>', @@ -49,10 +51,8 @@ tree.Filter.prototype.toString = function() { return '[' + this.id + ']'; }; -/** - * Negate this filter: warning - this changes - * the filter itself. - */ +// Negate this filter: warning - this changes +// the filter itself. tree.Filter.prototype.negate = function() { return new tree.Filter(this.key, opNegate[this.op], this.val); }; @@ -245,6 +245,8 @@ tree.Filter.simplify = function(filters) { return filters; }; +// Test two rules to decide whether one can be merged into the other. +// returns the rule that the other rule can be merged into. tree.Filter.mergable = function(f1, f2) { var filters1 = Object.keys(f1); var filters2 = Object.keys(f2); diff --git a/lib/mess/tree/zoom.js b/lib/mess/tree/zoom.js index c19239d..962f88e 100644 --- a/lib/mess/tree/zoom.js +++ b/lib/mess/tree/zoom.js @@ -1,10 +1,14 @@ var tree = require('mess/tree'); +// Storage for zoom ranges. Only supports continuous ranges, +// and stores them as bit-sequences so that they can be combined, +// inverted, and compared quickly. tree.Zoom = function(op, value, index) { value = parseInt(value); if (value > tree.Zoom.maxZoom || value < 0) { throw { - message: 'Only zoom levels between 0 and ' + tree.Zoom.maxZoom + ' supported.', + message: 'Only zoom levels between 0 and ' + + tree.Zoom.maxZoom + ' supported.', index: index }; } @@ -57,7 +61,7 @@ tree.Zoom.ranges = { 23: 50 }; -// Only works for single range zooms. [XXX....XXXXX.........] is invalid. +// Only works for single range zooms. `[XXX....XXXXX.........]` is invalid. tree.Zoom.toXML = function(zoom) { var conditions = []; if (zoom != tree.Zoom.all) { @@ -68,8 +72,10 @@ tree.Zoom.toXML = function(zoom) { end = i; } } - if (start > 0) conditions.push('' + tree.Zoom.ranges[start] + ''); - if (end < 22) conditions.push('' + tree.Zoom.ranges[end + 1] + ''); + if (start > 0) conditions.push('' + + tree.Zoom.ranges[start] + ''); + if (end < 22) conditions.push('' + + tree.Zoom.ranges[end + 1] + ''); } return conditions; };