Beamtalk API Reference
The standard library for Beamtalk, where everything is a message send.
See each class page for full API documentation and usage examples.
Choosing a Base Class
When defining a new class, pick one of these three base classes:
| Base class | When to use |
|---|---|
Object | General-purpose reference types — containers, handles, exceptions, and anything with mutable or I/O-bearing state. |
Value | Immutable scalar value types — Boolean, Number, DateTime, Regex, CompiledMethod, StackFrame. Equality is structural; instances are interchangeable. |
Actor | Stateful concurrent objects backed by a gen_server process. Use when an object must own private state and handle concurrent messages safely. |
Choosing a Sequence
Three core sequence types, each tuned for a different access pattern:
| Type | Use for | indexed at: | grows? |
|---|---|---|---|
List | sequential / streaming / stack-like — the default | O(n) | yes (O(1) prepend) |
Array | random access by position; size known up front | O(log n), persistent at:put: | no (fixed size) |
Tuple | Erlang/OTP FFI interop only — not a general-purpose collection | — | — |
Reach for List by default; switch to Array when you index or update by
position (build one from a list with aList asArray). Array is canonical
(content-based =:=/hash), so it works as a Dictionary/Set key.
Class Hierarchy
- ProtoObject Root of the Beamtalk class hierarchy.
- Erlang Gateway to the BEAM ecosystem.
- ErlangModule Proxy for calling functions on a specific Erlang module.
- Object Base class for all Beamtalk objects.
- Actor Base class for process-based objects.
- ClassBuilder Fluent builder for creating and registering Beamtalk classes.
- ReactiveSubprocess Actor for push-mode subprocess delivery.
- Server Abstract Actor subclass for BEAM-level OTP interop.
- Subprocess Actor for interactive bidirectional communication with OS processes.
- TimeoutProxy Transparent forwarding proxy with configurable timeout.
- TranscriptStream Per-workspace shared log with pub/sub semantics.
- AnnouncementNavigation live subscription-graph introspection queries
- Announcer a typed pub/sub dispatcher handle (ADR 0093 Layer 2).
- SystemAnnouncer the singleton system event bus (ADR 0093 Layer 2).
- AtomicCounter named integer counter backed by ETS for lock-free increments.
- BeamtalkInterface Workspace-level reflection and class registry.
- Behaviour Abstract superclass of all class-describing objects.
- BindingsView a live, Dictionary-protocol view over session or workspace
- Block First-class closures (anonymous functions).
- Console the running process's standard I/O (ADR 0099 §1).
- DynamicSupervisor Abstract base class for dynamic OTP supervision trees.
- Ets shared in-memory table for actor state sharing.
- Exception Base class for all exceptions.
- Error Non-resumable exceptions.
- BEAMError Foreign BEAM-specific exceptions.
- ExitError BEAM process exit signal.
- ThrowError BEAM non-local return.
- InstantiationError Incorrect object creation errors.
- RuntimeError Message dispatch and mutation errors.
- TypeError Type mismatch errors.
- BEAMError Foreign BEAM-specific exceptions.
- Error Non-resumable exceptions.
- File File system operations.
- FileHandle a handle to an open file.
- Inspector a live, immutable cursor for navigating into a single object
- Json JSON encoding and decoding.
- Logger structured logging via Erlang's logger.
- OS shell command execution.
- Pid BEAM process identifier.
- Port BEAM port identifier.
- Program the running program/invocation (ADR 0099 §2).
- Protocol Runtime protocol registry queries (ADR 0068 Phase 2c).
- Reference BEAM unique reference.
- Session a first-class handle to a REPL session (ADR 0081).
- Stream Lazy, closure-based sequences.
- Subscription the unsubscribe token returned by `when:do:` et al (ADR 0093).
- Supervisor Abstract base class for static OTP supervision trees.
- Symbol Atomic identifiers.
- System OS environment, platform detection, and process info.
- SystemNavigation Class-registry navigation queries ("who implements X",
- TestResult Structured result from running a test suite.
- TestRunner Programmatic test execution returning structured results.
- Time current time accessors.
- Timer schedule delayed and repeating work via Erlang timer primitives.
- Tracing Actor observability, trace context, and performance telemetry.
- UndefinedObject The absence of a value.
- Value Base class for immutable value types.
- Announcement base event type for the typed Observer substrate (ADR 0093).
- ActorSpawned system event announced when a Beamtalk actor starts (ADR 0093).
- ActorStopped system event announced when a Beamtalk actor terminates (ADR 0093).
- BindingChanged system event announced when a workspace binding changes (ADR 0093).
- ClassLoaded system event announced when a class is loaded or redefined (ADR 0093).
- ClassRemoved system event announced when a class is removed (ADR 0093).
- FlushCompleted system event announced when `Workspace flush` finishes (ADR 0093).
- ObjectStateChanged system event announced when a *watched* actor commits a
- SupervisionChildAdded system event announced when a supervisor starts a
- SupervisionChildCrashed system event announced when a supervised child
- Boolean Abstract superclass for True and False.
- ChangeEntry One recorded in-memory method mutation (ADR 0082 Phase 1).
- ChangeLog Navigable view of the workspace's pending in-memory changes
- Collection Abstract superclass for all collections.
- Array Fixed-size indexed collection with O(log n) random access.
- Bag Immutable multiset (unordered collection allowing duplicate elements).
- Binary byte-level data and serialization.
- String UTF-8 text operations.
- Dictionary Immutable key-value collection.
- Interval An arithmetic sequence of integers.
- List Ordered collection of elements.
- Set Unordered collection of unique elements.
- Tuple Erlang interop type for fixed-size heterogeneous collections.
- CompiledMethod Method introspection object.
- DateTime UTC date and time via Erlang calendar/os modules.
- InspectorField an immutable record for one drillable field of an inspected
- Number Abstract superclass for numeric types.
- Package First-class package reflection for the Beamtalk system.
- ProcessNavigation live supervision-tree introspection queries (ADR 0092).
- Queue O(1) amortised FIFO queue backed by Erlang's `:queue` module.
- Random Random number generation.
- Regex Compiled regular expressions via Erlang re module (PCRE2).
- Result Value type for expected success/failure outcomes (ADR 0060).
- StackFrame A single frame in an exception stack trace.
- SubscriptionNode an immutable snapshot record for one live subscription on
- SupervisionNode an immutable snapshot record for one process in the live
- SupervisionSpec Value type describing how to start an actor as a supervised child.
- SupervisionTree a navigable snapshot of the live supervision tree (ADR 0092).
- TestCase Base class for BUnit test cases.
- Announcement base event type for the typed Observer substrate (ADR 0093).
- WorkspaceInterface Per-workspace actor introspection and binding container.
- Actor Base class for process-based objects.
All Classes
- ActorActor — Base class for process-based objects.
- ActorSpawnedActorSpawned — system event announced when a Beamtalk actor starts (ADR 0093).
- ActorStoppedActorStopped — system event announced when a Beamtalk actor terminates (ADR 0093).
- AnnouncementAnnouncement — base event type for the typed Observer substrate (ADR 0093).
- AnnouncementNavigationAnnouncementNavigation — live subscription-graph introspection queries
- AnnouncerAnnouncer — a typed pub/sub dispatcher handle (ADR 0093 Layer 2).
- ArrayArray — Fixed-size indexed collection with O(log n) random access.
- AtomicCounterAtomicCounter — named integer counter backed by ETS for lock-free increments.
- BEAMErrorBEAMError — Foreign BEAM-specific exceptions.
- BagBag — Immutable multiset (unordered collection allowing duplicate elements).
- BeamtalkInterfaceBeamtalkInterface — Workspace-level reflection and class registry.
- BehaviourBehaviour — Abstract superclass of all class-describing objects.
- BinaryBinary — byte-level data and serialization.
- BindingChangedBindingChanged — system event announced when a workspace binding changes (ADR 0093).
- BindingsViewBindingsView — a live, Dictionary-protocol view over session or workspace
- BlockBlock — First-class closures (anonymous functions).
- BooleanBoolean — Abstract superclass for True and False.
- ChangeEntryChangeEntry — One recorded in-memory method mutation (ADR 0082 Phase 1).
- ChangeLogChangeLog — Navigable view of the workspace's pending in-memory changes
- CharacterCharacter — Unicode character (codepoint) wrapper.
- ClassClass — A concrete class in the Beamtalk system.
- ClassBuilderClassBuilder — Fluent builder for creating and registering Beamtalk classes.
- ClassLoadedClassLoaded — system event announced when a class is loaded or redefined (ADR 0093).
- ClassRemovedClassRemoved — system event announced when a class is removed (ADR 0093).
- CollectionCollection — Abstract superclass for all collections.
- CompiledMethodCompiledMethod — Method introspection object.
- ConsoleConsole — the running process's standard I/O (ADR 0099 §1).
- DateTimeDateTime — UTC date and time via Erlang calendar/os modules.
- DictionaryDictionary — Immutable key-value collection.
- DynamicSupervisorDynamicSupervisor — Abstract base class for dynamic OTP supervision trees.
- ErlangErlang — Gateway to the BEAM ecosystem.
- ErlangModuleErlangModule — Proxy for calling functions on a specific Erlang module.
- ErrorError — Non-resumable exceptions.
- EtsEts — shared in-memory table for actor state sharing.
- ExceptionException — Base class for all exceptions.
- ExitErrorExitError — BEAM process exit signal.
- FalseFalse — The false boolean value.
- FileFile — File system operations.
- FileHandleFileHandle — a handle to an open file.
- FloatFloat — Floating-point arithmetic and operations.
- FlushCompletedFlushCompleted — system event announced when `Workspace flush` finishes (ADR 0093).
- InspectorInspector — a live, immutable cursor for navigating into a single object
- InspectorFieldInspectorField — an immutable record for one drillable field of an inspected
- InstantiationErrorInstantiationError — Incorrect object creation errors.
- IntegerInteger — Whole number arithmetic and operations.
- IntervalInterval — An arithmetic sequence of integers.
- JsonJson — JSON encoding and decoding.
- ListList — Ordered collection of elements.
- LoggerLogger — structured logging via Erlang's logger.
- MetaclassMetaclass — The class of all metaclass objects in the Beamtalk system.
- NumberNumber — Abstract superclass for numeric types.
- OSOS — shell command execution.
- ObjectObject — Base class for all Beamtalk objects.
- ObjectStateChangedObjectStateChanged — system event announced when a *watched* actor commits a
- PackagePackage — First-class package reflection for the Beamtalk system.
- PidPid — BEAM process identifier.
- PortPort — BEAM port identifier.
- ProcessNavigationProcessNavigation — live supervision-tree introspection queries (ADR 0092).
- ProgramProgram — the running program/invocation (ADR 0099 §2).
- ProtoObjectProtoObject — Root of the Beamtalk class hierarchy.
- ProtocolProtocol — Runtime protocol registry queries (ADR 0068 Phase 2c).
- QueueQueue — O(1) amortised FIFO queue backed by Erlang's `:queue` module.
- RandomRandom — Random number generation.
- ReactiveSubprocessReactiveSubprocess — Actor for push-mode subprocess delivery.
- ReferenceReference — BEAM unique reference.
- RegexRegex — Compiled regular expressions via Erlang re module (PCRE2).
- ResultResult — Value type for expected success/failure outcomes (ADR 0060).
- RuntimeErrorRuntimeError — Message dispatch and mutation errors.
- ServerServer — Abstract Actor subclass for BEAM-level OTP interop.
- SessionSession — a first-class handle to a REPL session (ADR 0081).
- SetSet — Unordered collection of unique elements.
- StackFrameStackFrame — A single frame in an exception stack trace.
- StreamStream — Lazy, closure-based sequences.
- StringString — UTF-8 text operations.
- SubprocessSubprocess — Actor for interactive bidirectional communication with OS processes.
- SubscriptionSubscription — the unsubscribe token returned by `when:do:` et al (ADR 0093).
- SubscriptionNodeSubscriptionNode — an immutable snapshot record for one live subscription on
- SupervisionChildAddedSupervisionChildAdded — system event announced when a supervisor starts a
- SupervisionChildCrashedSupervisionChildCrashed — system event announced when a supervised child
- SupervisionNodeSupervisionNode — an immutable snapshot record for one process in the live
- SupervisionSpecSupervisionSpec — Value type describing how to start an actor as a supervised child.
- SupervisionTreeSupervisionTree — a navigable snapshot of the live supervision tree (ADR 0092).
- SupervisorSupervisor — Abstract base class for static OTP supervision trees.
- SymbolSymbol — Atomic identifiers.
- SystemSystem — OS environment, platform detection, and process info.
- SystemAnnouncerSystemAnnouncer — the singleton system event bus (ADR 0093 Layer 2).
- SystemNavigationSystemNavigation — Class-registry navigation queries ("who implements X",
- TestCaseTestCase — Base class for BUnit test cases.
- TestResultTestResult — Structured result from running a test suite.
- TestRunnerTestRunner — Programmatic test execution returning structured results.
- ThrowErrorThrowError — BEAM non-local return.
- TimeTime — current time accessors.
- TimeoutProxyTimeoutProxy — Transparent forwarding proxy with configurable timeout.
- TimerTimer — schedule delayed and repeating work via Erlang timer primitives.
- TracingTracing — Actor observability, trace context, and performance telemetry.
- TranscriptStreamTranscriptStream — Per-workspace shared log with pub/sub semantics.
- TrueTrue — The true boolean value.
- TupleTuple — Erlang interop type for fixed-size heterogeneous collections.
- TypeErrorTypeError — Type mismatch errors.
- UndefinedObjectUndefinedObject — The absence of a value.
- ValueValue — Base class for immutable value types.
- WorkspaceInterfaceWorkspaceInterface — Per-workspace actor introspection and binding container.