D4rtRunner class

D4rtRunner - Execute pre-parsed AST trees without analyzer dependency.

This class provides the core interpreter functionality for executing SAstNode trees. Unlike the full D4rt class in tom_d4rt_exec, D4rtRunner works exclusively with pre-parsed AST and does not require the analyzer.

Use Cases

Execute AST loaded from JSON files
Execute AST from precompiled scripts
Embedded interpreter without heavy analyzer dependency

Example:

// From JSON string
final runner = D4rtRunner();
final ast = runner.parseJson(jsonString);
final result = runner.execute(ast: ast);

// From JSON file
final result = await runner.executeFromJsonFile('script.ast.json');

For source code parsing and execution, use the D4rt class from tom_d4rt_exec which provides full integration with tom_ast_generator.

Constructors

D4rtRunner({bool reuseAcrossRuns = true}): Creates a D4rtRunner instance for executing pre-parsed AST.

Properties

allowedPackages → Set<String>: The packages this instance has been granted via providePackage (its security whitelist). Read-only snapshot.
no setter
bridgedClasses → Map<String, Map<String, LibraryClass>>: Registered bridged class definitions: URI → (name → class).
no setter
bridgedEnumDefinitions → Map<String, Map<String, LibraryEnum>>: Registered bridged enum definitions: URI → (name → enum).
no setter
bridgedExtensions → Map<String, List<LibraryExtension>>: Registered bridged extension definitions: URI → list of extensions.
no setter
bridgedLibraryUris → Set<String>: The set of library URIs that have at least one registered bridge (class, enum, extension, function, variable, getter, or setter).
no setter
bridgesFinalized → bool: Whether finalizeBridges has been called on this runner. Step 6.
no setter
classAliases → List<({String aliasName, String library, String targetName})>: Registered class aliases keyed by library URI.
no setter
debugLoadedModuleCount → int: Step #3 (retention) — number of bundle modules whose SCompilationUnit this runner currently retains (via the most recent _lastModuleLoader). 0 before the first execute or after dispose. Because every executeBundle builds a fresh loader, this reflects only the current run, never an accumulation of prior runs' ASTs.
no setter
functionTypedefs → List<({String library, String name})>: Registered function typedefs.
no setter
hashCode → int: The hash code for this object.
no setterinherited
libraryFunctions → Map<String, Map<String, LibraryFunction>>: Registered library functions: URI → (name → function).
no setter
libraryGetters → Map<String, Map<String, LibraryGetter>>: Registered library getters: URI → (name → getter).
no setter
libraryReExports → Map<String, List<({Set<String>? hide, Set<String>? show, String uri})>>: GEN-107: Registered library re-exports keyed by source library URI.
no setter
librarySetters → Map<String, Map<String, LibrarySetter>>: Registered library setters: URI → (name → setter).
no setter
libraryVariables → Map<String, Map<String, LibraryVariable>>: Registered library variables: URI → (name → variable).
no setter
reuseAcrossRuns → bool: Whether the cross-run bridge caches are reused between executeBundle* calls. See the constructor. false forces a fresh warm parent and fresh bridged module environments on every run for full inter-run isolation.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
visitor → InterpreterVisitor?: Gets the current interpreter visitor instance.
no setter

Methods

