ball_engine

Tree-walking interpreter for the Ball programming language.

ball_engine executes Ball programs directly -- no intermediate code generation. It walks the protobuf expression tree, evaluates each node, and dispatches std base functions through a pluggable module-handler system. Every evaluator is async, so I/O, timers, and user-defined await all suspend through Dart's native Future mechanism.

Install

dart pub add ball_engine

Quick start

import 'package:ball_base/ball_base.dart';
import 'package:ball_engine/engine.dart';

Future<void> main() async {
  final program = Program(); // load from .ball.json or build in-memory
  final engine = BallEngine(program, stdout: (line) => print(line));
  await engine.run();
}

Features

Constructor options

BallEngine(
  program,
  stdout: (line) { /* capture output */ },
  stderr: (line) { /* capture errors */ },
  stdinReader: () async => await readLine(),
  args: ['--flag', 'value'],
  moduleHandlers: [StdModuleHandler(), MyCustomHandler()],
  resolver: ModuleResolver(),
  enableProfiling: true,
);

Custom modules

Implement BallModuleHandler to expose your own base functions to Ball code:

class TimeHandler extends BallModuleHandler {
  // Claim the `time` module so the engine routes its calls here.
  @override
  bool handles(String module) => module == 'time';

  // `input` is the function's single argument value; `engine` lets you
  // compose other ball functions. Return type is FutureOr<Object?>.
  @override
  Object? call(String function, Object? input, BallCallable engine) {
    if (function == 'now') return DateTime.now().millisecondsSinceEpoch;
    throw BallRuntimeError('unknown: time.$function');
  }
}

Pass the handler to the engine via moduleHandlers: [TimeHandler()].

Related packages

• @ball-lang/engine -- TypeScript/JavaScript engine (experimental)

Links

• Website: https://ball-lang.dev
• Repository: https://github.com/ball-lang/ball
• Issue tracker: https://github.com/ball-lang/ball/issues

License

MIT