Debugger.Script

This article covers features introduced in SpiderMonkey 1.8.6

A Debugger.Script instance refers to a bytecode sequence in a debuggee. This is the JavaScript-level presentation of a JSAPI JSScript object. It may represent code from any of the following types of JSScript object:

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

Accessor properties

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

Property Type Description
lineCount Number The number of lines in the source file the script's code occupies.
live Boolean

true if the script represented by this instance still exists in the debuggee or false if it's been destroyed.

This is true for most scripts. However, when a call to eval() or a similar feature returns, the script representing the top-level code may be deleted and this property becomes false. In that situation, accessing the Debugger.Script object's properties and methods throws an exception.

Scripts are only deleted while the debuggee is running. The debugger doesn't need to worry that a script will be deleted asynchronously, such as by garbage collection.

Note: SpiderMonkey may choose to cache scripts for eval() code and re-use them when equivalent code is evaluated later, so you should not assume that every eval() script will be deleted when its execution is completed.
startLine Number The line number in the code file indicated by url at which the script's code begins.
strictMode Boolean true if the script's code is ECMAScript strict mode code; otherwise false.
url String The filename or URL from which the script's code was loaded.

Methods

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

Method Return value Description
clearAllBreakpoints() n/a Removes all breakpoints set in this script.
clearBreakpoints() n/a Removes all breakpoints that use the specified handler; optionally, only breakpoints at a particular offset can be removed.
decompile() String

Returns a string containing a JavaScript source code equivalent to the referenced script, both in effect and result. This does not include the function header and parameter names, however; see Debugger.Object.decompile() for a way to get what you probably want in that case.

getAllOffsets() Array Returns an array describing the relationship between bytecode instruction offsets and source code positions in the script.
getAllColumnOffsets() Array Returns an array which, for each position in the source code, describes the bytecode offsets of all instructions that are an entry point for that position.
getBreakpoints() Array of Object Returns an array of the handler objects for all the breakpoints set at a given offset into the script, or in the entire script.
getChildScripts() Array of Debugger.Script Returns an array whose elements are the Debugger.Script objects representing each function and generator expression in the script.
getLineOffsets() Array Returns an array of bytecode instruction offsets representing the entry points on the specified line of the source code.
getOffsetLine() Number Returns the line number containing the bytecode at the specified offset into the script.
setBreakpoint() n/a Sets a new breakpoint in this script.

clearAllBreakpoints()

Removes all breakpoints set on the script. Optionally, you may specify a bytecode offset to only remove breakpoints at a specific offset in the script.

clearAllBreakpoints(
  [optional] offse
 );
Parameters
offset Optional
An offset into the script's bytecode. If this is provided, only breakpoints located at this offset are removed. If the offset is not valid in this script, an error is thrown.

clearBreakpoints()

Removes all of the breakpoints set that use the specified handler. Optionally, you may specify a bytecode offset to only remove matching breakpoints at a specific offset in the script.

clearAllBreakpoints(
  handler,
  [optional] offset
);
Parameters
handler
A breakpoint handler object for which to clear breakpoints. Any matching breakpoints using this handler object are removed.
offset Optional
An offset into the script's bytecode. If this is provided, only breakpoints both using the specified handler and located at this offset are removed. If the offset is not valid in this script, an error is thrown.
Notes

Breakpoints using other handler objects, even at the same offset, are not affected by this method.

decompile()

Returns a string containing JavaScript code equivalent to this script in both effect and result.

Note: The returned string doesn't include the function header and parameter names, however; see Debugger.Object.decompile() for a way to get what you probably want in that case.
String decompile(
  [optional] pretty
);
Parameters
pretty Optional
If specified and set to true, this parameter causes the returned code to be formatted with indentations and line breaks to make it more human-readable.
Return value

JavaScript source code for this script.

getAllOffsets()

Returns an array that describes the relationships between bytecode instruction offsets and their positions in the source code from which the script was loaded. This provides a way to, for example, display the current execution point in the user interface for your debugger code.

getAllOffsets()
Parameters

