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, runtime, compilation, data). 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
@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:
loup run wordcount.lpscr notes.txt
With no argument it counts its built-in sample:
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 |
@mode(host.native) |
.lphc |
Native binaries | The Loup Native Book |
@mode(web.scripted), @mode(web.compiled) |
.lpweb |
Browser applications (no browser runtime ships yet) | The Loup Web Book |
@mode(freestanding) |
.lpfree |
Kernels, bootloaders, firmware | The Loup Freestanding Book |
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,OptionandResult - Functions, closures, default and named arguments, generators
- Structs, enums with
match, classes with inheritance, interfaces, generics, operator overloading - Exceptions (
throw,try/catch/finally),Resultwith?, andattempt - Modules and imports; projects with an
.lppkgmanifest - Interpolated strings and template fences
async/await(executed eagerly and in order today; see Chapter 13)- The ownership verbs (
reads,edits,takes,shares),modifiermethods andsafeblocks - A standard library with files, processes, paths, JSON, CSV, TOML, YAML, regular expressions, time and an HTTP server
loup testwithdebug.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
Part II: Shaping Data
Part III: Programs at Scale
Part IV: Dynamic and Asynchronous
- Concurrency
- Reflection and Dynamic Compilation ⚠ Planned
- Reactive UI ⚠ Planned
Part V: Shipping Scripts
- Testing
- JavaScript Host Interop ⚠ Planned
- Building Script Tools
- Memory Safety and Resource Management
Installing Loup and Running the Examples
Official builds come from code-craft-ai-company/loup-releases. On Linux and macOS:
curl -fsSL https://github.com/code-craft-ai-company/loup-releases/releases/latest/download/loup-install.sh | sh
On Windows, in 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:
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.