lux/docs/README.md

# Lux Documentation

**Lux** is a functional programming language with first-class algebraic effects. It combines the safety of static typing with the flexibility of effect handlers, letting you write pure code that can do impure things—without losing control.

## Quick Links

| I want to... | Go to... |
|--------------|----------|
| Try Lux in 5 minutes | [Quick Start](#quick-start) |
| Learn Lux systematically | [The Lux Guide](guide/01-introduction.md) |
| Understand effects | [Effects Guide](guide/05-effects.md) |
| Look up syntax | [Language Reference](reference/syntax.md) |
| See the standard library | [Standard Library](reference/stdlib.md) |
| Build something | [Tutorials](tutorials/README.md) |

---

## Quick Start

### Install

```bash
# Clone and build
git clone https://github.com/your-org/lux
cd lux
cargo build --release

# Or with Nix
nix build
```

### Hello World

Create `hello.lux`:

```lux
fn main(): Unit with {Console} =
    Console.print("Hello, World!")

let output = run main() with {}
```

Run it:

```bash
lux hello.lux
# Output: Hello, World!
```

### The REPL

```bash
$ lux
Lux v0.1.0 - Type :help for commands

> 1 + 2 * 3
7

> fn square(x: Int): Int = x * x
<function>

> square(5)
25

> List.map([1, 2, 3], fn(x: Int): Int => x * 2)
[2, 4, 6]
```

---

## What Makes Lux Different?

### 1. Effects Are Explicit

In most languages, a function can do anything—print, crash, launch missiles—and the type doesn't tell you. In Lux, side effects are tracked:

```lux
// This function ONLY does math—the type guarantees it
fn add(a: Int, b: Int): Int = a + b

// This function uses Console—you can see it in the signature
fn greet(name: String): Unit with {Console} =
    Console.print("Hello, " + name)
```

### 2. Effects Are Handleable

Effects aren't just tracked—they're *values* you can intercept and redefine:

```lux
effect Logger {
    fn log(msg: String): Unit
}

fn compute(): Int with {Logger} = {
    Logger.log("Starting")
    let result = 42
    Logger.log("Done")
    result
}

// Run with console logging
handler consoleLogger: Logger {
    fn log(msg) = {
        Console.print("[LOG] " + msg)
        resume(())
    }
}

let result = run compute() with { Logger = consoleLogger }
```

### 3. Handlers Can Resume

Unlike exceptions, effect handlers can *continue* the computation:

```lux
effect Ask {
    fn ask(question: String): String
}

fn survey(): Unit with {Ask, Console} = {
    let name = Ask.ask("What's your name?")
    let color = Ask.ask("Favorite color?")
    Console.print(name + " likes " + color)
}

// Handler that provides answers
handler autoAnswer: Ask {
    fn ask(q) =
        if String.contains(q, "name") then resume("Alice")
        else resume("blue")
}

run survey() with { Ask = autoAnswer }
// Output: Alice likes blue
```

---

## Documentation Structure

### [The Lux Guide](guide/01-introduction.md)
A sequential guide to learning Lux, from basics to advanced topics.

1. [Introduction](guide/01-introduction.md) - Why Lux, installation, first program
2. [Basic Types](guide/02-basic-types.md) - Int, String, Bool, functions
3. [Functions](guide/03-functions.md) - Definitions, closures, higher-order
4. [Data Types](guide/04-data-types.md) - ADTs, pattern matching, records
5. [Effects](guide/05-effects.md) - The core innovation
6. [Handlers](guide/06-handlers.md) - Defining and using handlers
7. [Modules](guide/07-modules.md) - Code organization, imports
8. [Error Handling](guide/08-errors.md) - Fail effect, Option, Result
9. [Standard Library](guide/09-stdlib.md) - Built-in functions
10. [Advanced Topics](guide/10-advanced.md) - Traits, generics, optimization

### [Language Reference](reference/syntax.md)
Complete syntax and semantics reference.

- [Syntax](reference/syntax.md) - Grammar and syntax rules
- [Types](reference/types.md) - Type system details
- [Effects](reference/effects.md) - Effect system reference
- [Standard Library](reference/stdlib.md) - All built-in functions

### [Tutorials](tutorials/README.md)
Project-based learning.

**Standard Programs:**
- [Calculator](tutorials/calculator.md) - Basic REPL calculator
- [Todo App](tutorials/todo.md) - File I/O and data structures
- [HTTP Client](tutorials/http-client.md) - Fetching web data

**Effect Showcases:**
- [Dependency Injection](tutorials/dependency-injection.md) - Testing with effects
- [State Machines](tutorials/state-machines.md) - Modeling state with effects
- [Parser Combinators](tutorials/parsers.md) - Effects for backtracking

---

## Project Ideas

Once you've learned the basics, try building:

### Beginner
- **Unit converter** - Temperatures, distances, weights
- **Word counter** - Count words, lines, characters in files
- **Quiz game** - Random questions with scoring

### Intermediate
- **Markdown parser** - Parse and render Markdown
- **Task manager** - CLI todo list with file persistence
- **API client** - Fetch and display data from a REST API

### Advanced
- **Effect-based testing framework** - Use effects for test isolation
- **Configuration DSL** - Effect-based config with validation
- **Interpreter** - Build a small language interpreter

### Showcasing Effects
- **Transactional file system** - Rollback on failure using effects
- **Mock HTTP for testing** - Swap real HTTP with mock handlers
- **Async simulation** - Model concurrency with effect handlers
- **Capability-based security** - Effects as capabilities

---

## Philosophy

Lux is designed around these principles:

1. **Explicitness over magic** - Effects in the type signature, not hidden
2. **Composition over inheritance** - Effects combine freely
3. **Safety with escape hatches** - Type safety by default, but practical
4. **Functional core, imperative shell** - Pure logic, effectful boundaries

---

## Getting Help

- **REPL**: Type `:help` for commands
- **LSP**: Full IDE support in VS Code, Neovim
- **Examples**: See `examples/` directory
- **Issues**: Report bugs on GitHub

---

*Lux: Where effects are first-class citizens.*