The Zebra Programming Language

A guide to Zebra from fundamentals through advanced patterns, for experienced programmers learning a new language.

Zebra is a statically-typed, compiled language with Python-flavoured syntax (by way of Cobra). It compiles to Zig, and from there to native code. The language and compiler live at github.com/torial/zebra-language; this book's source is at github.com/torial/zebra-language-book.

How the book is organised

Where to start

• New to Zebra? Start with 01: Getting Started and read Part 1 in order.
• In a hurry? Read the 30-Minute Quickstart, then keep the Syntax Cheat Sheet open while you work.
• Coming from an OOP language? Chapters 07–10b, then 11 and 12.
• Interested in safety features? Chapters 11 (nil tracking), 12 (results), 14 (contracts), 14b (lifetimes).

Use the sidebar (or the ← / → keys) to move between chapters, and the search icon (or S) to search the whole book.

Status

The chapters are re-verified against the current Zebra compiler on a rolling basis; validate-examples.py in the repository is the source of truth for which code examples compile. Found a mistake? See CONTRIBUTING.md.

01: Getting Started

Audience: All
Time: 30 minutes
Prerequisites: None
You'll learn: Install Zebra, run your first program, understand the toolchain

The Big Picture

Zebra is a modern, statically-typed language that prioritizes safety, clarity, and correctness. It combines ideas from Python, C#, Objective-C, and Eiffel into a pragmatic language for building robust systems.

This book teaches you to write Zebra code fluently. By the end, you'll understand:

• How Zebra's type system catches bugs at compile time
• Why nil tracking and error handling are first-class citizens
• How to write clean, expressive code that reads almost like pseudocode

Let's get your environment set up and run your first program.

What is Zebra?

Short version: A statically-typed language that feels dynamic, with compile-time safety guarantees that prevent entire categories of bugs.

Key properties:

• Compiled — Zebra code compiles to Zig (which then compiles to machine code)
• Strongly typed — Types are checked at compile time, preventing type mismatches
• Nil-safe — You explicitly mark values that can be nil, preventing null pointer errors
• Error-aware — A function that can fail says so (throws); every caller either handles the error (catch) or passes it on explicitly (?), so a failure cannot be silently dropped
• Expressive — Clear, readable syntax that emphasizes intent over cleverness

Who uses it: People building systems where reliability matters (CLI tools, servers, data processing, embedded systems).

Installation

