Debugger

This draft is being discussed in bug 636907. The interface it describes is not stable.

The Debugger constructor makes objects with methods for debugging code running in other compartments. Given a Debugger instance d, you can:

• add debuggee compartments to d's purview by calling d.addDebuggee;
• request notification of basic debugging events by assigning a handler object to d.hooks;
• set breakpoints by obtaining a Debugger.Script instance and calling its setBreakpoint method;
• set watchpoints by calling d.setPropertyWatchpoint;
• examine the debuggee's stack frames and lexical enviroments;
• inspect and manipulate its objects;

and so on.

Your event handling methods run in the same thread as the debuggee, on the same JavaScript stack: when the event occurs, the debuggee pauses while your handler methods run, and resumes (unless you say otherwise) when your methods return. Your event handling methods run in the debugger's compartment. SpiderMonkey mediates their access to the debuggee's objects, and prevents the debuggee from accessing the debugger's objects at all.

The Debugger object provides various sorts of objects representing the debuggee's state, which the debugger code can examine and manipulate:

• Debugger.Object instances represent objects in the debuggee.
• Debugger.Frame instances represent debuggee stack frames.
• Debugger.Script instances represent the debuggee's code, whether it is a function body, code passed to eval, or a top-level script.
• Debugger.Environment instances represent the variable scopes in effect at different points in the debuggee's code.

A Debugger instance can only debug code running in other compartments, and you may not create cycles of debugger/debuggee compartments.

The Debugger interface does not support cross-thread or multi-threaded debugging. As a general rule, only one thread may use a compartment at a time. When one compartment is debugging another, arbitrary events in the debuggee compartment may cause code to run in the debugger compartment; conversely, a call to any method in this interface could cause the debugger to try interact with the debuggee compartment. Thus, as a general rule, you should never permit different threads to run in the debugger and debuggee compartments simultaneously.

General Conventions

Properties

Properties of objects the Debugger interface creates, and those of the interface objects themselves, follow some general conventions:

• Instances and prototypes are extensible; you can add your own properties and methods to them.
• Properties are configurable. This applies to both "own" and prototype properties, and to both methods and data properties. (Leaving these properties open to redefinition will hopefully make it easier for JavaScript debugger code to cope with bugs, bug fixes, and changes in the interface over time.)
• Method properties are writable.
• We prefer inherited accessor properties to own data properties. Both are read using the same syntax, but inherited accessors seem like a more accurate reflection of what's going on. Unless otherwise noted, these properties have getters but no setters, as they cannot meaningfully be assigned to.

Debuggee Values

The Debugger interface follows some 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 Debugger.Object instances, which provide reflection-oriented methods for inspecting their referents; see Debugger.Object, below.

Of the debugger's objects, only Debugger.Object instances may be passed to the debuggee: when this occurs, the debuggee receives the Debugger.Object's referent, not the Debugger.Object instance itself.

In the descriptions below, the term "debuggee value" means either a primitive value or a Debugger.Object instance; it is a value that might be received from the debuggee, or that could be passed to the debuggee.

Completion Values

When a debuggee stack frame completes its execution, or when some sort of debuggee call initiated by the debugger finishes, the Debugger interface provides a value describing how the code completed; these are called completion values. A completion value has one of the following forms:

{ return: value }

The code completed normally, returning value. Value is a debuggee value.

{ yield: value }

The running code is a generator frame which has yielded value. Value is a debuggee value.

{ throw: value }

The code threw value as an exception. Value is a debuggee value.

null

The code was terminated, as if by the "slow script" dialog box.

If control reaches the end of a generator frame, the completion value is {throw: stop} where stop is a Debugger.Object object representing the StopIteration object being thrown.

Resumption Values

As the debuggee runs, the Debugger interface calls various debugger-provided handler functions to report the debuggee's behavior. Some of these calls can return a value indicating how the debuggee's execution should continue; these are called resumption values. A resumption value has one of the following forms:

undefined

The debuggee should continue execution normally.

{ return: value }

Return value immediately as the current value of the function. Value must be a debuggee value. (Most handler functions support this, except those whose descriptions say otherwise.)

{ yield: value }

Yield value immediately as the next value of the current frame, which must be a generator frame. Value is a debuggee value. The current frame must be a generator frame that has not yet completed in some other way. You may use yield resumption values to substitute a new value or one already yielded by a generator, or to make a generator yield additional values.

{ throw: value }

Throw value as an execption from the current bytecode instruction. Value must be a debuggee value.

null

Terminate the debuggee, as if it had been cancelled by the "slow script" dialog box.

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 Debugger instance's uncaughtExceptionHook property, as described below.

The Debugger Object

