# Saga

> Saga is a statically typed functional language with algebraic effects and handlers, compiling to the BEAM (Erlang VM).

Saga targets the Erlang BEAM and ships with effects-based concurrency, supervision, error handling, and testing as language features. The links below organize the language guide, BEAM-specific topics, and worked example programs.

## Guide

- [Language Tour](https://saga-lang.org/guide/tour.md): A quick overview of everything Saga offers, in one page.
- [Installation](https://saga-lang.org/guide/installation.md): Install Erlang, the Saga compiler, and set up your editor.
- [Getting Started](https://saga-lang.org/guide/getting-started.md): Your first Saga program, basic commands, and a quick taste of the language.
- [Basics](https://saga-lang.org/guide/basics.md): Bindings, primitive types, operators, blocks, strings, and pipes.
- [Functions](https://saga-lang.org/guide/functions.md): Definitions, annotations, pub/private, lambdas, currying, and composition.
- [Types](https://saga-lang.org/guide/types.md): ADTs, records, tuples, type parameters, opaque types, and dictionaries.
- [Pattern Matching](https://saga-lang.org/guide/pattern-matching.md): Case expressions, guards, destructuring, list/record/string patterns, and exhaustiveness.
- [Control Flow](https://saga-lang.org/guide/control-flow.md): do...else for sequential pattern binding, and list comprehensions.
- [Traits](https://saga-lang.org/guide/traits.md): Type-driven dispatch with Show, Eq, Ord. where clauses, supertraits, and deriving.
- [Effects & Handlers](https://saga-lang.org/guide/effects-and-handlers.md): Declaring effects, performing with !, writing handlers, resume, and abort.
- [Error Handling](https://saga-lang.org/guide/error-handling.md): The Fail effect, to_result, Result vs Fail philosophy, panic, and catch_panic.
- [Handler Patterns](https://saga-lang.org/guide/handler-patterns.md): Named, inline, let-bound, and factory handlers. Stacking, ordering, and the return clause.
- [Advanced Effects](https://saga-lang.org/guide/advanced-effects.md): Row polymorphism, effect signatures on higher-order functions, subtyping, and multishot continuations.
- [Testing](https://saga-lang.org/guide/testing.md): Effect-based testing with describe, test, handler swapping, and CI integration.
- [Project & Modules](https://saga-lang.org/guide/modules.md): Project layout, project.toml configuration, module declarations, imports, pub visibility, and qualified access.
- [Ecosystem](https://saga-lang.org/guide/ecosystem.md): Hex, git, and path dependencies. saga install, the lockfile, transitive deps, NIF compilation with rebar3, and the dep cache.

## BEAM Platform

- [Concurrency & Actors](https://saga-lang.org/guide/concurrency.md): The Actor effect: spawn, send, receive. Isolation and message passing on the BEAM.
- [Supervision](https://saga-lang.org/guide/supervision.md): Supervision as a handler pattern. Restart strategies, backoff, and let-it-crash.
- [BitStrings](https://saga-lang.org/guide/bitstrings.md): Binary construction, pattern matching, segment specifiers, and Std.BitString.
- [Refs](https://saga-lang.org/guide/refs.md): Atomic references for controlled mutable state. When to use refs vs recursion.
- [Interop](https://saga-lang.org/guide/interop.md): Calling Erlang, Hex dependencies, git deps, and project.toml configuration.

## Reference

- [Generic Deriving](https://saga-lang.org/guide/generic-deriving.md): Make your own traits derivable. The Generic representation, building-block instances, and the rules a derivable trait must follow.

## Examples

- [Hello World](https://saga-lang.org/examples/hello-world.md): The simplest Saga program.
- [Binary Search Tree](https://saga-lang.org/examples/binary-search-tree.md): A functional BST with insert, contains, and in-order traversal using ADTs and recursion.
- [Validation with Error Accumulation](https://saga-lang.org/examples/validation.md): Collect all validation errors instead of stopping at the first one, using continuations.
- [File I/O](https://saga-lang.org/examples/file-io.md): Reading, writing, and deleting files with the File effect and ADT error types.
- [Async Tasks](https://saga-lang.org/examples/async.md): Spawning concurrent tasks and collecting results with the Async effect.
- [Supervisor](https://saga-lang.org/examples/supervisor.md): Automatic retry with a limit using the supervised handler pattern.
- [N-Queens Solver](https://saga-lang.org/examples/nqueens.md): Backtracking search using Choose + Fail effects with multishot continuations.
- [Ambient Context](https://saga-lang.org/examples/ambient-context.md): Request-scoped values and audit logs as effects, replacing argument plumbing and the Reader/Writer monads.

## Optional

- [Syntax reference](https://saga-lang.org/syntax-reference.md): Compact cheatsheet of all language syntax. Useful as a minimal LLM context when the full guide is too much.
- [Full reference](https://saga-lang.org/llms-full.txt): All guides and worked examples concatenated as a single markdown document.
- [Standard library](https://saga-lang.org/stdlib): Generated API reference for the Saga standard library.
- [GitHub repository](https://github.com/dylantf/saga): Compiler source, issue tracker, and the raw `examples/` directory of short feature demos.