The Tor Browser: comparison toolkit/devtools/gcli/Templater.jsm

--1:000000000000
+:3036a461562f
+/*
+* Copyright 2012, Mozilla Foundation and contributors
+*
+* Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+this.EXPORTED_SYMBOLS = [ "template" ];
+Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
+XPCOMUtils.defineLazyModuleGetter(this, "console",
+"resource://gre/modules/devtools/Console.jsm");
+'do not use strict';
+// WARNING: do not 'use strict' without reading the notes in envEval();
+// Also don't remove the 'do not use strict' marker. The orion build uses these
+// markers to know where to insert AMD headers.
+/**
+* For full documentation, see:
+* https://github.com/mozilla/domtemplate/blob/master/README.md
+*/
+/**
+* Begin a new templating process.
+* @param node A DOM element or string referring to an element's id
+* @param data Data to use in filling out the template
+* @param options Options to customize the template processing. One of:
+* - allowEval: boolean (default false) Basic template interpolations are
+*   either property paths (e.g. ${a.b.c.d}), or if allowEval=true then we
+*   allow arbitrary JavaScript
+* - stack: string or array of strings (default empty array) The template
+*   engine maintains a stack of tasks to help debug where it is. This allows
+*   this stack to be prefixed with a template name
+* - blankNullUndefined: By default DOMTemplate exports null and undefined
+*   values using the strings 'null' and 'undefined', which can be helpful for
+*   debugging, but can introduce unnecessary extra logic in a template to
+*   convert null/undefined to ''. By setting blankNullUndefined:true, this
+*   conversion is handled by DOMTemplate
+*/
+var template = function(node, data, options) {
+var state = {
+options: options || {},
+// We keep a track of the nodes that we've passed through so we can keep
+// data.__element pointing to the correct node
+nodes: []
+};
+state.stack = state.options.stack;
+if (!Array.isArray(state.stack)) {
+if (typeof state.stack === 'string') {
+state.stack = [ options.stack ];
+}
+else {
+state.stack = [];
+}
+}
+processNode(state, node, data);
+};
+//
+//
+//
+/**
+* Helper for the places where we need to act asynchronously and keep track of
+* where we are right now
+*/
+function cloneState(state) {
+return {
+options: state.options,
+stack: state.stack.slice(),
+nodes: state.nodes.slice()
+};
+}
+/**
+* Regex used to find ${...} sections in some text.
+* Performance note: This regex uses ( and ) to capture the 'script' for
+* further processing. Not all of the uses of this regex use this feature so
+* if use of the capturing group is a performance drain then we should split
+* this regex in two.
+*/
+var TEMPLATE_REGION = /\$\{([^}]*)\}/g;
+/**
+* Recursive function to walk the tree processing the attributes as it goes.
+* @param node the node to process. If you pass a string in instead of a DOM
+* element, it is assumed to be an id for use with document.getElementById()
+* @param data the data to use for node processing.
+*/
+function processNode(state, node, data) {
+if (typeof node === 'string') {
+node = document.getElementById(node);
+}
+if (data == null) {
+data = {};
+}
+state.stack.push(node.nodeName + (node.id ? '#' + node.id : ''));
+var pushedNode = false;
+try {
+// Process attributes
+if (node.attributes && node.attributes.length) {
+// We need to handle 'foreach' and 'if' first because they might stop
+// some types of processing from happening, and foreach must come first
+// because it defines new data on which 'if' might depend.
+if (node.hasAttribute('foreach')) {
+processForEach(state, node, data);
+return;
+}
+if (node.hasAttribute('if')) {
+if (!processIf(state, node, data)) {
+return;
+}
+}
+// Only make the node available once we know it's not going away
+state.nodes.push(data.__element);
+data.__element = node;
+pushedNode = true;
+// It's good to clean up the attributes when we've processed them,
+// but if we do it straight away, we mess up the array index
+var attrs = Array.prototype.slice.call(node.attributes);
+for (var i = 0; i < attrs.length; i++) {
+var value = attrs[i].value;
+var name = attrs[i].name;
+state.stack.push(name);
+try {
+if (name === 'save') {
+// Save attributes are a setter using the node
+value = stripBraces(state, value);
+property(state, value, data, node);
+node.removeAttribute('save');
+}
+else if (name.substring(0, 2) === 'on') {
+// If this attribute value contains only an expression
+if (value.substring(0, 2) === '${' && value.slice(-1) === '}' &&
+value.indexOf('${', 2) === -1) {
+value = stripBraces(state, value);
+var func = property(state, value, data);
+if (typeof func === 'function') {
+node.removeAttribute(name);
+var capture = node.hasAttribute('capture' + name.substring(2));
+node.addEventListener(name.substring(2), func, capture);
+if (capture) {
+node.removeAttribute('capture' + name.substring(2));
+}
+}
+else {
+// Attribute value is not a function - use as a DOM-L0 string
+node.setAttribute(name, func);
+}
+}
+else {
+// Attribute value is not a single expression use as DOM-L0
+node.setAttribute(name, processString(state, value, data));
+}
+}
+else {
+node.removeAttribute(name);
+// Remove '_' prefix of attribute names so the DOM won't try
+// to use them before we've processed the template
+if (name.charAt(0) === '_') {
+name = name.substring(1);
+}
+// Async attributes can only work if the whole attribute is async
+var replacement;
+if (value.indexOf('${') === 0 &&
+value.charAt(value.length - 1) === '}') {
+replacement = envEval(state, value.slice(2, -1), data, value);
+if (replacement && typeof replacement.then === 'function') {
+node.setAttribute(name, '');
+replacement.then(function(newValue) {
+node.setAttribute(name, newValue);
+}).then(null, console.error);
+}
+else {
+if (state.options.blankNullUndefined && replacement == null) {
+replacement = '';
+}
+node.setAttribute(name, replacement);
+}
+}
+else {
+node.setAttribute(name, processString(state, value, data));
+}
+}
+}
+finally {
+state.stack.pop();
+}
+}
+}
+// Loop through our children calling processNode. First clone them, so the
+// set of nodes that we visit will be unaffected by additions or removals.
+var childNodes = Array.prototype.slice.call(node.childNodes);
+for (var j = 0; j < childNodes.length; j++) {
+processNode(state, childNodes[j], data);
+}
+if (node.nodeType === 3 /*Node.TEXT_NODE*/) {
+processTextNode(state, node, data);
+}
+}
+finally {
+if (pushedNode) {
+data.__element = state.nodes.pop();
+}
+state.stack.pop();
+}
+}
+/**
+* Handle attribute values where the output can only be a string
+*/
+function processString(state, value, data) {
+return value.replace(TEMPLATE_REGION, function(path) {
+var insert = envEval(state, path.slice(2, -1), data, value);
+return state.options.blankNullUndefined && insert == null ? '' : insert;
+});
+}
+/**
+* Handle <x if="${...}">
+* @param node An element with an 'if' attribute
+* @param data The data to use with envEval()
+* @returns true if processing should continue, false otherwise
+*/
+function processIf(state, node, data) {
+state.stack.push('if');
+try {
+var originalValue = node.getAttribute('if');
+var value = stripBraces(state, originalValue);
+var recurse = true;
+try {
+var reply = envEval(state, value, data, originalValue);
+recurse = !!reply;
+}
+catch (ex) {
+handleError(state, 'Error with \'' + value + '\'', ex);
+recurse = false;
+}
+if (!recurse) {
+node.parentNode.removeChild(node);
+}
+node.removeAttribute('if');
+return recurse;
+}
+finally {
+state.stack.pop();
+}
+}
+/**
+* Handle <x foreach="param in ${array}"> and the special case of
+* <loop foreach="param in ${array}">.
+* This function is responsible for extracting what it has to do from the
+* attributes, and getting the data to work on (including resolving promises
+* in getting the array). It delegates to processForEachLoop to actually
+* unroll the data.
+* @param node An element with a 'foreach' attribute
+* @param data The data to use with envEval()
+*/
+function processForEach(state, node, data) {
+state.stack.push('foreach');
+try {
+var originalValue = node.getAttribute('foreach');
+var value = originalValue;
+var paramName = 'param';
+if (value.charAt(0) === '$') {
+// No custom loop variable name. Use the default: 'param'
+value = stripBraces(state, value);
+}
+else {
+// Extract the loop variable name from 'NAME in ${ARRAY}'
+var nameArr = value.split(' in ');
+paramName = nameArr[0].trim();
+value = stripBraces(state, nameArr[1].trim());
+}
+node.removeAttribute('foreach');
+try {
+var evaled = envEval(state, value, data, originalValue);
+var cState = cloneState(state);
+handleAsync(evaled, node, function(reply, siblingNode) {
+processForEachLoop(cState, reply, node, siblingNode, data, paramName);
+});
+node.parentNode.removeChild(node);
+}
+catch (ex) {
+handleError(state, 'Error with \'' + value + '\'', ex);
+}
+}
+finally {
+state.stack.pop();
+}
+}
+/**
+* Called by processForEach to handle looping over the data in a foreach loop.
+* This works with both arrays and objects.
+* Calls processForEachMember() for each member of 'set'
+* @param set The object containing the data to loop over
+* @param templNode The node to copy for each set member
+* @param sibling The sibling node to which we add things
+* @param data the data to use for node processing
+* @param paramName foreach loops have a name for the parameter currently being
+* processed. The default is 'param'. e.g. <loop foreach="param in ${x}">...
+*/
+function processForEachLoop(state, set, templNode, sibling, data, paramName) {
+if (Array.isArray(set)) {
+set.forEach(function(member, i) {
+processForEachMember(state, member, templNode, sibling,
+data, paramName, '' + i);
+});
+}
+else {
+for (var member in set) {
+if (set.hasOwnProperty(member)) {
+processForEachMember(state, member, templNode, sibling,
+data, paramName, member);
+}
+}
+}
+}
+/**
+* Called by processForEachLoop() to resolve any promises in the array (the
+* array itself can also be a promise, but that is resolved by
+* processForEach()). Handle <LOOP> elements (which are taken out of the DOM),
+* clone the template node, and pass the processing on to processNode().
+* @param member The data item to use in templating
+* @param templNode The node to copy for each set member
+* @param siblingNode The parent node to which we add things
+* @param data the data to use for node processing
+* @param paramName The name given to 'member' by the foreach attribute
+* @param frame A name to push on the stack for debugging
+*/
+function processForEachMember(state, member, templNode, siblingNode, data, paramName, frame) {
+state.stack.push(frame);
+try {
+var cState = cloneState(state);
+handleAsync(member, siblingNode, function(reply, node) {
+data[paramName] = reply;
+if (node.parentNode != null) {
+if (templNode.nodeName.toLowerCase() === 'loop') {
+for (var i = 0; i < templNode.childNodes.length; i++) {
+var clone = templNode.childNodes[i].cloneNode(true);
+node.parentNode.insertBefore(clone, node);
+processNode(cState, clone, data);
+}
+}
+else {
+var clone = templNode.cloneNode(true);
+clone.removeAttribute('foreach');
+node.parentNode.insertBefore(clone, node);
+processNode(cState, clone, data);
+}
+}
+delete data[paramName];
+});
+}
+finally {
+state.stack.pop();
+}
+}
+/**
+* Take a text node and replace it with another text node with the ${...}
+* sections parsed out. We replace the node by altering node.parentNode but
+* we could probably use a DOM Text API to achieve the same thing.
+* @param node The Text node to work on
+* @param data The data to use in calls to envEval()
+*/
+function processTextNode(state, node, data) {
+// Replace references in other attributes
+var value = node.data;
+// We can't use the string.replace() with function trick (see generic
+// attribute processing in processNode()) because we need to support
+// functions that return DOM nodes, so we can't have the conversion to a
+// string.
+// Instead we process the string as an array of parts. In order to split
+// the string up, we first replace '${' with '\uF001$' and '}' with '\uF002'
+// We can then split using \uF001 or \uF002 to get an array of strings
+// where scripts are prefixed with $.
+// \uF001 and \uF002 are just unicode chars reserved for private use.
+value = value.replace(TEMPLATE_REGION, '\uF001$$$1\uF002');
+// Split a string using the unicode chars F001 and F002.
+var parts = value.split(/\uF001|\uF002/);
+if (parts.length > 1) {
+parts.forEach(function(part) {
+if (part === null || part === undefined || part === '') {
+return;
+}
+if (part.charAt(0) === '$') {
+part = envEval(state, part.slice(1), data, node.data);
+}
+var cState = cloneState(state);
+handleAsync(part, node, function(reply, siblingNode) {
+var doc = siblingNode.ownerDocument;
+if (reply == null) {
+reply = cState.options.blankNullUndefined ? '' : '' + reply;
+}
+if (typeof reply.cloneNode === 'function') {
+// i.e. if (reply instanceof Element) { ...
+reply = maybeImportNode(cState, reply, doc);
+siblingNode.parentNode.insertBefore(reply, siblingNode);
+}
+else if (typeof reply.item === 'function' && reply.length) {
+// NodeLists can be live, in which case maybeImportNode can
+// remove them from the document, and thus the NodeList, which in
+// turn breaks iteration. So first we clone the list
+var list = Array.prototype.slice.call(reply, 0);
+list.forEach(function(child) {
+var imported = maybeImportNode(cState, child, doc);
+siblingNode.parentNode.insertBefore(imported, siblingNode);
+});
+}
+else {
+// if thing isn't a DOM element then wrap its string value in one
+reply = doc.createTextNode(reply.toString());
+siblingNode.parentNode.insertBefore(reply, siblingNode);
+}
+});
+});
+node.parentNode.removeChild(node);
+}
+}
+/**
+* Return node or a import of node, if it's not in the given document
+* @param node The node that we want to be properly owned
+* @param doc The document that the given node should belong to
+* @return A node that belongs to the given document
+*/
+function maybeImportNode(state, node, doc) {
+return node.ownerDocument === doc ? node : doc.importNode(node, true);
+}
+/**
+* A function to handle the fact that some nodes can be promises, so we check
+* and resolve if needed using a marker node to keep our place before calling
+* an inserter function.
+* @param thing The object which could be real data or a promise of real data
+* we use it directly if it's not a promise, or resolve it if it is.
+* @param siblingNode The element before which we insert new elements.
+* @param inserter The function to to the insertion. If thing is not a promise
+* then handleAsync() is just 'inserter(thing, siblingNode)'
+*/
+function handleAsync(thing, siblingNode, inserter) {
+if (thing != null && typeof thing.then === 'function') {
+// Placeholder element to be replaced once we have the real data
+var tempNode = siblingNode.ownerDocument.createElement('span');
+siblingNode.parentNode.insertBefore(tempNode, siblingNode);
+thing.then(function(delayed) {
+inserter(delayed, tempNode);
+if (tempNode.parentNode != null) {
+tempNode.parentNode.removeChild(tempNode);
+}
+}).then(null, function(error) {
+console.error(error.stack);
+});
+}
+else {
+inserter(thing, siblingNode);
+}
+}
+/**
+* Warn of string does not begin '${' and end '}'
+* @param str the string to check.
+* @return The string stripped of ${ and }, or untouched if it does not match
+*/
+function stripBraces(state, str) {
+if (!str.match(TEMPLATE_REGION)) {
+handleError(state, 'Expected ' + str + ' to match ${...}');
+return str;
+}
+return str.slice(2, -1);
+}
+/**
+* Combined getter and setter that works with a path through some data set.
+* For example:
+* <ul>
+* <li>property(state, 'a.b', { a: { b: 99 }}); // returns 99
+* <li>property(state, 'a', { a: { b: 99 }}); // returns { b: 99 }
+* <li>property(state, 'a', { a: { b: 99 }}, 42); // returns 99 and alters the
+* input data to be { a: { b: 42 }}
+* </ul>
+* @param path An array of strings indicating the path through the data, or
+* a string to be cut into an array using <tt>split('.')</tt>
+* @param data the data to use for node processing
+* @param newValue (optional) If defined, this value will replace the
+* original value for the data at the path specified.
+* @return The value pointed to by <tt>path</tt> before any
+* <tt>newValue</tt> is applied.
+*/
+function property(state, path, data, newValue) {
+try {
+if (typeof path === 'string') {
+path = path.split('.');
+}
+var value = data[path[0]];
+if (path.length === 1) {
+if (newValue !== undefined) {
+data[path[0]] = newValue;
+}
+if (typeof value === 'function') {
+return value.bind(data);
+}
+return value;
+}
+if (!value) {
+handleError(state, '"' + path[0] + '" is undefined');
+return null;
+}
+return property(state, path.slice(1), value, newValue);
+}
+catch (ex) {
+handleError(state, 'Path error with \'' + path + '\'', ex);
+return '${' + path + '}';
+}
+}
+/**
+* Like eval, but that creates a context of the variables in <tt>env</tt> in
+* which the script is evaluated.
+* WARNING: This script uses 'with' which is generally regarded to be evil.
+* The alternative is to create a Function at runtime that takes X parameters
+* according to the X keys in the env object, and then call that function using
+* the values in the env object. This is likely to be slow, but workable.
+* @param script The string to be evaluated.
+* @param data The environment in which to eval the script.
+* @param frame Optional debugging string in case of failure.
+* @return The return value of the script, or the error message if the script
+* execution failed.
+*/
+function envEval(state, script, data, frame) {
+try {
+state.stack.push(frame.replace(/\s+/g, ' '));
+// Detect if a script is capable of being interpreted using property()
+if (/^[_a-zA-Z0-9.]*$/.test(script)) {
+return property(state, script, data);
+}
+else {
+if (!state.options.allowEval) {
+handleError(state, 'allowEval is not set, however \'' + script + '\'' +
+' can not be resolved using a simple property path.');
+return '${' + script + '}';
+}
+with (data) {
+return eval(script);
+}
+}
+}
+catch (ex) {
+handleError(state, 'Template error evaluating \'' + script + '\'', ex);
+return '${' + script + '}';
+}
+finally {
+state.stack.pop();
+}
+}
+/**
+* A generic way of reporting errors, for easy overloading in different
+* environments.
+* @param message the error message to report.
+* @param ex optional associated exception.
+*/
+function handleError(state, message, ex) {
+logError(message + ' (In: ' + state.stack.join(' > ') + ')');
+if (ex) {
+logError(ex);
+}
+}
+/**
+* A generic way of reporting errors, for easy overloading in different
+* environments.
+* @param message the error message to report.
+*/
+function logError(message) {
+console.log(message);
+}

The Tor Browser / file comparison

comparison: toolkit/devtools/gcli/Templater.jsm

toolkit/devtools/gcli/Templater.jsm