Beamtalk Documentation

Welcome to the Beamtalk documentation! This guide will help you navigate the design documents and understand how Beamtalk brings Smalltalk's live programming philosophy to the BEAM virtual machine.

Important: Beamtalk is Smalltalk-inspired, not Smalltalk-compatible. We preserve Smalltalk's core ideas (message passing, live environment, uniform syntax) while making pragmatic changes for BEAM and modern development. See Syntax Rationale for details.

---

Quick Start

New to Beamtalk? Start here:

1. Design Principles — The core philosophy guiding all decisions
2. Language Features — Syntax reference and planned features
3. Examples — Simple programs to see the language in action

---

Documentation Overview

Core Language Design

Document	Description
Design Principles	Interactive-first, actors, hot reload, async-first — the foundational ideas
Language Features	Complete syntax reference: messages, blocks, classes, strings
Syntax Rationale	Why we keep certain Smalltalk conventions and diverge from others
Object Model	How "everything is an object" maps to the BEAM (ADR 0005)
Known Limitations	What's not yet supported, with workarounds

Architecture & Implementation

Document	Description
Architecture	Compiler pipeline, runtime, and hot code loading
Testing Strategy	How we test the compiler and runtime

Vision & Planning

Document	Description
Agent-Native Development	AI agents as developers and live actor systems

---

Reading Paths

"I want to understand the language"

1. Design Principles — Philosophy and core ideas
2. Syntax Rationale — Why Beamtalk looks the way it does
3. Language Features — Full syntax reference
4. Examples — See it in practice

"I want to understand how it works"

1. Architecture — Compiler and runtime overview
2. Object Model (ADR 0005) — Smalltalk objects on BEAM
3. Testing Strategy — How we verify correctness

For implementation details, see internal/ documentation.

"I want to build AI agents"

1. Agent-Native Development — Live actor systems for AI agents
2. Design Principles — Live programming for exploration

---

Code Examples

Examples Directory (examples/)

Simple programs demonstrating language features:

• hello.bt — Simple class with a greeting method
• counter.bt — Assignment and arithmetic

Use the REPL to load examples:

$ beamtalk repl
> :load examples/hello.bt
Loaded

Standard Library (stdlib/src/)

The foundational classes implementing Smalltalk's "everything is a message" philosophy:

Class	Description
Object	Base class for value types; Actor for BEAM processes
Block	First-class closures
True / False	Boolean control flow via messages
UndefinedObject	Null object pattern (nil singleton)
Integer	Arbitrary precision arithmetic
String	UTF-8 text with grapheme operations
Array	Fixed-size indexed collection (tuple)
List	Linked list with fast prepend
Set	Unordered unique elements
Dictionary	Key-value map
Regex	Regular expression matching (PCRE2)
DateTime	Date and time operations
JSON	JSON parsing and encoding
Collection	Abstract collection protocol

See stdlib/src/README.md for detailed documentation.

Test Cases (test-package-compiler/cases/)

Comprehensive test cases for language features, each containing:

• .bt source files
• Expected Core Erlang output (snapshots)

Browse these for real-world usage patterns.

---

Contributing

See AGENTS.md in the repository root for:

• Development guidelines
• Code conventions
• How to add new features
• Testing requirements

---

About Beamtalk

Beamtalk is a Smalltalk/Newspeak-inspired language targeting the BEAM (Erlang VM). It combines:

• Smalltalk's simplicity — Everything is a message send (with pragmatic BEAM adaptations)
• BEAM's reliability — Lightweight processes, fault tolerance, hot code reload
• Live development — No compile-deploy-restart cycle

The compiler is written in Rust and generates Core Erlang, which is then compiled to BEAM bytecode.

Repository: github.com/jamesc/beamtalk