Debugger - Revision history

Jimb: Replace with a link to the new MDN page.

2014-04-16T04:40:21Z

Replace with a link to the new MDN page.

Jimb: [master 66aefea] Document more values for D.S.p.introductionType.

2014-02-24T23:36:16Z

[master 66aefea] Document more values for D.S.p.introductionType.

← Older revision		Revision as of 23:36, 24 February 2014
Line 1,056:		Line 1,056:
	<li><code>"Worker"</code>, for code loaded by calling the Web worker constructor—the worker's main script.		<li><code>"Worker"</code>, for code loaded by calling the Web worker constructor—the worker's main script.
	<li><code>"importScripts"</code>, for code by calling <code>importScripts</code> in a web worker.		<li><code>"importScripts"</code>, for code by calling <code>importScripts</code> in a web worker.
	<li><code>"~~handler~~"</code>, for code assigned to DOM elements' event handler IDL attributes.		<li><code>"eventHandler"</code>, for code assigned to DOM elements' event handler IDL attributes as a string.
	<li><code>"scriptElement"</code>, for code belonging to <code><script></code> elements.		<li><code>"scriptElement"</code>, for code belonging to <code><script></code> elements.
			<li><code>"javascriptURL"</code>, for code presented in <code>javascript:</code> URLs.
			<li><code>"setTimeout"</code>, for code passed to <code>setTimeout</code> as a string.
			<li><code>"setInterval"</code>, for code passed to <code>setInterval</code> as a string.
	<li><code>undefined</code>, if the implementation doesn't know how the code was introduced.		<li><code>undefined</code>, if the implementation doesn't know how the code was introduced.
	</ul>		</ul>

Jimb: [master 83ed526] Document 'lineNumber' option to D.F.p.eval.

2014-02-12T00:28:10Z

[master 83ed526] Document 'lineNumber' option to D.F.p.eval.

← Older revision		Revision as of 00:28, 12 February 2014
Line 462:		Line 462:
	<dt>url		<dt>url
	<dd>The filename or URL to which we should attribute <i>code</i>. If this property is omitted, the URL defaults to <code>"debugger eval code"</code>.		<dd>The filename or URL to which we should attribute <i>code</i>. If this property is omitted, the URL defaults to <code>"debugger eval code"</code>.
			<dt>lineNumber
			<dd>The line number at which the evaluated code should be claimed to begin within <i>url</i>.
	</dl>		</dl>

Jimb: [master 103cb46] Rename to D.E.p.elementAttributeName; it and D.E.p.element are implemented now.

2014-01-23T01:01:10Z

[master 103cb46] Rename to D.E.p.elementAttributeName; it and D.E.p.element are implemented now.

← Older revision		Revision as of 01:01, 23 January 2014
Line 1,034:		Line 1,034:
	(Note that code passed to <code>eval</code>, the <code>Function</code> constructor, or a similar function is <i>not</i> considered to be loaded from a URL; the <code>url</code> accessor on <code>Debugger.Source</code> instances for such sources should return <code>undefined</code>.)		(Note that code passed to <code>eval</code>, the <code>Function</code> constructor, or a similar function is <i>not</i> considered to be loaded from a URL; the <code>url</code> accessor on <code>Debugger.Source</code> instances for such sources should return <code>undefined</code>.)

	<dt>element ~~<i>(not yet implemented)</i>~~		<dt>element
	<dd>The <code>Debugger.Object</code> instance referring to the DOM element to which this source code belongs, if any, or <code>undefined</code> if it belongs to no DOM element. Source belongs to a DOM element in the following cases:		<dd>The <code>Debugger.Object</code> instance referring to the DOM element to which this source code belongs, if any, or <code>undefined</code> if it belongs to no DOM element. Source belongs to a DOM element in the following cases:
	<ul>		<ul>
Line 1,044:		Line 1,044:
	(If the sources attached to a DOM element change, the <code>Debugger.Source</code> instances representing superceded code still refer to the DOM element; this accessor only reflects origins, not current relationships.)		(If the sources attached to a DOM element change, the <code>Debugger.Source</code> instances representing superceded code still refer to the DOM element; this accessor only reflects origins, not current relationships.)

	<dt>~~elementProperty <i>(not yet implemented)</i>~~		<dt>elementAttributeName
	<dd>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 <code>undefined</code>.		<dd>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 <code>undefined</code>.

Jimb: [master ed515ef] Rework source introduction metadata; add access for script's global.

