Debugger.Object

Cette traduction est en cours.

Debugger.Object

Une instace de Debugger.Object représente un objet du code débugué, fournissant des méthodes orientés reflection pour pouvoir inspecter et modifier son référent. Les proprotétées du référent n'apparaisent pas directement en tant que propriétées de l'instance de Debugger.Object. Le débogueur peut accéder à ces propriétées uniquement en passant par des méthodes comme Debugger.Object.prototype.getOwnPropertyDescriptor et Debugger.Object.prototype.defineProperty, cela afin d'être sur que le débogueur n'invoquera pas par érreur des getters et setters du référent.

SpiderMonkey crée exactement une instance de Debugger.Object par objet du code débogué présenté à une instance de Debugger : Si le débogueur rencontre le même objet en passant par deux chemins différents (par exemple si deux fonction sont appellé sur le même objet), SpiderMonkey présentera au débogueur la même instance de Debugger.Object à chaque fois. Cela signifie que le débogueur peut utiliser l'opérateur == pour reconaitre les moments ou deux instances de Debugger.Object font référence au même objet du code débogué (si instance == instance alors elles font référence au même objet). Le débogueur peut alors placer ses propres propriétes sur une instance de Debugger.Object pour stocker des méta-données sur un objet du code débogué en particulier.

Du code JavaScripot dans diférents compartiments peut avoir diférentes visions du même objet. Par exemple dans Firefox, du code dans un compartiment priviilégié peut voir les objets des éléments DOM contenu sans les redifinitions ou extensions fait à aux propriétées de cet objet par du code contenu. (Dans la términolgie Firefox, le code privilégié voit les élément au travers d'un “xray wrapper”). Afin de s'assurer que le code du débogueur voit chaque objet comme le code débogué le verait, chaque instance de Debugger.Object présente son référent comme il serait vu depuis un compartiment particulier. Ce “viewing compartment” est chosi pour corespondre à la foçon dont le débogueur rencontre le référent. En conséquence, une seule instance de Debugger peut avoir en réalitée plusieurs instances de Debugger.Object : une par compartiment depuis lequel le référent est vu.

Si plus d'une instance de Debugger est en train de débouer le même code, chaque Debugger obtient une instance de Debugger.Object pour chaque objet donné. Cela permet au code utilisant chaque instance de Debugger de placer les propriétés qu'elle veut sur ses propres instance de Debugger.Object, cela sans avoir à s'inquiéter d'interferer avec d'autres débogueurs.

Tandis que la plupart des instances Debugger.Object sont crées SpiderMonkey dans processus d'exposition des comportements et états du code débogué au débogueur, le débogueur peut utiliser Debugger.Object.prototype.makeDebuggeeValue pour créer des instances de Debugger.Object pour un objet du code déboguer donné, ou utiliser Debugger.Object.prototype.copy et Debugger.Object.prototype.create pour créer de nouveaux objets dans les compartiment du code débogué, alloués comme elles l'auraient été par des gloables du code débogué.

Les instances de Debugger.Object protègent leurs référents du garbage collector. Aussi logntemps que l'instance de Debugger.Object est vivante, le référent l'est aussi. Cela veut dire que le garbage collection n'a pas d'effet visible sur les instances de Debugger.Object.

Accessor Properties of the Debugger.Object prototype

A Debugger.Object instance inherits the following accessor properties from its prototype:

proto
The referent’s prototype (as a new Debugger.Object instance), or null if it has no prototype.
class
A string naming the ECMAScript [[Class]] of the referent.
callable
true if the referent is a callable object (such as a function or a function proxy); false otherwise.
name

The name of the referent, if it is a named function. If the referent is an anonymous function, or not a function at all, this is undefined.

This accessor returns whatever name appeared after the function keyword in the source code, regardless of whether the function is the result of instantiating a function declaration (which binds the function to its name in the enclosing scope) or evaluating a function expression (which binds the function to its name only within the function’s body).

displayName

The referent’s display name, if the referent is a function with a display name. If the referent is not a function, or if it has no display name, this is undefined.

If a function has a given name, its display name is the same as its given name. In this case, the displayName and name properties are equal.

If a function has no name, SpiderMonkey attempts to infer an appropriate name for it given its context. For example:

function f() {}          // display name: f (the given name)
var g = function () {};  // display name: g
o.p = function () {};    // display name: o.p
var q = {
  r: function () {}      // display name: q.r
};

Note that the display name may not be a proper JavaScript identifier, or even a proper expression: we attempt to find helpful names even when the function is not immediately assigned as the value of some variable or property. Thus, we use a/b to refer to theb defined withina, and a< to refer to a function that occurs somewhere within an expression that is assigned toa. For example:

function h() {
  var i = function() {};    // display name: h/i
  f(function () {});        // display name: h/<
}
var s = f(function () {});  // display name: s<
parameterNames

If the referent is a debuggee function, the names of the its parameters, as an array of strings. If the referent is not a debuggee function, or not a function at all, this is undefined.

If the referent is a host function for which parameter names are not available, return an array with one element per parameter, each of which is undefined.

If the referent is a function proxy, return an empty array.

If the referent uses destructuring parameters, then the array’s elements reflect the structure of the parameters. For example, if the referent is a function declared in this way:

function f(a, [b, c], {d, e:f}) { ... }

then this Debugger.Object instance’s parameterNames property would have the value:

["a", ["b", "c"], {d:"d", e:"f"}]
script
If the referent is a function that is debuggee code, this is that function’s script, as a Debugger.Script instance. If the referent is a function proxy or not debuggee code, this is undefined.
environment
If the referent is a function that is debuggee code, a Debugger.Environment instance representing the lexical environment enclosing the function when it was created. If the referent is a function proxy or not debuggee code, this is undefined.
errorMessageName
If the referent is an error created with an engine internal message template this is a string which is the name of the template; undefined otherwise.
isBoundFunction
If the referent is a debuggee function, returns true if the referent is a bound function; false otherwise. If the referent is not a debuggee function, or not a function at all, returns undefined instead.
isArrowFunction
If the referent is a debuggee function, returns true if the referent is an arrow function; false otherwise. If the referent is not a debuggee function, or not a function at all, returns undefined instead.
isPromise
true if the referent is a Promise; false otherwise.
boundTargetFunction
If the referent is a bound debuggee function, this is its target function— the function that was bound to a particular this object. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is undefined.
boundThis
If the referent is a bound debuggee function, this is the this value it was bound to. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is undefined.
boundArguments
If the referent is a bound debuggee function, this is an array (in the Debugger object’s compartment) that contains the debuggee values of the arguments object it was bound to. If the referent is either not a bound function, not a debuggee function, or not a function at all, this is undefined.
isProxy
If the referent is a (scripted) proxy, either revoked or not, return true. If the referent is not a (scripted) proxy, return false.
proxyTarget
If the referent is a non-revoked (scripted) proxy, return a Debugger.Object instance referring to the ECMAScript [[ProxyTarget]] of the referent. If the referent is a revoked (scripted) proxy, return null. If the referent is not a (scripted) proxy, return undefined.
proxyHandler
If the referent is a non-revoked (scripted) proxy, return a Debugger.Object instance referring to the ECMAScript [[ProxyHandler]] of the referent. If the referent is a revoked (scripted) proxy, return null. If the referent is not a (scripted) proxy, return undefined.
promiseState

If the referent is a Promise, return a string indicating whether the Promise is pending, or has been fulfilled or rejected. This string takes one of the following values:

  • "pending", if the Promise is pending.

  • "fulfilled", if the Promise has been fulfilled.

  • "rejected", if the Promise has been rejected.

If the referent is not a Promise, throw a TypeError.

promiseValue

Return a debuggee value representing the value the Promise has been fulfilled with.

If the referent is not a Promise, or the Promise has not been fulfilled, throw a TypeError.

promiseReason

Return a debuggee value representing the value the Promise has been rejected with.

If the referent is not a Promise, or the Promise has not been rejected, throw a TypeError.

promiseAllocationSite
If the referent is a Promise, this is the JavaScript execution stack captured at the time of the promise’s allocation. This can return null if the promise was not created from script. If the referent is not a Promise, throw a TypeError exception.
promiseResolutionSite
If the referent is a Promise, this is the JavaScript execution stack captured at the time of the promise’s resolution. This can return null if the promise was not resolved by calling its resolve or reject resolving functions from script. If the referent is not a Promise, throw a TypeError exception.
promiseID
If the referent is a Promise, this is a process-unique identifier for the Promise. With e10s, the same id can potentially be assigned to multiple Promise instances, if those instances were created in different processes. If the referent is not a Promise, throw a TypeError exception.
promiseDependentPromises
If the referent is a Promise, this is an Array of Debugger.Objects referring to the promises directly depending on the referent Promise. These are:
  1. Return values of then() calls on the promise.
  2. Return values of Promise.all() if the referent Promise was passed in as one of the arguments.
  3. Return values of Promise.race() if the referent Promise was passed in as one of the arguments.

Once a Promise is settled, it will generally notify its dependent promises and forget about them, so this is most useful on pending promises.

Note that the Array only contains the promises that directly depend on the referent Promise. It does not contain promises that depend on promises that depend on the referent Promise.

If the referent is not a Promise, throw a TypeError exception.

promiseLifetime
If the referent is a Promise, this is the number of milliseconds elapsed since the Promise was created. If the referent is not a Promise, throw a TypeError exception.
promiseTimeToResolution
If the referent is a Promise, this is the number of milliseconds elapsed between when the Promise was created and when it was resolved. If the referent hasn’t been resolved or is not a Promise, throw a TypeError exception.
global
A Debugger.Object instance referring to the global object in whose scope the referent was allocated. This does not unwrap cross-compartment wrappers: if the referent is a wrapper, the result refers to the wrapper’s global, not the wrapped object’s global. The result refers to the global directly, not via a wrapper.
allocationSite
If object allocation site tracking was enabled when this Debugger.Object’s referent was allocated, return the JavaScript execution stack captured at the time of the allocation. Otherwise, return null.

Function Properties of the Debugger.Object prototype

The functions described below may only be called with a this value referring to a Debugger.Object instance; they may not be used as methods of other kinds of objects. The descriptions use “referent” to mean “the referent of this Debugger.Object instance”.

Unless otherwise specified, these methods are not invocation functions; if a call would cause debuggee code to run (say, because it gets or sets an accessor property whose handler is debuggee code, or because the referent is a proxy whose traps are debuggee code), the call throws a Debugger.DebuggeeWouldRun exception.

getProperty(name)
Return the value of the referent’s property namedname, or undefined if it has no such property.Name must be a string. The result is a debuggee value.
setProperty(name,value)
Storevalue as the value of the referent’s property namedname, creating the property if it does not exist.Name must be a string;value must be a debuggee value.
getOwnPropertyDescriptor(name)
Return a property descriptor for the property namedname of the referent. If the referent has no such property, return undefined. (This function behaves like the standard Object.getOwnPropertyDescriptor function, except that the object being inspected is implicit; the property descriptor returned is allocated as if by code scoped to the debugger’s global object (and is thus in the debugger’s compartment); and its value, get, and set properties, if present, are debuggee values.)
getOwnPropertyNames()
Return an array of strings naming all the referent’s own properties, as if Object.getOwnPropertyNames(referent) had been called in the debuggee, and the result copied in the scope of the debugger’s global object.
getOwnPropertySymbols()
Return an array of strings naming all the referent’s own symbols, as if Object.getOwnPropertySymbols(referent) had been called in the debuggee, and the result copied in the scope of the debugger’s global object.
defineProperty(name,attributes)
Define a property on the referent namedname, as described by the property descriptordescriptor. Any value, get, and set properties ofattributes must be debuggee values. (This function behaves like Object.defineProperty, except that the target object is implicit, and in a different compartment from the function and descriptor.)
defineProperties(properties)
Add the properties given byproperties to the referent. (This function behaves like Object.defineProperties, except that the target object is implicit, and in a different compartment from theproperties argument.)
deleteProperty(name)
Remove the referent’s property namedname. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable.
seal()
Prevent properties from being added to or deleted from the referent. Return this Debugger.Object instance. (This function behaves like the standard Object.seal function, except that the object to be sealed is implicit and in a different compartment from the caller.)
freeze()
Prevent properties from being added to or deleted from the referent, and mark each property as non-writable. Return this Debugger.Object instance. (This function behaves like the standard Object.freeze function, except that the object to be sealed is implicit and in a different compartment from the caller.)
preventExtensions()
Prevent properties from being added to the referent. (This function behaves like the standard Object.preventExtensions function, except that the object to operate on is implicit and in a different compartment from the caller.)
isSealed()
Return true if the referent is sealed—that is, if it is not extensible, and all its properties have been marked as non-configurable. (This function behaves like the standard Object.isSealed function, except that the object inspected is implicit and in a different compartment from the caller.)
isFrozen()
Return true if the referent is frozen—that is, if it is not extensible, and all its properties have been marked as non-configurable and read-only. (This function behaves like the standard Object.isFrozen function, except that the object inspected is implicit and in a different compartment from the caller.)
isExtensible()
Return true if the referent is extensible—that is, if it can have new properties defined on it. (This function behaves like the standard Object.isExtensible function, except that the object inspected is implicit and in a different compartment from the caller.)
copy(value)

Apply the HTML5 “structured cloning” algorithm to create a copy ofvalue in the referent’s global object (and thus in the referent’s compartment), and return a Debugger.Object instance referring to the copy.

Note that this returns primitive values unchanged. This means you can use Debugger.Object.prototype.copy as a generic “debugger value to debuggee value” conversion function—within the limitations of the “structured cloning” algorithm.

create(prototype, [properties])
Create a new object in the referent’s global (and thus in the referent’s compartment), and return a Debugger.Object referring to it. The new object’s prototype isprototype, which must be an Debugger.Object instance. The new object’s properties are as given byproperties, as ifproperties were passed to Debugger.Object.prototype.defineProperties, with the new Debugger.Object instance as the this value.
makeDebuggeeValue(value)

Return the debuggee value that representsvalue in the debuggee. Ifvalue is a primitive, we return it unchanged; ifvalue is an object, we return the Debugger.Object instance representing that object, wrapped appropriately for use in this Debugger.Object’s referent’s compartment.

Note that, ifvalue is an object, it need not be one allocated in a debuggee global, nor even a debuggee compartment; it can be any object the debugger wishes to use as a debuggee value.

As described above, each Debugger.Object instance presents its referent as viewed from a particular compartment. Given a Debugger.Object instanced and an objecto, the call d.makeDebuggeeValue(o) returns a Debugger.Object instance that presentso as it would be seen by code ind’s compartment.

decompile([pretty])
If the referent is a function that is debuggee code, return the JavaScript source code for a function definition equivalent to the referent function in its effect and result, as a string. Ifpretty is present and true, produce indented code with line breaks. If the referent is not a function that is debuggee code, return undefined.
call(this,argument, …)
If the referent is callable, call it with the giventhis value andargument values, and return a completion value describing how the call completed.This should be a debuggee value, or { asConstructor: true } to invoke the referent as a constructor, in which case SpiderMonkey provides an appropriate this value itself. Eachargument must be a debuggee value. All extant handler methods, breakpoints, and so on remain active during the call. If the referent is not callable, throw a TypeError. This function follows the invocation function conventions.
apply(this,arguments)
If the referent is callable, call it with the giventhis value and the argument values inarguments, and return a completion value describing how the call completed.This should be a debuggee value, or { asConstructor: true } to invokefunction as a constructor, in which case SpiderMonkey provides an appropriate this value itself.Arguments must either be an array (in the debugger) of debuggee values, or null or undefined, which are treated as an empty array. All extant handler methods, breakpoints, and so on remain active during the call. If the referent is not callable, throw a TypeError. This function follows the invocation function conventions.
executeInGlobal(code, [options])

If the referent is a global object, evaluatecode in that global environment, and return a completion value describing how it completed.Code is a string. All extant handler methods, breakpoints, and so on remain active during the call. This function follows the invocation function conventions. If the referent is not a global object, throw a TypeError exception.

Codeis interpreted as strict mode code when it contains a Use Strict Directive.

This evaluation is semantically equivalent to executing statements at the global level, not an indirect eval. Regardless ofcode being strict mode code, variable declarations incode affect the referent global object.

Theoptions argument is as for Debugger.Frame.prototype.eval.

executeInGlobalWithBindings(code,bindings, [options])

Like executeInGlobal, but evaluatecode using the referent as the variable object, but with a lexical environment extended with bindings from the objectbindings. For each own enumerable property ofbindings namedname whose value isvalue, include a variable in the lexical environment in whichcode is evaluated namedname, whose value isvalue. Eachvalue must be a debuggee value. (This is not like a with statement:code may access, assign to, and delete the introduced bindings without having any effect on thebindings object.)

This method allows debugger code to introduce temporary bindings that are visible to the given debuggee code and which refer to debugger-held debuggee values, and do so without mutating any existing debuggee environment.

Note that, like executeInGlobal, any declarations it contains affect the referent global object, even ascode is evaluated in an environment extended according tobindings. (In the terms used by the ECMAScript specification, the VariableEnvironment of the execution context forcode is the referent, and thebindings appear in a new declarative environment, which is the eval code’s LexicalEnvironment.)

Theoptions argument is as for Debugger.Frame.prototype.eval.

asEnvironment()
If the referent is a global object, return the Debugger.Environment instance representing the referent’s global lexical scope. The global lexical scope’s enclosing scope is the global object. If the referent is not a global object, throw a TypeError.
unwrap()
If the referent is a wrapper that this Debugger.Object’s compartment is permitted to unwrap, return a Debugger.Object instance referring to the wrapped object. If we are not permitted to unwrap the referent, return null. If the referent is not a wrapper, return this Debugger.Object instance unchanged.
unsafeDereference()

Return the referent of this Debugger.Object instance.

If the referent is an inner object (say, an HTML5 Window object), return the corresponding outer object (say, the HTML5 WindowProxy object). This makes unsafeDereference more useful in producing values appropriate for direct use by debuggee code, without using invocation functions.

This method pierces the membrane of Debugger.Object instances meant to protect debugger code from debuggee code, and allows debugger code to access debuggee objects through the standard cross-compartment wrappers, rather than via Debugger.Object’s reflection-oriented interfaces. This method makes it easier to gradually adapt large code bases to this Debugger API: adapted portions of the code can use Debugger.Object instances, but use this method to pass direct object references to code that has not yet been updated.

forceLexicalInitializationByName(binding)
Ifbinding is in an uninitialized state initialize it to undefined and return true, otherwise do nothing and return false.

Source Metadata

Generated from file:
 
js/src/doc/Debugger/Debugger.Object.md
Watermark:
sha256:769e72a8136b921b313d24b17ffc23ab290ce65b413ed8ba86e597904261acb2
Changeset:
7ae377917236

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : maximelore
 Dernière mise à jour par : maximelore,