When called as a constructor, the Debugger object creates a new Debugger instance.

new Debugger([global, ...])

Create a debugger object, and apply its addDebuggee method to each of the given global objects to add their compartments as initial debuggees.

Accessor Properties of the Debugger Prototype Object

A Debugger instance inherits the following accessor properties from its prototype:

enabled

A boolean value indicating whether this Debugger instance's hooks, breakpoints, and watchpoints are currently enabled. It is an accessor property with a getter and setter: assigning to it enables or disables this Debugger instance; reading it produces true if the instance is enabled, or false otherwise. This property is initially true in a freshly created Debugger instance. This property gives debugger code a single point of control for disentangling itself from the debuggee, regardless of what sort of events or hooks or "points" we add to the interface.

uncaughtExceptionHook

Either null or a function that SpiderMonkey calls when a call to a debug event hook, breakpoint handler, watchpoint handler, or similar function throws some exception, debugger-exception. Exceptions thrown in the debugger are not propagated to user code; instead, SpiderMonkey calls this function, passing debugger-exception as its sole argument and the Debugger instance as the this value. This function should return a resumption value, which determines how the debuggee should continue. If the uncaught exception hook itself throws an exception, uncaught-hook-exception, SpiderMonkey throws an exception confess-to-debuggee-exception to the debuggee whose message blames the debugger, and includes textual descriptions of uncaught-hook-exception and debugger-exception. If this property's value is null, SpiderMonkey throws an exception to the debuggee whose message blames the debugger, and includes a textual description of debugger-exception. Assigning anything other than a callable value or null to this property throws a TypeError exception. (The hope here is that some sort of backstop, even if imperfect, will make life easier for debugger developers, especially since an uncaughtExceptionHook has access to browser-level features like alert, which this API's implementation does not.)

Debugging hooks

A Debugger instance has methods that are automatically called by the JS engine under the circumstances described below.

onNewScript(script, [function])

New code, represented by the Debugger.Script instance script, has been loaded into a debuggee compartment. If the new code is part of a function, function is a Debugger.Object reference to the function object. (Not all code is part of a function; for example, the code appearing in a <script> tag that is outside of any functions defined in that tag would be passed to newScript without an accompanying function argument.) Note that script may be a temporary script, created for a call to eval and destroyed when its execution is complete. This method's return value is ignored.

onDebuggerStatement(frame)

The debuggee has executed a debugger statement in frame. This method should return a resumption value specifying how the debuggee's execution should proceed.

onEnterFrame(frame)

The stack frame frame is about to begin executing code. (Naturally, frame is currently the youngest debuggee frame.) This method should return a resumption value specifying how the debuggee's execution should proceed.

onExceptionUnwind(frame, value)

The exception value has been thrown. Stack unwinding is underway. Some frames may already have been removed; frame is the most recent remaining stack frame. This method should return a resumption value specifying how the debuggee's execution should proceed. If it returns undefined, stack unwinding continues as normal: if the current offset in frame is in a try block, control jumps to the corresponding catch/finally code; otherwise frame is discarded and stack unwinding continues. If the next older frame is also a debuggee script frame, the onExceptionUnwind hook will be called again for that frame.

sourceHandler(ASuffusionOfYellow)

This method is never called. If it is ever called, a contradiction has been proven, and the debugger is free to assume that everything is true.

onError(frame, report)

SpiderMonkey is about to report an error in frame. Report is an object describing the error, with the following properties:

message

The fully formatted error message.

file

If present, the source file name, URL, etc. (If this property is present, the line property will be too, and vice versa.)

line

If present, the source line number at which the error occurred.

lineText

If present, this is the source code of the offending line.

offset

The index of the character within lineText at which the error occurred.

warning

Present and true if this is a warning; absent otherwise.

strict

Present and true if this error or warning is due to the strict option (not to be confused with ES strict mode)

exception

Present and true if an exception will be thrown; absent otherwise.

arguments

An array of strings, representing the arguments substituted into the error message.

This method's return value is ignored.

On a new Debugger instance, each of these properties is initially undefined. Any value assigned to a debugging hook must be either a callable object or undefined; otherwise a TypeError is thrown.

When one of the events described above occurs in a debuggee, the engine pauses the debuggee and calls the corresponding debugging hook on each Debugger object that is observing the debuggee. Afterwards, it continues running the debuggee where it left off, unless one of the hooks threw an exception or returned a non-default resumption value, as described above.

Hook object methods run in the same thread in which the event occurred. They run in the compartment to which they belong, not in a debuggee compartment.

Function Properties of the Debugger Prototype Object

The functions described below may only be called with a this value referring to a Debugger instance; they may not be used as methods of other kinds of objects.

