lux/docs/guide/01-introduction.md

# Chapter 1: Introduction to Lux

Welcome to Lux, a functional programming language where side effects are first-class citizens.

## Why Lux?

Every program does more than compute. It reads files, makes network requests, prints output, handles errors. In most languages, these *effects* are invisible—a function's type doesn't tell you what it might do.

Lux changes this. Effects are:
- **Visible** in the type signature
- **Controllable** via handlers
- **Composable** without boilerplate

This isn't just academic. It means:
- Tests can swap real I/O for mocks—automatically
- Error handling is explicit, not exceptional
- Dependencies are injected through the type system

## Installation

### From Source (Cargo)

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

# Add to PATH
export PATH="$PATH:$(pwd)/target/release"
```

### With Nix

```bash
# Enter development shell
nix develop

# Or build
nix build
./result/bin/lux
```

### Verify Installation

```bash
$ lux --version
Lux 0.1.0

$ lux --help
Usage: lux [OPTIONS] [FILE]

Options:
  -c, --check    Type check without running
  --lsp          Start LSP server
  --repl         Start interactive REPL
  -h, --help     Print help
```

## Your First Program

Create a file called `hello.lux`:

```lux
// hello.lux - Your first Lux program

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

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

Run it:

```bash
$ lux hello.lux
Hello, Lux!
```

Let's break this down:

### The Function Signature

```lux
fn main(): Unit with {Console}
```

- `fn main()` - A function named `main` with no parameters
- `: Unit` - Returns `Unit` (like `void`)
- `with {Console}` - **Uses the Console effect**

That last part is key. The type tells us this function prints to the console. A function without `with {...}` is *pure*—it can only compute.

### The Body

```lux
Console.print("Hello, Lux!")
```

`Console.print` is an *effect operation*. It's not a regular function—it's a request to the environment to print something.

### Running Effects

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

The `run ... with {}` expression executes a computation with its effects. The `{}` means "use the default handlers for all effects." Console's default handler prints to stdout.

## The REPL

Lux has an interactive mode:

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

>
```

Try some expressions:

```
> 1 + 2
3

> "Hello, " + "World"
"Hello, World"

> [1, 2, 3]
[1, 2, 3]

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

Define functions:

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

> square(5)
25

> fn greet(name: String): Unit with {Console} = Console.print("Hi, " + name)
<function>

> run greet("Alice") with {}
Hi, Alice
```

REPL commands:

```
:help     - Show help
:type e   - Show type of expression
:quit     - Exit REPL
:clear    - Clear screen
```

## A Slightly Bigger Program

Let's write a program that asks for your name:

```lux
// greet.lux

fn askName(): String with {Console} = {
    Console.print("What's your name?")
    Console.readLine()
}

fn main(): Unit with {Console} = {
    let name = askName()
    Console.print("Hello, " + name + "!")
}

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

```bash
$ lux greet.lux
What's your name?
> Alice
Hello, Alice!
```

Notice how:
- `askName` returns `String` but has `with {Console}` because it does I/O
- Both functions declare their effects
- The `run` at the end provides the runtime

## Pure vs Effectful

Here's the key insight. Compare:

```lux
// Pure - no effects, only computes
fn add(a: Int, b: Int): Int = a + b

// Effectful - uses Console
fn printSum(a: Int, b: Int): Unit with {Console} =
    Console.print(toString(a + b))
```

You can call `add` from anywhere. But `printSum` can only be called from:
1. Another function that declares `Console`
2. Inside a `run ... with {}` block

This is the effect discipline. Effects propagate up until handled.

## What's Next

Now that you can run programs, let's learn:

- [Chapter 2: Basic Types](02-basic-types.md) - Numbers, strings, booleans
- [Chapter 3: Functions](03-functions.md) - Definitions, closures, composition
- [Chapter 4: Data Types](04-data-types.md) - ADTs and pattern matching

Or jump ahead to what makes Lux special:

- [Chapter 5: Effects](05-effects.md) - The core innovation