2014-01-11T00:48:56Z

[master ed515ef] Rework source introduction metadata; add access for script's global.

← Older revision		Revision as of 00:48, 11 January 2014
Line 553:		Line 553:
	<dt>sourceLength		<dt>sourceLength
	<dd>The length, in characters, of this script's code within the <code>Debugger.Source</code> instance given by <code>source</code>.		<dd>The length, in characters, of this script's code within the <code>Debugger.Source</code> instance given by <code>source</code>.

			<dt>global
			<dd>A <code>Debugger.Object</code> instance referring to the global object in whose scope this script runs. The result refers to the global directly, not via a wrapper or a <code>WindowProxy</code> ("outer window", in Firefox).

	<dt>staticLevel		<dt>staticLevel
Line 944:		Line 947:
	<dt>getVariable(<i>name</i>)		<dt>getVariable(<i>name</i>)
	<dd>Return the value of the variable bound to <i>name</i> in this environment, or <code>undefined</code> if this environment does not bind <i>name</i>. <i>Name</i> must be a string that is a valid ECMAScript identifier name. The result is a debuggee value.		<dd>Return the value of the variable bound to <i>name</i> in this environment, or <code>undefined</code> if this environment does not bind <i>name</i>. <i>Name</i> must be a string that is a valid ECMAScript identifier name. The result is a debuggee value.

			JavaScript engines often omit variables from environments, to save space and reduce execution time. If the given variable should be in scope, but <code>getVariable</code> is unable to produce its value, it returns an ordinary JavaScript object (not a <code>Debugger.Object</code> instance) whose <code>optimizedOut</code> property is <code>true</code>.

	This is not an [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function]]; if this call would cause debuggee code to run (say, because the environment is a <code>"with"</code> environment, and <i>name</i> refers to an accessor property of the <code>with</code> statement's operand), this call throws a [[#The_Debugger.DebuggeeWouldRun_Exception\|<code>Debugger.DebuggeeWouldRun</code>]] exception.		This is not an [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function]]; if this call would cause debuggee code to run (say, because the environment is a <code>"with"</code> environment, and <i>name</i> refers to an accessor property of the <code>with</code> statement's operand), this call throws a [[#The_Debugger.DebuggeeWouldRun_Exception\|<code>Debugger.DebuggeeWouldRun</code>]] exception.
Line 1,042:		Line 1,047:
	<dd>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 <code>undefined</code>.		<dd>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 <code>undefined</code>.

	<dt>~~introductionScript~~ <i>(not yet implemented)</i>		<dt>introductionType <i>(not yet implemented)</i>
	<dd>If this source was passed to an <i>introduction call</i> in debuggee code, this is the <code>Debugger.Script</code> instance referring to the script containing that call. Otherwise, this is <code>undefined</code>. (Taken together with the <code>introductionScriptOffset</code> property, one can determine the call's source and position within that source of the call.)		<dd>A string indicating how this source code was introduced into the system. This accessor returns one of the following values:

	~~An introduction call is a function call (or assignment to a setter property) that introduces new JavaScript code to~~ the system. This is one of the following:
	<ul>		<ul>
	<li>~~A call~~ to <code>eval</code>.		<li><code>"eval"</code>, for code passed to <code>eval</code>.
	<li>~~A call~~ to the <code>Function</code> constructor.		<li><code>"Function"</code>, for code passed to the <code>Function</code> constructor.
	<li>~~A call to the~~ <code>Worker</code> ~~web~~ worker constructor or the <code>importScripts</code> ~~function~~, ~~which expect~~ a ~~script URL~~.		<li><code>"Worker"</code>, for code loaded by calling the Web worker constructor—the worker's main script.
	<li>~~An assignment~~ to an event handler IDL ~~attribute of a DOM element~~.		<li><code>"importScripts"</code>, for code by calling <code>importScripts</code> in a web worker.
			<li><code>"handler"</code>, for code assigned to DOM elements' event handler IDL attributes.
			<li><code>"scriptElement"</code>, for code belonging to <code><script></code> elements.
			<li><code>undefined</code>, if the implementation doesn't know how the code was introduced.
	</ul>		</ul>

			<dt>introductionScript <i>(not yet implemented)</i>
	<dt>introductionScriptOffset <i>(not yet implemented)</i>		<dt>introductionScriptOffset <i>(not yet implemented)</i>
	<dd>If <code>introductionScript</code> is a script, ~~this~~ is the bytecode offset within that script of the ~~introduction~~ call.		<dd>If this source was introduced by calling a function from debuggee code, then <code>introductionScript</code> is the <code>Debugger.Script</code> instance referring to the script containing that call, and <code>introductionScriptOffset</code> is the call's bytecode offset within that script. Otherwise, these are both <code>undefined</code>. Taken together, these properties indicate the location of the introducing call.

	~~<dt>introductionKind <i>(not yet implemented)</i>~~		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 <code>introductionScript</code> and <code>introductionScriptOffset</code> refer to the property assignment.
	~~<dd>A string indicating what kind~~ of ~~introduction call introduced this <code>Debugger~~.~~Source</code>~~'s ~~code into~~ the ~~system. This is~~ <code>~~undefined~~</code> if <code>~~introductionScript~~</code> ~~is undefined; otherwise, it is one of~~ the ~~following strings:~~
	~~<ul>~~		Since a <code><script></code> element parsed from a web page's original HTML was not introduced by any scripted call, its source's <code>introductionScript</code> and <code>introductionScriptOffset</code> accessors both return <code>undefined</code>.
	~~<li>~~<code>~~"eval"~~</code>
	~~<li>~~<code>~~"Function"~~</code>		If a <code><script></code> 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.
	~~<li>~~<code>~~"Worker"~~</code>
	~~<li>~~<code>~~"importScripts"~~</code>
	<li><code>~~"handler"~~<~~/code~~> ~~(for DOM elements' event handler IDL attributes)~~
	</ul>

			Although the main script of a worker thread is introduced by a call to <code>Worker</code> or <code>SharedWorker</code>, these accessors always return <code>undefined</code> on such script's sources. A worker's main script source and the call that created the worker are always in separate threads, but <code>Debugger</code> 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 <code>Debugger</code> 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 <code>Debugger</code>.
	</dl>		</dl>

Jimb: [master fe5d673] Formatting tweaks for Debugger.Source merge.

2013-10-30T19:07:09Z

[master fe5d673] Formatting tweaks for Debugger.Source merge.

Show changes

Jimb: [b28913f] Merge branch 'master' of github.com:jimblandy/DebuggerDocs

2013-10-14T20:43:28Z

[b28913f] Merge branch 'master' of github.com:jimblandy/DebuggerDocs

← Older revision		Revision as of 20:43, 14 October 2013
Line 53:		Line 53:
	<ul>		<ul>
	<li>a <i>debuggee frame</i> is a frame running debuggee code;		<li>a <i>debuggee frame</i> is a frame running debuggee code;
	<li>a <i>debuggee function</i> is a function that closes over a debuggee global object (and thus the function's code is debuggee code); and		<li>a <i>debuggee function</i> is a function that closes over a debuggee global object (and thus the function's code is debuggee code);
			<li>a <i>debuggee environment</i> is an environment whose outermost enclosing environment is a debuggee global object; and
	<li>a <i>debuggee script</i> is a script containing debuggee code.		<li>a <i>debuggee script</i> is a script containing debuggee code.
	</ul>		</ul>
Line 64:		Line 65:
	<dd>The code completed normally, returning <i>value</i>. <i>Value</i> is a debuggee value.		<dd>The code completed normally, returning <i>value</i>. <i>Value</i> is a debuggee value.
	<dt>{ yield: <i>value</i> }		<dt>{ yield: <i>value</i> }
	<dd>The running code is a generator frame which has yielded <i>value</i>. <i>Value</i> is a debuggee value.		<dd><i>(Not yet implemented.)</i> The running code is a generator frame which has yielded <i>value</i>. <i>Value</i> is a debuggee value.
	<dt>{ throw: <i>value</i> }		<dt>{ throw: <i>value</i> }
	<dd>The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee value.		<dd>The code threw <i>value</i> as an exception. <i>Value</i> is a debuggee value.
Line 82:		Line 83:
	<dd>Return <i>value</i> immediately as the current value of the function. <i>Value</i> must be a debuggee value. (Most handler functions support this, except those whose descriptions say otherwise.) If the function was called as a constructor (that is, via a <code>new</code> expression), then <i>value</i> serves as the value returned by the function's body, not that produced by the <code>new</code> expression: if the value is not an object, the <code>new</code> expression returns the frame's <code>this</code> value.		<dd>Return <i>value</i> immediately as the current value of the function. <i>Value</i> must be a debuggee value. (Most handler functions support this, except those whose descriptions say otherwise.) If the function was called as a constructor (that is, via a <code>new</code> expression), then <i>value</i> serves as the value returned by the function's body, not that produced by the <code>new</code> expression: if the value is not an object, the <code>new</code> expression returns the frame's <code>this</code> value.
	<dt>{ yield: <i>value</i> }		<dt>{ yield: <i>value</i> }
	<dd>Yield <i>value</i> immediately as the next value of the current frame, which must be a generator frame. <i>Value</i> is a debuggee value. The current frame must be a generator frame that has not yet completed in some other way. You may use <code>yield</code> resumption values to substitute a new value or one already yielded by a generator, or to make a generator yield additional values.		<dd><i>(Not yet implemented.)</i> Yield <i>value</i> immediately as the next value of the current frame, which must be a generator frame. <i>Value</i> is a debuggee value. The current frame must be a generator frame that has not yet completed in some other way. You may use <code>yield</code> resumption values to substitute a new value or one already yielded by a generator, or to make a generator yield additional values.
	<dt>{ throw: <i>value</i> }		<dt>{ throw: <i>value</i> }
	<dd>Throw <i>value</i> as an execption from the current bytecode instruction. <i>Value</i> must be a debuggee value.		<dd>Throw <i>value</i> as an execption from the current bytecode instruction. <i>Value</i> must be a debuggee value.
Line 428:		Line 429:
	When SpiderMonkey calls an <code>onPop</code> handler for a frame that is throwing an exception or being terminated, and the handler returns <code>undefined</code>, then SpiderMonkey proceeds with the exception or termination. That is, an <code>undefined</code> resumption value leaves the frame's throwing and termination process undisturbed.		When SpiderMonkey calls an <code>onPop</code> handler for a frame that is throwing an exception or being terminated, and the handler returns <code>undefined</code>, then SpiderMonkey proceeds with the exception or termination. That is, an <code>undefined</code> resumption value leaves the frame's throwing and termination process undisturbed.

	When a generator frame yields a value, SpiderMonkey calls its <code>Debugger.Frame</code> instance's <code>onPop</code> handler method, if present, passing a <code>yield</code> resumption value; however, the <code>Debugger.Frame</code> instance remains live.		<i>(Not yet implemented.)</i> When a generator frame yields a value, SpiderMonkey calls its <code>Debugger.Frame</code> instance's <code>onPop</code> handler method, if present, passing a <code>yield</code> resumption value; however, the <code>Debugger.Frame</code> instance remains live.

	If multiple <code>Debugger</code> instances each have <code>Debugger.Frame</code> instances for a given stack frame with <code>onPop</code> handlers set, their handlers are run in an unspecified order. The resumption value each handler returns establishes the completion value reported to the next handler.		If multiple <code>Debugger</code> instances each have <code>Debugger.Frame</code> instances for a given stack frame with <code>onPop</code> handlers set, their handlers are run in an unspecified order. The resumption value each handler returns establishes the completion value reported to the next handler.
Line 486:		Line 487:

	=== Generator Frames ===		=== Generator Frames ===

			<i>Not all behavior described in this section has been implemented yet.</i>

	SpiderMonkey supports generator-iterator objects, which produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses <code>yield</code> produces a generator-iterator object, as does evaluating a generator expression like <code>(i*i for each (i in [1,2,3]))</code>.		SpiderMonkey supports generator-iterator objects, which produce a series of values by repeatedly suspending the execution of a function or expression. For example, calling a function that uses <code>yield</code> produces a generator-iterator object, as does evaluating a generator expression like <code>(i*i for each (i in [1,2,3]))</code>.
Line 685:		Line 688:

	<dt>parameterNames		<dt>parameterNames
	<dd>If the referent is a function, the names of the its parameters, as an array of strings. If the referent is not a function at all, this is <code>undefined</code>.		<dd>If the referent is a debuggee function, the names of the its parameters, as an array of strings. If the referent is not a debuggee function, or not a function at all, this is <code>undefined</code>.

	If the referent is a host function for which parameter names are not available, return an array with one element per parameter, each of which is <code>undefined</code>.		If the referent is a host function for which parameter names are not available, return an array with one element per parameter, each of which is <code>undefined</code>.
Line 885:		Line 888:

	(If more than one <code>Debugger</code> instance is debugging the same code, each <code>Debugger</code> gets a separate <code>Debugger.Environment</code> instance for a given environment. This allows the code using each <code>Debugger</code> instance to place whatever properties it likes on its own <code>Debugger.Object</code> instances, without worrying about interfering with other debuggers.)		(If more than one <code>Debugger</code> instance is debugging the same code, each <code>Debugger</code> gets a separate <code>Debugger.Environment</code> instance for a given environment. This allows the code using each <code>Debugger</code> instance to place whatever properties it likes on its own <code>Debugger.Object</code> instances, without worrying about interfering with other debuggers.)

			If a <code>Debugger.Environment</code> instance's referent is not a debuggee environment, then attempting to access its properties (other than <code>inspectable</code>) or call any its methods throws an instance of <code>Error</code>.

	<code>Debugger.Environment</code> instances protect their referents from the garbage collector; as long as the <code>Debugger.Environment</code> instance is live, the referent remains live. Garbage collection has no visible effect on <code>Debugger.Environment</code> instances.		<code>Debugger.Environment</code> instances protect their referents from the garbage collector; as long as the <code>Debugger.Environment</code> instance is live, the referent remains live. Garbage collection has no visible effect on <code>Debugger.Environment</code> instances.
Line 893:		Line 898:

	<dl>		<dl>
			<dt>inspectable
			<dd>True if this environment is a debuggee environment, and can therefore be inspected. False otherwise. All other properties and methods of <code>Debugger.Environment</code> instances throw if applied to a non-inspectable environment.

	<dt>type		<dt>type
	<dd>The type of this environment object, one of the following values:		<dd>The type of this environment object, one of the following values:

Jimb: [master d36e9a8] Document Debugger.prototype.makeGlobalObjectReference.

2013-09-17T22:38:43Z

[master d36e9a8] Document Debugger.prototype.makeGlobalObjectReference.

← Older revision		Revision as of 22:38, 17 September 2013
Line 3:		Line 3:
	The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can:		The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can:
	<ul>		<ul>
	<li>add debuggee global objects to its purview using its <code>addDebuggee</code> method;		<li>add debuggee global objects to its purview using its [[#Debugger.prototype.addDebuggee\|<code>addDebuggee</code>]] method;
	<li>request notification of basic debugging events like stack frame entry and <code>debugger</code> statement execution by providing appropriate handler functions;		<li>request notification of basic debugging events like stack frame entry and <code>debugger</code> statement execution by providing appropriate handler functions;
	<li>set breakpoints in scripts;		<li>set breakpoints in scripts;
Line 119:		Line 119:
	<dl>		<dl>
	<dt>new Debugger([<i>global</i>, ...])		<dt>new Debugger([<i>global</i>, ...])
	<dd>Create a debugger object, and apply its <code>addDebuggee</code> method to each of the given <i>global</i> objects to add them as the initial debuggees.		<dd>Create a debugger object, and apply its [[#Debugger.prototype.addDebuggee\|<code>addDebuggee</code>]] method to each of the given <i>global</i> objects to add them as the initial debuggees.
	</dl>		</dl>

Line 224:		Line 224:

	<dl>		<dl>
	<dt>addDebuggee(<i>global</i>)		<dt>{{anchor\|Debugger.prototype.addDebuggee}}addDebuggee(<i>global</i>)
	<dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. If the designated global is already a debuggee, this has no effect. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to ~~<i>~~global~~</i>'s referent~~.		<dd>Add the global object designated by <i>global</i> to the set of global objects this <code>Debugger</code> instance is debugging. If the designated global is already a debuggee, this has no effect. Return this <code>Debugger</code>'s <code>Debugger.Object</code> instance referring to the designated global.

	The value <i>global</i> may be any of the following:		The value <i>global</i> may be any of the following:
Line 245:		Line 245:
	<dd>Remove the global object designated by <i>global</i> from this <code>Debugger</code> instance's set of debuggees. Return <code>undefined</code>.		<dd>Remove the global object designated by <i>global</i> from this <code>Debugger</code> instance's set of debuggees. Return <code>undefined</code>.

	This method interprets <i>global</i> using the same rules that <code>addDebuggee</code> does.		This method interprets <i>global</i> using the same rules that [[#Debugger.prototype.addDebuggee\|<code>addDebuggee</code>]] does.

	<dt>hasDebuggee(<i>global</i>)		<dt>hasDebuggee(<i>global</i>)
	<dd>Return <code>true</code> if the global object designated by <i>global</i> is a debuggee of this <code>Debugger</code> instance.		<dd>Return <code>true</code> if the global object designated by <i>global</i> is a debuggee of this <code>Debugger</code> instance.

	This method interprets <i>global</i> using the same rules that <code>addDebuggee</code> does.		This method interprets <i>global</i> using the same rules that [[#Debugger.prototype.addDebuggee\|<code>addDebuggee</code>]] does.

	<dt>getDebuggees()		<dt>getDebuggees()
Line 306:		Line 306:

	This handler method is only available to debuggers running in privileged code ("chrome", in Firefox). Most functions provided by this <code>Debugger</code> API observe activity in only those globals that are reachable by the API's user, thus imposing capability-based restrictions on a <code>Debugger</code>'s reach. However, <code>findAllGlobals</code> allows the API user to find all global objects anywhere within the JavaScript system (the "JSRuntime", in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, <code>findAllGlobals</code> is only available to privileged code.		This handler method is only available to debuggers running in privileged code ("chrome", in Firefox). Most functions provided by this <code>Debugger</code> API observe activity in only those globals that are reachable by the API's user, thus imposing capability-based restrictions on a <code>Debugger</code>'s reach. However, <code>findAllGlobals</code> allows the API user to find all global objects anywhere within the JavaScript system (the "JSRuntime", in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, <code>findAllGlobals</code> is only available to privileged code.

			<dt>makeGlobalObjectReference(<i>global</i>)
			<dd>Return the <code>Debugger.Object</code> whose referent is the global object designated by <i>global</i>, without adding the designated global as a debuggee. If <i>global</i> does not designate a global object, throw a <code>TypeError</code>. Determine which global is designated by <i>global</i> using the same rules as [[#Debugger.prototype.addDebuggee\|<code>Debugger.prototype.addDebuggee</code>]].
	</dl>		</dl>

Line 865:		Line 868:
	<dt>unsafeDereference()		<dt>unsafeDereference()
	<dd>Return the referent of this <code>Debugger.Object</code> instance.		<dd>Return the referent of this <code>Debugger.Object</code> instance.

			If the referent is an inner object (say, an HTML5 <code>Window</code> object), return the corresponding outer object (say, the HTML5 <code>WindowProxy</code> object). This makes <code>unsafeDereference</code> more useful in producing values appropriate for direct use by debuggee code, without using [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation functions]].

	This method pierces the membrane of <code>Debugger.Object</code> instances meant to protect debugger code from debuggee code, and allows debugger code to access debuggee objects through the standard cross-compartment wrappers, rather than via <code>Debugger.Object</code>'s reflection-oriented interfaces. This method makes it easier to gradually adapt large code bases to this Debugger API: adapted portions of the code can use <code>Debugger.Object</code> instances, but use this method to pass direct object references to code that has not yet been updated.		This method pierces the membrane of <code>Debugger.Object</code> instances meant to protect debugger code from debuggee code, and allows debugger code to access debuggee objects through the standard cross-compartment wrappers, rather than via <code>Debugger.Object</code>'s reflection-oriented interfaces. This method makes it easier to gradually adapt large code bases to this Debugger API: adapted portions of the code can use <code>Debugger.Object</code> instances, but use this method to pass direct object references to code that has not yet been updated.

Jimb: [master 15eb6db] The API and protocol are implemented and deployed.

2013-08-08T23:01:13Z

[master 15eb6db] The API and protocol are implemented and deployed.

← Older revision		Revision as of 23:01, 8 August 2013
Line 1:		Line 1:
	<i>This interface is ~~partly~~ implemented in Firefox ~~Nightly builds~~. Some ~~parts~~ are not implemented, some APIs may yet change, and anything marked "(future plan)" is a long way off. You can [https://github.com/jimblandy/DebuggerDocs fork this specification on github] to draft and discuss revisions.</i>		<i>This interface is implemented in Firefox, and is the basis of Firefox's built-in JavaScript debugger. Some details are not implemented, some APIs may yet change, and anything marked "(future plan)" is a long way off. You can [https://github.com/jimblandy/DebuggerDocs fork this specification on github] to draft and discuss revisions.</i>

	The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can:		The <code>Debugger</code> constructor makes objects with methods for debugging code running in global objects in other compartments. Given a <code>Debugger</code> instance, you can:

Jimb: [master e9ac7f0] Fix up anchor for Debugger.Frame.prototype.eval.

2013-08-01T22:27:40Z

[master e9ac7f0] Fix up anchor for Debugger.Frame.prototype.eval.

← Older revision		Revision as of 22:27, 1 August 2013
Line 442:		Line 442:

	<dl>		<dl>
	<dt>eval(<i>code</i>)		<dt>{{anchor\|Debugger.Frame.prototype.eval}}eval(<i>code</i>, [<i>options</i>])
	<dd>Evaluate <i>code</i> in the execution context of this frame, and return a [[#Completion_Values\|completion value]] describing how it completed. <i>Code</i> is a string. If this frame's <code>environment</code> property is <code>null</code>, throw a <code>TypeError</code>. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]].		<dd>Evaluate <i>code</i> in the execution context of this frame, and return a [[#Completion_Values\|completion value]] describing how it completed. <i>Code</i> is a string. If this frame's <code>environment</code> property is <code>null</code>, throw a <code>TypeError</code>. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]].

Line 449:		Line 449:
	If <i>code</i> is not strict mode code, then variable declarations in <i>code</i> affect the environment of this frame. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the <code>VariableEnvironment</code> of the execution context that this frame represents.) If implementation restrictions prevent SpiderMonkey from extending this frame's environment as requested, this call throws an Error exception.		If <i>code</i> is not strict mode code, then variable declarations in <i>code</i> affect the environment of this frame. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the <code>VariableEnvironment</code> of the execution context that this frame represents.) If implementation restrictions prevent SpiderMonkey from extending this frame's environment as requested, this call throws an Error exception.

	<dt>evalWithBindings(<i>code</i>, <i>bindings</i>)		If given, <i>options</i> should be an object whose properties specify details of how the evaluation should occur. The <code>eval</code> method recognizes the following properties:
			<dl>
			<dt>url
			<dd>The filename or URL to which we should attribute <i>code</i>. If this property is omitted, the URL defaults to <code>"debugger eval code"</code>.
			</dl>

			<dt>evalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])
	<dd>Like <code>eval</code>, but evaluate <i>code</i> in the environment of this frame, extended with bindings from the object <i>bindings</i>. For each own enumerable property of <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a variable in the environment in which <i>code</i> is evaluated named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must be a debuggee value. (This is not like a <code>with</code> statement: <i>code</i> may access, assign to, and delete the introduced bindings without having any effect on the <i>bindings</i> object.)		<dd>Like <code>eval</code>, but evaluate <i>code</i> in the environment of this frame, extended with bindings from the object <i>bindings</i>. For each own enumerable property of <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a variable in the environment in which <i>code</i> is evaluated named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must be a debuggee value. (This is not like a <code>with</code> statement: <i>code</i> may access, assign to, and delete the introduced bindings without having any effect on the <i>bindings</i> object.)

Line 455:		Line 461:

	Note that, like <code>eval</code>, declarations in the <i>code</i> passed to <code>evalWithBindings</code> affect the environment of this frame, even as that environment is extended by bindings visible within <i>code</i>. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the <code>VariableEnvironment</code> of the execution context that this frame represents, and the <i>bindings</i> appear in a new declarative environment, which is the eval code's <code>LexicalEnvironment</code>.) If implementation restrictions prevent SpiderMonkey from extending this frame's environment as requested, this call throws an <code>Error</code> exception.		Note that, like <code>eval</code>, declarations in the <i>code</i> passed to <code>evalWithBindings</code> affect the environment of this frame, even as that environment is extended by bindings visible within <i>code</i>. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the <code>VariableEnvironment</code> of the execution context that this frame represents, and the <i>bindings</i> appear in a new declarative environment, which is the eval code's <code>LexicalEnvironment</code>.) If implementation restrictions prevent SpiderMonkey from extending this frame's environment as requested, this call throws an <code>Error</code> exception.

			The <i>options</i> argument is as for [[#Debugger.Frame.prototype.eval\|<code>Debugger.Frame.prototype.eval</code>]], described above.

	<dt>pop(<i>completion</i>) <i>(future plan)</i>		<dt>pop(<i>completion</i>) <i>(future plan)</i>
Line 788:		Line 796:
	<dd>If the referent is callable, call it with the given <i>this</i> value and the argument values in <i>arguments</i>, and return a [[#Completion_Values\|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke <i>function</i> as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. <i>Arguments</i> must either be an array (in the debugger) of debuggee values, or <code>null</code> or <code>undefined</code>, which are treated as an empty array. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger\|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]].		<dd>If the referent is callable, call it with the given <i>this</i> value and the argument values in <i>arguments</i>, and return a [[#Completion_Values\|completion value]] describing how the call completed. <i>This</i> should be a debuggee value, or <code>{ asConstructor: true }</code> to invoke <i>function</i> as a constructor, in which case SpiderMonkey provides an appropriate <code>this</code> value itself. <i>Arguments</i> must either be an array (in the debugger) of debuggee values, or <code>null</code> or <code>undefined</code>, which are treated as an empty array. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. Details of how the call is carried out are given in the description of [[#Debugger.Frame.Debugger\|Debugger.Frame.Debugger frames]]. If the referent is not callable, throw a <code>TypeError</code>. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]].

	<dt>evalInGlobal(<i>code</i>)		<dt>evalInGlobal(<i>code</i>, [<i>options</i>])
	<dd>If the referent is a global object, evaluate <i>code</i> in that global environment, and return a [[#Completion_Values\|completion value]] describing how it completed. <i>Code</i> is a string. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]]. If the referent is not a global object, throw a <code>TypeError</code> exception.		<dd>If the referent is a global object, evaluate <i>code</i> in that global environment, and return a [[#Completion_Values\|completion value]] describing how it completed. <i>Code</i> is a string. All extant handler methods, breakpoints, watchpoints, and so on remain active during the call. This function follows the [[#Invocation_Functions_and_.22debugger.22_Frames\|invocation function conventions]]. If the referent is not a global object, throw a <code>TypeError</code> exception.

Line 795:		Line 803:
	If <i>code</i> is not strict mode code, then variable declarations in <i>code</i> affect the referent global object. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the referent.)		If <i>code</i> is not strict mode code, then variable declarations in <i>code</i> affect the referent global object. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for the eval code is the referent.)

	<dt>evalInGlobalWithBindings(<i>code</i>, <i>bindings</i>)		The <i>options</i> argument is as for [[#Debugger.Frame.prototype.eval\|<code>Debugger.Frame.prototype.eval</code>]], described above.

			<dt>evalInGlobalWithBindings(<i>code</i>, <i>bindings</i>, [<i>options</i>])
	<dd>Like <code>evalInGlobal</code>, but evaluate <i>code</i> using the referent as the variable object, but with a lexical environment extended with bindings from the object <i>bindings</i>. For each own enumerable property of <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a variable in the lexical environment in which <i>code</i> is evaluated named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must be a debuggee value. (This is not like a <code>with</code> statement: <i>code</i> may access, assign to, and delete the introduced bindings without having any effect on the <i>bindings</i> object.)		<dd>Like <code>evalInGlobal</code>, but evaluate <i>code</i> using the referent as the variable object, but with a lexical environment extended with bindings from the object <i>bindings</i>. For each own enumerable property of <i>bindings</i> named <i>name</i> whose value is <i>value</i>, include a variable in the lexical environment in which <i>code</i> is evaluated named <i>name</i>, whose value is <i>value</i>. Each <i>value</i> must be a debuggee value. (This is not like a <code>with</code> statement: <i>code</i> may access, assign to, and delete the introduced bindings without having any effect on the <i>bindings</i> object.)

Line 801:		Line 811:

	Note that, like <code>evalInGlobal</code>, if the code passed to <code>evalInGlobalWithBindings</code> is not strict mode code, then any declarations it contains affect the referent global object, even as <i>code</i> is evaluated in an environment extended according to <i>bindings</i>. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for non-strict eval code is the referent, and the <i>bindings</i> appear in a new declarative environment, which is the eval code's <code>LexicalEnvironment</code>.)		Note that, like <code>evalInGlobal</code>, if the code passed to <code>evalInGlobalWithBindings</code> is not strict mode code, then any declarations it contains affect the referent global object, even as <i>code</i> is evaluated in an environment extended according to <i>bindings</i>. (In the terms used by the ECMAScript specification, the <code>VariableEnvironment</code> of the execution context for non-strict eval code is the referent, and the <i>bindings</i> appear in a new declarative environment, which is the eval code's <code>LexicalEnvironment</code>.)

			The <i>options</i> argument is as for [[#Debugger.Frame.prototype.eval\|<code>Debugger.Frame.prototype.eval</code>]], described above.

	<dt>asEnvironment()		<dt>asEnvironment()