1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.Script.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,238 @@
1.4 +# Debugger.Script
1.5 +
1.6 +A `Debugger.Script` instance refers to a sequence of bytecode in the
1.7 +debuggee; it is the [`Debugger`][debugger-object] API's presentation of a JSAPI `JSScript`
1.8 +object. Each of the following is represented by single JSScript object:
1.9 +
1.10 +* The body of a function—that is, all the code in the function that is not
1.11 + contained within some nested function.
1.12 +
1.13 +* The code passed to a single call to `eval`, excluding the bodies of any
1.14 + functions that code defines.
1.15 +
1.16 +* The contents of a `<script>` element.
1.17 +
1.18 +* A DOM event handler, whether embedded in HTML or attached to the element
1.19 + by other JavaScript code.
1.20 +
1.21 +* Code appearing in a `javascript:` URL.
1.22 +
1.23 +The [`Debugger`][debugger-object] interface constructs `Debugger.Script` objects as scripts
1.24 +of debuggee code are uncovered by the debugger: via the `onNewScript`
1.25 +handler method; via [`Debugger.Frame`][frame]'s `script` properties; via the
1.26 +`functionScript` method of [`Debugger.Object`][object] instances; and so on. For a
1.27 +given [`Debugger`][debugger-object] instance, SpiderMonkey constructs exactly one
1.28 +`Debugger.Script` instance for each underlying script object; debugger
1.29 +code can add its own properties to a script object and expect to find
1.30 +them later, use `==` to decide whether two expressions refer to the same
1.31 +script, and so on.
1.32 +
1.33 +(If more than one [`Debugger`][debugger-object] instance is debugging the same code, each
1.34 +[`Debugger`][debugger-object] gets a separate `Debugger.Script` instance for a given
1.35 +script. This allows the code using each [`Debugger`][debugger-object] instance to place
1.36 +whatever properties it likes on its `Debugger.Script` instances, without
1.37 +worrying about interfering with other debuggers.)
1.38 +
1.39 +A `Debugger.Script` instance is a strong reference to a JSScript object;
1.40 +it protects the script it refers to from being garbage collected.
1.41 +
1.42 +Note that SpiderMonkey may use the same `Debugger.Script` instances for
1.43 +equivalent functions or evaluated code—that is, scripts representing the
1.44 +same source code, at the same position in the same source file,
1.45 +evaluated in the same lexical environment.
1.46 +
1.47 +## Accessor Properties of the Debugger.Script Prototype Object
1.48 +
1.49 +A `Debugger.Script` instance inherits the following accessor properties
1.50 +from its prototype:
1.51 +
1.52 +`url`
1.53 +: The filename or URL from which this script's code was loaded. If the
1.54 + `source` property is non-`null`, then this is equal to `source.url`.
1.55 +
1.56 +`startLine`
1.57 +: The number of the line at which this script's code starts, within the
1.58 + file or document named by `url`.
1.59 +
1.60 +`lineCount`
1.61 +: The number of lines this script's code occupies, within the file or
1.62 + document named by `url`.
1.63 +
1.64 +`source`
1.65 +: The [`Debugger.Source`][source] instance representing the source code from which
1.66 + this script was produced. This is `null` if the source code was not
1.67 + retained.
1.68 +
1.69 +`sourceStart`
1.70 +: The character within the [`Debugger.Source`][source] instance given by `source` at
1.71 + which this script's code starts; zero-based. If this is a function's
1.72 + script, this is the index of the start of the `function` token in the
1.73 + source code.
1.74 +
1.75 +`sourceLength`
1.76 +: The length, in characters, of this script's code within the
1.77 + [`Debugger.Source`][source] instance given by `source`.
1.78 +
1.79 +`global`
1.80 +: A [`Debugger.Object`][object] instance referring to the global object in whose
1.81 + scope this script runs. The result refers to the global directly, not
1.82 + via a wrapper or a `WindowProxy` ("outer window", in Firefox).
1.83 +
1.84 +`staticLevel`
1.85 +: The number of function bodies enclosing this script's code.
1.86 +
1.87 + Global code is at level zero; bodies of functions defined at the top
1.88 + level in global code are at level one; bodies of functions nested within
1.89 + those are at level two; and so on.
1.90 +
1.91 + A script for code passed to direct `eval` is at a static level one
1.92 + greater than that of the script containing the call to `eval`, because
1.93 + direct eval code runs within the caller's scope. However, a script for
1.94 + code passed to an indirect `eval` call is at static level zero, since it
1.95 + is evaluated in the global scope.
1.96 +
1.97 + Note that a generator's expressions are considered to be part of the
1.98 + body of a synthetic function, produced by the compiler.
1.99 +
1.100 + Scripts' static level be useful in deciding where to set breakpoints.
1.101 + For example, a breakpoint set on line 3 in this code:
1.102 +
1.103 + function f() {
1.104 + x = function g() { // line 2
1.105 + // line 3; no code here
1.106 + ...;
1.107 + }
1.108 + }
1.109 +
1.110 + should be set in `g`'s script, not in `f`'s, even though neither script
1.111 + contains code at that line. In such a case, the most deeply nested
1.112 + script—the one with the highest static level—should receive the
1.113 + breakpoint.
1.114 +
1.115 +`strictMode`
1.116 +: This is `true` if this script's code is ECMAScript strict mode code, and
1.117 + `false` otherwise.
1.118 +
1.119 +`sourceMapURL`
1.120 +: If this script was produced by a minimizer or translated from some other
1.121 + language, and we know the URL of a <b>source map</b> document relating
1.122 + the source positions in this script to the corresponding source
1.123 + positions in the original source, then this property's value is that
1.124 + URL. Otherwise, this is `null`.
1.125 +
1.126 + (On the web, the translator may provide the source map URL in a
1.127 + specially formatted comment in the JavaScript source code, or via a
1.128 + header in the HTTP reply that carried the generated JavaScript.)
1.129 +
1.130 +## Function Properties of the Debugger.Script Prototype Object
1.131 +
1.132 +The functions described below may only be called with a `this` value
1.133 +referring to a `Debugger.Script` instance; they may not be used as
1.134 +methods of other kinds of objects.
1.135 +
1.136 +<code>decompile([<i>pretty</i>])</code>
1.137 +: Return a string containing JavaScript source code equivalent to this
1.138 + script in its effect and result. If <i>pretty</i> is present and true,
1.139 + produce indented code with line breaks.
1.140 +
1.141 + (Note that [`Debugger.Object`][object] instances referring to functions also have
1.142 + a `decompile` method, whose result includes the function header and
1.143 + parameter names, so it is probably better to write
1.144 + <code><i>f</i>.decompile()</code> than to write
1.145 + <code><i>f</i>.getFunctionScript().decompile()</code>.)
1.146 +
1.147 +`getAllOffsets()`
1.148 +: Return an array <i>L</i> describing the relationship between bytecode
1.149 + instruction offsets and source code positions in this script. <i>L</i>
1.150 + is sparse, and indexed by source line number. If a source line number
1.151 + <i>line</i> has no code, then <i>L</i> has no <i>line</i> property. If
1.152 + there is code for <i>line</i>, then <code><i>L</i>[<i>line</i>]</code> is an array
1.153 + of offsets of byte code instructions that are entry points to that line.
1.154 +
1.155 + For example, suppose we have a script for the following source code:
1.156 +
1.157 + a=[]
1.158 + for (i=1; i < 10; i++)
1.159 + // It's hip to be square.
1.160 + a[i] = i*i;
1.161 +
1.162 + Calling `getAllOffsets()` on that code might yield an array like this:
1.163 +
1.164 + [[0], [5, 20], , [10]]
1.165 +
1.166 + This array indicates that:
1.167 +
1.168 + * the first line's code starts at offset 0 in the script;
1.169 +
1.170 + * the `for` statement head has two entry points at offsets 5 and 20 (for
1.171 + the initialization, which is performed only once, and the loop test,
1.172 + which is performed at the start of each iteration);
1.173 +
1.174 + * the third line has no code;
1.175 +
1.176 + * and the fourth line begins at offset 10.
1.177 +
1.178 +<code>getLineOffsets(<i>line</i>)</code>
1.179 +: Return an array of bytecode instruction offsets representing the entry
1.180 + points to source line <i>line</i>. If the script contains no executable
1.181 + code at that line, the array returned is empty.
1.182 +
1.183 +<code>getOffsetLine(<i>offset</i>)</code>
1.184 +: Return the source code line responsible for the bytecode at
1.185 + <i>offset</i> in this script.
1.186 +
1.187 +`getChildScripts()`
1.188 +: Return a new array whose elements are Debugger.Script objects for each
1.189 + function and each generator expression in this script. Only direct
1.190 + children are included; nested children can be reached by walking the
1.191 + tree.
1.192 +
1.193 +<code>setBreakpoint(<i>offset</i>, <i>handler</i>)</code>
1.194 +: Set a breakpoint at the bytecode instruction at <i>offset</i> in this
1.195 + script, reporting hits to the `hit` method of <i>handler</i>. If
1.196 + <i>offset</i> is not a valid offset in this script, throw an error.
1.197 +
1.198 + When execution reaches the given instruction, SpiderMonkey calls the
1.199 + `hit<code> method of <i>handler</i>, passing a [</code>Debugger.Frame`][frame] instance
1.200 + representing the currently executing stack frame. The `hit` method's
1.201 + return value should be a [resumption value][rv], determining how execution should
1.202 + continue.
1.203 +
1.204 + Any number of breakpoints may be set at a single location; when control
1.205 + reaches that point, SpiderMonkey calls their handlers in an unspecified
1.206 + order.
1.207 +
1.208 + Any number of breakpoints may use the same <i>handler</i> object.
1.209 +
1.210 + Breakpoint handler method calls are cross-compartment, intra-thread
1.211 + calls: the call takes place in the same thread that hit the breakpoint,
1.212 + and in the compartment containing the handler function (typically the
1.213 + debugger's compartment).
1.214 +
1.215 + The new breakpoint belongs to the [`Debugger`][debugger-object] instance to which this
1.216 + script belongs; disabling the [`Debugger`][debugger-object] instance disables this
1.217 + breakpoint.
1.218 +
1.219 +<code>getBreakpoints([<i>offset</i>])</code>
1.220 +: Return an array containing the handler objects for all the breakpoints
1.221 + set at <i>offset</i> in this script. If <i>offset</i> is omitted, return
1.222 + the handlers of all breakpoints set anywhere in this script. If
1.223 + <i>offset</i> is present, but not a valid offset in this script, throw
1.224 + an error.
1.225 +
1.226 +<code>clearBreakpoints(handler, [<i>offset</i>])</code>
1.227 +: Remove all breakpoints set in this [`Debugger`][debugger-object] instance that use
1.228 + <i>handler</i> as their handler. If <i>offset</i> is given, remove only
1.229 + those breakpoints set at <i>offset</i> that use <i>handler</i>; if
1.230 + <i>offset</i> is not a valid offset in this script, throw an error.
1.231 +
1.232 + Note that, if breakpoints using other handler objects are set at the
1.233 + same location(s) as <i>handler</i>, they remain in place.
1.234 +
1.235 +<code>clearAllBreakpoints([<i>offset</i>])</code>
1.236 +: Remove all breakpoints set in this script. If <i>offset</i> is present,
1.237 + remove all breakpoints set at that offset in this script; if
1.238 + <i>offset</i> is not a valid bytecode offset in this script, throw an
1.239 + error.
1.240 +
1.241 +
