The Tor Browser / file comparison

comparison: js/src/doc/Debugger/Debugger.Source.md

js/src/doc/Debugger/Debugger.Source.md

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:d67c12576eed
1 # Debugger.Source
2
3 A `Debugger.Source` instance represents a piece of JavaScript source
4 code: its properties provide the source code itself as a string, and
5 describe where it came from. Each [`Debugger.Script`][script] instance refers to
6 the `Debugger.Source` instance holding the source code from which it was
7 produced.
8
9 If a single piece of source code contains both top-level code and
10 function definitions, perhaps with nested functions, then the
11 [`Debugger.Script`][script] instances for those all refer to the same
12 `Debugger.Source` instance. Each script indicates the substring of the
13 overall source to which it corresponds.
14
15 A `Debugger.Source` instance may represent only a portion of a larger
16 source document. For example, an HTML document can contain JavaScript in
17 multiple `<script>` elements and event handler content attributes.
18 In this case, there may be either a single `Debugger.Source` instance
19 for the entire HTML document, with each [`Debugger.Script`][script] referring to
20 its substring of the document; or there may be a separate
21 `Debugger.Source` instance for each `<script>` element and
22 attribute. The choice is left up to the implementation.
23
24 If a given piece of source code is presented to the JavaScript
25 implementation more than once, with the same origin metadata, the
26 JavaScript implementation may generate a fresh `Debugger.Source`
27 instance to represent each presentation, or it may use a single
28 `Debugger.Source` instance to represent them all.
29
30 Each [`Debugger`][debugger-object] instance has a separate collection of `Debugger.Source`
31 instances representing the source code that has been presented to the
32 system.
33
34 A debugger may place its own properties on `Debugger.Source` instances,
35 to store metadata about particular pieces of source code.
36
37
38 ## Accessor Properties of the Debugger.Source Prototype Object
39
40 A `Debugger.Source` instance inherits the following accessor properties
41 from its prototype:
42
43 `text`
44 : The JavaScript source code, as a string. The value satisfies the
45 `Program`, `FunctionDeclaration`, or `FunctionExpression` productions in
46 the ECMAScript standard.
47
48 `enclosingStart` <i>(future plan)</i>
49 : The position within the enclosing document at which this source's text
50 starts. This is a zero-based character offset. (The length of this
51 script within the enclosing document is `source.length`.)
52
53 `lineCount` <i>(future plan)</i>
54 : The number of lines in the source code. If there are characters after
55 the last newline in the source code, those count as a final line;
56 otherwise, `lineCount` is equal to the number of newlines in the source
57 code.
58
59 `url`
60 : The URL from which this source was loaded, if this source was loaded
61 from a URL. Otherwise, this is `undefined`. Source may be loaded from a
62 URL in the following ways:
63
64 * The URL may appear as the `src` attribute of a `<script>` element
65 in markup text.
66
67 * The URL may be passed to the `Worker` web worker constructor, or the web
68 worker `importScripts` function.
69
70 * The URL may be the name of a XPCOM JavaScript module or subscript.
71
72 (Note that code passed to `eval`, the `Function` constructor, or a
73 similar function is <i>not</i> considered to be loaded from a URL; the
74 `url` accessor on `Debugger.Source` instances for such sources should
75 return `undefined`.)
76
77 `element`
78 : The [`Debugger.Object`][object] instance referring to the DOM element to which
79 this source code belongs, if any, or `undefined` if it belongs to no DOM
80 element. Source belongs to a DOM element in the following cases:
81
82 * Source belongs to a `<script>` element if it is the element's text
83 content (that is, it is written out as the body of the `<script>`
84 element in the markup text), or is the source document referenced by its
85 `src` attribute.
86
87 * Source belongs to a DOM element if it is an event handler content
88 attribute (that is, if it is written out in the markup text as an
89 attribute value).
90
91 * Source belongs to a DOM element if it was assigned to one of the
92 element's event handler IDL attributes as a string. (Note that one may
93 assign both strings and functions to DOM elements' event handler IDL
94 attributes. If one assigns a function, that function's script's source
95 does <i>not</i> belong to the DOM element; the function's definition
96 must appear elsewhere.)
97
98 (If the sources attached to a DOM element change, the `Debugger.Source`
99 instances representing superceded code still refer to the DOM element;
100 this accessor only reflects origins, not current relationships.)
101
102 `elementAttributeName`
103 : If this source belongs to a DOM element because it is an event handler
104 content attribute or an event handler IDL attribute, this is the name of
105 that attribute, a string. Otherwise, this is `undefined`.
106
107 `introductionType`
108 : A string indicating how this source code was introduced into the system.
109 This accessor returns one of the following values:
110
111 * `"eval"`, for code passed to `eval`.
112
113 * `"Function"`, for code passed to the `Function` constructor.
114
115 * `"Worker"`, for code loaded by calling the Web worker constructor—the
116 worker's main script.
117
118 * `"importScripts"`, for code by calling `importScripts` in a web worker.
119
120 * `"eventHandler"`, for code assigned to DOM elements' event handler IDL
121 attributes as a string.
122
123 * `"scriptElement"`, for code belonging to `<script>` elements.
124
125 * `"javascriptURL"`, for code presented in `javascript:` URLs.
126
127 * `"setTimeout"`, for code passed to `setTimeout` as a string.
128
129 * `"setInterval"`, for code passed to `setInterval` as a string.
130
131 * `undefined`, if the implementation doesn't know how the code was
132 introduced.
133
134 `introductionScript`, `introductionScriptOffset` <i>(future plan)</i>
135 : If this source was introduced by calling a function from debuggee code,
136 then `introductionScript` is the [`Debugger.Script`][script] instance referring to
137 the script containing that call, and `introductionScriptOffset` is the
138 call's bytecode offset within that script. Otherwise, these are both
139 `undefined`. Taken together, these properties indicate the location of
140 the introducing call.
141
142 For the purposes of these accessors, assignments to accessor properties
143 are treated as function calls. Thus, setting a DOM element's event
144 handler IDL attribute by assigning to the corresponding JavaScript
145 property creates a source whose `introductionScript` and
146 `introductionScriptOffset` refer to the property assignment.
147
148 Since a `<script>` element parsed from a web page's original HTML
149 was not introduced by any scripted call, its source's
150 `introductionScript` and `introductionScriptOffset` accessors both
151 return `undefined`.
152
153 If a `<script>` element was dynamically inserted into a document,
154 then these accessors refer to the call that actually caused the script
155 to run—usually the call that made the element part of the document.
156 Thus, they do <i>not</i> refer to the call that created the element;
157 stored the source as the element's text child; made the element a child
158 of some uninserted parent node that was later inserted; or the like.
159
160 Although the main script of a worker thread is introduced by a call to
161 `Worker` or `SharedWorker`, these accessors always return `undefined` on
162 such script's sources. A worker's main script source and the call that
163 created the worker are always in separate threads, but [`Debugger`][debugger-object] is an
164 inherently single-threaded facility: its debuggees must all run in the
165 same thread. Since the global that created the worker is in a different
166 thread, it is guaranteed not to be a debuggee of the [`Debugger`][debugger-object] instance
167 that owns this source; and thus the creating call is never "in debuggee
168 code". Relating a worker to its creator, and other multi-threaded
169 debugging concerns, are out of scope for [`Debugger`][debugger-object].
170
171
172
173 ## Function Properties of the Debugger.Source Prototype Object
174
175 <code>substring(<i>start</i>, [<i>end</i>])</code> <i>(future plan)</i>
176 : Return a substring of this instance's `source` property, starting at
177 <i>start</i> and extending to, but not including, <i>end</i>. If
178 <i>end</i> is `undefined`, the substring returned extends to the end of
179 the source.
180
181 Both indices are zero-based. If either is `NaN` or negative, it is
182 replaced with zero. If either is greater than the length of the source,
183 it is replaced with the length of the source. If <i>start</i> is larger
184 than <i>end</i>, they are swapped. (This is meant to be consistent with
185 the way `String.prototype.substring` interprets its arguments.)
186
187 <code>lineToPosition(<i>line</i>)</code> <i>(future plan)</i>
188 : Return an object of the form
189 <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
190 <i>start</i> is the character index within `source` of the first
191 character of line number <i>line</i>, and <i>length</i> is the length of
192 that line in characters, including the final newline, if any. The first
193 line is numbered one. If <i>line</i> is negative or greater than the
194 number of lines in this `Debugger.Source` instance, then return `null`.
195
196 <code>positionToLine(<i>start</i>)</code> <i>(future plan)</i>
197 : Return an object of the form
198 <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
199 <i>line</i> is the line number containing the character position
200 <i>start</i>, and <i>length</i> is the length of that line in
201 characters, including the final newline, if any. The first line is
202 numbered one. If <i>start</i> is negative or greater than the length of
203 the source code, then return `null`.
204
205 <code>findScripts(<i>query</i>)</code> <i>(future plan)</i>
206 : Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
207 matching <i>query</i> that are produced from this `Debugger.Source`
208 instance. Aside from the restriction to scripts produced from this
209 source, <i>query</i> is interpreted as for
210 `Debugger.prototype.findScripts`.
211
212

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial