Debugger.Object

This article covers features introduced in SpiderMonkey 1.8.6

A Debugger.Object instance represents an object in the script being debugged. Debugger code never directly accesses debuggee objects; instead, it operates on Debugger.Object instances that, in turn, refer to the objects in the debuggee.

Accessor properties

Instances of Debugger.Object inherit these properties from the prototype.

Property Type Description
callable Boolean true if the referent is a callable object, such as a Function or function proxy; otherwise false.
class String The ECMAScript Class of the object to which the instance refers, as a string.
environment Debugger.Environment If the referent is a function implemented in JavaScript, this is the lexical environment enclosing the function when it was created. Otherwise, this is undefined.
name String If the referent is a function, this is the function's name. If the referent is an anonymous function or is not a function at all, this is undefined.
parameterNames Array of String

If the referent is a function, this is an array of strings indicating the names of each of its parameters. If the referent isn't a function, this is undefined. If the parameter names are unavailable, the array has one element per parameter, but each parameter is undefined. For function proxies, this is an empty array.

If the referent uses destructuring parameters, the elements in the array reflect the structure of the parameters. For example, if the referent is a function declared as below:

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

This property's value would be:

["a", ["b", "c"], {d:"d", e:"f"}]
proto Debugger.Object The prototype of the object to which the instance refers, or null if it has no prototype.
proxyCallTrap Debugger.Object If the referent is a function proxy, this is its call trap function; that is, the function called when the function proxy is called. Otherwise, this is null.
proxyConstructTrap Debugger.Object If the referent is a function proxy, this is its construction trap function; that is, the function called when the function proxy is called using a new expression. Otherwise, this is null.
proxyHandler Debugger.Object If the referent is a proxy, this is its handler; that is, the object whose methods are invoked to implement access to the proxy's properties. Otherwise, this is null.
script Debugger.Script If the referent is a function implemented in JavaScript, this is a Debugger.Script instance representing that script. Otherwise this is undefined.

Methods

These methods must be called with a this value referring to the Debugger.Object instance.