checkPermission(dynamic operation) → bool: Checks if any permission allows the given operation.
dispose() → void: Step #3 (retention) — releases the interpreter artifacts retained from the most recent run so a finished run's SCompilationUnit graph, interpreted declarations, and per-run environment become collectable while this runner is kept alive but idle.
eval(String expression) → dynamic: Evaluate an expression in the current context.
execute({required SCompilationUnit ast, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic: Execute an AST.
executeBundle(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic: Execute an AstBundle with full import resolution.
executeBundleAs<T>(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → T: Execute bundle and unwrap the result to type T via D4.unwrapAs.
executeBundleAsAsync<T>(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → Future<T>: Async variant of executeBundleAs — awaits the result if it is a Future before unwrapping to T.
executeFromJson({required String jsonString, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic: Execute from a JSON string.
executeFromJsonFile({required String path, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → Future: Execute from a JSON file.
finalizeBridges() → void: Runs every extension callback registered via registerExtensions in registration order, then marks the runner as finalized.
grant(Permission permission) → void: Grants a permission.
hasPermission(Permission permission) → bool: Checks if a specific permission is granted.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
parseJson(String jsonString) → SCompilationUnit: Parses an AST from a JSON string.
parseJsonFile(String path) → Future<SCompilationUnit>: Parses an AST from a JSON file.
providePackage(String packageName) → bool: Step 7 — Grants packageName to this instance and reports whether its bridge definitions are already in the process-global pool.
registerBridgedClass(BridgedClass definition, String library, {String? sourceUri}) → void: Registers a bridged class definition.
registerBridgedClassLazy(String name, Type nativeType, BridgedClass thunk(), String library, {String? sourceUri}) → void: Step #17 — registers a bridged class via a deferred factory thunk.
registerBridgedEnum(BridgedEnumDefinition<Enum> definition, String library, {String? sourceUri}) → void: Registers a bridged enum definition.
registerBridgedExtension(BridgedExtensionDefinition definition, String library, {String? sourceUri}) → void: Registers a bridged extension.
registerClassAlias(String aliasName, String targetName, String library) → void: GEN-074: Registers a class alias (type alias).
registerExtensions(String packageName, void body()) → void: Registers a body callback that wires additional bridge state (e.g. registerRelaxers(), registerD4rtRuntimeExtensions(), registerD4rtInterfaceProxyOverrides()) after the main registerBridgedClass/registerBridgedEnum/etc. registrations for packageName have happened.
registerFunctionTypedef(String name, String library) → void: Registers a function typedef so it can be resolved as a type.
registerGenericConstructor(String className, String constructorName, GenericConstructorFactory factory) → void: Registers a generic-constructor factory for className.constructorName.
registerGlobalGetter(String name, Object? getter(), String library, {String? sourceUri}) → void: Registers a global getter.
registerGlobalSetter(String name, void setter(Object? value), String library, {String? sourceUri}) → void: Registers a global setter.
registerGlobalVariable(String name, Object? value, String library, {String? sourceUri}) → void: Registers a global variable.
registerInterfaceProxy(String bridgedTypeName, InterfaceProxyFactory factory) → void: Registers an interface-proxy factory for bridgedTypeName.
registerLibraryReExport(String sourceUri, String targetUri, {Set<String>? show, Set<String>? hide}) → void: GEN-107: Registers a re-export from one library to another.
registerRelaxerFactory(String baseTypeName, GenericTypeWrapperFactory factory) → void: Registers a relaxer (generic-type-wrapper) factory for baseTypeName.
registerTopLevelFunction(String? name, NativeFunctionImpl function, String library, {String? sourceUri, String? signature}) → void: Registers a top-level native function.
registertopLevelFunction(String? name, NativeFunctionImpl function, String library, {String? sourceUri, String? signature}) → void: Lower-case alias for registerTopLevelFunction.
resetScriptDeclarations() → void: §U28 / TODO #14 — Evict script-declared entries from the current global environment so a follower executeBundle call starts with the same name-set the first build saw.
revoke(Permission permission) → void: Revokes a permission.
setDebug(bool enabled) → void: Enables or disables debug logging.
toString() → String: A string representation of this object.
inherited
warmup() → void: OPEN B.11 / U25 — Pre-builds the bridge + stdlib infrastructure so the first real execute/executeBundle call does not cold-start mid-test.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

debugBridgedModuleEnvBuildCount → int: Diagnostics / test introspection — number of bridged-module envs built so far (PERF step #2). Increments only on a cache miss.
no setter
debugPooledPackages → Set<String>: Diagnostics / test introspection — the set of package names currently in the process-global pool (including the synthetic _defaultPackage once a legacy register* call has run). Read-only; does not expose the bundles.
no setter
debugWarmParentCacheSize → int: Diagnostics / test introspection — how many warm parents are currently cached for migrated instances (step 8). Lets tests assert that two consecutive executes for the same allowed-set build the parent once.
no setter

Static Methods

debugPooledClassCount(String packageName) → int: Diagnostics / test introspection — the number of bridged classes pooled under packageName across all source URIs (0 if not pooled). Lets tests assert that a freshly-provided package's definitions landed in the pool without exposing the internal bundle type.
debugResetPool() → void: Diagnostics / test introspection — clears the process-global pool and the step-8 warm-parent cache (the migrated-instance parents are keyed on pool contents, so they must be evicted together to stay consistent). Used only by tests that need a pristine pool (both are otherwise immortal for the life of the process). Not part of the normal runtime contract.