Confirmed users
497
edits
Debugger: Difference between revisions
Specify Proxy introspection interface.
(Define the Debugger.DebuggeeWouldRun exception. Add Debugger.Object.prototype.get/setProperty, Debugger.Environment.prototype.get/setVariable.) |
(Specify Proxy introspection interface.) |
||
| Line 82: | Line 82: | ||
=== The Debugger.DebuggeeWouldRun Exception === | === The Debugger.DebuggeeWouldRun Exception === | ||
Some debugger operations that appear to simply inspect the debuggee's state would actually cause the debuggee to execute code. For example, reading a variable could run a getter on the global or a <code>with</code> expression operand, and getting an object's property descriptor could run handler | Some debugger operations that appear to simply inspect the debuggee's state would actually cause the debuggee to execute code. For example, reading a variable could run a getter on the global or a <code>with</code> expression operand, and getting an object's property descriptor could run a handler trap if the object is a proxy. To protect the debugger's integrity, only operations whose stated purpose is to run debuggee code can do so; these are called [[#Invocation_functions|invocation functions]], and follow certain common conventions to report the debuggee's behavior safely. Any other operation that would run debuggee code throws an instance of the <code>Debugger.DebuggeeWouldRun</code> exception. | ||
=== Invocation functions === | === Invocation functions === | ||
| Line 522: | Line 522: | ||
<dt>callable | <dt>callable | ||
<dd><code>true</code> if the referent is a callable object (such as a function or a function | <dd><code>true</code> if the referent is a callable object (such as a function or a function proxy); false otherwise. | ||
<dt>name | <dt>name | ||
| Line 531: | Line 531: | ||
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 <code>undefined</code>. | 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 <code>undefined</code>. | ||
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: | 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: | ||
| Line 541: | Line 543: | ||
<dt>script | <dt>script | ||
<dd>If the referent is a function implemented in JavaScript, that function's script, as a <code>Debugger.Script</code> instance. If the referent is not a function implemented in JavaScript, this is <code>undefined</code>. | <dd>If the referent is a function implemented in JavaScript, that function's script, as a <code>Debugger.Script</code> instance. If the referent is a function proxy or not a function implemented in JavaScript, this is <code>undefined</code>. | ||
<dt>environment | <dt>environment | ||
<dd>If the referent is a function implemented in JavaScript, a <code>Debugger.Environment</code> instance representing the lexical environment enclosing the function when it was created. If the referent is not a function implemented in JavaScript, | <dd>If the referent is a function implemented in JavaScript, a <code>Debugger.Environment</code> instance representing the lexical environment enclosing the function when it was created. If the referent is a function proxy or not a function implemented in JavaScript, this is <code>undefined</code>. | ||
<dt>proxyHandler | |||
<dd>If the referent is a proxy, its handler—the object whose methods are invoked to implement accesses of the proxy's properties. If the referent is not a proxy, this is <code>null</code>. | |||
<dt>proxyCallTrap | |||
<dd>If the referent is a function proxy, its call trap function—the function called when the function proxy is called. If the referent is not a function proxy, this is <code>null</code>. | |||
<dt>proxyConstructTrap | |||
<dd>If the referent is a function proxy, its construction trap function—the function called when the function proxy is called via a <code>new</code> expression. If the referent is not a function proxy, this is <code>null</code>. | |||
</dl> | </dl> | ||
=== Properties of the Debugger.Object prototype === | === Function Properties of the Debugger.Object prototype === | ||
The functions described below may only be called with a <code>this</code> value referring to a <code>Debugger.Object</code> instance; they may not be used as methods of other kinds of objects. The descriptions use "referent" to mean "the referent of this <code>Debugger.Object</code> instance". | The functions described below may only be called with a <code>this</code> value referring to a <code>Debugger.Object</code> instance; they may not be used as methods of other kinds of objects. The descriptions use "referent" to mean "the referent of this <code>Debugger.Object</code> instance". | ||
Unless otherwise specified, these methods are not [[#Invocation_functions|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 <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<dl> | <dl> | ||
<dt>getProperty(<i>name</i>) | <dt>getProperty(<i>name</i>) | ||
<dd>Return the value of the referent's property named <i>name</i>, or <code>undefined</code> if it has no such property. <i>Name</i> must be a string. The result is a debuggee value | <dd>Return the value of the referent's property named <i>name</i>, or <code>undefined</code> if it has no such property. <i>Name</i> must be a string. The result is a debuggee value. | ||
<dt>setProperty(<i>name</i>, <i>value</i>) | <dt>setProperty(<i>name</i>, <i>value</i>) | ||
<dd>Store <i>value</i> as the value of the referent's property named <i>name</i>, creating the property if it does not exist. <i>Name</i> must be a string; <i>value</i> must be a debuggee value | <dd>Store <i>value</i> as the value of the referent's property named <i>name</i>, creating the property if it does not exist. <i>Name</i> must be a string; <i>value</i> must be a debuggee value. | ||
<dt>getOwnPropertyDescriptor(<i>name</i>) | <dt>getOwnPropertyDescriptor(<i>name</i>) | ||
<dd>Return a property descriptor for the property named <i>name</i> of the referent. If the referent has no such property, return <code>undefined</code>. (This function behaves like the standard <code>Object.getOwnPropertyDescriptor</code> function, except that the object being inspected is implicit; the property descriptor returned is in the debugger's compartment; and its <code>value</code>, <code>get</code>, and <code>set</code> properties, if present, are debuggee values.) | <dd>Return a property descriptor for the property named <i>name</i> of the referent. If the referent has no such property, return <code>undefined</code>. (This function behaves like the standard <code>Object.getOwnPropertyDescriptor</code> function, except that the object being inspected is implicit; the property descriptor returned is in the debugger's compartment; and its <code>value</code>, <code>get</code>, and <code>set</code> properties, if present, are debuggee values.) | ||
<dt>getOwnPropertyNames() | <dt>getOwnPropertyNames() | ||
<dd>Return an array of strings naming all the referent's own properties, as if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been called in the debuggee, and the result copied to the debugger's compartment. | <dd>Return an array of strings naming all the referent's own properties, as if <code>Object.getOwnPropertyNames(<i>referent</i>)</code> had been called in the debuggee, and the result copied to the debugger's compartment. | ||
<dt>defineProperty(<i>name</i>, <i>attributes</i>) | <dt>defineProperty(<i>name</i>, <i>attributes</i>) | ||
<dd>Define a property on the referent named <i>name</i>, as described by the property descriptor <i>descriptor</i>. Any <code>value</code>, <code>get</code>, and <code>set</code> properties of <i>attributes</i> must be debuggee values. (This function behaves like <code>Object.defineProperty</code>, except that the target object is implicit, and in a different compartment from the function and descriptor.) | <dd>Define a property on the referent named <i>name</i>, as described by the property descriptor <i>descriptor</i>. Any <code>value</code>, <code>get</code>, and <code>set</code> properties of <i>attributes</i> must be debuggee values. (This function behaves like <code>Object.defineProperty</code>, except that the target object is implicit, and in a different compartment from the function and descriptor.) | ||
<dt>defineProperties(<i>properties</i>) | <dt>defineProperties(<i>properties</i>) | ||
<dd>Add the properties given by <i>properties</i> to the referent. (This function behaves like <code>Object.defineProperties</code>, except that the target object is implicit, and in a different compartment from the <i>properties</i> argument.) | <dd>Add the properties given by <i>properties</i> to the referent. (This function behaves like <code>Object.defineProperties</code>, except that the target object is implicit, and in a different compartment from the <i>properties</i> argument.) | ||
<dt>deleteProperty(<i>name</i>) | <dt>deleteProperty(<i>name</i>) | ||
<dd>Remove the referent's property named <i>name</i>. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable. | <dd>Remove the referent's property named <i>name</i>. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable. | ||
<dt>seal() | <dt>seal() | ||
<dd>Prevent properties from being added to or deleted from the referent. Return this <code>Debugger.Object</code> instance. (This function behaves like the standard <code>Object.seal</code> function, except that the object to be sealed is implicit and in a different compartment from the caller.) | <dd>Prevent properties from being added to or deleted from the referent. Return this <code>Debugger.Object</code> instance. (This function behaves like the standard <code>Object.seal</code> function, except that the object to be sealed is implicit and in a different compartment from the caller.) | ||
<dt>freeze() | <dt>freeze() | ||
<dd>Prevent properties from being added to or deleted from the referent, and mark each property as non-writable. Return this <code>Debugger.Object</code> instance. (This function behaves like the standard <code>Object.freeze</code> function, except that the object to be sealed is implicit and in a different compartment from the caller.) | <dd>Prevent properties from being added to or deleted from the referent, and mark each property as non-writable. Return this <code>Debugger.Object</code> instance. (This function behaves like the standard <code>Object.freeze</code> function, except that the object to be sealed is implicit and in a different compartment from the caller.) | ||
<dt>preventExtensions() | <dt>preventExtensions() | ||
<dd>Prevent properties from being added to the referent. (This function behaves like the standard <code>Object.preventExtensions</code> function, except that the object to operate on is implicit and in a different compartment from the caller.) | <dd>Prevent properties from being added to the referent. (This function behaves like the standard <code>Object.preventExtensions</code> function, except that the object to operate on is implicit and in a different compartment from the caller.) | ||
<dt>isSealed() | <dt>isSealed() | ||