Which Zebra this book targets. The book tracks the language as of Zebra 0.9.0-rc3. Anything older — including 0.9.0-rc1 and rc2 — lacks parts of what the later chapters teach (the GUI chapter's toolbars, trees, g.scope and hotkeys, among others), so install rc3 or newer. zebra --version tells you what you have.

A release is one folder: the zebra compiler, the Zig toolchain it was built and tested with, the language guide and the examples. You do not need to install Zig separately — Zebra compiles your program to Zig and builds it with the bundled copy.

Windows (PowerShell)

irm https://raw.githubusercontent.com/torial/zebra-language/main/install/install.ps1 | iex

This installs to %USERPROFILE%\.zebra\current and adds it to your user PATH. Open a new terminal so the PATH change takes effect, then:

zebra --version

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/torial/zebra-language/main/install/install.sh | sh

This installs to ~/.zebra/current and prints the export PATH=... line to add to your shell profile (~/.bashrc, ~/.zshrc). Add it, open a new terminal, then run zebra --version.

Updating

zebra up            # download the latest release, verify it, swap it in
zebra up --check    # only report whether a newer release exists

Manual install

Download the archive for your platform from the Releases page, unpack it anywhere, and put that folder on your PATH.

From source

Building from source needs Zig 0.16.0 on your PATH (other versions are not supported):

git clone https://github.com/torial/zebra-language.git
cd zebra-language
zig build

The compiler is zig-out/bin/zebra (zebra.exe on Windows). Add zig-out/bin to your PATH so zebra works from any directory. A source build uses the Zig on your PATH to build your programs too.

Your First Program

Create a file named hello.zbr:

# file: hello.zbr
# teaches: hello world, the print function
# chapter: 01-Getting-Started

def main()
    print("Hello, Zebra!")

Run it:

zebra hello.zbr

Output:

Hello, Zebra!

What just happened?

1. def main() — Defined the entry point function. Zebra runs main automatically when the program starts.
2. print("...") — Printed text to the console.
3. zebra hello.zbr — Compiled and ran the program.

That's the whole program. No class wrapper, no boilerplate.

If you're new to programming

A function is a reusable block of code. main is special — it runs automatically when you start the program.

A statement is an instruction. print("Hello, Zebra!") is a statement that outputs text.

Larger programs often group related code into classes (Chapter 07). Small scripts don't need them.

If you know Python

# Python
print("Hello, World!")

# Zebra — same call syntax
print("Hello, Zebra!")

Where Python's entry point is implicit (top-level statements run at import), Zebra's is explicit (you define main). The clarity scales: as programs grow you can group code into classes and modules without reshaping the entry point.

Verbosity dial — annotations are optional when the type is obvious

Zebra has full type inference. You can write either:

def main()
    var name: str = "World"        # explicit — annotation aids the reader
    var age: int = 30
    var pi: float = 3.14159
    print("${name} is ${age}")

or, equivalently:

def main()
    var name = "World"             # inferred from the literal
    var age = 30
    var pi = 3.14159
    print("${name} is ${age}")

Both compile to the same Zig. Use annotations when they aid the reader (function signatures, public class fields, hairy generic returns) and drop them when the right-hand side already makes the type obvious (literals, named-constructor calls, expressions whose return type is plain). The book mostly uses the inferred form going forward; you'll see explicit annotations where they earn their keep.

You can also still use the class-based entry point if you prefer it (older code does):

class Main
    static
        def main
            print("Hello, Zebra!")

Both forms work. Bare def main() is the recommended default for scripts and small programs.

The Toolchain

Zebra's workflow is:

hello.zbr (Zebra code)
    ↓
zebra compiler
    ↓
hello.zig (Zig code)
    ↓
zig compiler
    ↓
hello.exe (Executable)
    ↓
Run: ./hello

Why two steps? Zebra targets Zig because Zig is:

• Low-level (good for systems programming)
• Safe (catches undefined behavior at compile time)
• Explicit (no hidden magic)
• Fast (compiles to efficient machine code)

As a Zebra programmer, you mostly ignore the Zig step. You write .zbr, run zebra <file>, and get a fast executable.

Common Commands

# Compile and run
zebra hello.zbr

# Fast check: parse and type-check only (~60 ms), no Zig build.
# It can pass on a program that would still fail to build -- use --check-full for that.
zebra -c hello.zbr

# Full check: everything short of running (the front end plus Zig's analysis)
zebra --check-full hello.zbr

# Optimised build (the default is a debug build)
zebra --release hello.zbr

# Run the def test_*() functions in a file
zebra test hello.zbr

# Keep the generated Zig for inspection
zebra --emit-zig --output-dir out hello.zbr

# Every command and flag
zebra --help

Flags are exact: whole words take two dashes (--release), single letters one (-c), and an unrecognised flag is an error rather than being ignored.

Your Second Program (A Little Interesting)

# file: greet.zbr
# teaches: variables, string interpolation
# chapter: 01-Getting-Started

def main()
    var name = "World"
    print("Hello, ${name}!")

Output:

Hello, World!

What's new?

• var name = "World" — Declared a variable named name and initialized it with "World". The type str is inferred from the literal; you could also write var name: str = "World" if you wanted to make the type explicit.
• "Hello, ${name}!" — String interpolation: ${name} is replaced with the value of name.

Understanding Errors

When you make a mistake, Zebra tells you clearly:

def main()
    var count = 5
    print("Hello " + count)  # ❌ Can't add string + number

Error:

greet.zbr:3:11: error: cannot concatenate 'str' and 'int' — call .toString() on it, or use string interpolation
    print("Hello " + count)  # ❌ Can't add string + number
          ^

What it means:

• File and line: greet.zbr:3:11 — error at line 3, column 11, pointing at the start of "Hello "
• Error type: "cannot concatenate 'str' and 'int'" — + doesn't mix strings and numbers in Zebra
• The problem: + expects both sides to be strings (or both numbers), but got "Hello " (a string) and count (an int)

Fix: Use string concatenation:

print("Hello ".concat(5.toString()))

Or use string interpolation:

print("Hello ${5}")

Project Structure (Thinking Ahead)

As programs grow, organize them:

my-project/
├── main.zbr          # Entry point
├── utils.zbr         # Helper functions
├── data.zbr          # Data structures
└── lib/
    └── db.zbr        # Database utilities

Later chapters will show how to use multiple files. For now, keep everything in one .zbr file.

Using Other Files: use and exposing

When your program spans multiple files, Zebra's use statement imports another module:

# file: math_utils.zbr
def square(n: int): int
    return n * n

def cube(n: int): int
    return n * n * n

# file: main.zbr
use math_utils exposing square

def main()
    var answer = square(5)
    print(answer)  # 25

Naming note: inside an ensure block (Chapter 14), result means the function's return value. Everywhere else it is an ordinary name, so var result = ... is fine — but avoid it in a function that has an ensure, where it would be ambiguous to a reader.

Selective Imports with exposing

use math_utils brings the module into scope as math_utils.square(5). Adding exposing square lifts the name in directly so you can call square(5) without the prefix. You can expose multiple names at once:

use math_utils exposing square, cube

This keeps your code clean when you use many names from a module. You'll see use...exposing extensively in later chapters.

Exercises

Exercise 1: Customize the Greeting

Modify hello.zbr to:

1. Declare a variable for your name
2. Print a greeting using that variable

def main()
    var my_name = "Alice"
    print("Hello! My name is ${my_name}.")

Hello! My name is Alice.

Exercise 2: Combine Multiple Variables

Create a program that:

1. Declares three variables: first_name, last_name, and age
2. Prints a sentence combining all three

def main()
    var first_name = "Bob"
    var last_name = "Smith"
    var age = 30
    print("My name is ${first_name} ${last_name} and I'm ${age} years old.")

My name is Bob Smith and I'm 30 years old.

Next Steps

• → 02-Values-and-Types — Dive into Zebra's type system
• → 03-Collections — Work with Lists and HashMaps
• 🏋 Project-1-CLI-Tool — Build something real

Key Takeaways

• Zebra is compiled — Code becomes fast executables
• Entry point is explicit — Every program defines main (top-level def main(), or Main.main inside a class for larger programs)
• Type annotations are optional — Use them where they aid the reader; lean on inference when the right-hand side is obvious
• Strings use interpolation — "${variable}" is easier to read than concatenation
• Errors are clear — The compiler helps you fix problems
• Simple programs are simple — Print and variables are enough for Hello World

Troubleshooting

"zebra: command not found" → Zebra isn't in your PATH. Check the installation instructions for your OS.

"error: file not found: hello.zbr" → Make sure you're in the directory with hello.zbr. Try: ls hello.zbr

"error: cannot concatenate 'str' and 'int'" → You mixed types (like string + number). Use toString() or string interpolation instead.

Program compiles but doesn't run → The executable was created but you need to run it. Try: ./hello (Unix/Mac) or hello.exe (Windows)

Ready? Head to 02-Values-and-Types and learn the full type system.

02: Values and Types

Audience: All
Time: 90 minutes
Prerequisites: 01-Getting-Started
You'll learn: Zebra's type system, declaring variables, type inference, value vs. reference semantics

The Big Picture

Every value in Zebra has a type. The type tells you:

• What kind of data it holds
• What operations you can perform on it
• How much memory it uses
• Whether it can be nil

Zebra's type system is your best friend—it catches mistakes at compile time instead of in production.

Basic Types

Integers

# file: 02_integers.zbr
# teaches: integer types, arithmetic
# chapter: 02-Values-and-Types

def main()
    var age = 25
    var population = 8_000_000_000     # Underscores for readability
    var tiny: int8 = 100               # explicit narrow type
    var huge: int64 = 9_223_372_036_854_775_807

    print(age)
    print(population)
    print(tiny)
    print(huge)

Integer types:

• int — Default integer (usually 64-bit)
• int8, int16, int32, int64 — Specific sizes
• uint, uint8, etc. — Unsigned (non-negative) integers

Arithmetic:

var x = 10
var y = 3
print(x + y)  # 13
print(x - y)  # 7
print(x * y)  # 30
print(x / y)  # 3 (integer division)
print(x % y)  # 1 (remainder)

When a Result Doesn't Fit: Overflow

Every integer type has a range — a byte holds 0 to 255, an int8 holds -128 to 127, an int holds about ±9.2 × 10¹⁸. If +, - or * produces a value outside the range, the program stops rather than carry on with a wrong number:

# file: 02_overflow_trap.zbr
# teaches: integer overflow stops the program
# chapter: 02-Values-and-Types

def add_ten(b: byte): byte
    return b + 10

def main()
    print(add_ten(100))    # 110
    print(add_ten(250))    # 260 does not fit in a byte: the program stops here
    print("not reached")

110
thread 20484 panic: integer overflow

This holds in every build, including zebra --release — an optimised program does not quietly wrap. When wrapping or clamping is what you want (hashes, checksums, colour channels, counters that roll over), say so with an operator:

# file: 02_wrap_saturate.zbr
# teaches: wrapping (+% -% *%) and saturating (+| -| *|) arithmetic
# chapter: 02-Values-and-Types

def main()
    var b: byte = 250
    print(b +% 10)     # 4    -- wraps around past 255
    print(b +| 10)     # 255  -- saturates: clamps at the top
    var s: int8 = -128
    print(s -| 1)      # -128 -- clamps at the bottom
    print(-%s)         # -128 -- wrapping negation

They are Zig's operators with Zig's spelling, and they work on integers only.

Mixing Integer Types

When two different integer types meet in arithmetic, the result is the wider type — the same rule for + - * / %, for & | ^, and for the wrapping and saturating forms:

# file: 02_mixing_ints.zbr
# teaches: how two integer types combine
# chapter: 02-Values-and-Types

def main()
    var b: byte = 250
    var n: int = 1000
    var t: int8 = -5
    print(b + n)       # 1250 -- byte with int is an int
    print(b + t)       # 245  -- byte with int8 is an int16 (a signed type that holds both)
    print(b + 3)       # 253  -- a plain literal takes the other side's type

Three things the compiler refuses, each with a message naming the fix:

• A literal that does not fit the other side. k + 300 with a byte k — 300 is not a byte. The check is by value, so k + (300 - 200) is fine and k + 100 * 3 is not.
• A result that would have to narrow on its own. b = b + n with a byte b and an int n produces an int, and an int does not fit back into a byte silently. Convert it yourself (see Narrowing below).
• uint beside a signed type. No signed type holds every uint value, so u + n asks you to convert one side first.

error: 300 does not fit in 'byte' (0..255), the type of the other operand of '+'
error: type mismatch: expected byte, found int -- an int does not narrow to a byte on its own; use `.toByte()` (low 8 bits)
error: cannot mix 'uint' and 'int' in arithmetic: no signed type holds every uint value -- convert one side first (`.toInt()` on the uint, checked)

Literal Suffixes

A suffix gives a literal its type, and the variable it initialises takes that type too:

# file: 02_literal_suffixes.zbr
# teaches: typed literals
# chapter: 02-Values-and-Types

def main()
    var a = 300_i16        # an int16
    var b = 5_u8           # a byte (uint8)
    var c = 7u             # a uint -- the underscore is optional
    var mask = 0xFF_u8     # hex works the same way
    var f = 1.5_f32        # a float32
    print(a)               # 300
    print(b +% 255_u8)     # 4 -- b really is a byte, so this wraps at 255
    print(c)               # 7
    print(mask)            # 255
    print(f)               # 1.5

Integer suffixes are _i and _u (the 64-bit int and uint) or either with a width — 8, 16, 32, 64 or 128. The literal must fit its type: 300_u8 and 128_i8 are refused (-128_i8, int8's minimum, is fine). Two spellings look alike and are not: in a decimal number a bare _16 is a digit separator (300_16 is 30016), while in hex a bare size is the signed type (0xFF_32 is 255 as an int32).

Floating Point

# file: 02_floats.zbr
# teaches: float types, precision
# chapter: 02-Values-and-Types

def main()
    var pi = 3.14159
    var precise: float64 = 3.141592653589793

    print(pi)
    print(precise)

    # Arithmetic
    var result = pi * 2.0
    print(result)

Float types:

• float — Default floating point (usually 64-bit)
• float32, float64 — Specific precision

Booleans

# file: 02_bools.zbr
# teaches: boolean values, logic
# chapter: 02-Values-and-Types

def main()
    var is_ready = true
    var is_finished = false

    print(is_ready)
    print(is_finished)

    # Logic
    print(true and false)  # false
    print(true or false)  # true
    print(not true)  # false

Strings

# file: 02_strings.zbr
# teaches: string type, string operations
# chapter: 02-Values-and-Types

def main()
    var greeting = "Hello"
    var name = "World"

    print(greeting)
    print(greeting.len)  # 5
    print(greeting.upper())  # HELLO
    print(name.lower())  # world

    # Concatenation
    var message = greeting.concat(" ").concat(name)
    print(message)  # Hello World

String methods (we'll cover these fully in Chapter 06):

• .len — Length
• .upper() — Uppercase
• .lower() — Lowercase
• .concat() — Concatenate
• .contains() — Check for substring
• .split() — Split by delimiter

Tuples — Multi-Value Bundles

A tuple holds two or more values of possibly different types, packed together. Useful for returning multiple results from a function or pairing values without writing a struct.

# file: 02_tuples.zbr
# teaches: tuple types, literals, destructuring, and indexing
# chapter: 02-Values-and-Types

def minmax(a: int, b: int): (int, int)
    if a < b
        return (a, b)
    return (b, a)

def main()
    # Positional destructure into named locals
    var (lo, hi) = minmax(7, 3)
    print(lo)  # 3
    print(hi)  # 7

    # Hold as a tuple value, index into it
    var t = minmax(1, 9)
    print(t.0)  # 1
    print(t.1)  # 9

    # Mixed types work — (str, int), (float, bool), etc.
    var pair: (str, int) = ("alice", 42)
    print(pair.0)  # alice
    print(pair.1)  # 42

Rules:

• A tuple type uses parens with commas: (int, int), (str, int), (float, bool, bool).
• A tuple literal uses the same syntax: (7, 3), ("alice", 42).
• Destructure with var (x, y) = expr — binds names positionally.
• Index with .0, .1, .2 (integer literal after ., zero-based).
• For lists of tuples (List((str, int))), the for-loop for k, v in list destructures automatically — see Chapter 03.

Tuples are the right tool when the pair is transient (returning two values from one function) or structural (a coordinate pair). For values you'll pass through many functions or attach methods to, a struct (Chapter 07b) reads better.

Declaring Variables

Type Inference (the default)

Zebra infers the type from the right-hand side. Most variables don't need an annotation:

var age = 25          # Inferred as int
var name = "Alice"    # Inferred as str
var active = true     # Inferred as bool
var pi = 3.14         # Inferred as float

Explicit Types (when they aid the reader)

You can always pin the type explicitly. Reach for this when:

• the right-hand side is a function call whose return type isn't obvious to a reader
• you want a different concrete width (int8, float32) than inference would pick
• the variable starts as nil or undefined and inference can't narrow it

var age: int = 25                          # redundant; inference would do
var payment_amount: float = compute_total()  # earns its keep — return type isn't visible
var counter: int8 = 0                      # narrower than the default int
var maybeUser: User? = nil                 # required: nil alone has no type

The book uses inference by default and adds annotations only where they earn their keep.

Naming Conventions

Use snake_case for variables:

var user_id = 42           # ✅ Good
var UserID = 42            # ❌ Avoid (that's for classes)
var user_id_number = 42    # ✅ Clear but verbose
var uid = 42               # ❌ Too abbreviated

Comparison and Equality

# file: 02_comparisons.zbr
# teaches: comparison operators
# chapter: 02-Values-and-Types

def main()
    var x = 10
    var y = 20

    print(x == y)  # false (equal)
    print(x != y)  # true (not equal)
    print(x < y)  # true (less than)
    print(x > y)  # false (greater than)
    print(x <= y)  # true (less or equal)
    print(x >= y)  # false (greater or equal)

    var name = "Alice"
    print(name == "Alice")  # true
    print(name == "Bob")  # false

Type Conversions

Implicit Conversion (When Safe)

var small: int8 = 100
var big: int = small  # ✅ Fine: int8 → int is always safe

Narrowing: Choosing What Happens to Values That Don't Fit

Going from a wider integer to a narrower one is always explicit, and there are two ways to do it — decide which one you mean:

# file: 02_narrowing.zbr
# teaches: checked vs truncating narrowing
# chapter: 02-Values-and-Types

def main()
    var n = 300
    print(n.toByte())      # 44  -- toByte() keeps the low 8 bits
    var small = 200
    print(small.toUint8()) # 200 -- fits, so the checked form returns it
    print(n.toUint8())     # 300 does not fit: the program stops here

44
200
thread 24072 panic: integer conversion out of range: 300 does not fit in byte

toInt8(), toInt16(), toInt32(), toInt64(), toUint8() … toUint64() are checked: they return the value when it fits and stop the program when it does not. toByte() is the one that deliberately keeps the low bits.

Explicit Conversion

# file: 02_conversions.zbr
# teaches: type conversion
# chapter: 02-Values-and-Types

def main()
    var x = 42
    var s = x.toString()      # int → str
    print(s)

    var pi = 3.14
    var i = pi.toInt()        # float → int (loses decimal)
    print(i)  # 3

    var flag = true
    var b = flag.toString()   # bool → str
    print(b)  # true

Nullable Types (Introduction)

Sometimes a value might not exist. Zebra uses ? to mark this:

# file: 02_nullables.zbr
# teaches: nullable types introduction
# chapter: 02-Values-and-Types

def main()
    var name: str? = "Alice"    # Can hold str or nil
    var empty: str? = nil       # Explicitly nil

    # You must check before using
    if name != nil
        print(name)  # Safe to use

    if empty != nil
        print(empty)
    else
        print("Name is empty")

Key point: str? means "string or nil". We'll explore nil tracking fully in Chapter 11.

If you're new to programming

A nullable type is like an optional value. Sometimes you have it, sometimes you don't. Instead of errors when it's missing, Zebra lets you check first.

Type Mismatch Errors

Zebra prevents mixing types unsafely:

var x: int = "hello"  # ❌ Error: can't assign str to int
var y: str = 42       # ❌ Error: can't assign int to str
var z: int = 3.14     # ❌ Error: can't assign float to int

Why? Type safety catches bugs before they happen. You can't accidentally treat a string as a number.

Real World: Processing User Data

# file: 02_user_data.zbr
# teaches: realistic variable use
# chapter: 02-Values-and-Types

class User
    var id: int
    var name: str
    var email: str
    var age: int
    var is_active: bool

def main()
    # Create a user
    var user = User()
    user.id = 1
    user.name = "Alice"
    user.email = "alice@example.com"
    user.age = 30
    user.is_active = true

    # Display
    print("User: ${user.name}")
    print("Email: ${user.email}")
    print("Age: ${user.age}")
    print("Active: ${user.is_active}")

Common Mistakes

❌ Mistake: Skipping a type annotation when the right-hand side is opaque

var result = compute()  # What's the type?

💡 Why it matters: Inference is fine when the literal makes the type obvious (var x = 25). When the RHS is a function call whose return type isn't visible at the call site, an annotation pays for itself in readability.

✅ Better:

var result: int = compute()  # Clear: it's an int

❌ Mistake: Mixing types in arithmetic

var x = 10
var y = 3.14
print(x + y)  # ❌ Can't add int + float

💡 Why: Different types might need different handling.

✅ Better:

var x = 10.0
var y = 3.14
print(x + y)  # ✅ Both float

❌ Mistake: Using a nullable type without checking

var name: str? = nil
print(name.upper())  # ❌ Error: nil doesn't have .upper()

✅ Better:

var name: str? = nil
if name != nil
    print(name.upper())  # Safe

Exercises

Exercise 1: Type Conversion

Write a program that:

1. Creates an integer variable
2. Creates a float variable
3. Converts both to strings
4. Prints them

def main()
    var count = 42
    var price = 19.99

    var count_str = count.toString()
    var price_str = price.toString()

    print("Count: ${count_str}")
    print("Price: ${price_str}")

Count: 42
Price: 19.99

Exercise 2: Comparisons

Write a program that compares two numbers and prints which is larger:

def main()
    var x = 100
    var y = 75

    if x > y
        print("${x} is larger than ${y}")
    else
        print("${y} is larger than ${x}")

100 is larger than 75

Exercise 3: User Profile

Create a data structure to hold user information (name, age, email) and print a profile:

class Person
    var name: str
    var age: int
    var email: str

def main()
    var person = Person()
    person.name = "Carol"
    person.age = 28
    person.email = "carol@example.com"

    print("Name: ${person.name}")
    print("Age: ${person.age}")
    print("Email: ${person.email}")

Next Steps

• → 03-Collections — Lists and HashMaps
• → 04-Functions — Write reusable code
• → 11-Nil-Tracking — Deep dive into nullable types

Key Takeaways

• Every value has a type — Integers, floats, booleans, strings, and more
• Types are checked at compile time — Catches bugs early
• Use type inference when obvious, explicit types when clarity matters
• Conversions are explicit — No silent type changes
• Nullable types use ? — str? can be string or nil
• Always check nil before using — if value != nil { ... }

Next: Head to 03-Collections to learn Lists and HashMaps.

03: Collections

Audience: All
Time: 120 minutes
Prerequisites: 01-Getting-Started, 02-Values-and-Types
You'll learn: Lists, HashMaps, Sets, iteration, indexing, collection methods

The Big Picture

Collections let you group values. Instead of declaring 100 separate variables for 100 names, you use one List(str) that holds all 100.

Zebra provides:

• List(T) — Ordered, resizable sequences (like Python's list)
• HashMap(K, V) — Key-value pairs (like Python's dict)
• Set(T) — Unique elements of any hashable type (Set(str)(), Set(int)())

Lists

A List holds multiple values of the same type in order.

Creating Lists

# file: 03_lists.zbr
# teaches: list creation and access
# chapter: 03-Collections

def main()
    # List literal — the cleanest way to make a populated list.
    # The element type is inferred from the first element.
    var fruits = ["apple", "banana", "cherry"]

    # An empty list with an explicit annotation — and `.add()` to grow:
    var empty: List(str) = []
    empty.add("date")
    print(empty.count())  # 1

    # Access by index
    var first = fruits.at(0)
    var second = fruits.at(1)
    print(first)  # apple
    print(second)  # banana

    # Check size
    print(fruits.count())  # 3

    # Iterate
    for fruit in fruits
        print(fruit)

The constructor form var fruits = List(str)() is still valid — useful when you want an empty list to grow without specifying an element type up front (the element type is inferred from the first .add()). For populated lists, […] is shorter and reads better.

List Operations

# file: 03_list_ops.zbr
# teaches: list manipulation
# chapter: 03-Collections

def main()
    var nums = [10, 20, 30]             # list literal — type inferred

    # Check existence
    print(nums.contains(20))  # true

    # Find the first matching element (there's no indexOf — search with a predicate;
    # .find() returns an Optional, nil if nothing matches)
    print(nums.find(def(x) = x == 20))  # 20

    # Remove by index (List.remove takes an index, not a value)
    nums.remove(1)
    print(nums.count())  # 2

    # Clear
    nums.clear()
    print(nums.count())  # 0

Sorting

# file: 03_sorting.zbr
# teaches: sort, sort with a comparator, sortBy, reverse
# chapter: 03-Collections

def main()
    var nums = [42, 7, 19, 3]
    nums.sort()                            # ascending, in place
    print(nums.at(0))
    print(nums.at(3))

    nums.sort(def(a: int, b: int) = a > b) # comparator: true when a goes first
    print(nums.at(0))

    var names = ["mallory", "bob", "alice"]
    names.sort()                           # strings: lexicographic
    print(names.at(0))
    names.sortBy(def(s: str) = s.len)      # one-argument key: shortest first
    print(names.at(0))
    names.reverse()
    print(names.at(0))

Output:

3
42
42
alice
bob
mallory

All four reorder the list in place. Numbers and strings know their own order. A list of your own class sorts with plain sort() once the class declares cue compare, the method sort() and < call to order two values, together with the cue equals it requires (Chapter 07, "Cues"). Until then, pass a comparator or a key.

Iteration Patterns

# file: 03_iteration.zbr
# teaches: different iteration styles
# chapter: 03-Collections

def main()
    var items = List(str)()
    items.add("first")
    items.add("second")
    items.add("third")

    # Simple iteration (typed local works around print's {s} fallback)
    for item in items
        var s: str = item
        print(s)

    # Iteration with index — interpolation into a string handles the type fine
    var i = 0
    while i < items.count()
        print("${i}: ${items.at(i)}")
        i = i + 1

If you're new to programming

A List is like a numbered shelf. You can:

• Add items: list.add(item)
• Take items: list.remove(item)
• Check what's there: list.at(0) gets the first item
• Count items: list.count()

If you know Python

# Python
fruits = ["apple", "banana"]
fruits.append("cherry")
for fruit in fruits:
    print(fruit)

# Zebra
var fruits = List(str)()
fruits.add("apple")
fruits.add("banana")
fruits.add("cherry")
for fruit in fruits
    print(fruit)

The main difference: Zebra requires the element type (List(str)) at the construction site; once declared, the type flows through inference.

HashMaps

A HashMap stores key-value pairs. Fast lookup by key.

Creating and Using HashMaps

# file: 03_hashmaps.zbr
# teaches: hashmap creation and access
# chapter: 03-Collections

def main()
    # Create empty HashMap
    var ages = HashMap(str, int)()

    # Add key-value pairs
    ages.put("Alice", 30)
    ages.put("Bob", 25)
    ages.put("Carol", 28)

    # Retrieve by key — get returns int? (nil if missing)
    if ages.get("Alice") as a
        print(a)  # 30

    # Check if key exists
    print(ages.contains("Alice"))  # true

    # Iterate over key/value pairs
    for name, age in ages
        print("${name}: ${age}")

A note on the API: .put()/.fetch() are older HashMap method names that still work; .set()/.get() are the canonical forms used by QUICKSTART. .fetch() returns the value directly and panics on missing keys; .get() returns an optional — the safer pattern.

Your own types as keys. str, int and the other built-ins work as HashMap keys and Set elements out of the box. A class of your own can be one too, and it is then compared by identity: two separate objects with the same contents are two different keys. To key by contents, give the class cue hash and cue equals (Chapter 07, "Cues"); a struct can get both from @derive(Eq, Hash) (Chapter 07b).

HashMap Operations

# file: 03_hashmap_ops.zbr
# teaches: hashmap manipulation
# chapter: 03-Collections

def main()
    var config = HashMap(str, str)()
    config.put("host", "localhost")
    config.put("port", "8080")
    config.put("debug", "true")

    # Count entries
    print(config.count())  # 3

    # Remove entry
    config.remove("debug")
    print(config.count())  # 2

    # Look up safely — get returns str? (nil if missing)
    if config.get("host") as host
        print(host)  # localhost

    # Iterate over keys and values
    for key, value in config
        print("${key} = ${value}")

If you know Python

# Python
ages = {"Alice": 30, "Bob": 25}
print(ages["Alice"])
for name, age in ages.items():
    print(name, age)

# Zebra
var ages = HashMap(str, int)()
ages.put("Alice", 30)
ages.put("Bob", 25)
if ages.get("Alice") as a
    print(a)
for name, age in ages
    print("${name} ${age}")

Deduplication with HashMap

Need unique values? Use a HashMap where keys track membership:

# file: 03_dedup.zbr
# teaches: using HashMap for uniqueness
# chapter: 03-Collections

def main()
    var seen = HashMap(int, bool)()
    var unique = List(int)()

    var ids = [1, 2, 3, 2]              # last element is a duplicate

    for id in ids
        if not seen.contains(id)
            seen.put(id, true)
            unique.add(id)

    print(unique.count())  # 3

    # Check membership
    print(seen.contains(2))  # true

Real World: Data Processing

# file: 03_real_world.zbr
# teaches: collections in realistic scenarios
# chapter: 03-Collections

class Student
    var name: str
    var gpa: float

def main()
    # List of students
    var students = List(Student)()

    var alice = Student()
    alice.name = "Alice"
    alice.gpa = 3.9
    students.add(alice)

    var bob = Student()
    bob.name = "Bob"
    bob.gpa = 3.5
    students.add(bob)

    # Calculate average GPA
    var total = 0.0
    for student in students
        total = total + student.gpa
    var average = total / students.count()
    print("Average GPA: ${average}")

    # Find student by name
    var target_name = "Alice"
    for student in students
        if student.name == target_name
            print("Found: ${student.name} (${student.gpa})")

Common Patterns

Filter and Transform

# file: 03_patterns.zbr
# teaches: collection patterns
# chapter: 03-Collections

def main()
    var numbers = [1, 2, 3, 4, 5]

    # Filter: keep only even numbers
    var evens: List(int) = []
    for num in numbers
        if num % 2 == 0
            evens.add(num)

    print("Evens: ")
    for e in evens
        print(e)

    # Count matching items
    var count_gt_3 = 0
    for num in numbers
        if num > 3
            count_gt_3 = count_gt_3 + 1
    print("Numbers > 3: ${count_gt_3}")

Common Mistakes

❌ Mistake: Forgetting type parameters

var items = List()  # What type? List(what)?

✅ Better:

var items = List(str)()  # Clear: list of strings

❌ Mistake: Iterating and modifying

for item in items
    items.remove(item)  # ❌ Unsafe: modifying while iterating

✅ Better:

var to_remove = List(str)()
for item in items
    if should_remove(item)
        to_remove.add(item)
for item in to_remove
    for i in 0..items.count()
        if items.at(i) == item
            items.remove(i)
            break

❌ Mistake: Using wrong key type for HashMap

var map = HashMap(str, int)()
map.put(1, 100)  # ❌ Key should be str, not int

✅ Better:

var map = HashMap(str, int)()
map.put("count", 100)  # ✅ Key is str

Exercises

Exercise 1: List Operations

Create a list of numbers and find the sum:

def main()
    var nums = [10, 20, 30, 40]

    var sum = 0
    for num in nums
        sum = sum + num

    print("Sum: ${sum}")  # 100

Exercise 2: HashMap Lookup

Create a phone book and look up a number:

def main()
    var phone_book = HashMap(str, str)()
    phone_book.put("Alice", "555-1234")
    phone_book.put("Bob", "555-5678")
    phone_book.put("Carol", "555-9999")

    var name = "Bob"
    if phone_book.get(name) as number
        print("${name}'s number: ${number}")

Exercise 3: Unique Words

Count unique words in a sentence (using HashMap for deduplication):

def main()
    var text = "the quick brown fox jumps over the lazy dog"
    var words: List(str) = text.split(" ")  # typed annotation auto-collects the iterator

    var seen = HashMap(str, bool)()
    for word in words
        seen.put(word, true)

    print("Total words: ${words.count()}")
    print("Unique words: ${seen.count()}")

Next Steps

• → 04-Functions — Reuse collection-processing code
• → 05-Control-Flow — Pattern matching on collections
• 🏋 Project-3-Data-Analysis — Real collection processing

Key Takeaways

• List(T) holds ordered items, access by index
• HashMap(K,V) holds key-value pairs, fast lookup
• Deduplication — use HashMap keys for unique-value tracking
• Iteration with for item in collection is the main pattern
• Type parameters are required: List(str) not just List
• Modifying while iterating is unsafe; collect changes first

Next: Head to 04-Functions to write reusable code.

04: Functions and Scope

Audience: All
Time: 120 minutes
Prerequisites: 01-02-03
You'll learn: Define functions, parameters, return values, scope, closures, capture blocks

The Big Picture

Functions let you:

• Reuse code — Write once, call many times
• Organize logic — Group related operations
• Name ideas — process_payment() is clearer than inline logic
• Test parts — Functions are easier to test in isolation

Basic Functions

Defining Functions

# file: 04_functions.zbr
# teaches: function definition and calling
# chapter: 04-Functions-and-Scope

def add(a: int, b: int): int
    return a + b

def multiply(x: int, y: int): int
    return x * y

def main()
    var result1 = add(5, 3)
    print(result1)  # 8

    var result2 = multiply(4, 7)
    print(result2)  # 28

Breakdown:

• def add(...) — Define a function named add at the module top level. No surrounding class is needed when the function is just a reusable operation.
• (a: int, b: int) — Parameters: a and b, both integers.
• : int (after the closing paren) — Return type is integer.
• return a + b — The value to return.

When you do want to group related functions on a class — for namespacing, or because they share class state — use static def name(...) inside class Name. We'll show that pattern when it earns its keep (Chapter 07).

Functions With Multiple Parameters

# file: 04_multi_params.zbr
# teaches: multiple parameters
# chapter: 04-Functions-and-Scope

def pad(text: str, width: int, fill: str): str
    # (Implementation would go here)
    return text

def main()
    var padded = pad("hi", 10, "*")
    print(padded)

Optional Logic (No Return Value)

# file: 04_void.zbr
# teaches: functions that don't return values
# chapter: 04-Functions-and-Scope

def log(message: str)
    print("[LOG] ${message}")

def main()
    log("Application started")
    log("Processing data")
    log("Done")

When a function doesn't return a value, omit the : <type> after the parameter list.

Scope

Scope is where a variable can be accessed.

Local Scope

Variables declared inside a function are local (only accessible there):

# file: 04_scope.zbr
# teaches: variable scope
# chapter: 04-Functions-and-Scope

class Calculator
    static
        var global_val: int = 100  # Shared (class-level)

        def compute()
            var local_val = 50      # Local to this function
            print(local_val)  # ✅ Can access
            print(global_val)  # ✅ Can access class-level

        def other()
            # print local_val       # ❌ Can't access, it's not here
            pass

def main()
    Calculator.compute()

Shadowing (Careful!)

class Example
    static
        var count: int = 10        # Class-level

        def show()
            var count = 5           # Local (shadows class variable)
            print(count)  # 5 (local shadows class)

        def another()
            print(count)  # 10 (uses class-level)

Shadowing can be confusing. Rename to clarify intent.

If you're new to programming

Scope determines where you can use a variable.

• Local: Only inside the function where it's declared
• Class-level: Accessible from all functions in the class

Closures and Capture

Functions can create inner functions that capture outer variables:

# file: 04_closures.zbr
# teaches: closures and variable capture
# chapter: 04-Functions-and-Scope

def make_multiplier(factor: int): def(int)
    return def(x: int)
        capture
            var factor: int = factor
        return x * factor

def main()
    var double = make_multiplier(2)
    var triple = make_multiplier(3)

    print(double(5))  # 10
    print(triple(5))  # 15

What's happening:

1. make_multiplier(2) creates a function that multiplies by 2
2. double = ... stores that function in a variable
3. double(5) calls it: 5 * 2 = 10

A lambda can read its enclosing function's parameters and locals directly. The capture block does something more specific: it gives each closure its own private copy of factor, kept for as long as the closure lives — per-closure state, shown next.

Closures Share, They Don't Copy

A var local that a lambda writes is shared with the function that declared it, as in C#: a write through the closure is seen outside, and every closure naming the variable sees the same one.

# file: 04_shared_capture.zbr
# teaches: closures share the variables they write
# chapter: 04-Functions-and-Scope

def main()
    var count = 0
    var bump = def()
        count += 1
    bump()
    bump()
    print(count)    # 2 -- the closure and main share `count`

Parameters, loop variables and as bindings are read as a copy made when the closure is created, so a closure made in a loop sees that iteration's value; changing one of them after a closure has read it is refused, with the fix (copy it into a var first). And a closure value is a reference, like a C# delegate: pass it to a function or store it in a field, and every holder calls the same closure, with the same capture state.

Capture Syntax

# file: 04_capture.zbr
# teaches: capture blocks
# chapter: 04-Functions-and-Scope

def make_counter(): def(): int
    var count: int = 0
    return def(): int
        capture
            var count: int = count
        count = count + 1
        return count

def main()
    var counter = make_counter()
    print(counter())  # 1
    print(counter())  # 2
    print(counter())  # 3

Real World: Reusable Utilities

# file: 04_utilities.zbr
# teaches: practical function use
# chapter: 04-Functions-and-Scope

def repeat_str(text: str, times: int): str
    var result = ""
    var i = 0
    while i < times
        result = result.concat(text)
        i = i + 1
    return result

def pad_left(text: str, width: int): str
    var padding_needed = width - @as(int, text.len)
    if padding_needed <= 0
        return text
    var padding = repeat_str(" ", padding_needed)
    return padding.concat(text)

def main()
    var padded = pad_left("hello", 10)
    print("[${padded}]")  # [     hello]

Aside: the @as(int, text.len) cast works around BUG-093 (s.len is usize, not int, so it can't be subtracted from an int literal directly). Once that bug is fixed the cast becomes optional.

Common Patterns

Early Return

# file: 04_patterns.zbr
# teaches: early return pattern
# chapter: 04-Functions-and-Scope

def validate_email(email: str): bool
    if email.len == 0
        return false
    if not email.contains("@")
        return false
    if not email.contains(".")
        return false
    return true

Default Arguments

Zebra supports parameter defaults directly — you don't need an overload:

def log(message: str, prefix: str = "[INFO]")
    print("${prefix} ${message}")

def main()
    log("Application started")              # [INFO] Application started
    log("Disk failing", "[WARN]")           # [WARN] Disk failing

You can also pass arguments by name when that aids the reader:

log(prefix: "[ERROR]", message: "Out of memory")

Passing Functions As Arguments

# file: 04_higher_order.zbr
# teaches: functions as arguments
# chapter: 04-Functions-and-Scope

def map_int(items: List(int), transform: def(int): int): List(int)
    var result = List(int)()
    for item in items
        result.add(transform(item))
    return result

def main()
    var nums = List(int)()
    nums.add(1)
    nums.add(2)
    nums.add(3)

    var double_it = def(x: int): int = x * 2
    var doubled = map_int(nums, double_it)

    for d in doubled
        print(d)  # 2, 4, 6

sig — Named Function Types

When you pass functions around frequently, name the function type with sig for cleaner code and reusable signatures:

# file: 04_sig.zbr
# teaches: named function types with sig
# chapter: 04-Functions-and-Scope

sig Transformer(x: int): int      # "a function int → int"
sig Predicate(s: str): bool       # "a function str → bool"

def apply_all(nums: List(int), fn: Transformer): List(int)
    var result = List(int)()
    for n in nums
        result.add(fn(n))
    return result

static def double(x: int): int
    return x * 2

static def square(x: int): int
    return x * x

def main()
    var nums = List(int)()
    nums.add(1)
    nums.add(2)
    nums.add(3)

    var doubled = apply_all(nums, double)
    var squared = apply_all(nums, square)

    for d in doubled
        print(d)  # 2, 4, 6
    for s in squared
        print(s)  # 1, 4, 9

sig Transformer(x: int): int is a type alias — "a function that takes one int and returns an int". Any function or lambda with that shape is compatible (structural typing — no implements required).

sig as a class field — the idiomatic event-callback pattern:

sig OnClick()

class Button
    var onClick: OnClick? = nil

    def click()
        if .onClick as cb
            cb()

Cross-module: sig types are exported and importable across modules:

# callbacks.zbr
sig OnReady()
sig OnError(msg: str)

# main.zbr
use callbacks exposing OnReady, OnError

def run(cb: OnReady)
    cb()

Lambda Passed Directly as an Argument

Instead of assigning a lambda to a variable first, pass it directly:

# file: 04_lambda_arg.zbr
# teaches: lambda as call argument (statement-body form)
# chapter: 04-Functions-and-Scope

sig IntFn(x: int): int      # name the function type first

def apply(n: int, transform: IntFn): int
    return transform(n)

def main()
    # Statement-body lambda as a call argument:
    var result = apply(5, def(x: int): int
        var doubled = x * 2
        return doubled
    )
    print(result)  # 10

Indentation rule: the lambda body indents under def(...). The closing ) of the enclosing call returns to the call-site indent level — one level out from the lambda body. Nesting works too:

# file: 04_nested_lambda.zbr
# teaches: nested lambda as argument
# chapter: 04-Functions-and-Scope

sig VoidFn()        # function type: no params, no return

def run_twice(action: VoidFn)
    action()
    action()

def with_logging(label: str, action: VoidFn)
    print("start: ${label}")
    action()
    print("end: ${label}")

def main()
    with_logging("outer", def()
        run_twice(def()
            print("  inner")
        )
    )
    # Prints:
    # start: outer
    #   inner
    #   inner
    # end: outer

Common Mistakes

❌ Mistake: Returning wrong type

def get_age(): int
    return "25"  # ❌ Returning str, not int

✅ Better:

def get_age(): int
    return 25    # ✅ Returning int

❌ Mistake: Using variable outside its scope

def process()
    var data = fetch_data()

def use()
    print(data)  # ❌ data doesn't exist here

✅ Better:

def process(): str
    var data = fetch_data()
    return data

def use()
    var data = process()
    print(data)  # ✅ data is here

❌ Mistake: Forgetting to return

def compute(): int
    var result = 5 + 3
    # Forgot return!

✅ Better:

def compute(): int
    var result = 5 + 3
    return result

Exercises

Exercise 1: Simple Function

Write a function that calculates the factorial of a number:

def factorial(n: int): int
    if n <= 1
        return 1
    return n * factorial(n - 1)

def main()
    print(factorial(5))  # 120

Exercise 2: Closure

Create a function that returns an "adder" function:

def make_adder(base: int): def(int): int
    return def(x: int): int
        capture
            var base: int = base
        return x + base

def main()
    var add_10 = make_adder(10)
    print(add_10(5))  # 15
    print(add_10(20))  # 30

Exercise 3: Filtering

Write a function that filters a list:

def even_numbers(nums: List(int)): List(int)
    var evens = List(int)()
    for num in nums
        if num % 2 == 0
            evens.add(num)
    return evens

def main()
    var nums = List(int)()
    nums.add(1)
    nums.add(2)
    nums.add(3)
    nums.add(4)
    nums.add(5)

    var result = even_numbers(nums)
    for r in result
        print(r)

Next Steps

• → 05-Control-Flow — if/else, loops, pattern matching
• → 15-Pipelines — Function composition
• 🏋 Project-1-CLI-Tool — Use functions extensively

Key Takeaways

• Functions are reusable blocks of code with clear inputs and outputs
• Scope determines where variables can be accessed
• Closures capture outer variables for use in inner functions
• Early return makes logic clearer
• Functions as arguments enable powerful abstractions
• sig names a function type — required for parameters that accept lambdas (inline def(T): R is not a valid parameter type); sig is also importable across modules
• Lambda-in-call — pass a statement-body def(...) directly as an argument; closing ) returns to the call-site indent level
• Name functions well — process_payment() is better than do_thing()

Next: Head to 05-Control-Flow to learn if/else, loops, and pattern matching.

05: Control Flow

Audience: All
Time: 90 minutes
Prerequisites: 01-04
You'll learn: if/else, match, for loops, while loops, guards, break/continue

The Big Picture

Control flow directs which code runs based on conditions. Instead of executing every line in order, you:

• Skip code if a condition isn't met (if)
• Repeat code until done (for, while)
• Branch based on many options (match)

If / Else

Basic If

# file: 05_if.zbr
# teaches: conditional execution
# chapter: 05-Control-Flow

def main()
    var age = 18

    if age >= 18
        print("You can vote")

If / Else

# file: 05_if_else.zbr
# teaches: if-else branching
# chapter: 05-Control-Flow

def main()
    var score = 75

    if score >= 90
        print("A")
    else if score >= 80
        print("B")
    else if score >= 70
        print("C")
    else
        print("F")

Breakdown:

• if condition — Execute if true
• else if condition — Try the next condition (Zebra spells the chain else if, two words)
• else — Default case (if all above are false)

Multiple Conditions

# file: 05_conditions.zbr
# teaches: boolean logic
# chapter: 05-Control-Flow

def main()
    var age = 25
    var has_license = true

    if age >= 18 and has_license
        print("Can drive")

    if age < 16 or not has_license
        print("Cannot drive")

Operators:

• and — Both must be true
• or — At least one must be true
• not — Flip the value

Inline Conditions

Zebra lets you write short conditions on one line, and use if as an expression that produces a value.

One-Line If Statement

# file: 05_inline_if.zbr
# teaches: one-line if statement
# chapter: 05-Control-Flow

def main()
    var x = 10
    if x > 0: print("positive")     # colon required before body

    # One-line with else:
    var label = ""
    if x > 0: label = "pos" else: label = "non-pos"

    # Chained else-if on one line:
    var grade = 78
    var letter = ""
    if grade >= 90: letter = "A" else if grade >= 80: letter = "B" else: letter = "C"
    print(letter)  # C

The : is required before the body. No block — the condition and body sit on the same line.

If as an Expression

To produce a value — to initialise a variable or pass an argument — use the three-argument form if(condition, value_if_true, value_if_false):

# file: 05_if_expr.zbr
# teaches: if-expression
# chapter: 05-Control-Flow

def main()
    var score = 85

    # Choose a value:
    var verdict = if(score >= 60, "pass", "fail")
    print(verdict)  # pass

    # Use it directly as an argument:
    print(if(score > 90, "excellent", "good"))  # good

    # Absolute value:
    var n: int = -5
    var abs_n: int = if(n >= 0, n, -n)
    print(abs_n)  # 5

Rules for the expression form:

• It takes exactly three arguments, and the two values must have the same type.
• For more than two outcomes, nest it — if(a, x, if(b, y, z)) — or use the statement form above and assign inside each branch.
• The colon form if cond: a else: b is a statement only: it runs one of two statements, and it does not parse where a value is expected.

Coming from Python? This does the job of value_if_true if cond else value_if_false, but reads condition-first, like a function call.

Match (Pattern Matching)

Match is more powerful than if/else. It handles many cases elegantly.

Simple Match

# file: 05_match.zbr
# teaches: pattern matching
# chapter: 05-Control-Flow

def main()
    var color = "red"

    branch color
        on "red"
            print("Stop")
        on "yellow"
            print("Caution")
        on "green"
            print("Go")
        else
            print("Unknown")

Match With Types

Zebra's idiomatic way to dispatch on "what kind of thing is this" is a union plus branch. Each variant of the union carries its own data:

# file: 05_match_type.zbr
# teaches: type-based matching with unions
# chapter: 05-Control-Flow

union Pet
    dog: str       # name
    cat: str       # name
    fish: str      # tank-size

def main()
    var pet: Pet = Pet.dog("Rex")

    branch pet
        on Pet.dog as name
            print("${name} says: Woof!")
        on Pet.cat as name
            print("${name} says: Meow!")
        on Pet.fish as size
            print("tank: ${size}")
        else
            pass

Zebra has no class inheritance, so dispatching on a class hierarchy isn't the natural pattern here. See Chapter 09 (Composition and Mixins) for why, and Chapter 07b (Structs and Unions) for more on tagged unions.

If you know Python

# Python
match color:
    case "red":
        print("Stop")
    case "green":
        print("Go")

# Zebra
branch color
    on "red"
        print("Stop")
    on "green"
        print("Go")

Loops

For Loop (Iteration)

# file: 05_for.zbr
# teaches: for loop iteration
# chapter: 05-Control-Flow

def main()
    var fruits = List(str)()
    fruits.add("apple")
    fruits.add("banana")
    fruits.add("cherry")

    for fruit in fruits
        var f: str = fruit       # typed local for {s} formatting
        print(f)

    # Numeric range — n.to(end) is exclusive on `end`.
    var i = 0
    while i < fruits.count()
        print("Item ${i}: ${fruits.at(i)}")
        i = i + 1

While Loop (Condition-Based)

# file: 05_while.zbr
# teaches: while loop
# chapter: 05-Control-Flow

def main()
    var count = 0

    while count < 5
        print("Count: ${count}")
        count = count + 1

    print("Done!")

Break and Continue

# file: 05_break_continue.zbr
# teaches: loop control
# chapter: 05-Control-Flow

def main()
    # Break: exit loop early
    var i = 0
    while true
        if i == 5
            break
        print(i)
        i = i + 1

    # Continue: skip to next iteration. Numeric ranges use either `start:end`
    # or the equivalent method form `start.to(end)` — both are exclusive on
    # `end` (so `1.to(11)` yields 1,2,...,10).
    for num in 1.to(11)
        if num % 2 == 0
            continue
        print(num)  # Prints odd numbers only

for walks lists, ranges and maps. It also walks any type of your own that declares the iteration cues, cue iter / cue next; Chapter 07 ("Cues") shows how. The quickest way to get such a type is to let the compiler write it, with a generator.

Generators: Lazy Sequences with yield

A top-level def whose return type is Iter(T) is a generator. Its body does not run when you call it. It runs a step at a time as the caller asks for values: each yield v hands one value to the loop and pauses, and the next request resumes the body just after the yield. Nothing is collected into a list first.

# file: 05_generators.zbr
# teaches: generators -- a def returning Iter(T) that produces values with yield
# chapter: 05-Control-Flow

def evens(limit: int): Iter(int)
    var i = 0
    while i < limit
        yield i
        i = i + 2

def longWords(words: List(str), n: int): Iter(str)
    for w in words
        if w.len > n
            yield w

def naturals(): Iter(int)              # never finishes on its own
    var n = 1
    while true
        yield n
        n = n + 1

def main()
    for x in evens(7)
        print(x)

    var words = ["generator", "is", "lazy", "iteration"]
    for w in longWords(words, 4)
        print(w)

    for n in naturals()                # the consumer decides when to stop
        if n > 3
            break
        print("n = ${n}")

    var it = evens(4)                  # next() by hand: one value per call
    print(it.next()!)
    print(it.next()!)
    print(it.next() == nil)            # finished

Output:

0
2
4
6
generator
iteration
n = 1
n = 2
n = 3
0
2
true

What happened here:

• evens(7) produced 0, 2, 4, 6 one at a time; the loop's i lives across the pauses.
• naturals() would run forever on its own. It is safe because the caller stops asking (break), and the generator never computes a value nobody asked for.
• A generator is an iterator, so it.next() gives the next value, and nil once the body has finished.

The rules:

• yield v produces a value. A bare return finishes early; a generator cannot return a value ("a generator finishes with a bare return; it produces values with yield").
• Iter(T) is only a return type. Bind the call (var it = evens(4)) and let the type be inferred; var it: Iter(int) = ... is refused.
• Generators are top-level defs. A method cannot yield (yet).
• A yield inside branch, try, with, using or allocate is refused by name; restructure with an if chain. A for that yields can walk a List, a range, or another iterable (a generator included), with one loop variable and no if filter on the loop.

Under the hood: the compiler turns a generator into a class with cue next, the same shape you would write by hand in Chapter 07, with the function's locals as fields.

Guards

Guards are conditions that must be true for code to run. Zebra spells them with the one early-exit form it has — an inline if — rather than a dedicated keyword (a guard statement existed until 2026-09-15 and was removed: it was if not with a second spelling).

# file: 05_guards.zbr
# teaches: guard conditions
# chapter: 05-Control-Flow

def process(name: str)
    # Early returns state the precondition and leave at once:
    if not name.len > 0: return
    if name.len > 100: return

    # Process only if all guards passed
    print("Processing: ${name}")

def main()
    process("")            # Guard fails — returns early
    process("Alice")       # Guards pass — processes
    process("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")  # too long — returns early

if not cond: return reads as "the call must satisfy cond; otherwise return now". When the precondition is a contract — something the caller was wrong to violate rather than an input to tolerate — use require instead (Chapter 14): it names the violation and can be stripped from a --turbo build.

Real World: Data Validation

# file: 05_validation.zbr
# teaches: practical control flow
# chapter: 05-Control-Flow

def validate_email(email: str): bool
    # Check not empty
    if email.len == 0
        return false

    # Check has @
    if not email.contains("@")
        return false

    # Check has domain
    var parts: List(str) = email.split("@")
    if parts.count() != 2
        return false

    var domain: str = parts.at(1)
    if not domain.contains(".")
        return false

    return true

def main()
    var emails = List(str)()
    emails.add("alice@example.com")
    emails.add("invalid.email")
    emails.add("bob@domain.co")

    for email in emails
        var e: str = email
        if validate_email(e)
            print("Valid: ${e}")
        else
            print("Invalid: ${e}")

Common Patterns

Early Return

def process_order(order_id: int): bool
    var order = fetch_order(order_id)
    
    if order == nil
        return false
    
    if order.total == 0
        return false
    
    if not order.has_items
        return false
    
    # Do the real processing
    charge_card(order)
    ship_items(order)
    return true

Nested Conditions

for user in users
    if user.is_active
        for order in user.orders
            if order.status == "pending"
                process_order(order)

Else-If Chain

if age < 13
    category = "child"
else if age < 18
    category = "teen"
else if age < 65
    category = "adult"
else
    category = "senior"

Common Mistakes

❌ Mistake: Forgetting the condition

if age >= 18  # Missing condition or wrong structure
    print("Adult")
    print("Extra")  # Both print regardless

✅ Better:

if age >= 18
    print("Adult")
else
    print("Minor")

❌ Mistake: Unreachable code

if x > 0
    return true
else
    return false
return false  # ❌ Never reached

✅ Better:

if x > 0
    return true
return false

❌ Mistake: Mutating collection while iterating

for fruit in fruits
    if fruit == "apple"
        fruits.remove(0)  # ❌ Unsafe — modifying during iteration

✅ Better:

var to_remove = List(int)()           # collect indices
var idx = 0
for fruit in fruits
    if fruit == "apple"
        to_remove.add(idx)
    idx = idx + 1
# Remove in reverse so earlier indices stay valid.
var k = to_remove.count() - 1
while k >= 0
    fruits.remove(to_remove.at(k))
    k = k - 1

Exercises

Exercise 1: Grade Calculator

Write a function that converts numeric scores to letter grades:

def grade_to_letter(score: int): str
    if score >= 90
        return "A"
    else if score >= 80
        return "B"
    else if score >= 70
        return "C"
    else if score >= 60
        return "D"
    else
        return "F"

def main()
    var scores = List(int)()
    scores.add(95)
    scores.add(75)
    scores.add(88)
    scores.add(62)

    for score in scores
        var grade = grade_to_letter(score)
        print("${score} = ${grade}")

Exercise 2: Find Maximum

Iterate through a list and find the maximum value:

def find_max(nums: List(int)): int
    if nums.count() == 0
        return 0

    var max_val = nums.at(0)
    for num in nums
        if num > max_val
            max_val = num
    return max_val

def main()
    var nums = List(int)()
    nums.add(10)
    nums.add(45)
    nums.add(23)
    nums.add(89)
    nums.add(34)

    var max = find_max(nums)
    print("Max: ${max}")  # 89

Exercise 3: Filter With Control Flow

Count elements matching a condition:

def count_evens(nums: List(int)): int
    var count = 0
    for num in nums
        if num % 2 == 0
            count = count + 1
    return count

def main()
    var nums = List(int)()
    nums.add(1)
    nums.add(2)
    nums.add(3)
    nums.add(4)
    nums.add(5)
    nums.add(6)

    var even_count = count_evens(nums)
    print("Even numbers: ${even_count}")  # 3

Next Steps

• → 06-Strings-and-Unicode — Text manipulation
• → 05-Control-Flow — Combine control flow with strings
• 🏋 Project-1-CLI-Tool — Use loops and conditions extensively

Key Takeaways

• if/else handles simple binary choices
• Inline if (if cond: stmt) compresses a simple branch to one line
• If-expression (var x = if cond: a else: b) produces a value — else: required; chained else if not supported in expression position
• match (branch) is better for many cases
• for loops iterate over collections, ranges, and anything with cue iter / cue next
• Generators (def f(): Iter(T) with yield) produce a sequence lazily, one value per request
• while loops repeat based on conditions
• break exits loops, continue skips iterations
• Early return makes functions clearer
• Guard clauses prevent "arrow code" (deeply nested if statements)

Next: Head to 06-Strings-and-Unicode to work with text.

06: Strings and Unicode

Audience: All
Time: 90 minutes
Prerequisites: 01-05
You'll learn: String operations, Unicode, formatting, pattern matching with regex

The Big Picture

Strings are how programs work with text. Zebra treats strings as:

• Unicode-aware — Emoji, Chinese, Arabic, etc. all work correctly
• First-class — Rich library of methods
• Immutable — Can't change them after creation (create new ones instead)
• Efficient — UTF-8 encoding optimizes storage

String Basics

String Literals

# file: 06_string_basics.zbr
# teaches: string creation
# chapter: 06-Strings-and-Unicode

def main()
    # Simple string
    var greeting = "Hello"
    print(greeting)

    # With quotes inside
    var quoted = "She said \"Hello\""
    print(quoted)

    # Multi-line (triple-quoted)
    var poem = """
    Roses are red
    Violets are blue
    """
    print(poem)

    # Escape sequences
    var path = "C:\\Users\\Name\\Documents"
    var tab = "Name\tAge\tCity"
    var newline = "Line1\nLine2"

String Properties

# file: 06_string_props.zbr
# teaches: string properties and methods
# chapter: 06-Strings-and-Unicode

def main()
    var text = "Hello, World!"

    # Byte length (Unicode-aware count is below — see codePointCount)
    print(text.len)  # 13

    # Indexing gives a BYTE, not a character: text[i] is the i-th byte of the UTF-8
    # encoding, so it prints as a number. For text, take a slice (next) or iterate
    # text.chars(), which yields whole characters even when they are multi-byte.
    var first_byte = text[0]
    print(first_byte.toString())  # 72  (the byte for "H")
    print(text[0..1])             # H

    # Substring/slice
    var part: str = text[0..5]
    print(part)  # Hello

    # Case conversion
    print(text.upper())  # HELLO, WORLD!
    print(text.lower())  # hello, world!

String Interpolation

# file: 06_interpolation.zbr
# teaches: string interpolation
# chapter: 06-Strings-and-Unicode

def main()
    var name = "Alice"
    var age = 30

    # Simple interpolation
    print("Name: ${name}")  # Name: Alice

    # Expressions in interpolation
    print("Age next year: ${age + 1}")  # Age next year: 31

    # Method calls
    var lower_name = name.lower()
    print("Lowercase: ${lower_name}")  # Lowercase: alice

    # Format specifiers
    var price = 19.99
    print("Price: ${price:.2f}")  # Price: 19.99

String Methods

Searching

# file: 06_search.zbr
# teaches: searching in strings
# chapter: 06-Strings-and-Unicode

def main()
    var text = "Hello, World!"

    # Contains
    print(text.contains("World"))  # true
    print(text.contains("xyz"))  # false

    # Index — returns -1 when not found
    print(text.indexOf("World"))  # 7
    print(text.indexOf("xyz"))  # -1

    # Starts/ends with
    print(text.startsWith("Hello"))  # true
    print(text.endsWith("!"))  # true

Splitting and Joining

# file: 06_split_join.zbr
# teaches: splitting and joining strings
# chapter: 06-Strings-and-Unicode

def main()
    # Split — annotate the local with `: List(str)` to materialise the iterator
    # into an actual list (otherwise it stays as a forward iterator only).
    var csv = "apple,banana,cherry"
    var fruits: List(str) = csv.split(",")
    for fruit in fruits
        var f: str = fruit
        print(f)

    # Join
    var items = List(str)()
    items.add("one")
    items.add("two")
    items.add("three")
    var result = ", ".join(items)
    print(result)  # one, two, three

Trimming and Padding

# file: 06_trim_pad.zbr
# teaches: trimming and padding
# chapter: 06-Strings-and-Unicode

def main()
    var padded = "  hello  "

    # Trim whitespace
    print("|${padded.trim()}|")  # |hello|
    print("|${padded.trimLeft()}|")  # |hello  |
    print("|${padded.trimRight()}|")  # |  hello|

    # Padding
    var short = "hi"
    print(short.padLeft(10, "*"))  # ********hi
    print(short.padRight(10, "-"))  # hi--------
    print(short.center(10, "*"))  # ****hi****

Replacing

# file: 06_replace.zbr
# teaches: string replacement
# chapter: 06-Strings-and-Unicode

def main()
    var text = "cat and dog and bird"

    # Replace (first occurrence, or all)
    var once = text.replace("and", "or")      # Replaces once
    print(once)

    var all = text.replaceAll("and", "or")    # Replaces all
    print(all)

    # Case conversion
    var lower = "Hello World".lower()
    print(lower)  # hello world

Unicode and Internationalization

Unicode Basics

# file: 06_unicode.zbr
# teaches: unicode support
# chapter: 06-Strings-and-Unicode

def main()
    # Emoji
    var emoji = "Hello 👋 🌍 🎉"
    print(emoji)
    print(emoji.len)  # Byte length
    print(emoji.codePointCount())  # Character count

    # Chinese
    var chinese = "你好世界"             # Hello World in Chinese
    print(chinese)

    # Arabic (right-to-left)
    var arabic = "مرحبا بالعالم"         # Hello World
    print(arabic)

    # Mixed scripts
    var mixed = "Hello 世界 مرحبا"
    print(mixed)

Character Iteration

# file: 06_char_iter.zbr
# teaches: iterating over characters
# chapter: 06-Strings-and-Unicode

def main()
    var text = "Hello"

    # Iterate characters (yields `char`; .toString() lifts back to str for printing)
    for c in text.chars()
        print(c.toString())

    # Byte iteration — yields each byte as a u8
    var data = "AB"
    for byte in data.bytes()
        print(byte)  # 65, 66 (ASCII values)

.chars() and .bytes() are different lenses on the same string. .chars() walks Unicode codepoints (so "👋" yields one element); .bytes() walks the raw UTF-8 bytes (so "👋" yields four). Use whichever matches what you're counting.

Regular Expressions (Intro)

Regular expressions let you search and validate text patterns.

Basic Patterns

# file: 06_regex_intro.zbr
# teaches: regular expressions introduction
# chapter: 06-Strings-and-Unicode

def main()
    # Simple pattern
    var email = "alice@example.com"
    var pattern = Regex.compile("[a-z]+@[a-z]+\\.[a-z]+")

    print(pattern.match(email))  # true

    # Find matches
    var text = "I have 2 apples and 3 oranges"
    var digit_pattern = Regex.compile("\\d+")
    if digit_pattern.find(text) as found
        print(found)  # 2

    # Replace
    var clean = digit_pattern.replace(text, "X")
    print(clean)  # I have X apples and X oranges

Real World: Text Processing

# file: 06_text_processing.zbr
# teaches: practical text operations
# chapter: 06-Strings-and-Unicode

def parse_csv_line(line: str): List(str)
    var out: List(str) = line.split(",")
    return out

def normalize_whitespace(text: str): str
    var lines = List(str)()
    for line in text.split("\n")
        var trimmed = line.trim()
        if trimmed.len > 0
            lines.add(trimmed)
    return "\n".join(lines)

def extract_numbers(text: str): List(str)
    var results = List(str)()
    var pattern = Regex.compile("\\d+")
    for match in pattern.findAll(text)
        results.add(match)
    return results

def main()
    # Parse CSV
    var csv_line = "Alice,30,alice@example.com"
    var fields = parse_csv_line(csv_line)
    var name: str = fields.at(0)
    var age:  str = fields.at(1)
    print("Name: ${name}")
    print("Age: ${age}")

    # Extract numbers
    var text = "I was born in 1990 and moved in 2005"
    var years = extract_numbers(text)
    for year in years
        var y: str = year
        print(y)

Common Patterns

Email Validation

def is_valid_email(email: str): bool
    if not email.contains("@")
        return false
    var parts: List(str) = email.split("@")
    if parts.count() != 2
        return false
    var domain: str = parts.at(1)
    if not domain.contains(".")
        return false
    return true

URL Parsing

def parse_url(url: str): HashMap(str, str)
    var result = HashMap(str, str)()
    var parts: List(str) = url.split("://")
    if parts.count() == 2
        var proto: str = parts.at(0)
        result.put("protocol", proto)
    return result

String Templating

def template(text: str, values: HashMap(str, str)): str
    var result = text
    for key, value in values
        var placeholder = "${${key}}"
        result = result.replace(placeholder, value)
    return result

Common Mistakes

❌ Mistake: Forgetting that strings are immutable

var text = "hello"
text[0] = 'H'  # ❌ Can't modify

✅ Better:

var text = "hello"
var capitalized = "H".concat(text[1..])

❌ Mistake: Ignoring Unicode length

var emoji = "👋"
print(emoji.len)  # ❌ Returns 4 (bytes), not 1

✅ Better:

var emoji = "👋"
print(emoji.codePointCount())  # ✅ Returns 1 (characters)

❌ Mistake: Inefficient concatenation in loops

var result = ""
for i in 1.to(1000)
    result = result + "${i},"  # ❌ O(n²) complexity

✅ Better:

var sb = StringBuilder()
for i in 1.to(1000)
    sb.append("${i},")
var result = sb.build()  # ✅ O(n) complexity

Exercises

Exercise 1: String Reversal

Write a function that reverses a string:

def reverse_str(text: str): str
    var chars = List(str)()
    for c in text.chars()
        chars.add(c.toString())

    var result = ""
    var i = chars.count() - 1
    while i >= 0
        result = result.concat(chars.at(i))
        i = i - 1
    return result

def main()
    var reversed = reverse_str("hello")
    print(reversed)  # olleh

Exercise 2: Email Validator

Write a simple email validator:

def is_valid_email(email: str): bool
    if email.len < 5
        return false
    if not email.contains("@")
        return false
    if not email.contains(".")
        return false
    var parts: List(str) = email.split("@")
    if parts.count() != 2
        return false
    var domain: str = parts.at(1)
    if domain.len < 3
        return false
    return true

def main()
    var emails = List(str)()
    emails.add("alice@example.com")
    emails.add("invalid")
    emails.add("bob@domain.co")

    for email in emails
        var e: str = email
        if is_valid_email(e)
            print("Valid: ${e}")
        else
            print("Invalid: ${e}")

Exercise 3: CSV Parsing

Parse a CSV line and extract fields:

def parse_csv(line: str): List(str)
    var out: List(str) = line.split(",")
    return out

def parse_with_trim(line: str): List(str)
    var trimmed = List(str)()
    for field in line.split(",")
        trimmed.add(field.trim())
    return trimmed

def main()
    var csv = "Alice, 30, NYC"
    var fields = parse_with_trim(csv)
    for field in fields
        var f: str = field
        print("|${f}|")

Next Steps

• → 07-Classes — Object-oriented programming
• → 18-Regular-Expressions — Deep dive into regex
• 🏋 Project-1-CLI-Tool — Text processing practical application

Key Takeaways

• Strings are immutable — Create new ones instead of modifying
• Interpolation is readable — Use "${var}" over concatenation
• Methods are rich — .split(), .replace(), .trim(), etc.
• Unicode works seamlessly — emoji, Chinese, Arabic, etc.
• Regex enables pattern matching — For validation and extraction
• StringBuilder is efficient — Use for loop-based concatenation

Next: Head to Part 2 for object-oriented programming with 07-Classes.

07: Classes and Instances

Audience: All (with beginner sidebar)
Time: 120 minutes
Prerequisites: 01-06
You'll learn: Define classes, instantiate objects, instance methods, fields, initialization, cues (the methods the compiler calls for printing, ==, hashing, ordering and for)

The Big Picture

Classes are blueprints for objects. Instead of a loose collection of variables, a class groups related data and behavior together.

Real world: A car has properties (color, speed) and behaviors (accelerate, brake)
Code: A Car class has fields (color, speed) and methods (accelerate, brake)

Defining Classes

Simple Class

# file: 07_class_basic.zbr
# teaches: class definition, cue init
# chapter: 07-Classes-and-Instances

class Person
    var name: str
    var age: int

    cue init(name: str, age: int)
        this.name = name
        this.age = age

    def greet()
        print("Hi, I'm ${this.name}")

def main()
    var person = Person("Alice", 30)
    person.greet()  # Hi, I'm Alice

Breakdown:

• class Person — Define a class named Person.
• var name: str — Field (property) of the class.
• cue init(name, age) — Constructor. this.name = name initialises the field from the argument of the same name (using this. to disambiguate).
• def greet() — Method of the class.
• Person("Alice", 30) — Create an instance, passing constructor args.

The class fields don't need defaults when cue init always sets them. The "field default" form (var name: str = "") shines when you want to allow construction without specifying every field — see "Fields and Initialization" below.

Fields and Initialization

# file: 07_init.zbr
# teaches: field defaults vs. explicit init
# chapter: 07-Classes-and-Instances

class Rectangle
    var width: int = 0      # Defaults — class is constructible with `Rectangle()`
    var height: int = 0

    def area(): int
        return this.width * this.height

def main()
    var rect = Rectangle()
    rect.width = 10
    rect.height = 5
    print(rect.area())  # 50

Field defaults make a class bare-constructible (Rectangle() works) and let callers fill in only the fields they care about. Adding cue init(width: int, height: int) would make construction strict and let you drop the defaults — both styles compose.

Instance Methods

# file: 07_methods.zbr
# teaches: instance methods
# chapter: 07-Classes-and-Instances

class Counter
    var count: int = 0

    def increment()
        this.count = this.count + 1

    def decrement()
        this.count = this.count - 1

    def reset()
        this.count = 0

    def get_count(): int
        return this.count

def main()
    var counter = Counter()
    counter.increment()
    counter.increment()
    counter.increment()
    print(counter.get_count())  # 3
    counter.reset()
    print(counter.get_count())  # 0

Static Methods (Class Methods)

# file: 07_static.zbr
# teaches: static (class-level) methods
# chapter: 07-Classes-and-Instances

class MathUtil
    static
        def abs(x: int): int
            if x < 0
                return 0 - x
            return x

        def max_of(a: int, b: int): int
            if a > b
                return a
            return b

def main()
    print(MathUtil.abs(-5))  # 5
    print(MathUtil.max_of(10, 20))  # 20

When the methods are pure and don't share state, you have a choice: group them on a class for namespacing (as above) or write them as plain top-level defs in a module. Pick the form that reads better at the call site. Top-level def keeps the call as abs(-5); the class form makes MathUtil.abs(-5) self-documenting at a distance.

If you're new to programming

A class is like a template. When you create an instance (with Person()), you're making a specific copy from that template.

Fields are the properties (like name, age)

Methods are the behaviors (like greet())

Instance methods work on a specific object (person.greet())

Static methods belong to the class itself (MathUtil.abs())

Method Modifiers and Attributes

Three method-level attributes alter the generated code without changing the method's signature:

class Config
    @once
    def load(): str                  # body runs once; result cached on the instance
        return File.read("config.json")

    @profile
    def heavy_work()                 # body wrapped with Profile.start/end automatically
        # ...

    static
        @tag("unit", "fast")
        def test_defaults()          # tagged for filtered test runs
            assert Config().load() == "{}"

@once is the most common — handy for expensive lazy initialisation (loading a config file, building a lookup table) where you want the caching to be invisible at the call site.

with — Contextual Self

with obj makes obj the implicit receiver for bare-name method calls and field assignments inside the block. It's a compile-time textual rewrite — no runtime cost:

with g
    text("Status: ready")        # → g.text("Status: ready")
    button("OK", .ok)            # → g.button("OK", .ok)
    x = 5                        # → g.x = 5

What's rewritten:

What's not rewritten:

• Statements nested inside if, for, while, branch inside the block — those still need the full obj.method(...) form.
• Expression positions — only top-level statements in the block are rewritten.

with is most useful for GUI-style code where you'd otherwise type the same g. prefix on every line. It pairs naturally with using for layout containers (Chapter 14b).

Cues — Methods the Compiler Calls

You have already written one cue: cue init, the constructor. The word cue marks a method that the compiler calls for you, at a place the language defines. A def is a method that your code calls.

The set of cues is closed. There are exactly nine, and each one has a call site:

T in equals and compare is the declaring type: == and < hand the cue another value of the same type, so cue equals(other: int) is refused where you write it.

A cue is still a method, so you can call it yourself (a.equals(b), x.toString(), it.next()). The cue keyword adds two things: the compiler promises to call it at that site, and it checks the signature against the shape in the table when you declare it, not later.

If you know Python

Cues are Python's dunder methods without the underscores: __init__, __str__, __eq__, __hash__, __lt__ and friends, __iter__, __next__, and __enter__ / __exit__, which Python's with statement calls (Zebra's using, not its with). Two differences. The set is closed, so you cannot invent a cue the way you can invent __frobnicate__. And one compare returning negative/zero/positive stands in for all four ordering operators.

Printing, equality, hashing, ordering

# file: 07_cues_money.zbr
# teaches: the toString, equals, hash and compare cues, and where the compiler calls them
# chapter: 07-Classes-and-Instances

class Money
    var cents: int

    cue init(cents: int)
        .cents = cents

    cue toString(): str
        var c = .cents % 100
        var pad = if(c < 10, "0", "")
        return "${.cents / 100}.${pad}${c}"

    cue equals(other: Money): bool
        return .cents == other.cents

    cue hash(): int
        return .cents

    cue compare(other: Money): int
        return .cents - other.cents

def main()
    var price = Money(1505)
    print(price)                       # toString
    print("Total: ${price}")           # toString again, inside ${}

    var same = Money(1505)
    print(price == same)               # equals: same value, two objects
    print(price != Money(99))

    print(price < Money(2000))         # compare
    var prices = List(Money)()
    prices.add(Money(2000))
    prices.add(price)
    prices.add(Money(5))
    prices.sort()                      # compare, once per comparison
    print(prices.at(0))

    var notes: HashMap(Money, str) = HashMap()
    notes.put(price, "lunch")
    print(notes.get(same)!)            # hash finds the slot, equals confirms it
    var seen: Set(Money) = Set()
    seen.add(price)
    seen.add(same)
    print(seen.count())

Output:

15.05
Total: 15.05
true
true
true
0.05
lunch
1

What happened here:

• print(price) and "Total: ${price}" both called toString.
• price == same called equals. price and same are two separate objects, and they compare equal because their values match.
• < and sort() called compare. A negative result means "this one comes first", so sort() puts the smallest amount at index 0.
• The HashMap called hash to find the slot and equals to confirm the key. That is why notes.get(same) finds the entry stored under price, and why the Set ends up holding one element, not two.

Without cues, a class has identity

A class is a reference type: a variable holds a reference to an object, and var c = a gives the same object a second name. With no cue equals, == asks whether two names refer to the same object. With no cue hash, a HashMap keys a class by identity too.

# file: 07_cues_identity.zbr
# teaches: what == and HashMap keys mean for a class with no cues
# chapter: 07-Classes-and-Instances

class Ticket
    var seat: int

    cue init(seat: int)
        .seat = seat

def main()
    var a = Ticket(12)
    var b = Ticket(12)
    var c = a
    print(a == b)                      # two objects
    print(a == c)                      # one object, two names
    var holders: HashMap(Ticket, str) = HashMap()
    holders.put(a, "Ann")
    holders.put(b, "Bob")
    print(holders.count())             # keyed by identity

Output:

false
true
2

Identity is often what you want for an object that is something: a connection, a service, a game entity. Add equals (and hash, if it will be a key) when two separate objects with the same contents should count as the same value, as Money does. Ordering has no default at all: < and sort() on a class without cue compare do not build.

Keep the cues consistent

The compiler checks each cue's shape, and it checks that the cues which depend on each other come together: cue hash without cue equals is refused, and so is cue compare without cue equals. What it cannot check is that your cues agree with each other, so that part is up to you:

• Equal values must hash equally. If a == b, then a.hash() must equal b.hash(), or a HashMap will look in the wrong slot and miss a key it holds. The safe rule: hash only fields that equals compares.
• compare returns 0 exactly when equals is true. Otherwise the operators disagree. Here equals looks at the student and the score, while compare looks only at the score:

# file: 07_cues_consistency.zbr
# teaches: compare and equals must agree -- the compiler checks that both exist, not that they agree
# chapter: 07-Classes-and-Instances

class Grade
    var student: str
    var score: int

    cue init(student: str, score: int)
        .student = student
        .score = score

    cue equals(other: Grade): bool
        return .student == other.student and .score == other.score

    cue compare(other: Grade): int
        return .score - other.score

def main()
    var a = Grade("Ann", 90)
    var b = Grade("Bob", 90)
    print(a <= b)
    print(a >= b)
    print(a == b)

Output:

true
true
false

a <= b and a >= b both hold, yet a == b is false: compare says the two grades tie, and equals says they differ. Make them tell the same story. Either have compare break a tie on the student's name, or have equals compare only score.

Iteration: cue iter and cue next

for x in obj works on lists, ranges and maps (Chapters 03 and 05), and on any type that declares these cues:

• cue next(): E? hands out the next element, or nil when there are no more. A type with cue next is its own iterator.
• cue iter(): I returns a separate iterator object, whose type I declares cue next. Each for loop calls iter() again and gets a fresh one.

# file: 07_cues_iter.zbr
# teaches: cue iter and cue next -- making a type work in `for x in obj`
# chapter: 07-Classes-and-Instances

class Countdown
    var start: int

    cue init(start: int)
        .start = start

    cue iter(): CountdownIter          # a fresh iterator for each `for`
        return CountdownIter(.start)

class CountdownIter
    var n: int

    cue init(n: int)
        .n = n

    cue next(): int?                   # nil means "no more"
        if .n <= 0
            return nil
        .n = .n - 1
        return .n + 1

class Ticker                           # its own iterator: `cue next`, no `cue iter`
    var left: int

    cue init(left: int)
        .left = left

    cue next(): int?
        if .left <= 0
            return nil
        .left = .left - 1
        return .left + 1

def main()
    var launch = Countdown(3)
    for n in launch
        print("launch ${n}")
    for n in launch                    # iter() runs again: a fresh countdown
        print("again ${n}")

    var t = Ticker(2)
    for n in t
        print("tick ${n}")
    for n in t                         # t is used up: the body never runs
        print("never ${n}")
    else
        print("ticker exhausted")

    var manual = Ticker(1)
    print(manual.next()!)              # next() is callable by hand, too
    print(manual.next() == nil)

Output:

launch 3
launch 2
launch 1
again 3
again 2
again 1
tick 2
tick 1
ticker exhausted
1
true

The two shapes behave differently the second time round. Countdown can be walked any number of times, because each loop asks it for a new iterator. Ticker is used up after one pass, because the loop consumes the object itself. Use cue iter for something that holds its elements (a collection), and a lone cue next for something that produces them once (a stream of tokens, lines from a reader).

Only the cue spelling makes a type iterable: a def next() or def iter() is an ordinary method that for does not look at. (A debugger client's next() is a command, not an iterator, which is why the two spellings are kept apart.)

For most lazy sequences you will not write the iterator class at all. A generator (Chapter 05), a def that returns Iter(T) and produces values with yield, is compiled into a class with cue next for you.

What is not a cue

• allocate calls ordinary defs. allocate uses an allocator source's def allocator() and def deinit() (Chapter 14b). Those are spelled def, and cue deinit is refused as an unknown cue. (using is different: its begin and end are cues, in the table above.)
• A def begin() no using reaches is just a method. Like def next(), a def begin() or def end() is an ordinary method until a using block meets it. Older code that spells a using resource's hooks def begin() / def end() still compiles in this release, with a deprecation warning at each using; a later release will refuse it.
• There is no destructor. Zebra 1.0 has no cue deinit; the compiler refuses it. Memory is reclaimed by the arena that owns it (Chapter 14b), and anything with a release step (a file, a lock, a layout group) goes in a using block.
• len and contains are not cues. A def len(): int on your type is an ordinary method; nothing in the language calls it for you.
• There is no operator overloading. equals gives you ==, and compare gives you < <= > >=; nothing gives you +, *, or indexing with obj[i] on your own types. Write a named method (a.plus(b), bag.at(i)).

@derive — Auto-Generated Methods

For struct declarations, @derive(Debug, Eq, Hash) instructs the compiler to auto-generate the toString, equals, and hash cues based on the struct's fields:

@derive(Debug, Eq, Hash)
struct Point
    var x: int
    var y: int

def main()
    var p = Point(x: 1, y: 2)
    var q = Point(x: 1, y: 2)
    print(p.toString())  # Point(x=1, y=2)
    print(p.equals(q))  # true (and p == q routes through it)
    print(p.hash() == q.hash())  # true

What each trait generates:

The traits are independent — derive any subset. Without @derive, you'd write the cues by hand; with it, the compiler keeps them in sync as you add or remove fields. A hand-written cue wins over the derived one.

These three are the toString, equals and hash cues from the previous section, written for you. @derive does not write compare, iter or next; write those by hand.

@derive is struct-only. For a class, write the cues explicitly, as Money does above. A class has identity, and the field-by-field default is rarely what its equality should mean.

Real World: User Management

# file: 07_user_system.zbr
# teaches: realistic class design
# chapter: 07-Classes-and-Instances

class User
    var username: str = ""
    var email: str = ""
    var created_at: str = ""
    var is_active: bool = true

    def is_valid(): bool
        return this.username.len > 0 and this.email.contains("@")

    def deactivate()
        this.is_active = false

    def display_profile()
        print("User: ${this.username}")
        print("Email: ${this.email}")
        print("Active: ${this.is_active}")

class UserManager
    static
        var users: List(User) = List(User)()

        def add_user(user: User): bool
            if not user.is_valid()
                return false
            UserManager.users.add(user)
            return true

        def find_user(username: str): User?
            for user in UserManager.users
                if user.username == username
                    return user
            return nil

        def user_count(): int
            return UserManager.users.count()

def main()
    var user1 = User()
    user1.username = "alice"
    user1.email = "alice@example.com"

    if UserManager.add_user(user1)
        print("User added")

    if UserManager.find_user("alice") as found
        found.display_profile()

Common Patterns

Value Object

class Point
    var x: int = 0
    var y: int = 0

    def distance_from_origin(): float
        return 0.0  # sqrt(x*x + y*y) once you have a sqrt to call

Service Class

class EmailService
    static
        def send(to: str, subject: str, body: str): bool
            # Implementation
            return true

Builder Pattern

class UserBuilder
    var username: str = ""
    var email: str = ""
    var age: int = 0

    def with_username(name: str)
        this.username = name

    def with_email(addr: str)
        this.email = addr

    def build(): User
        var user = User()
        user.username = this.username
        user.email = this.email
        return user

Common Mistakes

❌ Mistake: Forgetting to initialize fields

class Person
    var name: str  # No default value
var p = Person()
print(p.name)  # ❌ Uninitialized!

✅ Better:

class Person
    var name: str = ""  # Has default

❌ Mistake: Modifying shared fields unintentionally

class Counter
    static var count: int = 0
    
    def reset
        count = 0  # Affects ALL instances!

✅ Better:

class Counter
    var count: int = 0  # Instance field
    
    def reset
        count = 0  # Only this instance

❌ Mistake: Writing a cue as a def

class Widget
    var n: int
    cue init(n: int)
        .n = n
    def toString(): str
        return "Widget(${.n})"

💡 Why it's wrong: toString, equals, hash and compare are found by name, so there is one spelling for each. The compiler refuses the def and names the fix:

error: `toString` is a cue -- the compiler calls it for print and string interpolation -- so it is written `cue toString(): str`, not `def`

The constructor is the same: def init(...) is refused with "the constructor is written cue init(...), not def init".

✅ Better: cue toString(): str

❌ Mistake: A hash with no equals

class Key
    var id: int
    cue init(id: int)
        .id = id
    cue hash(): int
        return .id

💡 Why it's wrong: a key is found by its hash and confirmed by equals. On its own, the hash would quietly leave the key compared by identity:

error: `cue hash` needs `cue equals` on the same type (a HashMap key is looked up by hash, then confirmed by equals)

✅ Better: add cue equals(other: Key): bool comparing the same fields the hash uses.

❌ Mistake: A cue with the wrong shape

class Ver
    var n: int
    cue init(n: int)
        .n = n
    cue equals(other: Ver): bool
        return .n == other.n
    cue compare(other: Ver): bool    # "is this less?" -- the wrong question
        return .n < other.n

💡 Why it's wrong: compare answers "before, same, or after" with one int, so one cue can drive all four operators and sort(). The shape is checked where you declare it:

error: `cue compare` takes the other value and returns int (negative, zero, positive): `cue compare(other: Ver): int`

✅ Better: return .n - other.n from a cue compare(other: Ver): int.

❌ Mistake: A compare with no equals

class Score
    var n: int
    cue init(n: int)
        .n = n
    cue compare(other: Score): int
        return .n - other.n

💡 Why it's wrong: with no equals, == would still mean "the same object", so two scores could be neither less nor greater than each other and still not equal. The compiler refuses the pair at the declaration:

error: `cue compare` needs `cue equals` on the same type (otherwise `a <= b` and `a >= b` can both hold while `a == b` is false)

✅ Better: add cue equals(other: Score): bool comparing the same fields as compare (on a struct, @derive(Eq) counts).

❌ Mistake: Inventing a cue (or looking for a destructor)

class Connection
    var open: bool = true
    cue deinit()
        .open = false

💡 Why it's wrong: the nine cues are the whole set. Anything else is refused, deinit included:

error: unknown cue 'deinit': the cues are init, toString, equals, hash, compare, iter, next, begin, end (a method the compiler calls for you; anything else is a `def`)

✅ Better: for a release step, give the class cue begin() / cue end() and use it in a using block (Chapter 14b). For any other method, write def.

❌ Mistake: using hooks written as def

class Section
    def begin()
        print("start")
    def end()
        print("stop")

def main()
    using Section()
        print("work")

💡 Why it's wrong: using calls begin and end for you, so they are cues. Code written before they were still builds and runs, but every using that reaches the def pair prints a warning, and a later release will refuse it:

warning: type 'Section' used in 'using' declares begin/end with `def`; they are cues now -- write `cue begin()` and `cue end()` (`def` is deprecated here and will be refused)

✅ Better: cue begin() and cue end().

Exercises

Exercise 1: Bank Account

Create a BankAccount class with deposit and withdraw methods:

class BankAccount
    var balance: float = 0.0
    var account_number: str = ""

    def deposit(amount: float)
        this.balance = this.balance + amount

    def withdraw(amount: float): bool
        if amount > this.balance
            return false
        this.balance = this.balance - amount
        return true

    def get_balance(): float
        return this.balance

def main()
    var account = BankAccount()
    account.account_number = "1234567890"
    account.deposit(1000.0)
    print("Balance: ${account.get_balance()}")
    account.withdraw(100.0)
    print("Balance: ${account.get_balance()}")

Exercise 2: Product Catalog

Create a Product class and a simple store:

class Product
    var name: str = ""
    var price: float = 0.0
    var quantity: int = 0

    def total_value(): float
        return this.price * @as(f64, @floatFromInt(this.quantity))

class Store
    var products: List(Product) = List(Product)()

    def add_product(product: Product)
        this.products.add(product)

    def total_inventory_value(): float
        var total = 0.0
        for product in this.products
            total = total + product.total_value()
        return total

def main()
    var store = Store()

    var apple = Product()
    apple.name = "Apple"
    apple.price = 0.50
    apple.quantity = 100
    store.add_product(apple)

    var orange = Product()
    orange.name = "Orange"
    orange.price = 0.75
    orange.quantity = 80
    store.add_product(orange)

    print("Total value: ${store.total_inventory_value()}")

Next Steps

• → 08-Interfaces — Contracts for classes
• → 09-Inheritance — Class hierarchies
• 🏋 Project-2-HTTP-Server — Use classes extensively

Key Takeaways

• Classes group data and behavior — Fields + methods
• Instances are references — Each Person() is a new object, but var b = a gives the same object a second name
• Cues are the methods the compiler calls — init, toString, equals, hash, compare, iter, next, and begin / end for using; the set is closed, and there is no cue deinit
• == on a class is identity unless the class has cue equals; a HashMap key needs cue hash and cue equals, ordering needs cue compare and cue equals, and they must agree
• Instance methods work on specific objects
• Shared methods belong to the class, not instances
• Initialize fields — Don't leave them undefined
• Methods should have clear names — deposit() not d()

Next: Head to 08-Interfaces to define contracts between classes.

7b: Structs, Unions, and Value Types

Audience: All
Time: 120 minutes
Prerequisites: 02-Values, 04-Functions, 07-Classes
You'll learn: Structs (value types), unions (tagged unions), ^T heap indirection, except for struct updates, branch pattern matching on unions

The Big Picture

Zebra has three kinds of composite types:

You already know classes (Chapter 07). This chapter covers the other two — and they're essential for writing efficient, safe Zebra code.

Structs: Value Types

A struct is like a class, but with value semantics. When you assign a struct variable, the entire value is copied.

# file: 07b_struct_basic.zbr
# teaches: struct definition and value semantics
# chapter: 07b-Structs-Unions

struct Point
    var x: int
    var y: int

    cue init(x: int, y: int)
        this.x = x
        this.y = y

    def distSq(): int
        return x * x + y * y

def main()
    var a = Point(3, 4)
    var b = a              # copies the entire Point
    print(a.distSq())  # 25
    print(b.x)  # 3

When to use struct vs class

• Struct: Small, short-lived values. Config objects, coordinates, tokens, AST nodes.
• Class: Long-lived objects with identity. Collections, services, shared mutable state.

Rule of thumb: if you'd never ask "is this the same object?", use a struct.

Cues on structs

A struct takes the same cues as a class (Chapter 07, "Cues"): toString for printing, equals for ==, hash for use as a key, compare for < and sort(), iter / next for for. They work by value. There is no identity to fall back on, so == on a struct needs an equals, written by hand or by @derive(Eq).

# file: 07b_struct_cues.zbr
# teaches: cues on a struct -- toString, equals, hash, compare, by value
# chapter: 07b-Structs-Unions

struct Version
    var major: int
    var minor: int

    cue toString(): str
        return "v${.major}.${.minor}"

    cue equals(other: Version): bool
        return .major == other.major and .minor == other.minor

    cue hash(): int
        return .major * 1000 + .minor

    cue compare(other: Version): int
        if .major != other.major
            return .major - other.major
        return .minor - other.minor

def main()
    var installed = Version(major: 1, minor: 10)
    var wanted = Version(major: 1, minor: 2)
    print(installed)
    print(installed > wanted)          # compare: 10 > 2, not "1.10" < "1.2"

    var releases = List(Version)()
    releases.add(installed)
    releases.add(wanted)
    releases.add(Version(major: 0, minor: 9))
    releases.sort()
    for r in releases
        print(r)

    var copy = installed               # a struct copy...
    print(copy == installed)           # ...is equal by value
    var seen: Set(Version) = Set()
    seen.add(installed)
    seen.add(copy)
    print(seen.count())

Output:

v1.10
true
v0.9
v1.2
v1.10
true
1

@derive(Debug, Eq, Hash) (Chapter 07) writes toString, equals and hash field by field. It does not write compare; write that one yourself, as Version does. compare needs an equals on the same type, and a derived one counts, so @derive(Eq) plus a hand-written cue compare is enough. A hand-written cue wins over a derived one, so you can derive Eq, Hash and still write your own toString.

except — Struct Update Copies

The except keyword creates a copy of a struct with specific fields overridden. This is the primary idiom for immutable-style struct manipulation:

# file: 07b_except.zbr
# teaches: except struct update syntax
# chapter: 07b-Structs-Unions

struct Config
    var indent: int
    var owner: str
    var verbose: bool

    cue init(indent: int, owner: str, verbose: bool)
        this.indent = indent
        this.owner = owner
        this.verbose = verbose

    def indented(): Config
        var c = this except
            indent = indent + 1
        return c

    def withOwner(name: str): Config
        var c = this except
            owner = name
        return c

def main()
    var base = Config(0, "nobody", false)
    var inner = base.indented()
    var owned = inner.withOwner("Alice")
    print(owned.indent)  # 1
    print(owned.owner)  # Alice
    print(owned.verbose)  # false (unchanged)

Critical rule: no method chaining on temporaries

# WRONG — temporary struct can't be mutated:
# var c = makeConfig().indented().withOwner("Foo")

# RIGHT — use intermediate variables:
var c0 = makeConfig()
var c1 = c0.indented()
var c = c1.withOwner("Foo")

Enums

Enums define a fixed set of named constants:

# file: 07b_enum.zbr
# teaches: enum types
# chapter: 07b-Structs-Unions

enum Color
    red
    green
    blue

enum Status(int)
    ok = 0
    err = 1

def main()
    var c = Color.red
    var s = Status.ok
    print(s)  # 0

Use branch (see below) to match on enum values.

Unions: Tagged Unions

A union is a type that can hold one of several variants, each with its own payload type. Think of it as a type-safe alternative to "this could be an int OR a string OR nothing."

# file: 07b_union_basic.zbr
# teaches: union definition and construction
# chapter: 07b-Structs-Unions

union Value
    int_: int
    str_: str
    bool_: bool
    none_

def main()
    var v1 = Value.int_(42)
    var v2 = Value.str_("hello")
    var v3 = Value.none_()

Naming convention: Variants that collide with Zebra keywords get a trailing underscore: int_, str_, bool_, none_.

branch — Pattern Matching on Unions

Use branch to inspect which variant a union holds:

# file: 07b_branch.zbr
# teaches: branch pattern matching
# chapter: 07b-Structs-Unions

union Shape
    circle: float           # radius
    rect: Dims              # width/height struct
    point                   # no payload

struct Dims
    var w: float
    var h: float
    cue init(w: float, h: float)
        this.w = w
        this.h = h

def describe(s: Shape): str
    branch s
        on Shape.circle as r
            return "Circle with radius ${r}"
        on Shape.rect as d
            return "Rectangle ${d.w} x ${d.h}"
        on Shape.point
            return "Point"
        else
            pass
    return "unknown"

def main()
    var c = Shape.circle(3.14)
    var r = Shape.rect(Dims(10.0, 5.0))
    print(describe(c))  # Circle with radius 3.14
    print(describe(r))  # Rectangle 10.0 x 5.0

Rules:

• Each on arm binds the variant's payload to a name (as r, as d)
• else with pass is required for non-exhaustive branches
• Payload-less variants (point) don't need as binding

Branch on enums and strings

branch also works on enums and strings:

branch color
    on Color.red
        print("Stop")
    on Color.green
        print("Go")
    else
        print("Unknown")

branch command
    on "quit"
        sys.exit(0)
    on "help"
        print("Available commands: quit, help")
    else
        print("Unknown command")

^T — Heap Indirection for Recursive Types

Structs and unions live on the stack. But what if a type needs to reference itself? A Node with a next field that's also a Node would be infinitely sized.

^T solves this — it's a heap-allocated pointer to T:

# file: 07b_heap_indirect.zbr
# teaches: ^T heap indirection
# chapter: 07b-Structs-Unions

struct Node
    var value: int
    var next: ^Node?     # optional heap pointer to another Node

    cue init(value: int, next: ^Node?)
        this.value = value
        this.next = next

def main()
    var a = Node(1, nil)
    var b = Node(2, nil)
    a.next = b              # auto-boxes: copies b to the heap
    print(a.value)  # 1

Key points:

• ^T in field type → *T in Zig (a pointer)
• ^T? → ?*T (an optional pointer)
• Assignment to a ^T field auto-boxes: allocates a heap copy
• Inside branch, ^T payloads are transparent — the binding has type T, not *T

Where you see ^T in practice

The Zebra compiler's own AST uses ^T heavily:

union Expr
    int_: int
    str_: str
    binary: ^ExprBinary       # recursive: contains two sub-Exprs
    call: ^ExprCall

struct ExprBinary
    var left: ^Expr
    var op: BinaryOp
    var right: ^Expr

Putting It All Together: A Small AST

# file: 07b_mini_ast.zbr
# teaches: combining structs, unions, and ^T
# chapter: 07b-Structs-Unions

union Expr
    num: int
    add: ^BinExpr
    neg: ^Expr

struct BinExpr
    var left: ^Expr
    var right: ^Expr

    cue init(left: ^Expr, right: ^Expr)
        this.left = left
        this.right = right

def eval(e: Expr): int
    branch e
        on Expr.num as n
            return n
        on Expr.add as b
            return eval(b.left) + eval(b.right)
        on Expr.neg as inner
            return 0 - eval(inner)
        else
            pass
    return 0

def main()
    # 3 + (neg 2) = 1
    var three = Expr.num(3)
    var two = Expr.neg(Expr.num(2))
    var sum = Expr.add(BinExpr(three, two))
    print(eval(sum))  # 1

Exercises

Exercise 1: RGB Color Struct

Define a Color struct with r, g, b fields (all int). Add a mix method that averages two colors using except.

struct Color
    var r: int
    var g: int
    var b: int

    cue init(r: int, g: int, b: int)
        this.r = r
        this.g = g
        this.b = b

    def mix(other: Color): Color
        var c = this except
            r = (r + other.r) / 2
            g = (g + other.g) / 2
            b = (b + other.b) / 2
        return c

def main()
    var red = Color(255, 0, 0)
    var blue = Color(0, 0, 255)
    var purple = red.mix(blue)
    print(purple.r)  # 127
    print(purple.b)  # 127

Exercise 2: Expression Evaluator

Extend the mini AST to support multiplication. Add a mul variant and handle it in eval.

Key Takeaways

• struct = value type; assignment copies the whole value
• Cues work on structs by value — == on a struct needs equals (hand-written or @derive(Eq)); compare is always hand-written and needs an equals beside it
• union = tagged union; holds one variant at a time
• branch = pattern matching on unions, enums, and strings
• except = create a struct copy with specific fields overridden
• ^T = heap-indirection pointer; breaks recursive type cycles
• Use structs for small config/data objects, classes for stateful services

Next: Head to 08-Interfaces for polymorphism without inheritance.

08: Interfaces and Protocols

Audience: All
Time: 120 minutes
Prerequisites: 07-Classes-and-Instances
You'll learn: Define interfaces, implement contracts, polymorphism, real-world patterns

The Big Picture

Interfaces define contracts—promises about what an object can do, without specifying how. Instead of depending on concrete classes, you depend on interfaces. This enables:

• Swappable implementations — Change how something works without changing callers
• Polymorphism — Treat different objects the same way
• Testing — Mock implementations easily
• Flexibility — Add new implementations without modifying existing code

Defining Interfaces

Simple Interface

# file: 08_interface_basic.zbr
# teaches: interface definition
# chapter: 08-Interfaces-and-Protocols

interface Animal
    def speak(): str
    def move()

class Dog implements Animal
    def speak(): str
        return "Woof!"

    def move()
        print("Running on four legs")

class Bird implements Animal
    def speak(): str
        return "Tweet!"

    def move()
        print("Flying through the air")

def main()
    var dog: Animal = Dog()
    print(dog.speak())  # Woof!
    dog.move()             # Running on four legs

    var bird: Animal = Bird()
    print(bird.speak())  # Tweet!
    bird.move()            # Flying through the air

Key points:

• interface Animal — Define what any animal must do
• implements Animal goes on the class line itself (class Dog implements Animal) — Promise to implement all methods
• To implement more than one interface, list them on the same line: class Dog implements Animal, Trainable
• Treat objects as their interface type (var dog: Animal)

Multiple Methods

# file: 08_interface_methods.zbr
# teaches: interface with multiple methods
# chapter: 08-Interfaces-and-Protocols

interface PaymentProcessor
    def process(amount: float): bool
    def refund(transaction_id: str): bool
    def get_status(transaction_id: str): str

class CreditCardProcessor implements PaymentProcessor
    def process(amount: float): bool
        print("Processing credit card: ${amount}")
        return true
        
    def refund(transaction_id: str): bool
        print("Refunding transaction: ${transaction_id}")
        return true
        
    def get_status(transaction_id: str): str
        return "completed"

class PayPalProcessor implements PaymentProcessor
    def process(amount: float): bool
        print("Processing PayPal: ${amount}")
        return true
        
    def refund(transaction_id: str): bool
        print("PayPal refund: ${transaction_id}")
        return true
        
    def get_status(transaction_id: str): str
        return "pending"

Polymorphism in Action

Using Different Implementations

# file: 08_polymorphism.zbr
# teaches: polymorphic behavior
# chapter: 08-Interfaces-and-Protocols

def process_payment(processor: PaymentProcessor, amount: float)
    if processor.process(amount)
        print("Payment successful")
    else
        print("Payment failed")

def main()
    var cc_processor = CreditCardProcessor()
    var paypal_processor = PayPalProcessor()

    # Same code, different behavior
    process_payment(cc_processor, 99.99)
    process_payment(paypal_processor, 49.99)

Collections of Interface Types

# file: 08_collection_interface.zbr
# teaches: storing different implementations
# chapter: 08-Interfaces-and-Protocols

class Zoo
    var animals: List(Animal) = List(Animal)()

    def add_animal(animal: Animal)
        this.animals.add(animal)

    def make_them_speak()
        for animal in this.animals
            print(animal.speak())

    def exercise_all()
        for animal in this.animals
            animal.move()

def main()
    var zoo = Zoo()
    zoo.add_animal(Dog())
    zoo.add_animal(Bird())
    zoo.add_animal(Dog())

    zoo.make_them_speak()
    zoo.exercise_all()

Real World: Logging System

# file: 08_logger_system.zbr
# teaches: realistic interface use
# chapter: 08-Interfaces-and-Protocols

interface Logger
    def debug(message: str)
    def info(message: str)
    def warn(message: str)
    def log_error(message: str)

class ConsoleLogger implements Logger
    def debug(message: str)
        print("[DEBUG] ${message}")
        
    def info(message: str)
        print("[INFO] ${message}")
        
    def warn(message: str)
        print("[WARN] ${message}")
        
    def log_error(message: str)
        print("[ERROR] ${message}")

class FileLogger implements Logger
    def debug(message: str)
        # Write to file: [DEBUG] message
        
    def info(message: str)
        # Write to file: [INFO] message
        
    def warn(message: str)
        # Write to file: [WARN] message
        
    def log_error(message: str)
        # Write to file: [ERROR] message

class Application
    var logger: Logger

    def set_logger(l: Logger)
        this.logger = l

    def do_work()
        this.logger.info("Starting work")
        # Do work
        this.logger.info("Work complete")

def main()
    var app = Application()

    # Use console logger
    app.set_logger(ConsoleLogger())
    app.do_work()

    # Switch to file logger (same code, different output)
    app.set_logger(FileLogger())
    app.do_work()

Why log_error, not error? error is a plain identifier in Zebra itself, but an interface's methods are also emitted as a Zig vtable field name, and error is a Zig keyword there — interface Logger with a plain def error(...) type-checks but fails at build with a Zig parse error (expected '.', found ':'). It's a gap in the compiler's keyword-escaping for interface vtables specifically (BUG to file), not a rule of the language — but until it's fixed, avoid error as an interface method name.

Common Patterns

Strategy Pattern

interface SortStrategy
    def sort(items: List(int))

class AscendingSort implements SortStrategy
    def sort(items: List(int))
        # Sort ascending

class DescendingSort implements SortStrategy
    def sort(items: List(int))
        # Sort descending

class Sorter
    var strategy: SortStrategy

    def set_strategy(s: SortStrategy)
        this.strategy = s

    def sort(items: List(int))
        this.strategy.sort(items)

Adapter Pattern

interface NewSystem
    def process(data: str)

class OldSystem
    def old_process(input: str)
        # Old implementation
        pass

class OldSystemAdapter implements NewSystem
    var old_system: OldSystem = OldSystem()

    def process(data: str)
        # Adapt new interface to old system
        this.old_system.old_process(data)

If you're new to programming

An interface is like a promise or contract. When you say a class "implements" an interface, you promise that it has all the methods the interface requires.

This lets you write code that works with any object that implements that interface, without knowing exactly which class it is.

Polymorphism means "many forms"—the same code can work with different types of objects.

If you know Python

# Python (using duck typing)
class Dog:
    def speak(self):
        return "Woof!"

class Bird:
    def speak(self):
        return "Tweet!"

def get_sound(animal):
    return animal.speak()

# Zebra (using interfaces)
interface Animal
    def speak(): str

class Dog implements Animal
    def speak(): str
        return "Woof!"

class Bird implements Animal
    def speak(): str
        return "Tweet!"

def get_sound(animal: Animal): str
    return animal.speak()

Python relies on duck typing ("if it quacks like a duck"). Zebra makes the contract explicit with interfaces.

Common Mistakes

❌ Mistake: Not implementing all interface methods

interface Animal
    def speak(): str
    def move()

class Dog implements Animal
    def speak(): str
        return "Woof!"
    # ❌ Missing: def move

💡 Why: The compiler requires all methods. You're breaking the contract.

✅ Better:

class Dog implements Animal
    def speak(): str
        return "Woof!"
    def move()
        print("Running")

❌ Mistake: Wrong method signature

interface PaymentProcessor
    def process(amount: float): bool

class CreditCard implements PaymentProcessor
    def process(amount: int): bool  # ❌ int, not float
        return true

✅ Better:

class CreditCard implements PaymentProcessor
    def process(amount: float): bool  # ✅ Matches interface
        return true

❌ Mistake: Forgetting to declare implementation

class Dog  # ❌ Doesn't say implements Animal
    def speak(): str
        return "Woof!"

✅ Better:

class Dog implements Animal  # ✅ Explicit contract
    def speak(): str
        return "Woof!"

Exercises

Exercise 1: Shape Interface

Create an interface for shapes and multiple implementations:

interface Shape
    def area(): float
    def perimeter(): float

class Circle implements Shape
    var radius: float = 0.0

    def area(): float
        return 3.14 * this.radius * this.radius
    def perimeter(): float
        return 2.0 * 3.14 * this.radius

class Rectangle implements Shape
    var width: float = 0.0
    var height: float = 0.0

    def area(): float
        return this.width * this.height
    def perimeter(): float
        return 2.0 * (this.width + this.height)

def print_shape_info(shape: Shape)
    print("Area: ${shape.area()}")
    print("Perimeter: ${shape.perimeter()}")

def main()
    var circle = Circle()
    circle.radius = 5.0
    print_shape_info(circle)

    var rect = Rectangle()
    rect.width = 10.0
    rect.height = 5.0
    print_shape_info(rect)

Exercise 2: Database Interface

Create a database interface with multiple implementations:

interface Database
    def save(key: str, value: str): bool
    def load(key: str): str?
    def delete(key: str): bool

class MemoryDatabase implements Database
    var data: HashMap(str, str) = HashMap(str, str)()

    def save(key: str, value: str): bool
        this.data.put(key, value)
        return true
    def load(key: str): str?
        return this.data.get(key)
    def delete(key: str): bool
        this.data.remove(key)
        return true

def main()
    var db: Database = MemoryDatabase()
    db.save("user1", "Alice")
    db.save("user2", "Bob")

    if db.load("user1") as user
        print("Found: ${user}")

    db.delete("user1")

Exercise 3: Document Processor

Create an interface for document processors:

interface DocumentProcessor
    def process(content: str): str
    def validate(content: str): bool

class MarkdownProcessor implements DocumentProcessor
    def process(content: str): str
        # Convert markdown to HTML
        return "<html>${content}</html>"
    def validate(content: str): bool
        return content.len > 0

class JSONValidator implements DocumentProcessor
    def process(content: str): str
        return content  # Already valid JSON
    def validate(content: str): bool
        return content.contains("{") and content.contains("}")

def process_document(processor: DocumentProcessor, doc: str)
    if processor.validate(doc)
        var processed = processor.process(doc)
        print("Processed: ${processed}")
    else
        print("Invalid document")

def main()
    var md = MarkdownProcessor()
    process_document(md, "# Hello")

    var json = JSONValidator()
    process_document(json, "{}")

Next Steps

• → 09-Composition-and-Mixins — Sharing behaviour without inheritance
• → 14-Contracts — More complex interfaces
• 🏋 Project-2-HTTP-Server — Interfaces for handlers and middleware

Key Takeaways

• Interfaces define contracts — What methods must exist, not how they work
• Polymorphism lets you write code once, work with many types
• Swap implementations without changing callers
• Testing is easier — Mock implementations implement the interface
• Makes code flexible — Add new implementations without modifying existing code
• Forces clear design — Interfaces make relationships explicit

Next: Head to 09-Composition-and-Mixins for code reuse without classical inheritance.

09: Composition and Mixins

Audience: All Time: 90 minutes Prerequisites: 07-Classes, 08-Interfaces You'll learn: Why Zebra rejects class inheritance, how to share behaviour with mixins, and how to combine smaller classes via composition

Why no inheritance?

Zebra deliberately omits class inheritance. There is no extends, no super, no parent class.

Decades of inheritance experience surfaced known problems: the fragile base-class problem (a change in the parent silently breaks subclasses), diamond inheritance ambiguity, surprising method-resolution order, and tight coupling between base and derived classes. Languages like Go and Rust have shown that large systems can be built without ever needing inheritance.

Zebra leans on three reuse primitives, each with a clear role:

This chapter covers mixins (adds) and composition (field-holding). Interfaces were covered in Chapter 08.

Mixins — sharing methods across classes

A mixin is a named bag of methods that a class can pull in. Declare it with mixin:

# file: 09_mixin_basic.zbr
# teaches: declaring and using mixins
# chapter: 09-Composition-and-Mixins

mixin Loggable
    def log(message: str)
        print("[log] ${message}")

mixin Cacheable
    var _cache: HashMap(str, str)

    cue init()
        _cache = HashMap(str, str)()

    def cache_get(key: str): str?
        return _cache.get(key)

    def cache_set(key: str, value: str)
        _cache.set(key, value)

Then use adds on the class:

class UserService adds Loggable, Cacheable
    var _cache: HashMap(str, str)   # redeclared — see the note below

    cue init()
        _cache = HashMap(str, str)()

    def lookup(id: str): str
        var hit = this.cache_get(id)
        if hit as found
            return found
        this.log("cache miss for ${id}")
        var fetched = "user-${id}"
        this.cache_set(id, fetched)
        return fetched

def main()
    var svc = UserService()
    print(svc.lookup("42"))  # logs "cache miss for 42", returns "user-42"
    print(svc.lookup("42"))  # silent cache hit, returns "user-42"

Key points:

• A mixin is declared with mixin, not class. It can't be instantiated on its own.
• class C adds M1, M2, M3 includes M1's, M2's, and M3's methods (and fields) into C as if they were declared on C directly.
• From outside the class, mixin members look identical to native ones: svc.log(...) and svc.cache_get(...) need no dotted prefix.
• No method-resolution magic: if two mixins define a method with the same name, that's a compile error — pick one or rename one.

Two workarounds you'll need with the current compiler. The current Zebra compiler (2026-09) has a codegen gap with mixin state that a plain reading of the language wouldn't predict, so both patterns below are deliberate, not stylistic:

1. Redeclare mixin var fields on the class itself (var _cache: HashMap(str, str) on UserService above, matching the mixin's declaration exactly). Without the redeclaration, the field type-checks fine but the compiler never emits it into the class's struct, and every access — even this.field — fails at compile time with "no field named … in struct". This is a compiler bug, not a language rule; it has no workaround inside the mixin's own methods, only at the class that adds it.
2. Call a mixin method from the class's own methods with an explicit this. prefix (this.cache_get(id), not bare cache_get(id)). Bare calls to mixin methods only resolve for an external caller (svc.cache_get(...)); called bare from inside the class that added the mixin, they fail with "undefined name". this. sidesteps it.

Composition — has-a, not is-a

When a class needs the services of another class but isn't conceptually the same kind of thing, hold an instance as a field:

# file: 09_composition.zbr
# teaches: composition with helper classes
# chapter: 09-Composition-and-Mixins

class FileWriter
    var path: str = ""

    cue init(p: str)
        path = p

    def write(content: str)
        File.write(path, content)

class AuditedReport
    var writer: FileWriter
    var entries: List(str)

    cue init(p: str)
        this.writer = FileWriter(p)
        this.entries = List(str)()

    def add_entry(line: str)
        this.entries.add(line)

    def publish()
        var content = this.entries.join("\n")
        this.writer.write(content)

def main()
    var r = AuditedReport("/tmp/audit.log")
    r.add_entry("user logged in")
    r.add_entry("user updated profile")
    r.publish()

AuditedReport uses FileWriter; it isn't a FileWriter. The same idea inheritance-heavy languages call "favouring composition over inheritance." In Zebra it's just the natural pattern.

Mixin vs. composition — when to use each

A reasonable default order: reach for interfaces first (when you only need a contract), composition second (when you need a helper), mixins last (when the same exact methods need to be reused verbatim across multiple classes).

Multiple mixins — building richer classes

A class can combine several mixins:

# file: 09_multiple_mixins.zbr
# teaches: combining multiple mixins
# chapter: 09-Composition-and-Mixins

mixin Timestamped
    var created_at_ms: int = 0

    def stamp_now()
        this.created_at_ms = DateTime.now().toEpoch()

mixin Tagged
    var tags: List(str)

    cue init()
        this.tags = List(str)()

    def tag(t: str)
        this.tags.add(t)

class BlogPost adds Timestamped, Tagged
    var title: str = ""
    var body: str = ""
    var created_at_ms: int = 0      # redeclared from Timestamped — see the note above
    var tags: List(str)             # redeclared from Tagged

    cue init(t: str, b: str)
        this.title = t
        this.body = b
        this.tags = List(str)()
        this.stamp_now()

def main()
    var p = BlogPost("Hello", "First post body")
    p.tag("intro")
    p.tag("zebra")
    print("${p.title} — ${p.tags.count()} tags @ ${p.created_at_ms} ms")

The class picks up created_at_ms, tags, stamp_now(), and tag(...) as if they were declared directly on BlogPost.

Polymorphism — reach for interfaces (Chapter 08)

When you want a function that works on "anything that can do X," use an interface — not a hierarchy:

# file: 09_polymorphism.zbr
# teaches: interface-based polymorphism (instead of inheritance)
# chapter: 09-Composition-and-Mixins

interface Sounding
    def sound(): str

class Dog implements Sounding
    var name: str = ""

    cue init(n: str)
        this.name = n

    def sound(): str
        return "${this.name}: Woof!"

class Cat implements Sounding
    var name: str = ""

    cue init(n: str)
        this.name = n

    def sound(): str
        return "${this.name}: Meow!"

def main()
    var animals: List(Sounding) = List(Sounding)()
    animals.add(Dog("Rex"))
    animals.add(Cat("Whiskers"))

    for a in animals
        print(a.sound())

Both Dog and Cat implements Sounding. Code that wants any sounding thing accepts a Sounding; the underlying class can be anything. This is the polymorphism inheritance offers — without coupling Dog or Cat to a shared base implementation.

Real world: a document with capabilities

A realistic example combining interface + mixin + field composition:

# file: 09_document_capabilities.zbr
# teaches: combining interface + mixin + composition
# chapter: 09-Composition-and-Mixins

interface Publishable
    def publish()

mixin Versioned
    var version: int = 0

    def bump()
        this.version = this.version + 1

class Storage
    var path: str = ""

    cue init(p: str)
        path = p

    def write(content: str)
        File.write(path, content)

class BlogPost implements Publishable adds Versioned
    var title: str = ""
    var body: str = ""
    var storage: Storage
    var version: int = 0            # redeclared from Versioned — see the note above

    cue init(t: str, store_path: str)
        title = t
        storage = Storage(store_path)

    def publish()
        this.bump()                              # mixin method
        var content = "${this.title} v${this.version}\n\n${this.body}"
        this.storage.write(content)              # composition

def main()
    var post = BlogPost("Hello", "/tmp/hello.txt")
    post.body = "First post"
    post.publish()                       # writes v1
    post.body = "First post (revised)"
    post.publish()                       # writes v2

BlogPost plays the role of a Publishable (interface), gains version-tracking (mixin), and uses a Storage helper (field). Three orthogonal capabilities, none of them coupled into a fragile inheritance chain.

If you're new to programming

Inheritance is a popular but easy-to-misuse feature. The mental shift Zebra asks of you is: instead of "Dog is a kind of Animal," ask "what does Dog need to do?" and pull those abilities in piece by piece.

A useful default: start with no mixins. When two classes share a contract, declare an interface and have both implements it. When one class needs another class's services, hold an instance as a field. When two classes need exactly the same methods, factor those methods into a mixin and have both adds it.

Common mistakes

❌ Reaching for class hierarchies you can't have

class Dog inherits Animal       # ❌ `inherits` doesn't exist in Zebra
    def bark
        print("${name} says: Woof!")

✅ Use a mixin or an interface:

mixin Named
    var name: str = ""

class Dog adds Named
    def bark
        print("${name} says: Woof!")

❌ Calling super to chain into a "parent"

def accelerate
    super.accelerate()           # ❌ no `super` in Zebra

✅ Express the shared behaviour as a method on a mixin and call it directly:

mixin Acceleratable
    var speed: int = 0

    def base_accelerate
        speed = speed + 10

class Car adds Acceleratable
    def accelerate
        base_accelerate()
        print("Car cruising at ${speed} mph")

❌ Two mixins declaring the same method name

mixin A
    def hello
        print("A")

mixin B
    def hello
        print("B")

class C adds A, B               # ❌ ambiguous: which hello()?

✅ Rename one or pick the canonical mixin:

mixin A
    def hello_a
        print("A")

mixin B
    def hello_b
        print("B")

class C adds A, B

❌ Modelling a "kind-of" relationship with a mixin

A mixin is for shared methods, not for "is-a" modelling. If you find yourself reaching for inheritance because Dog is a kind of Animal, the right answer is usually an interface for the shared contract, with each concrete class implementing it independently.

Exercises

Exercise 1: Vehicle behaviours

Build three vehicle types (Car, Motorcycle, Truck) that share starting/stopping behaviour via a mixin, but each has a distinct describe() method.

mixin Engine
    var running: bool = false

    def start
        running = true
        print("Engine started")

    def stop
        running = false
        print("Engine stopped")

class Car adds Engine
    var brand: str = ""
    var doors: int = 4
    var running: bool = false       # redeclared from Engine — see the note above

    cue init(b: str)
        brand = b

    def describe(): str
        return "${brand} car with ${doors} doors"

class Motorcycle adds Engine
    var brand: str = ""
    var running: bool = false       # redeclared from Engine

    cue init(b: str)
        brand = b

    def describe(): str
        return "${brand} motorcycle"

class Truck adds Engine
    var brand: str = ""
    var payload_kg: int = 0
    var running: bool = false       # redeclared from Engine

    cue init(b: str, p: int)
        brand = b
        payload_kg = p

    def describe(): str
        return "${brand} truck (${payload_kg}kg payload)"

def main()
    var car = Car("Toyota")
    car.start()
    print(car.describe())
    car.stop()

Exercise 2: Employees and managers — without inheritance

Model Employee, Manager, and Director without any "kind-of" relationship. Use a mixin for shared salary/name behaviour, and composition for the manager's reporting structure.

mixin Compensated
    var name: str = ""
    var salary: float = 0.0

    def info(): str
        return "${name} (${salary})"

class Employee adds Compensated
    var name: str = ""               # redeclared from Compensated
    var salary: float = 0.0          # redeclared from Compensated

    cue init(n: str, s: float)
        name = n
        salary = s

class Manager adds Compensated
    var name: str = ""               # redeclared from Compensated
    var salary: float = 0.0          # redeclared from Compensated
    var team: List(Employee)

    cue init(n: str, s: float)
        name = n
        salary = s
        team = List(Employee)()

    def add_report(e: Employee)
        team.add(e)

    def full_info(): str
        return "${this.info()}, manages ${team.count()}"

class Director adds Compensated
    var name: str = ""               # redeclared from Compensated
    var salary: float = 0.0          # redeclared from Compensated
    var managers: List(Manager)
    var budget: float = 0.0

    cue init(n: str, s: float, b: float)
        name = n
        salary = s
        budget = b
        managers = List(Manager)()

    def full_info(): str
        return "${this.info()}, budget ${budget}"

Exercise 3: Shapes implementing a common interface

Use the Shape interface from Chapter 08 with three independent classes — no shared base, no inheritance.

interface Shape
    def area(): float
    def perimeter(): float

class Circle implements Shape
    var radius: float = 0.0

    cue init(r: float)
        radius = r

    def area(): float
        return 3.14 * radius * radius

    def perimeter(): float
        return 2.0 * 3.14 * radius

class Rectangle implements Shape
    var width: float = 0.0
    var height: float = 0.0

    cue init(w: float, h: float)
        width = w
        height = h

    def area(): float
        return width * height

    def perimeter(): float
        return 2.0 * (width + height)

class Triangle implements Shape
    var base: float = 0.0
    var height: float = 0.0
    var hypotenuse: float = 0.0

    cue init(b: float, h: float, hy: float)
        base = b
        height = h
        hypotenuse = hy

    def area(): float
        return 0.5 * base * height

    def perimeter(): float
        return base + height + hypotenuse

def main()
    var shapes: List(Shape) = List(Shape)()
    shapes.add(Circle(5.0))
    shapes.add(Rectangle(4.0, 6.0))
    shapes.add(Triangle(3.0, 4.0, 5.0))

    for s in shapes
        print("area=${s.area()} perim=${s.perimeter()}")

Next Steps

• → 10-Properties — Field access patterns and getter idioms
• → 14-Contracts — Enforce invariants across composed types
• 🏋 Project-1-CLI-Tool — Use mixins for cross-cutting concerns (logging, configuration)

Key Takeaways

• Zebra has no inheritance. No extends, no super, no parent class. This is by design.
• Three reuse primitives: interfaces (implements — polymorphism), mixins (adds — behaviour reuse), composition (fields — has-a).
• Reach for interfaces first, composition second, mixins last.
• Mixins are flat — their methods become part of the class as if declared directly.
• Conflicting mixin methods are a compile error — no method-resolution magic, no diamond ambiguity.

Next: Head to 10-Properties for getter idioms and computed-value patterns.

10: Properties and Computed Values

Audience: All
Time: 90 minutes
Prerequisites: 07-Classes
You'll learn: Getters, setters, computed properties, lazy initialization, encapsulation

The Big Picture

Properties, in the sense this chapter uses the word, let you control how a value is read or changed instead of letting code touch a field directly. You can:

• Validate on assignment (no negative ages)
• Calculate on access (compute age from birth year)
• Cache computed values
• Log access for debugging

Zebra has no dedicated property syntax. There is no prop, get, or set keyword, and no paren-less "computed field" declaration — a def that looks like a field access (def age: int, no parentheses) is a parse error. Every pattern in this chapter is an ordinary method: declared with () (def age(): int) and called with () (person.age()). "Property" here describes the pattern — a method that behaves like a field from the caller's point of view — not a language feature. A plain var field, by contrast, is read and assigned with no parentheses at all (person.age, person.age = 30) — see the "Read-only and write-only" section below for how that interacts with the method-based patterns here — see "Read-Only Properties" and "Write-Only Properties" under Common Patterns.

Getters

Simple Getter

# file: 10_getter.zbr
# teaches: computed properties
# chapter: 10-Properties-and-Computed-Values

class Person
    var birth_year: int = 2000
    
    def age(): int
        return 2024 - birth_year
    
    def name_length(): int
        var name = "Alice"
        return name.len

def main()
    var person = Person()
    person.birth_year = 1990
    print(person.age())  # 34
    print(person.name_length())  # 5

Derived Properties

# file: 10_derived.zbr
# teaches: deriving values from fields
# chapter: 10-Properties-and-Computed-Values

class Rectangle
    var width: int = 0
    var height: int = 0
    
    def area(): int
        return width * height
    
    def perimeter(): int
        return 2 * (width + height)
    
    def is_square(): bool
        return width == height

def main()
    var rect = Rectangle()
    rect.width = 10
    rect.height = 10

    print("Area: ${rect.area()}")  # 100
    print("Perimeter: ${rect.perimeter()}")  # 40
    print("Square: ${rect.is_square()}")  # true

Setters (Validation)

Controlling Field Assignment

# file: 10_setter_validation.zbr
# teaches: setters with validation
# chapter: 10-Properties-and-Computed-Values

class Account
    var balance: float = 0.0
    
    def deposit(amount: float): bool
        if amount <= 0.0
            return false
        balance = balance + amount
        return true
    
    def withdraw(amount: float): bool
        if amount <= 0.0
            return false
        if amount > balance
            return false
        balance = balance - amount
        return true
    
    def get_balance(): float
        return balance

def main()
    var account = Account()
    account.deposit(100.0)
    print(account.get_balance())  # 100.0

    account.withdraw(25.0)
    print(account.get_balance())  # 75.0

    account.withdraw(100.0)  # Fails (not enough balance)
    print(account.get_balance())  # 75.0 (unchanged)

Setter with Side Effects

# file: 10_setter_effects.zbr
# teaches: setters with side effects
# chapter: 10-Properties-and-Computed-Values

class User
    var username: str = ""
    var email: str = ""
    var last_modified: str = ""
    
    def set_username(new_name: str): bool
        if new_name.len < 3
            return false
        username = new_name
        last_modified = "2024-01-01"  # Update timestamp
        return true
    
    def set_email(new_email: str): bool
        if not new_email.contains("@")
            return false
        email = new_email
        last_modified = "2024-01-01"  # Update timestamp
        return true

def main()
    var user = User()
    if user.set_username("alice")
        print("Username set")

    if user.set_email("alice@example.com")
        print("Email set")
        print("Last modified: ${user.last_modified}")

Computed Properties

# file: 10_computed.zbr
# teaches: expensive computed properties
# chapter: 10-Properties-and-Computed-Values

class DataSet
    var numbers: List(int) = List()
    
    def sum(): int
        var total = 0
        for num in numbers
            total = total + num
        return total
    
    def average(): float
        if numbers.count() == 0
            return 0.0
        return sum() / numbers.count()
    
    def min_value(): int
        var min = numbers.at(0)
        for num in numbers
            if num < min
                min = num
        return min
    
    def max_value(): int
        var max = numbers.at(0)
        for num in numbers
            if num > max
                max = num
        return max

def main()
    var data = DataSet()
    data.numbers.add(10)
    data.numbers.add(20)
    data.numbers.add(30)
    data.numbers.add(40)

    print("Sum: ${data.sum()}")  # 100
    print("Average: ${data.average()}")  # 25
    print("Min: ${data.min_value()}")  # 10
    print("Max: ${data.max_value()}")  # 40

Lazy Initialization

# file: 10_lazy_init.zbr
# teaches: lazy initialization
# chapter: 10-Properties-and-Computed-Values

class Database
    var connection: str?   = nil
    var is_connected: bool = false
    
    def get_connection(): str
        if connection == nil
            # Expensive operation: only when needed
            connection = "Connected to DB"
            is_connected = true
        return connection!  # narrowed to str? above; unwrap for the str return type

def main()
    var db = Database()

    # Connection not created yet
    print("Is connected: ${db.is_connected}")  # false

    # Access connection (now it's created)
    var conn = db.get_connection()
    print(conn)  # Connected to DB

    # Already exists — no second connection attempt
    var conn2 = db.get_connection()
    print(conn2)  # Connected to DB

Real World: Temperature Converter

# file: 10_temperature.zbr
# teaches: properties in realistic scenarios
# chapter: 10-Properties-and-Computed-Values

class Temperature
    var celsius: float = 0.0
    
    def fahrenheit(): float
        return celsius * 9.0 / 5.0 + 32.0
    
    def kelvin(): float
        return celsius + 273.15
    
    def set_from_fahrenheit(f: float)
        celsius = (f - 32.0) * 5.0 / 9.0
    
    def set_from_kelvin(k: float)
        celsius = k - 273.15
    
    def is_freezing(): bool
        return celsius <= 0.0
    
    def is_boiling(): bool
        return celsius >= 100.0

def main()
    var temp = Temperature()
    temp.celsius = 25.0

    print("Celsius: ${temp.celsius}")
    print("Fahrenheit: ${temp.fahrenheit()}")
    print("Kelvin: ${temp.kelvin()}")
    print("Freezing: ${temp.is_freezing()}")
    print("Boiling: ${temp.is_boiling()}")

    temp.set_from_fahrenheit(98.6)
    print("Body temp in Celsius: ${temp.celsius}")

Real World: Configuration

# file: 10_config.zbr
# teaches: configuration management
# chapter: 10-Properties-and-Computed-Values

class Config
    var host: str = "localhost"
    var port: int = 8080
    var debug: bool = false
    
    def set_host(h: str): bool
        if h.len == 0
            return false
        host = h
        return true
    
    def set_port(p: int): bool
        if p < 1 or p > 65535
            return false
        port = p
        return true
    
    def get_url(): str
        return "http://${host}:${port}"
    
    def set_debug(d: bool)
        debug = d

def main()
    var config = Config()
    config.set_host("example.com")
    config.set_port(443)
    config.set_debug(true)

    print(config.get_url())  # http://example.com:443
    print("Debug: ${config.debug}")  # true

Common Patterns

Read-Only Properties

class BankAccount
    var balance: float = 0.0
    
    def get_balance(): float
        return balance  # Can read
    
    def deposit(amount: float)
        balance = balance + amount  # Can modify only via methods
    
    # No setter: direct assignment not allowed

Write-Only Properties

class Password
    var encrypted_password: str = ""
    
    def set_password(plain: str)
        # Encrypt and store
        encrypted_password = "encrypted:" + plain
    
    # No getter: can't read it back

If you're new to programming

A getter is a method that retrieves a value (often computing it on the fly).

A setter is a method that stores a value (often with validation).

Computed properties are values you calculate rather than store. Like age = current_year - birth_year.

Lazy initialization means "don't create something expensive until someone actually asks for it."

Common Mistakes

❌ Mistake: Exposing internal fields directly

class User
    var age: int = 0
var user = User()
user.age = -5  # ❌ No validation!

✅ Better:

class User
    var age: int = 0
    def set_age(new_age: int): bool
        if new_age < 0
            return false
        age = new_age
        return true

❌ Mistake: Computing expensive properties every time

class DataSet
    var numbers: List(int) = List()
    
    def sum(): int  # Recalculates every call
        var total = 0
        for num in numbers
            total = total + num
        return total  # O(n) every time!

✅ Better (if called often):

class DataSet
    var numbers: List(int) = List()
    var cached_sum: int? = nil
    
    def sum(): int
        if cached_sum == nil
            var total = 0
            for num in numbers
                total = total + num
            cached_sum = total
        return cached_sum
    
    def add_number(num: int)
        numbers.add(num)
        cached_sum = nil  # Invalidate cache

❌ Mistake: Side effects in getters

class Logger
    var count: int = 0
    
    def get_count(): int
        count = count + 1  # ❌ Has side effect!
        return count

✅ Better:

class Logger
    var count: int = 0
    
    def get_count(): int
        return count  # ✅ Pure getter, no side effects
    
    def log_access
        count = count + 1  # Explicit method for side effects

Exercises

Exercise 1: Bank Account Properties

Create a bank account with validated setters:

class BankAccount
    var owner: str = ""
    var balance: float = 0.0
    var interest_rate: float = 0.02
    
    def set_owner(name: str): bool
        if name.len < 2
            return false
        owner = name
        return true
    
    def deposit(amount: float): bool
        if amount <= 0.0
            return false
        balance = balance + amount
        return true
    
    def withdraw(amount: float): bool
        if amount > balance
            return false
        balance = balance - amount
        return true
    
    def apply_interest
        var interest = balance * interest_rate
        balance = balance + interest
    
    def get_balance(): float
        return balance

def main()
    var account = BankAccount()
    account.set_owner("Alice")
    account.deposit(1000.0)
    account.apply_interest()
    print("Balance: ${account.get_balance()}")

Exercise 2: Circle Properties

Create a circle class with radius and diameter properties:

class Circle
    var radius: float = 0.0
    
    def set_radius(r: float): bool
        if r <= 0.0
            return false
        radius = r
        return true
    
    def diameter(): float
        return radius * 2.0
    
    def set_diameter(d: float): bool
        if d <= 0.0
            return false
        radius = d / 2.0
        return true
    
    def area(): float
        return 3.14159 * radius * radius
    
    def circumference(): float
        return 2.0 * 3.14159 * radius

def main()
    var circle = Circle()
    circle.set_radius(5.0)

    print("Radius: ${circle.radius}")
    print("Diameter: ${circle.diameter()}")
    print("Area: ${circle.area()}")
    print("Circumference: ${circle.circumference()}")

    circle.set_diameter(20.0)
    print("New radius: ${circle.radius}")

Exercise 3: User Profile with Validation

Create a user profile with validated properties:

class UserProfile
    var username: str = ""
    var email: str = ""
    var age: int = 0
    
    def set_username(name: str): bool
        if name.len < 3 or name.len > 20
            return false
        username = name
        return true
    
    def set_email(addr: str): bool
        if not addr.contains("@") or not addr.contains(".")
            return false
        email = addr
        return true
    
    def set_age(a: int): bool
        if a < 13 or a > 120
            return false
        age = a
        return true
    
    def is_adult(): bool
        return age >= 18
    
    def is_valid(): bool
        return username.len > 0 and email.contains("@") and age > 0

def main()
    var user = UserProfile()
    if user.set_username("alice_wonder")
        print("Username set")
    if user.set_email("alice@example.com")
        print("Email set")
    if user.set_age(25)
        print("Age set")

    print("Is adult: ${user.is_adult()}")
    print("Is valid: ${user.is_valid()}")

Next Steps

• → 11-Nil-Tracking — Advanced safety with properties
• → 14-Contracts — Enforce property invariants
• 🏋 Project-1-CLI-Tool — Use configuration properties

Key Takeaways

• Zebra has no property syntax — every getter and setter in this chapter is an ordinary method, declared and called with ()
• Getters compute values from fields
• Setters validate before storing
• Computed properties derive from other data
• Lazy initialization defers expensive work
• Control access to prevent invalid states
• Encapsulation protects class invariants

Next: Head to Part 3 and 11-Nil-Tracking for Zebra's safety features.

10b: Modules, Namespaces, and Visibility

Audience: All Time: 90 minutes Prerequisites: 04-Functions-and-Scope, 07-Classes-and-Instances You'll learn: Splitting code across files with use, qualified vs. exposed imports, visibility keywords (public/private/internal/protected), namespaces (flat and nested), extend for adding methods to existing types, partial files

The Big Picture

A single .zbr file works for an example or a small tool. Real projects need to split code across many files for the same reasons every other language does:

• Comprehension — a 200-line file is readable; a 20,000-line file is not
• Reuse — the same Vec2 struct shouldn't be re-defined in every script
• Boundaries — a Wallet class should hide its internal balance from the rest of the program
• Naming — parse could mean three different things in three different domains; the module name disambiguates

Zebra gives you four tools for this:

This chapter walks each in turn.

Files as Modules

Every .zbr file is automatically a module. The module name is the filename without the extension.

# file: math_utils.zbr
def square(x: int): int
    return x * x

struct Vec2
    var x: float
    var y: float

    def length(): float
        return Math.sqrt(x*x + y*y)

To use this from another file, write use math_utils and then reference the names with a math_utils. prefix:

# file: main.zbr
use math_utils

def main()
    var n = math_utils.square(5)
    var v = math_utils.Vec2(3.0, 4.0)
    print(v.length())

The compiler resolves use math_utils by looking for math_utils.zbr:

1. In the same directory as the importing file
2. In selfhost/, test/, and the stdlib path

That's the whole module model — one file, one module, lookup by name.

exposing — Importing Specific Names

The qualified math_utils.square(...) form gets verbose if you call into the module often. exposing lets you bind specific names directly into your scope:

# file: main.zbr
use math_utils exposing square, Vec2

def main()
    var n = square(5)            # no math_utils. prefix
    var v = Vec2(3.0, 4.0)
    print(v.length())

Combine forms freely:

use math_utils exposing square, Vec2  # also have math_utils.* available

After this line, square and Vec2 are in scope unqualified; everything else in math_utils is still reachable as math_utils.something().

Qualified vs. exposed — which to use

• Exposed — when the names are domain-specific and unambiguous in context (square, Vec2, parseJson).
• Qualified — when the unqualified name would collide with another module's name, or when the qualification adds useful context for the reader (db.query(...) is clearer than query(...)).

A common pattern: expose the types and qualify the operations.

use http exposing Request, Response

def handle(req: Request): Response
    return http.json_response(req.body)

Request and Response are types you'll mention often; json_response is an action where the http. prefix reads naturally.

Cross-Module Type Annotations

Either form works in a type annotation:

# Qualified:
var v: math_utils.Vec2 = math_utils.Vec2(1.0, 2.0)

# Exposed:
use math_utils exposing Vec2
var v: Vec2 = Vec2(1.0, 2.0)

Pick the one that matches the rest of your imports — consistency reads better than micro-optimisation.

Visibility Keywords

By default every top-level declaration in a module is public — reachable from any file that imports the module. Use a visibility keyword to narrow that:

Visibility applies to fields and methods inside a class, and to top-level functions/types in a module:

# file: wallet.zbr
class Wallet
    private var balance: float     # only Wallet's own methods can read/write

    public def deposit(amount: float)
        .balance = .balance + amount

    public def get_balance(): float
        return .balance

    private def log_event(msg: str)
        # internal bookkeeping — callers can't reach this
        print("[wallet] ${msg}")

# file: main.zbr
use wallet exposing Wallet

def main()
    var w = Wallet()
    w.deposit(100.0)            # ok — deposit is public
    print(w.get_balance())  # ok
    # w.balance                  # ERROR — balance is private
    # w.log_event("oops")        # ERROR — log_event is private

The compiler enforces visibility at use sites. The error message tells you which keyword would unlock access.

When to use each

• private — the default for state and helpers. Start private; promote to public only when an external caller actually needs the access.
• protected — used when subclasses need access but the public API doesn't. Rare in Zebra (composition is preferred over inheritance, see Ch09).
• internal — module-private. Useful when a top-level helper is shared among several classes in the same file but not part of the public API.
• public — the rest.

Note on _underscore prefix. Earlier Zebra code used a leading _ on identifiers to signal "compiler-internal." The visibility keywords superseded that convention for user code. The _ prefix is now reserved for compiler-emitted symbols (_io, _allocator, etc.) — don't use it in your own code.

Namespaces — Grouping Inside a File

A namespace block wraps top-level declarations under a named scope:

# file: colors.zbr
namespace Colors
    struct Rgb
        var r: int
        var g: int
        var b: int

    def from_hex(hex: int): Rgb
        return Rgb(r: (hex >> 16) & 0xFF,
                   g: (hex >> 8)  & 0xFF,
                   b: hex & 0xFF)

Usage:

use colors

def main()
    var red  = Colors.Rgb(r: 255, g: 0, b: 0)
    var blue = Colors.from_hex(0x0000FF)

All names declared inside namespace Colors are accessed as Colors.X.

Inside the namespace, methods can call each other without the prefix — from_hex could call another helper inside Colors directly.

When to use a namespace

• Group related helpers that don't share state. A class is overkill for utility functions; a namespace gives them a name without instantiation.
• Cluster a small type with its operations. Colors.Rgb and Colors.from_hex belong together; a namespace keeps them paired.
• Avoid top-level pollution. Without a namespace, every helper in every file lives in the module's top scope. Namespaces structure that.

Nested namespaces

Two syntaxes — pick whichever reads better for your case.

Dotted path — concise for a single leaf:

namespace Sql.Sqlite
    static def open(path: str): int
        # ...

def main()
    var db = Sql.Sqlite.open("mydb.db")

Nested body — natural when the outer namespace also has direct members:

namespace Sql
    static def version(): str
        return "1.0"

    namespace Sqlite
        static def open(path: str): int
            # ...

    namespace Postgres
        static def connect(url: str): int
            # ...

def main()
    print(Sql.version())
    var db = Sql.Sqlite.open("mydb.db")
    var pg = Sql.Postgres.connect("postgresql://localhost/mydb")

Both compile to the same nested struct in the generated Zig.

extend — Adding Methods to Existing Types

extend adds methods to a type that's already defined — including built-in types like str and int:

extend str
    def shout(): str
        return this.upper() + "!"

    def word_count(): int
        return this.split(" ").len

# Anywhere in the same file:
var s = "hello world"
print(s.shout())  # HELLO WORLD!
print(s.word_count())  # 2

this inside an extend body is the receiver value. The extended type can be any built-in (str, int, float, bool, char) or any user class/struct.

Common patterns

extend int
    def is_even(): bool
        return this % 2 == 0

    def abs(): int
        if this < 0: return -this
        return this

extend List(str)
    def join_with(sep: str): str
        return this.join(sep)

extend can also conform an existing type to an interface or include a mixin:

extend str is Printable
    def show(): str
        return this

Important: extensions are file-scoped

Methods added via extend are visible only in the file where the extend block appears. They are not exported across module boundaries.

# file: helpers.zbr
extend int
    def double(): int
        return this * 2

# file: main.zbr
use helpers
def main()
    # var n = 5.double()    # ERROR — double() not visible here
    pass

If you need a cross-module extension, either:

• Repeat the extend block in each importing file (intentional, explicit), or
• Wrap the extension in a regular function: def double(n: int): int { return n * 2 }

This is a deliberate design — extensions are powerful but ambient. Forcing them to be file-local keeps surprises out of large codebases.

Partial Files

A class can be split across multiple files by naming convention. Given a primary file Foo.zbr declaring class Foo, any file named Foo.X.zbr (where X is any segment) is treated as a partial. Its class Foo members are merged into the primary class at compile time.

# file: Wallet.zbr  (primary)
class Wallet
    private var balance: float

    public def get_balance(): float
        return .balance

# file: Wallet.transactions.zbr  (partial — merges into Wallet)
class Wallet
    public def deposit(amount: float)
        .balance = .balance + amount

    public def withdraw(amount: float) throws
        if amount > .balance
            raise "insufficient funds"
        .balance = .balance - amount

After compilation, Wallet has balance, get_balance, deposit, and withdraw — as though they had all been declared in one file.

When to use partials: large classes whose methods cluster by concern (persistence, JSON serialisation, UI binding). The compiler emits identical code either way; partials are a source-organisation tool, not a runtime concept.

Real World: Multi-Module CLI Project

Here's a project layout that uses every primitive in this chapter:

my-tool/
├── build.zbr
└── src/
    ├── main.zbr               # entry point
    ├── cli.zbr                # argument parsing (public API)
    ├── cli.internal.zbr       # cli internals (partial of cli)
    └── work.zbr               # core logic

src/main.zbr

use cli exposing Options
use work

def main()
    var opts = cli.parse_args(sys.args())
    work.run(opts)

src/cli.zbr

class Options
    public var verbose: bool = false
    public var input_path: str = ""

namespace Cli
    static def usage(): str
        return "my-tool [--verbose] FILE"

def parse_args(args: List(str)): Options
    var opts = Options()
    for arg in args
        if arg == "--verbose"
            opts.verbose = true
        else
            opts.input_path = arg
    return opts

src/cli.internal.zbr (partial — merges with Cli namespace)

namespace Cli
    # internal helper — not exposed in cli.zbr's public surface
    static def normalize_path(p: str): str
        if p.starts_with("./")
            return p.slice(2, p.len)
        return p

src/work.zbr

use cli exposing Options

extend Options
    def describe(): str
        return "verbose=${.verbose}, input=${.input_path}"

def run(opts: Options)
    if opts.verbose
        print("Processing: ${opts.describe()}")
    # ... core logic ...

Two things worth noticing:

1. work.zbr extends Options (defined in cli.zbr) with a describe() method. The extension is local to work.zbr — other files see Options without describe.
2. cli.internal.zbr is a partial of the Cli namespace from cli.zbr. The compiler merges the two before resolving names. From main.zbr's perspective, Cli.normalize_path and Cli.usage are in the same namespace.

Common Mistakes

❌ Mistake: Forgetting to import a module

def main()
    var v = math_utils.square(5)   # ERROR: math_utils not in scope

✅ Better:

use math_utils

def main()
    var v = math_utils.square(5)

❌ Mistake: Trying to use an extend method across files

# helpers.zbr
extend int
    def is_prime(): bool
        # ...

# main.zbr
use helpers
def main()
    print(7.is_prime())         # ERROR: extension not visible here

✅ Better: wrap the logic in a regular function instead:

# helpers.zbr
def is_prime(n: int): bool
    # ...

# main.zbr
use helpers exposing is_prime
def main()
    print(is_prime(7))

❌ Mistake: Making everything public by default

class Wallet
    var balance: float           # default = public — leaks internal state

✅ Better: start private, promote when needed:

class Wallet
    private var balance: float
    public def get_balance(): float
        return .balance

❌ Mistake: Confusing a namespace with a class

namespace Colors
    struct Rgb
        var r: int

# Wrong — can't instantiate a namespace:
# var c = Colors(...)

✅ Better: instantiate the type inside the namespace:

var c = Colors.Rgb(r: 255, g: 0, b: 0)

Exercises

Exercise 1: Split and Import

Split this single-file program into a geometry.zbr module and a main.zbr that imports it. Expose the Circle class and the area function.

# Single file (start)
struct Circle
    var radius: float

    def area(): float
        return 3.14159 * radius * radius

def total_area(circles: List(Circle)): float
    var sum = 0.0
    for c in circles
        sum = sum + c.area()
    return sum

def main()
    var cs = [Circle(1.0), Circle(2.0), Circle(3.0)]
    print(total_area(cs))

struct Circle
    var radius: float

    def area(): float
        return 3.14159 * radius * radius

def total_area(circles: List(Circle)): float
    var sum = 0.0
    for c in circles
        sum = sum + c.area()
    return sum

use geometry exposing Circle, total_area

def main()
    var cs = [Circle(1.0), Circle(2.0), Circle(3.0)]
    print(total_area(cs))

Exercise 2: Namespace Refactor

Convert this loose-functions module into a namespace-based one:

def hex_to_rgb(hex: int): (int, int, int)
    return ((hex >> 16) & 0xFF, (hex >> 8) & 0xFF, hex & 0xFF)

def darken(rgb: (int, int, int), pct: int): (int, int, int)
    var (r, g, b) = rgb
    return (r * (100 - pct) / 100,
            g * (100 - pct) / 100,
            b * (100 - pct) / 100)

namespace Colors
    def hex_to_rgb(hex: int): (int, int, int)
        return ((hex >> 16) & 0xFF, (hex >> 8) & 0xFF, hex & 0xFF)

    def darken(rgb: (int, int, int), pct: int): (int, int, int)
        var (r, g, b) = rgb
        return (r * (100 - pct) / 100,
                g * (100 - pct) / 100,
                b * (100 - pct) / 100)

Exercise 3: Visibility Audit

Take a class you've written and audit its visibility. Which fields are truly private? Which methods are only called from inside the class? Tighten the visibility, then make sure the rest of your program still compiles.

This exercise has no programmatic solution — it's the workflow that matters. Done well, visibility tightening usually finds at least one field or method that shouldn't have been exposed.

Next Steps

• → 22b-Build-System-and-Tooling — multi-module project builds
• → 22c-Testing-and-Validation — test each module independently
• → 08-Interfaces-and-Protocols — pair modules with interface conformance

Key Takeaways

• One file = one module — use module_name imports it; resolution is filename-based
• use M exposing X, Y binds names directly into scope; bare use M requires M.X qualification
• public / private / internal / protected control access; private is the right default for state, promote as needed
• namespace groups declarations inside a file; nested form (namespace Outer.Inner or namespace Outer { namespace Inner { ... } }) builds hierarchies
• extend adds methods to existing types, including built-ins — but the extension is file-scoped, not exported across modules
• Partial files (Foo.X.zbr merging into Foo.zbr) split a large class across files at compile time

Next: Chapter 14b shifts focus to runtime — memory lifetimes, the allocate block, the <- copy-out operator, and the heap-indirection ^T syntax that ties them together.

11: Nil Tracking and Safety

Audience: All
Time: 120 minutes
Prerequisites: 02-Values, 05-Control-Flow, 07-Classes
You'll learn: Nullable types, nil checking, type narrowing, the ! force-unwrap operator, optionals

The Big Picture

Nil (null/nothing) is one of the most common sources of bugs. Zebra's nil tracking forces you to handle it:

"A billion-dollar mistake." — Tony Hoare, on inventing the null reference

Zebra says: Explicit nil is safe. Implicit nil is forbidden.

Nullable Types

Marking Optionality

# file: 11_nullable.zbr
# teaches: nullable types
# chapter: 11-Nil-Tracking-and-Safety

class User
    var name: str      # Can't be nil
    var nickname: str? # Can be nil
    var bio: str?      # Can be nil

def main()
    var user = User()
    user.name = "Alice"    # ✅ Fine
    user.nickname = nil    # ✅ Allowed (it's str?)
    user.bio = "Developer" # ✅ Can assign string to str?
    
    # This won't compile:
    # var empty: str = nil  # ❌ str can't be nil

Key point: The ? mark means "this can be nil or the type."

Nil Checking

Safe Access Pattern

# file: 11_nil_check.zbr
# teaches: nil checking
# chapter: 11-Nil-Tracking-and-Safety

def main()
    var nickname: str? = "Bobby"
    var empty: str? = nil
    
    # Check before using
    if nickname != nil
        print(nickname)  # Safe: known to not be nil
    
    if empty == nil
        print("No nickname set")
    else
        print(empty)
    
    # Two ways to check:
    if nickname != nil
        print("Has nickname")
    
    if nickname == nil
        print("No nickname")
    else
        print("Has: ${nickname}")

Type Narrowing

After checking, the type is narrowed:

# file: 11_narrowing.zbr
# teaches: type narrowing
# chapter: 11-Nil-Tracking-and-Safety

def process_name(input: str?)
    if input != nil
        # Inside the block, input is narrowed to str
        print(input.len)  # ✅ Safe: know it's str
        print(input.upper())  # ✅ Safe

Narrowing follows the if x != nil block, not an early return. The early-return shape — if input == nil: return and then using input below — does not narrow (the else-branch of == nil is on the not-yet list), so write it as the block above, or bind with if input as name (next section), or unwrap explicitly with input!.

# an early return still works, with an explicit unwrap after it
def shout(input: str?): str
    if input == nil
        return ""
    return input!.upper()

if x as n — Unwrap-and-Bind

The most idiomatic way to unwrap an optional and use the inner value is the if x as n binding form. When x: T?, it binds a non-optional n: T in the then-branch — no separate unwrap required:

# file: 11_if_as.zbr
# teaches: optional unwrap binding form
# chapter: 11-Nil-Tracking-and-Safety

def main()
    var maybe_name: str? = "Alice"

    if maybe_name as name
        # `name` is `str` here — non-optional
        print("Hello, ${name}!")
    else
        print("No name")

This form combines the nil-check, the unwrap, and the binding into a single statement, and it works both for plain optionals (T?) and for optional class/union check + unwrap together:

# Combined type check + unwrap:
var maybe_user: User? = lookup()
if maybe_user is User as u
    print(u.name)  # u is `User` (non-optional)

if x as n is preferred over ! whenever the wrapped value is going to be used right away — it's safer (no panic possibility) and reads more naturally.

The ! Operator (Force-Unwrap)

Warning: Only use when you're absolutely certain the value isn't nil.

# file: 11_unwrap.zbr
# teaches: force-unwrap operator
# chapter: 11-Nil-Tracking-and-Safety

def main()
    var name: str? = "Alice"
    
    # Unwrap: assert it's not nil
    var safe_name = name!
    print(safe_name)  # Now just str
    
    # If it WAS nil, this would crash
    var empty: str? = nil
    # var crash = empty!  # ❌ Would panic at runtime

Unwrap with Fallback

# file: 11_unwrap_or.zbr
# teaches: safe unwrapping
# chapter: 11-Nil-Tracking-and-Safety

def get_user_name(user_id: int): str?
    if user_id == 1
        return "Alice"
    return nil

def main()
    var maybe_name = get_user_name(1)

    # Option 1: Check and use default
    if maybe_name as name
        print(name)
    else
        print("Unknown user")

    # Option 2: `orelse` supplies a fallback when the value is nil
    var safe_name = get_user_name(2) orelse "Guest"
    print(safe_name)  # Guest

Real World: Database Queries

# file: 11_database.zbr
# teaches: nil in realistic scenarios
# chapter: 11-Nil-Tracking-and-Safety

class User
    var id: int
    var name: str
    var email: str?

class UserDatabase
    static
        def find_user(user_id: int): User?
            if user_id == 1
                var user = User()
                user.id = 1
                user.name = "Alice"
                user.email = "alice@example.com"
                return user
            return nil
        
        def find_user_email(user_id: int): str?
            var user = find_user(user_id)
            if user == nil
                return nil
            return user.email

def main()
    var user = UserDatabase.find_user(1)
    if user != nil
        print(user.name)
        if user.email != nil
            print(user.email)
        else
            print("No email on file")
    else
        print("User not found")
    
    # Chaining nil checks
    var email = UserDatabase.find_user_email(999)
    if email != nil
        print("Email: ${email}")
    else
        print("User not found")

Common Patterns

Optional Chaining

def get_user_city(user_id: int): str?
    var user = find_user(user_id)
    if user == nil
        return nil
    var address = get_address(user.id)
    if address == nil
        return nil
    return address.city

Guard Clauses

def process(data: str?)
    if data == nil
        return
    if data.len == 0
        return
    # Now process safely
    do_work(data)

If you're new to programming

Nil means "nothing" or "no value." Different languages call it null, None, undefined.

Zebra makes you declare which variables can be nil with ?. This prevents accidental crashes.

Type narrowing means the compiler recognizes that after you check if x != nil, you can safely use x.

Common Mistakes

❌ Mistake: Forgetting to check for nil

var email: str? = get_email()
print(email.len)  # ❌ Crash if email is nil!

✅ Better:

var email: str? = get_email()
if email != nil
    print(email.len)  # ✅ Safe

❌ Mistake: Using ! without certainty

var value: str? = get_value()
print(value!)  # ❌ Crashes if value is nil

✅ Better:

var value: str? = get_value()
if value != nil
    print(value)  # ✅ Safe — or use a fallback: print(value orelse "none")

❌ Mistake: Assigning nil to non-nullable

var name: str = nil  # ❌ str can't be nil

✅ Better:

var name: str? = nil  # ✅ Declares it can be nil

Exercises

Exercise 1: Find User Email

Write a function that safely retrieves a user's email:

class User
    var id: int
    var name: str
    var email: str?

class UserDB
    static
        def find_user(id: int): User?
            if id == 1
                var user = User()
                user.id = 1
                user.name = "Alice"
                user.email = "alice@example.com"
                return user
            return nil
        
        def get_email(user_id: int): str?
            var user = find_user(user_id)
            if user == nil
                return nil
            return user.email

def main()
    var email = UserDB.get_email(1)
    if email != nil
        print("Email: ${email}")
    else
        print("User not found or no email")

Exercise 2: Safe Division

Write a division function that returns nil on error:

class Calculator
    static
        def safe_divide(a: float, b: float): float?
            if b == 0.0
                return nil
            return a / b

def main()
    var result = Calculator.safe_divide(10.0, 2.0)
    if result != nil
        print("Result: ${result}")
    
    var bad = Calculator.safe_divide(10.0, 0.0)
    if bad != nil
        print(bad)
    else
        print("Cannot divide by zero")

Exercise 3: Nullable Chain

Write a function that navigates nullable fields:

class Profile
    var name: str
    var bio: str?

class User
    var id: int
    var profile: Profile?

class UserService
    static
        def get_user_bio(user_id: int): str?
            var user = find_user(user_id)
            if user == nil
                return nil
            var profile = user.profile
            if profile == nil
                return nil
            return profile.bio
        
        def find_user(id: int): User?
            if id == 1
                var user = User()
                user.id = 1
                var profile = Profile()
                profile.name = "Alice"
                profile.bio = "Developer"
                user.profile = profile
                return user
            return nil

def main()
    var bio = UserService.get_user_bio(1)
    if bio != nil
        print("Bio: ${bio}")
    else
        print("No bio found")

Next Steps

• → 12-Error-Handling — throws, raise, and catch for error cases
• → 14-Contracts — Enforce non-nil invariants
• 🏋 Project-2-HTTP-Server — Handle nil API responses

Key Takeaways

• ? marks nullable types — str? can be string or nil
• Check before using — if value != nil { ... }
• Type narrowing — Compiler recognizes after checks
• ! unwraps — Only when certain it's not nil
• Guard clauses — Exit early if nil
• Nil safety prevents crashes — It's a feature, not a limitation

Next: Head to 12-Error-Handling for exceptions (throws/raise/catch) and error propagation.

12: Error Handling

Audience: All
Time: 120 minutes
Prerequisites: 02-Values, 04-Functions, 07-Classes, 11-Nil-Tracking
You'll learn: throws annotation, raise statement, method-level catch clauses, error propagation, inline catch expressions

The Big Picture

Zebra's error model is exceptions — throws/raise/try/catch. The shape is inspired by Zig's error-set system (each throws function returns anyerror!T in the generated Zig), but enriched: raise "msg" carries a string message, and raise "msg", obj attaches a structured details object via a thread-local _error_ctx — strictly more than Zig's payload-less error enums.

Error paths are explicit in the type system: throws on a signature is the only way a function can fail, so you can see at a glance which functions may fail and which cannot.

Note: Earlier versions of Zebra exposed a Result(T) type as an error-as-value alternative. That type and its .isOk()/.okValue() methods were removed. Use throws for all error handling.

Functions That Can Fail: throws

Mark a function with throws to indicate it may produce an error:

# file: 12_throws_basic.zbr
# teaches: throws annotation
# chapter: 12-Error-Handling

class Validator
    static
        def parse_int(text: str): int throws
            if text.len == 0
                raise "Empty string"
            # Parse and return
            return 42

def main()
    var result = Validator.parse_int("123") catch 0
    print(result)

Breakdown:

• : int throws — This function returns int but may fail
• raise "Empty string" — Signal an error with a message
• catch 0 — If the call fails, use 0 as the fallback value

raise — Signaling Errors

Use raise to signal that something went wrong:

# file: 12_raise.zbr
# teaches: raise statement
# chapter: 12-Error-Handling

class FileLoader
    static
        def load(path: str): str throws
            if path.len == 0
                raise "Path cannot be empty"
            if not path.endsWith(".txt")
                raise "Only .txt files supported"
            return "file contents here"

raise immediately exits the function and propagates the error to the caller.

Method-Level catch — Handling Errors

Block Form

For structured error handling, attach a catch clause to a method (or def) at the same indent level as the def keyword. The clause runs when any throws call inside the method body raises:

# file: 12_method_catch.zbr
# teaches: method-level catch clause
# chapter: 12-Error-Handling

def attempt()
    var value = Validator.parse_int("")
    print("Got: ${value}")
catch
    print("Failed to parse")

def main()
    attempt()

Catch with Binding

Bind the error value to inspect it. The binding gives you an error object with a .message field (a plain string binding, |err|, prints the whole error via interpolation; .message is how you pull just the text out):

# file: 12_catch_binding.zbr
# teaches: catch with error binding
# chapter: 12-Error-Handling

def attempt()
    var value = Validator.parse_int("")
    print("Got: ${value}")
catch |err|
    print("Error: ${err.message}")

def main()
    attempt()

Note: Earlier Zebra versions allowed a try ... catch ... block at any point inside a method body, and a typed error binding written |err as str|. Both forms were removed; today every catch clause attaches to either a def (method-level) or a single expression (inline postfix expr catch fallback), and the binding is untyped — use |err| and read .message.

catch Expression — Inline Fallbacks

For simple cases, use catch as an expression to provide a default:

# file: 12_catch_expr.zbr
# teaches: catch expression for defaults
# chapter: 12-Error-Handling

def main()
    # Provide a default value if the call fails
    var value = Validator.parse_int("abc") catch 0
    print(value)  # 0

    var count = Validator.parse_int("") catch 0
    print(count)  # 0

This is the most common pattern for simple error recovery. An inline catch can also bind the error (expr catch |e| fallback), but e there is a bare anyerror with no .message field — for a fallback that depends on what went wrong, use a method-level catch |e| (above), where e.message is available.

Error Propagation

Functions annotated with throws can propagate errors from callees, but propagation isn't automatic — mark the call with ?. If a throws function calls another throws function without catching, the ? sends the error straight to the caller:

# file: 12_propagation.zbr
# teaches: error propagation
# chapter: 12-Error-Handling

class Parser
    static
        def parse_config(text: str): str throws
            if text.len == 0
                raise "Empty config"
            return "parsed"

class System
    static
        def load_system(config_text: str): str throws
            # The `?` sends a raise from parse_config straight to our caller
            var parsed = Parser.parse_config(config_text)?
            return "System loaded with: ${parsed}"

def main()
    var result = System.load_system("data") catch "load failed"
    print(result)

Real World: API Client

# file: 12_api_client.zbr
# teaches: realistic error handling
# chapter: 12-Error-Handling

class APIClient
    static
        def fetch_user(user_id: int): str throws
            if user_id <= 0
                raise "Invalid user ID"
            if user_id == 1
                return "Alice"
            raise "User not found"

        def fetch_and_greet(user_id: int): str throws
            var user = fetch_user(user_id)?
            return "Hello, ${user}!"

def attempt_greet(user_id: int)
    var g = APIClient.fetch_and_greet(user_id)
    print(g)
catch |err|
    print("Error: ${err.message}")

def main()
    # Using inline catch expression
    var greeting = APIClient.fetch_and_greet(1) catch "Could not greet"
    print(greeting)  # Hello, Alice!

    # Using method-level catch (wraps a multi-line block)
    attempt_greet(999)          # prints "Error: User not found"

Exercises

Exercise 1: Safe Division

Write a function safe_divide(a: int, b: int): int throws that raises on division by zero.

class MathUtils
    static
        def safe_divide(a: int, b: int): int throws
            if b == 0
                raise "Division by zero"
            return a / b

def main()
    var r1 = MathUtils.safe_divide(10, 2) catch 0
    var r2 = MathUtils.safe_divide(10, 0) catch 0
    print(r1)  # 5
    print(r2)  # 0

Exercise 2: Chained Error Handling

Write two functions that chain: parse_age(text: str): int throws and validate_age(text: str): str throws (returns "valid" if age is 0-150).

class AgeValidator
    static
        def parse_age(text: str): int throws
            if text.len == 0
                raise "Empty input"
            var age = text.tryInt()          # int? -- nil when the text is not a number
            if age == nil
                raise "Not a number"
            return age!

        def validate_age(text: str): str throws
            var age = parse_age(text)?
            if age < 0
                raise "Age cannot be negative"
            if age > 150
                raise "Age too large"
            return "valid"

def attempt_validate(text: str)
    var result = AgeValidator.validate_age(text)
    print(result)  # "valid"
catch |err|
    print("Error: ${err.message}")

def main()
    attempt_validate("25")        # prints "valid"
    var r2 = AgeValidator.validate_age("200") catch "invalid"
    print(r2)  # invalid

Next Steps

• → 13-Generics — Type-safe containers
• → 15-Pipelines — Chain operations gracefully

Key Takeaways

• throws — Annotates functions that may fail
• raise — Signals an error, exits the function immediately
• Method-level catch — Attach a catch clause to a def at the same indent level; it runs when any throws call in the body raises
• catch expression — Inline fallback: expr catch default
• Errors propagate with ? — Mark every call to a throws function with ? to send its error to the caller; propagation is not automatic
• Errors are explicit — You always know which functions can fail

Next: Head to 13-Generics for type-safe abstractions.

13: Generics and Type Constraints

Audience: Experienced programmers
Time: 120 minutes
Prerequisites: 02-Values-and-Types, 07-Classes-and-Instances, 08-Interfaces-and-Protocols
You'll learn: Generic types, type parameters, constraints, practical uses, common pitfalls

The Big Picture

So far, you've written code that works with specific types: a List(int), a HashMap(str, int). But what if you want a function that works with any type? That's where generics come in.

Generics let you write code that's type-safe but reusable across different types:

class Container(T)
    var item: T
    
    def get(): T
        return item

Container(int) holds integers. Container(str) holds strings. Same code, different types. This is safer than using object or any, because the type checker still verifies you don't mix types.

Generic Classes

The simplest generic is a container that holds a single value:

# file: 13_generic_container.zbr
# teaches: generic class definition
# chapter: 13-Generics-and-Type-Constraints

class Container(T)
    var item: T
    
    def store(value: T)
        item = value
    
    def retrieve(): T
        return item

def main()
    var int_box = Container(int)()
    int_box.store(42)
    print(int_box.retrieve())  # Output: 42
    
    var str_box = Container(str)()
    str_box.store("hello")
    print(str_box.retrieve())  # Output: hello

Notice the syntax:

• Container(T) — T is a type parameter
• Container(int)() — substitute int for T, then create an instance
• Inside the class, T can be used like any other type

You can have multiple type parameters:

# file: 13_generic_pair.zbr
# teaches: multiple type parameters
# chapter: 13-Generics-and-Type-Constraints

class Pair(K, V)
    var key: K
    var value: V
    
    def set_key(k: K)
        key = k
    
    def set_value(v: V)
        value = v
    
    def get_key(): K
        return key
    
    def get_value(): V
        return value

def main()
    var p = Pair(str, int)()
    p.set_key("count")
    p.set_value(42)
    print("Key: ${p.get_key()}, Value: ${p.get_value()}")

Generic Methods

You can also write generic methods within regular classes:

# file: 13_generic_methods.zbr
# teaches: generic methods
# chapter: 13-Generics-and-Type-Constraints

class Utils
    static
        def identity(T)(value: T): T
            return value

        def first_of_three(T)(a: T, b: T, c: T): T
            return a

def main()
    var x = Utils.identity(int)(42)
    print(x)  # Output: 42

    var y = Utils.identity(str)("hello")
    print(y)  # Output: hello

    var z = Utils.first_of_three(int)(1, 2, 3)
    print(z)  # Output: 1

A generic method declares its type parameters in their own parentheses before the value parameters -- def identity(T)(value: T): T -- and the caller passes the type first: Utils.identity(int)(42). Zebra does not infer the type argument from the values; Utils.identity(42) is refused with a message showing the explicit form. Instance methods work the same way (box.wrap(int)(7)).

Generic Functions

Top-level functions can be generic too. The type parameters come in their own parens before the value parens — def fname(T)(value: T): T:

# file: 13_generic_function.zbr
# teaches: top-level generic function declaration
# chapter: 13-Generics-and-Type-Constraints

def identity(T)(value: T): T
    return value

def first(T)(items: List(T)): T?
    if items.count() == 0
        return nil
    return items.at(0)

def main()
    var n: int = identity(int)(42)
    var s: str = identity(str)("hello")
    var first_num: int? = first(int)([1, 2, 3])
    if first_num as v
        print(v)  # 1
    print(s)      # hello

Rules:

• The type parameter list (T) (or (T, U) etc.) comes immediately after the function name.
• Inside the body, T is a regular type — usable in annotations, casts, and return types.
• At the call site the type argument is required: identity(int)(42). A bare identity(42) is refused -- the type is not inferred from the arguments.
• A type name that is declared nowhere (for example writing def total(items: List(T)) without the (T)) is refused as unknown type 'T', with the generic spelling as the hint.
• Under the hood the compiler emits a comptime T: type parameter to Zig.

When to use:

• Generic function — utility code that works for any type (identity, first, swap).
• Generic method — operation that belongs to a generic class (covered above).
• Generic class — container or wrapper around values of any type (Stack(T), Cache(K, V)).

The three forms cover almost every generic pattern you'll need.

Generic Collections

You already use generics implicitly with List and HashMap:

# file: 13_generic_collections.zbr
# teaches: using generic stdlib types
# chapter: 13-Generics-and-Type-Constraints

def main()
    var numbers: List(int) = List()
    numbers.add(1)
    numbers.add(2)
    numbers.add(3)
    
    for n in numbers
        print(n)
    
    var ages: HashMap(str, int) = HashMap()
    ages.put("Alice", 30)
    ages.put("Bob", 25)
    
    for name, age in ages
        print("${name}: ${age}")

These are all generic types. The standard library provides them pre-built.

Type Constraints

Sometimes you want a generic that works with any type that implements an interface:

# file: 13_type_constraints.zbr
# teaches: interface constraints
# chapter: 13-Generics-and-Type-Constraints

interface Printable
    def display(): str

class Dog implements Printable
    def display(): str
        return "Woof!"

class Cat implements Printable
    def display(): str
        return "Meow!"

class Printer
    static
        def print_item(item: Printable)
            print(item.display())

def main()
    var dog = Dog()
    var cat = Cat()
    
    Printer.print_item(dog)  # Output: Woof!
    Printer.print_item(cat)  # Output: Meow!

Here, Printer.print_item accepts any type that implements Printable. This is a constraint: "T must implement interface Printable".

More advanced: a constraint on a generic class's type parameter. The interface itself takes a type parameter — Comparable(T) — which is how a class names itself in the signature (Score implements Comparable(Score)), and where T implements Comparable(T) is checked when the class is instantiated: ComparableList(int)() is refused, because a primitive cannot implement an interface.

# file: 13_generic_constraints_advanced.zbr
# teaches: constraints in generic methods
# chapter: 13-Generics-and-Type-Constraints

interface Comparable(T)
    def compareTo(other: T): int

class Score implements Comparable(Score)
    var value: int
    cue init(v: int)
        value = v
    def compareTo(other: Score): int
        return value - other.value

class ComparableList(T where T implements Comparable(T))
    var items: List(T) = List(T)()

    def add(item: T)
        items.add(item)

    def find_max(): T?
        if items.count() == 0
            return nil
        var max = items.at(0)
        var i = 1
        while i < items.count()
            var item = items.at(i)
            # T implements Comparable(T), so compareTo is available
            if item.compareTo(max) > 0
                max = item
            i = i + 1
        return max

def main()
    var list = ComparableList(Score)()
    list.add(Score(10))
    list.add(Score(5))
    list.add(Score(20))
    if list.find_max() as max
        print("Max: ${max.value}")  # Max: 20

Comparable(T) is not cue compare. The interface above is a constraint you declare and you call (item.compareTo(max)). The language's own ordering protocol is the compare cue (Chapter 07, "Cues"): <, <=, >, >= and list.sort() call cue compare, and they do not look at compareTo. Score(1) < Score(2) does not build with only the interface. If you want both, give the class both; the cue's body can simply return .compareTo(other). Like every cue compare, it needs a cue equals on the same class.

Type Aliases and Refinement Types

A different flavour of "generic" — instead of parameterising over types, you can parameterise over values that constrain a base type at runtime.

Plain type aliases

A type declaration creates a named alias for an existing type, optionally with a where constraint:

# file: 13_type_aliases.zbr
# teaches: type aliases with constraints
# chapter: 13-Generics-and-Type-Constraints

type PositiveInt = int where value > 0
type NonEmptyStr = str where value.len > 0
type Ratio       = float where value >= 0.0 and value <= 1.0
type UncheckedInt = int                       # no constraint — plain alias

def main()
    var count: PositiveInt = 42               # OK — 42 > 0
    var doubled: int = count * 2              # transparent — works as int
    print(doubled)  # 84

    # var bad: PositiveInt = -1               # runtime panic: "type constraint 'PositiveInt' failed"

Key properties:

• Transparent. PositiveInt is just int in the generated Zig — no wrapper struct, no runtime overhead beyond the constraint check.
• value is the implicit binding in the where clause — refers to the variable being declared.
• Check at initialization. The compiler emits a runtime check after every var x: AliasType = expr declaration. If the constraint fails, the program panics with the alias name in the message.
• --turbo strips checks — the same flag that strips contract assertions (Chapter 14) also strips type-alias checks for production builds.

Refinement types — aliases with value parameters

A type alias can carry value parameters that are bound into the constraint. Same family of alias, many different bounds:

# file: 13_refinement_types.zbr
# teaches: parametric refinement types
# chapter: 13-Generics-and-Type-Constraints

type Bounded(lo: int, hi: int) = int where value >= lo and value <= hi

def main()
    var score: Bounded(0, 100) = 85           # OK
    var neg:   Bounded(-50, 50) = -20         # OK
    # var bad: Bounded(0, 100) = 150          # runtime panic

    var temp: Bounded(-273, 1000) = 37        # body temperature — OK
    print(temp)  # 37

The parameters (here lo and hi) sit alongside value in the where expression. Each var x: Bounded(...) declaration substitutes the parameter values and emits the check.

Struct base types

The base type can be a struct, and the constraint can inspect fields:

struct Range
    var lo: int
    var hi: int

type ValidRange = Range where value.lo < value.hi

def main()
    var r: ValidRange = Range(lo: 0, hi: 10)  # OK
    # var bad: ValidRange = Range(lo: 5, hi: 3)  # runtime panic

Struct aliases don't carry value parameters in v1.0 — the parametric form is for primitive base types only.

When to reach for refinement types

• Domain invariants that should hold at every assignment — port numbers in 1..65535, percentages in 0..100, ages in 0..150.
• Self-documenting parameter types — Bounded(0, 100) reads better than int plus a comment.
• Bug-catching in tests — paired with --turbo-stripped release builds, you pay the check cost only during development.

For invariants on whole functions (not just variable assignments), prefer require / ensure contracts — see Chapter 14.

Real World: Generic Cache

A practical example: a cache that works with any type:

# file: 13_generic_cache.zbr
# teaches: realistic generic class
# chapter: 13-Generics-and-Type-Constraints

class Cache(K, V)
    var data: HashMap(K, V) = HashMap()
    var max_size: int
    
    cue init(max_size: int)
        this.max_size = max_size
    
    def put(key: K, value: V)
        if data.count() >= max_size and not data.contains(key)
            # Evict first key (simplistic LRU simulation)
            # In real code, track access order
            pass
        data.put(key, value)
    
    def lookup(key: K): V?
        if data.contains(key)
            return data.fetch(key)
        return nil
    
    def clear
        data = HashMap()

def main()
    var cache = Cache(str, int)(3)   # the ctor args go on the constructor call
    cache.put("a", 1)
    cache.put("b", 2)
    cache.put("c", 3)
    
    var val = cache.lookup("b")
    if val != nil
        print("Got: ${val}")

Common Mistakes

Mistake 1: Forgetting to Instantiate Generic Parameters

# WRONG
var box = Container()  # Error: T not specified
box.store(42)

# CORRECT
var box = Container(int)()
box.store(42)

Mistake 2: Mixing Types in a Generic Container

# WRONG
var box = Container(int)()
box.store("hello")  # Error: Expected int, got str

# CORRECT
var box = Container(str)()
box.store("hello")

Mistake 3: Forgetting to Declare the Type Parameter

# WRONG - T is used but never declared
def find_max(items: List(T)): T     # error: unknown type 'T'
    var max = items.at(0)
    for item in items
        if item > max
            max = item
    return max

# CORRECT - declare T, and pass it at the call
def find_max(T)(items: List(T)): T
    var max = items.at(0)
    for item in items
        if item > max
            max = item
    return max

# find_max(int)([3, 9, 4]) is 9

The body is checked for each type it is called with: find_max(int) and find_max(str) compile; a type with no > does not (today the error comes from Zig, not Zebra).

Mistake 4: Expecting Runtime Type Tests on T

Type parameters are not erased. Each distinct type argument compiles its own copy of the function (Zig's comptime monomorphization), so inside process(int) the parameter simply is int, and there is nothing to test at runtime. Code that only makes sense for some types belongs behind an interface constraint (T where T implements Comparable(T)) or in a separate, non-generic function -- not behind a runtime check on T.

Exercises

Exercise 1: Generic Stack

Implement a Stack(T) class with push, pop, and is_empty methods:

class Stack(T)
    var items: List(T) = List()
    
    def push(value: T)
        items.add(value)
    
    def pop(): T?
        if items.count() == 0
            return nil
        var value = items.at(items.count() - 1)
        # Remove last item (simplified - no remove method)
        return value
    
    def is_empty(): bool
        return items.count() == 0

def main()
    var stack = Stack(int)()
    stack.push(1)
    stack.push(2)
    stack.push(3)
    
    var val = stack.pop()
    if val != nil
        print("Popped: ${val}")

Exercise 2: Filter Function with a sig Predicate

Write a function that filters a list of int based on a predicate. Function parameters that accept lambdas must use a named sig type — inline def(T): R types are not valid in parameter position (see Chapter 04).

sig IntPredicate(x: int): bool      # name the function type

class ListUtils
    static
        def filter(items: List(int), pred: IntPredicate): List(int)
            var result: List(int) = List()
            for item in items
                if pred(item)
                    result.add(item)
            return result

def is_even(x: int): bool
    return x % 2 == 0

def main()
    var numbers: List(int) = List()
    numbers.add(1)
    numbers.add(2)
    numbers.add(3)
    numbers.add(4)

    var evens = ListUtils.filter(numbers, is_even)

    for e in evens
        print(e)

Exercise 3: Generic Wrapper with Validation

Create a ValidatedBox(T) that only accepts values passing a validation function:

class ValidatedBox(T)
    var item: T?
    var validator: T -> bool
    
    cue init(validator: T -> bool)
        this.validator = validator
    
    def set(value: T): bool
        if validator(value)
            item = value
            return true
        return false
    
    def get(): T?
        return item

def main()
    var age_box = ValidatedBox(int)()
    age_box.init({ x in x >= 0 and x <= 150 })
    
    if age_box.store(25)
        print("Valid age: ${age_box.retrieve()}")
    
    if not age_box.store(200)
        print("Invalid age")

Key Takeaways

• Generics enable type-safe reusable code — Write once, use with many types
• Type parameters are like function parameters — Container(T) where T is filled in at use time
• Collections are generics — List(T), HashMap(K, V) work with any type
• Constraints limit generics — Use interfaces to require specific capabilities
• Type erasure happens at compile time — Don't rely on runtime type information

Next Steps

• → 14-Contracts — Express what generics must provide
• → 15-Pipelines — Chain generic operations cleanly
• → Project 1 — Use generics in real code

Generics are the bridge between flexibility and safety. Master them, and your code scales.

14: Contracts and Assertions

Audience: All Time: 90 minutes Prerequisites: 04-Functions-and-Scope, 07-Classes-and-Instances, 12-Error-Handling You'll learn: require (preconditions), ensure (postconditions, result, old), invariant (class invariants), assert, and the --turbo strip flag

The Big Picture

Contracts are one of Zebra's marquee features. A contract is an executable specification attached to a function or class — the compiler emits runtime checks for each clause:

def withdraw(amount: int): int throws
    require
        amount > 0
        amount <= balance
    ensure
        result == old balance - amount
    balance = balance - amount
    return balance

Three keywords cover the common cases:

These get checked at runtime by default. Pass --turbo to the compiler to strip them all out for production builds — same semantics as -DNDEBUG for C assert.

Why bother? Manual if x raise "..." checks at the top of each method work, but they bury the contract in normal control flow. require / ensure / invariant make the contract syntactically distinct, give it a structured failure message with the failing clause, and let the production build remove the cost without touching the source.

This is Design by Contract, an idea from Eiffel that Zebra inherits and adapts.

Preconditions: require

A require block lists conditions that must hold when the method is called. Each condition is a Boolean expression on its own line:

# file: 14_require.zbr
# teaches: precondition checking with require
# chapter: 14-Contracts-and-Assertions

class Bank
    var balance: int = 100

    def withdraw(amount: int): int
        require
            amount > 0
            amount <= balance
        balance = balance - amount
        return balance

def main()
    var bank = Bank()
    print(bank.withdraw(50))  # 50
    # bank.withdraw(-10)            # → panic: require failed in 'withdraw'
    # bank.withdraw(1000)           # → panic: require failed in 'withdraw'

If any clause is false, Zebra panics with a message naming the method and the failing clause.

When to use require:

• Validate parameters (range, non-emptiness, format)
• Assert preconditions on the receiver's state ("only call after init")
• Document required ordering between methods

require failures indicate a caller bug — the caller violated the contract. Don't use require for user input you intend to validate gracefully; that's throws + raise (Chapter 12).

Postconditions: ensure

An ensure block lists conditions that must hold when the method returns normally:

# file: 14_ensure.zbr
# teaches: postcondition checking with ensure
# chapter: 14-Contracts-and-Assertions

class Counter
    var count: int = 0

    def increment(): int
        ensure
            count > 0
        count = count + 1
        return count

def main()
    var c = Counter()
    print(c.increment())  # 1
    print(c.increment())  # 2

ensure clauses fire only on the success path, not when the method raises an error. This is by design (a throwing method has no meaningful postcondition).

The result keyword

Inside ensure, the keyword result refers to the value the method is about to return. It has the same type as the method's declared return, so member access works naturally:

# file: 14_ensure_result.zbr
# teaches: result in ensure clauses
# chapter: 14-Contracts-and-Assertions

class Strings
    static
        def normalise(s: str): str
            ensure
                result.len <= s.len           # never grows
                not result.startsWith(" ")
                not result.endsWith(" ")
            return s.trim()

result is only valid inside ensure. In the method body, you'd refer to the to-be-returned variable by its own name; result is a contract-time binding, not a regular variable.

The old snapshot

When you need to compare the post-call state to the pre-call state, use the old operator inside ensure. It snapshots an expression at function entry:

# file: 14_ensure_old.zbr
# teaches: old snapshots in ensure clauses
# chapter: 14-Contracts-and-Assertions

class Counter
    var count: int = 0

    def increment(): int
        ensure
            result == old count + 1       # post-state vs pre-state
            count == old count + 1
        count = count + 1
        return count

old expr is valid only inside ensure. Each occurrence captures expr once at function entry; the captured value is then used in the post-condition check.

Invariants: invariant

A class invariant block lists conditions that must hold whenever the object is observable from outside. Zebra checks the invariant after cue init returns and after every public method exits:

# file: 14_invariant.zbr
# teaches: class invariants
# chapter: 14-Contracts-and-Assertions

class Account
    var balance: int = 0
    var transactions: int = 0

    invariant
        balance >= 0
        transactions >= 0

    def deposit(amount: int)
        require
            amount > 0
        balance = balance + amount
        transactions = transactions + 1

    def withdraw(amount: int)
        require
            amount > 0
            amount <= balance
        balance = balance - amount
        transactions = transactions + 1

def main()
    var acct = Account()
    acct.deposit(50)
    acct.withdraw(30)
    # Both invariants checked after each method returns.

Why invariants are a force multiplier: instead of repeating the same five sanity checks at the end of every method, you write them once in invariant and the compiler weaves them into every method exit. When you add a sixth method later, it gets the invariant check for free.

An invariant is checked after cue init returns, not before — your constructor is allowed to assemble state stepwise. Same for setters: the invariant is checked once at the end, not after each individual assignment.

Assertions: assert

For one-off checks inside a method body — debug-time sanity probes that don't fit the contract structure — Zebra has a plain assert statement:

# file: 14_assert.zbr
# teaches: assert statement
# chapter: 14-Contracts-and-Assertions

class Math
    static
        def divide(a: int, b: int): int
            require
                b != 0
            var q = a / b
            assert q * b == a       # integer-division sanity probe
            return q

Like the contract clauses, assert panics on a false condition — but unlike them it is not stripped by --turbo: a contract is an obligation on the caller, an assert is a check you wrote to run in every build. It's a more granular tool than ensure — useful for checking intermediate values inside a method body.

Real-world example: a sorted list

A class that combines require (caller contract), ensure (per-method guarantee), and invariant (always-true property):

# file: 14_sorted_list.zbr
# teaches: combining require, ensure, and invariant
# chapter: 14-Contracts-and-Assertions

class SortedList
    var items: List(int)

    cue init()
        items = List(int)()

    invariant
        # The list is always non-decreasing
        isSorted()

    # private: the invariant is checked after every PUBLIC method, so a
    # public isSorted() would re-trigger the invariant that calls it.
    private def isSorted(): bool
        var i = 1
        while i < items.count()
            if items.at(i - 1) > items.at(i)
                return false
            i = i + 1
        return true

    def insert(value: int)
        ensure
            items.count() == old items.count() + 1
        # Find the first position whose element is not smaller than value.
        var i = 0
        while i < items.count() and items.at(i) < value
            i = i + 1
        items.add(value)
        # Shift the tail right by one, then drop value into its slot.
        var j = items.count() - 1
        while j > i
            items.set(j, items.at(j - 1))
            j = j - 1
        items.set(i, value)

    def smallest(): int
        require
            items.count() > 0
        return items.at(0)

def main()
    var sl = SortedList()
    sl.insert(3)
    sl.insert(1)
    sl.insert(2)
    print(sl.smallest())  # 1
    # Invariant verified after every public method.

The invariant catches any bug in insert automatically — there's no need to remember to add a "verify still sorted" check at the end of every mutation.

--turbo: stripping contracts for production

In normal builds, every require, ensure, and invariant emits runtime check code. These add safety during development but cost cycles in hot paths. Pass --turbo to the compiler to strip them entirely (assert statements are kept):

zebra app.zbr              # contracts active — runtime checks emitted
zebra --turbo app.zbr      # contracts stripped — same source, faster binary

--turbo is, for contracts, the same source-to-binary toggle C/C++ get with -DNDEBUG. Use it for production releases; develop and test without it.

Don't put load-bearing logic inside contract clauses — anything you can't afford to lose at --turbo time. Side effects in require / ensure are already a code smell; --turbo makes the smell into a bug.

If you're new to programming

A precondition is "what must be true before I run." A postcondition is "what I promise will be true after I run." An invariant is "what stays true the whole time the object exists."

Contracts are a way of writing your assumptions down as code instead of in comments — comments rot when the code changes; contracts panic when the code violates them.

Common Mistakes

❌ Using require for user-input validation

def parse_age(s: str): int
    require
        s.len > 0       # ❌ user-supplied — should be a graceful failure, not a panic
    return 42

✅ Use throws/raise for failures the caller can handle:

def parse_age(s: str): int throws
    if s.len == 0
        raise "empty input"
    return 42

Reserve require for caller-bug detection.

❌ Putting side effects in require / ensure / invariant

def step(): int
    ensure
        logger.write("step done")    # ❌ side effect in ensure
        result > 0
    ...

Contract clauses are stripped by --turbo. Anything you do inside one evaporates in production.

❌ Using result outside ensure

def f(): int
    return result + 1     # ❌ `result` is contract-only; not a regular variable

result is only meaningful inside ensure. Inside the method body, store the to-be-returned value in a regular var if you need to refer to it.

❌ Expecting ensure to fire on the error path

def divide(a: int, b: int): int throws
    ensure
        result > 0
    if b == 0
        raise "div by zero"
    return a / b

When the function raises, ensure is not evaluated — that's correct behaviour (a throwing method has no meaningful postcondition). Don't design contracts that depend on ensure running on error paths.

Exercises

Exercise 1: Bank account with contracts

Rewrite the standard bank-account example using require, ensure, and invariant:

class BankAccount
    var balance: int = 0
    var transactions: int = 0

    invariant
        balance >= 0
        transactions >= 0

    def deposit(amount: int)
        require
            amount > 0
        ensure
            balance == old balance + amount
            transactions == old transactions + 1
        balance = balance + amount
        transactions = transactions + 1

    def withdraw(amount: int)
        require
            amount > 0
            amount <= balance
        ensure
            balance == old balance - amount
            transactions == old transactions + 1
        balance = balance - amount
        transactions = transactions + 1

def main()
    var acct = BankAccount()
    acct.deposit(100)
    acct.withdraw(30)
    print("Balance: ${acct.balance}")
    print("Transactions: ${acct.transactions}")

Exercise 2: Validated array indexer

Write a class that wraps a List(int) with bounds-checked access, using require to document the contract:

class SafeArray
    var items: List(int)

    cue init()
        items = List(int)()

    def push(v: int)
        ensure
            items.count() == old items.count() + 1
        items.add(v)

    def at(i: int): int
        require
            i >= 0
            i < items.count()
        return items.at(i)

    def first(): int
        require
            items.count() > 0
        return items.at(0)

def main()
    var sa = SafeArray()
    sa.push(10)
    sa.push(20)
    print(sa.at(0))  # 10
    print(sa.first())  # 10
    # sa.at(99)                # → panic: require failed in 'at'

Exercise 3: Stack with size invariant

Write a Stack(int) with push/pop/top that maintains an invariant relating count() to items.count():

class Stack
    var items: List(int)
    var size: int = 0

    cue init()
        items = List(int)()

    invariant
        size >= 0
        size == items.count()

    def push(v: int)
        ensure
            size == old size + 1
        items.add(v)
        size = size + 1

    def pop(): int
        require
            size > 0
        ensure
            size == old size - 1
        var last = items.at(size - 1)
        items.remove(size - 1)      # remove by index, keeping the invariant true
        size = size - 1
        return last

    def top(): int
        require
            size > 0
        return items.at(size - 1)

def main()
    var s = Stack()
    s.push(1)
    s.push(2)
    s.push(3)
    print(s.top())  # 3
    print(s.pop())  # 3
    print(s.top())  # 2

Key Takeaways

• require documents the caller's contract. Use it for caller-bug detection, not for graceful user-input validation.
• ensure documents the method's promise. result refers to the return value; old expr snapshots expr at entry.
• invariant documents the object's permanent state. Checked after init and after every public method exit — write the invariant once, get the check for free everywhere.
• assert is the granular tool: an inline sanity probe inside a method body.
• --turbo strips the contract clauses (require/ensure/invariant); assert survives it. Develop with contracts on; ship with contracts off. Don't put side effects inside contract clauses.

Next Steps

• → 15-Pipelines — Composing functions whose contracts compose, too
• 🏋 Project 1 (CLI Tool) — Use contracts for argument validation

Contracts turn debugging from "where did this go wrong" into "the contract says what was supposed to be true; here's exactly which clause failed."

14b: Memory Management and Lifetimes

Audience: All — required for long-running services or bounded-memory work Time: 120 minutes Prerequisites: 07-Classes-and-Instances, 07b-Structs-Unions-and-Value-Types You'll learn: The default arena allocator, scoped allocate blocks, the <<- copy-out operator, the using EXPR resource pattern, and ^T heap-indirection for recursive types

The Big Picture

Most languages handle memory in one of three ways:

• Garbage collection (Python, Java, Go) — fast to write, periodic pauses
• Manual malloc/free (C, C++) — total control, easy to misuse
• Borrow checker / ownership (Rust) — compile-time safe, learning curve

Zebra picks a fourth option: a program-wide arena allocator, with optional bounded scopes. By default every allocation lives until program exit; you never write free. When you need to reclaim memory mid-program — for a long-running server, a streaming file processor, a large batch job — you wrap the work in an allocate Arena() block.

This model has two benefits worth naming:

1. The 90% case has zero cognitive overhead. Short-lived programs, CLI tools, scripts — they just work. No annotations, no ceremony.
2. The 10% case is explicit. When you need bounded memory, the allocate block is right there in the source: a reader can see exactly where the memory is reclaimed.

This chapter covers the default model, the scoped escape hatch, the <<- copy-out operator for passing values past a scope boundary, and the ^T heap-indirection syntax for recursive types.

The Default Allocator

Every Zebra program starts with one ArenaAllocator, exposed internally as _allocator. Every implicit allocation — string concatenation, List growth, class instantiation — pulls from this arena.

def main()
    var s = "hello"
    var t = " world"
    var combined = s + t          # allocates a new str — arena handles it
    var nums = List(int)()
    nums.add(1); nums.add(2)       # List growth — arena handles it
    var c = Circle(radius: 5.0)   # class instance — arena handles it
    print(combined)
    # Program exits; arena is destroyed; all of the above freed at once.

There's no s.free(), nums.deinit(), or c.drop(). There's no defer. Allocations live until program exit.

Why no individual free?

Two reasons:

1. ArenaAllocator doesn't support targeted frees. Calling allocator.free(x) on an arena either no-ops (middle of the arena) or rewinds the bump pointer (last allocation) — which corrupts any sub-slice still in use elsewhere. So even if Zebra emitted defer allocator.free(x), it would not be safe.
2. For typical programs it doesn't matter. A CLI tool that runs for 200ms doesn't care that its strings outlive a function call. The OS reclaims the whole arena on process exit.

For long-running programs that do care, the answer is allocate.

Scoped Memory: allocate Blocks

The allocate <expr> block redirects _allocator to a different allocator for a lexical scope. When the block exits, scoped allocators clean up and _allocator reverts to the parent.

def main()
    var summary = ""
    allocate Arena()
        var src = File.read("big_file.txt")
        var parsed = parse(src)
        summary <<- summarise(parsed)       # copy result out (see below)
    # src, parsed, and all parse temporaries freed here.
    print(summary)

Inside the block, every implicit allocation goes through the inner arena. When the block exits, the entire inner arena is reclaimed — even if big_file.txt was 100MB and parsed produced thousands of intermediate strings.

Named allocator wrappers

allocate accepts any value that implements AllocatorSource (a class with def allocator(): Allocator + def deinit()). The stdlib ships a named wrapper for every common pattern:

Scoped means the wrapper frees everything on block exit. Non-scoped wrappers are singletons; allocations outlive the block naturally.

Typical use cases

• Streaming file processor. Read → parse → reduce, in a loop. Wrap each iteration in allocate Arena() so the previous iteration's buffers don't pile up.
• Leak detection in CI. Swap Arena() for Debug() during development; Debug() reports any unmatched allocations on exit.
• Stack-local scratch. allocate StackFallback(4096)() keeps small work on the stack and only spills to the heap if the 4KB budget is exceeded.
• Bounded peak memory. Any batch operation where you want a hard ceiling on memory usage.

What Does NOT Survive a Scoped Block

Anything allocated inside a scoped allocate block is freed when the block exits. If you save a reference to it in an outer variable directly, that reference becomes dangling.

# UNSAFE — DO NOT DO THIS
var dangling: str
allocate Arena()
    var src = File.read("config.txt")
    dangling = src                # WRONG: src lives in the inner arena
print(dangling)  # dangling slice — undefined behaviour

The compiler can't always catch this — dangling = src looks like a normal assignment. The right pattern is the <<- copy-out operator.

<<- Copy-Out

The <<- operator deep-copies a value from the inner allocator into the parent allocator and assigns it to an outer variable:

var summary: str = ""
allocate Arena()
    var src = File.read("big_file.txt")
    var s = process(src)
    summary <<- s                 # deep-copies s into the parent allocator
# src + s + temporaries freed; summary survives.
print(summary)

For each supported type, <<- does the right thing:

The HashMap limitation is by design. Deep-copying a HashMap requires re-hashing every key, and the result almost always indicates the wrong data structure for the lifetime pattern. If you need to surface key/value data past a block boundary, iterate and rebuild:

var out: HashMap(str, int) = HashMap(str, int)()
allocate Arena()
    var tmp: HashMap(str, int) = HashMap(str, int)()
    populate(tmp)
    # out <<- tmp                                   # ERROR
    for k, v in tmp                                 # iterate + rebuild
        out.set(k, v)                               # k and v are str/int — copy-out implicit

Outside a scoped block

<<- is a normal assignment when used outside any scoped block (or inside a non-scoped wrapper like Page()/Smp()/C()). You can write <<- defensively in code that might or might not be inside allocate — it's always safe.

def main()
    var x: str = ""
    x <<- "hello"                 # outside any allocate block — plain assignment

using EXPR — Resource Scope Blocks

The using EXPR block runs a body with a resource that has a begin() / end() lifecycle. The compiler calls those two methods for you, so they are cues (Chapter 07, "Cues"): any class that declares cue begin() and cue end() works — no interface declaration required:

class CountGroup
    var entered: int = 0
    var exited: int = 0

    cue begin()
        .entered = .entered + 1

    cue end()
        .exited = .exited + 1

def main()
    var g = CountGroup()
    using g
        print("inside the using block")
    # Here: g.entered == 1, g.exited == 1

Desugaring

A using EXPR block compiles to Zig of this shape (a sketch, not Zebra — body... stands for the block's statements):

{
    const _resource = EXPR;
    _resource.begin();
    defer _resource.end();
    body...
}

EXPR is evaluated exactly once. end() fires only if begin() completed successfully — if begin() raises, end() does not run.

Why this matters for memory

using is the RAII pattern from C++ and the with statement from Python, in one form. It pairs begin/end calls so a reader can see the resource is cleaned up. The GUI stdlib uses it for layout groups:

using g.vbox("##main", true)
    using g.hbox("##row", false)
        g.button("OK", .ok)
        g.button("Cancel", .cancel)
    g.text("Status: ready")

Each vbox and hbox opens a layout container in begin() and closes it in end(). The body in between issues widget commands inside that container.

using vs. allocate

They compose. A program can have using blocks inside allocate blocks and vice versa.

No destructors

Zebra has no destructor: there is no cue deinit in 1.0, and the compiler refuses one ("unknown cue 'deinit'"). A destructor would run at the end of a scope, and a class instance is a reference that can outlive the scope it was made in (stored in a list, returned, captured), so "end of scope" is not "end of the object". The two constructs above cover the two jobs a destructor does elsewhere. The arena reclaims memory, and using runs a release step at a point you can see in the source. begin() and end() are the two cues using calls; there is no third one for the end of a scope.

Older code: before begin and end became cues they were written def begin() / def end(). That spelling still builds in this release, but each using that reaches it prints a warning ("declares begin/end with def; they are cues now") and a later release will refuse it.

^T — Heap Indirection for Recursive Types

^T is a special field-type marker for breaking recursive struct or union cycles. It's the only reason to reach for ^T in Zebra; for ordinary references, classes already give you reference semantics.

struct Node
    var value: int
    var next:  ^Node?              # heap-boxed optional pointer

def main()
    var a = Node(1, nil)
    var b = Node(2, nil)
    a.next = b                     # auto-boxes b into a *Node on the heap

The rules

^T? and nil

struct TreeNode
    var value: int
    var left:  ^TreeNode?
    var right: ^TreeNode?

def main()
    var root  = TreeNode(value: 5, left: nil, right: nil)
    var child = TreeNode(value: 3, left: nil, right: nil)
    root.left = child              # auto-boxes child into *TreeNode

    if root.left as n              # n: TreeNode — pointer is transparent
        print(n.value)

Unions with ^T payload

The classic AST shape:

union Expr
    num(value: int)
    add(left: ^Expr, right: ^Expr)

def main()
    var e = Expr.add(left: Expr.num(1), right: Expr.num(2))
    branch e
        on Expr.add as a
            # a.left: Expr (not ^Expr — auto-deref'd)
            print("add")
        on Expr.num as n
            print(n.value)

This is exactly how Zebra's own compiler models its AST.

Memory interaction

^T allocations go through whatever _allocator is active. Inside an allocate Arena() block, the boxes live in the inner arena and are freed on block exit. The <<- copy-out operator recursively follows ^T? chains — copying out a linked list copies every node.

var head: ^Node? = nil
allocate Arena()
    var n = Node(value: "a", next: Node(value: "b", next: nil))
    head <<- n             # recursively copies the entire chain into parent
# inner nodes freed; head's chain is intact in the parent arena.

Where the Memory Goes: --census

When a long-running program grows, the question is which line is allocating. Build and run it with --census and every allocation is counted under the source line that made it:

zebra --census prog.zbr                       # report on stderr at exit
ZEBRA_CENSUS_OUT=out.json zebra --census prog.zbr

At exit — including through sys.exit — the program prints a report on stderr and writes zebra-census.json. It lists the totals (allocations, bytes requested, bytes freed, peak), then each site: the file and line, what allocated there (a runtime helper such as _str_concat, a constructor, your own function), how many allocations and bytes it requested, and how many bytes it still keeps at the end. The ranking by bytes kept is the one that shows a leak or an unbounded cache. Without the flag nothing is counted, and sys.memStats() reports the census fields as -1 (not measured) rather than 0.

A program embedded in a host (--library-mode) can be built with --census=host: the census is compiled in but not started, and the host calls _zbr_cens_install() when the window it wants to measure begins — after start-up, say, so the report covers the steady state only. A census build costs time per allocation, so use it to investigate, not to ship.

Real World: Streaming File Processor

A pattern that benefits from every primitive in this chapter — a loop that processes many files, with bounded peak memory and a structured result that survives each iteration:

# file: 14b_streaming_processor.zbr
# teaches: allocate + <<- + using together
# chapter: 14b-Memory-Management-and-Lifetimes

class Summary
    public var filename: str = ""
    public var word_count: int = 0
    public var top_word: str = ""

def process_one(path: str): Summary
    var result = Summary()
    result.filename = path
    allocate Arena()
        var src = File.read(path)
        var words = src.split(" ")
        result.word_count = words.count()
        result.top_word <<- most_frequent(words)  # copy-out the single str
    # All of src + words freed here; result survives.
    return result

def most_frequent(words: List(str)): str
    # ... implementation that allocates a HashMap internally ...
    return ""

def main()
    var summaries: List(Summary) = List()
    for name in File.listDir("./docs")        # entry names, not paths
        var s = process_one(Path.join("./docs", name))
        summaries.add(s)               # Summary itself is in the outer arena

    for s in summaries
        print("${s.filename}: ${s.word_count} words, top=${s.top_word}")

Each call to process_one reads its file, computes its summary, copies the relevant strings into the caller's arena, then frees everything else. Peak memory stays bounded at one file's worth — regardless of whether there are 10 files or 10,000.

Common Mistakes

❌ Mistake: Storing a value from inside an allocate block without <<-

var s: str
allocate Arena()
    s = File.read("config.txt")      # s now points into the inner arena
# s is dangling here

✅ Better:

var s: str
allocate Arena()
    var tmp = File.read("config.txt")
    s <<- tmp                         # deep-copy into parent

❌ Mistake: Trying to copy out a HashMap

var out: HashMap(str, int) = HashMap(str, int)()
allocate Arena()
    var tmp: HashMap(str, int) = HashMap(str, int)()
    out <<- tmp                       # ERROR: HashMap copy-out not supported

✅ Better: iterate and rebuild outside:

for k, v in tmp
    out.set(k, v)                     # primitives copy implicitly

❌ Mistake: Reaching for ^T on a class field

class Tree
    var left:  ^Tree?                 # ERROR: ^ClassName is illegal

✅ Better: Tree is already a reference type:

class Tree
    var left:  Tree?                  # plain reference; no ^ needed

❌ Mistake: Forgetting that allocate Page() doesn't free

allocate Page()
    var src = File.read("huge.bin")
# src is NOT freed here — Page() is non-scoped

✅ Better: use Arena() for bounded scopes:

allocate Arena()
    var src = File.read("huge.bin")
# src freed here

Exercises

Exercise 1: A Bounded-Memory Loop

Rewrite this loop so peak memory stays bounded at one file at a time:

def main()
    var counts: List(int) = List()
    for name in File.listDir("./logs")
        var path = Path.join("./logs", name)
        var src = File.read(path)        # accumulates across iterations
        counts.add(src.split("\n").count())

def main()
    var counts: List(int) = List()
    for name in File.listDir("./logs")
        var path = Path.join("./logs", name)
        var n: int = 0
        allocate Arena()
            var src = File.read(path)
            n <<- src.split("\n").count()
        counts.add(n)

Exercise 2: A Recursive Tree

Define a binary tree of integers using ^T? and write a function that counts the nodes recursively.

struct TreeNode
    var value: int
    var left:  ^TreeNode?
    var right: ^TreeNode?

def count_nodes(t: ^TreeNode?): int
    if t as n                # n: TreeNode — pointer is transparent
        return 1 + count_nodes(n.left) + count_nodes(n.right)
    return 0

def main()
    var leaf  = TreeNode(value: 3, left: nil, right: nil)
    var leaf2 = TreeNode(value: 7, left: nil, right: nil)
    var root  = TreeNode(value: 5, left: leaf, right: leaf2)
    print(count_nodes(root))  # 3

Exercise 3: A using Resource

Write a BlockTimer class whose cue begin() starts a clock and whose cue end() prints the elapsed milliseconds. Use it with using to time a block. (The standard library's Timer.start() is the clock; t.elapsed() gives milliseconds as a float.)

class BlockTimer
    var label: str
    var clock: Timer

    cue init(label: str)
        .label = label
        .clock = Timer.start()

    cue begin()
        .clock = Timer.start()

    cue end()
        print("${.label}: ${.clock.elapsed()} ms")

def main()
    using BlockTimer("nap")
        sys.sleep(20)
        # ... work ...
    # Prints "nap: NN ms" when the block exits

Next Steps

• → 14c-Concurrency-Channels-and-Threads — concurrent primitives that share this memory model
• → 22-FFI-and-Interop — allocate C() for libc-allocated values crossing the FFI boundary
• → 07b-Structs-Unions-and-Value-Types — the value-type model that ^T punches through

Key Takeaways

• Default model: arena allocator, no individual frees. Allocations live until program exit; the OS reclaims the arena.
• allocate <wrapper> scopes the allocator for a block; on exit, scoped wrappers free everything inside.
• Named wrappers include Arena() (most common), Debug() (leak detection), FixedBuffer(buf), StackFallback(N)(), Pool(T)(), and non-scoped singletons Page() / Smp() / C().
• <<- copy-out deep-copies a value past a scope boundary — works for str, List(T), classes/structs (incl. recursive ^T? chains), and primitives; HashMap is intentionally not supported — iterate and rebuild.
• using EXPR blocks call the begin() / end() cues around a body; any class that declares cue begin() and cue end() works. Use for arbitrary cleanup; pair with allocate for memory.
• ^T heap-indirection is for recursive structs/unions only; auto-boxes, transparent in branch and for-loops; ^ClassName is illegal (classes are already references).

Next: Chapter 14c covers concurrency — Chan(T) channels, sys.go() for spawning threads, and the ThreadPool / Atomic primitives — built on the memory model from this chapter.

14c: Concurrency — Channels and Threads

Audience: All — required for servers, parallel computation, or any I/O at scale Time: 120 minutes Prerequisites: 04-Functions-and-Scope, 14b-Memory-Management-and-Lifetimes You'll learn: Chan(T) channels, sys.go() for spawning threads, Atomic(T) for shared counters and flags, ThreadPool(n) for bounded worker pools, and which primitive to reach for in each situation

The Big Picture

Concurrency in Zebra has two pillars:

• Threads — independent stacks running in parallel, sharing the same arena allocator
• Channels — typed, buffered queues that move values safely between threads

This is the [CSP model] popularised by Go: prefer communicating over sharing. Most patterns reduce to "spawn a worker, give it a channel, read from the channel." The compiler doesn't have a borrow checker, so correctness comes from this discipline plus a small set of Atomic primitives for the few cases where channels are overkill.

This chapter walks the four primitives — Chan(T), sys.go(), Atomic(T), ThreadPool(n) — and the patterns that combine them.

Channels: Chan(T)

Chan(T) is a thread-safe buffered channel carrying values of type T. Construct it with a capacity:

var ch: Chan(int) = Chan(int)(4)   # buffer up to 4 values

Three operations:

def main()
    var ch: Chan(int) = Chan(int)(4)
    ch.send(1)
    ch.send(2)
    ch.close()

    var v1: int? = ch.recv()       # 1
    var v2: int? = ch.recv()       # 2
    var v3: int? = ch.recv()       # nil — channel closed + empty

    if v1 as n
        print(n)                   # 1
    if v3 == nil: print("done")

The <- operator

The <- operator is syntactic sugar for send / recv:

ch <- 42                # equivalent to ch.send(42)

var v: int? = nil
v <- ch                 # equivalent to v = ch.recv()

<- reads naturally — left arrow into the channel for send, left arrow into the variable for receive. Many Zebra programs use the sugar exclusively.

Not to be confused with <<-. Chapter 14b covers <<-, the copy-out operator inside allocate blocks. It is a different token: <- means channel send/receive and nothing else.

Spawning Threads: sys.go()

sys.go(def() ...) spawns a fire-and-forget background thread that runs the function's body:

sys.go(def()
    print("hello from a thread")
)

The function takes no parameters. Every variable from the enclosing scope that the body uses must be declared in a capture block at the top of the body. An ordinary lambda captures what it reads on its own; a thread closure does not, and using an outside variable without declaring it is refused ("a sys.go closure names what it uses in a capture block"). Re-declaring under the same name (var ch: Chan(int) = ch) is the usual idiom. Captured values are copied into the thread closure at spawn time, so the spawning function can return immediately without leaving dangling references.

def main()
    var ch: Chan(int) = Chan(int)(4)

    sys.go(def()
        capture
            var ch: Chan(int) = ch
        ch.send(1)
        ch.send(2)
        ch.close()
    )

    # Main thread reads:
    var sum = 0
    var done = false
    while not done
        var v: int? = ch.recv()
        if v as n
            sum = sum + n
        else
            done = true
    print(sum)  # 3

What sys.go() does NOT give you

• No join. Threads are detached. There's no thread.wait() or return-value collection — use a channel to signal completion or to return a result.
• No backpressure. Every sys.go() call spawns a new OS thread. If you need bounded concurrency, use ThreadPool(n) (below).
• No panic recovery. If the body raises, the thread terminates. Design tasks to validate inputs before running heavy work.

Producer / Consumer Pattern

The canonical pattern: one or more producers send to a channel; one or more consumers recv until the channel is closed + empty.

# file: 14c_pipeline.zbr
# teaches: producer/consumer with Chan
# chapter: 14c-Concurrency-Channels-and-Threads

def main()
    var ch: Chan(int) = Chan(int)(4)

    # Producer: send 1..5, then close
    sys.go(def()
        capture
            var ch: Chan(int) = ch
        for i in 1..5
            ch.send(i)
        ch.close()
    )

    # Consumer: read until closed + empty
    var sum: int = 0
    var done: bool = false
    while not done
        var v: int? = ch.recv()
        if v as n
            sum = sum + n
        else
            done = true

    print(sum)  # 1+2+3+4 = 10

This is the workhorse of concurrent Zebra. Two takeaways:

1. The producer is responsible for closing. Without ch.close(), the consumer's recv() would block forever after the last value — it has no way to know the producer is finished.
2. The consumer reads T?, not T. recv() returns nil when the channel is closed and empty. The if v as n pattern is the idiomatic way to handle both cases.

Atomic(T) — Lock-Free Counters and Flags

Some shared state doesn't need a channel — a counter incremented by many threads, a "done" flag, a one-shot signal. For those, use Atomic(T):

var counter: Atomic(int) = Atomic(int)(0)
counter.add(1)
var n: int = counter.load()

Supported T: int and bool.

All operations use sequentially-consistent memory ordering — the safest and least-surprising default. For cases where relaxed ordering would be sound and faster, drop into zig"..." and call @atomicRmw directly.

Shared counter

def main()
    var total: Atomic(int) = Atomic(int)(0)

    sys.go(def()
        capture
            var total: Atomic(int) = total
        var _ = total.add(1)
    )
    sys.go(def()
        capture
            var total: Atomic(int) = total
        var _ = total.add(1)
    )

    # There is no join: poll until both increments have landed.
    while total.load() < 2
        sys.sleep(1)

    print(total.load())  # 2

One-shot done flag

def do_work()
    sys.sleep(20)                # stand-in for real work

def main()
    var done: Atomic(bool) = Atomic(bool)(false)

    sys.go(def()
        capture
            var done: Atomic(bool) = done
        do_work()
        done.store(true)
    )

    while not done.load()
        sys.sleep(10)

    print("worker finished")

Atomic vs. Chan — Which to Reach For

Rule of thumb: if multiple threads write the value, reach for Atomic; if one thread produces and another consumes, reach for Chan.

ThreadPool(n) — Bounded Workers

sys.go() spawns an unbounded thread per call — fine for a handful, bad for thousands. ThreadPool(n) runs a fixed n workers and queues submitted tasks among them:

def main()
    var pool: ThreadPool = ThreadPool(4)        # 4 worker threads
    var counter: Atomic(int) = Atomic(int)(0)

    var i: int = 0
    while i < 8
        pool.submit(def()
            capture
                var counter: Atomic(int) = counter
            var _: int = counter.add(1)
        )
        i = i + 1

    pool.wait()                  # blocks until all submitted tasks finish
    print(counter.load())  # 8

Key behaviours

• Reusable. submit after wait queues more work. A subsequent wait blocks on the new tasks.
• Workers run for the pool's lifetime — they're spawned at construction.
• Task panics terminate the worker, not the program — and they are not recovered. Validate inputs before submitting.

ThreadPool vs. sys.go()

For a 1000-item batch, ThreadPool(8) is almost always the right choice. For two or three I/O tasks running alongside the main thread, sys.go() is simpler.

ThreadPool + Chan: collecting results

The standard pattern for parallel computation with a return value:

def main()
    var ch: Chan(int) = Chan(int)(8)
    var pool: ThreadPool = ThreadPool(4)

    for i in 0..8
        pool.submit(def()
            capture
                var idx: int = i
                var ch: Chan(int) = ch
            ch.send(idx * idx)
        )

    pool.wait()                  # all tasks done; close the channel
    ch.close()

    var sum: int = 0
    var done: bool = false
    while not done
        var v: int? = ch.recv()
        if v as n
            sum = sum + n
        else
            done = true

    print(sum)  # 0+1+4+9+16+25+36+49 = 140

Three things to notice:

1. The capture block names everything the closure uses — captured-by-value semantics mean each task sees its own idx, not the shared loop variable.
2. pool.wait() runs before ch.close() — closing too early would race with sends still in flight.
3. The consumer is the main thread — no extra worker needed.

Memory and Allocator Interactions

Two important caveats:

Chan(T) uses the page allocator, not the arena. This is intentional — channels need to outlive any single allocate scope. But it means: do not construct a channel inside a short-lived allocate block if it's going to be used after the block exits. The channel itself survives, but its internal buffer storage may not.

ThreadPool also uses the page allocator. Same rule: don't construct one inside a short-lived allocate scope.

For practical purposes: declare your channels and pools at function scope (or higher) and pass them by reference. Don't nest them inside allocate Arena() blocks unless you understand the lifetime implications.

Real World: Parallel File Processor

A common shape: walk a directory, process each file in parallel with a bounded pool, collect results via a channel.

# file: 14c_parallel_files.zbr
# teaches: ThreadPool + Chan for parallel I/O
# chapter: 14c-Concurrency-Channels-and-Threads

class FileResult
    public var path: str = ""
    public var line_count: int = 0

def process_file(path: str): FileResult
    var src = File.read(path)
    var lines = src.lines()        # not split("\n"): that counts the empty piece after a final newline
    var r = FileResult()
    r.path = path
    r.line_count = lines.count()
    return r

def main()
    var names = File.listDir("./docs")        # entry names, not paths
    var ch: Chan(FileResult) = Chan(FileResult)(names.count())
    var pool: ThreadPool = ThreadPool(4)

    for name in names
        pool.submit(def()
            capture
                var p: str = Path.join("./docs", name)
                var ch: Chan(FileResult) = ch
            ch.send(process_file(p))
        )

    pool.wait()
    ch.close()

    var results: List(FileResult) = List()
    var done = false
    while not done
        var r: FileResult? = ch.recv()
        if r as got
            results.add(got)
        else
            done = true

    for r in results
        print("${r.path}: ${r.line_count} lines")

This same shape — pool + channel + capture closure — covers parallel HTTP requests, parallel database queries, parallel image processing, and most other batch I/O patterns.

Common Mistakes

❌ Mistake: Forgetting to close the channel

sys.go(def()
    capture
        var ch: Chan(int) = ch
    for i in 1..5
        ch.send(i)
    # ch.close() omitted — consumer will block forever after the 4th value
)

✅ Better:

sys.go(def()
    capture
        var ch: Chan(int) = ch
    for i in 1..5
        ch.send(i)
    ch.close()
)

❌ Mistake: Sending to a closed channel

ch.close()
ch.send(1)              # PANIC at runtime

✅ Better: the producer is the only one who should close, and only after the last send.

❌ Mistake: Closing the channel before the producers finish

for i in 0..8
    pool.submit(def()
        capture
            var ch: Chan(int) = ch
        ch.send(work())
    )
ch.close()              # WRONG: tasks are still running
pool.wait()

✅ Better: wait first, then close:

for i in 0..8: pool.submit(...)
pool.wait()             # all sends are complete
ch.close()

❌ Mistake: Sharing a plain counter across threads

var counter: int = 0
sys.go(def()
    counter = counter + 1       # refused: a `sys.go` closure names what it uses in a `capture` block
)

The compiler refuses this — counter is not declared in a capture block. Declaring it there does not make it shared either: a captured int is a copy taken at spawn time, so it cannot carry a count back to the spawning thread.

✅ Better: use Atomic(int) and capture the cell:

var counter: Atomic(int) = Atomic(int)(0)
sys.go(def()
    capture
        var counter: Atomic(int) = counter
    var _ = counter.add(1)
)
sys.go(def()
    capture
        var counter: Atomic(int) = counter
    var _ = counter.add(1)
)

❌ Mistake: Using the loop variable without capturing it

for i in 0..8
    pool.submit(def()
        # capture missing — compile error: mutable 'i' not accessible
        print(i)
    )

✅ Better: use a capture block to snapshot the value — each task gets its own copy of i as it was when the task was submitted:

for i in 0..8
    pool.submit(def()
        capture
            var idx: int = i
        print(idx)
    )

Exercises

Exercise 1: A Simple Pipeline

Write a program that uses one producer thread to send the integers 1 through 10 down a channel, and the main thread to print their sum.

def main()
    var ch: Chan(int) = Chan(int)(4)

    sys.go(def()
        capture
            var ch: Chan(int) = ch
        for i in 1..11
            ch.send(i)
        ch.close()
    )

    var sum: int = 0
    var done: bool = false
    while not done
        var v: int? = ch.recv()
        if v as n
            sum = sum + n
        else
            done = true

    print(sum)  # 55

Exercise 2: Parallel Squaring

Use ThreadPool(4) to compute the squares of 0..16 in parallel. Collect the results in any order via a channel and print the sum.

def main()
    var ch: Chan(int) = Chan(int)(16)
    var pool: ThreadPool = ThreadPool(4)

    for i in 0..16
        pool.submit(def()
            capture
                var idx: int = i
                var ch: Chan(int) = ch
            ch.send(idx * idx)
        )

    pool.wait()
    ch.close()

    var sum: int = 0
    var done: bool = false
    while not done
        var v: int? = ch.recv()
        if v as n
            sum = sum + n
        else
            done = true

    print(sum)  # 0^2 + 1^2 + ... + 15^2 = 1240

Exercise 3: Wait Without Joining

Threads don't expose a join() call. Use an Atomic(bool) flag to have the main thread wait until a background thread signals completion.

def main()
    var done: Atomic(bool) = Atomic(bool)(false)

    sys.go(def()
        capture
            var done: Atomic(bool) = done
        # ... do work ...
        sys.sleep(100)
        done.store(true)
    )

    while not done.load()
        sys.sleep(10)

    print("background work finished")

Next Steps

• → 14b-Memory-Management-and-Lifetimes — the memory model that underpins all of this
• → 22c-Testing-and-Validation — concurrent code needs tests; the runner handles them like any other
• → 20-File-IO-and-System-Access — combine with sys.go for non-blocking I/O patterns

Key Takeaways

• Chan(T) is a thread-safe buffered channel: send blocks when full, recv blocks when empty, close signals end-of-stream
• <- sugar — ch <- v sends; v <- ch receives; reads naturally for pipelines
• sys.go(def() ...) spawns a fire-and-forget thread; outside variables must be declared in a capture block and are copied at spawn time; no join (use a channel for completion)
• Atomic(T) (T = int or bool) is for shared counters, flags, and one-shot signals; never blocks
• Rule of thumb: multiple writers → Atomic; producer/consumer → Chan
• ThreadPool(n) is a bounded worker pool with submit / wait; natural backpressure; reusable
• ThreadPool + Chan is the standard pattern for parallel computation with collected results
• Allocator caveat: Chan and ThreadPool use the page allocator; declare them at function scope, not inside short-lived allocate blocks
• Capture loop variables explicitly in for i in 0..N: pool.submit(...) — using i without a capture block is a compile error, and the capture gives each task its own copy

That's the end of the new chapters in Part 3. The next chapter in reading order is the existing 15-Pipelines-and-Function-Composition; when you're ready for the practical project arc, jump ahead to Part 4.

15: Pipelines and Function Composition

Audience: Experienced programmers
Time: 90 minutes
Prerequisites: 04-Functions-and-Scope, 06-Strings-and-Unicode
You'll learn: Pipeline operator, function composition, readable chains, real-world data flow

The Big Picture

Imagine you have a string and want to:

1. Convert to lowercase
2. Split into words
3. Get the first word
4. Get its length

Without pipelines:

var text = "HELLO WORLD"
var words = text.lower().split(" ")
var first_word = words.at(0)
var length = first_word.len

With the pipeline operator ->, this reads left-to-right:

var text = "HELLO WORLD"
var first_word = (text
    -> .lower()
    -> .split(" ")
    -> .at(0))
var length = first_word.len   # .len is a field, not a call — pipelines need calls

Pipelines make data transformations flow naturally, like reading prose.

Note on multi-line pipelines: Zebra's tokenizer ends an expression at a bare end-of-line, so a multi-line pipeline must be wrapped in parentheses. Single-line pipelines (var r = 5 -> add(10) -> double()) don't need parens.

Basic Pipeline Syntax

The -> operator passes the left-hand value to the right-hand expression:

# file: 15_pipeline_basics.zbr
# teaches: pipeline operator
# chapter: 15-Pipelines-and-Function-Composition

def main()
    var text = "HELLO WORLD"

    # Without pipeline (nested calls)
    var result1 = text.lower().split(" ")

    # With pipeline (left-to-right) — multi-line needs parens
    var result2 = (text
        -> .lower()
        -> .split(" "))

    # Both are equivalent
    for word in result2
        print(word)

Notice how pipeline reads more naturally: "take text, lowercase it, split it". Each -> says "pass the result of the previous expression to this one".

Chaining Multiple Operations

Pipelines shine when you have many sequential transformations:

# file: 15_pipeline_chain.zbr
# teaches: chaining operations
# chapter: 15-Pipelines-and-Function-Composition

class StringProcessor
    static
        def process(text: str): str
            return (text
                -> .lower()
                -> .trim()
                -> .replace("  ", " "))

def main()
    var input = "  HELLO   WORLD  "
    var output = StringProcessor.process(input)
    print(output)  # Output: hello world

Each line applies one transformation. This is much clearer than deeply nested method calls.

Pipelines with Collections

Pipelines work great with lists and maps:

# file: 15_pipeline_collections.zbr
# teaches: piping through collections
# chapter: 15-Pipelines-and-Function-Composition

class DataProcessor
    static
        def count_words(text: str): int
            return (text
                -> .lower()
                -> .split(" ")
                -> .count())

def main()
    var input = "The Quick Brown Fox"
    var words = (input
        -> .lower()
        -> .split(" "))

    var count = words.count()
    print("Word count: ${count}")

Here, the pipeline takes a string, lowercases it, splits into a list, and we can call .count() on the result.

Custom Functions in Pipelines

You can pipe to any function that takes one argument:

# file: 15_pipeline_custom.zbr
# teaches: custom functions in pipelines
# chapter: 15-Pipelines-and-Function-Composition

class Utils
    static
        def double(x: int): int
            return x * 2

        def add_ten(x: int): int
            return x + 10

        def format_result(x: int): str
            return "Result: ${x}"

def main()
    var result = (5
        -> Utils.double()
        -> Utils.add_ten()
        -> Utils.format_result())

    print(result)  # Output: Result: 20

The pipeline auto-prepends the left-hand value as the first argument to the right-hand call. 5 -> Utils.double() becomes Utils.double(5). If the function takes more arguments, supply them in the parens: 5 -> Utils.add(10) becomes Utils.add(5, 10).

Real World: Data Transformation Pipeline

A practical example: process a CSV-like dataset:

# file: 15_pipeline_real_world.zbr
# teaches: realistic pipeline
# chapter: 15-Pipelines-and-Function-Composition

class DataAnalysis
    static
        def parse_numbers(line: str): List(int)
            var numbers: List(int) = List()
            var parts = line.split(",")
            for part in parts
                # Simplified: real parsing more complex
                var num = part.trim().toInt()
                numbers.add(num)
            return numbers

        def sum_list(items: List(int)): int
            var total = 0
            for item in items
                total = total + item
            return total

        def average(total: int, count: int): float
            if count == 0
                return 0.0
            return total / count

def main()
    var csv_line = "10, 20, 30, 40"

    var avg = (csv_line
        -> DataAnalysis.parse_numbers()
        -> DataAnalysis.sum_list()
        -> DataAnalysis.average(4))         # auto-prepends sum as first arg

    print("Average: ${avg}")

This reads as: "Parse CSV, sum values, calculate average." Much clearer than nested calls!

Function Composition Pattern

You can create composed functions that combine multiple operations:

# file: 15_function_composition.zbr
# teaches: composing functions
# chapter: 15-Pipelines-and-Function-Composition

class Transform
    static
        def lowercase(text: str): str
            return text.lower()

        def remove_spaces(text: str): str
            return text.replace(" ", "")

        def reverse_it(text: str): str
            return text.reverse()

        def compose_all(text: str): str
            return (text
                -> Transform.lowercase()
                -> Transform.remove_spaces()
                -> Transform.reverse_it())

def main()
    var input = "HELLO WORLD"
    var output = Transform.compose_all(input)
    print(output)  # Output: dlrowolleh

Each step is a self-contained function. Composition lets you reuse them in different orders.

Pipelines with Error Handling

Pipelines propagate errors naturally — if any step's throws function raises, the whole pipeline aborts and the error surfaces at the function boundary. Use a method-level catch clause to handle it:

# file: 15_pipeline_results.zbr
# teaches: pipelines with error handling
# chapter: 15-Pipelines-and-Function-Composition

class SafeParser
    static
        def parse_int(text: str): int throws
            if text.len == 0
                raise "Empty string"
            # NOTE: Hardcoded for demonstration. A real implementation would parse
            # the string into an integer. See Chapter 06 (Strings) for actual parsing.
            if text == "42"
                return 42
            raise "Not a number"

        def double_it(x: int): int
            return x * 2

def run(input: str)
    var doubled = (input
        -> SafeParser.parse_int()
        -> SafeParser.double_it())
    print(doubled)
catch |e|
    print("error: ${e}")

def main()
    run("42")               # prints 84
    run("not a number")     # prints "error: Not a number"

When an error occurs, the pipeline aborts and the method-level catch clause runs. The catch |e| block sits at the same indent level as def — that's the Zebra error-handling idiom (see Chapter 12).

Common Mistakes

Mistake 1: Piping to a Field, Not a Call

# WRONG — pipeline RHS must be a call expression
var result = (text
    -> .lower()
    -> .len)        # Error: .len is a field access, not a call

# CORRECT — finish the pipeline, then read the field
var lowered = text -> .lower()
var result = lowered.len

Mistake 2: Forgetting the Parens on a Multi-Line Pipeline

# WRONG — the expression ends at the first newline
var result = text
    -> .lower()             # parse error: unexpected token
    -> .split(" ")

# CORRECT — wrap the whole pipeline in parens
var result = (text
    -> .lower()
    -> .split(" "))

# Or write it on a single line (no parens needed):
var result = text -> .lower() -> .split(" ")

Mistake 3: Forgetting That the Pipe Becomes the First Argument

# Pipeline auto-prepends the left-hand value as the FIRST argument.
# So `10 -> Utils.add(5)` calls `Utils.add(10, 5)`, not `Utils.add(5, 10)`.

# Want 10 as the SECOND argument? Don't use a pipeline:
var result = Utils.add(5, 10)

Mistake 4: Over-Piping (Readability)

# TOO MUCH — hard to follow after many steps
var result = ("data"
    -> .lower()
    -> .trim()
    -> .replace("a", "b")
    -> .reverse()
    -> .split("")
    -> Filter.remove_blanks()
    -> Sorter.sort()
    -> Formatter.join_with_commas())

# BETTER — break into logical chunks with intermediate variables
var cleaned = ("data"
    -> .lower()
    -> .trim()
    -> .replace("a", "b"))

var processed = (cleaned
    -> .reverse()
    -> .split(""))

Exercises

Exercise 1: Text Processing Pipeline

Create a pipeline that takes user input and: converts to lowercase, removes leading/trailing spaces, and counts words:

class TextStats
    static
        def count_words(text: str): int
            if text.len == 0
                return 0
            var words = text.split(" ")
            return words.count()

def main()
    var user_input = "  HELLO WORLD FOO  "

    var word_count = (user_input
        -> .lower()
        -> .trim()
        -> TextStats.count_words())

    print("Words: ${word_count}")

Exercise 2: Number Transformation Pipeline

Build a pipeline that: parses an integer, doubles it, adds 10, and formats as a string:

class NumUtils
    static
        def parse_safe(text: str): int throws
            if text == "5"
                return 5
            raise "Invalid number"

        def double_it(x: int): int
            return x * 2

        def add_ten(x: int): int
            return x + 10

        def to_message(x: int): str
            return "Final result: ${x}"

def run(input: str)
    var final = (input
        -> NumUtils.parse_safe()
        -> NumUtils.double_it()
        -> NumUtils.add_ten()
        -> NumUtils.to_message())
    print(final)
catch |e|
    print("error: ${e}")

def main()
    run("5")               # prints "Final result: 20"
    run("not a number")    # prints "error: Invalid number"

Exercise 3: List Filtering Pipeline

Create a pipeline that filters a list of numbers to keep only even values and sums them:

class ListOps
    static
        def filter_even(items: List(int)): List(int)
            var result: List(int) = List()
            for item in items
                if item % 2 == 0
                    result.add(item)
            return result

        def sum_all(items: List(int)): int
            var total = 0
            for item in items
                total = total + item
            return total

def main()
    var numbers: List(int) = List()
    numbers.add(1)
    numbers.add(2)
    numbers.add(3)
    numbers.add(4)
    numbers.add(5)
    numbers.add(6)

    var sum = (numbers
        -> ListOps.filter_even()
        -> ListOps.sum_all())

    print("Sum of evens: ${sum}")

Key Takeaways

• Pipelines make data transformations read naturally — Left-to-right flow matches human thinking
• The -> operator passes results forward — The left value auto-prepends as the first argument of the right-hand call
• Pipelines work with methods and functions — Mix .method() calls with Function() calls
• Multi-line pipelines must be wrapped in (...) — Zebra ends an expression at a bare EOL; parens keep the chain together
• Break long pipelines into logical chunks — Maintain readability for complex transformations
• Pipelines + throws = clean error handling — A method-level catch clause handles errors anywhere in the chain

Next Steps

• → 16-Project-1 — Build a tool that uses pipelines extensively
• → 21-Regular-Expressions — Pipelines + pattern matching = powerful text processing

Pipelines let your code flow like your thoughts. Master them, and complex transformations become natural.

Project 1: Command-Line Text Processing Tool

Time: 3-4 hours
Prereq: 01-12
Build: A file processor that counts words, finds patterns, and analyzes text

Project Overview

Create a CLI tool that:

• Reads files from command line arguments
• Counts lines, words, characters (like Unix wc command)
• Searches for patterns (like grep-lite functionality)
• Outputs statistics
• Handles multiple files
• Reports errors gracefully

Learning Outcomes:

• Command-line argument parsing and validation
• File I/O with proper error handling
• Collections (List/HashMap) for data aggregation
• Algorithms for text analysis
• Error handling with throws, ? and catch
• Code organization in reusable modules
• Testing strategies for CLI tools

Difficulty: Intermediate | Skills Required: 1-12 chapters | Team Size: Solo

Step 1: Command-Line Argument Parsing

First, create a module to handle CLI arguments:

# file: cli_args.zbr
# teaches: argument parsing
# project: Project-1-CLI-Tool

class CliArgs
    var command: str
    var filename: str
    var pattern: str?

    cue init(command: str, filename: str)
        this.command = command
        this.filename = filename
        pattern = nil

class CommandParser
    static
        def parse(args: List(str)): CliArgs throws
            # Precondition: program name + command + filename
            if args.count() < 3
                raise "Usage: textool [command] [file]"

            var command = args.at(1)
            var filename = args.at(2)

            # Validate command
            if not valid_command(command)
                raise "Unknown command: ${command}"

            # Create args object
            var cli_args = CliArgs(command, filename)

            # Add pattern if provided
            if args.count() >= 4
                cli_args.pattern = args.at(3)

            return cli_args

        def valid_command(cmd: str): bool
            return cmd == "count" or cmd == "search" or cmd == "stats"

Step 2: File Reading and Basic Counting

Build the core file I/O and counting functionality. Every operation that can fail is marked throws; a caller writes ? after the call to pass the error up, so count_lines needs no error-handling code of its own:

# file: file_processor.zbr
# teaches: file I/O and text processing
# project: Project-1-CLI-Tool

class Stats
    var filename: str
    var lines: int
    var words: int
    var chars: int

    cue init(filename: str, lines: int, words: int, chars: int)
        this.filename = filename
        this.lines = lines
        this.words = words
        this.chars = chars

    def display(): str
        return "${lines} lines, ${words} words, ${chars} chars: ${filename}"

class FileProcessor
    static
        def read_file(filename: str): str throws
            # Check if file exists first
            if not File.exists(filename)
                raise "File not found: ${filename}"

            # Read the entire file
            var content = File.read(filename)

            if content.len == 0
                raise "File is empty: ${filename}"

            return content

        def count_lines(filename: str): int throws
            var content = read_file(filename)?
            var lines = content.split("\n")

            # Count non-empty lines (common behavior)
            var count = 0
            for line in lines
                if line.trim().len > 0
                    count = count + 1

            return count

        def count_words(filename: str): int throws
            var content = read_file(filename)?
            var words = content.split(" ")

            var count = 0
            for word in words
                if word.trim().len > 0
                    count = count + 1

            return count

        def count_chars(filename: str): int throws
            var content = read_file(filename)?
            return content.len

        def get_stats(filename: str): Stats throws
            var content = read_file(filename)?

            var lines = content.split("\n")
            var line_count = lines.count()
            var word_count = 0
            var char_count = content.len

            for line in lines
                var words = line.split(" ")
                for word in words
                    if word.len > 0
                        word_count = word_count + 1

            return Stats(filename, line_count, word_count, char_count)

Step 3: Pattern Matching

Add grep-like pattern search functionality. use file_processor exposing FileProcessor brings the class from Step 2 into scope by name:

# file: pattern_search.zbr
# teaches: pattern matching and filtering
# project: Project-1-CLI-Tool

use file_processor exposing FileProcessor, Stats

class PatternMatcher
    static
        def search_lines(filename: str, pattern: str): List(str) throws
            var content = FileProcessor.read_file(filename)?
            var lines = content.split("\n")

            var matches = List(str)()
            var line_num = 0

            for line in lines
                line_num = line_num + 1
                if line.contains(pattern)
                    # Format: "line_number: content"
                    matches.add("${line_num}: ${line}")

            if matches.count() == 0
                raise "No matches found for pattern: ${pattern}"

            return matches

        def search_with_context(filename: str, pattern: str, context_lines: int): List(str) throws
            var content = FileProcessor.read_file(filename)?
            var lines = content.split("\n")

            var results = List(str)()
            var line_num = 0

            for line in lines
                line_num = line_num + 1
                if line.contains(pattern)
                    # Add context lines before
                    var start = line_num - context_lines - 1
                    if start < 0
                        start = 0

                    var i = start
                    while i < line_num - 1
                        results.add(lines.at(i))
                        i = i + 1

                    # Add the matching line (with marker)
                    results.add("> ${line_num}: ${line}")

                    # Add context lines after
                    var end = line_num + context_lines
                    if end > lines.count()
                        end = lines.count()

                    i = line_num
                    while i < end
                        results.add(lines.at(i))
                        i = i + 1

            return results

Step 4: Main Application Logic

Tie everything together in the main entry point. main is where errors stop: its method-level catch clause (after the body, at the same indent as def) turns any error raised anywhere below into one printed line. Note if args.pattern as pattern — the optional is unwrapped and bound in one step:

# file: project1_main.zbr
# teaches: orchestrating modules
# project: Project-1-CLI-Tool

use cli_args exposing CliArgs, CommandParser
use file_processor exposing FileProcessor
use pattern_search exposing PatternMatcher

class Application
    var args: CliArgs

    cue init(parsed_args: CliArgs)
        args = parsed_args

    def run(): bool throws
        if args.command == "count"
            return handle_count()?
        else if args.command == "search"
            return handle_search()?
        else if args.command == "stats"
            return handle_stats()?

        raise "Unknown command: ${args.command}"

    def handle_count(): bool throws
        var lines = FileProcessor.count_lines(args.filename)?
        var words = FileProcessor.count_words(args.filename)?
        var chars = FileProcessor.count_chars(args.filename)?

        print("${lines} lines")
        print("${words} words")
        print("${chars} chars")

        return true

    def handle_search(): bool throws
        if args.pattern as pattern
            var matches = PatternMatcher.search_lines(args.filename, pattern)?
            print("Found ${matches.count()} matches:")

            for match in matches
                print(match)

            return true

        raise "Search requires a pattern"

    def handle_stats(): bool throws
        var stats = FileProcessor.get_stats(args.filename)?
        print(stats.display())
        return true

def main()
    var parsed = CommandParser.parse(sys.args())?
    var app = Application(parsed)
    app.run()?
catch |e|
    print("Error: ${e.message}")

Part 2: Adding Features

A throws method composes other throws methods with ?; the first failure ends the method and hands the error to the caller. At the top, an inline postfix catch supplies a fallback value instead of propagating:

use file_processor exposing FileProcessor

class FileAnalyzer
    static
        def analyze(filename: str): str throws
            var lines = FileProcessor.count_lines(filename)?
            var words = FileProcessor.count_words(filename)?
            return "Lines: ${lines}, Words: ${words}"

def main()
    print(FileAnalyzer.analyze("test.txt") catch "could not analyze test.txt")

Part 3: Full Implementation

Add these features:

• Read command-line arguments
• Support multiple files
• Pattern matching (grep-like)
• Output formatting
• Error handling

Expected functionality:

# Word count
tool -c file.txt          # Count lines
tool -w file.txt          # Count words
tool -l file.txt          # Get line length

# Search
tool -s "pattern" file.txt  # Search lines matching pattern

# Multiple files
tool -c file1.txt file2.txt # Count lines in multiple files

Testing Your Project

Create a test file to verify your implementation:

# Create sample file
echo "The quick brown fox" > sample.txt
echo "jumps over the lazy dog" >> sample.txt

# Test commands (with compile-and-run, the program's own arguments go after `--`)
zebra project1_main.zbr -- count sample.txt         # Count lines, words, chars
zebra project1_main.zbr -- search sample.txt quick  # Find pattern
zebra project1_main.zbr -- stats sample.txt         # Show statistics
zebra project1_main.zbr -- search sample.txt zzz    # Error: No matches found for pattern: zzz

Exercises & Extensions

Exercise 1: Add Line Numbering Output

Modify the search function to always show line numbers with output:

def search_with_numbers(filename: str, pattern: str): List(str) throws
    # Results already carry line numbers from PatternMatcher; `?` passes
    # any error straight through to our caller
    return PatternMatcher.search_lines(filename, pattern)?

Exercise 2: Find Longest Line

Add a new longest command that finds and displays the longest line:

class FileProcessor
    static
        def find_longest_line(filename: str): str throws
            var content: str = read_file(filename)?
            var lines = content.split("\n")
            var longest = ""
            var max_len = 0

            for line in lines
                if line.len > max_len
                    max_len = line.len
                    longest = line

            return "Longest (${max_len} chars): ${longest}"

Exercise 3: Statistics Summary

Extend stats to show min/max/average line length:

class Stats
    var filename: str
    var lines: int
    var words: int
    var chars: int
    var min_line_len: int
    var max_line_len: int
    var avg_line_len: float
    
    def display(): str
        var summary = "${lines} lines, ${words} words, ${chars} chars\n"
        return summary + "Line lengths: min=${min_line_len}, max=${max_line_len}, avg=${avg_line_len}"

Exercise 4: Case-Insensitive Search

Add support for a -i flag to search case-insensitively:

class PatternMatcher
    static
        def search_case_insensitive(filename: str, pattern: str): List(str) throws
            var content = FileProcessor.read_file(filename)?
            var lines = content.split("\n")
            var pattern_lower = pattern.lower()

            var matches = List(str)()
            var line_num = 0

            for line in lines
                line_num = line_num + 1
                if line.lower().contains(pattern_lower)
                    matches.add("${line_num}: ${line}")

            return matches

Challenge: Support Multiple Files

Modify the application to process multiple files at once. A file that cannot be read should be skipped rather than abort the whole run — catch nil turns the error into an optional, and if ... as keeps only the successes:

class Application
    var files: List(str)

    def aggregate_stats(filenames: List(str)): str
        var total_lines = 0
        var total_words = 0
        var total_chars = 0

        for filename in filenames
            var s = FileProcessor.get_stats(filename) catch nil
            if s as stats
                total_lines = total_lines + stats.lines
                total_words = total_words + stats.words
                total_chars = total_chars + stats.chars

        return "Total: ${total_lines} lines, ${total_words} words, ${total_chars} chars"

Key Concepts Reinforced

• File I/O — Reading files with error handling
• Collections — Using List to accumulate results
• Control flow — Iterating and filtering text
• Nil handling — Optional pattern argument
• Error handling — throws methods, ? propagation, catch at the boundary
• Classes — Organizing functionality into modules
• Strings — Splitting, searching, formatting
• Optionals — catch nil and if ... as to skip failures without aborting

Architecture Decisions

Module Organization:

• cli_args.zbr — Argument parsing (thin responsibility)
• file_processor.zbr — Core file I/O (stable, well-tested)
• pattern_search.zbr — Search logic (isolated from I/O)
• project1_main.zbr — Orchestration and CLI (thin coordinator)

Why this structure? Each module has a clear, testable responsibility. You can test file reading separately from pattern matching, and both separately from CLI handling.

Error Handling Strategy: Every I/O operation is throws, and every caller writes ?. Errors bubble up naturally—if file reading fails, search fails; if search fails, main's catch clause reports it. No hidden failures, and no error-checking code anywhere except the one place errors are actually handled.

Expected code size: 300-400 lines total with all exercises

What You've Built

✅ Real-world program structure with modules
✅ Complete file and stream processing
✅ Command-line interface with argument parsing
✅ Robust error handling with throws, ? and catch
✅ Pattern matching and text analysis
✅ Extensible design for new features

Performance Notes

For large files (>10MB), consider:

1. Reading line-by-line instead of entire file into memory
2. Early exit from search (stop after first N matches)
3. Streaming pattern matching instead of loading whole file

Example streaming read:

# Read and process line-by-line instead of all at once
def count_lines_streaming(filename: str): int throws
    # (Pseudocode - requires file iteration API)
    var count = 0
    # for line in File.read_lines(filename)
    #     count = count + 1
    return count

Next: Project 2 adds networking and concurrency concepts to build an HTTP server.

Projects 2 & 3: HTTP Server and Data Analysis

Project 2: HTTP Server (16-18 hours)

Build: A small REST API server that answers real HTTP requests with JSON

Learning Outcomes:

• Serving HTTP with the built-in Http.serve
• Routing on method and path, including a path parameter
• Producing and parsing JSON with Json
• Choosing status codes (200, 201, 400, 404, 405)
• Module-level state shared by a server's handlers
• What "one thread per connection" means for that state

Zebra's standard library already knows how to speak HTTP. Http.serve(port, handler) listens on a port, parses each request into an HttpRequest (method, path, content, and the raw query string), calls your handler, and writes the HttpResponse it returns back to the client. Your job is the part that is actually about your application: the data, and deciding which response each request gets.

The project is three files in one directory:

Step 1: The Data Model

# file: user_store.zbr
# teaches: module-level state, a small data model, JSON output
# project: Project-2-HTTP-Server

class User
    var id: int
    var name: str

    cue init(id: int, name: str)
        this.id = id
        this.name = name

    def toJson(): str
        var obj = Json.object()
        obj.putInt("id", this.id)
        obj.put("name", this.name)
        return Json.stringify(obj)

# One list shared by every function in this file (QUICKSTART §2.1).
var users = List(User)()
var next_id = 1

def addUser(name: str): User
    var user = User(next_id, name)
    users.add(user)
    next_id = next_id + 1
    return user

def findUser(id: int): User?
    for user in users
        if user.id == id
            return user
    return nil

def allUsersJson(): str
    var parts = List(str)()
    for user in users
        parts.add(user.toJson())
    return "[" + parts.join(",") + "]"

users and next_id are module-level variables: one value shared by every function in the file, so a user added by one request is visible to the next. Json.object() builds the JSON text for us, so a name containing a quote is escaped correctly without any hand-written string gymnastics.

Step 2: Request Routing

The router is a single function from HttpRequest to HttpResponse. The built-in HttpResponse has factories for the common cases — HttpResponse.ok(body) and HttpResponse.notFound(body) — and HttpResponse.new(status, body) for any other status code.

# file: router.zbr
# teaches: routing on method and path, path parameters, status codes
# project: Project-2-HTTP-Server

use user_store exposing addUser, findUser, allUsersJson

def route(req: HttpRequest): HttpResponse
    if req.path == "/health"
        return HttpResponse.ok("{\"status\": \"healthy\"}")

    if req.path == "/api/users"
        if req.method == "GET"
            return HttpResponse.ok(allUsersJson())
        if req.method == "POST"
            return createUser(req.content)
        return HttpResponse.new(405, "method not allowed")

    # /api/users/<id> -- a path parameter
    if req.path.startsWith("/api/users/") and req.method == "GET"
        # "/api/users/2".split("/") is ["", "api", "users", "2"].
        # Keep the ": str" -- without it, today's compiler mistypes the element.
        var idText: str = req.path.split("/").at(3)
        if findUser(idText.toInt()) as user
            return HttpResponse.ok(user.toJson())
        return HttpResponse.notFound("no user ${idText}")

    return HttpResponse.notFound("no route for ${req.method} ${req.path}")

def createUser(body: str): HttpResponse
    # Expect a JSON body like {"name": "Ada"}
    if Json.parse(body) as json
        var name = json.tryStr("name") orelse ""
        if name.len > 0
            return HttpResponse.new(201, addUser(name).toJson())
    return HttpResponse.new(400, "expected a JSON body like {\"name\": \"Ada\"}")

Every route is an if you can read top to bottom. Adding a route is adding a branch; there is no registration table to keep in sync.

Step 3: Starting the Server

# file: http_server.zbr
# teaches: starting a real server with Http.serve
# project: Project-2-HTTP-Server

use router exposing route

def main()
    print("Listening on http://localhost:8080  (Ctrl+C to stop)")
    Http.serve(8080, route)

Http.serve takes the port and the handler function, and never returns: it accepts connections until you stop the process.

Concurrency note. Http.serve handles each connection on its own thread, so requests can run at the same time. The users list has no lock around it, so two simultaneous POSTs could race. That is fine for trying the server out with one client at a time, as below; a production server would need to guard shared state.

Exercises

1. Add query parameter parsing: req.query holds the raw text after ? (e.g. name=Ada&limit=5); split it into key/value pairs and support GET /api/users?name=Ada
2. Complete the resource: add PUT /api/users/<id> (rename) and DELETE /api/users/<id>, returning 404 for an unknown id
3. Request logging: log each request (timestamp, method, path, response code)
4. Middleware: wrap route in a function that runs code before and after every request
5. Validation: reject names that are empty after .trim() or longer than 50 characters with a 400
6. Guard the shared state: make concurrent POSTs safe (see Chapter 14c)

Testing the Server

Run the three files from the same directory. The first build takes a little while; then the server prints its banner and waits:

$ zebra http_server.zbr
Listening on http://localhost:8080  (Ctrl+C to stop)

From a second terminal:

$ curl http://localhost:8080/health
{"status": "healthy"}

$ curl http://localhost:8080/api/users
[]

$ curl -X POST -d '{"name": "Ada"}' http://localhost:8080/api/users
{"id":1,"name":"Ada"}

$ curl -X POST -d '{"name": "Grace"}' http://localhost:8080/api/users
{"id":2,"name":"Grace"}

$ curl http://localhost:8080/api/users
[{"id":1,"name":"Ada"},{"id":2,"name":"Grace"}]

$ curl http://localhost:8080/api/users/2
{"id":2,"name":"Grace"}

$ curl -i http://localhost:8080/api/users/9
HTTP/1.1 404 Not Found
...
no user 9

$ curl -i -X DELETE http://localhost:8080/api/users
HTTP/1.1 405 Method Not Allowed
...
method not allowed

Use curl -i to see the status line and headers. (The runtime labels every response Content-Type: text/html; charset=utf-8, even when the body is JSON.)

Stop the server with Ctrl+C.

Project 3: Text Data Analysis (12-15 hours)

Build: Analyze text data (n-grams, frequencies, similarity) for linguistic patterns

Learning Outcomes:

• Advanced data structures (HashMap, nested structures)
• Algorithms (n-gram extraction, frequency analysis, similarity scoring)
• File batch processing
• Statistical analysis
• Performance optimization with data structures

Step 1: Frequency Analysis

Start with counting word frequencies:

# file: frequency_analysis.zbr
# teaches: frequency counting and sorting
# project: Project-3-Data-Analysis

class WordFrequency
    var word: str
    var count: int
    
    cue init(word: str, count: int)
        this.word = word
        this.count = count
    
    def to_string(): str
        return "${word}: ${count}"

class FrequencyAnalyzer
    static
        def analyze_text(text: str): List(WordFrequency)
            var words = text.lower().split(" ")
            var freq: HashMap(str, int) = HashMap()
            
            # Count occurrences
            for word in words
                var cleaned = word.trim()
                if cleaned.len > 0
                    if freq.contains(cleaned)
                        freq.put(cleaned, freq.fetch(cleaned) + 1)
                    else
                        freq.put(cleaned, 1)
            
            # Convert to list and sort by frequency
            var results: List(WordFrequency) = List()
            for word, count in freq
                var wf = WordFrequency(word, count)
                results.add(wf)
            
            # Simple bubble sort (in-place)
            var i = 0
            while i < results.count()
                var j = 0
                while j < results.count() - 1
                    var current = results.at(j)
                    var next = results.at(j + 1)
                    if current.count < next.count
                        # Swap (simplified)
                        var temp = current
                        results[j] = next
                        results[j + 1] = temp
                    j = j + 1
                i = i + 1
            
            return results
        
        def top_words(text: str, limit: int): List(WordFrequency)
            var all_freqs = analyze_text(text)
            var results: List(WordFrequency) = List()
            
            var i = 0
            while i < limit and i < all_freqs.count()
                results.add(all_freqs.at(i))
                i = i + 1
            
            return results

Step 2: N-gram Extraction

Extract contiguous sequences of N words:

# file: ngram_analysis.zbr
# teaches: n-gram extraction and pattern detection
# project: Project-3-Data-Analysis

class NGram
    var gram: str
    var count: int
    var positions: List(int)  # Track where it appears
    
    cue init(gram: str)
        this.gram = gram
        count = 1
        positions = List()

class NGramAnalyzer
    static
        def extract_ngrams(text: str, n: int): HashMap(str, NGram)
            var words = text.lower().split(" ")
            var ngrams: HashMap(str, NGram) = HashMap()
            
            var i = 0
            while i < words.count() - (n - 1)
                var gram = ""
                var j = 0
                while j < n
                    var word = words.at(i + j).trim()
                    if j > 0
                        gram = gram.concat(" ")
                    gram = gram.concat(word)
                    j = j + 1
                
                if ngrams.contains(gram)
                    var ng = ngrams.fetch(gram)
                    ng.count = ng.count + 1
                    ng.positions.add(i)
                else
                    var ng = NGram(gram)
                    ng.positions.add(i)
                    ngrams.put(gram, ng)
                
                i = i + 1
            
            return ngrams
        
        def top_ngrams(text: str, n: int, limit: int): List(NGram)
            var all_grams = extract_ngrams(text, n)
            var results: List(NGram) = List()
            
            # Simple sorting
            for gram, ng in all_grams
                results.add(ng)
            
            # Bubble sort by count
            var i = 0
            while i < results.count()
                var j = 0
                while j < results.count() - 1
                    var current = results.at(j)
                    var next = results.at(j + 1)
                    if current.count < next.count
                        var temp = current
                        results[j] = next
                        results[j + 1] = temp
                    j = j + 1
                i = i + 1
            
            # Return top N
            var top: List(NGram) = List()
            i = 0
            while i < limit and i < results.count()
                top.add(results.at(i))
                i = i + 1
            
            return top

Step 3: Similarity Analysis

Compare texts using Jaccard and other similarity metrics:

# file: similarity_analysis.zbr
# teaches: similarity metrics and comparison
# project: Project-3-Data-Analysis

class SimilarityMetrics
    static
        def jaccard_similarity(text1: str, text2: str): float
            var words1 = text1.lower().split(" ")
            var words2 = text2.lower().split(" ")
            
            # Find intersection
            var intersection = 0
            for word1 in words1
                for word2 in words2
                    if word1 == word2
                        intersection = intersection + 1
                        break
            
            # Size of the union (crude approximation)
            var total = words1.count() + words2.count() - intersection
            
            if total == 0
                return 0.0
            
            return intersection.toFloat() / total.toFloat()
        
        def cosine_similarity(text1: str, text2: str): float
            # Simplified cosine similarity (not true cosine, but similar)
            var words1 = text1.lower().split(" ")
            var words2 = text2.lower().split(" ")
            
            var common = 0
            for word1 in words1
                for word2 in words2
                    if word1 == word2
                        common = common + 1
            
            var len1 = words1.count()
            var len2 = words2.count()
            
            if len1 == 0 or len2 == 0
                return 0.0
            
            var denominator = len1 + len2
            return (2.0 * common.toFloat()) / denominator.toFloat()
        
        def hamming_distance(text1: str, text2: str): int
            var words1 = text1.lower().split(" ")
            var words2 = text2.lower().split(" ")
            
            var max_len = words1.count()
            if words2.count() > max_len
                max_len = words2.count()
            
            var distance = 0
            var i = 0
            while i < max_len
                var w1 = if(i < words1.count(), words1.at(i), "")
                var w2 = if(i < words2.count(), words2.at(i), "")
                
                if w1 != w2
                    distance = distance + 1
                
                i = i + 1
            
            return distance

Step 4: Main Analysis Application

Tie together all analysis tools:

# file: analysis_main.zbr
# teaches: combining analysis modules
# project: Project-3-Data-Analysis

use frequency_analysis exposing WordFrequency, FrequencyAnalyzer
use ngram_analysis exposing NGram, NGramAnalyzer

class TextAnalysisReport
    var source_file: str = ""
    var word_count: int = 0
    var unique_words: int = 0
    var top_words: List(WordFrequency) = List(WordFrequency)()
    var bigrams: List(NGram) = List(NGram)()
    var trigrams: List(NGram) = List(NGram)()

class AnalysisApplication
    static
        def analyze_file(filename: str): TextAnalysisReport throws
            # File.read is not `throws` -- a missing file stops the program --
            # so check first and raise an error the caller can catch.
            if not File.exists(filename)
                raise "File not found: ${filename}"

            var content = File.read(filename)
            if content.len == 0
                raise "File is empty: ${filename}"

            var words = content.split(" ")
            var unique_words_set: HashMap(str, int) = HashMap()

            for word in words
                var cleaned = word.lower().trim()
                if cleaned.len > 0
                    unique_words_set.put(cleaned, 1)

            var report = TextAnalysisReport()
            report.source_file = filename
            report.word_count = words.count()
            report.unique_words = unique_words_set.count()
            report.top_words = FrequencyAnalyzer.top_words(content, 10)
            report.bigrams = NGramAnalyzer.top_ngrams(content, 2, 5)
            report.trigrams = NGramAnalyzer.top_ngrams(content, 3, 5)

            return report

        def print_report(report: TextAnalysisReport)
            print("==== Text Analysis Report ====")
            print("File: ${report.source_file}")
            print("Total words: ${report.word_count}")
            print("Unique words: ${report.unique_words}")
            print("")

            print("Top 10 Words:")
            for wf in report.top_words
                print("  ${wf.to_string()}")
            print("")

            print("Top 5 Bigrams:")
            for bigram in report.bigrams
                print("  ${bigram.gram} (${bigram.count})")
            print("")

            print("Top 5 Trigrams:")
            for trigram in report.trigrams
                print("  ${trigram.gram} (${trigram.count})")

def main()
    var report = AnalysisApplication.analyze_file("sample.txt")
    AnalysisApplication.print_report(report)
catch |err|
    print("Error: ${err.message}")

Exercises

1. Find most common bigrams and trigrams — Already implemented in Step 2
2. Detect language patterns — Compare bigram distributions across texts
3. Compare two documents — Use similarity metrics from Step 3
4. Find suspicious passages — Identify sections with high similarity to other documents (plagiarism detection)
5. Build a frequency graph — Output word frequency distribution
6. Implement TF-IDF — Weight words by frequency and document uniqueness

Testing

Put the four files in one directory with a sample.txt next to them, then:

$ zebra analysis_main.zbr
==== Text Analysis Report ====
File: sample.txt
Total words: 15
Unique words: 11

Top 10 Words:
  the: 3
  quick: 2
  fox: 2
...

(That is the report for a sample.txt containing the quick brown fox jumps over the lazy dog and the quick red fox runs. Words with equal counts may come out in a different order.) Without a sample.txt the program prints Error: File not found: sample.txt.

Exercise 3 is where a compare_files.zbr comes from: write it yourself, using SimilarityMetrics from Step 3.

Project Comparison Summary

Capstone Challenge: Integrated System

After completing all three projects, combine them:

class IntegratedSystem
    static
        def run_analysis_via_http(port: int, analysis_dir: str)
            # Start HTTP server (Project 2)
            # Serve text analysis results (Project 3)
            # Process files via CLI (Project 1)
            
            # GET /health — Health check
            # POST /analyze — Upload and analyze file
            # GET /results — Retrieve analysis results
            # GET /compare — Compare two documents

This demonstrates:

• ✅ Networking and servers
• ✅ Complex data processing
• ✅ CLI integration
• ✅ Professional system design

Each project is a portfolio piece. Together, they demonstrate mastery of Zebra and modern programming fundamentals.

Project Comparison

Progressive Difficulty

1. CLI Tool: Learn file I/O and basic structure
2. HTTP Server: Add networking and concurrency concepts
3. Data Analysis: Deep dive into algorithms and data structures

Each project reuses concepts from previous ones while introducing new challenges.

Capstone Challenges

After completing all three:

1. Integrate CLI tool with HTTP server (serve file statistics)
2. Use data analysis in HTTP endpoints
3. Build a combined system processing files via HTTP

Expected Outcomes

✅ Real-world program architecture
✅ Network programming fundamentals
✅ Advanced data structure manipulation
✅ Practical error handling
✅ Performance considerations
✅ Testing strategies

Each project is a portfolio piece demonstrating Zebra mastery.

18b: Building GUI Applications

Audience: All — anyone who wants a window instead of a terminal Time: 120 minutes Prerequisites: 05-Control-Flow, 07-Classes-and-Instances, 07b-Structs-Unions-and-Value-Types You'll learn: The MVU (Model-View-Update) architecture, Gui.run, dispatching messages with g.send, laying out widgets with using g.vbox/g.hbox, the widget catalogue, forms, the native tree, drawing on a canvas, the embedded code editor, and how to test a GUI without ever opening a window

Version note: this chapter tracks Zebra 0.9.0-rc3 or newer. Trees, toolbars, g.scope, window-wide hotkeys (g.hotkey) and the g.area canvas all landed after 0.9.0-rc2 and are not in the rc1 or rc2 releases. A compiler built from the main branch after rc2 has them too, even though its zebra --version may still say rc2.

The Big Picture

Zebra's GUI is built on MVU — Model, View, Update — the architecture popularised by Elm. There is no widget tree for you to mutate, no callbacks firing at unpredictable times, and no onClick handler reaching into global state. There are three functions and one rule:

The rule: view may not modify the model. When the user does something, view sends a message; update is the only place state changes. That single constraint is what makes a GUI reasonable to think about — every possible state transition is a branch arm in one function you can read top to bottom.

If you have written a GUI before, the thing to unlearn is the callback. You will not write "when this button is clicked, do X." You will write "when this button is clicked, say that it was clicked," and separately, "when someone says the button was clicked, the new state is X."

Zebra runs the loop for you:

init() ──▶ model ──▶ view(g, model) ──▶ user clicks ──▶ g.send(Msg.foo)
                ▲                                              │
                └────────── update(model, Msg.foo) ◀───────────┘

Your First Window

Here is a complete, working program. Save it as counter.zbr:

# file: counter.zbr
# teaches: MVU, Gui.run, g.send, hbox layout
# chapter: 18b-GUI-Applications

struct Counter
    var count: int

union Msg
    inc
    dec
    reset

def init(): Counter
    return Counter(count: 0)

def update(m: Counter, msg: Msg): Counter
    branch msg
        on Msg.inc    return Counter(count: m.count + 1)
        on Msg.dec    return Counter(count: m.count - 1)
        on Msg.reset  return Counter(count: 0)

def view(g: Gui, m: Counter)
    g.text("Count: " + m.count.toString())
    g.separator()
    using g.hbox("##buttons", false)
        g.button("+", Msg.inc)
        g.button("-", Msg.dec)
        g.button("Reset", Msg.reset)

def main()
    Gui.run("Counter", 300, 160, init, update, view)

Run it with native OS controls:

zebra --gui-backend=libui_ng counter.zbr

A real window appears, with real Win32 / GTK3 / Cocoa buttons. Click + and the label updates.

What each piece is doing

• struct Counter is the Model. It holds everything the program knows. If it isn't in the model, view can't draw it.
• union Msg enumerates everything that can happen. Three variants, three things a user can do. This union is the complete vocabulary of your program's events — which is why reading it tells you what the program does.
• update takes the old state and a message and returns the new state. It never touches the screen.
• view takes the state and draws it. It never changes the state; each widget carries the message it sends when the user acts on it (g.button("+", Msg.inc)), and g.send(...) reports anything else.
• Gui.run wires them together and owns the event loop.

Notice that update returns a new Counter rather than modifying the old one. That's the immutable-update idiom from Chapter 07b, and it is the natural fit here: each message produces the next state, so the history of your program is a chain of values rather than a pile of mutations.

Running It: Two Backends and a Stub

The same source runs against several backends. You choose at the command line — the program does not change:

zebra --gui-backend=libui_ng counter.zbr   # native OS controls (recommended)
zebra counter.zbr                          # stub backend — see below

The terminal backend (--gui-backend=tui) is unavailable in current releases. It is built on the ZigZag library, which does not support Zig 0.17 yet, and the compiler refuses the flag by name, saying so. The notes on the TUI later in this chapter describe that backend for when it returns.

The compiler scaffolds a zig build project next to your source (counter_gui_libui_ng/) and builds it. The first build fetches and compiles the GUI library, so it takes a while; subsequent runs are fast.

The stub backend is your test harness

Run a GUI program with no --gui-backend flag at all and you get the stub backend: it runs exactly one frame, prints every widget it would have drawn to stderr, and exits.

$ zebra counter.zbr
[gui] text: Count: 0
[gui] ---
[gui] button: +
[gui] button: -
[gui] button: Reset

This is more useful than it looks. It means a GUI program is testable in CI — no display, no window manager, no clicking. You can assert on the widget tree the way you would assert on any other output. It is also the fastest way to check that a layout change did what you meant before waiting on a full native build.

Note: the stub never fires an event, so a single stub frame shows you the initial view. To exercise update, call it directly from a test (see Testing Your Update Function below) — not by sending a message unconditionally from view, which is a livelock (see Common Mistakes).

Messages That Carry Data

Not everything is a bare event. When the user types, the message needs to carry what they typed. Union variants can hold a payload:

# file: greeter.zbr
# teaches: payload messages, g.field, mixed unions
# chapter: 18b-GUI-Applications

struct Model
    var name: str
    var greeting: str

union Msg
    name_changed: str
    greet
    clear

def init(): Model
    return Model(name: "", greeting: "")

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.name_changed as newName
            return Model(name: newName, greeting: m.greeting)
        on Msg.greet
            if m.name.len == 0
                return Model(name: m.name, greeting: "Please type a name first.")
            return Model(name: m.name, greeting: "Hello, " + m.name + "!")
        on Msg.clear
            return Model(name: "", greeting: "")

def view(g: Gui, m: Model)
    g.text("What is your name?")
    g.field("##name", m.name, def(s: str): Msg = Msg.name_changed(s))
    using g.hbox("##row", false)
        g.button("Greet", Msg.greet)
        g.button("Clear", Msg.clear)
    g.separator()
    g.text(m.greeting)

def main()
    Gui.run("Greeter", 360, 200, init, update, view)

Two things to notice.

A payload comes from the widget. g.field(id, text, on) shows text and calls on with whatever the user typed; on builds the message, here Msg.name_changed(s) in call syntax. Receiving it uses a binding in the branch arm: on Msg.name_changed as newName. This is exactly the union pattern from Chapter 07b — the GUI adds no new concepts here.

A Msg union may mix payload and no-payload variants freely, as this one does. greet and clear carry nothing; name_changed carries a str.

Widgets That Carry Their Message

A button carries a message. A checkbox and a text entry carry a function that builds one, because the message needs the new value:

The model drives the widget: you pass the model's value in, and the widget reports a change by sending the message on returns. update stores it; the next render passes the stored value back in. Nothing is read out of a widget, so view never learns about a change before update does.

# file: widgets.zbr
# teaches: toggle, field, slider; the on function
# chapter: 18b-GUI-Applications

struct Model
    var loud: bool
    var volume: float
    var label: str

union Msg
    set_loud: bool
    set_volume: float
    set_label: str

def init(): Model
    return Model(loud: false, volume: 50.0, label: "untitled")

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.set_loud as v    return Model(loud: v, volume: m.volume, label: m.label)
        on Msg.set_volume as v  return Model(loud: m.loud, volume: v, label: m.label)
        on Msg.set_label as v   return Model(loud: m.loud, volume: m.volume, label: v)

def view(g: Gui, m: Model)
    g.toggle("Loud mode", m.loud, def(b: bool): Msg = Msg.set_loud(b))
    g.field("Label", m.label, def(s: str): Msg = Msg.set_label(s))
    g.slider("Volume", m.volume, 0.0, 100.0, def(v: float): Msg = Msg.set_volume(v))
    g.separator()
    g.text("volume=" + m.volume.toString() + " loud=" + m.loud.toString())

def main()
    Gui.run("Widgets", 380, 260, init, update, view)

Every widget that holds state has this shape: the model supplies the value the widget shows, and the on function names the message for a change. There is no widget that returns a value — so view never compares anything, and update is the only place the model changes. g.inputMultiline(label, text, on), g.combobox(label, items, selected, on) and g.spinbox(label, value, min, max, on) follow the same rule with def(s: str), def(i: int) and def(n: int).

So do the entries that look different but are not. g.password(label, text, on) and g.search(label, text, on) are g.field on a masked entry and a search-styled one; same def(s: str). g.radio(label, items, selected, on) is one radio button per item with exactly one selected; it reports the chosen index with def(i: int), like a combobox, but the choices are in the open instead of behind a click. g.comboboxEditable(label, items, text, on) is a drop-down the user can also type into — a recent-files list with "or enter your own" — and because what comes back is text, its on is def(s: str), not an index.

Layout

Widgets stack vertically by default. To place them side by side, put them in a horizontal box. Boxes nest, and using scopes them:

# file: layout.zbr
# teaches: using g.vbox / g.hbox, nesting, stretch
# chapter: 18b-GUI-Applications

struct Model
    var status: str

union Msg
    refresh

def init(): Model
    return Model(status: "ready")

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.refresh  return Model(status: "refreshed")

def view(g: Gui, m: Model)
    using g.vbox("##root", true)
        using g.hbox("##toolbar", false)
            g.button("Refresh", Msg.refresh)
            g.text("Status: " + m.status)
        g.separator()
        using g.hbox("##body", true)
            using g.vbox("##left", true)
                g.text("Left panel")
            using g.vbox("##right", true)
                g.text("Right panel")

def main()
    Gui.run("Layout", 480, 300, init, update, view)

That produces a toolbar row across the top and two panels side by side filling the rest of the window.

The two arguments

g.vbox(id, stretch) and g.hbox(id, stretch) both take:

• id — a unique string identifying this box. The backend creates the box on the first frame and reuses it thereafter, so the id must be stable across frames. Prefix with ## by convention: it marks the string as an identifier rather than a user-visible label.
• stretch — whether this box expands to fill the space available in its parent. A toolbar row is false (it should stay as short as its contents); a main content area is true.

using versus begin/end

using is the recommended form because the box closes itself at the end of the indented block — you cannot forget an endVBox. The explicit pair exists too:

g.beginHBox("##row", false)
    g.button("Left", Msg.left)
    g.button("Right", Msg.right)
g.endHBox()

Both compile to the same thing. Prefer using.

Gotcha: the using header and the first line of its body must be on adjacent lines — no blank line between them.

The Widget Catalogue

Widget identity comes from the label. A widget is matched to last render's widget of the same kind and label, in order — so two buttons labelled + are still two buttons. For a widget whose label you don't want displayed, use the ## prefix: g.field("##filepath", m.path, on).

A variant carries one payload. The check column's on gets two values, a row and a flag, and a union variant holds exactly one — so the message carries a small struct: struct Pick with row and checked, and def(row: int, checked: bool): Msg = Msg.pick_row(Pick(row: row, checked: checked)). The tree's onExpand is the same shape; you will see it below.

What is not there yet

Being honest about the edges, because discovering these by trial is unpleasant:

• Trees are a single text column. An icon from a built-in set, but no extra columns, no drag-and-drop, no in-place editing, and no keyboard on the TUI. A file browser that needs a size column is a table.
• Icons are bytes, not files. folder, file, dot and warn are painted by the runtime, and Gui.registerIcon takes your own RGBA pixels — but there is no image decoder yet, so a PNG is yours to decode. Buttons and table cells take no images at all.
• Drawing has no images, gradients or transforms. libui has them; they are not bound. (g.canvas covers the rest of the mouse and the keyboard — below.)
• g.sameLine(), g.spacing(), g.indent() are cosmetic no-ops on native backends — they belong to the immediate-mode style. Use an hbox.
• g.textColored renders the text but ignores the colour.
• Fixed pixel widths aren't supported; boxes divide space by stretch (g.minSize(id, w, h) gives a box a floor).

Forms

A settings dialog is two columns: labels on the left, lined up, and the controls on the right. g.beginForm(id) / g.endForm(id) lays its children out that way. Nothing else about the view changes. Each widget's own label becomes its row label, so g.field("Host name", ...) inside a form is a row called Host name.

# file: settings_form.zbr
# teaches: g.beginForm / g.endForm, a widget's label as its row label, m except
# chapter: 18b-GUI-Applications

struct Model
    var host: str
    var port: int
    var tls: bool

union Msg
    set_host: str
    set_port: int
    set_tls: bool

def init(): Model
    return Model(host: "localhost", port: 8080, tls: true)

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.set_host as s  return m except host = s
        on Msg.set_port as n  return m except port = n
        on Msg.set_tls as b   return m except tls = b

def view(g: Gui, m: Model)
    g.beginForm("settings")
    g.field("Host name", m.host, def(s: str): Msg = Msg.set_host(s))
    g.spinbox("Port", m.port, 1, 65535, def(n: int): Msg = Msg.set_port(n))
    g.toggle("Use TLS", m.tls, def(b: bool): Msg = Msg.set_tls(b))
    g.endForm("settings")
    g.separator()
    g.text(if(m.tls, "https://", "http://") + m.host + ":" + m.port.toString())

def main()
    Gui.run("Settings", 380, 220, init, update, view)

On the stub:

[gui] form: settings
[gui] input: Host name = localhost
[gui] spinbox: Port val=8080 [1,65535]
[gui] checkbox: Use TLS = true
[gui] ---
[gui] text: https://localhost:8080

Three things to notice.

The form is geometry, not behaviour. The three widgets inside it are the same field, spinbox and toggle from the catalogue, with the same on functions. Take the beginForm / endForm lines out and the program still works; it just stacks.

m except host = s is the struct-update idiom from Chapter 07b. widgets.zbr rebuilt the whole Model in every arm; with three fields that was tolerable, with ten it is not. except copies the model and changes one field.

A row may be conditional. Wrap a widget in if m.advanced and its row appears and disappears with the flag. The backend inserts and removes the row; you do not manage it.

On the TUI and the stub a form is a plain vertical box. Only the native backend has the two-column layout, which is why the stub output above looks like any other stack.

Trees

Every desktop has one native tree: a single text column with expanders, a selection, and a double-click. Windows' SysTreeView32 has no columns at all, so that is the subset Zebra binds — the same widget on Win32, GTK (GtkTreeView) and Cocoa (NSOutlineView).

The view emits the whole tree on every render. Between g.beginTree(...) and g.endTree():

• g.treeNode(key, label, expanded) opens a node; the calls that follow are its children, until g.treePop().
• g.treeLeaf(key, label) is a node with no children.

key is the app's stable name for the node — a path is the natural key. The backend diffs by key from one render to the next, so the tree is not rebuilt when a label changes.

The part to get right is expansion. An expander click does not open the node. It sends onExpand(key, open); update puts the key into (or out of) the model; the next render passes expanded: true for that key, and that opens it. The model owns what is open. So "Open all" is not a special tree operation — it is a message like any other, and update sets the list.

onExpand gets two values, a key and a flag, and a variant carries one — so the message carries a small struct, Toggle, exactly as the table's check column did.

# file: file_tree.zbr
# teaches: g.beginTree / treeNode / treeLeaf / treePop / endTree, the model owns what is open
# chapter: 18b-GUI-Applications

struct Toggle
    var key: str
    var open: bool

struct Model
    var open: List(str)
    var selected: str

union Msg
    select: str
    expand: Toggle
    open_all
    close_all

def init(): Model
    var open: List(str) = ["src"]
    return Model(open: open, selected: "")

def isOpen(m: Model, key: str): bool
    for k in m.open
        if k == key
            return true
    return false

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.select as k
            return m except selected = k
        on Msg.expand as t
            var out: List(str) = []
            for k in m.open
                if k != t.key
                    out.add(k)
            if t.open
                out.add(t.key)
            return m except open = out
        on Msg.open_all
            var all: List(str) = ["src", "docs"]
            return m except open = all
        on Msg.close_all
            var none: List(str) = []
            return m except open = none

def view(g: Gui, m: Model)
    g.beginTree("files", def(k: str): Msg = Msg.select(k), def(k: str): Msg = Msg.select(k), def(k: str, o: bool): Msg = Msg.expand(Toggle(key: k, open: o)))
    g.treeNode("src", "src/", isOpen(m, "src"))
    g.treeLeaf("src/main.zbr", "main.zbr")
    g.treeLeaf("src/Parser.zbr", "Parser.zbr")
    g.treePop()
    g.treeNode("docs", "docs/", isOpen(m, "docs"))
    g.treeLeaf("docs/README.md", "README.md")
    g.treePop()
    g.treeLeaf("build.zbr", "build.zbr")
    g.endTree()
    g.text("selected: " + m.selected)
    using g.hbox("##buttons", false)
        g.button("Open all", Msg.open_all)
        g.button("Close all", Msg.close_all)

def main()
    Gui.run("Files", 320, 320, init, update, view)

On the stub:

[gui] beginTree: files
[gui] tree d=0 v src/ (src)
[gui] tree d=1 - main.zbr (src/main.zbr)
[gui] tree d=1 - Parser.zbr (src/Parser.zbr)
[gui] tree d=0 > docs/ (docs)
[gui] tree d=1 - README.md (docs/README.md)
[gui] tree d=0 - build.zbr (build.zbr)
[gui] text: selected: 
[gui] button: Open all
[gui] button: Close all

Read v as an open node, > as a closed one, - as a leaf, and d= as the depth. src is open because init put it in the list; docs is closed. Nothing in view decided that — isOpen only reads the model.

g.beginTree takes three functions after the id: onSelect and onActivate are def(key: str): Msg, sent on selection and on double-click; onExpand is def(key: str, open: bool): Msg. This program does not distinguish a double-click from a click, so both build Msg.select.

The treePop() calls are the tree's structure: src/ has two leaves and then pops, docs/ has one and pops, and build.zbr is at the root. Miss a pop and everything after it becomes a child of the wrong node. The stub's d= column is the quickest way to check.

Drawing

g.area(id, w, h, draw, on) is a canvas: Direct2D on Windows, Cairo on GTK, CoreGraphics on macOS. draw paints it; on is the message for a mouse press.

draw is different from every other function in this chapter: the toolkit calls it at paint time, not view. By then view has returned and m is gone. So the closure starts with a capture block that copies what it needs out of the model. The runtime keeps those captured bytes and repaints only when they change — a message that alters a captured value repaints the area, one that does not, does not.

# file: board.zbr
# teaches: g.area, a draw closure with capture, the mouse-press message
# chapter: 18b-GUI-Applications

struct Model
    var cells: List(bool)

union Msg
    press: int
    clear

def init(): Model
    var cells: List(bool) = [false, false, false, false, false, false, false, false, false]
    return Model(cells: cells)

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.press as cell
            var out: List(bool) = []
            var i = 0
            for c in m.cells
                out.add(if(i == cell, not c, c))
                i += 1
            return Model(cells: out)
        on Msg.clear
            return init()

def view(g: Gui, m: Model)
    g.area("board", 240, 240, def(c: Gui)
        capture
            var cells: List(bool) = m.cells
        var side = 240.0
        var k = 80.0
        c.fillRect(0.0, 0.0, side, side, 0xFAFAF0)
        c.line(k, 0.0, k, side, 0x333333, 2.0)
        c.line(k * 2.0, 0.0, k * 2.0, side, 0x333333, 2.0)
        c.line(0.0, k, side, k, 0x333333, 2.0)
        c.line(0.0, k * 2.0, side, k * 2.0, 0x333333, 2.0)
        var i = 0
        for filled in cells
            if filled
                var cx = (i % 3).toFloat() * k + k / 2.0
                var cy = (i / 3).toFloat() * k + k / 2.0
                c.fillCircle(cx, cy, 28.0, 0x2A6EBB)
            i += 1
    , def(x: float, y: float, button: int): Msg = if(button == 1, Msg.press((y / 80.0).toInt() * 3 + (x / 80.0).toInt()), Msg.clear))
    g.button("Clear", Msg.clear)

def main()
    Gui.run("Board", 300, 320, init, update, view)

A left click on a cell toggles it; any other button clears the board. On the stub the draw closure runs once and prints its verbs:

[gui] area: board 240x240
[gui] fillRect (0,0) 240x240 #fafaf0
[gui] line (80,0)-(80,240) #333333 t=2.0
[gui] line (160,0)-(160,240) #333333 t=2.0
[gui] line (0,80)-(240,80) #333333 t=2.0
[gui] line (0,160)-(240,160) #333333 t=2.0
[gui] button: Clear

No circles, because every cell starts false.

Some things to know:

• The block-lambda shape. A multi-line closure is def(c: Gui) on the call line, its body indented under it, and then , on a line of its own to start the next argument. The capture block comes first inside the body.
• Coordinates are the area's own pixels, origin top-left; w and h are a minimum size, and c.canvasWidth() / c.canvasHeight() tell you what you actually got.
• Colours are 0xRRGGBB; a float is written with a point (2.0, not 2).
• The verbs: line(x1, y1, x2, y2, colour, thickness), rect(x, y, w, h, colour, thickness), fillRect(x, y, w, h, colour), circle(cx, cy, r, colour, thickness), fillCircle(cx, cy, r, colour), drawText(x, y, s, colour, size) with size 0 meaning the control font. Outside a draw closure they do nothing.
• The press goes through update like everything else. on turns a coordinate into a cell index and that into a message; view never looks at the mouse.

The TUI shows a placeholder where the area would be.

The rest of the mouse, and the keyboard

g.area reports a press and nothing else. g.canvas(id, w, h, draw, onMouse, onKey) is the same surface with the whole story: onMouse(ev, x, y, b) is called with ev 1 for a press, 2 for a release, 3 for a move (b is the buttons held, so a drag is a move with b != 0), 4 when the pointer enters and 5 when it leaves; onKey(vk, mods, down) gets keys once the canvas has focus (a click gives it), in the same vocabulary as g.hotkey — letters as uppercase ASCII, arrows 0x25–0x28. Every event is a message, which is the point: a draggable dot is three arms of update.

# file: canvas.zbr
# teaches: g.canvas, mouse move/release and keys as messages, a drag in update
# chapter: 18b-GUI-Applications

struct Model
    var x: float
    var y: float
    var dragging: bool

struct Ev
    var ev: int
    var x: float
    var y: float
    var b: int

struct Key
    var vk: int
    var mods: int
    var down: bool

union Msg
    mouse: Ev
    key: Key

def init(): Model
    return Model(x: 60.0, y: 60.0, dragging: false)

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.mouse as e
            var dx: float = e.x - m.x
            var dy: float = e.y - m.y
            if e.ev == 1 and dx * dx + dy * dy < 400.0
                return m except dragging = true
            if e.ev == 2
                return m except dragging = false
            if e.ev == 3 and m.dragging
                return m except x = e.x, y = e.y
            return m
        on Msg.key as k
            if not k.down
                return m
            if k.vk == 0x25
                return m except x = m.x - 10.0
            if k.vk == 0x27
                return m except x = m.x + 10.0
            return m

def view(g: Gui, m: Model)
    g.canvas("dot", 240, 160, def(c: Gui)
        capture
            var px: float = m.x
            var py: float = m.y
            var drag: bool = m.dragging
        c.fillRect(0.0, 0.0, c.canvasWidth(), c.canvasHeight(), 0xF4F4F4)
        c.fillCircle(px, py, 20.0, if(drag, 0xE05020, 0x2060C0))
    , def(ev: int, x: float, y: float, b: int): Msg = Msg.mouse(Ev(ev: ev, x: x, y: y, b: b)), def(vk: int, mods: int, down: bool): Msg = Msg.key(Key(vk: vk, mods: mods, down: down)))

def main()
    Gui.run("Canvas", 260, 220, init, update, view)

Two closures carry structs because a variant holds one payload (the same reason as the check column above). Note that the colour while dragging is not set anywhere in view — the draw closure captured dragging, so the press that flipped it also repainted.

Tooltips, Icons and the Clipboard

Three small things that separate a working app from a finished one.

g.tooltip(text) gives the widget emitted just before it a hover text. It is a statement about the previous line, so it reads like a caption:

g.button("Copy", Msg.copy)
g.tooltip("Copy the text above to the system clipboard")

The clipboard has no widget to hang on, so it is two statics on Gui, and they belong in update, where the model changes:

# file: clipboard.zbr
# teaches: g.tooltip, Gui.clipboardText / setClipboardText, treeNodeIcon / treeLeafIcon
# chapter: 18b-GUI-Applications

struct Model
    var text: str
    var pasted: str
    var picked: str

union Msg
    set_text: str
    copy
    paste
    pick: str

def init(): Model
    return Model(text: "hello from zebra", pasted: "", picked: "")

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.set_text as s
            return m except text = s
        on Msg.copy
            Gui.setClipboardText(m.text)
            return m
        on Msg.paste
            return m except pasted = Gui.clipboardText()
        on Msg.pick as k
            return m except picked = k

def view(g: Gui, m: Model)
    g.field("Text", m.text, def(s: str): Msg = Msg.set_text(s))
    g.tooltip("What Copy puts on the clipboard")
    using g.hbox("##row", false)
        g.button("Copy", Msg.copy)
        g.tooltip("Copy the text above to the system clipboard")
        g.button("Paste", Msg.paste)
        g.tooltip("Read the system clipboard into the line below")
    g.text("pasted: " + m.pasted)
    g.beginTree("files", def(k: str): Msg = Msg.pick(k), def(k: str): Msg = Msg.pick(k), def(k: str, o: bool): Msg = Msg.pick(if(o, k, k)))
    g.treeNodeIcon("src", "src/", true, "folder")
    g.treeLeafIcon("src/main.zbr", "main.zbr", "file")
    g.treeLeafIcon("src/todo", "unsaved", "warn")
    g.treePop()
    g.treeLeafIcon("build", "build", "dot")
    g.treeLeaf("plain", "no icon")
    g.endTree()
    g.tooltip("Icons come from the built-in set")
    g.text("picked: " + m.picked)

def main()
    Gui.run("Clipboard", 340, 360, init, update, view)

Msg.copy writes the model's text to the clipboard and returns the model unchanged; Msg.paste reads the clipboard into the model, and view shows it. On the stub both are a process-local string, so a copy followed by a paste prints what was copied; on a desktop the round trip crosses the operating system's clipboard, and what you paste may have come from another program.

treeNodeIcon and treeLeafIcon are treeNode and treeLeaf with one more argument, an icon name. Four are painted by the runtime (folder, file, dot, warn), and the program can add its own: Gui.registerIcon(name, w, h, rgba) takes straight-alpha RGBA bytes in a str — w * h * 4 of them, which StringBuilder.appendChar(n) assembles a byte at a time or a raw file supplies — and the name then works wherever a built-in one does. Register in main before Gui.run (registrations are queued until the toolkit is up) or from update. Any unregistered name draws nothing. Zebra has no image decoder yet, so a PNG is the program's to decode; when one exists, a path will slot in beside the bytes.

On the stub:

[gui] tooltip: What Copy puts on the clipboard
[gui] tree d=0 v src/ (src) [folder]
[gui] tree d=1 - main.zbr (src/main.zbr) [file]

The TUI ignores tooltips and icons; it has nowhere to hover and no cell to draw in.

Toolbars

A menubar is fixed when the window is created, which is why the menus are declared in every render and the first one wins. A toolbar is the other kind of strip: it lives under the menubar (GTK and Windows) or in the title bar (macOS, where the platform keeps them), its items carry icons, and it can change -- an item may be enabled by the model, and the set itself may grow and shrink between renders. The verbs mirror the menus with those two differences:

# file: toolbar.zbr
# teaches: g.beginToolbar / tool / toolIcon / toolSeparator / toolEnabled, a toolbar that follows the model
# chapter: 18b-GUI-Applications

struct Model
    var running: bool
    var log: str
    var clicks: int

union Msg
    build
    run
    stop
    clear

def init(): Model
    return Model(running: false, log: "idle", clicks: 0)

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.build
            return m except log = "built", clicks = m.clicks + 1
        on Msg.run
            return m except running = true, log = "running", clicks = m.clicks + 1
        on Msg.stop
            return m except running = false, log = "stopped", clicks = m.clicks + 1
        on Msg.clear
            return m except log = "", clicks = 0

# a 12x12 filled square, straight-alpha RGBA
def square(r: int, g: int, b: int): str
    var sb = StringBuilder()
    var i: int = 0
    while i < 144
        sb.appendChar(r)
        sb.appendChar(g)
        sb.appendChar(b)
        sb.appendChar(255)
        i = i + 1
    return sb.build()

def view(g: Gui, m: Model)
    g.beginToolbar()
    g.toolIcon("Build", "hammer", "Compile the project", Msg.build)
    g.toolIcon("Run", "go", "Run the tests", Msg.run)
    g.toolEnabled(m.running)
    g.tool("Stop", Msg.stop)
    if m.clicks > 0
        g.toolSeparator()
        g.toolIcon("Clear", "warn", "Clear the log", Msg.clear)
    g.endToolbar()
    g.text("state: " + m.log)
    g.text("clicks: " + m.clicks.toString())

def main()
    Gui.registerIcon("hammer", 12, 12, square(0x60, 0x60, 0xC0))
    Gui.registerIcon("go", 12, 12, square(0x2E, 0xB8, 0x4E))
    Gui.run("toolbar", 420, 160, init, update, view)

g.tool(label, msg) is a button in the strip; g.toolIcon(label, icon, tip, msg) adds an icon -- a built-in name or one from Gui.registerIcon, exactly as for the tree -- and a tooltip. g.toolEnabled(b) applies to the next item and then resets, so g.toolEnabled(m.running) followed by the Stop item is the whole of "Stop is only clickable while something runs". A g.toolSeparator() is an item too, which keeps the indices the runtime uses stable.

The strip is compared with the last render's: the same labels, icons and tooltips in the same order means the runtime updates it in place (refreshing which message each item sends, pushing any enabled change); anything else rebuilds it. So the Clear item appearing after the first click costs one rebuild, and nothing in the program has to know that.

On the stub each item prints as [gui] tool: Build [hammer]; the TUI shows a row of buttons.

The Code Editor

Zebra ships a real code editor widget — the libui-ng backend embeds Scintilla, the editing component behind Notepad++ and SciTE. This is what makes it practical to write a development tool in Zebra.

# file: editor.zbr
# teaches: CodeEditor, class Model, widget handles
# chapter: 18b-GUI-Applications

class Model
    var editor: CodeEditor? = nil
    var status: str = "ready"

union Msg
    save
    clear

def init(): Model
    var m = Model()
    m.editor = CodeEditor.forZebra()
    m.editor!.setText("def main()\n    print(\"hi\")\n")
    return m

def update(m: Model, msg: Msg): Model
    branch msg
        on Msg.save
            var text = m.editor!.getText()
            m.status = "saved " + text.len.toString() + " bytes"
        on Msg.clear
            m.editor!.setText("")
            m.status = "cleared"
    return m

def view(g: Gui, m: Model)
    using g.vbox("##root", true)
        using g.hbox("##bar", false)
            g.button("Save", Msg.save)
            g.button("Clear", Msg.clear)
            g.text(m.status)
        m.editor!.render(g, "##editor", 0, 0)

def main()
    Gui.run("Editor", 520, 360, init, update, view)

The editor's methods:

Why this Model is a class

Every other example in this chapter used struct Model. This one uses class, and the reason is worth understanding.

A CodeEditor is a handle to a live widget that owns a text buffer. It has identity: there is one actual editor on screen, and the model needs to refer to that one, not to a copy of it. Structs are value types — passing one to update copies it — so a struct model would hand update a copy whose field mutations are thrown away. A class is a reference type, so m.editor!.setText("") in update reaches the editor the user is looking at.

The rule of thumb:

• Pure data model (numbers, strings, lists) → struct, and return a new one from update. Cleaner, and the immutability is genuinely useful.
• Model owning widget handles or OS resources → class, mutate in place, return m.

Testing Your Update Function

update is a pure function from (Model, Msg) to Model. That means it is ordinary code, and you can test it without a GUI at all:

def test_inc()
    var m = init()
    var m2 = update(m, Msg.inc)
    assert m2.count == 1
    var m3 = update(m2, Msg.inc)
    assert m3.count == 2

def test_reset()
    var m = update(Counter(count: 41), Msg.reset)
    assert m.count == 0

Put the tests in the same file as init and update and run zebra test counter.zbr: it runs every def test_*() function (the test_ prefix is how it finds them) and reports 2 passed, 0 failed.

This is the practical payoff of the MVU constraint. In a callback-based GUI, the logic that changes state is tangled into event handlers and can only be exercised by driving the UI. Here, all of it lives in one pure function that takes a value and returns a value.

For the view side, the stub backend gives you the widget tree as text, which you can capture and assert on.

Common Mistakes

❌ Mistake: Mutating the model in view

def view(g: Gui, m: Model)
    m.count = m.count + 1         # ❌ view must not change state
    g.text("Count: ${m.count}")

✅ Fix: Let a widget send a message and let update do it.

def view(g: Gui, m: Model)
    g.button("Add", Msg.inc)      # ✅
    g.text("Count: ${m.count}")

With a struct model the compiler stops you outright — the parameter is not mutable. With a class model it will compile and appear to work, then desynchronise from update in ways that are miserable to debug. Treat the discipline as real even when the compiler doesn't enforce it.

❌ Mistake: Sending a message unconditionally from view

def view(g: Gui, m: Model)
    g.send(Msg.tick)                   # ❌ every render queues a message …
    g.text("ticks: ${m.ticks}")        #    … and a queued message causes a render

✅ Fix: A message comes from an event — a widget, or a subscription.

def view(g: Gui, m: Model)
    g.every(1000, Msg.tick)            # ✅ once a second, while the view says so
    g.text("ticks: ${m.ticks}")

view runs after an event: a click, a change, a timer. An unconditional g.send in view is a livelock; the runtime drops it after a few passes with a warning. No widget returns a value, so there is nothing in view to compare; a g.send there is almost always a mistake.)

❌ Mistake: Reusing a widget id

g.field("Name", m.first, onFirst)   # ❌ both entries carry the id "Name"
g.field("Name", m.last, onLast)

✅ Fix: Give each a unique id; hide the label with ## if you don't want it shown.

g.field("##first", m.first, onFirst)
g.field("##last", m.last, onLast)

❌ Mistake: Expecting sameLine() to work

g.sameLine() is an immediate-mode idea and does nothing on native backends. Use using g.hbox(...). The same goes for g.spacing() and g.indent().

❌ Mistake: Expecting an expander click to open the node

g.treeNode("src", "src/", false)     # ❌ always closed: the click only sends onExpand

✅ Fix: Pass the model's answer. The click sends onExpand(key, open), update records it, and the next render opens the node.

g.treeNode("src", "src/", isOpen(m, "src"))   # ✅

The same rule as every other widget: the model drives it. A tree whose expanded is a constant never moves, however much you click.

Real World: the Zebra IDE

The largest GUI program written in Zebra is the Zebra IDE (github.com/torial/zebra-ide, src/ide.zbr): a lightweight IDE for Zebra, C and Zig, written in this chapter's idiom and talking to zebra lsp and zebra debug. It is worth reading once you have the basics, because it is every idea above at full scale:

• A class Model holding a BufferSet of open documents -- each tab is a CodeEditor handle -- plus read-only editors for the Build, Tests and Debugger panes; the References, Symbols and Problems panes are tables.
• A Msg union of some forty-five variants: bare events (save_file, build), payload-carrying ones (jump_ref: int, open_path: str, toggle_dir: str), and tick.
• A menubar (g.beginMenu), a toolbar (g.beginToolbar) whose debug items follow the session and whose tail is the project's own tools from its manifest, a project explorer, tabs, a find bar of fields whose messages run the jump / open / find / rename, and the keyboard shortcuts claimed with g.hotkey so that Ctrl+S saves with the focus anywhere in the window -- view pops the claimed chords with g.takeKey() and sends each as its message.
• Long-running work without blocking the loop: the compiler, the gates and the language server run as processes, and a g.every(100, Msg.tick) subscription delivers Msg.tick; update drains what has arrived into the model, and view shows it.

That last pattern is how you integrate long-running work into MVU: something outside the loop produces, a subscription turns "time passed" into a message, and update moves the result into the model.

Exercises

Exercise 1: A Temperature Converter

Build a window with one input for Celsius and a label showing Fahrenheit.

• Model: the Celsius text and the converted value.
• Msg: one payload variant carrying the new text.
• Use .toFloat() to parse, and handle the case where the text isn't a number.

Hint: one g.field with an on function and one g.text is the whole of view.

Exercise 2: A Todo List

Model a list of tasks, each with a description and a done flag.

• Msg needs at least: add: str, toggle: int, remove: int.
• view draws an hbox per task: a checkbox and a "Delete" button.
• Every task's widgets need unique ids — derive them from the index, e.g. "##done" + i.toString().

The number of tasks changes between renders, and each task creates widgets. That is fine: the runtime inserts and removes widgets as the view changes, so a conditional or growing layout needs no special handling. Run it on the stub backend first and read the widget tree.

Exercise 3: Test It Without a Window

Take your todo list and write update tests — def test_*() functions, run with zebra test — that add three tasks, toggle the second, remove the first, and assert the resulting model. Do not open a window.

If that felt easy, you have understood why MVU is worth the constraint.

Summary

• MVU is three functions: init builds the state, update changes it, view draws it. Only update may change state.
• g.send(msg) is how view reports that something happened.
• A Msg union is the complete vocabulary of events in your program; it may mix payload and no-payload variants.
• Layout is nested using g.vbox / g.hbox, with stable ##ids and a stretch flag. Layout may change between renders — conditional rows and boxes are inserted and removed for you.
• Stateful widgets are driven by the model: pass the value in, and the on function names the message for a change. No widget returns a value.
• Forms lay labels left and controls right; the tree is a single column whose open set lives in the model; g.area is a canvas whose draw closure captures what it paints.
• g.tooltip captions the widget before it; the clipboard is two Gui statics called from update; tree icons come from a small painted set.
• CodeEditor embeds Scintilla; a model that owns widget handles should be a class, not a struct.
• The stub backend prints the widget tree and exits, which makes GUI programs testable without a display.
• The same source runs on native controls or on the stub — chosen by a command-line flag (the terminal backend returns when its library supports Zig 0.17).

Chapter 19: Standard Library Tour

Time: 90 min | Audience: Intermediate | Prerequisites: Chapters 01-06

Learning Outcomes

After this chapter, you will:

• Know the major modules and APIs in Zebra's standard library
• Understand when to use built-in functions vs. writing your own
• Navigate API documentation effectively
• Use string, collection, math, and system operations fluently
• Recognize patterns you can apply to your own libraries

Overview: What's Already Built

Zebra ships with a comprehensive standard library organized into builtin modules. Each module is available without importing — just use it by name.