Debugger.Script

A Debugger.Script instance may refer to a sequence of bytecode in the debuggee or to a block of WebAssembly code. For the former, it is the Debugger API’s presentation of a JSAPI JSScript object. The two cases are distinguished by their format property being "js" or "wasm".

Debugger.Script for JSScripts

For Debugger.Script instances referring to a JSScript, they are distinguished by their format property being "js".

Each of the following is represented by a 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 scripts of debuggee code are uncovered by the debugger: via the onNewScript handler method; via Debugger.Frame’s script properties; via the functionScript method of Debugger.Object instances; and so on. For a given Debugger instance, SpiderMonkey 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.

(If more than one Debugger instance is debugging the same code, each Debugger gets a separate Debugger.Script instance for a given script. This allows the code using each Debugger instance to place whatever properties it likes on its Debugger.Script instances, without worrying about interfering with other debuggers.)

A Debugger.Script instance is a strong reference to a JSScript object; it protects the script it refers to from being garbage collected.

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 environment.

Debugger.Script for WebAssembly

For Debugger.Script instances referring to a block of WebAssembly code, they are distinguished by their format property being "wasm".

Currently only entire modules evaluated via new WebAssembly.Module are represented.

Debugger.Script objects for WebAssembly are uncovered via onNewScript when a new WebAssembly module is instantiated and via the findScripts method on Debugger instances. SpiderMonkey constructs exactly one Debugger.Script for each underlying WebAssembly module per Debugger instance.

A Debugger.Script instance is a strong reference to the underlying WebAssembly module; it protects the module it refers to from being garbage collected.

Please note at the time of this writing, support for WebAssembly is very preliminary. Many properties and methods below throw.

Convention

For descriptions of properties and methods below, if the behavior of the property or method differs between the instance referring to a JSScript or to a block of WebAssembly code, the text will be split into two sections, headed by “if the instance refers to a JSScript” and “if the instance refers to WebAssembly code”, respectively. If the behavior does not differ, no such emphasized headings will appear.

Accessor Properties of the Debugger.Script Prototype Object

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

isGeneratorFunction

True if this instance refers to a JSScript for a function defined with a function* expression or statement. False otherwise.

isAsyncFunction

True if this instance refers to a JSScript for an async function, defined with an async function expression or statement. False otherwise.

displayName

If the instance refers to a JSScript, this is the script’s display name, if it has one. If the script has no display name — for example, if it is a top-level eval script — this is undefined.

If the script’s function has a given name, its display name is the same as its function’s given name.

If the script’s function has no name, SpiderMonkey attempts to infer an appropriate name for it given its context. For example:

function f() {}          // display name: f (the given name)
var g = function () {};  // display name: g
o.p = function () {};    // display name: o.p
var q = {
  r: function () {}      // display name: q.r
};

Note that the display name may not be a proper JavaScript identifier, or even a proper expression: we attempt to find helpful names even when the function is not immediately assigned as the value of some variable or property. Thus, we use a/b to refer to the b defined within a, and a< to refer to a function that occurs somewhere within an expression that is assigned to a. For example:

function h() {
  var i = function() {};    // display name: h/i
  f(function () {});        // display name: h/<
}
var s = f(function () {});  // display name: s<``</pre>

If the instance refers to WebAssembly code, throw a TypeError.

url

If the instance refers to a JSScript, the filename or URL from which this script’s code was loaded. For scripts created by eval or the Function constructor, this may be a synthesized filename, starting with a valid URL and followed by information tracking how the code was introduced into the system; the entire string is not a valid URL. For Function.prototype’s script, this is null. If this Debugger.Script’s source property is non-null, then this is equal to source.url.

If the instance refers to WebAssembly code, throw a TypeError.

startLine

If the instance refers to a JSScript, the number of the line at which this script’s code starts, within the file or document named by url.

lineCount

If the instance refers to a JSScript, the number of lines this script’s code occupies, within the file or document named by url.

source

If the instance refers to a JSScript, the Debugger.Source instance representing the source code from which this script was produced. This is null if the source code was not retained.

If the instance refers to WebAssembly code, the Debugger.Source instance representing the serialized text format of the WebAssembly code.

sourceStart

If the instance refers to a JSScript, the character within the Debugger.Source instance given by source at which this script’s code starts; zero-based. If this is a function’s script, this is the index of the start of the function token in the source code.

If the instance refers to WebAssembly code, throw a TypeError.

sourceLength

If the instance refers to a JSScript, the length, in characters, of this script’s code within the Debugger.Source instance given by source.

If the instance refers to WebAssembly code, throw a TypeError.

global

If the instance refers to a JSScript, a Debugger.Object instance referring to the global object in whose scope this script runs. The result refers to the global directly, not via a wrapper or a WindowProxy (“outer window”, in Firefox).

If the instance refers to WebAssembly code, throw a TypeError.

format

If the instance refers to a JSScript, "js".

If the instance refers to WebAssembly code, "wasm".

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.

getAllOffsets()

If the instance refers to a JSScript, 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