# Tutorials

Learn Lux by building real projects.

## Standard Programs

These tutorials cover common programming tasks:

| Tutorial | What You'll Build | Concepts |
|----------|-------------------|----------|
| [Calculator](calculator.md) | REPL calculator | Parsing, evaluation, REPL loop |
| [Todo App](todo.md) | CLI task manager | File I/O, data structures |
| [HTTP Client](http-client.md) | API consumer | HTTP effects, JSON parsing |
| [Word Counter](word-counter.md) | Text analyzer | File reading, string ops |

## Effect Showcases

These tutorials demonstrate Lux's unique effect system:

| Tutorial | What You'll Learn | Key Concept |
|----------|-------------------|-------------|
| [Dependency Injection](dependency-injection.md) | Testing with mock handlers | Handler swapping |
| [State Machines](state-machines.md) | Modeling state transitions | Custom effects |
| [Effects Cookbook](effects-cookbook.md) | Common effect patterns | Handler patterns |

## Quick Start: Your First Project

### 1. Create Project Directory

```bash
mkdir my-first-lux
cd my-first-lux
```

### 2. Create Main File

```lux
// main.lux

fn main(): Unit with {Console} = {
    Console.print("Welcome to my Lux project!")
    Console.print("Enter your name:")
    let name = Console.readLine()
    Console.print("Hello, " + name + "!")
}

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

### 3. Run It

```bash
lux main.lux
```

### 4. Add a Module

```lux
// lib/greetings.lux

pub fn hello(name: String): String =
    "Hello, " + name + "!"

pub fn goodbye(name: String): String =
    "Goodbye, " + name + "!"
```

```lux
// main.lux
import lib/greetings as greet

fn main(): Unit with {Console} = {
    Console.print("Enter your name:")
    let name = Console.readLine()
    Console.print(greet.hello(name))
    Console.print(greet.goodbye(name))
}

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

## Project Ideas by Difficulty

### Beginner

- **Temperature converter** - Convert between Celsius, Fahrenheit, Kelvin
- **Number guessing game** - Random number with hints
- **Simple quiz** - Multiple choice questions with scoring
- **Unit converter** - Length, weight, volume conversions

### Intermediate

- **Markdown previewer** - Parse basic Markdown to HTML
- **Contact book** - CRUD with file persistence
- **Simple grep** - Search files for patterns
- **CSV processor** - Read, filter, transform CSV files

### Advanced

- **Test framework** - Use effects for test isolation
- **Config loader** - Effect-based configuration with validation
- **Mini interpreter** - Build a small language
- **Chat client** - HTTP-based chat application

### Effect Showcases

- **Transaction system** - Rollback on failure
- **Capability security** - Effects as capabilities
- **Async simulation** - Model async with effects
- **Dependency graph** - Track and inject dependencies

## How to Use These Tutorials

1. **Read through first** - Understand the goal
2. **Type the code** - Don't copy-paste
3. **Experiment** - Modify and see what happens
4. **Build your own** - Apply concepts to your ideas

## Getting Help

- Check the [Language Reference](../reference/syntax.md)
- See [examples/](../../examples/) for working code
- Use the REPL to experiment

Happy building!