Debugger.Frame

  • Revision slug: SpiderMonkey/JS_Debugger_API_Reference/Debugger.Frame
  • Revision title: Debugger.Frame
  • Revision id: 67573
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment describe generators; info to move to guide soon; 567 words added

Revision Content

{{ jsapi_minversion_header("1.8.6") }}

A Debugger.Frame instance represents a stack frame in a debuggee. With it, you can find the script being executed in the frame, walk the stack to get to older frames, find the lexical environment in which execution is taking place, and so forth.

Note: Much of the following exposition will move to the guide soon.

About debuggee frames

Each debuggee frame has exactly one Debugger.Frame instance; therefore, every hook object method called while the debuggee is running in a particular frame receives the same frame object. Similarly, walking the stack back to a previously-accessed debuggee frame gets you the same frame object as before. Debuggers can add additional properties to frame objects and expect to find them later. In addition, you can use the == operator to determine whether or not two expressions refer to the same frame.

When the debuggee pops a stack frame -- for example, because a function call has returned or an exception has been thrown -- the Debugger.Frame instance referring to that frame becomes inactive. You can detect this by checking its live property; if this property is false, the frame is inactive. Its other properties and methods all throw exceptions.

Note: Frames become inactive only at times the debugger can rely upon: when the debuggee runs or when it removes frames from the stack itself.

Although the debugger shares a JavaScript stack with the debuggee, the stack frames presented to the debugger by Debugger.Frame never include frames running the debugger's own code.

Note: Stack frames representing the control state of generator-iterator objects are represented using a special variety of Debugger.Frame.

Generator frames

SpiderMonkey supports generator-iterator objects. These produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses the yield() operator produces a generator-iterator object. So does evaluating a generator expression such as (i*i for each (i in [1, 2, 3])).

A generator-iterator object refers to a stack frame with no fixed continuation frame. While the generator's code is running, its continuation is whatever frame called its next() method (thereby requesting the next result from the generator). While the generator is suspended, it has no particular continuation frame, and when it resumes again, the continuation frame for that resumption may differ from the previous resumption.

Differences between generator frames and other frames

A Debugger.Frame instance representing a generator frame differs from an ordinary stack frame in the following ways:

  • The generator property is true.
  • The older property refers to the frame's continuation frame while the generator is running and is null while the generator is suspended.
  • The depth property reflects the frame's position on the stack when it's resumed and is null while the generator is suspended.
  • The live property remains true until the frame returns, throws an exception, or is terminated. That means generator frames can be live while not present on the stack.
  • A generator frame disappears from the stack each time the generator yields a value and is suspended. It reappears at the top of the stack when it's resumed to produce the generator's next value. The same Debugger.Frame instance refers to the generator frame until it returns, throws an exception, or is terminated.
Note: Whether or not the Debugger.Frame object on the stack when the generator is resumed is a new one or an existing one is not specified, and you should not rely on any particular behavior in this regard.

How generator frames and other frames are the same

All other Debugger.Frame methods and accessor properties work just like for other types of frames, even when the generator frame is suspended. You can examine a suspended generator frame's properties and use its script and offset properties to see which yield() operation it's suspended at, for example.

The lifespan of a generator frame

A Debugger.Frame instance referring to a generator-iterator frame holds a strong reference to the generator-iterator object. The frame and its object will live as long as the Debugger.Frame instance does. However, once the generator function returns, throws an exception, or is terminated (thereby ending the iteration), the Debugger.Frame instance becomes inactive and its live property becomes false, just like for any other kind of frame that is popped.

Once a generator frame is no longer live, it no longer holds a strong reference to the generator-iterator object.

Accessor properties

Instances of the Debugger.Frame object inherit these properties from the prototype.


Property Type Description
arguments Array of objects

The arguments passed to the current frame, or null if the frame isn't of type "call". When not null, this is an Array object in the debugger's compartment with a non-writable length property and properties whose names are array indices. Each property is a read-only accessor property whose getter returns the current value of the corresponding parameter.

