summaryrefslogtreecommitdiffstats
path: root/js/src/doc/Debugger/Debugger.Source.md
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /js/src/doc/Debugger/Debugger.Source.md
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'js/src/doc/Debugger/Debugger.Source.md')
-rw-r--r--js/src/doc/Debugger/Debugger.Source.md220
1 files changed, 220 insertions, 0 deletions
diff --git a/js/src/doc/Debugger/Debugger.Source.md b/js/src/doc/Debugger/Debugger.Source.md
new file mode 100644
index 000000000..6a5535b74
--- /dev/null
+++ b/js/src/doc/Debugger/Debugger.Source.md
@@ -0,0 +1,220 @@
+# Debugger.Source
+
+A `Debugger.Source` instance represents either a piece of JavaScript source
+code or the serialized text of a block of WebAssembly code. The two cases are
+distinguished by the latter having its `introductionType` property always
+being `"wasm"` and the former having its `introductionType` property never
+being `"wasm"`.
+
+Each [`Debugger`][debugger-object] instance has a separate collection of
+`Debugger.Source` instances representing the source code that has been
+presented to the system.
+
+A debugger may place its own properties on `Debugger.Source` instances,
+to store metadata about particular pieces of source code.
+
+## Debugger.Source for JavaScript
+
+For a `Debugger.Source` instance representing a piece of JavaScript source
+code, its properties provide the source code itself as a string, and describe
+where it came from. Each [`Debugger.Script`][script] instance refers to the
+`Debugger.Source` instance holding the source code from which it was produced.
+
+If a single piece of source code contains both top-level code and
+function definitions, perhaps with nested functions, then the
+[`Debugger.Script`][script] instances for those all refer to the same
+`Debugger.Source` instance. Each script indicates the substring of the
+overall source to which it corresponds.
+
+A `Debugger.Source` instance may represent only a portion of a larger
+source document. For example, an HTML document can contain JavaScript in
+multiple `<script>` elements and event handler content attributes.
+In this case, there may be either a single `Debugger.Source` instance
+for the entire HTML document, with each [`Debugger.Script`][script] referring to
+its substring of the document; or there may be a separate
+`Debugger.Source` instance for each `<script>` element and
+attribute. The choice is left up to the implementation.
+
+If a given piece of source code is presented to the JavaScript
+implementation more than once, with the same origin metadata, the
+JavaScript implementation may generate a fresh `Debugger.Source`
+instance to represent each presentation, or it may use a single
+`Debugger.Source` instance to represent them all.
+
+## Debugger.Source for WebAssembly
+
+For a `Debugger.Source` instance representing the serialized text of a block
+of WebAssembly code, its properties provide the serialized text as a string.
+
+Currently only entire modules evaluated via `new WebAssembly.Module` are
+represented. SpiderMonkey constructs exactly one `Debugger.Source` for each
+underlying WebAssembly module per [`Debugger`][debugger-object] instance.
+
+Please note at the time of this writing, support for WebAssembly is very
+preliminary. Many properties below return placeholder values.
+
+## Convention
+
+For descriptions of properties and methods below, if the behavior of the
+property or method differs between the instance referring to JavaScript source
+or to a block of WebAssembly code, the text will be split into two sections,
+headed by "**if the instance refers to JavaScript source**" 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.Source Prototype Object
+
+A `Debugger.Source` instance inherits the following accessor properties
+from its prototype:
+
+`text`
+: **If the instance refers to JavaScript source**, the JavaScript source
+ code, as a string. The value satisfies the `Program`,
+ `FunctionDeclaration`, or `FunctionExpression` productions in the
+ ECMAScript standard.
+
+ **If the instance refers to WebAssembly code**, the serialized text
+ representation. The format is yet to be specified in the WebAssembly
+ standard. Currently, the text is an s-expression based syntax.
+
+`url`
+: **If the instance refers to JavaScript source**, the URL from which this
+ source was loaded, if this source was loaded from a URL. Otherwise, this
+ is `undefined`. Source may be loaded from a URL in the following ways:
+
+ * The URL may appear as the `src` attribute of a `<script>` element
+ in markup text.
+
+ * The URL may be passed to the `Worker` web worker constructor, or the web
+ worker `importScripts` function.
+
+ * The URL may be the name of a XPCOM JavaScript module or subscript.
+
+ (Note that code passed to `eval`, the `Function` constructor, or a
+ similar function is <i>not</i> considered to be loaded from a URL; the
+ `url` accessor on `Debugger.Source` instances for such sources should
+ return `undefined`.)
+
+ **If the instance refers to WebAssembly code**, the URL of the script that
+ called `new WebAssembly.Module` with the string `"> wasm"` appended.
+
+`sourceMapURL`
+: **If the instance refers to JavaScript source**, if this source was
+ produced by a minimizer or translated from some other language, and we
+ know the URL of a <b>source map</b> document relating the source positions
+ in this source to the corresponding source positions in the original
+ source, then this property's value is that URL. Otherwise, this is `null`.
+
+ (On the web, the translator may provide the source map URL in a
+ specially formatted comment in the JavaScript source code, or via a
+ header in the HTTP reply that carried the generated JavaScript.)
+
+ This property is writable, so you can change the source map URL by
+ setting it. All Debugger.Source objects referencing the same
+ source will see the change. Setting an empty string has no affect
+ and will not change existing value.
+
+ **If the instance refers to WebAssembly code**, `null`. Attempts to write
+ to this property throw a `TypeError`.
+
+`element`
+: The [`Debugger.Object`][object] instance referring to the DOM element to which
+ this source code belongs, if any, or `undefined` if it belongs to no DOM
+ element. Source belongs to a DOM element in the following cases:
+
+ * Source belongs to a `<script>` element if it is the element's text
+ content (that is, it is written out as the body of the `<script>`
+ element in the markup text), or is the source document referenced by its
+ `src` attribute.
+
+ * Source belongs to a DOM element if it is an event handler content
+ attribute (that is, if it is written out in the markup text as an
+ attribute value).
+
+ * Source belongs to a DOM element if it was assigned to one of the
+ element's event handler IDL attributes as a string. (Note that one may
+ assign both strings and functions to DOM elements' event handler IDL
+ attributes. If one assigns a function, that function's script's source
+ does <i>not</i> belong to the DOM element; the function's definition
+ must appear elsewhere.)
+
+ (If the sources attached to a DOM element change, the `Debugger.Source`
+ instances representing superceded code still refer to the DOM element;
+ this accessor only reflects origins, not current relationships.)
+
+`elementAttributeName`
+: If this source belongs to a DOM element because it is an event handler
+ content attribute or an event handler IDL attribute, this is the name of
+ that attribute, a string. Otherwise, this is `undefined`.
+
+`introductionType`
+: **If the instance refers to JavaScript source**, a string indicating how
+ this source code was introduced into the system. This accessor returns
+ one of the following values:
+
+ * `"eval"`, for code passed to `eval`.
+
+ * `"Function"`, for code passed to the `Function` constructor.
+
+ * `"Worker"`, for code loaded by calling the Web worker constructor—the
+ worker's main script.
+
+ * `"importScripts"`, for code by calling `importScripts` in a web worker.
+
+ * `"eventHandler"`, for code assigned to DOM elements' event handler IDL
+ attributes as a string.
+
+ * `"scriptElement"`, for code belonging to `<script>` elements.
+
+ * `"javascriptURL"`, for code presented in `javascript:` URLs.
+
+ * `"setTimeout"`, for code passed to `setTimeout` as a string.
+
+ * `"setInterval"`, for code passed to `setInterval` as a string.
+
+ * `undefined`, if the implementation doesn't know how the code was
+ introduced.
+
+ **If the instance refers to WebAssembly code**, `"wasm"`.
+
+`introductionScript`, `introductionOffset`
+: **If the instance refers to JavaScript source**, and if this source was
+ introduced by calling a function from debuggee code, then
+ `introductionScript` is the [`Debugger.Script`][script] instance referring
+ to the script containing that call, and `introductionOffset` is the call's
+ bytecode offset within that script. Otherwise, these are both `undefined`.
+ Taken together, these properties indicate the location of the introducing
+ call.
+
+ For the purposes of these accessors, assignments to accessor properties are
+ treated as function calls. Thus, setting a DOM element's event handler IDL
+ attribute by assigning to the corresponding JavaScript property creates a
+ source whose `introductionScript` and `introductionOffset` refer to the
+ property assignment.
+
+ Since a `<script>` element parsed from a web page's original HTML was not
+ introduced by any scripted call, its source's `introductionScript` and
+ `introductionOffset` accessors both return `undefined`.
+
+ If a `<script>` element was dynamically inserted into a document, then these
+ accessors refer to the call that actually caused the script to run—usually
+ the call that made the element part of the document. Thus, they do
+ <i>not</i> refer to the call that created the element; stored the source as
+ the element's text child; made the element a child of some uninserted parent
+ node that was later inserted; or the like.
+
+ Although the main script of a worker thread is introduced by a call to
+ `Worker` or `SharedWorker`, these accessors always return `undefined` on
+ such script's sources. A worker's main script source and the call that
+ created the worker are always in separate threads, but
+ [`Debugger`][debugger-object] is an inherently single-threaded facility: its
+ debuggees must all run in the same thread. Since the global that created the
+ worker is in a different thread, it is guaranteed not to be a debuggee of
+ the [`Debugger`][debugger-object] instance that owns this source; and thus
+ the creating call is never "in debuggee code". Relating a worker to its
+ creator, and other multi-threaded debugging concerns, are out of scope for
+ [`Debugger`][debugger-object].
+
+ **If the instance refers to WebAssembly code**, `introductionScript` is
+ the [`Debugger.Script`][script] instance referring to the same underlying
+ WebAssembly module. `introductionOffset` is `undefined`.