None.

Return value

A sparse array, indexed by source code line number. Lines in the source that have no code have no corresponding entry in the array. For lines that do have code, the corresponding entry in the array is an array of offsets to each bytecode instruction that's an entry point to the line.

Example

Consider this source code:

 a=[];
 for (i=1; i < 10; i++)
   // It's hip to be square.
   a[i] = i*i;

The array returned by getAllOffsets() on this code might look like this:

[
  [0],
  [5, 20],
  ,
  [10]
]

The first line of code starts at offset 0 in the script; this is the code a=[].

The for statement on line 2 has two entry points. The first is at offset 5 into the bytecode; this is the initialization of the loop variable: i=1; this happens just once, when the for loop is initialized. The second is the loop test, which is executed at the start of each loop iteration.

The third line has no code; it's just a comment.

The fourth line has just one entry point, starting at offset 10 into the bytecode, for the code a[i] = i*i.

Note that the offsets don't necessarily progress in increasing order; a lot depends on how the optimization of the bytecode was performed.

getAllColumnOffsets()

Returns an array which, for each position in the source code, describes the bytecode offsets of all instructions that are an entry point for that position. A position is a (line, column) pair. An instruction is an entry point for a given position if it can be reached from an instruction on a different position. To set a breakpoint on a given position you need to set a breakpoint on all entry points for that position.

This function differs from getAllOffsets in that it considers instructions that can be reached from an instruction on a different column on the same line as an entry point for their respective position, whereas getAllOffsets does not consider the instruction an entry point in that case. This distinction is useful if one wants to set multiple breakpoints per line.

Parameters

None.

Return value

An array of entries, each of which map a position to a bytecode offset. Each position in the source code has zero or more entries, one for each entry point. Individual entries in the array look like this:

{
   lineNumber: 2
   columnNumber: 3
   offset: 42
}

getBreakpoints()

Returns an array of the handler objects for all the breakpoints in the script, or, optionally, at a specified offset into the bytecode.

getBreakpoints(
  [optional] offset
);
Parameters
offset Optional
The offset into the bytecode for which to return all breakpoints. If this isn't specified, all breakpoint handlers in the script are returned.
Return value

An array of all breakpoint handlers in the script (or at the specified offset).

Exceptions thrown
TypeError
offset was specified but is not a valid offset into the script.

getChildScripts()

Returns a new array containing Debugger.Script objects for each function and generator expression in the script.

Array getChildScripts();
Parameters

None.

Return value

An array whose elements are Debugger.Script objects representing each of the immediate child functions and generator expressions in the script.

Note: The returned array contains only direct children of the script; if you need all descendants, you need to walk the tree yourself.

getLineOffsets()

Returns an array of bytecode instruction offsets to the entry points on the specified line of the source code file for the script.

Array getLineOffsets(
  line
);
Parameters
line
The line number in the source code file for which to retrieve the entry point offsets.
Return value

An array containing the offsets to the bytecode for each entry point in the specified line of the source code. If the specified line has no entry points, this array is empty.

getOffsetLine()

Returns the line number in the original source code file on which the specified bytecode offset occurs.

Number getOffsetLine(
  offset
);
Parameters
offset
The offset to the bytecode for which to retrieve the corresponding source code line number.
Return value

The line number on which the specified bytecode offset occurs.

Exceptions thrown
TypeError
The specified offset is invalid.

setBreakpoint()

Sets a breakpoint at the specified bytecode instruction offset.

Note: The new breakpoint belongs to the Debugger instance in which it was created; disabling the Debugger instance also disables the new breakpoint.
setBreakpoint(
  offset,
  handler
);
Parameters
offset
The offset into the bytecode at which to place the new breakpoint.
handler
A breakpoint handler object to be called when the breakpoint is reached. This object's hit() method gets called at that time. The object must be in the debugger's compartment.
Exceptions thrown
TypeError
The specified offset is invalid.

Document Tags and Contributors

Contributors to this page: Sheppy, ejpbruel1
Last updated by: ejpbruel1,