Learn Aura

This book teaches Aura the way a programmer tends to actually learn a language: by writing short programs that do something real, then extending them until the pieces fit together.

Each chapter introduces one part of the language through a program that would make sense to run. By the end of the track you will have built command-style tools, domain models, text parsers, concurrent worker pools, subprocess runners, and small network services, and you will have met the language rules that keep those programs honest.

The Three Questions Aura Wants You To Ask

Programs in Aura tend to be easier to read when three questions are answered near the code.

Who owns this value? Small things copy — numbers, booleans, durations, queue handles. Binding one to a new name is cheap and both names keep working. Everything else moves: strings, collections, class instances, files, processes, task groups, network resources. Assignment hands ownership over. (A task handle sits in between: it copies when its result can be read more than once.) At a call boundary the signature tells you which it is — a bare parameter shares, own transfers.

Can this call fail? Failure that a caller might sensibly handle lives in the return type. Result[T, E], Option[T], QueueReceive[T], TaskResult[T], and the I/O and process error enums let a program handle each failure at the line where it matters.

What closes this resource? Files, network sockets, subprocess pipes, supervisors, and task groups should normally live inside a with block. The block is what runs cleanup — on normal exit and on runtime errors that unwind through it. with is how you turn "please remember to close this" into "this closes itself."

The Shape Of An Aura Program

A complete script:

class Point:
    x: float64
    y: float64

def distance(point: Point) -> float64:
    return sqrt((point.x * point.x) + (point.y * point.y))

point = Point(x=3.0, y=4.0)
print(distance(point))

Several ideas are already visible. Point is a class with named fields. distance only reads its argument, so the bare parameter grants shared access and the caller keeps the point. print renders a value and adds a newline. The script runs top to bottom; no main is required.

Run it with:

aura run examples/classes/point_distance.au

What This Track Covers

The chapters are ordered so that each idea has a practical reason to exist before the formal rules arrive.

1. Getting Aura Running — install the CLI, run your first program, build your first binary.
2. Aura For Python Developers — the fast track: what transfers from Python, and what will surprise you.
3. The First Program — bindings, functions, control flow, and small decisions made with match.
4. Shaping Data — classes, enums, methods, and the patterns that keep domain data honest.
5. Working With Collections — list[T], dict[K, V], set[T], eager owned comprehensions, owned list/str slices, and fixed shape numeric Array[T] values.
6. Converting Between Types — as, .to_float(), parsing text, and why nothing converts implicitly.
7. Values, Moves, And Borrows — the ownership model, explained through the programs that benefit from it.
8. Results, Options, And try — how Aura represents recoverable failure without hiding control flow.
9. Testing — writing tests, reading a failed assertion, parameterized cases, and CI output.
10. Organizing Code — splitting a program into files, packages, and workspaces.
11. Structured Concurrency — TaskGroup, Task[T], Queue[T], cancellation, and worker pools.
12. Talking To The World — files, processes, sockets, HTTP, and supervisors.
13. Running And Shipping — when to use run, when to use build, and what the native binary gives you.
14. Calling A Small C API — package-authorized FFI v0 for fixed-width values, temporary byte views, and opaque handles.

Three case studies put the pieces together:

• Log Analyzer — a text-processing tool with parsing, aggregation, and a report.
• Queue Worker Pool — a structured-concurrency pattern that shuts down cleanly.
• Supervised Process Runner — a small service supervisor with a restart policy and an event stream.

Reading The Manual Alongside Learn

Each Learn chapter ends by pointing at the matching Manual section. When a rule is surprising or a contract needs checking, go straight to the reference:

• Types
• Ownership And Borrowing
• Collections
• Numeric Arrays
• Concurrency
• Process Module
• Foreign Function Interface (FFI) v0
• API Index

The Manual is deliberately less chatty than Learn. It says what a thing is, not why you might want it.