1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.Source.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,212 @@
1.4 +# Debugger.Source
1.5 +
1.6 +A `Debugger.Source` instance represents a piece of JavaScript source
1.7 +code: its properties provide the source code itself as a string, and
1.8 +describe where it came from. Each [`Debugger.Script`][script] instance refers to
1.9 +the `Debugger.Source` instance holding the source code from which it was
1.10 +produced.
1.11 +
1.12 +If a single piece of source code contains both top-level code and
1.13 +function definitions, perhaps with nested functions, then the
1.14 +[`Debugger.Script`][script] instances for those all refer to the same
1.15 +`Debugger.Source` instance. Each script indicates the substring of the
1.16 +overall source to which it corresponds.
1.17 +
1.18 +A `Debugger.Source` instance may represent only a portion of a larger
1.19 +source document. For example, an HTML document can contain JavaScript in
1.20 +multiple `<script>` elements and event handler content attributes.
1.21 +In this case, there may be either a single `Debugger.Source` instance
1.22 +for the entire HTML document, with each [`Debugger.Script`][script] referring to
1.23 +its substring of the document; or there may be a separate
1.24 +`Debugger.Source` instance for each `<script>` element and
1.25 +attribute. The choice is left up to the implementation.
1.26 +
1.27 +If a given piece of source code is presented to the JavaScript
1.28 +implementation more than once, with the same origin metadata, the
1.29 +JavaScript implementation may generate a fresh `Debugger.Source`
1.30 +instance to represent each presentation, or it may use a single
1.31 +`Debugger.Source` instance to represent them all.
1.32 +
1.33 +Each [`Debugger`][debugger-object] instance has a separate collection of `Debugger.Source`
1.34 +instances representing the source code that has been presented to the
1.35 +system.
1.36 +
1.37 +A debugger may place its own properties on `Debugger.Source` instances,
1.38 +to store metadata about particular pieces of source code.
1.39 +
1.40 +
1.41 +## Accessor Properties of the Debugger.Source Prototype Object
1.42 +
1.43 +A `Debugger.Source` instance inherits the following accessor properties
1.44 +from its prototype:
1.45 +
1.46 +`text`
1.47 +: The JavaScript source code, as a string. The value satisfies the
1.48 + `Program`, `FunctionDeclaration`, or `FunctionExpression` productions in
1.49 + the ECMAScript standard.
1.50 +
1.51 +`enclosingStart` <i>(future plan)</i>
1.52 +: The position within the enclosing document at which this source's text
1.53 + starts. This is a zero-based character offset. (The length of this
1.54 + script within the enclosing document is `source.length`.)
1.55 +
1.56 +`lineCount` <i>(future plan)</i>
1.57 +: The number of lines in the source code. If there are characters after
1.58 + the last newline in the source code, those count as a final line;
1.59 + otherwise, `lineCount` is equal to the number of newlines in the source
1.60 + code.
1.61 +
1.62 +`url`
1.63 +: The URL from which this source was loaded, if this source was loaded
1.64 + from a URL. Otherwise, this is `undefined`. Source may be loaded from a
1.65 + URL in the following ways:
1.66 +
1.67 + * The URL may appear as the `src` attribute of a `<script>` element
1.68 + in markup text.
1.69 +
1.70 + * The URL may be passed to the `Worker` web worker constructor, or the web
1.71 + worker `importScripts` function.
1.72 +
1.73 + * The URL may be the name of a XPCOM JavaScript module or subscript.
1.74 +
1.75 + (Note that code passed to `eval`, the `Function` constructor, or a
1.76 + similar function is <i>not</i> considered to be loaded from a URL; the
1.77 + `url` accessor on `Debugger.Source` instances for such sources should
1.78 + return `undefined`.)
1.79 +
1.80 +`element`
1.81 +: The [`Debugger.Object`][object] instance referring to the DOM element to which
1.82 + this source code belongs, if any, or `undefined` if it belongs to no DOM
1.83 + element. Source belongs to a DOM element in the following cases:
1.84 +
1.85 + * Source belongs to a `<script>` element if it is the element's text
1.86 + content (that is, it is written out as the body of the `<script>`
1.87 + element in the markup text), or is the source document referenced by its
1.88 + `src` attribute.
1.89 +
1.90 + * Source belongs to a DOM element if it is an event handler content
1.91 + attribute (that is, if it is written out in the markup text as an
1.92 + attribute value).
1.93 +
1.94 + * Source belongs to a DOM element if it was assigned to one of the
1.95 + element's event handler IDL attributes as a string. (Note that one may
1.96 + assign both strings and functions to DOM elements' event handler IDL
1.97 + attributes. If one assigns a function, that function's script's source
1.98 + does <i>not</i> belong to the DOM element; the function's definition
1.99 + must appear elsewhere.)
1.100 +
1.101 + (If the sources attached to a DOM element change, the `Debugger.Source`
1.102 + instances representing superceded code still refer to the DOM element;
1.103 + this accessor only reflects origins, not current relationships.)
1.104 +
1.105 +`elementAttributeName`
1.106 +: If this source belongs to a DOM element because it is an event handler
1.107 + content attribute or an event handler IDL attribute, this is the name of
1.108 + that attribute, a string. Otherwise, this is `undefined`.
1.109 +
1.110 +`introductionType`
1.111 +: A string indicating how this source code was introduced into the system.
1.112 + This accessor returns one of the following values:
1.113 +
1.114 + * `"eval"`, for code passed to `eval`.
1.115 +
1.116 + * `"Function"`, for code passed to the `Function` constructor.
1.117 +
1.118 + * `"Worker"`, for code loaded by calling the Web worker constructor—the
1.119 + worker's main script.
1.120 +
1.121 + * `"importScripts"`, for code by calling `importScripts` in a web worker.
1.122 +
1.123 + * `"eventHandler"`, for code assigned to DOM elements' event handler IDL
1.124 + attributes as a string.
1.125 +
1.126 + * `"scriptElement"`, for code belonging to `<script>` elements.
1.127 +
1.128 + * `"javascriptURL"`, for code presented in `javascript:` URLs.
1.129 +
1.130 + * `"setTimeout"`, for code passed to `setTimeout` as a string.
1.131 +
1.132 + * `"setInterval"`, for code passed to `setInterval` as a string.
1.133 +
1.134 + * `undefined`, if the implementation doesn't know how the code was
1.135 + introduced.
1.136 +
1.137 +`introductionScript`, `introductionScriptOffset` <i>(future plan)</i>
1.138 +: If this source was introduced by calling a function from debuggee code,
1.139 + then `introductionScript` is the [`Debugger.Script`][script] instance referring to
1.140 + the script containing that call, and `introductionScriptOffset` is the
1.141 + call's bytecode offset within that script. Otherwise, these are both
1.142 + `undefined`. Taken together, these properties indicate the location of
1.143 + the introducing call.
1.144 +
1.145 + For the purposes of these accessors, assignments to accessor properties
1.146 + are treated as function calls. Thus, setting a DOM element's event
1.147 + handler IDL attribute by assigning to the corresponding JavaScript
1.148 + property creates a source whose `introductionScript` and
1.149 + `introductionScriptOffset` refer to the property assignment.
1.150 +
1.151 + Since a `<script>` element parsed from a web page's original HTML
1.152 + was not introduced by any scripted call, its source's
1.153 + `introductionScript` and `introductionScriptOffset` accessors both
1.154 + return `undefined`.
1.155 +
1.156 + If a `<script>` element was dynamically inserted into a document,
1.157 + then these accessors refer to the call that actually caused the script
1.158 + to run—usually the call that made the element part of the document.
1.159 + Thus, they do <i>not</i> refer to the call that created the element;
1.160 + stored the source as the element's text child; made the element a child
1.161 + of some uninserted parent node that was later inserted; or the like.
1.162 +
1.163 + Although the main script of a worker thread is introduced by a call to
1.164 + `Worker` or `SharedWorker`, these accessors always return `undefined` on
1.165 + such script's sources. A worker's main script source and the call that
1.166 + created the worker are always in separate threads, but [`Debugger`][debugger-object] is an
1.167 + inherently single-threaded facility: its debuggees must all run in the
1.168 + same thread. Since the global that created the worker is in a different
1.169 + thread, it is guaranteed not to be a debuggee of the [`Debugger`][debugger-object] instance
1.170 + that owns this source; and thus the creating call is never "in debuggee
1.171 + code". Relating a worker to its creator, and other multi-threaded
1.172 + debugging concerns, are out of scope for [`Debugger`][debugger-object].
1.173 +
1.174 +
1.175 +
1.176 +## Function Properties of the Debugger.Source Prototype Object
1.177 +
1.178 +<code>substring(<i>start</i>, [<i>end</i>])</code> <i>(future plan)</i>
1.179 +: Return a substring of this instance's `source` property, starting at
1.180 + <i>start</i> and extending to, but not including, <i>end</i>. If
1.181 + <i>end</i> is `undefined`, the substring returned extends to the end of
1.182 + the source.
1.183 +
1.184 + Both indices are zero-based. If either is `NaN` or negative, it is
1.185 + replaced with zero. If either is greater than the length of the source,
1.186 + it is replaced with the length of the source. If <i>start</i> is larger
1.187 + than <i>end</i>, they are swapped. (This is meant to be consistent with
1.188 + the way `String.prototype.substring` interprets its arguments.)
1.189 +
1.190 +<code>lineToPosition(<i>line</i>)</code> <i>(future plan)</i>
1.191 +: Return an object of the form
1.192 + <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
1.193 + <i>start</i> is the character index within `source` of the first
1.194 + character of line number <i>line</i>, and <i>length</i> is the length of
1.195 + that line in characters, including the final newline, if any. The first
1.196 + line is numbered one. If <i>line</i> is negative or greater than the
1.197 + number of lines in this `Debugger.Source` instance, then return `null`.
1.198 +
1.199 +<code>positionToLine(<i>start</i>)</code> <i>(future plan)</i>
1.200 +: Return an object of the form
1.201 + <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
1.202 + <i>line</i> is the line number containing the character position
1.203 + <i>start</i>, and <i>length</i> is the length of that line in
1.204 + characters, including the final newline, if any. The first line is
1.205 + numbered one. If <i>start</i> is negative or greater than the length of
1.206 + the source code, then return `null`.
1.207 +
1.208 +<code>findScripts(<i>query</i>)</code> <i>(future plan)</i>
1.209 +: Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
1.210 + matching <i>query</i> that are produced from this `Debugger.Source`
1.211 + instance. Aside from the restriction to scripts produced from this
1.212 + source, <i>query</i> is interpreted as for
1.213 + `Debugger.prototype.findScripts`.
1.214 +
1.215 +
