1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/js/src/doc/Debugger/Debugger.Environment.md Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,231 @@
1.4 +# Debugger.Environment
1.5 +
1.6 +A `Debugger.Environment` instance represents a lexical environment,
1.7 +associating names with variables. Each [`Debugger.Frame`][frame] instance
1.8 +representing a debuggee frame has an associated environment object
1.9 +describing the variables in scope in that frame; and each
1.10 +[`Debugger.Object`][object] instance representing a debuggee function has an
1.11 +environment object representing the environment the function has closed
1.12 +over.
1.13 +
1.14 +ECMAScript environments form a tree, in which each local environment is
1.15 +parented by its enclosing environment (in ECMAScript terms, its 'outer'
1.16 +environment). We say an environment <i>binds</i> an identifier if that
1.17 +environment itself associates the identifier with a variable, independently
1.18 +of its outer environments. We say an identifier is <i>in scope</i> in an
1.19 +environment if the identifier is bound in that environment or any enclosing
1.20 +environment.
1.21 +
1.22 +SpiderMonkey creates `Debugger.Environment` instances as needed as the
1.23 +debugger inspects stack frames and function objects; calling
1.24 +`Debugger.Environment` as a function or constructor raises a `TypeError`
1.25 +exception.
1.26 +
1.27 +SpiderMonkey creates exactly one `Debugger.Environment` instance for each
1.28 +environment it presents via a given [`Debugger`][debugger-object] instance:
1.29 +if the debugger encounters the same environment through two different
1.30 +routes (perhaps two functions have closed over the same environment),
1.31 +SpiderMonkey presents the same `Debugger.Environment` instance to the
1.32 +debugger each time. This means that the debugger can use the `==` operator
1.33 +to recognize when two `Debugger.Environment` instances refer to the same
1.34 +environment in the debuggee, and place its own properties on a
1.35 +`Debugger.Environment` instance to store metadata about particular
1.36 +environments.
1.37 +
1.38 +(If more than one [`Debugger`][debugger-object] instance is debugging the
1.39 +same code, each [`Debugger`][debugger-object] gets a separate
1.40 +`Debugger.Environment` instance for a given environment. This allows the
1.41 +code using each [`Debugger`][debugger-object] instance to place whatever
1.42 +properties it likes on its own [`Debugger.Object`][object] instances,
1.43 +without worrying about interfering with other debuggers.)
1.44 +
1.45 +If a `Debugger.Environment` instance's referent is not a debuggee
1.46 +environment, then attempting to access its properties (other than
1.47 +`inspectable`) or call any its methods throws an instance of `Error`.
1.48 +
1.49 +`Debugger.Environment` instances protect their referents from the
1.50 +garbage collector; as long as the `Debugger.Environment` instance is
1.51 +live, the referent remains live. Garbage collection has no visible
1.52 +effect on `Debugger.Environment` instances.
1.53 +
1.54 +
1.55 +## Accessor Properties of the Debugger.Environment Prototype Object
1.56 +
1.57 +A `Debugger.Environment` instance inherits the following accessor
1.58 +properties from its prototype:
1.59 +
1.60 +`inspectable`
1.61 +: True if this environment is a debuggee environment, and can therefore
1.62 + be inspected. False otherwise. All other properties and methods of
1.63 + `Debugger.Environment` instances throw if applied to a non-inspectable
1.64 + environment.
1.65 +
1.66 +`type`
1.67 +: The type of this environment object, one of the following values:
1.68 +
1.69 + * "declarative", indicating that the environment is a declarative
1.70 + environment record. Function calls, calls to `eval`, `let` blocks,
1.71 + `catch` blocks, and the like create declarative environment records.
1.72 +
1.73 + * "object", indicating that the environment's bindings are the
1.74 + properties of an object. The global object and DOM elements appear in
1.75 + the chain of environments via object environments. (Note that `with`
1.76 + statements have their own environment type.)
1.77 +
1.78 + * "with", indicating that the environment was introduced by a `with`
1.79 + statement.
1.80 +
1.81 +`parent`
1.82 +: The environment that encloses this one (the "outer" environment, in
1.83 + ECMAScript terminology), or `null` if this is the outermost environment.
1.84 +
1.85 +`object`
1.86 +: A [`Debugger.Object`][object] instance referring to the object whose
1.87 + properties this environment reflects. If this is a declarative
1.88 + environment record, this accessor throws a `TypeError` (since
1.89 + declarative environment records have no such object). Both `"object"`
1.90 + and `"with"` environments have `object` properties that provide the
1.91 + object whose properties they reflect as variable bindings.
1.92 +
1.93 +`callee`
1.94 +: If this environment represents the variable environment (the top-level
1.95 + environment within the function, which receives `var` definitions) for
1.96 + a call to a function <i>f</i>, then this property's value is a
1.97 + [`Debugger.Object`][object] instance referring to <i>f</i>. Otherwise,
1.98 + this property's value is `null`.
1.99 +
1.100 +
1.101 +
1.102 +## Function Properties of the Debugger.Environment Prototype Object
1.103 +
1.104 +The methods described below may only be called with a `this` value
1.105 +referring to a `Debugger.Environment` instance; they may not be used as
1.106 +methods of other kinds of objects.
1.107 +
1.108 +`names()`
1.109 +: Return an array of strings giving the names of the identifiers bound by
1.110 + this environment. The result does not include the names of identifiers
1.111 + bound by enclosing environments.
1.112 +
1.113 +<code>getVariable(<i>name</i>)</code>
1.114 +: Return the value of the variable bound to <i>name</i> in this
1.115 + environment, or `undefined` if this environment does not bind
1.116 + <i>name</i>. <i>Name</i> must be a string that is a valid ECMAScript
1.117 + identifier name. The result is a debuggee value.
1.118 +
1.119 + JavaScript engines often omit variables from environments, to save space
1.120 + and reduce execution time. If the given variable should be in scope, but
1.121 + `getVariable` is unable to produce its value, it returns an ordinary
1.122 + JavaScript object (not a [`Debugger.Object`][object] instance) whose
1.123 + `optimizedOut` property is `true`.
1.124 +
1.125 + This is not an [invocation function][inv fr];
1.126 + if this call would cause debuggee code to run (say, because the
1.127 + environment is a `"with"` environment, and <i>name</i> refers to an
1.128 + accessor property of the `with` statement's operand), this call throws a
1.129 + [`Debugger.DebuggeeWouldRun`][wouldrun]
1.130 + exception.
1.131 +
1.132 +<code>setVariable(<i>name</i>, <i>value</i>)</code>
1.133 +: Store <i>value</i> as the value of the variable bound to <i>name</i> in
1.134 + this environment. <i>Name</i> must be a string that is a valid
1.135 + ECMAScript identifier name; <i>value</i> must be a debuggee value.
1.136 +
1.137 + If this environment binds no variable named <i>name</i>, throw a
1.138 + `ReferenceError`.
1.139 +
1.140 + This is not an [invocation function][inv fr];
1.141 + if this call would cause debuggee code to run, this call throws a
1.142 + [`Debugger.DebuggeeWouldRun`][wouldrun]
1.143 + exception.
1.144 +
1.145 +<code>getVariableDescriptor(<i>name</i>)</code>
1.146 +: Return an property descriptor describing the variable bound to
1.147 + <i>name</i> in this environment, of the sort returned by
1.148 + `Debugger.Object.prototype.getOwnPropertyDescriptor`. <i>Name</i> must
1.149 + be a string whose value is a valid ECMAScript identifier name.
1.150 +
1.151 + If this is an `"object"` or `"with"` environment record, this simply
1.152 + returns the descriptor for the given property of the environment's
1.153 + object. If this is a declarative environment record, this returns a
1.154 + descriptor reflecting the binding's mutability as the descriptor's
1.155 + `writable` property, and its deletability as the descriptor's
1.156 + `configurable` property. All declarative environment record bindings are
1.157 + marked as `enumerable`. <i>(This isn't great; the semantics of variables
1.158 + in declarative enviroments don't really match those of properties, so
1.159 + writing code that operates properly on descriptors for either kind may
1.160 + be difficult.)</i>
1.161 +
1.162 + If this environment binds no variable named <i>name</i>, throw a
1.163 + `ReferenceError`.
1.164 +
1.165 +<code>defineVariable(<i>name</i>, <i>descriptor</i>)</code>
1.166 +: Create or reconfigure the variable bound to <i>name</i> in this
1.167 + environment according to <i>descriptor</i>. <i>Descriptor</i> is the
1.168 + sort of value returned by `getVariableDescriptor`. On success, return
1.169 + `undefined`; on failure, throw an appropriate exception. <i>Name</i>
1.170 + must be a string whose value is a valid ECMAScript identifier name.
1.171 +
1.172 + If implementation restrictions prevent SpiderMonkey from creating or
1.173 + reconfiguring the variable as requested, this call throws an `Error`
1.174 + exception.
1.175 +
1.176 +<code>deleteVariable(<i>name</i>)</code>
1.177 +: Delete this environment's binding for <i>name</i>.
1.178 +
1.179 + If this environment binds no variable named <i>name</i>, throw a
1.180 + `ReferenceError`.
1.181 +
1.182 + If implementation restrictions prevent SpiderMonkey from deleting the
1.183 + variable as requested, this call throws an `Error` exception.
1.184 +
1.185 +<code>find(<i>name</i>)</code>
1.186 +: Return a reference to the innermost environment, starting with this
1.187 + environment, that binds <i>name</i>. If <i>name</i> is not in scope in
1.188 + this environment, return `null`. <i>Name</i> must be a string whose
1.189 + value is a valid ECMAScript identifier name.
1.190 +
1.191 +<code>eval(<i>code</i>)</code> <i>(future plan)</i>
1.192 +: Evaluate <i>code</i> in this environment, and return a
1.193 + [completion value][cv] describing how it completed. <i>Code</i> is a
1.194 + string. All extant handler methods, breakpoints, watchpoints, and so on
1.195 + remain active during the call. This function follows the
1.196 + [invocation function conventions][inv fr].
1.197 +
1.198 + <i>Code</i> is interpreted as strict mode code when it contains a Use
1.199 + Strict Directive.
1.200 +
1.201 + If <i>code</i> is not strict mode code, then variable declarations in
1.202 + <i>code</i> affect this environment. (In the terms used by the
1.203 + ECMAScript specification, the `VariableEnvironment` of the execution
1.204 + context for the eval code is the `VariableEnvironment` this
1.205 + `Debugger.Environment` instance represents.) If implementation
1.206 + restrictions prevent SpiderMonkey from extending this environment as
1.207 + requested, this call throws an `Error` exception.
1.208 +
1.209 +<code>evalWithBindings(<i>code</i>, <i>bindings</i>)</code> <i>(future plan)</i>
1.210 +: Like `eval`, but evaluate <i>code</i> in this environment, extended with
1.211 + bindings from the object <i>bindings</i>. For each own enumerable
1.212 + property of <i>bindings</i> named <i>name</i> whose value is
1.213 + <i>value</i>, include a variable in the environment in which <i>code</i>
1.214 + is evaluated named <i>name</i>, whose value is <i>value</i>. Each
1.215 + <i>value</i> must be a debuggee value. (This is not like a `with`
1.216 + statement: <i>code</i> may access, assign to, and delete the introduced
1.217 + bindings without having any effect on the <i>bindings</i> object.)
1.218 +
1.219 + This method allows debugger code to introduce temporary bindings that
1.220 + are visible to the given debuggee code and which refer to debugger-held
1.221 + debuggee values, and do so without mutating any existing debuggee
1.222 + environment.
1.223 +
1.224 + Note that, like `eval`, declarations in the <i>code</i> passed to
1.225 + `evalWithBindings` affect this environment, even as <i>code</i> is
1.226 + evaluated with <i>bindings</i> visible. (In the terms used by the
1.227 + ECMAScript specification, the `VariableEnvironment` of the execution
1.228 + context for the eval code is the `VariableEnvironment` this environment
1.229 + represents, and the <i>bindings</i> appear in a new declarative
1.230 + environment, which is the eval code's `LexicalEnvironment`.) If
1.231 + implementation restrictions prevent SpiderMonkey from extending this
1.232 + environment as requested, this call throws an `Error` exception.
1.233 +
1.234 +
