michael@0: # Debugger.Source
michael@0: 
michael@0: A `Debugger.Source` instance represents a piece of JavaScript source
michael@0: code: its properties provide the source code itself as a string, and
michael@0: describe where it came from. Each [`Debugger.Script`][script] instance refers to
michael@0: the `Debugger.Source` instance holding the source code from which it was
michael@0: produced.
michael@0: 
michael@0: If a single piece of source code contains both top-level code and
michael@0: function definitions, perhaps with nested functions, then the
michael@0: [`Debugger.Script`][script] instances for those all refer to the same
michael@0: `Debugger.Source` instance. Each script indicates the substring of the
michael@0: overall source to which it corresponds.
michael@0: 
michael@0: A `Debugger.Source` instance may represent only a portion of a larger
michael@0: source document. For example, an HTML document can contain JavaScript in
michael@0: multiple `<script>` elements and event handler content attributes.
michael@0: In this case, there may be either a single `Debugger.Source` instance
michael@0: for the entire HTML document, with each [`Debugger.Script`][script] referring to
michael@0: its substring of the document; or there may be a separate
michael@0: `Debugger.Source` instance for each `<script>` element and
michael@0: attribute. The choice is left up to the implementation.
michael@0: 
michael@0: If a given piece of source code is presented to the JavaScript
michael@0: implementation more than once, with the same origin metadata, the
michael@0: JavaScript implementation may generate a fresh `Debugger.Source`
michael@0: instance to represent each presentation, or it may use a single
michael@0: `Debugger.Source` instance to represent them all.
michael@0: 
michael@0: Each [`Debugger`][debugger-object] instance has a separate collection of `Debugger.Source`
michael@0: instances representing the source code that has been presented to the
michael@0: system.
michael@0: 
michael@0: A debugger may place its own properties on `Debugger.Source` instances,
michael@0: to store metadata about particular pieces of source code.
michael@0: 
michael@0: 
michael@0: ## Accessor Properties of the Debugger.Source Prototype Object
michael@0: 
michael@0: A `Debugger.Source` instance inherits the following accessor properties
michael@0: from its prototype:
michael@0: 
michael@0: `text`
michael@0: :   The JavaScript source code, as a string. The value satisfies the
michael@0:     `Program`, `FunctionDeclaration`, or `FunctionExpression` productions in
michael@0:     the ECMAScript standard.
michael@0: 
michael@0: `enclosingStart` <i>(future plan)</i>
michael@0: :   The position within the enclosing document at which this source's text
michael@0:     starts. This is a zero-based character offset. (The length of this
michael@0:     script within the enclosing document is `source.length`.)
michael@0: 
michael@0: `lineCount` <i>(future plan)</i>
michael@0: :   The number of lines in the source code. If there are characters after
michael@0:     the last newline in the source code, those count as a final line;
michael@0:     otherwise, `lineCount` is equal to the number of newlines in the source
michael@0:     code.
michael@0: 
michael@0: `url`
michael@0: :   The URL from which this source was loaded, if this source was loaded
michael@0:     from a URL. Otherwise, this is `undefined`. Source may be loaded from a
michael@0:     URL in the following ways:
michael@0: 
michael@0:     * The URL may appear as the `src` attribute of a `<script>` element
michael@0:       in markup text.
michael@0: 
michael@0:     * The URL may be passed to the `Worker` web worker constructor, or the web
michael@0:       worker `importScripts` function.
michael@0: 
michael@0:     * The URL may be the name of a XPCOM JavaScript module or subscript.
michael@0: 
michael@0:     (Note that code passed to `eval`, the `Function` constructor, or a
michael@0:     similar function is <i>not</i> considered to be loaded from a URL; the
michael@0:     `url` accessor on `Debugger.Source` instances for such sources should
michael@0:     return `undefined`.)
michael@0: 
michael@0: `element`
michael@0: :   The [`Debugger.Object`][object] instance referring to the DOM element to which
michael@0:     this source code belongs, if any, or `undefined` if it belongs to no DOM
michael@0:     element. Source belongs to a DOM element in the following cases:
michael@0: 
michael@0:     * Source belongs to a `<script>` element if it is the element's text
michael@0:       content (that is, it is written out as the body of the `<script>`
michael@0:       element in the markup text), or is the source document referenced by its
michael@0:       `src` attribute.
michael@0: 
michael@0:     * Source belongs to a DOM element if it is an event handler content
michael@0:       attribute (that is, if it is written out in the markup text as an
michael@0:       attribute value).
michael@0: 
michael@0:     * Source belongs to a DOM element if it was assigned to one of the
michael@0:       element's event handler IDL attributes as a string. (Note that one may
michael@0:       assign both strings and functions to DOM elements' event handler IDL
michael@0:       attributes. If one assigns a function, that function's script's source
michael@0:       does <i>not</i> belong to the DOM element; the function's definition
michael@0:       must appear elsewhere.)
michael@0: 
michael@0:     (If the sources attached to a DOM element change, the `Debugger.Source`
michael@0:     instances representing superceded code still refer to the DOM element;
michael@0:     this accessor only reflects origins, not current relationships.)
michael@0: 
michael@0: `elementAttributeName`
michael@0: :   If this source belongs to a DOM element because it is an event handler
michael@0:     content attribute or an event handler IDL attribute, this is the name of
michael@0:     that attribute, a string. Otherwise, this is `undefined`.
michael@0: 
michael@0: `introductionType`
michael@0: :   A string indicating how this source code was introduced into the system.
michael@0:     This accessor returns one of the following values:
michael@0: 
michael@0:     * `"eval"`, for code passed to `eval`.
michael@0: 
michael@0:     * `"Function"`, for code passed to the `Function` constructor.
michael@0: 
michael@0:     * `"Worker"`, for code loaded by calling the Web worker constructor—the
michael@0:       worker's main script.
michael@0: 
michael@0:     * `"importScripts"`, for code by calling `importScripts` in a web worker.
michael@0: 
michael@0:     * `"eventHandler"`, for code assigned to DOM elements' event handler IDL
michael@0:       attributes as a string.
michael@0: 
michael@0:     * `"scriptElement"`, for code belonging to `<script>` elements.
michael@0: 
michael@0:     * `"javascriptURL"`, for code presented in `javascript:` URLs.
michael@0: 
michael@0:     * `"setTimeout"`, for code passed to `setTimeout` as a string.
michael@0: 
michael@0:     * `"setInterval"`, for code passed to `setInterval` as a string.
michael@0: 
michael@0:     * `undefined`, if the implementation doesn't know how the code was
michael@0:       introduced.
michael@0: 
michael@0: `introductionScript`, `introductionScriptOffset` <i>(future plan)</i>
michael@0: :   If this source was introduced by calling a function from debuggee code,
michael@0:     then `introductionScript` is the [`Debugger.Script`][script] instance referring to
michael@0:     the script containing that call, and `introductionScriptOffset` is the
michael@0:     call's bytecode offset within that script. Otherwise, these are both
michael@0:     `undefined`. Taken together, these properties indicate the location of
michael@0:     the introducing call.
michael@0: 
michael@0:     For the purposes of these accessors, assignments to accessor properties
michael@0:     are treated as function calls. Thus, setting a DOM element's event
michael@0:     handler IDL attribute by assigning to the corresponding JavaScript
michael@0:     property creates a source whose `introductionScript` and
michael@0:     `introductionScriptOffset` refer to the property assignment.
michael@0: 
michael@0:     Since a `<script>` element parsed from a web page's original HTML
michael@0:     was not introduced by any scripted call, its source's
michael@0:     `introductionScript` and `introductionScriptOffset` accessors both
michael@0:     return `undefined`.
michael@0: 
michael@0:     If a `<script>` element was dynamically inserted into a document,
michael@0:     then these accessors refer to the call that actually caused the script
michael@0:     to run—usually the call that made the element part of the document.
michael@0:     Thus, they do <i>not</i> refer to the call that created the element;
michael@0:     stored the source as the element's text child; made the element a child
michael@0:     of some uninserted parent node that was later inserted; or the like.
michael@0: 
michael@0:     Although the main script of a worker thread is introduced by a call to
michael@0:     `Worker` or `SharedWorker`, these accessors always return `undefined` on
michael@0:     such script's sources. A worker's main script source and the call that
michael@0:     created the worker are always in separate threads, but [`Debugger`][debugger-object] is an
michael@0:     inherently single-threaded facility: its debuggees must all run in the
michael@0:     same thread. Since the global that created the worker is in a different
michael@0:     thread, it is guaranteed not to be a debuggee of the [`Debugger`][debugger-object] instance
michael@0:     that owns this source; and thus the creating call is never "in debuggee
michael@0:     code". Relating a worker to its creator, and other multi-threaded
michael@0:     debugging concerns, are out of scope for [`Debugger`][debugger-object].
michael@0: 
michael@0: 
michael@0: 
michael@0: ## Function Properties of the Debugger.Source Prototype Object
michael@0: 
michael@0: <code>substring(<i>start</i>, [<i>end</i>])</code> <i>(future plan)</i>
michael@0: :   Return a substring of this instance's `source` property, starting at
michael@0:     <i>start</i> and extending to, but not including, <i>end</i>. If
michael@0:     <i>end</i> is `undefined`, the substring returned extends to the end of
michael@0:     the source.
michael@0: 
michael@0:     Both indices are zero-based. If either is `NaN` or negative, it is
michael@0:     replaced with zero. If either is greater than the length of the source,
michael@0:     it is replaced with the length of the source. If <i>start</i> is larger
michael@0:     than <i>end</i>, they are swapped. (This is meant to be consistent with
michael@0:     the way `String.prototype.substring` interprets its arguments.)
michael@0: 
michael@0: <code>lineToPosition(<i>line</i>)</code> <i>(future plan)</i>
michael@0: :   Return an object of the form
michael@0:     <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
michael@0:     <i>start</i> is the character index within `source` of the first
michael@0:     character of line number <i>line</i>, and <i>length</i> is the length of
michael@0:     that line in characters, including the final newline, if any. The first
michael@0:     line is numbered one. If <i>line</i> is negative or greater than the
michael@0:     number of lines in this `Debugger.Source` instance, then return `null`.
michael@0: 
michael@0: <code>positionToLine(<i>start</i>)</code> <i>(future plan)</i>
michael@0: :   Return an object of the form
michael@0:     <code>{ line:<i>line</i>, start:<i>start</i>, length:<i>length</i> }</code>, where
michael@0:     <i>line</i> is the line number containing the character position
michael@0:     <i>start</i>, and <i>length</i> is the length of that line in
michael@0:     characters, including the final newline, if any. The first line is
michael@0:     numbered one. If <i>start</i> is negative or greater than the length of
michael@0:     the source code, then return `null`.
michael@0: 
michael@0: <code>findScripts(<i>query</i>)</code> <i>(future plan)</i>
michael@0: :   Return an array of [`Debugger.Script`][script] instances for all debuggee scripts
michael@0:     matching <i>query</i> that are produced from this `Debugger.Source`
michael@0:     instance. Aside from the restriction to scripts produced from this
michael@0:     source, <i>query</i> is interpreted as for
michael@0:     `Debugger.prototype.findScripts`.
michael@0: 
michael@0: