Confirmed users
497
edits
Debugger: Difference between revisions
[b28913f] Merge branch 'master' of github.com:jimblandy/DebuggerDocs
([master d36e9a8] Document Debugger.prototype.makeGlobalObjectReference.) |
([b28913f] Merge branch 'master' of github.com:jimblandy/DebuggerDocs) |
||
| Line 53: | Line 53: | ||
<ul> | <ul> | ||
<li>a <i>debuggee frame</i> is a frame running debuggee code; | <li>a <i>debuggee frame</i> is a frame running debuggee code; | ||
<li>a <i>debuggee function</i> is a function that closes over a debuggee global object (and thus the function's code is debuggee code); and | <li>a <i>debuggee function</i> is a function that closes over a debuggee global object (and thus the function's code is debuggee code); | ||
<li>a <i>debuggee environment</i> is an environment whose outermost enclosing environment is a debuggee global object; and | |||
<li>a <i>debuggee script</i> is a script containing debuggee code. | <li>a <i>debuggee script</i> is a script containing debuggee code. | ||
</ul> | </ul> | ||
| Line 64: | Line 65: | ||
<dd>The code completed normally, returning <i>value</i>. <i>Value</i> is a debuggee value. | <dd>The code completed normally, returning <i>value</i>. <i>Value</i> is a debuggee value. | ||
<dt>{ yield: <i>value</i> } | <dt>{ yield: <i>value</i> } | ||
<dd>The running code is a generator frame which has yielded <i>value</i>. <i>Value</i> is a debuggee value. | <dd><i>(Not yet implemented.)</i> The running code is a generator frame which has yielded <i>value</i>. <i>Value</i> is a debuggee value. | ||
<dt>{ throw: <i>value</i> } | <dt>{ throw: <i>value</i> } | ||
<dd>The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee value. | <dd>The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee value. | ||
| Line 82: | Line 83: | ||
<dd>Return <i>value</i> immediately as the current value of the function. <i>Value</i> must be a debuggee value. (Most handler functions support this, except those whose descriptions say otherwise.) If the function was called as a constructor (that is, via a <code>new</code> expression), then <i>value</i> serves as the value returned by the function's body, not that produced by the <code>new</code> expression: if the value is not an object, the <code>new</code> expression returns the frame's <code>this</code> value. | <dd>Return <i>value</i> immediately as the current value of the function. <i>Value</i> must be a debuggee value. (Most handler functions support this, except those whose descriptions say otherwise.) If the function was called as a constructor (that is, via a <code>new</code> expression), then <i>value</i> serves as the value returned by the function's body, not that produced by the <code>new</code> expression: if the value is not an object, the <code>new</code> expression returns the frame's <code>this</code> value. | ||
<dt>{ yield: <i>value</i> } | <dt>{ yield: <i>value</i> } | ||
<dd>Yield <i>value</i> immediately as the next value of the current frame, which must be a generator frame. <i>Value</i> is a debuggee value. The current frame must be a generator frame that has not yet completed in some other way. You may use <code>yield</code> resumption values to substitute a new value or one already yielded by a generator, or to make a generator yield additional values. | <dd><i>(Not yet implemented.)</i> Yield <i>value</i> immediately as the next value of the current frame, which must be a generator frame. <i>Value</i> is a debuggee value. The current frame must be a generator frame that has not yet completed in some other way. You may use <code>yield</code> resumption values to substitute a new value or one already yielded by a generator, or to make a generator yield additional values. | ||
<dt>{ throw: <i>value</i> } | <dt>{ throw: <i>value</i> } | ||
<dd>Throw <i>value</i> as an execption from the current bytecode instruction. <i>Value</i> must be a debuggee value. | <dd>Throw <i>value</i> as an execption from the current bytecode instruction. <i>Value</i> must be a debuggee value. | ||
| Line 428: | Line 429: | ||
When SpiderMonkey calls an <code>onPop</code> handler for a frame that is throwing an exception or being terminated, and the handler returns <code>undefined</code>, then SpiderMonkey proceeds with the exception or termination. That is, an <code>undefined</code> resumption value leaves the frame's throwing and termination process undisturbed. | When SpiderMonkey calls an <code>onPop</code> handler for a frame that is throwing an exception or being terminated, and the handler returns <code>undefined</code>, then SpiderMonkey proceeds with the exception or termination. That is, an <code>undefined</code> resumption value leaves the frame's throwing and termination process undisturbed. | ||
When a generator frame yields a value, SpiderMonkey calls its <code>Debugger.Frame</code> instance's <code>onPop</code> handler method, if present, passing a <code>yield</code> resumption value; however, the <code>Debugger.Frame</code> instance remains live. | <i>(Not yet implemented.)</i> When a generator frame yields a value, SpiderMonkey calls its <code>Debugger.Frame</code> instance's <code>onPop</code> handler method, if present, passing a <code>yield</code> resumption value; however, the <code>Debugger.Frame</code> instance remains live. | ||
If multiple <code>Debugger</code> instances each have <code>Debugger.Frame</code> instances for a given stack frame with <code>onPop</code> handlers set, their handlers are run in an unspecified order. The resumption value each handler returns establishes the completion value reported to the next handler. | If multiple <code>Debugger</code> instances each have <code>Debugger.Frame</code> instances for a given stack frame with <code>onPop</code> handlers set, their handlers are run in an unspecified order. The resumption value each handler returns establishes the completion value reported to the next handler. | ||
| Line 486: | Line 487: | ||
=== Generator Frames === | === Generator Frames === | ||
<i>Not all behavior described in this section has been implemented yet.</i> | |||
SpiderMonkey supports generator-iterator objects, which produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses <code>yield</code> produces a generator-iterator object, as does evaluating a generator expression like <code>(i*i for each (i in [1,2,3]))</code>. | SpiderMonkey supports generator-iterator objects, which produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses <code>yield</code> produces a generator-iterator object, as does evaluating a generator expression like <code>(i*i for each (i in [1,2,3]))</code>. | ||
| Line 685: | Line 688: | ||
<dt>parameterNames | <dt>parameterNames | ||
<dd>If the referent is a function, the names of the its parameters, as an array of strings. If the referent is not a function at all, this is <code>undefined</code>. | <dd>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 <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 host function for which parameter names are not available, return an array with one element per parameter, each of which is <code>undefined</code>. | ||
| Line 885: | Line 888: | ||
(If more than one <code>Debugger</code> instance is debugging the same code, each <code>Debugger</code> gets a separate <code>Debugger.Environment</code> instance for a given environment. This allows the code using each <code>Debugger</code> instance to place whatever properties it likes on its own <code>Debugger.Object</code> instances, without worrying about interfering with other debuggers.) | (If more than one <code>Debugger</code> instance is debugging the same code, each <code>Debugger</code> gets a separate <code>Debugger.Environment</code> instance for a given environment. This allows the code using each <code>Debugger</code> instance to place whatever properties it likes on its own <code>Debugger.Object</code> instances, without worrying about interfering with other debuggers.) | ||
If a <code>Debugger.Environment</code> instance's referent is not a debuggee environment, then attempting to access its properties (other than <code>inspectable</code>) or call any its methods throws an instance of <code>Error</code>. | |||
<code>Debugger.Environment</code> instances protect their referents from the garbage collector; as long as the <code>Debugger.Environment</code> instance is live, the referent remains live. Garbage collection has no visible effect on <code>Debugger.Environment</code> instances. | <code>Debugger.Environment</code> instances protect their referents from the garbage collector; as long as the <code>Debugger.Environment</code> instance is live, the referent remains live. Garbage collection has no visible effect on <code>Debugger.Environment</code> instances. | ||
| Line 893: | Line 898: | ||
<dl> | <dl> | ||
<dt>inspectable | |||
<dd>True if this environment is a debuggee environment, and can therefore be inspected. False otherwise. All other properties and methods of <code>Debugger.Environment</code> instances throw if applied to a non-inspectable environment. | |||
<dt>type | <dt>type | ||
<dd>The type of this environment object, one of the following values: | <dd>The type of this environment object, one of the following values: | ||