D4rt class

The main D4rt interpreter class.

This class provides the primary interface for executing Dart code at runtime. It manages the interpretation environment, handles bridged types, and provides methods for code execution with proper error handling and debugging support.

Example:

final interpreter = D4rt();

// Register a bridged class to make native types available in interpreted code
interpreter.registerBridgedClass(myBridgedClass, 'my_library');

// Execute Dart code
final result = await interpreter.execute(source: '''
  void main() {
    print("Hello from D4rt!");
  }
''');

Constructors

D4rt({bool reuseAcrossRuns = true}): Creates a D4rt interpreter instance. sce43: mirrors the reference's constructor.

Properties

allowedPackages → Set<String>: The packages this instance has been granted via providePackage (process-global pool membership is independent). Step 7.
no setter
bridgedLibraryUris → Set<String>: The set of library URIs that have been registered as bridged.
no setter
bridgesFinalized → bool: Whether finalizeBridges has been called. Step 6.
no setter
classAliases → List<({String aliasName, String library, String targetName})>: Registered class aliases, for module-env registration.
no setter
debugLoadedModuleCount → int: Number of source modules whose parsed unit this instance currently retains. 0 before the first execute or after dispose.
no setter
functionTypedefs → List<({String library, int? maxPositional, String name, int? requiredPositional})>: Registered function typedefs, for module-env registration.
no setter
hashCode → int: The hash code for this object.
no setterinherited
lastErrorTrace → List<D4rtStackFrame>: The interpreted frames the last error to leave this interpreter passed through, innermost first — empty when the last run succeeded, or failed outside any interpreted call.
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
loadedSourceModuleCount → int: The number of source files (file: modules, entry script included) the last run loaded. 0 before the first execute. executeFile reports it as sourcesLoaded (DFIN2).
no setter
onUncaughtError ↔ void Function(Object error, StackTrace stackTrace)?: Execute a parsed SCompilationUnit in the given environment. Called when an error escapes an interpreted callback that the platform invoked, rather than the script's own future chain.
getter/setter pair
reuseAcrossRuns → bool: Whether the cross-run bridge caches are reused between runs.
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

analyze({required String source, Map<String, String>? sources, bool includeBuiltins = false}) → IntrospectionResult: Analyzes the given source code and returns introspection information about all declared functions, classes, variables, enums, and extensions.
checkPermission(dynamic operation) → bool: Checks if any permission in the granted set allows the given operation.
continuedExecute({String? source, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs, String? library}) → dynamic: Execute additional source code in the existing global context.
createBundle(String entryPointPath, {Map<String, String>? explicitSources, String? packageName, String? projectRoot, AstBundlerConfig? bundlerConfig}) → Future<AstBundle>: Creates a distributable AstBundle from a file path.
createBundleFromSource(String source, {String sourcePath = 'main.dart', Map<String, String>? explicitSources, AstBundlerConfig? bundlerConfig}) → Future<AstBundle>: Creates a distributable AstBundle from a source code string.
dispose() → void: Releases the interpreter artifacts retained from the most recent run.
eval(String expression) → dynamic: Evaluates an expression or statement in the context of previously executed code.
execute({String? source, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs, Object? args, String? library, Map<String, String>? sources, String? basePath, bool allowFileSystemImports = false}) → dynamic: Execute the given source code.
executeBundle(AstBundle bundle, {String? entryPoint, String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs}) → dynamic: Executes a pre-made AstBundle using D4rtRunner.
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.
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.
executeProgram(D4rtProgram program, {String name = 'main', List<Object?>? positionalArgs, Map<String, Object?>? namedArgs, Map<String, String>? sources, bool allowFileSystemImports = false}) → dynamic: Runs program as execute would run its source, without parsing it.
finalizeBridges() → void: Runs every queued extension callback (in registration order) and freezes the runner. Step 6.
getConfiguration() → D4rtConfiguration: Returns a complete configuration snapshot of this interpreter instance.
getEnvironmentState() → EnvironmentState?: Returns the current state of the global environment.
grant(Permission permission) → void: Grants a permission for security-sensitive operations.
hasPermission(Permission permission) → bool: Checks if a specific permission is granted.
invoke(String name, List<Object?> positionalArgs, [Map<String, Object?> namedArgs = const {}, Map<String, String>? sources]) → dynamic: Invoke a property or method on the given instance.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
parse(String source, {String? basePath}) → D4rtProgram: Parses source once into a D4rtProgram that executeProgram can run any number of times, on this interpreter or another (woneprpd132, mirrors tom_d4rt).
providePackage(String packageName) → bool: Declares that the bridges for packageName are about to be (or have already been) registered, and reports whether the caller may skip re-registering them. Steps 7–8.
registerBridgedClass(BridgedClass definition, String library, {String? sourceUri}) → void: Registers a bridged class definition for use in interpreted code.
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 for use in interpreted code.
registerBridgedExtension(BridgedExtensionDefinition definition, String library, {String? sourceUri}) → void: Registers a bridged extension for use in interpreted code.
registerClassAlias(String aliasName, String targetName, String library) → void: GEN-074: Registers a class alias (type alias) for use in interpreted code.
registerExtensions(String packageName, void body()) → void: Registers a body callback that runs additional bridge wiring (e.g. registerRelaxers(), registerD4rtRuntimeExtensions(), registerD4rtInterfaceProxyOverrides()) after the main bridge registrations for packageName.
registerFunctionTypedef(String name, String library, {int? requiredPositional, int? maxPositional}) → void: Registers a function typedef so it can be used as a type in D4rt scripts.
registerGenericConstructor(String className, String constructorName, GenericConstructorFactory factory) → void: Registers a generic-constructor factory for className.constructorName. Use '' for the unnamed constructor.
registerGlobalGetter(String name, Object? getter(), String library, {String? sourceUri}) → void: Registers a global getter for use in interpreted code.
registerGlobalSetter(String name, void setter(Object?), String library, {String? sourceUri}) → void: Registers a global setter for a top-level setter in a specific library.
registerGlobalVariable(String name, Object? value, String library, {String? sourceUri}) → void: Registers a global variable for use in interpreted code.
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 factory for baseTypeName (RC-2 generics).
registertopLevelFunction(String? name, NativeFunctionImpl function, String library, {String? sourceUri, String? signature}) → void: Registers a top-level native function for use in interpreted code.
resetScriptDeclarations() → void: §U28 / TODO #14 — Evict script-declared entries from the inner D4rtRunner's global environment so a follower executeBundle call starts with the same name-set the first build saw.
revoke(Permission permission) → void: Revokes a previously granted permission.
setDebug(bool enabled) → void: Enables or disables debug logging for the interpreter.
toString() → String: A string representation of this object.
inherited
validateRegistrations({required String source, Map<String, String>? sources, String? basePath, bool allowFileSystemImports = false}) → List<String>: Validates all bridge registrations by running the given init script and collecting all registration errors without aborting on the first one.
warmup() → void: OPEN B.11 / U25 — Pre-builds the parser + bridge infrastructure so the first real build does not cold-start mid-test under host load.

Operators

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

Static Properties

debugBridgedModuleEnvBuildCount → int: Diagnostics — how many bridged-module environments have been built.
no setter
debugPooledPackages → Set<String>: The names of every package currently pooled process-wide. Step 7.
no setter
debugWarmParentCacheSize → int: The number of distinct warm parents cached for migrated instances. Step 8.
no setter

Static Methods

debugPooledClassCount(String packageName) → int: The number of bridged classes pooled under packageName. Step 7.
debugResetPool() → void: Clears the process-global package pool and warm-parent cache. Step 7/8.