addDebuggee(global)

Add the compartment to which the object global belongs to the set of compartments this Debugger instance is debugging. Return this Debugger instance. While global is typically a global object in the compartment, it can be any object in the desired compartment. If global is a Debugger.Object instance, operate on the compartment to which its referent belongs. The global object must be in a different compartment than this Debugger instance itself. If adding global's compartment would create a cycle of debugger and debuggee compartments, this method throws an error.

removeDebuggee(global)

Remove the compartment to which the object global belongs from the set of compartments this Debugger instance is debugging. Return this Debugger instance. While global is typically a global object in the compartment, it can be any object in the desired compartment. If global is a Debugger.Object instance, operate on the compartment to which its referent belongs.

hasDebuggee(global)

Return true if the compartment to which global belongs is a debuggee of this Debugger instance. If global is a Debugger.Object instance, operate on the compartment to which its referent belongs.

getDebuggees()

Return an array of distinct Debugger.Object instances whose referents are all the compartments this Debugger instance is debugging.

getYoungestFrame()

Return a Debugger.Frame instance referring to the youngest debuggee frame currently on the calling thread's stack, or null if there are no debuggee frames on the stack.

getAllScripts([global])

Return an array of Debugger.Script objects, one for each debuggee script. With no argument, return all scripts for all debuggees. With the optional argument global, return all debuggee scripts that could run in that debuggee. If global is present but is not (a cross-compartment wrapper or Debugger.Object for) an object in a debuggee global's scope, throw a TypeError. This returns all existing scripts (in the given global, if any) that would qualify for the onNewScript hook if they were created right now. However, unlike onNewScript, getAllScripts includes not only top-level scripts but also nested function scripts.

clearBreakpoint(handler)

Remove all breakpoints set in this Debugger instance that use handler as their handler. Note that, if breakpoints using other handler objects are set at the same location(s) as handler, they remain in place.

clearAllBreakpoints()

Remove all breakpoints set using this Debugger instance.

setPropertyWatchpoint(object, name, handler) (future plan)

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

add(frame, descriptor)

A property named name has been added to object's referent. Descriptor is a property descriptor of the sort accepted by Object.defineProperty, giving the newly added property's attributes.

delete(frame)

A property named name has been deleted from object's referent.

change(frame, oldDescriptor, newDescriptor)

The existing property named name on object's referent has had its attributes changed from those given by oldDescriptor to those given by newDescriptor.

set(frame, value)

The property named name is about to have value assigned to it. The assignment has not yet taken place, so the debugger can use getOwnPropertyDescriptor to find the property's pre-assignment value (assuming it is not an accessor property). This call takes place whether the property is a data or accessor property, even if the property is not writable or lacks a setter. This call takes place even if the property is a value property and value is identical to its current value. If this call includes a value property, whose value is a debuggee value newValue, in the resumption value it returns, the assignment stores newValue instead of value.

get(frame)

The property named name is about to be read. This call takes place whether the property is a data or accessor property, even if the property lacks a getter.

In all cases, the method's frame argument is the current stack frame, whose code is about to perform the operation on the object being reported. Methods should return resumption values; however, watchpoint handler methods may not return return resumption values.

If a given method is absent from handler, then events of the given sort are ignored. The watchpoint retains a reference to the handler object itself, and consults its properties each time an event occurs, so adding methods to or removing methods from handler after setting the watchpoint enables or disables reporting of the corresponding events.

Values passed to handler's methods are debuggee values. Descriptors passed to handler's methods are ordinary objects in the debugger's compartment, except for value, get, and set properties in descriptors, which are debuggee values.

Watchpoint handler calls are cross-compartment, intra-thread calls: handler must be a function in the debugger's compartment (and thus calls to it take place in the debugger's compartment), and the call takes place in the same thread that changed the property.

The new watchpoint belongs to this Debugger instance; disabling the Debugger instance disables this watchpoint.

clearPropertyWatchpoint(object, name) (future plan)

Remove any watchpoint set on the own property named name of the referent of the Debugger.Object instance object.

clearAllWatchpoints() (future plan)

Clear all watchpoints owned by this Debugger instance.

Debugger.Frame

A Debugger.Frame instance represents a debuggee stack frame. Given a Debugger.Frame instance, you can find the script the frame is executing, walk the stack to older frames, find the lexical environment in which the execution is taking place, and so on.

SpiderMonkey creates only one Debugger.Frame instance for a given debuggee frame. Every hook object method called while the debuggee is running in a given frame receives the same frame object. Similarly, walking the stack back to a previously accessed debuggee frame yields the same frame object as before. Debugger code can add its own properties to a frame object and expect to find them later, use == to decide whether two expressions refer to the same frame, and so on.

