Debugger.Environment
A Debugger.Environment
instance represents a lexical environment,
associating names with variables. Each Debugger.Frame
instance
representing a debuggee frame has an associated environment object
describing the variables in scope in that frame; and each
Debugger.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 binds an identifier if that environment itself associates the identifier with a variable, independently of its outer environments. We say an identifier is in scope 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
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
instance is debugging the
same code, each Debugger
gets a separate
Debugger.Environment
instance for a given environment. This allows the
code using each Debugger
instance to place whatever
properties it likes on its own Debugger.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
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 f, then this property’s value is a
[Debugger.Script
][script] instance referring to f’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 name in this
environment, or undefined
if this environment does not bind
name. Name 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
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;
if this call would cause debuggee code to run (say, because the
environment is a "with"
environment, and name refers to an
accessor property of the with
statement’s operand), this call throws a
Debugger.DebuggeeWouldRun
exception.
setVariable(name, value)
Store value as the value of the variable bound to name in this environment. Name must be a string that is a valid ECMAScript identifier name; value must be a debuggee value.
If this environment binds no variable named name, throw a
ReferenceError
.
This is not an invocation function;
if this call would cause debuggee code to run, this call throws a
Debugger.DebuggeeWouldRun
exception.
find(name)
Return a reference to the innermost environment, starting with this
environment, that binds name. If name is not in scope in
this environment, return null
. Name must be a string whose
value is a valid ECMAScript identifier name.