The Tor Browser: comparison browser/devtools/shared/widgets/VariablesViewController.jsm

--1:000000000000
+:7a0da14d7885
+/* -*- Mode: javascript; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ft=javascript ts=2 et sw=2 tw=80: */
+/* 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";
+const { classes: Cc, interfaces: Ci, utils: Cu } = Components;
+Cu.import("resource://gre/modules/Services.jsm");
+Cu.import("resource://gre/modules/XPCOMUtils.jsm");
+let {Promise: promise} = Cu.import("resource://gre/modules/Promise.jsm", {});
+Cu.import("resource:///modules/devtools/VariablesView.jsm");
+Cu.import("resource:///modules/devtools/ViewHelpers.jsm");
+XPCOMUtils.defineLazyModuleGetter(this, "devtools",
+"resource://gre/modules/devtools/Loader.jsm");
+Object.defineProperty(this, "WebConsoleUtils", {
+get: function() {
+return devtools.require("devtools/toolkit/webconsole/utils").Utils;
+},
+configurable: true,
+enumerable: true
+});
+XPCOMUtils.defineLazyGetter(this, "VARIABLES_SORTING_ENABLED", () =>
+Services.prefs.getBoolPref("devtools.debugger.ui.variables-sorting-enabled")
+);
+XPCOMUtils.defineLazyModuleGetter(this, "console",
+"resource://gre/modules/devtools/Console.jsm");
+const MAX_LONG_STRING_LENGTH = 200000;
+const DBG_STRINGS_URI = "chrome://browser/locale/devtools/debugger.properties";
+this.EXPORTED_SYMBOLS = ["VariablesViewController", "StackFrameUtils"];
+/**
+* Controller for a VariablesView that handles interfacing with the debugger
+* protocol. Is able to populate scopes and variables via the protocol as well
+* as manage actor lifespans.
+*
+* @param VariablesView aView
+*        The view to attach to.
+* @param object aOptions [optional]
+*        Options for configuring the controller. Supported options:
+*        - getObjectClient: @see this._setClientGetters
+*        - getLongStringClient: @see this._setClientGetters
+*        - getEnvironmentClient: @see this._setClientGetters
+*        - releaseActor: @see this._setClientGetters
+*        - overrideValueEvalMacro: @see _setEvaluationMacros
+*        - getterOrSetterEvalMacro: @see _setEvaluationMacros
+*        - simpleValueEvalMacro: @see _setEvaluationMacros
+*/
+function VariablesViewController(aView, aOptions = {}) {
+this.addExpander = this.addExpander.bind(this);
+this._setClientGetters(aOptions);
+this._setEvaluationMacros(aOptions);
+this._actors = new Set();
+this.view = aView;
+this.view.controller = this;
+}
+VariablesViewController.prototype = {
+/**
+* The default getter/setter evaluation macro.
+*/
+_getterOrSetterEvalMacro: VariablesView.getterOrSetterEvalMacro,
+/**
+* The default override value evaluation macro.
+*/
+_overrideValueEvalMacro: VariablesView.overrideValueEvalMacro,
+/**
+* The default simple value evaluation macro.
+*/
+_simpleValueEvalMacro: VariablesView.simpleValueEvalMacro,
+/**
+* Set the functions used to retrieve debugger client grips.
+*
+* @param object aOptions
+*        Options for getting the client grips. Supported options:
+*        - getObjectClient: callback for creating an object grip client
+*        - getLongStringClient: callback for creating a long string grip client
+*        - getEnvironmentClient: callback for creating an environment client
+*        - releaseActor: callback for releasing an actor when it's no longer needed
+*/
+_setClientGetters: function(aOptions) {
+if (aOptions.getObjectClient) {
+this._getObjectClient = aOptions.getObjectClient;
+}
+if (aOptions.getLongStringClient) {
+this._getLongStringClient = aOptions.getLongStringClient;
+}
+if (aOptions.getEnvironmentClient) {
+this._getEnvironmentClient = aOptions.getEnvironmentClient;
+}
+if (aOptions.releaseActor) {
+this._releaseActor = aOptions.releaseActor;
+}
+},
+/**
+* Sets the functions used when evaluating strings in the variables view.
+*
+* @param object aOptions
+*        Options for configuring the macros. Supported options:
+*        - overrideValueEvalMacro: callback for creating an overriding eval macro
+*        - getterOrSetterEvalMacro: callback for creating a getter/setter eval macro
+*        - simpleValueEvalMacro: callback for creating a simple value eval macro
+*/
+_setEvaluationMacros: function(aOptions) {
+if (aOptions.overrideValueEvalMacro) {
+this._overrideValueEvalMacro = aOptions.overrideValueEvalMacro;
+}
+if (aOptions.getterOrSetterEvalMacro) {
+this._getterOrSetterEvalMacro = aOptions.getterOrSetterEvalMacro;
+}
+if (aOptions.simpleValueEvalMacro) {
+this._simpleValueEvalMacro = aOptions.simpleValueEvalMacro;
+}
+},
+/**
+* Populate a long string into a target using a grip.
+*
+* @param Variable aTarget
+*        The target Variable/Property to put the retrieved string into.
+* @param LongStringActor aGrip
+*        The long string grip that use to retrieve the full string.
+* @return Promise
+*         The promise that will be resolved when the string is retrieved.
+*/
+_populateFromLongString: function(aTarget, aGrip){
+let deferred = promise.defer();
+let from = aGrip.initial.length;
+let to = Math.min(aGrip.length, MAX_LONG_STRING_LENGTH);
+this._getLongStringClient(aGrip).substring(from, to, aResponse => {
+// Stop tracking the actor because it's no longer needed.
+this.releaseActor(aGrip);
+// Replace the preview with the full string and make it non-expandable.
+aTarget.onexpand = null;
+aTarget.setGrip(aGrip.initial + aResponse.substring);
+aTarget.hideArrow();
+deferred.resolve();
+});
+return deferred.promise;
+},
+/**
+* Adds properties to a Scope, Variable, or Property in the view. Triggered
+* when a scope is expanded or certain variables are hovered.
+*
+* @param Scope aTarget
+*        The Scope where the properties will be placed into.
+* @param object aGrip
+*        The grip to use to populate the target.
+*/
+_populateFromObject: function(aTarget, aGrip) {
+let deferred = promise.defer();
+let objectClient = this._getObjectClient(aGrip);
+objectClient.getPrototypeAndProperties(aResponse => {
+let { ownProperties, prototype } = aResponse;
+// 'safeGetterValues' is new and isn't necessary defined on old actors.
+let safeGetterValues = aResponse.safeGetterValues || {};
+let sortable = VariablesView.isSortable(aGrip.class);
+// Merge the safe getter values into one object such that we can use it
+// in VariablesView.
+for (let name of Object.keys(safeGetterValues)) {
+if (name in ownProperties) {
+let { getterValue, getterPrototypeLevel } = safeGetterValues[name];
+ownProperties[name].getterValue = getterValue;
+ownProperties[name].getterPrototypeLevel = getterPrototypeLevel;
+} else {
+ownProperties[name] = safeGetterValues[name];
+}
+}
+// Add all the variable properties.
+if (ownProperties) {
+aTarget.addItems(ownProperties, {
+// Not all variables need to force sorted properties.
+sorted: sortable,
+// Expansion handlers must be set after the properties are added.
+callback: this.addExpander
+});
+}
+// Add the variable's __proto__.
+if (prototype && prototype.type != "null") {
+let proto = aTarget.addItem("__proto__", { value: prototype });
+// Expansion handlers must be set after the properties are added.
+this.addExpander(proto, prototype);
+}
+// If the object is a function we need to fetch its scope chain
+// to show them as closures for the respective function.
+if (aGrip.class == "Function") {
+objectClient.getScope(aResponse => {
+if (aResponse.error) {
+// This function is bound to a built-in object or it's not present
+// in the current scope chain. Not necessarily an actual error,
+// it just means that there's no closure for the function.
+console.warn(aResponse.error + ": " + aResponse.message);
+return void deferred.resolve();
+}
+this._populateWithClosure(aTarget, aResponse.scope).then(deferred.resolve);
+});
+} else {
+deferred.resolve();
+}
+});
+return deferred.promise;
+},
+/**
+* Adds the scope chain elements (closures) of a function variable.
+*
+* @param Variable aTarget
+*        The variable where the properties will be placed into.
+* @param Scope aScope
+*        The lexical environment form as specified in the protocol.
+*/
+_populateWithClosure: function(aTarget, aScope) {
+let objectScopes = [];
+let environment = aScope;
+let funcScope = aTarget.addItem("<Closure>");
+funcScope.target.setAttribute("scope", "");
+funcScope.showArrow();
+do {
+// Create a scope to contain all the inspected variables.
+let label = StackFrameUtils.getScopeLabel(environment);
+// Block scopes may have the same label, so make addItem allow duplicates.
+let closure = funcScope.addItem(label, undefined, true);
+closure.target.setAttribute("scope", "");
+closure.showArrow();
+// Add nodes for every argument and every other variable in scope.
+if (environment.bindings) {
+this._populateWithEnvironmentBindings(closure, environment.bindings);
+} else {
+let deferred = promise.defer();
+objectScopes.push(deferred.promise);
+this._getEnvironmentClient(environment).getBindings(response => {
+this._populateWithEnvironmentBindings(closure, response.bindings);
+deferred.resolve();
+});
+}
+} while ((environment = environment.parent));
+return promise.all(objectScopes).then(() => {
+// Signal that scopes have been fetched.
+this.view.emit("fetched", "scopes", funcScope);
+});
+},
+/**
+* Adds nodes for every specified binding to the closure node.
+*
+* @param Variable aTarget
+*        The variable where the bindings will be placed into.
+* @param object aBindings
+*        The bindings form as specified in the protocol.
+*/
+_populateWithEnvironmentBindings: function(aTarget, aBindings) {
+// Add nodes for every argument in the scope.
+aTarget.addItems(aBindings.arguments.reduce((accumulator, arg) => {
+let name = Object.getOwnPropertyNames(arg)[0];
+let descriptor = arg[name];
+accumulator[name] = descriptor;
+return accumulator;
+}, {}), {
+// Arguments aren't sorted.
+sorted: false,
+// Expansion handlers must be set after the properties are added.
+callback: this.addExpander
+});
+// Add nodes for every other variable in the scope.
+aTarget.addItems(aBindings.variables, {
+// Not all variables need to force sorted properties.
+sorted: VARIABLES_SORTING_ENABLED,
+// Expansion handlers must be set after the properties are added.
+callback: this.addExpander
+});
+},
+/**
+* Adds an 'onexpand' callback for a variable, lazily handling
+* the addition of new properties.
+*
+* @param Variable aTarget
+*        The variable where the properties will be placed into.
+* @param any aSource
+*        The source to use to populate the target.
+*/
+addExpander: function(aTarget, aSource) {
+// Attach evaluation macros as necessary.
+if (aTarget.getter || aTarget.setter) {
+aTarget.evaluationMacro = this._overrideValueEvalMacro;
+let getter = aTarget.get("get");
+if (getter) {
+getter.evaluationMacro = this._getterOrSetterEvalMacro;
+}
+let setter = aTarget.get("set");
+if (setter) {
+setter.evaluationMacro = this._getterOrSetterEvalMacro;
+}
+} else {
+aTarget.evaluationMacro = this._simpleValueEvalMacro;
+}
+// If the source is primitive then an expander is not needed.
+if (VariablesView.isPrimitive({ value: aSource })) {
+return;
+}
+// If the source is a long string then show the arrow.
+if (WebConsoleUtils.isActorGrip(aSource) && aSource.type == "longString") {
+aTarget.showArrow();
+}
+// Make sure that properties are always available on expansion.
+aTarget.onexpand = () => this.populate(aTarget, aSource);
+// Some variables are likely to contain a very large number of properties.
+// It's a good idea to be prepared in case of an expansion.
+if (aTarget.shouldPrefetch) {
+aTarget.addEventListener("mouseover", aTarget.onexpand, false);
+}
+// Register all the actors that this controller now depends on.
+for (let grip of [aTarget.value, aTarget.getter, aTarget.setter]) {
+if (WebConsoleUtils.isActorGrip(grip)) {
+this._actors.add(grip.actor);
+}
+}
+},
+/**
+* Adds properties to a Scope, Variable, or Property in the view. Triggered
+* when a scope is expanded or certain variables are hovered.
+*
+* This does not expand the target, it only populates it.
+*
+* @param Scope aTarget
+*        The Scope to be expanded.
+* @param object aSource
+*        The source to use to populate the target.
+* @return Promise
+*         The promise that is resolved once the target has been expanded.
+*/
+populate: function(aTarget, aSource) {
+// Fetch the variables only once.
+if (aTarget._fetched) {
+return aTarget._fetched;
+}
+// Make sure the source grip is available.
+if (!aSource) {
+return promise.reject(new Error("No actor grip was given for the variable."));
+}
+let deferred = promise.defer();
+aTarget._fetched = deferred.promise;
+// If the target is a Variable or Property then we're fetching properties.
+if (VariablesView.isVariable(aTarget)) {
+this._populateFromObject(aTarget, aSource).then(() => {
+// Signal that properties have been fetched.
+this.view.emit("fetched", "properties", aTarget);
+// Commit the hierarchy because new items were added.
+this.view.commitHierarchy();
+deferred.resolve();
+});
+return deferred.promise;
+}
+switch (aSource.type) {
+case "longString":
+this._populateFromLongString(aTarget, aSource).then(() => {
+// Signal that a long string has been fetched.
+this.view.emit("fetched", "longString", aTarget);
+deferred.resolve();
+});
+break;
+case "with":
+case "object":
+this._populateFromObject(aTarget, aSource.object).then(() => {
+// Signal that variables have been fetched.
+this.view.emit("fetched", "variables", aTarget);
+// Commit the hierarchy because new items were added.
+this.view.commitHierarchy();
+deferred.resolve();
+});
+break;
+case "block":
+case "function":
+this._populateWithEnvironmentBindings(aTarget, aSource.bindings);
+// No need to signal that variables have been fetched, since
+// the scope arguments and variables are already attached to the
+// environment bindings, so pausing the active thread is unnecessary.
+// Commit the hierarchy because new items were added.
+this.view.commitHierarchy();
+deferred.resolve();
+break;
+default:
+let error = "Unknown Debugger.Environment type: " + aSource.type;
+Cu.reportError(error);
+deferred.reject(error);
+}
+return deferred.promise;
+},
+/**
+* Release an actor from the controller.
+*
+* @param object aActor
+*        The actor to release.
+*/
+releaseActor: function(aActor){
+if (this._releaseActor) {
+this._releaseActor(aActor);
+}
+this._actors.delete(aActor);
+},
+/**
+* Release all the actors referenced by the controller, optionally filtered.
+*
+* @param function aFilter [optional]
+*        Callback to filter which actors are released.
+*/
+releaseActors: function(aFilter) {
+for (let actor of this._actors) {
+if (!aFilter || aFilter(actor)) {
+this.releaseActor(actor);
+}
+}
+},
+/**
+* Helper function for setting up a single Scope with a single Variable
+* contained within it.
+*
+* This function will empty the variables view.
+*
+* @param object aOptions
+*        Options for the contents of the view:
+*        - objectActor: the grip of the new ObjectActor to show.
+*        - rawObject: the raw object to show.
+*        - label: the label for the inspected object.
+* @param object aConfiguration
+*        Additional options for the controller:
+*        - overrideValueEvalMacro: @see _setEvaluationMacros
+*        - getterOrSetterEvalMacro: @see _setEvaluationMacros
+*        - simpleValueEvalMacro: @see _setEvaluationMacros
+* @return Object
+*         - variable: the created Variable.
+*         - expanded: the Promise that resolves when the variable expands.
+*/
+setSingleVariable: function(aOptions, aConfiguration = {}) {
+this._setEvaluationMacros(aConfiguration);
+this.view.empty();
+let scope = this.view.addScope(aOptions.label);
+scope.expanded = true; // Expand the scope by default.
+scope.locked = true; // Prevent collpasing the scope.
+let variable = scope.addItem("", { enumerable: true });
+let populated;
+if (aOptions.objectActor) {
+populated = this.populate(variable, aOptions.objectActor);
+variable.expand();
+} else if (aOptions.rawObject) {
+variable.populate(aOptions.rawObject, { expanded: true });
+populated = promise.resolve();
+}
+return { variable: variable, expanded: populated };
+},
+};
+/**
+* Attaches a VariablesViewController to a VariablesView if it doesn't already
+* have one.
+*
+* @param VariablesView aView
+*        The view to attach to.
+* @param object aOptions
+*        The options to use in creating the controller.
+* @return VariablesViewController
+*/
+VariablesViewController.attach = function(aView, aOptions) {
+if (aView.controller) {
+return aView.controller;
+}
+return new VariablesViewController(aView, aOptions);
+};
+/**
+* Utility functions for handling stackframes.
+*/
+let StackFrameUtils = {
+/**
+* Create a textual representation for the specified stack frame
+* to display in the stackframes container.
+*
+* @param object aFrame
+*        The stack frame to label.
+*/
+getFrameTitle: function(aFrame) {
+if (aFrame.type == "call") {
+let c = aFrame.callee;
+return (c.name || c.userDisplayName || c.displayName || "(anonymous)");
+}
+return "(" + aFrame.type + ")";
+},
+/**
+* Constructs a scope label based on its environment.
+*
+* @param object aEnv
+*        The scope's environment.
+* @return string
+*         The scope's label.
+*/
+getScopeLabel: function(aEnv) {
+let name = "";
+// Name the outermost scope Global.
+if (!aEnv.parent) {
+name = L10N.getStr("globalScopeLabel");
+}
+// Otherwise construct the scope name.
+else {
+name = aEnv.type.charAt(0).toUpperCase() + aEnv.type.slice(1);
+}
+let label = L10N.getFormatStr("scopeLabel", name);
+switch (aEnv.type) {
+case "with":
+case "object":
+label += " [" + aEnv.object.class + "]";
+break;
+case "function":
+let f = aEnv.function;
+label += " [" +
+(f.name || f.userDisplayName || f.displayName || "(anonymous)") +
+"]";
+break;
+}
+return label;
+}
+};
+/**
+* Localization convenience methods.
+*/
+let L10N = new ViewHelpers.L10N(DBG_STRINGS_URI);

The Tor Browser / file comparison

comparison: browser/devtools/shared/widgets/VariablesViewController.jsm

browser/devtools/shared/widgets/VariablesViewController.jsm