Confirmed users
497
edits
Debugger: Difference between revisions
Jump to navigation
Jump to search
Define the Debugger.DebuggeeWouldRun exception. Add Debugger.Object.prototype.get/setProperty, Debugger.Environment.prototype.get/setVariable.
(→Properties of the Debugger.Object prototype: Add Debugger.Object.prototype.asEnvironment.) |
(Define the Debugger.DebuggeeWouldRun exception. Add Debugger.Object.prototype.get/setProperty, Debugger.Environment.prototype.get/setVariable.) |
||
| Line 79: | Line 79: | ||
If a function that would normally return a resumption value to indicate how the debuggee should continue instead throws an exception, we never propagate such an exception to the debuggee; instead, we call the associated <code>Debugger</code> instance's <code>uncaughtExceptionHook</code> property, as described below. | If a function that would normally return a resumption value to indicate how the debuggee should continue instead throws an exception, we never propagate such an exception to the debuggee; instead, we call the associated <code>Debugger</code> instance's <code>uncaughtExceptionHook</code> property, as described below. | ||
=== 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 method 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 === | |||
An <i>invocation function</i> is any function in this interface that allows the debugger to invoke code in the debuggee: <code>Debugger.Object.prototype.call</code>, <code>Debugger.Frame.prototype.eval</code>, and so on. | |||
While invocation functions differ in the code to be run and how to pass values to it, they all follow this general procedure: | |||
<ol> | |||
<li>Let <i>older</i> be the youngest debuggee frame on the stack, or null if there is no such frame. (This is never one of the the debugger's own frames; those never appear as <code>Debugger.Frame</code> instances.) | |||
<li>Push a <code>"debugger"</code> frame on the stack, with <i>older</i> as its <code>older</code> property. | |||
<li>Invoke the debuggee code as appropriate for the given invocation function, with the <code>"debugger"</code> frame as its continuation. For example, <code>Debugger.Frame.prototype.eval</code> pushes an <code>"eval"</code> frame for code it runs, whereas <code>Debugger.Object.prototype.call</code> pushes a <code>"call"</code> frame. | |||
<li>When the debuggee code completes, whether by returning, throwing an exception or being terminated, pop the <code>"debugger"</code> frame, and return an appropriate [[#Completion_Values|completion value]] from the invocation function to the debugger. | |||
</ol> | |||
== The Debugger Object == | == The Debugger Object == | ||
| Line 358: | Line 375: | ||
</dl> | </dl> | ||
=== Generator Frames === | === Generator Frames === | ||
| Line 548: | Line 552: | ||
<dl> | <dl> | ||
<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. This is not an [[#Invocation_functions|invocation function]]; if this call would cause debuggee code to run (say, because the property is an accessor property with a getter), this call throws a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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. This is not an [[#Invocation_functions|invocation function]]; if this call would cause debuggee code to run, this call throws a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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. | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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. | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<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.) | ||
If the referent is a proxy, this may throw a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<dt>isSealed() | <dt>isSealed() | ||
| Line 593: | Line 619: | ||
<dt>call(<i>this</i>, <i>argument</i>, ...) | <dt>call(<i>this</i>, <i>argument</i>, ...) | ||
<dd>If the referent is callable, call it with the given <i>this</i> value and <i>argument</i> values, and return a [[#Completion_Values|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke the referent as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. Each <i>argument</i> must be a debuggee value. All extant hook object methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. | <dd>If the referent is callable, call it with the given <i>this</i> value and <i>argument</i> values, and return a [[#Completion_Values|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke the referent as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. Each <i>argument</i> must be a debuggee value. All extant hook object methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. This function follows the [[#Invocation_functions|invocation function conventions]]. | ||
<dt>apply(<i>this</i>, <i>arguments</i>) | <dt>apply(<i>this</i>, <i>arguments</i>) | ||
<dd>If the referent is callable, call it with the given <i>this</i> value and the argument values in <i>arguments</i>, and return a [[#Completion_Values|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke <i>function</i> as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. <i>Arguments</i> must either be an array (in the debugger) of debuggee values, or <code>null</code> or <code>undefined</code>, which are treated as an empty array. All extant hook object methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. | <dd>If the referent is callable, call it with the given <i>this</i> value and the argument values in <i>arguments</i>, and return a [[#Completion_Values|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke <i>function</i> as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. <i>Arguments</i> must either be an array (in the debugger) of debuggee values, or <code>null</code> or <code>undefined</code>, which are treated as an empty array. All extant hook object methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. This function follows the [[#Invocation_functions|invocation function conventions]]. | ||
<dt>asEnvironment() | <dt>asEnvironment() | ||
| Line 638: | Line 664: | ||
<dt>names() | <dt>names() | ||
<dd>Return an array of strings giving the names of the identifiers bound by this environment. | <dd>Return an array of strings giving the names of the identifiers bound by this environment. | ||
<dt>getVariable(<i>name</i>) | |||
<dd>Return the value of the variable named <i>name</i> in this environment, or <code>undefined</code> if it has no such variable. <i>Name</i> must be a string that is a valid identifier name. The result is a debuggee value. This is not an [[#Invocation_functions|invocation function]]; if this call would cause debuggee code to run (say, because the variable is an accessor property of the global object with a getter), this call throws a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<dt>setVariable(<i>name</i>, <i>value</i>) | |||
<dd>Store <i>value</i> as the value of the variable named <i>name</i> in this environment, creating the variable if it does not exist. <i>Name</i> must be a string that is a valid identifier name; <i>value</i> must be a debuggee value. This is not an [[#Invocation_functions|invocation function]]; if this call would cause debuggee code to run, this call throws a <code>Debugger.DebuggeeWouldRun</code> exception. | |||
<dt>getVariableDescriptor(<i>name</i>) | <dt>getVariableDescriptor(<i>name</i>) | ||