Compose libraries with graphs, add executeLib

CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.3.0
+- (Breaking) Modified public API for defining bridge classes. See Pub example.
+- (Breaking) Relative import URIs may no longer work (it's unclear whether they
+  worked before). Support will be re-added in a future release.
+- (Deprecated) `Runtime.executeNamed()` is deprecated. Use `Runtime.executeLib()`
+  instead.
+- Compiler now uses graphs to compose libraries from imports, exports, and parts,
+  and should now mostly follow the Dart spec.
+- Partial support for `show` and `hide` on imports and exports
+- Support defining `extends`, `implements`, and `with` on bridge classes
+- Support for adding files to the compiler before compiling, for use in bridge
+  libraries to enable exports.
+- Add recursion guard for type resolution
+
 ## 0.2.0
 
 - Partial support for anonymous functions and the Dart runtime type system

README.md

@@ -90,7 +90,7 @@ void main() {
       .asByteData();
   
   final runtime = Runtime(bytecode);
-  print(runtime.executeNamed(0, 'main')); // -> 499500
+  print(runtime.executeLib('package:my_package/main.dart', 'main')); // -> 499500
 }
 ```
 

example/dart_eval_example.dart

@@ -56,22 +56,34 @@ void main(List<String> args) {
     }
   ''';
 
+  // Create a compiler and define the classes' bridge declarations so it knows their structure
   final compiler = Compiler();
   compiler.defineBridgeClasses([$TimestampedTime.$declaration, $WorldTimeTracker$bridge.$declaration]);
 
+  // Compile the source code into a Program containing metadata and bytecode. In a real app, you would likely
+  // compile the Eval code separately and output it to a file using program.write(), sharing only bridge classes
+  // with a local shared library
   final program = compiler.compile({
-    'package:example': {'main.dart': source}
+    'example': {'main.dart': source}
   });
 
-  final runtime = Runtime.ofProgram(program);
-  runtime.registerBridgeFunc('package:example/bridge.dart', 'TimestampedTime.', $TimestampedTime.$new);
-  runtime.registerBridgeFunc('package:example/bridge.dart', 'WorldTimeTracker.', $WorldTimeTracker$bridge.$new);
+  // Create a runtime from the compiled program, and register bridge functions for all static methods and constructors.
+  // Default constructors use "ClassName." syntax.
+  final runtime = Runtime.ofProgram(program)
+    ..registerBridgeFunc('package:example/bridge.dart', 'TimestampedTime.', $TimestampedTime.$new)
+    ..registerBridgeFunc('package:example/bridge.dart', 'WorldTimeTracker.', $WorldTimeTracker$bridge.$new);
 
+  // Call runtime.setup() after registering all bridge functions
   runtime.setup();
 
+  // Specify some args for the function we're about to call. Except for [int]s, [double]s, [bool]s, and [List]s, use
+  // [$Value] wrappers. For named args, specify them in order using null to represent an unspecified arg.
   runtime.args = [$String('USA')];
-  final timeTracker = runtime.executeNamed(0, 'fn') as WorldTimeTracker;
 
+  // Call the function and cast the result to the desired type
+  final timeTracker = runtime.executeLib('package:example/main.dart', 'fn') as WorldTimeTracker;
+
+  // We can now utilize the returned bridge class
   print('UK timezone offset: ' + timeTracker.getTimeFor('UK').timezoneOffset.toString() + ' (from outside Eval!)');
 }
 

lib/src/eval/bridge/declaration.dart

@@ -6,8 +6,9 @@ class BridgeDeclaration {
 }
 
 class DeclarationOrBridge<T extends Declaration, R extends BridgeDeclaration> {
-  DeclarationOrBridge({this.declaration, this.bridge}) : assert(declaration != null || bridge != null);
+  DeclarationOrBridge(this.sourceLib, {this.declaration, this.bridge}) : assert(declaration != null || bridge != null);
 
+  int sourceLib;
   T? declaration;
   R? bridge;
 

lib/src/eval/bridge/declaration/function.dart

@@ -22,7 +22,7 @@ class BridgeParameter {
 @JsonSerializable()
 class BridgeFunctionDef {
   const BridgeFunctionDef(
-      {required this.returns, required this.params, required this.namedParams, this.generics = const {}});
+      {required this.returns, this.params = const [], this.namedParams = const [], this.generics = const {}});
 
   final BridgeTypeAnnotation returns;
   final Map<String, BridgeGenericParam> generics;

lib/src/eval/bridge/runtime_bridge.dart

@@ -1,5 +1,6 @@
 import 'package:dart_eval/dart_eval_bridge.dart';
 import 'package:dart_eval/src/eval/runtime/runtime.dart';
+import 'package:dart_eval/src/eval/shared/stdlib/core/base.dart';
 
 /// A bridge class can be extended inside the dart_eval VM and used both in and outside of it.
 mixin $Bridge<T> on Object implements $Value, $Instance {