ball_base

Core protobuf types and std module builders for the Ball programming language.

ball_base is the foundation package that every Ball tool depends on. It exposes the generated protobuf types defined in proto/ball/v1/ball.proto, canonical builders for the standard-library modules (std, std_collections, std_io, std_memory, std_concurrency, std_convert, std_fs, std_time), and re-exports the Editions-capable protobuf runtime from ball_protobuf (which was extracted into its own package).

Install

dart pub add ball_base

Quick start

import 'package:ball_base/ball_base.dart';

void main() {
  // Build a Program that imports the universal std module.
  final program = Program()
    ..modules.addAll([buildStdModule(), buildStdCollectionsModule()]);

  print('Modules: ${program.modules.map((m) => m.name).join(', ')}');
}

What's exported

Export	Purpose
`Program`, `Module`, `Expression`, `FunctionDefinition`, `Literal`, ...	Buf-generated `ball.v1` proto types
`DescriptorProto`, `FieldDescriptorProto`	Re-exported `google.protobuf` descriptor types
`buildStdModule()`	Universal `std` module (arithmetic, comparison, logic, bitwise, strings, math, control flow, type ops)
`buildStdCollectionsModule()`, `buildStdMemoryModule()`	`std_collections` (list/map) and `std_memory` (linear memory for C/C++ interop)
`buildStdIoModule()`, `buildStdConcurrencyModule()`, `buildStdConvertModule()`, `buildStdFsModule()`, `buildStdTimeModule()`	The platform std modules: io, concurrency, convert, fs, time
`buildBallProtoModule()`	The `ball_proto` module
`marshal`, `unmarshal`, Editions resolver, …	Re-exported from `ball_protobuf`
`BallFile`, `decodeBallFileBinary`, `encodeBallFileJson`, …	Read/write `.ball.json` / `.ball.bin` (Any-enveloped `Program`/`Module`)
`analyzeCapabilities`, `checkPolicy`, `analyzeTermination`	Static capability + termination analysis over modules

Design notes

Every Ball program is a single protobuf message. This package provides the types needed to read, write, and transform those messages.
The std module builders are language-agnostic: the same proto definition is shared by every target compiler and engine (Dart, C++, and more).
All generated files under lib/gen/** are produced by buf generate. Do not edit them by hand.

License

MIT

Libraries

ball_base: Cross-language standard library for the ball programming language.
ball_file: Self-describing ball-file envelope.
ball_proto: ball_proto module builder — protobuf compatibility layer for Ball programs.
cli_core: Portable Ball CLI verbs — the single source of truth for the report text produced by ball info, ball validate, ball tree, ball audit, and ball version.
gen/ball/v1/ball.pb
gen/ball/v1/ball.pbenum
gen/ball/v1/ball.pbjson
gen/google/protobuf/descriptor.pb
gen/google/protobuf/descriptor.pbenum
gen/google/protobuf/descriptor.pbjson
gen/google/protobuf/struct.pb
gen/google/protobuf/struct.pbenum
gen/google/protobuf/struct.pbjson
std: Universal std base module builder for the ball programming language.
std_collections: std_collections base module builder for the ball programming language.
std_concurrency: std_concurrency base module builder for the ball programming language.
std_convert: std_convert base module builder for the ball programming language.
std_fs: std_fs base module builder for the ball programming language.
std_io: std_io base module builder for the ball programming language.
std_memory: std_memory base module builder for the ball programming language.
std_time: std_time base module builder for the ball programming language.