# The Loup Scripting Book

**Covers:** Loup 1.25 (toolchain 1.25.1) and the Loup Language Reference, the four v1.20 volumes as amended through 1.25 ([core](../../specs/loup-language-core-v1_20.md), [runtime](../../specs/loup-language-runtime-v1_20.md), [compilation](../../specs/loup-language-compilation-v1_20.md), [data](../../specs/loup-language-data-v1_20.md)). Section references such as §1-2.4 point into those volumes: the first number is the volume.

This book teaches Loup through scripts: files you run with `loup run`, with no build step and no project, that are fully type-checked before the first line executes. By the end you will be able to write the small tools you would otherwise write in Python, Ruby or a shell script — file processing, data conversion, command-line utilities — and know when to turn a script into a compiled program.

## A Script in Thirty Seconds

```loup
@mode(host.scripted)

# Count the words in a file (or in a built-in sample) and show the top three.
let argv = args();
let text = if (argv.length() > 0) { readText(argv[0]) } else { "the cat sat on the mat and the dog sat too" };

var counts: dict[string, int] = {};
for (word in text.split(" ")) {
    let w = word.trim().toLowerCase();
    if (w.length() == 0) {
        continue;
    }
    counts[w] = (counts.get(w) ?? 0) + 1;
}

var ranked = counts.entries();
ranked.sort(func(a: (string, int), b: (string, int)) => b.1 - a.1);

for ((word, n) in ranked.slice(0, 3)) {
    println(i"{$ word $}: {$ n $}");
}
```

Save it as `wordcount.lpscr` and run it:

```sh
loup run wordcount.lpscr notes.txt
```

With no argument it counts its built-in sample:

```text
the: 3
sat: 2
cat: 1
```

No manifest, no build step, and the compiler still checks every type: pass `readText` a number, or forget that `counts.get` returns an `Option`, and the script is rejected before it touches the file.

## Who This Book Is For

You write scripts: automation, data wrangling, small command-line tools, glue between programs. You have programmed in some language before; you do not need to know anything about Loup, WebAssembly or systems programming.

## The Modes, and Where This Book Fits

Every Loup source file declares an execution mode on its first line. There are six:

| Mode | Extension | What it is for | Book |
|---|---|---|---|
| `@mode(host.scripted)` | `.lpscr` | Scripts: top-level statements run in order by `loup run` | **this book** |
| `@mode(host.dual)` | `.loup` | Programs with a `main()` that run under `loup run` or compile to Wasm or native code | this book (Chapters 1 and 18), [The Loup Native Book](../loup-native/README.md) |
| `@mode(host.native)` | `.lphc` | Native binaries | [The Loup Native Book](../loup-native/README.md) |
| `@mode(web.scripted)`, `@mode(web.compiled)` | `.lpweb` | Browser applications (no browser runtime ships yet) | [The Loup Web Book](../loup-web/README.md) |
| `@mode(freestanding)` | `.lpfree` | Kernels, bootloaders, firmware | [The Loup Freestanding Book](../loup-freestanding/README.md) |

Every listing in this book starts with `@mode(host.scripted)` (on the website, later listings in a chapter may hide that line), and script files use the `.lpscr` extension. When a script becomes a program, it moves to `host.dual`: a `.loup` file whose code lives in `main()`. Chapter 1 shows the move and Chapter 18 does it for a complete tool.

In Loup 1.25, `loup run` type-checks a script and runs it on an interpreter on your operating system — Linux, macOS or Windows. The Language Reference describes a JIT that compiles scripts to WebAssembly and can run on JavaScript hosts; that is not what ships, and this book describes what does.

## What Works in Scripts Today

- Static types with inference; `int`, `float`, `string`, `bool`, `char`, `bytes`, lists, dicts, sets, tuples, `Option` and `Result`
- Functions, closures, default and named arguments, generators
- Structs, enums with `match`, classes with inheritance, interfaces, generics, operator overloading
- Exceptions (`throw`, `try`/`catch`/`finally`), `Result` with `?`, and `attempt`
- Modules and imports; projects with an `.lppkg` manifest
- Interpolated strings and template fences
- `async`/`await` (executed eagerly and in order today; see Chapter 13)
- The ownership verbs (`reads`, `edits`, `takes`, `shares`), `modifier` methods and `safe` blocks
- A standard library with files, processes, paths, JSON, CSV, TOML, YAML, regular expressions, time and an HTTP server
- `loup test` with `debug.assert`

Some chapters describe parts of the language that the 1.25 toolchain does not implement yet. They are marked:

> ⚠ **Planned — not in Loup 1.25.** …

Chapters 14 (reflection), 15 (reactive UI) and 17 (JavaScript interop) are design previews in their entirety; their listings show the intended design and are not verified. Inside the other chapters, a single unimplemented feature gets a short "⚠ Planned" note instead of a runnable listing.

## Table of Contents

### Part I: Getting Started
1. [Getting Started](ch01-getting-started.md)
2. [Variables and Data Types](ch02-variables-and-data-types.md)
3. [Functions and Closures](ch03-functions-and-closures.md)
4. [Control Flow](ch04-control-flow.md)
5. [Collections](ch05-collections.md)

### Part II: Shaping Data
6. [Structs](ch06-structs.md)
7. [Enums and Pattern Matching](ch07-enums-and-pattern-matching.md)
8. [Classes and Objects](ch08-classes-and-objects.md)
9. [Interfaces and Generics](ch09-interfaces-and-generics.md)

### Part III: Programs at Scale
10. [Error Handling](ch10-error-handling.md)
11. [Modules and Packages](ch11-modules-and-packages.md)
12. [Strings, Interpolation, and Template Fences](ch12-strings-interpolation-templates.md)

### Part IV: Dynamic and Asynchronous
13. [Concurrency](ch13-concurrency.md)
14. [Reflection and Dynamic Compilation](ch14-reflection.md) ⚠ Planned
15. [Reactive UI](ch15-reactive-ui.md) ⚠ Planned

### Part V: Shipping Scripts
16. [Testing](ch16-testing.md)
17. [JavaScript Host Interop](ch17-js-host-interop.md) ⚠ Planned
18. [Building Script Tools](ch18-building-script-tools.md)
19. [Memory Safety and Resource Management](ch19-memory-safety-and-resources.md)

## Installing Loup and Running the Examples

Official builds come from [`code-craft-ai-company/loup-releases`](https://github.com/code-craft-ai-company/loup-releases/releases). On Linux and macOS:

```sh
curl -fsSL https://github.com/code-craft-ai-company/loup-releases/releases/latest/download/loup-install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://github.com/code-craft-ai-company/loup-releases/releases/latest/download/loup-install.ps1 | iex
```

The installer puts the toolchain in `~/.loup` (or `%LOCALAPPDATA%\Programs\Loup`) and adds it to your `PATH`; Chapter 1 has the details. Then save a listing as `example.lpscr` and run it:

```sh
loup run example.lpscr
```

Scripts get file-system, process and secure-random access by default; network access needs `--allow-net` (Chapter 1, "Permissions"). If a listing spans several files, the text says how to lay them out.

Every runnable listing in this book has been checked with the Loup 1.25.1 toolchain. Listings marked as errors show the compiler's or the runtime's real output.

Ready? Start with [Chapter 1](ch01-getting-started.md).