Confirmed users
497
edits
Remote Debugging Protocol: Difference between revisions
Move "Source Locations" and "Lexical Environments" into their own top-level sections at the top.
m (Fix terminology: "agent" -> "actor") |
(Move "Source Locations" and "Lexical Environments" into their own top-level sections at the top.) |
||
| Line 266: | Line 266: | ||
Regardless of the lifetime of a grip, the client may only send messages to grip actors while the thread to which they belong is paused; the client's interaction with values cannot take place concurrently with the thread. | Regardless of the lifetime of a grip, the client may only send messages to grip actors while the thread to which they belong is paused; the client's interaction with values cannot take place concurrently with the thread. | ||
= Source Locations = | |||
Descriptions of source locations (written as <i>location</i> in packet descriptions) can take one of the following forms: | |||
{ "url":<i>url</i>, "line":<i>line</i>, "column":<i>column</i> } | |||
This refers to line <i>line</i>, column <i>column</i> of the source code loaded from <i>url</i>. Line and column numbers start with 1. If <i>column</i> or <i>line</i> are omitted, they default to 1. | |||
{ "eval":<i>location</i>, "id":<i>id</i>, "line":<i>line</i>, "column":<i>column</i> } | |||
This refers to line <i>line</i>, column <i>column</i> of the source code passed to the call to eval at <i>location</i>. To distinguish the different texts passed to eval, each is assigned a unique integer, <i>id</i>. | |||
{ "function":<i>location</i>, "id":<i>id</i>, "line":<i>line</i>, "column":<i>column</i> } | |||
This refers to line <i>line</i>, column <i>column</i> of the source code passed to the call to the <tt>Function</tt> constructor at <i>location</i>. To distinguish the different texts passed to eval, each is assigned a unique integer, <i>id</i>. | |||
As indicated, locations can be nested: a location like this one: | |||
{ "eval":{ "eval":{ "url":"file:///home/example/sample.js", "line":20 } | |||
"line":30 } | |||
"line":40 } | |||
refers to line 40 of the code passed to the call to eval occurring on line 30 of the code passed to the call to eval on line 20 of <tt>file:///home/example/sample.js</tt>. | |||
= Lexical Environments = | |||
A lexical environment (written as <i>environment</i> in packet descriptions) records the identifier bindings visible at a particular point in the program. An environment has one of the following forms: | |||
{ "type":"object", "actor":<i>actor</i>, "object":<i>object</i>, "parent":<i>parent-environment</i> } | |||
This represents a scope chain element whose identifier bindings reflect the properties of <i>object</i> (a grip). This could be the global object (<tt>window</tt> in a browser), or a DOM element (for event handler content attributes, which have the input element, form, and document on their scope chain along with the <tt>window</tt>). | |||
<i>Actor</i> is the name of an actor representing this lexical environment. The requests it can answer are described below. | |||
<i>Parent-environment</i> describes the next enclosing lexical environment; the <tt>parent</tt> property is omitted on the outermost environment. | |||
{ "type":"function", "actor":<i>actor</i>, "function":<i>function</i>, "function-name":<i>function-name</i>, | |||
"bindings":<i>bindings</i>, "parent":<i>parent-environment</i> } | |||
This represents the variable environment created by a call to <i>function</i> (a grip), whose name is <i>function-name</i> (a string). <i>Bindings</i> describes the bindings in scope, including the function's arguments, the <tt>arguments</tt> object, and local <tt>var</tt> and function bindings; its form is described in detail below. The <tt>function-name</tt> property is omitted if the function is anonymous. The other properties are as described above. | |||
{ "type":"with", "actor":<i>actor</i>, "object":<i>object</i>, "parent":<i>parent-environment</i> } | |||
This represents bindings introduced by a <tt>with</tt> statement whose operand is <i>object</i> (a grip). The other properties are as described above. | |||
{ "type":"block", "actor":<i>actor</i>, "bindings":<i>bindings</i>, "parent":<i>parent-environment</i> } | |||
This represents bindings introduced by a <tt>let</tt> block, <tt>for-in</tt> statement, <tt>catch</tt> block, or the like. The properties are as described above. | |||
A <i>bindings</i> value has the form: | |||
{ "mutable":{ <i>name</i>:<i>value</i>, ... }, | |||
"immutable":{ <i>name</i>:<i>value</i>, ... } } | |||
where each <i>name</i> is the name of a bound identifier, and each <i>value</i> is a grip on that identifier's value. Mutable bindings appear in the <tt>mutable</tt> object, and immutable bindings appear in the <tt>immutable</tt> object. If either category has no bindings, the property may be omitted entirely. | |||
Note that language implementations may omit some environment records from a function's scope if it can determine that the function would not use them. This means that it may be impossible for a debugger to find all the variables that ought to be in scope. | |||
To fully enumerate the bindings introduced by any lexical environment, the client can send a request of the following form to the environment's actor: | |||
{ "to":<i>env-actor</i>, "type":"bindings" } | |||
The actor will reply as follows: | |||
{ "from":<i>env-actor</i>, "bindings":<i>bindings</i> } | |||
To change the value of a variable bound in a particular lexical environment, the client can send a request to the environment's actor: | |||
{ "to":<i>env-actor</i>, "type":"assign", "name":<i>name</i>, "value":<i>value</i> } | |||
This changes the value of the identifier whose name is <i>name</i> (a string) to that represented by <i>value</i> (a grip). The actor will reply as follows, simply: | |||
{ "from":<i>env-actor</i> } | |||
If the named identifier is immutable, the actor will send an error reply of the form: | |||
{ "from":<i>env-actor</i>, "error":"immutable-binding", "message":<i>message</i> } | |||
= The Root Actor = | = The Root Actor = | ||
| Line 632: | Line 710: | ||
<i>TODO: specify the error to return if the frame cannot be popped --- can host (C++) function frames be popped?</i> | <i>TODO: specify the error to return if the frame cannot be popped --- can host (C++) function frames be popped?</i> | ||
== Evaluating Source-Language Expressions == | == Evaluating Source-Language Expressions == | ||