When the debuggee pops a stack frame (say, because a function call has returned or an exception has been thrown from it), the Debugger.Frame instance referring to that frame becomes inactive: its live property becomes false, and accessing its other properties or calling its methods throws an exception. Note that frames only become inactive at times that are predictable for the debugger: when the debuggee runs, or when the debugger removes frames from the stack itself.

Although the debugger shares a JavaScript stack with the debuggee, the stack frames presented to the debugger via this interface never include the frames running the debugger's own JavaScript code. (Note that "debugger" frames represent continuations that pass control from debuggee code that has completed execution to the debugger, not the debugger's frames themselves.)

Stack frames that represent the control state of generator-iterator objects behave in a special way, described in Generator Frames below.

Accessor Properties of the Debugger.Frame Prototype Object

A Debugger.Frame instance inherits the following accessor properties from its prototype:

type

A string describing what sort of frame this is:

• "call": a frame running a function call. (We may not be able to obtain frames for calls to host functions.)
• "eval": a frame running code passed to eval.
• "global": a frame running global code (JavaScript that is neither of the above).
• "debugger": a frame for a call to user code invoked by the debugger (see the eval method below).

this

The value of this for this frame (a debuggee value).

older

The next-older frame, in which control will resume when this frame completes. If there is no older frame, this is null. (On a suspended generator frame, the value of this property is null; see Generator Frames.)

depth

The depth of this frame, counting from oldest to youngest; the oldest frame has a depth of zero.

live

True if the frame this Debugger.Frame instance refers to is still on the stack (or, in the case of generator-iterator objects, has not yet finished its iteration); false if it has completed execution or been popped in some other way.

script

The script being executed in this frame (a Debugger.Script instance), or null on frames for calls to host functions and "debugger" frames. On frames whose callee property is not null, this is equal to callee.script.

offset

The offset of the bytecode instruction currently being executed in script, or undefined if the frame's script property is null.

environment

The lexical environment within which evaluation is taking place (a Debugger.Environment instance), or null on frames for calls to host functions and "debugger" frames.

callee

The function whose application created this frame, as a debuggee value, or null if this is not a "call" frame.

generator

True if this frame is a generator frame, false otherwise.

constructing

True if this frame is for a function called as a constructor, false otherwise.

arguments

The arguments passed to the current frame, or null if this is not a "call" frame. When non-null, this is an object, in the debugger's compartment, with Array.prototype on its prototype chain, 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. When the referent frame is popped, the argument value's properties' getters throw an error.

onStep

This property must be either undefined or a function. If it is a function, SpiderMonkey calls it, passing no arguments, when execution in this frame makes a small amount of progress. The function should return a resumption value specifying how the debuggee's execution should proceed. What constitutes "a small amount of progress" varies depending on the implementation, but it is fine-grained enough to implement useful "step" and "next" behavior.

onPop

This property must be either undefined or a function. If it is a function, SpiderMonkey calls it just before this frame is popped, passing a completion value indicating how this frame's execution completed. The function should return a resumption value indicating how execution should proceed. On newly created frames, this property's 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 thus calls to it take place in the debugger's compartment), and the call takes place in the thread to which the frame belongs. When a generator frame yields a value, SpiderMonkey calls its Debugger.Frame instance's onPop handler, if present, passing a yield resumption value; however, the Debugger.Frame instance remains live.

onResume(value)

This property must be either undefined or a function. If it is a function, SpiderMonkey calls it if the current frame is a generator frame whose execution has just been resumed. The function should return a resumption value indicating how execution should proceed. On newly created frames, this property's value is undefined. If the program resumed the generator by calling its send method and passing a value, then value is that value. Otherwise, value is undefined.

Function Properties of the Debugger.Frame Prototype Object

The functions described below may only be called with a this value referring to a Debugger.Frame instance; they may not be used as methods of other kinds of objects.

eval(code)

Evaluate code in the scope of this frame, and return a completion value describing how it completed. Code is a string. If this frame's environment property is null, throw a TypeError. All extant hook object methods, breakpoints, watchpoints, and so on remain active during the call. This function follows the invocation function conventions. Code is interpreted as strict mode code when it contains a Use Strict Directive, or the code executing in this frame is strict mode code.

evalWithBindings(code, bindings)

Like eval, but evaluate code in the scope of this frame, extended with bindings from the object bindings. For each own enumerable property of bindings named name whose value is value, include a variable in the environment in which code is evaluated named name, whose value is value. Each value must be a debuggee value. (This is not like a with statement: code may access, assign to, and delete the introduced bindings without having any effect on the bindings object.) This method allows debugger code to introduce temporary bindings that are visible to the given debuggee code and which refer to debugger-held debuggee values, and do so without mutating any existing debuggee scope.

