From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- js/src/doc/Debugger/Debugger.Environment.md | 182 ++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 js/src/doc/Debugger/Debugger.Environment.md (limited to 'js/src/doc/Debugger/Debugger.Environment.md') diff --git a/js/src/doc/Debugger/Debugger.Environment.md b/js/src/doc/Debugger/Debugger.Environment.md new file mode 100644 index 0000000000..eef4d35818 --- /dev/null +++ b/js/src/doc/Debugger/Debugger.Environment.md @@ -0,0 +1,182 @@ +# 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 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`][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 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`][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 name refers to an +accessor property of the `with` statement's operand), this call throws a +[`Debugger.DebuggeeWouldRun`][wouldrun] +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][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 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. + + +[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 -- cgit v1.2.3