Environment class

Represents the execution environment for interpreted code.

The Environment class manages variable bindings, function definitions, class definitions, and bridged types for a specific scope. Environments form a chain through their enclosing relationship, enabling lexical scoping.

Features:

• Variable and function storage
• Bridged class and enum registration
• Extension method management
• Prefixed imports support
• Scope chain traversal for name resolution

Example:

final globalEnv = Environment();
final functionEnv = Environment(enclosing: globalEnv);

globalEnv.define('globalVar', 42);
functionEnv.define('localVar', 'hello');

// Will find 'globalVar' by traversing up the scope chain
final value = functionEnv.get('globalVar');

Constructors

Environment({Environment? enclosing})

Creates a new environment, optionally with an enclosing (parent) environment.

Properties

bridgedClassNames → List<String>

Gets the names of all bridged classes registered in this environment.

no setter

bridgedEnumNames → List<String>

Gets the names of all bridged enums registered in this environment.

no setter

enclosing → Environment?

Gets the enclosing (parent) environment, if any.

no setter

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

staticFieldSnapshotOwner ↔ InterpretedClass?

OPEN B.9 — when this environment is the top execution scope of a static member, it holds snapshots of the owner class's static fields so that bare-identifier reads resolve without a class prefix. This marker records the owning class so that a bare-identifier write to one of those snapshotted fields can be propagated back to the class's authoritative static slot (InterpretedClass.setStaticField). Without it, the write would only mutate the discarded local snapshot and never survive the call.

getter/setter pair

values → Map<String, Object?>

Gets the map of variable bindings in this environment.

no setter

Methods

addUnnamedExtension(InterpretedExtension extension) → void

assign(String name, Object? value) → Object?

define(String name, Object? value) → void

Defines a new variable or function in this environment.

defineBridge(BridgedClass bridgedClass) → void

Registers a bridged class in this environment.

defineBridgeAlias(String aliasName, String targetName) → void

GEN-078: Registers a class alias that maps aliasName to an existing bridged class registered under targetName.

defineBridgedEnum(BridgedEnum bridgedEnum) → void

definePrefixedImport(String prefix, Environment importEnvironment) → void

defineSlot(int slot, String name, Object? value) → void

Writes value into this frame's slot array at slot and records the name→slot mapping, growing/allocating _slots lazily.

findBridgedClassByName(String name) → BridgedClass?

Looks up a bridged class by name, walking the enclosing scope chain. Returns null if no bridge with name is registered in this environment or any of its parents. Used by the property-access supertype-walk fallback in interpreter_visitor.dart to resolve getters/methods that are declared on a supertype bridge when the leaf bridge has no matching adapter (e.g. _AnimatedEvaluation wraps as AnimationWithParentMixin, whose bridge lacks value; the walk falls back to the Animation bridge where value is declared).

findBridgedEnumForValue(Object value) → BridgedEnum?

Checks if the given object is a bridged enum value

findDefiningEnvironment(String name) → Environment?

findExtensionMember(Object? target, String name, {InterpreterVisitor? visitor}) → Callable?

get(String name) → dynamic

Retrieves the value associated with name, throwing RuntimeD4rtException("Undefined variable: ...") when it is absent.

getBridgedEnumValue(Object value) → BridgedEnumValue?

Gets the BridgedEnumValue for a native enum value

getRawValueIfDefined(String name) → Object?

Gets the raw value for a variable if defined locally, without GlobalGetter unwrapping.

getRuntimeType(Object? value) → RuntimeType?

getSlot(int slot) → Object?

Reads the value at slot in THIS frame's slot array. The caller guarantees (via the static resolver's depth-0 coordinate) that the slot was written by a preceding defineSlot in the same frame. No name hashing — one list index (note-6, §10.4).

importEnvironment(Environment other, {Set<String>? show, Set<String>? hide, bool errorOnConflict = false}) → void

Imports definitions from another environment into this one. Can be filtered using show or hide combinators. If no filter is provided, all symbols from other are merged. This method directly modifies the current environment.

isDefinedLocally(String name) → bool

lookup(String name) → Object?

Non-throwing variant of get: resolves name across the lexical chain (locals, bridged classes/enums, prefixed imports) and returns kNotFound instead of throwing when nothing matches.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

propagateBridgeTypesTo(Environment target) → void

Propagates every bridge registered in this environment's type lookup to target for native-object resolution.

registerBridgeType(BridgedClass bridgedClass) → void

Pre-registers a bridge's native-type mapping for runtime type resolution.

removeLocalValue(String name) → bool

Removes name from this environment's local _values map.

shallowCopyFiltered({Set<String>? showNames, Set<String>? hideNames}) → Environment

Creates a shallow copy of this environment, optionally filtering symbols.

toBridgedClass(Type nativeType) → BridgedClass

toBridgedInstance(Object? nativeObject) → BridgedInstance<Object>?

Converts a native object to a bridged instance if a bridge exists.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

kNotFound → Object

Sentinel returned by lookup when name resolves to no binding in the whole chain. A fresh identity object so it can never collide with a real stored value (including null). Lets callers on the hot path distinguish "absent" from "present-but-null" WITHOUT throwing — see lookup.

final