# Debugger.Environment

A `Debugger.Environment` instance represents a lexical environment,
associating names with variables. Each [`Debugger.Frame`][frame] instance
representing a debuggee frame has an associated environment object
describing the variables in scope in that frame; and each
[`Debugger.Object`][object] instance representing a debuggee function has an
environment object representing the environment the function has closed
over.

ECMAScript environments form a tree, in which each local environment is
parented by its enclosing environment (in ECMAScript terms, its 'outer'
environment). We say an environment <i>binds</i> an identifier if that
environment itself associates the identifier with a variable, independently
of its outer environments. We say an identifier is <i>in scope</i> in an
environment if the identifier is bound in that environment or any enclosing
environment.

SpiderMonkey creates `Debugger.Environment` instances as needed as the
debugger inspects stack frames and function objects; calling
`Debugger.Environment` as a function or constructor raises a `TypeError`
exception.

SpiderMonkey creates exactly one `Debugger.Environment` instance for each
environment it presents via a given [`Debugger`][debugger-object] instance:
if the debugger encounters the same environment through two different
routes (perhaps two functions have closed over the same environment),
SpiderMonkey presents the same `Debugger.Environment` instance to the
debugger each time. This means that the debugger can use the `==` operator
to recognize when two `Debugger.Environment` instances refer to the same
environment in the debuggee, and place its own properties on a
`Debugger.Environment` instance to store metadata about particular
environments.

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

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

`Debugger.Environment` instances protect their referents from the
garbage collector; as long as the `Debugger.Environment` instance is
live, the referent remains live. Garbage collection has no visible
effect on `Debugger.Environment` instances.


## Accessor Properties of the Debugger.Environment Prototype Object

A `Debugger.Environment` instance inherits the following accessor
properties from its prototype:

### `inspectable`
True if this environment is a debuggee environment, and can therefore
be inspected. False otherwise. All other properties and methods of
`Debugger.Environment` instances throw if applied to a non-inspectable
environment.

### `type`
The type of this environment object, one of the following values:

* "declarative", indicating that the environment is a declarative
  environment record. Function calls, calls to `eval`, `let` blocks,
  `catch` blocks, and the like create declarative environment records.

* "object", indicating that the environment's bindings are the
  properties of an object. The global object and DOM elements appear in
  the chain of environments via object environments. (Note that `with`
  statements have their own environment type.)

* "with", indicating that the environment was introduced by a `with`
  statement.

### `scopeKind`
If this is a declarative environment, a string describing the kind of scope
which this environment is associated with, or `null` for other types of
environments.  There is an assortment of possible scope kinds which can be
generated, with a selection of possible values below.  Unlike the type
accessor, the categorization this performs is specific to SpiderMonkey's
implementation, and not derived from distinctions made in the ECMAScript
language specification.

* "function", indicating the top level body scope of a function for
arguments and 'var' variables.

* "function lexical", indicating the top level lexical scope in a function.

### `parent`
The environment that encloses this one (the "outer" environment, in
ECMAScript terminology), or `null` if this is the outermost environment.

### `object`
A [`Debugger.Object`][object] instance referring to the object whose
properties this environment reflects. If this is a declarative
environment record, this accessor throws a `TypeError` (since
declarative environment records have no such object). Both `"object"`
and `"with"` environments have `object` properties that provide the
object whose properties they reflect as variable bindings.

### `calleeScript`
If this environment represents the variable environment (the top-level
environment within the function, which receives `var` definitions) for
a call to a function <i>f</i>, then this property's value is a
[`Debugger.Script`][script] instance referring to <i>f</i>'s script. Otherwise,
this property's value is `null`.

### `optimizedOut`
True if this environment is optimized out. False otherwise. For example,
functions whose locals are never aliased may present optimized-out
environments. When true, `getVariable` returns an ordinary JavaScript
object whose `optimizedOut` property is true on all bindings, and
`setVariable` throws a `ReferenceError`.


## Function Properties of the Debugger.Environment Prototype Object

The methods described below may only be called with a `this` value
referring to a `Debugger.Environment` instance; they may not be used as
methods of other kinds of objects.

### `names()`
Return an array of strings giving the names of the identifiers bound by
this environment. The result does not include the names of identifiers
bound by enclosing environments.

### `getVariable(name)`

Return the value of the variable bound to <i>name</i> in this
environment, or `undefined` 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, in most cases.

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

Aside from the above case, this method can return something that is not a
debuggee value in two other cases. If a function argument is missing, then it
returns an ordinary JavaScript object whose `missingArgument` property is
`true`. Finally, if a variable name is bound in the environment but not yet
initialized (for example, if the debuggee is paused in the middle of an
initializer expression) then it returns an ordinary JavaScript object whose
`uninitialized` property is `true`.

This is not an [invocation function][inv fr];
if this call would cause debuggee code to run (say, because the
environment is a `"with"` environment, and <i>name</i> refers to an
accessor property of the `with` statement's operand), this call throws a
[`Debugger.DebuggeeWouldRun`][wouldrun]
exception.

### `setVariable(name, value)`
Store <i>value</i> as the value of the variable bound to <i>name</i> in
this environment. <i>Name</i> must be a string that is a valid
ECMAScript identifier name; <i>value</i> must be a debuggee value.

If this environment binds no variable named <i>name</i>, throw a
`ReferenceError`.

This is not an [invocation function][inv fr];
if this call would cause debuggee code to run, this call throws a
[`Debugger.DebuggeeWouldRun`][wouldrun]
exception.

### `find(name)`
Return a reference to the innermost environment, starting with this
environment, that binds <i>name</i>. If <i>name</i> is not in scope in
this environment, return `null`. <i>Name</i> must be a string whose
value is a valid ECMAScript identifier name.


[frame]: Debugger.Frame.md
[object]: Debugger.Object.md
[debugger-object]: Debugger.md
[inv fr]: Debugger.Frame.html#invocation-functions-and-debugger-frames
[wouldrun]: Conventions.html#the-debugger-debuggeewouldrun-exception