pop(completion) (future plan)

Pop this frame (and any younger frames) from the stack as if this frame had completed as specified by the completion value completion. Note that this does not resume the debuggee's execution; it merely adjusts the debuggee's state to what it would be if this frame's execution had completed. The debuggee will only resume execution when you return from the hook object method that brought control to the debugger originally. This cannot remove any "call" frames for calls to host functions from the stack. (We might be able to make this work eventually, but it will take some cleverness.)

replaceCall(function, this, arguments) (future plan)

Pop any younger frames from the stack, and then change this frame into a frame for a call to function, with the given this value and arguments. This should be a debuggee value, or { asConstructor: true } to invoke function as a constructor, in which case SpiderMonkey provides an appropriate this value itself. Arguments should be an array of debuggee values. This frame must be a "call" frame. This can be used as a primitive in implementing some forms of a "patch and continue" debugger feature. Note that this does not 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. The debuggee will only resume execution when you return from the hook object method that brought control to the debugger originally. Like pop, this cannot remove "call" frames for calls to host functions from the stack.

Invocation functions

An invocation function is any function in this interface that allows the debugger to invoke code in the debuggee: Debugger.Object.prototype.call, Debugger.Frame.prototype.eval, 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:

1. Let older 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 Debugger.Frame instances.)
2. Push a "debugger" frame on the stack, with older as its older property.
3. Invoke the debuggee code as appropriate for the given invocation function, with the "debugger" frame as its continuation. For example, Debugger.Frame.prototype.eval pushes an "eval" frame for code it runs, whereas Debugger.Object.prototype.call pushes a "call" frame.
4. When the debuggee code completes, whether by returning, throwing an exception or being terminated, pop the "debugger" frame, and return an appropriate completion value from the invocation function to the debugger.

