Debugger: Difference between revisions

== Debuggee Values ==

The <code>Debug</code> object follows certain conventions to help debuggers safely inspect and modify the debuggee's objects and values. Primitive values are passed freely between debugger and debuggee; copying or wrapping is handled transparently. Objects received from the debuggee (including host objects like DOM elements) are fronted in the debugger by <code>Debug.Object</code> instances, which provide reflection-oriented methods for inspecting their referents; see <code>Debug.Object</code>, below.

== Property Conventions ==

The <code>Debug</code> interface creates various sorts of objects to present the debuggee's state to the debugger. These objects' properties follow some conventions:

<ul>

<li>Properties described here are configurable. This applies to both "own" and prototype properties, and to both methods and data properties.

<li>Properties, both data and methods, are non-writable, unless stated otherwise. Since they are configurable, they can be made writable, but assigning to them has no effect on the debuggee unless stated otherwise.

<li>Instances and prototypes are extensible; you can add your own properties and methods to them.

</ul>

When execution reaches the given instruction, SpiderMonkey calls <i>handler</i>, passing a <code>Debug.Frame</code> instance representing the currently executing stack frame. The handler method's return value determines how execution should continue:

<li>If it returns an object of the form <code>{ throw: <i>value</i> }</code>, then <i>value</i> is thrown as an exception from the current bytecode instruction. <i>value</i> must be a debuggee value.

<li>If it returns null, the calling code is terminated, as if it had been cancelled by the "slow script" dialog box.

<dd>Set a watchpoint on the own property named <i>name</i> of the referent of the <code>Debug.Object</code> instance <i>object</i>, reporting events by calling <i>handler</i>'s methods. <i>Handler</i> may have the following methods, called under the given circumstances:

In all cases, the method's <i>frame</i> argument is the current stack frame, whose code is about to perform the operation on the object being reported.

 

The handler method's return value determines how execution proceeds, as described below for the <code>interrupt</code> hook function. Furthermore, <code>set</code> may return an object of the form <code>{ value:<i>newValue</i> }</code>, indicating that the property should have <i>newValue</i> assigned to it instead of the <i>value</i> passed to <code>set</code>.

<dd>A bytecode instruction is about to execute in the stack frame represented by <i>frame</i>, a <code>Debug.Frame</code> instance. Naturally, <i>frame</i> is the youngest debuggee frame.

 

This hook function's return value determines how execution should continue:

<li>If it returns an object of the form <code>{ return: <i>value</i> }</code>, then <i>value</i> is immediately returned as the current value of the function. <i>value</i> must be a debuggee value.

<li>If the hook throws an exception, ... well, we're in trouble. That's an error in the debugger which should be reported somehow, but certainly not handled by the debuggee.

<dd>The debuggee has executed a <i>debugger</i> statement in <i>frame</i>. This hook function's return value determines how execution proceeds, as for the <i>interrupt</i> hook function.

If this hook function returns a function <i>f</i>, SpiderMonkey will call <i>f</i> when execution of <i>frame</i> completes, passing one argument indicating how it completed.

<li>If the argument is of the form <code>{ return: <i>value</i> }</code>, then the code completed normally, yielding <i>value</i>. <i>Value</i> is a debuggee value.

<li>If the argument is of the form <code>{ throw: <i>value</i> }</code>, then the code threw <i>value</i> as an exception. <i>Value</i> is a debuggee value.

<li>If the argument is <code>null</code>, then the code was terminated, as if by the "slow script" dialog box.

<dd>The code running in <i>frame</i> is about to throw <i>value</i> as an exception. The value this hook function returns determines how execution proceeds, as for <i>interrupt</i>.

<dd>Begin evaluating <i>code</i> in the scope of this frame. <i>Code</i> is a string. This pushes a <code>"debugger"</code> frame on the debuggee's stack, evaluates <i>code</i>, and returns a value of the sort passed to an <code>enterFrame</code> completion function describing how the code completed. All extant hook functions, breakpoints, watchpoints, and so on remain active during the call.

<dt>finish(<i>result</i>) <i>(future plan)</i>

<dd>Pop this frame (and any younger frames) from the stack as if this frame had completed. <i>Result</i> is a value of the sort that the <code>interrupt</code> hook might return, indicating how execution should be prepared to continue.

Note that this does <i>not</i> resume the debuggee's execution; it merely adjusts the debuggee's state to what it would be if this frame's execution had completed. You must return <code>true</code> from the hook function to resume execution in that state.

Note that this does <i>not</i> resume the debuggee's execution; it merely adjusts the debuggee's state to what it would be if this frame were about to make this call. You must return <code>true</code> from the hook function to resume execution in that state.

<dd>Return a string containing JavaScript source code equivalent to this script in its effect and result. If <i>pretty</i> is present and true, produce indented code with line breaks.

<dd>If the referent is a function, push a <code>"debugger"</code> frame on the debuggee's stack, call the referent with the given <i>this</i> value and <i>argument</i> values, pop the <code>"debugger"</code> frame, and return a value of the sort passed to an <code>enterFrame</code> completion function describing how the call completed. The <i>this</i> and <i>argument</i> values must be debuggee values. All extant hook functions, breakpoints, watchpoints, and so on remain active during the call. If the referent is not a function, throw a <code>TypeError</code>.

<dd>If the referent is a function, push a <code>"debugger"</code> frame on the debuggee's stack, call the referent with the given <i>this</i> and argument values in <i>arguments</i>, pop the <code>"debugger"</code> frame, and return a value of the sort passed to an <code>enterFrame</code> completion function describing how the call completed. <i>This</i> must be a debuggee value, and <i>arguments</i> must be an array (in the debugger) of debuggee values. All extant hook functions, breakpoints, watchpoints, and so on remain active during the call. If the referent is not a function, throw a <code>TypeError</code>.