The Tor Browser: comparison toolkit/devtools/Console.jsm

--1:000000000000
+:c8d2da384bbb
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+/**
+* Define a 'console' API to roughly match the implementation provided by
+* Firebug.
+* This module helps cases where code is shared between the web and Firefox.
+* See also Browser.jsm for an implementation of other web constants to help
+* sharing code between the web and firefox;
+*
+* The API is only be a rough approximation for 3 reasons:
+* - The Firebug console API is implemented in many places with differences in
+*   the implementations, so there isn't a single reference to adhere to
+* - The Firebug console is a rich display compared with dump(), so there will
+*   be many things that we can't replicate
+* - The primary use of this API is debugging and error logging so the perfect
+*   implementation isn't always required (or even well defined)
+*/
+this.EXPORTED_SYMBOLS = [ "console", "ConsoleAPI" ];
+const {classes: Cc, interfaces: Ci, utils: Cu} = Components;
+Cu.import("resource://gre/modules/XPCOMUtils.jsm");
+XPCOMUtils.defineLazyModuleGetter(this, "Services",
+"resource://gre/modules/Services.jsm");
+let gTimerRegistry = new Map();
+/**
+* String utility to ensure that strings are a specified length. Strings
+* that are too long are truncated to the max length and the last char is
+* set to "_". Strings that are too short are padded with spaces.
+*
+* @param {string} aStr
+*        The string to format to the correct length
+* @param {number} aMaxLen
+*        The maximum allowed length of the returned string
+* @param {number} aMinLen (optional)
+*        The minimum allowed length of the returned string. If undefined,
+*        then aMaxLen will be used
+* @param {object} aOptions (optional)
+*        An object allowing format customization. Allowed customizations:
+*          'truncate' - can take the value "start" to truncate strings from
+*             the start as opposed to the end or "center" to truncate
+*             strings in the center.
+*          'align' - takes an alignment when padding is needed for MinLen,
+*             either "start" or "end".  Defaults to "start".
+* @return {string}
+*        The original string formatted to fit the specified lengths
+*/
+function fmt(aStr, aMaxLen, aMinLen, aOptions) {
+if (aMinLen == null) {
+aMinLen = aMaxLen;
+}
+if (aStr == null) {
+aStr = "";
+}
+if (aStr.length > aMaxLen) {
+if (aOptions && aOptions.truncate == "start") {
+return "_" + aStr.substring(aStr.length - aMaxLen + 1);
+}
+else if (aOptions && aOptions.truncate == "center") {
+let start = aStr.substring(0, (aMaxLen / 2));
+let end = aStr.substring((aStr.length - (aMaxLen / 2)) + 1);
+return start + "_" + end;
+}
+else {
+return aStr.substring(0, aMaxLen - 1) + "_";
+}
+}
+if (aStr.length < aMinLen) {
+let padding = Array(aMinLen - aStr.length + 1).join(" ");
+aStr = (aOptions.align === "end") ? padding + aStr : aStr + padding;
+}
+return aStr;
+}
+/**
+* Utility to extract the constructor name of an object.
+* Object.toString gives: "[object ?????]"; we want the "?????".
+*
+* @param {object} aObj
+*        The object from which to extract the constructor name
+* @return {string}
+*        The constructor name
+*/
+function getCtorName(aObj) {
+if (aObj === null) {
+return "null";
+}
+if (aObj === undefined) {
+return "undefined";
+}
+if (aObj.constructor && aObj.constructor.name) {
+return aObj.constructor.name;
+}
+// If that fails, use Objects toString which sometimes gives something
+// better than 'Object', and at least defaults to Object if nothing better
+return Object.prototype.toString.call(aObj).slice(8, -1);
+}
+/**
+* A single line stringification of an object designed for use by humans
+*
+* @param {any} aThing
+*        The object to be stringified
+* @param {boolean} aAllowNewLines
+* @return {string}
+*        A single line representation of aThing, which will generally be at
+*        most 80 chars long
+*/
+function stringify(aThing, aAllowNewLines) {
+if (aThing === undefined) {
+return "undefined";
+}
+if (aThing === null) {
+return "null";
+}
+if (typeof aThing == "object") {
+let type = getCtorName(aThing);
+if (aThing instanceof Components.interfaces.nsIDOMNode && aThing.tagName) {
+return debugElement(aThing);
+}
+type = (type == "Object" ? "" : type + " ");
+let json;
+try {
+json = JSON.stringify(aThing);
+}
+catch (ex) {
+// Can't use a real ellipsis here, because cmd.exe isn't unicode-enabled
+json = "{" + Object.keys(aThing).join(":..,") + ":.., " + "}";
+}
+return type + json;
+}
+if (typeof aThing == "function") {
+return aThing.toString().replace(/\s+/g, " ");
+}
+let str = aThing.toString();
+if (!aAllowNewLines) {
+str = str.replace(/\n/g, "|");
+}
+return str;
+}
+/**
+* Create a simple debug representation of a given element.
+*
+* @param {nsIDOMElement} aElement
+*        The element to debug
+* @return {string}
+*        A simple single line representation of aElement
+*/
+function debugElement(aElement) {
+return "<" + aElement.tagName +
+(aElement.id ? "#" + aElement.id : "") +
+(aElement.className ?
+"." + aElement.className.split(" ").join(" .") :
+"") +
+">";
+}
+/**
+* A multi line stringification of an object, designed for use by humans
+*
+* @param {any} aThing
+*        The object to be stringified
+* @return {string}
+*        A multi line representation of aThing
+*/
+function log(aThing) {
+if (aThing === null) {
+return "null\n";
+}
+if (aThing === undefined) {
+return "undefined\n";
+}
+if (typeof aThing == "object") {
+let reply = "";
+let type = getCtorName(aThing);
+if (type == "Map") {
+reply += "Map\n";
+for (let [key, value] of aThing) {
+reply += logProperty(key, value);
+}
+}
+else if (type == "Set") {
+let i = 0;
+reply += "Set\n";
+for (let value of aThing) {
+reply += logProperty('' + i, value);
+i++;
+}
+}
+else if (type.match("Error$") ||
+(typeof aThing.name == "string" &&
+aThing.name.match("NS_ERROR_"))) {
+reply += "  Message: " + aThing + "\n";
+if (aThing.stack) {
+reply += "  Stack:\n";
+var frame = aThing.stack;
+while (frame) {
+reply += "    " + frame + "\n";
+frame = frame.caller;
+}
+}
+}
+else if (aThing instanceof Components.interfaces.nsIDOMNode && aThing.tagName) {
+reply += "  " + debugElement(aThing) + "\n";
+}
+else {
+let keys = Object.getOwnPropertyNames(aThing);
+if (keys.length > 0) {
+reply += type + "\n";
+keys.forEach(function(aProp) {
+reply += logProperty(aProp, aThing[aProp]);
+});
+}
+else {
+reply += type + "\n";
+let root = aThing;
+let logged = [];
+while (root != null) {
+let properties = Object.keys(root);
+properties.sort();
+properties.forEach(function(property) {
+if (!(property in logged)) {
+logged[property] = property;
+reply += logProperty(property, aThing[property]);
+}
+});
+root = Object.getPrototypeOf(root);
+if (root != null) {
+reply += '  - prototype ' + getCtorName(root) + '\n';
+}
+}
+}
+}
+return reply;
+}
+return "  " + aThing.toString() + "\n";
+}
+/**
+* Helper for log() which converts a property/value pair into an output
+* string
+*
+* @param {string} aProp
+*        The name of the property to include in the output string
+* @param {object} aValue
+*        Value assigned to aProp to be converted to a single line string
+* @return {string}
+*        Multi line output string describing the property/value pair
+*/
+function logProperty(aProp, aValue) {
+let reply = "";
+if (aProp == "stack" && typeof value == "string") {
+let trace = parseStack(aValue);
+reply += formatTrace(trace);
+}
+else {
+reply += "    - " + aProp + " = " + stringify(aValue) + "\n";
+}
+return reply;
+}
+const LOG_LEVELS = {
+"all": Number.MIN_VALUE,
+"debug": 2,
+"log": 3,
+"info": 3,
+"trace": 3,
+"timeEnd": 3,
+"time": 3,
+"group": 3,
+"groupEnd": 3,
+"dir": 3,
+"dirxml": 3,
+"warn": 4,
+"error": 5,
+"off": Number.MAX_VALUE,
+};
+/**
+* Helper to tell if a console message of `aLevel` type
+* should be logged in stdout and sent to consoles given
+* the current maximum log level being defined in `console.maxLogLevel`
+*
+* @param {string} aLevel
+*        Console message log level
+* @param {string} aMaxLevel {string}
+*        String identifier (See LOG_LEVELS for possible
+*        values) that allows to filter which messages
+*        are logged based on their log level
+* @return {boolean}
+*        Should this message be logged or not?
+*/
+function shouldLog(aLevel, aMaxLevel) {
+return LOG_LEVELS[aMaxLevel] <= LOG_LEVELS[aLevel];
+}
+/**
+* Parse a stack trace, returning an array of stack frame objects, where
+* each has filename/lineNumber/functionName members
+*
+* @param {string} aStack
+*        The serialized stack trace
+* @return {object[]}
+*        Array of { file: "...", line: NNN, call: "..." } objects
+*/
+function parseStack(aStack) {
+let trace = [];
+aStack.split("\n").forEach(function(line) {
+if (!line) {
+return;
+}
+let at = line.lastIndexOf("@");
+let posn = line.substring(at + 1);
+trace.push({
+filename: posn.split(":")[0],
+lineNumber: posn.split(":")[1],
+functionName: line.substring(0, at)
+});
+});
+return trace;
+}
+/**
+* Format a frame coming from Components.stack such that it can be used by the
+* Browser Console, via console-api-log-event notifications.
+*
+* @param {object} aFrame
+*        The stack frame from which to begin the walk.
+* @param {number=0} aMaxDepth
+*        Maximum stack trace depth. Default is 0 - no depth limit.
+* @return {object[]}
+*         An array of {filename, lineNumber, functionName, language} objects.
+*         These objects follow the same format as other console-api-log-event
+*         messages.
+*/
+function getStack(aFrame, aMaxDepth = 0) {
+if (!aFrame) {
+aFrame = Components.stack.caller;
+}
+let trace = [];
+while (aFrame) {
+trace.push({
+filename: aFrame.filename,
+lineNumber: aFrame.lineNumber,
+functionName: aFrame.name,
+language: aFrame.language,
+});
+if (aMaxDepth == trace.length) {
+break;
+}
+aFrame = aFrame.caller;
+}
+return trace;
+}
+/**
+* Take the output from parseStack() and convert it to nice readable
+* output
+*
+* @param {object[]} aTrace
+*        Array of trace objects as created by parseStack()
+* @return {string} Multi line report of the stack trace
+*/
+function formatTrace(aTrace) {
+let reply = "";
+aTrace.forEach(function(frame) {
+reply += fmt(frame.filename, 20, 20, { truncate: "start" }) + " " +
+fmt(frame.lineNumber, 5, 5) + " " +
+fmt(frame.functionName, 75, 0, { truncate: "center" }) + "\n";
+});
+return reply;
+}
+/**
+* Create a new timer by recording the current time under the specified name.
+*
+* @param {string} aName
+*        The name of the timer.
+* @param {number} [aTimestamp=Date.now()]
+*        Optional timestamp that tells when the timer was originally started.
+* @return {object}
+*         The name property holds the timer name and the started property
+*         holds the time the timer was started. In case of error, it returns
+*         an object with the single property "error" that contains the key
+*         for retrieving the localized error message.
+*/
+function startTimer(aName, aTimestamp) {
+let key = aName.toString();
+if (!gTimerRegistry.has(key)) {
+gTimerRegistry.set(key, aTimestamp || Date.now());
+}
+return { name: aName, started: gTimerRegistry.get(key) };
+}
+/**
+* Stop the timer with the specified name and retrieve the elapsed time.
+*
+* @param {string} aName
+*        The name of the timer.
+* @param {number} [aTimestamp=Date.now()]
+*        Optional timestamp that tells when the timer was originally stopped.
+* @return {object}
+*         The name property holds the timer name and the duration property
+*         holds the number of milliseconds since the timer was started.
+*/
+function stopTimer(aName, aTimestamp) {
+let key = aName.toString();
+let duration = (aTimestamp || Date.now()) - gTimerRegistry.get(key);
+gTimerRegistry.delete(key);
+return { name: aName, duration: duration };
+}
+/**
+* Dump a new message header to stdout by taking care of adding an eventual
+* prefix
+*
+* @param {object} aConsole
+*        ConsoleAPI instance
+* @param {string} aLevel
+*        The string identifier for the message log level
+* @param {string} aMessage
+*        The string message to print to stdout
+*/
+function dumpMessage(aConsole, aLevel, aMessage) {
+aConsole.dump(
+"console." + aLevel + ": " +
+aConsole.prefix +
+aMessage + "\n"
+);
+}
+/**
+* Create a function which will output a concise level of output when used
+* as a logging function
+*
+* @param {string} aLevel
+*        A prefix to all output generated from this function detailing the
+*        level at which output occurred
+* @return {function}
+*        A logging function
+* @see createMultiLineDumper()
+*/
+function createDumper(aLevel) {
+return function() {
+if (!shouldLog(aLevel, this.maxLogLevel)) {
+return;
+}
+let args = Array.prototype.slice.call(arguments, 0);
+let frame = getStack(Components.stack.caller, 1)[0];
+sendConsoleAPIMessage(this, aLevel, frame, args);
+let data = args.map(function(arg) {
+return stringify(arg, true);
+});
+dumpMessage(this, aLevel, data.join(" "));
+};
+}
+/**
+* Create a function which will output more detailed level of output when
+* used as a logging function
+*
+* @param {string} aLevel
+*        A prefix to all output generated from this function detailing the
+*        level at which output occurred
+* @return {function}
+*        A logging function
+* @see createDumper()
+*/
+function createMultiLineDumper(aLevel) {
+return function() {
+if (!shouldLog(aLevel, this.maxLogLevel)) {
+return;
+}
+dumpMessage(this, aLevel, "");
+let args = Array.prototype.slice.call(arguments, 0);
+let frame = getStack(Components.stack.caller, 1)[0];
+sendConsoleAPIMessage(this, aLevel, frame, args);
+args.forEach(function(arg) {
+this.dump(log(arg));
+}, this);
+};
+}
+/**
+* Send a Console API message. This function will send a console-api-log-event
+* notification through the nsIObserverService.
+*
+* @param {object} aConsole
+*        The instance of ConsoleAPI performing the logging.
+* @param {string} aLevel
+*        Message severity level. This is usually the name of the console method
+*        that was called.
+* @param {object} aFrame
+*        The youngest stack frame coming from Components.stack, as formatted by
+*        getStack().
+* @param {array} aArgs
+*        The arguments given to the console method.
+* @param {object} aOptions
+*        Object properties depend on the console method that was invoked:
+*        - timer: for time() and timeEnd(). Holds the timer information.
+*        - groupName: for group(), groupCollapsed() and groupEnd().
+*        - stacktrace: for trace(). Holds the array of stack frames as given by
+*        getStack().
+*/
+function sendConsoleAPIMessage(aConsole, aLevel, aFrame, aArgs, aOptions = {})
+{
+let consoleEvent = {
+ID: "jsm",
+innerID: aConsole.innerID || aFrame.filename,
+level: aLevel,
+filename: aFrame.filename,
+lineNumber: aFrame.lineNumber,
+functionName: aFrame.functionName,
+timeStamp: Date.now(),
+arguments: aArgs,
+};
+consoleEvent.wrappedJSObject = consoleEvent;
+switch (aLevel) {
+case "trace":
+consoleEvent.stacktrace = aOptions.stacktrace;
+break;
+case "time":
+case "timeEnd":
+consoleEvent.timer = aOptions.timer;
+break;
+case "group":
+case "groupCollapsed":
+case "groupEnd":
+try {
+consoleEvent.groupName = Array.prototype.join.call(aArgs, " ");
+}
+catch (ex) {
+Cu.reportError(ex);
+Cu.reportError(ex.stack);
+return;
+}
+break;
+}
+Services.obs.notifyObservers(consoleEvent, "console-api-log-event", null);
+let ConsoleAPIStorage = Cc["@mozilla.org/consoleAPI-storage;1"]
+.getService(Ci.nsIConsoleAPIStorage);
+ConsoleAPIStorage.recordEvent("jsm", consoleEvent);
+}
+/**
+* This creates a console object that somewhat replicates Firebug's console
+* object
+*
+* @param {object} aConsoleOptions
+*        Optional dictionary with a set of runtime console options:
+*        - prefix {string} : An optional prefix string to be printed before
+*                            the actual logged message
+*        - maxLogLevel {string} : String identifier (See LOG_LEVELS for
+*                            possible values) that allows to filter which
+*                            messages are logged based on their log level.
+*                            If falsy value, all messages will be logged.
+*                            If wrong value that doesn't match any key of
+*                            LOG_LEVELS, no message will be logged
+*        - dump {function} : An optional function to intercept all strings
+*                            written to stdout
+*        - innerID {string}: An ID representing the source of the message.
+*                            Normally the inner ID of a DOM window.
+* @return {object}
+*        A console API instance object
+*/
+function ConsoleAPI(aConsoleOptions = {}) {
+// Normalize console options to set default values
+// in order to avoid runtime checks on each console method call.
+this.dump = aConsoleOptions.dump || dump;
+this.prefix = aConsoleOptions.prefix || "";
+this.maxLogLevel = aConsoleOptions.maxLogLevel || "all";
+this.innerID = aConsoleOptions.innerID || null;
+// Bind all the functions to this object.
+for (let prop in this) {
+if (typeof(this[prop]) === "function") {
+this[prop] = this[prop].bind(this);
+}
+}
+}
+ConsoleAPI.prototype = {
+debug: createMultiLineDumper("debug"),
+log: createDumper("log"),
+info: createDumper("info"),
+warn: createDumper("warn"),
+error: createMultiLineDumper("error"),
+exception: createMultiLineDumper("error"),
+trace: function Console_trace() {
+if (!shouldLog("trace", this.maxLogLevel)) {
+return;
+}
+let args = Array.prototype.slice.call(arguments, 0);
+let trace = getStack(Components.stack.caller);
+sendConsoleAPIMessage(this, "trace", trace[0], args,
+{ stacktrace: trace });
+dumpMessage(this, "trace", "\n" + formatTrace(trace));
+},
+clear: function Console_clear() {},
+dir: createMultiLineDumper("dir"),
+dirxml: createMultiLineDumper("dirxml"),
+group: createDumper("group"),
+groupEnd: createDumper("groupEnd"),
+time: function Console_time() {
+if (!shouldLog("time", this.maxLogLevel)) {
+return;
+}
+let args = Array.prototype.slice.call(arguments, 0);
+let frame = getStack(Components.stack.caller, 1)[0];
+let timer = startTimer(args[0]);
+sendConsoleAPIMessage(this, "time", frame, args, { timer: timer });
+dumpMessage(this, "time",
+"'" + timer.name + "' @ " + (new Date()));
+},
+timeEnd: function Console_timeEnd() {
+if (!shouldLog("timeEnd", this.maxLogLevel)) {
+return;
+}
+let args = Array.prototype.slice.call(arguments, 0);
+let frame = getStack(Components.stack.caller, 1)[0];
+let timer = stopTimer(args[0]);
+sendConsoleAPIMessage(this, "timeEnd", frame, args, { timer: timer });
+dumpMessage(this, "timeEnd",
+"'" + timer.name + "' " + timer.duration + "ms");
+},
+};
+this.console = new ConsoleAPI();
+this.ConsoleAPI = ConsoleAPI;

The Tor Browser / file comparison

comparison: toolkit/devtools/Console.jsm

toolkit/devtools/Console.jsm