path: root/devtools/client/shared/widgets/VariablesViewController.jsm

/* -*- indent-tabs-mode: nil; js-indent-level: 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 { utils: Cu } = Components;

var {require} = Cu.import("resource://devtools/shared/Loader.jsm", {});
var {XPCOMUtils} = require("resource://gre/modules/XPCOMUtils.jsm");
var {VariablesView} = require("resource://devtools/client/shared/widgets/VariablesView.jsm");
var Services = require("Services");
var promise = require("promise");
var defer = require("devtools/shared/defer");
var {LocalizationHelper, ELLIPSIS} = require("devtools/shared/l10n");

Object.defineProperty(this, "WebConsoleUtils", {
  get: function () {
    return require("devtools/client/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/Console.jsm");

const MAX_LONG_STRING_LENGTH = 200000;
const MAX_PROPERTY_ITEMS = 2000;
const DBG_STRINGS_URI = "devtools/client/locales/debugger.properties";

this.EXPORTED_SYMBOLS = ["VariablesViewController", "StackFrameUtils"];

/**
 * Localization convenience methods.
 */
var L10N = new LocalizationHelper(DBG_STRINGS_URI);

/**
 * 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;
}
this.VariablesViewController = VariablesViewController;

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 = 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 pseudo items in case there is too many properties to display.
   * Each item can expand into property slices.
   *
   * @param Scope aTarget
   *        The Scope where the properties will be placed into.
   * @param object aGrip
   *        The property iterator grip.
   */
  _populatePropertySlices: function (aTarget, aGrip) {
    if (aGrip.count < MAX_PROPERTY_ITEMS) {
      return this._populateFromPropertyIterator(aTarget, aGrip);
    }

    // Divide the keys into quarters.
    let items = Math.ceil(aGrip.count / 4);
    let iterator = aGrip.propertyIterator;
    let promises = [];
    for (let i = 0; i < 4; i++) {
      let start = aGrip.start + i * items;
      let count = i != 3 ? items : aGrip.count - i * items;

      // Create a new kind of grip, with additional fields to define the slice
      let sliceGrip = {
        type: "property-iterator",
        propertyIterator: iterator,
        start: start,
        count: count
      };

      // Query the name of the first and last items for this slice
      let deferred = defer();
      iterator.names([start, start + count - 1], ({ names }) => {
          let label = "[" + names[0] + ELLIPSIS + names[1] + "]";
        let item = aTarget.addItem(label, {}, { internalItem: true });
        item.showArrow();
        this.addExpander(item, sliceGrip);
        deferred.resolve();
      });
      promises.push(deferred.promise);
    }

    return promise.all(promises);
  },

  /**
   * Adds a property slice for a Variable in the view using the already
   * property iterator
   *
   * @param Scope aTarget
   *        The Scope where the properties will be placed into.
   * @param object aGrip
   *        The property iterator grip.
   */
  _populateFromPropertyIterator: function (aTarget, aGrip) {
    if (aGrip.count >= MAX_PROPERTY_ITEMS) {
      // We already started to split, but there is still too many properties, split again.
      return this._populatePropertySlices(aTarget, aGrip);
    }
    // We started slicing properties, and the slice is now small enough to be displayed
    let deferred = defer();
    aGrip.propertyIterator.slice(aGrip.start, aGrip.count,
      ({ ownProperties }) => {
        // Add all the variable properties.
        if (Object.keys(ownProperties).length > 0) {
          aTarget.addItems(ownProperties, {
            sorted: true,
            // Expansion handlers must be set after the properties are added.
            callback: this.addExpander
          });
        }
        deferred.resolve();
      });
    return deferred.promise;
  },

  /**
   * Adds the properties for a Variable in the view using a new feature in FF40+
   * that allows iteration over properties in slices.
   *
   * @param Scope aTarget
   *        The Scope where the properties will be placed into.
   * @param object aGrip
   *        The grip to use to populate the target.
   * @param string aQuery [optional]
   *        The query string used to fetch only a subset of properties
   */
  _populateFromObjectWithIterator: function (aTarget, aGrip, aQuery) {
    // FF40+ starts exposing `ownPropertyLength` on ObjectActor's grip,
    // as well as `enumProperties` request.
    let deferred = defer();
    let objectClient = this._getObjectClient(aGrip);
    let isArray = aGrip.preview && aGrip.preview.kind === "ArrayLike";
    if (isArray) {
      // First enumerate array items, e.g. properties from `0` to `array.length`.
      let options = {
        ignoreNonIndexedProperties: true,
        query: aQuery
      };
      objectClient.enumProperties(options, ({ iterator }) => {
        let sliceGrip = {
          type: "property-iterator",
          propertyIterator: iterator,
          start: 0,
          count: iterator.count
        };
        this._populatePropertySlices(aTarget, sliceGrip)
            .then(() => {
          // Then enumerate the rest of the properties, like length, buffer, etc.
              let options = {
                ignoreIndexedProperties: true,
                sort: true,
                query: aQuery
              };
              objectClient.enumProperties(options, ({ iterator }) => {
                let sliceGrip = {
                  type: "property-iterator",
                  propertyIterator: iterator,
                  start: 0,
                  count: iterator.count
                };
                deferred.resolve(this._populatePropertySlices(aTarget, sliceGrip));
              });
            });
      });
    } else {
      // For objects, we just enumerate all the properties sorted by name.
      objectClient.enumProperties({ sort: true, query: aQuery }, ({ iterator }) => {
        let sliceGrip = {
          type: "property-iterator",
          propertyIterator: iterator,
          start: 0,
          count: iterator.count
        };
        deferred.resolve(this._populatePropertySlices(aTarget, sliceGrip));
      });

    }
    return deferred.promise;
  },

  /**
   * Adds the given prototype in the view.
   *
   * @param Scope aTarget
   *        The Scope where the properties will be placed into.
   * @param object aProtype
   *        The prototype grip.
   */
  _populateObjectPrototype: function (aTarget, aPrototype) {
    // Add the variable's __proto__.
    if (aPrototype && aPrototype.type != "null") {
      let proto = aTarget.addItem("__proto__", { value: aPrototype });
      this.addExpander(proto, aPrototype);
    }
  },

  /**
   * 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) {
    if (aGrip.class === "Proxy") {
      this.addExpander(
        aTarget.addItem("<target>", { value: aGrip.proxyTarget }, { internalItem: true }),
        aGrip.proxyTarget);
      this.addExpander(
        aTarget.addItem("<handler>", { value: aGrip.proxyHandler }, { internalItem: true }),
        aGrip.proxyHandler);

      // Refuse to play the proxy's stupid game and return immediately
      let deferred = defer();
      deferred.resolve();
      return deferred.promise;
    }

    if (aGrip.class === "Promise" && aGrip.promiseState) {
      const { state, value, reason } = aGrip.promiseState;
      aTarget.addItem("<state>", { value: state }, { internalItem: true });
      if (state === "fulfilled") {
        this.addExpander(
          aTarget.addItem("<value>", { value }, { internalItem: true }),
          value);
      } else if (state === "rejected") {
        this.addExpander(
          aTarget.addItem("<reason>", { value: reason }, { internalItem: true }),
          reason);
      }
    } else if (["Map", "WeakMap", "Set", "WeakSet"].includes(aGrip.class)) {
      let entriesList = aTarget.addItem("<entries>", {}, { internalItem: true });
      entriesList.showArrow();
      this.addExpander(entriesList, {
        type: "entries-list",
        obj: aGrip
      });
    }

    // Fetch properties by slices if there is too many in order to prevent UI freeze.
    if ("ownPropertyLength" in aGrip && aGrip.ownPropertyLength >= MAX_PROPERTY_ITEMS) {
      return this._populateFromObjectWithIterator(aTarget, aGrip)
                 .then(() => {
                   let deferred = defer();
                   let objectClient = this._getObjectClient(aGrip);
                   objectClient.getPrototype(({ prototype }) => {
                     this._populateObjectPrototype(aTarget, prototype);
                     deferred.resolve();
                   });
                   return deferred.promise;
                 });
    }

    return this._populateProperties(aTarget, aGrip);
  },

  _populateProperties: function (aTarget, aGrip, aOptions) {
    let deferred = defer();

    let objectClient = this._getObjectClient(aGrip);
    objectClient.getPrototypeAndProperties(aResponse => {
      let ownProperties = aResponse.ownProperties || {};
      let prototype = aResponse.prototype || null;
      // '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.
      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__.
      this._populateObjectPrototype(aTarget, 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, {relaxed: 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 = 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
    });
  },

  _populateFromEntries: function (target, grip) {
    let objGrip = grip.obj;
    let objectClient = this._getObjectClient(objGrip);

    return new promise((resolve, reject) => {
      objectClient.enumEntries((response) => {
        if (response.error) {
          // Older server might not support the enumEntries method
          console.warn(response.error + ": " + response.message);
          resolve();
        } else {
          let sliceGrip = {
            type: "property-iterator",
            propertyIterator: response.iterator,
            start: 0,
            count: response.iterator.count
          };

          resolve(this._populatePropertySlices(target, sliceGrip));
        }
      });
    });
  },

  /**
   * 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 = defer();
    aTarget._fetched = deferred.promise;

    if (aSource.type === "property-iterator") {
      return this._populateFromPropertyIterator(aTarget, aSource);
    }

    if (aSource.type === "entries-list") {
      return this._populateFromEntries(aTarget, aSource);
    }

    if (aSource.type === "mapEntry") {
      aTarget.addItems({
        key: { value: aSource.preview.key },
        value: { value: aSource.preview.value }
      }, {
        callback: this.addExpander
      });

      return promise.resolve();
    }

    // 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;
        console.error(error);
        deferred.reject(error);
    }

    return deferred.promise;
  },

  /**
   * Indicates to the view if the targeted actor supports properties search
   *
   * @return boolean True, if the actor supports enumProperty request
   */
  supportsSearch: function () {
    // FF40+ starts exposing ownPropertyLength on object actor's grip
    // as well as enumProperty which allows to query a subset of properties.
    return this.objectActor && ("ownPropertyLength" in this.objectActor);
  },

  /**
   * Try to use the actor to perform an attribute search.
   *
   * @param Scope aScope
   *        The Scope instance to populate with properties
   * @param string aToken
   *        The query string
   */
  performSearch: function (aScope, aToken) {
    this._populateFromObjectWithIterator(aScope, this.objectActor, aToken)
        .then(() => {
          this.view.emit("fetched", "search", aScope);
        });
  },

  /**
   * 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 options
   *        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 configuration
   *        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 (options, configuration = {}) {
    this._setEvaluationMacros(configuration);
    this.view.empty();

    let scope = this.view.addScope(options.label);
    scope.expanded = true; // Expand the scope by default.
    scope.locked = true; // Prevent collapsing the scope.

    let variable = scope.addItem(undefined, { enumerable: true });
    let populated;

    if (options.objectActor) {
      // Save objectActor for properties filtering
      this.objectActor = options.objectActor;
      if (VariablesView.isPrimitive({ value: this.objectActor })) {
        populated = promise.resolve();
      } else {
        populated = this.populate(variable, options.objectActor);
        variable.expand();
      }
    } else if (options.rawObject) {
      variable.populate(options.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.
 */
var StackFrameUtils = this.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;
  }
};