Note: When the frame is popped, the argument values' properties' getters all throw errors.
callee Debugger.Object A Debugger.Object representing the JavaScript Function object whose application created the frame, as a debuggee value. null if this isn't a "call" type frame.
constructing Boolean true if the frame is for a function that's called as a constructor; otherwise false.
depth Number The depth of this frame, counting from oldest to youngest. The oldest frame's depth is 0.
environment Debugger.Environment The lexical environment in which evaluation of the script is taking place, or null on frames for calls to host functions and "debugger" type frames.
generator Boolean true if the frame is a generator frame; otherwise false.
live Boolean true if this Debugger.Frame instance refers to a frame that's still on the stack (or to a generator-iterator object that hasn't finished iterating yet), or false if the frame has completed execution or has been popped off the stack in some other way.
offset Number The offset to the bytecode instruction currently being executed in script, or undefined if the script property is null.
older Debugger.Frame

The next-oldest frame; this is the frame that will resume execution when this frame completes. If there is no older frame, this is null.

Note: On suspended generator frames, this value is null.
onPop Function

A function that SpiderMonkey calls just before the frame is popped. The function receives as a parameter a completion value indicating the manner in which execution completed, and should return a resumption value that specifies how execution should continue. If this is undefined, no pop routine is called. The default value is undefined.

Calls to frames' onPop handlers are cross-compartment, intra-thread calls; an onPop function must be in the debugger's compartment, and therefore calls to it tae place in the debugger's compartment. The call takes place in the thread to which the frame belongs.

When one of the debugger hooks forces a frame to complete early, by returning a return, throw, or null resumption value, SpiderMonkey calls this handler, if one has been set. The completion value passed to onPop in this case reflects the resumption value that caused the frame to complete execution.

Note: When a generator frame yields a value, SpiderMonkey calls its Debugger.Frame instance's onPop handler, if one has been set, passing a yield resumption value. However, in this case, the frame instance remains live.
onResume Function

A function, which receives one argument, that SpiderMonkey calls if the current frame in a generator whose execution has just resumed. This function should return a resumption value that specifies how execution should continue. If this is undefined, no resume routine is called. The default value is undefined.

The argument is the value passed to the generator's send() method, or undefined if no value was passed to it (or if the generator resumed by other means).

onStep Function

A function, which receives no arguments, that SpiderMonkey calls when execution in the frame makes a small amount of progress. This function should return a resumption value that specifies how execution should continue. If this is undefined, no step routine is called.

Note: The definition of "a small amount of progress" is up to the specific implementation, but is fine-grained enough for "step" and "next" operations to be useful.
script Debugger.Script

The script being executed in the frame, or null for frames representing calls to host functions or to frames of type "debugger".

Note: If the callee property is set, these two fields are equal.
this Object The value of this for the frame; this is a debuggee value.
type String

A string describing what type of frame the instance describes:

"call"
A frame running a function call.
"eval"
A frame running code passed to eval().
"global"
A frame running global code (that is, JavaScript that is neither a function call nor being handled by eval()).
"debugger"
A frame for a call to user code that's been invoked by the debugger; see the Debugger.Frame.eval() method.

Methods

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


Method Return value Description
{{ manch("eval") }} Completion value

Evaluates the code specified by the given string in the frame's environment, returning a completion value that describes how it completed execution.

{{ manch("evalWithBindings") }} Completion value Evaluates the code specified by the given string in the frame's environment, but extended with bindings from another object.
{{ manch("pop") }} {{ unimplemented_inline() }} n/a Pops the frame (as well as any younger frames) from the stack as if the frame had completed as specified by a given completion value.
{{ manch("replaceCal") }} {{ unimplemented_inline() }} n/a Pops any younger frames, then changes this frame into a frame to call a specified function with given this and arguments.

eval()

Evaluates the code specified by the given string in the frame's environment, returning a completion value that describes how it completed execution. All configured hook object methods, breakpoints, watchpoints, and the like remain in effect while the code is executed. This function follows the invocation function conventions.

The code is executed in strict mode if it contains a use strict directive, or if the code executing in this frame is strict mode code.

If the code is not strict mode code, then variable declarations in the code affect the environment of this frame.

eval(
  code
);
Parameters
code
A string containing the JavaScript code to execute.
Return value

A completion value describing how the execution of the code completed.