Note: Unless otherwise specified, none of these functions are invocation functions; that is, if a call to a Debugger.Object method would cause debuggee code to run (for example, 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.

 

Method Return value Description
apply() Completion value Calls the referent (if it's callable), passing the values in an array as the arguments to the referent.Throws a TypeError if it's not callable.
asEnvironment() Debugger.Environment Returns the Debugger.Environment representing the referent as a variable environment for executing code. If the referent isn't a global object, throws TypeError.
call() Completion value Calls the referent, if it's callable. Throws a TypeError if it's not callable.
copy() Debugger.Object Applies the HTML5 structured cloning algorithm to create a copy of the specified value in the referent's compartment, returning a Debugger.Object instance referring to the copy.
create() Debugger.Object Creates a new object in the referent's compartment.
decompile() String Returns JavaScript source code equivalent to the referent function in its effect and result. If the referent isn't a function, returns undefined.
defineProperties() n/a Adds multiple properties, from an array, to the referent.
defineProperty() n/a Defines a property on the referent.
deleteProperty() Boolean Removes a property from the referent, returning true if successful or false otherwise.
evalInGlobal() Completion value If the referent is a global object, evaluates the specified code in that environment.
evalInGlobalWithBindings() Completion value If the referent is a global object, evaluates the specified code in that environment, but with the lexical environment extended with specified bindings.
freeze() Debugger.Object Prevents properties from being added to or deleted from the referent, and also marks all properties as read-only. Returns this Debugger.Object instance.
getOwnPropertyDescriptor() ??? Returns a property descriptor for a given property.
getOwnPropertyNames() Array of String Returns a list of all the referent's property names.
getProperty() Debuggee value Returns the value of the referent's property by a given name.
isExtensible() Boolean Returns true if the referent is extensible; otherwise false.
isFrozen() Boolean Returns true if the referent is frozen; otherwise false.
isSealed() Boolean Returns true if the referent is sealed; otherwise false.
makeDebuggeeValue() ??? Returns a Debugger.Object from the same compartment.
preventExtensions() Debugger.Object Prevents properties from being added to the referent.
seal() Debugger.Object Prevents properties from being added to or deleted from the referent. Returns this Debugger.Object instance.
setProperty() n/a

Sets the value of a property in the referent object.

apply()

Calls the referent, returning a completion value describing how the call completed. All existing hook methods, breakpoints, watchpoints, and so forth remain active during the call. The invocation function conventions are followed.

apply(  
  this,  
  arguments
);
Parameters
this
The value to use as this while running the referent's code. This must either be a debuggee value or { asConstructor: true } to invoke the referent as a constructor; in this case, SpiderMonkey will provide an appropriate value for this.
arguments
An array of arguments to pass to the referent function as its arguments. Each element must be a debuggee value. You may specify null or undefined for the arguments parameter to pass no arguments to the referent.
Return value

Returns a completion value describing the circumstances of the call's completion.

Exceptions thrown
TypeError
The referent is not callable.

asEnvironment()

If the referent is a global object, returns the Debugger.Environment instance representing the referent as a global environment for evaluating code.

Debugger.Environment asEnvironment();
Parameters

None.

Return value

The Debugger.Environment instance representing the referent as a global environment for evaluating code.

Exceptions thrown
TypeError
The referent isn't a global object.

call()

Calls the referent, returning a completion value describing how the call completed. All existing hook methods, breakpoints, watchpoints, and so forth remain active during the call. The invocation function conventions are followed.

apply(  
  this,  
  [argument[,...]]
);
Parameters
this
The value to use as this while running the referent's code. This must either be a debuggee value or { asConstructor: true } to invoke the referent as a constructor; in this case, SpiderMonkey will provide an appropriate value for this.
argument... Optional
Zero or more arguments to pass to the referent function as its arguments. Each argument must be a debuggee value. You may specify null or undefined for the arguments parameter to pass no arguments to the referent.
Return value

Returns a completion value describing the circumstances of the call's completion.

Exceptions thrown
TypeError
The referent is not callable.

copy()

Applies the HTML5 structured clone algorithm to create a copy of a value in the debuggee's compartment, returning a Debugger.Object instance referring to the new copy.

Debugger.Object copy(
  value
);
Parameters
value
The value to copy. This is a value in the debugger's compartment.
Return value

A Debugger.Object instance referring to the new copy of value in the debuggee's compartment.

Note: Primitive values are returned unchanged. This lets you use copy() to convert debugger values to debuggee values, within the limitations of the structured clone algorithm.

create()

Creates a new object in the referent's compartment, returning a Debugger.Object instance referring to the new object.

Debugger.Object create(
  prototype,
  [optional] properties
);
Parameters
Return value

A Debugger.Object instance referring to the newly-created object. The new object's properties are taken from the properties array, just as if you had passed that array to defineProperties() with the new Debugger.Object instance as its this value.

decompile()

If the referent is a JavaScript function, this method returns source code for a JavaScript function definition that's equivalent to the referent function in both effect and result.

String decompile(
  pretty
);
prototype
The prototype for the new object. This must be a debuggee object.
properties Optional
The new object's properties.
Parameters
pretty Optional
If specified and true, the returned source code is indented with line breaks to be more readable. Otherwise, the code is compact.
Return value

A String containing a JavaScript function definition matching the referent's code, or undefined if the referent isn't a function.

defineProperties()

Defines the properties described by the specified object to the referent. See Object.defineProperties() in the JavaScript Reference for details; this works the same way, except that the target object is implicit and in a different compartment from the properties argument.

defineProperties(
  properties
);
Parameters
properties
An object whose enumerable properties are descriptors for the properties to define or modify on the referent.

defineProperty()

Defines a property on the referent. See Object.defineProperty() in the JavaScript Reference for details. This method works the same way, except that the target object is implicit and in a different compartment from both the function and the descriptor.

defineProperty(
  name,
  descriptor
);
Parameters
name
The name of the property to define.
descriptor
The property descriptor for the property to define. Any value, get, and set properties must be debuggee values.

deleteProperty()

Deletes a property from the referent.

Boolean deleteProperty(
  name
);
Parameters
name
The name of the parameter to delete.
Return value

true if the property was successfully removed, or didn't exist. false if the property is read only and can't be deleted.

evalInGlobal()

Evaluates code in the environment of the referent (if it's a global object). All hook functions, breakpoints, watchpoints, and so forth are retained during the code's execution. Invocation function conventions are followed.

Note: The code is interpreted as strict mode code when it contains a "use strict" directive. If the code isn't in strict mode, variable declarations in the code affect the referent global object.
evalInGlobal(
  code
);
Parameters
code
A string containing the JavaScript code to execute in the global object's environment.
Return value

Returns a completion value indicating how the code's execution completed.

Exceptions thrown
TypeError
The referent isn't a global object.

evalInGlobalWithBindings()

Like evalInGlobal(), this evaluates code in the environment of the referent (if it's a global object). All hook functions, breakpoints, watchpoints, and so forth are retained during the code's execution. Invocation function conventions are followed. The difference is that this method extends the lexical environment in which the code is executed with additional bindings.

Note: The code is interpreted as strict mode code when it contains a "use strict" directive. If the code isn't in strict mode, variable declarations in the code affect the referent global object.
evalInGlobalWithBindings(
  code,
  bindings
);
Parameters
code
A string containing the JavaScript code to execute in the global object's environment.
bindings
An object from which to include additional bindings. For each own enumerable property of this object, a variable is created with that property's name and value in the lexical environment in which the code will be evaluated. Each value must be a debuggee value. These additional variables are copies of the properties in the bindings object; changes to those variables are not reflected back into the bindings object.
Return value

Returns a completion value indicating how the code's execution completed.

Exceptions thrown
TypeError
The referent isn't a global object.

freeze()

Prevents properties from being added to or deleted from the referent. In addition, each existing property is made read-only and non-configurable. See Object.freeze() for details; this method is functionally equivalent, except the object to be frozen is implicit and in a different compartment from the caller.

Debugger.Object freeze();
Parameters

None.

Return value

This Debugger.Object instance.

getOwnPropertyDescriptor()

Returns a property descriptor for the named property in the referent. See Object.getOwnPropertyDescriptor() for details; this method is functionally equivalent, except that the object being inspected is implicit, the property descriptor that's returned is in the debugger's compartment, and its value, get, and set properties, if they exist, are debuggee values.

getOwnPropertyDescriptor(
  name
);
Parameters
name
The name of the property for which to return a property descriptor.
Return value

A property descriptor for the named property, or undefined if no such property exists.

getOwnPropertyNames()

Returns an array of strings naming all the referent's own properties, as if Object.getOwnPropertyNames(referent) had been called in the debuggee's compartment and the result then copied to the debugger's compartment.

Array getOwnPropertyNames();
Parameters

None.

Return value

An array of strings, each element the name of one of the referent's own properties.

getProperty()

Returns the value of the referent's property with the specified name.

getProperty(
  name
);
Parameters
name
A String identifying the name of the property to return the value of.
Return value

The specified property's value as a debuggee value, or undefined if the specified property doesn't exist.

isExtensible()

Reports whether or not the referent object is extensible; that is, if it can have new properties defined on it. This works just like the Object.isExtensible() method, except the object being inspected is implicit and is in a different compartment from the caller.

Boolean isExtensible();
Properties

None.

Return value

true if the referent object can have new properties defined on it, otherwise false.

isFrozen()

Reports whether or not the referent object is frozen. A frozen object is not extensible, and all its properties are both read-only and non-configurable. This method is functionally equivalent to Object.isFrozen(), but the object to be inspected is implicit and is in a different compartment from the caller.

Boolean isFrozen();
Parameters

None.

Return value

true if the referent object is frozen; otherwise false.

isSealed()

Reports whether or not the referent object is sealed. A sealed object is not extensible, and all its properties are non-configurable. This method is functionally equivalent to Object.isSealed(), but the object to be inspected is implicit and is in a different compartment from the caller.

Boolean isSealed();
Paramters

None.

Return value

true if the referent object is sealed; otherwise false.

preventExtensions()

Prevents properties from being added to the referent object. This is functionally the same as Object.preventExtensions(), except the object on which it operates is implicit and in a different compartment than the caller.

Debugger.Object preventExtensions();
Parameters

None.

Return value

The Debugger.Object that was acted upon.

seal()

Prevents properties from being added to or deleted from the referent object, and returns the Debugger.Object. This is functionally the same as Object.seal(), but the object to be sealed is implicit and in a different compartment than the caller.

Debugger.Object seal();
Parameters

None.

Return value

The Debugger.Object that was sealed.

setProperty()

Sets the value of a property on the referent object, creating the property if it doesn't exist.

setProperty(
  name,
  value
);
Parameters
name
A string indicating the name of the property whose value is to be set.
value
A debuggee value indicating the value to assign to the property.

Document Tags and Contributors

Contributors to this page: Sheppy, thaddee.tyl@gmail.com
Last updated by: thaddee.tyl@gmail.com,