Generator Frames

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 yield produces a generator-iterator object, as does evaluating a generator expression like (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; while the generator is suspended, it has no particular continuation frame; and when it resumes again, the continuation frame for that resumption could be different from that of the previous resumption.

A Debugger.Frame instance representing a generator frame differs from an ordinary stack frame as follows:

• A generator frame's generator property is true.
• A generator frame disappears from the stack each time the generator yields a value and is suspended, and reappears atop the stack when it is 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.
• A generator frame's older property refers to the frame's continuation frame while the generator is running, and is null while the generator is suspended.
• A generator frame's depth property reflects the frame's position on the stack when the generator is resumed, and is null while the generator is suspended.
• A generator frame's live property remains true until the frame returns, throws an exception, or is terminated. Thus, generator frames can be live while not present on the stack.

The other Debugger.Frame methods and accessor properties work as described on generator frames, even when the generator frame is suspended. You may examine a suspended generator frame's variables, and use its script and offset members to see which yield it is suspended at.

A Debugger.Frame instance referring to a generator-iterator frame has a strong reference to the generator-iterator object; the frame (and its object) will live as long as the Debugger.Frame instance does. However, when the generator function returns, throws an exception, or is terminated, thus ending the iteration, the Debugger.Frame instance becomes inactive and its live property becomes false, just as would occur for any other sort of frame that is popped. A non-live Debugger.Frame instance no longer holds a strong reference to the generator-iterator object.

Debugger.Script

A Debugger.Script instance refers to a sequence of bytecode in the debuggee; it is the JavaScript-level presentation of a JSAPI JSScript object. Each of the following is represented by single JSScript object:

• The body of a function—that is, all the code in the function that is not contained within some nested function.
• The code passed to a single call to eval, excluding the bodies of any functions that code defines.
• The contents of a <script> element.
• A DOM event handler, whether embedded in HTML or attached to the element by other JavaScript code.
• Code appearing in a javascript: URL.

The Debugger interface constructs Debugger.Script objects as script objects are uncovered by the debugger: via the newScript hook object method; via Debugger.Frame's script properties; via the functionScript method of Debugger.Object instances; and so on. It constructs exactly one Debugger.Script instance for each underlying script object; debugger code can add its own properties to a script object and expect to find them later, use == to decide whether two expressions refer to the same script, and so on.

A Debugger.Script instance is a strong reference to a JSScript object; it protects the script it refers to from being garbage collected. However, scripts representing code passed to eval may be deleted when the eval returns; see the description of the liveproperty, below.

Note that SpiderMonkey may use the same Debugger.Script instances for equivalent functions or evaluated code --- that is, scripts representing the same source code, at the same position in the same source file, evaluated in the same lexical scope.

Accessor Properties of the Debugger.Script Prototype Object

A Debugger.Script instance inherits the following accessor properties from its prototype:

url

The filename or URL from which this script's code was loaded.

startLine

The number of the line at which this script's code starts, within the file or document named by url.

lineCount

The number of lines this script's code occupies, within the file or document named by url.

live

True if the script this Debugger.Script instance refers to still exists in the debuggee; false if it has been destroyed. For most scripts, this property is always true. However, when a call to eval or a similar feature returns, the script representing the top-level code may be deleted. When this occurs, the script's live property becomes false, and accessing its other properties or calling its methods throws an exception. Scripts are only deleted when the debuggee is running; the debugger need not worry that a script will be deleted by garbage collection or some other asynchronous activity. SpiderMonkey may elect to cache scripts for eval code and re-use them when equivalent code is evaluated later, so it is not correct to assume that every eval script will certainly be deleted when its execution completes.

Function Properties of the Debugger.Script Prototype Object

The functions described below may only be called with a this value referring to a Debugger.Script instance; they may not be used as methods of other kinds of objects.

decompile([pretty])

Return a string containing JavaScript source code equivalent to this script in its effect and result. If pretty is present and true, produce indented code with line breaks. (Note that Debugger.Object instances referring to functions also have a decompile method, whose result includes the function header and parameter names, so it is probably better to write f.decompile() than to write f.getFunctionScript().decompile().)

getAllOffsets()

Return an array L describing the relationship between bytecode instruction offsets and source code positions in this script. L is sparse, and indexed by source line number. If a source line number line has no code, then L has no line property. If there is code for line, then L[line] is an array of offsets of byte code instructions that are entry points to that line. For example, suppose we have a script for the following source code: a=[] for (i=1; i < 10; i++) // It's hip to be square. a[i] = i*i; Calling getAllOffsets() on that code might yield an array like this: [[0], [5, 20], , [10]] This array indicates that:

• the first line's code starts at offset 0 in the script;
• the for statement head has two entry points at offsets 5 and 20 (for the initialization, which is performed only once, and the loop test, which is performed at the start of each iteration);
• the third line has no code;
• and the fourth line begins at offset 10.

getLineOffsets(line)

Return an array of bytecode instruction offsets representing the entry points to source line line. If the script contains no executable code at that line, the array returned is empty.

getOffsetLine(offset)

Return the source code line responsible for the bytecode at offset in this script.

getChildScripts()

Return a new array whose elements are Debugger.Script objects for each function and each generator expression in this script. Only direct children are included; nested children can be reached by walking the tree.

setBreakpoint(offset, handler)

Set a breakpoint at the bytecode instruction at offset in this script, reporting hits to the hit method of handler, an object in the debugger compartment. If offset is not a valid offset in this script, throw an error. When execution reaches the given instruction, SpiderMonkey calls the hit method of handler, passing a Debugger.Frame instance representing the currently executing stack frame. The hit method's return value should be a resumption value, determining how execution should continue. Any number of breakpoints may be set at a single location; when control reaches that point, SpiderMonkey calls their handlers in an unspecified order. Any number of breakpoints may use the same handler object. Breakpoint handler calls are cross-compartment, intra-thread calls: handler.hit must be a function in the debugger's compartment (and thus calls to it take place in the debugger's compartment), and the call takes place in the same thread that hit the breakpoint. The new breakpoint belongs to this Debugger instance; disabling the Debugger instance disables this breakpoint.

getBreakpoints([offset])

Return an array containing the handler objects for all the breakpoints set at offset in this script. If offset is omitted, return the handlers of all breakpoints set anywhere in this script. If offset is present, but not a valid offset in this script, throw an error.

clearBreakpoints(handler, [offset])

Remove all breakpoints set in this Debugger instance that use handler as their handler. If offset is given, remove only those breakpoints set at offset that use handler; if offset is not a valid offset in this script, throw an error. Note that, if breakpoints using other handler objects are set at the same location(s) as handler, they remain in place.

clearAllBreakpoints([offset])

Remove all breakpoints set in this script. If offset is present, remove all breakpoints set in that script; if offset is not a valid bytecode offset in this script, throw an error.

Debugger.Object

A Debugger.Object instance represents an object in the debuggee. Debugger code never accesses debuggee objects directly; instead, it operates on Debugger.Object instances that refer to the debuggee objects.

A Debugger.Object instance has reflection-oriented methods to inspect and modify its referent. The referent's properties do not appear directly as properties of the Debugger.Object instance; the debugger can access them only through methods like Debugger.Object.prototype.getOwnPropertyDescriptor and Debugger.Object.prototype.defineProperty, ensuring that the debugger will not inadvertently invoke the referent's getters and setters.

SpiderMonkey creates exactly one Debugger.Object instance for each debuggee object it presents to the debugger: if the debugger encounters the same object through two different routes (perhaps two functions are called on the same object), SpiderMonkey presents the same Debugger.Object instance to the debugger each time. This means that the debugger can use the == operator to recognize when two Debugger.Object instances refer to the same debuggee object, and place its own properties on a Debugger.Object instance to store metadata about particular debuggee objects.

While most Debugger.Object instances are created by SpiderMonkey in the process of exposing debuggee's behavior and state to the debugger, the debugger can use Debugger.Object.prototype.copy and Debugger.Object.prototype.create to create objects in a debuggee compartment.

Debugger.Object instances protect their referents from the garbage collector; as long as the Debugger.Object instance is live, the referent remains live. Garbage collection has no debugger-visible effect on Debugger.Object instances.

Accessor Properties of the Debugger.Object prototype

A Debugger.Object instance inherits the following accessor properties from its prototype:

proto

The referent's prototype (as a new Debugger.Object instance), or null if it has no prototype.

class

A string naming the ECMAScript [[Class]] of the referent.

callable

true if the referent is a callable object (such as a function or a function Proxy); false otherwise.

name

If the referent is a function, its function name. If the referent is an anonymous function, or not a function at all, this is undefined.

parameterNames

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 undefined. 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 undefined. 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: function f(a, [b, c], {d, e:f}) { ... } then this Debugger.Object instance's parameterNames property would have the value: ["a", ["b", "c"], {d:"d", e:"f"}]

script

If the referent is a function implemented in JavaScript, that function's script, as a Debugger.Script instance. If the referent is not a function implemented in JavaScript, this is undefined.

scope

If the referent is a function, a Debugger.Environment instance representing the lexical environment enclosing the function when it was created. If the referent is not a function, return undefined.

Properties of the Debugger.Object prototype

The functions described below may only be called with a this value referring to a Debugger.Object instance; they may not be used as methods of other kinds of objects. The descriptions use "referent" to mean "the referent of this Debugger.Object instance".

getOwnPropertyDescriptor(name)

Return a property descriptor for the property named name of the referent. If the referent has no such property, return undefined. (This function behaves like the standard Object.getOwnPropertyDescriptor function, except that the object being inspected is implicit; the property descriptor returned is in the debugger's compartment; and its value, get, and set properties, if present, are debuggee values.)

getOwnPropertyNames()

Return an array of strings naming all the referent's own properties, as if Object.getOwnPropertyNames(referent) had been called in the debuggee, and the result copied to the debugger's compartment.

defineProperty(name, attributes)

Define a property on the referent named name, as described by the property descriptor descriptor. Any value, get, and set properties of attributes must be debuggee values. (This function behaves like Object.defineProperty, except that the target object is implicit, and in a different compartment from the function and descriptor.)

defineProperties(properties)

Add the properties given by properties to the referent. (This function behaves like Object.defineProperties, except that the target object is implicit, and in a different compartment from the properties argument.)

deleteProperty(name)

Remove the referent's property named name. Return true if the property was successfully removed, or if the referent has no such property. Return false if the property is non-configurable.

seal()

Prevent properties from being added to or deleted from the referent. Return this Debugger.Object instance. (This function behaves like the standard Object.seal function, except that the object to be sealed is implicit and in a different compartment from the caller.)

freeze()

Prevent properties from being added to or deleted from the referent, and mark each property as non-writable. Return this Debugger.Object instance. (This function behaves like the standard Object.freeze function, except that the object to be sealed is implicit and in a different compartment from the caller.)

preventExtensions()

Prevent properties from being added to the referent. (This function behaves like the standard Object.preventExtensions function, except that the object to operate on is implicit and in a different compartment from the caller.)

isSealed()

Return true if the referent is sealed—that is, if it is not extensible, and all its properties have been marked as non-configurable. (This function behaves like the standard Object.isSealed function, except that the object inspected is implicit and in a different compartment from the caller.)

isFrozen()

Return true if the referent is frozen—that is, if it is not extensible, and all its properties have been marked as non-configurable and read-only. (This function behaves like the standard Object.isFrozen function, except that the object inspected is implicit and in a different compartment from the caller.)

isExtensible()

Return true if the referent is extensible—that is, if it can have new properties defined on it. (This function behaves like the standard Object.isExtensible function, except that the object inspected is implicit and in a different compartment from the caller.)

copy(value)

Apply the HTML5 "structured cloning" algorithm to create a copy of value in the referent's compartment, and return a Debugger.Object instance referring to the copy. Note that this returns primitive values unchanged. This means you can use Debugger.Object.prototype.copy as a generic "debugger value to debuggee value" conversion function—within the limitations of the "structured cloning" algorithm.

create(prototype, [properties])

Create a new object in the referent's compartment, and return a Debugger.Object referring to it. The new object's prototype is prototype, which must be a debuggee object. The new object's properties are as given by properties, as if properties were passed to Debugger.Object.prototype.defineProperties, with the new Debugger.Object instance as the this value.

decompile([pretty])

If the referent is a function defined in JavaScript, return the source code for a JavaScript function definition equivalent to the referent function in its effect and result, as a string. If pretty is present and true, produce indented code with line breaks. If the referent is not a function, return undefined.

call(this, argument, ...)

If the referent is callable, call it with the given this value and argument values, and return a completion value describing how the call completed. This should be a debuggee value, or { asConstructor: true } to invoke the referent as a constructor, in which case SpiderMonkey provides an appropriate this value itself. Each argument 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 frames. If the referent is not callable, throw a TypeError.

apply(this, arguments)

If the referent is callable, call it with the given this value and the argument values in arguments, and return a completion value describing how the call completed. This should be a debuggee value, or { asConstructor: true } to invoke function as a constructor, in which case SpiderMonkey provides an appropriate this value itself. Arguments must either be an array (in the debugger) of debuggee values, or null or undefined, 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 frames. If the referent is not callable, throw a TypeError.

Debugger.Environment

A Debugger.Environment instance represents a lexical environment, associating names with variables. "Call", "eval", and "global" stack frames have an associated environment object describing the variables in scope in that frame, and each function defined in JavaScript has an environment representing the scope the function has closed over.

SpiderMonkey Debugger.Environment instances as needed as the debugger inspects stack frames and function objects; calling Debugger.Environment as a function or constructor yields a TypeError.

SpiderMonkey creates exactly one Debugger.Environment instance for each environment it presents to the debugger: if the debugger encounters the same environment through two different routes (perhaps two functions have closed over the same scope), SpiderMonkey presents the same Debugger.Environment instance to the debugger each time. This means that the debugger can use the == operator to recognize when two Debugger.Environment instances refer to the same scope in the debuggee, and place its own properties on a Debugger.Environment instance to store metadata about particular scopes.

Debugger.Environment instances protect their referents from the garbage collector; as long as the Debugger.Environment instance is live, the referent remains live. Garbage collection has no debugger-visible effect on Debugger.Environment instances.

Accessor Properties of the Debugger.Environment Prototype Object

A Debugger.Environment instance inherits the following accessor properties from its prototype:

type

The type of this environment object, one of the following values:

• "declarative", indicating that the environment is a declarative environment record. Function calls, calls to eval, let blocks, catch blocks, and the like create declarative environment records.
• "object", indicating that the environment's bindings are the properties of an object. With statements create object environments; the global object and DOM elements appear in the scope chain via object environments.

outerEnvironment

The environment that encloses this one, or null if this is the outermost environment. This is a accessor property with a getter, and no setter, inherited by instances.

object

A Debugger.Object instance referring to the object whose properties this environment record reflects. If this is a declarative environment record, this accessor throws a TypeError.

Function Properties of the Debugger.Environment Prototype Object

The methods described below may only be called with a this value referring to a Debugger.Environment instance; they may not be used as methods of other kinds of objects.

boundIdentifiers()

Return an array of strings giving the names of the identifiers bound by this environment.

getVariableDescriptor(name)

Return an property descriptor describing the variable bound to name in this environment, of the sort returned by getOwnPropertyDescriptor. If this is an object environment record, this simply returns the descriptor for the given property of the environment's object. If this is a declarative environment record, this returns a descriptor reflecting the binding's mutability as the descriptor's writable property, and its deletability as the descriptor's configurable property. All declarative environment record bindings are marked as enumerable. (This isn't great; the semantics of variables in declarative enviroments don't really match those of properties, so returning descriptors that suggest that they do may be unhelpful.) If there is no variable named name in this environment, throw a ReferenceError. This method does not search this environment's enclosing environments for bindings for name.

defineVariable(name, descriptor)

Create or reconfigure the variable named name bound in this environment according to descriptor. On success, return undefined; on failure, throw an appropriate exception.

findBinding(name)

Return a reference to the innermost environment, starting with this environment, that binds name, a string. If name is unbound in this environment, return null.

Future Work

• The interface should reveal the presence of scripted proxies, allow the user to retrieve their handlers, and so on.
• The interface should provide clean, predictable ways to observe the effects of garbage collection. For example, perhaps it should provide an interface like [R. Kent Dybvig's guardians] for observing when objects and scripts become unreachable.