Exceptions thrown
TypeError
The frame's environment property is null.
Error
An attempt to extend the execution context's environment failed due to implementation restrictions.

evalWithBindings()

Evaluates the code specified by the given string in the frame's environment -- but extended with bindings from another, specified object -- returning a completion value that describes how it completed execution. All configured hook object methods, breakpoints, watchpoints, and the like remain in effect while the code is executed. This function follows the invocation function conventions.

The code is executed in strict mode if it contains a use strict directive, or if the code executing in this frame is strict mode code.

If the code is not strict mode code, then variable declarations in the code affect the environment of this frame.

Note: This lets debugger code introduce temporary bindings that are visible to debuggee code and refer to debugger-held debuggee values, without having to mutate any existing debuggee environment.
evalWithBindings(
  code,
  bindings
);
Parameters
code
A string containing the JavaScript code to execute.
bindings
For each enumerable property of this object, a variable is included in the execution environment of the code whose name and value correspond. Each value must be a debuggee value.
Return value

A completion value describing how the execution of the code completed.

Exceptions thrown
TypeError
The frame's environment property is null.
Error
An attempt to extend the execution context's environment failed due to implementation restrictions.

Revision Source

<p>{{ jsapi_minversion_header("1.8.6") }}</p>
<p>A <code>Debugger.Frame</code> instance represents a stack frame in a debuggee. With it, you can find the script being executed in the frame, walk the stack to get to older frames, find the lexical environment in which execution is taking place, and so forth.</p>
<div class="note"><strong>Note:</strong> Much of the following exposition will move to the guide soon.</div>
<h2>About debuggee frames</h2>
<p>Each debuggee frame has exactly one <code>Debugger.Frame</code> instance; therefore, every hook object method called while the debuggee is running in a particular frame receives the same frame object. Similarly, walking the stack back to a previously-accessed debuggee frame gets you the same frame object as before. Debuggers can add additional properties to frame objects and expect to find them later. In addition, you can use the <code>==</code> operator to determine whether or not two expressions refer to the same frame.</p>
<p>When the debuggee pops a stack frame -- for example, because a function call has returned or an exception has been thrown -- the Debugger.Frame instance referring to that frame becomes inactive. You can detect this by checking its live property; if this property is false, the frame is inactive. Its other properties and methods all throw exceptions.</p>
<div class="note"><strong>Note:</strong> Frames become inactive only at times the debugger can rely upon: when the debuggee runs or when it removes frames from the stack itself.</div>
<p>Although the debugger shares a JavaScript stack with the debuggee, the stack frames presented to the debugger by <code>Debugger.Frame</code> never include frames running the debugger's own code.</p>
<div class="note"><strong>Note:</strong> Stack frames representing the control state of generator-iterator objects are represented using a special variety of <code>Debugger.Frame</code>.</div>
<h2>Generator frames</h2>
<p>SpiderMonkey supports generator-iterator objects. These produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses the <a href="/en/JavaScript/Reference/Operators/yield" title="yield"><code>yield()</code></a> operator produces a generator-iterator object. So does evaluating a generator expression such as <code>(i*i for each (i in [1, 2, 3]))</code>.</p>
<p>A generator-iterator object refers to a stack frame with no fixed continuation frame. While the generator's code is running, its continuation is whatever frame called its <code>next()</code> method (thereby requesting the next result from the generator). While the generator is suspended, it has no particular continuation frame, and when it resumes again, the continuation frame for that resumption may differ from the previous resumption.</p>
<h3>Differences between generator frames and other frames</h3>
<p>A <code>Debugger.Frame</code> instance representing a generator frame differs from an ordinary stack frame in the following ways:</p>
<ul> <li>The <code>generator</code> property is true.</li> <li>The <code>older</code> property refers to the frame's continuation frame while the generator is running and is <code>null</code> while the generator is suspended.</li> <li>The <code>depth</code> property reflects the frame's position on the stack when it's resumed and is <code>null</code> while the generator is suspended.</li> <li>The <code>live</code> property remains true until the frame returns, throws an exception, or is terminated. That means generator frames can be live while not present on the stack.</li> <li>A generator frame disappears from the stack each time the generator yields a value and is suspended. It reappears at the top of the stack when it's resumed to produce the generator's next value. The same <code>Debugger.Frame</code> instance refers to the generator frame until it returns, throws an exception, or is terminated.</li>
</ul>
<div class="note"><strong>Note:</strong> Whether or not the <code>Debugger.Frame</code> object on the stack when the generator is resumed is a new one or an existing one is not specified, and you should not rely on any particular behavior in this regard.</div>
<h3>How generator frames and other frames are the same</h3>
<p>All other <code>Debugger.Frame</code> methods and accessor properties work just like for other types of frames, even when the generator frame is suspended. You can examine a suspended generator frame's properties and use its <code>script</code> and <code>offset</code> properties to see which <a href="/en/JavaScript/Reference/Operators/yield" title="yield"><code>yield()</code></a> operation it's suspended at, for example.</p>
<h3>The lifespan of a generator frame</h3>
<p>A <code>Debugger.Frame</code> instance referring to a generator-iterator frame holds a strong reference to the generator-iterator object. The frame and its object will live as long as the <code>Debugger.Frame</code> instance does. However, once the generator function returns, throws an exception, or is terminated (thereby ending the iteration), the <code>Debugger.Frame</code> instance becomes inactive and its <code>live</code> property becomes false, just like for any other kind of frame that is popped.</p>
<p>Once a generator frame is no longer live, it no longer holds a strong reference to the generator-iterator object.</p>
<h2>Accessor properties</h2>
<p>Instances of the <code>Debugger.Frame</code> object inherit these properties from the prototype.</p>
<br>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Property</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>arguments</code></td> <td><code>Array</code> of objects</td> <td> <p>The arguments passed to the current frame, or <code>null</code> if the frame isn't of type "call". When not <code>null</code>, this is an <a href="/en/JavaScript/Reference/Global_Objects/Array" title="Array"><code>Array</code></a> object in the debugger's compartment with a non-writable <code>length</code> property and properties whose names are array indices. Each property is a read-only accessor property whose getter returns the current value of the corresponding parameter.</p> <div class="note"><strong>Note:</strong> When the frame is popped, the argument values' properties' getters all throw errors.</div> </td> </tr> <tr> <td><code>callee</code></td> <td><code><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Object" title="en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Object">Debugger.Object</a></code></td> <td>A <code><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Object" title="en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Object">Debugger.Object</a></code> representing the JavaScript <code><a href="/en/JavaScript/Reference/Global_Objects/Function" title="Function">Function</a></code> object whose application created the frame, as a debuggee value. <code>null</code> if this isn't a "call" type frame.</td> </tr> <tr> <td><code>constructing</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Boolean" title="Boolean">Boolean</a></code></td> <td><code>true</code> if the frame is for a function that's called as a constructor; otherwise <code>false</code>.</td> </tr> <tr> <td><code>depth</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Number" title="Number">Number</a></code></td> <td>The depth of this frame, counting from oldest to youngest. The oldest frame's <code>depth</code> is 0.</td> </tr> <tr> <td><code>environment</code></td> <td><code><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Environment" title="en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Environment">Debugger.Environment</a></code></td> <td>The lexical environment in which evaluation of the script is taking place, or <code>null</code> on frames for calls to host functions and "debugger" type frames.</td> </tr> <tr> <td><code>generator</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Boolean" title="Boolean">Boolean</a></code></td> <td><code>true</code> if the frame is a generator frame; otherwise <code>false</code>.</td> </tr> <tr> <td><code>live</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Boolean" title="Boolean">Boolean</a></code></td> <td><code>true</code> if this <code>Debugger.Frame</code> instance refers to a frame that's still on the stack (or to a generator-iterator object that hasn't finished iterating yet), or <code>false</code> if the frame has completed execution or has been popped off the stack in some other way.</td> </tr> <tr> <td><code>offset</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Number" title="Number">Number</a></code></td> <td>The offset to the bytecode instruction currently being executed in <code>script</code>, or undefined if the <code>script</code> property is <code>null</code>.</td> </tr> <tr> <td><code>older</code></td> <td><code>Debugger.Frame</code></td> <td> <p>The next-oldest frame; this is the frame that will resume execution when this frame completes. If there is no older frame, this is <code>null</code>.</p> <div class="note"><strong>Note:</strong> On suspended generator frames, this value is <code>null</code>.</div> </td> </tr> <tr> <td><code>onPop</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Function" title="Function">Function</a></code></td> <td> <p>A function that SpiderMonkey calls just before the frame is popped. The function receives as a parameter a <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values" title="en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values">completion value</a> indicating the manner in which execution completed, and should return a <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values" title="en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values">resumption value</a> that specifies how execution should continue. If this is <code>undefined</code>, no pop routine is called. The default value is <code>undefined</code>.</p> <p>Calls to frames' <code>onPop</code> handlers are cross-compartment, intra-thread calls; an <code>onPop</code> function must be in the debugger's compartment, and therefore calls to it tae place in the debugger's compartment. The call takes place in the thread to which the frame belongs.</p> <p>When one of the <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#Debugging_hooks" title="en/SpiderMonkey/JS_Debugger_API_Reference/Debugger#Debugging_hooks">debugger hooks</a> forces a frame to complete early, by returning a <code>return</code>, <code>throw</code>, or <code>null</code> resumption value, SpiderMonkey calls this handler, if one has been set. The completion value passed to <code>onPop</code> in this case reflects the resumption value that caused the frame to complete execution.</p> <div class="note"><strong>Note:</strong> When a generator frame yields a value, SpiderMonkey calls its <code>Debugger.Frame</code> instance's <code>onPop</code> handler, if one has been set, passing a <code>yield</code> resumption value. <strong>However</strong>, in this case, the frame instance remains live.</div> </td> </tr> <tr> <td><code>onResume</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Function" title="Function">Function</a></code></td> <td> <p>A function, which receives one argument, that SpiderMonkey calls if the current frame in a generator whose execution has just resumed. This function should return a <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values" title="en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values">resumption value</a> that specifies how execution should continue. If this is <code>undefined</code>, no resume routine is called. The default value is <code>undefined</code>.</p> <p>The argument is the value passed to the generator's <a href="/en/JavaScript/Reference/Global_Objects/Generator/send" title="en/JavaScript/Reference/Global_Objects/Generator/send"><code>send()</code></a> method, or <code>undefined</code> if no value was passed to it (or if the generator resumed by other means).</p> </td> </tr> <tr> <td><code>onStep</code></td> <td><code><a href="/en/JavaScript/Reference/Global_Objects/Function" title="Function">Function</a></code></td> <td> <p>A function, which receives no arguments, that SpiderMonkey calls when execution in the frame makes a small amount of progress. This function should return a <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values" title="en/SpiderMonkey/JS_Debugger_API_Reference/Resumption_values">resumption value</a> that specifies how execution should continue. If this is <code>undefined</code>, no step routine is called.</p> <div class="note"><strong>Note:</strong> The definition of "a small amount of progress" is up to the specific implementation, but is fine-grained enough for "step" and "next" operations to be useful.</div> </td> </tr> <tr> <td><code>script</code></td> <td><code><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Script" title="en/SpiderMonkey/JS_Debugger_API_Reference/Debugger.Script">Debugger.Script</a></code></td> <td> <p>The script being executed in the frame, or null for frames representing calls to host functions or to frames of type "debugger".</p> <div class="note"><strong>Note:</strong> If the <code>callee</code> property is set, these two fields are equal.</div> </td> </tr> <tr> <td><code>this</code></td> <td><a href="/en/JavaScript/Reference/Global_Objects/Object" title="Object"><code>Object</code></a></td> <td>The value of <code>this</code> for the frame; this is a debuggee value.</td> </tr> <tr> <td><code>type</code></td> <td><a href="/en/JavaScript/Reference/Global_Objects/String" title="String"><code>String</code></a></td> <td> <p>A string describing what type of frame the instance describes:</p> <dl> <dt>"call"</dt> <dd>A frame running a function call.</dd> <dt>"eval"</dt> <dd>A frame running code passed to <a href="/en/JavaScript/Reference/Global_Objects/Object/eval" title="eval"><code>eval()</code></a>.</dd> <dt>"global"</dt> <dd>A frame running global code (that is, JavaScript that is neither a function call nor being handled by <code>eval()</code>).</dd> <dt>"debugger"</dt> <dd>A frame for a call to user code that's been invoked by the debugger; see the <code>Debugger.Frame.eval()</code> method.</dd> </dl> </td> </tr> </tbody>
</table>
<h2>Methods</h2>
<p>These methods must be called with a <code>this</code> value referring to the <code>Debugger.Frame</code> instance.</p>
<br>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Method</td> <td class="header">Return value</td> <td class="header">Description</td> </tr> <tr> <td>{{ manch("eval") }}</td> <td><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values" title="Completion values">Completion value</a></td> <td> <p>Evaluates the code specified by the given string in the frame's environment, returning a completion value that describes how it completed execution.</p> </td> </tr> <tr> <td>{{ manch("evalWithBindings") }}</td> <td><a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values" title="Completion values">Completion value</a></td> <td>Evaluates the code specified by the given string in the frame's environment, but extended with bindings from another object.</td> </tr> <tr> <td>{{ manch("pop") }} {{ unimplemented_inline() }}</td> <td>n/a</td> <td>Pops the frame (as well as any younger frames) from the stack as if the frame had completed as specified by a given completion value.</td> </tr> <tr> <td>{{ manch("replaceCal") }} {{ unimplemented_inline() }}</td> <td>n/a</td> <td>Pops any younger frames, then changes this frame into a frame to call a specified function with given <code>this</code> and arguments.</td> </tr> </tbody>
</table>
<h3>eval()</h3>
<p>Evaluates the code specified by the given string in the frame's environment, returning a completion value that describes how it completed execution. All configured hook object methods, breakpoints, watchpoints, and the like remain in effect while the code is executed. This function follows the <a href="/en/SpiderMonkey/JS_Debugger_API_Guide#Invocation_functions" title="en/SpiderMonkey/JS_Debugger_API_Guide#Invocation_functions">invocation function</a> conventions.</p>
<p>The code is executed in strict mode if it contains a use strict directive, or if the code executing in this frame is strict mode code.</p>
<p>If the code is <strong>not</strong> strict mode code, then variable declarations in the code affect the environment of this frame.</p>
<pre>eval(
  code
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>code</code></dt> <dd>A string containing the JavaScript code to execute.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values" title="Completion values">completion value</a> describing how the execution of the code completed.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>The frame's environment property is null.</dd> <dt><code>Error</code></dt> <dd>An attempt to extend the execution context's environment failed due to implementation restrictions.</dd>
</dl>
<h3>evalWithBindings()</h3>
<p>Evaluates the code specified by the given string in the frame's environment -- but extended with bindings from another, specified object -- returning a completion value that describes how it completed execution. All configured hook object methods, breakpoints, watchpoints, and the like remain in effect while the code is executed. This function follows the <a href="/en/SpiderMonkey/JS_Debugger_API_Guide#Invocation_functions" title="en/SpiderMonkey/JS_Debugger_API_Guide#Invocation_functions">invocation function</a> conventions.</p>
<p>The code is executed in strict mode if it contains a use strict directive, or if the code executing in this frame is strict mode code.</p>
<p>If the code is <strong>not</strong> strict mode code, then variable declarations in the code affect the environment of this frame.</p>
<div class="note"><strong>Note:</strong> This lets debugger code introduce temporary bindings that are visible to debuggee code and refer to debugger-held debuggee values, without having to mutate any existing debuggee environment.</div>
<pre>evalWithBindings(
  code,
  bindings
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>code</code></dt> <dd>A string containing the JavaScript code to execute.</dd> <dt><code>bindings</code></dt> <dd>For each enumerable property of this object, a variable is included in the execution environment of the <code>code</code> whose name and value correspond. Each value must be a debuggee value.</dd>
</dl>
<h6>Return value</h6>
<p>A <a href="/en/SpiderMonkey/JS_Debugger_API_Reference/Completion_values" title="Completion values">completion value</a> describing how the execution of the code completed.</p>
<h6>Exceptions thrown</h6>
<dl> <dt><code>TypeError</code></dt> <dd>The frame's environment property is null.</dd> <dt><code>Error</code></dt> <dd>An attempt to extend the execution context's environment failed due to implementation restrictions.</dd>
</dl>
Revert to this revision