Pebble

An educational compiler and bytecode VM for the Pebble programming language.

Pebble is a small imperative language that compiles to bytecode and runs on a custom stack-based virtual machine. The project is designed for learning how compilers work, built incrementally using TDD.

Language Features

• Integers, floats, strings, booleans
• Variables (let declarations, const, reassignment)
• Arithmetic, comparison, bitwise, and logical operators (and, or, not)
• Short-circuiting and / or and chained comparisons (1 < x < 10)
• Control flow: if/else, while, for loops, match
• Collections: lists, dicts, list comprehensions, slicing, tuple unpacking
• Functions (fn, return), default arguments, closures, and generators (yield)
• Async / await (async fn, await)
• Structs, classes with inheritance, and enums
• Error handling: try / catch / finally and throw
• Modules and imports (import, from ... import)
• String interpolation ("hello {name}")
• print() built-in
• Comments (#)
• Curly-brace blocks, newline-delimited statements (no semicolons)

Example

let count = 0
while count < 5 {
    if count > 0 {
        print(count)
    }
    count = count + 1
}

Pipeline

Source -> Lexer -> Parser -> Analyzer -> Module Resolver -> Type Checker -> Compiler -> Optimizer -> VM

See the documentation for a kid-friendly walk-through of each stage.

Quick Start

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Lint and type check
uv run ruff check .
uv run pyright src tests

Using Pebble from Python

from pebble import run_source

print(run_source('print("Hello from Pebble!")'), end="")

run_source, compile_source, check and format_source are Pebble's public API; see Using Pebble from Python.

Documentation

Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pebble-lang/

Releasing

Other projects in the series (PyStack and PyLLM) use a pinned release of this one, not whatever is on main. To publish a change for them:

1. Merge the change to main.
2. Tag it: git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z. A change to the public API bumps the minor version (v0.1.0 → v0.2.0); anything else bumps the patch (v0.1.0 → v0.1.1).
3. In each project that uses it, edit the tag in [tool.uv.sources], run uv lock --upgrade-package <name>, and open a pull request so CI checks the pair together.

Related Projects

This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the series home for the full story.

License

MIT