| @@ -4,146 +4,83 @@ A statically typed language built on algebraic effects, with actors, reference c |
| 4 | 4 | |
| 5 | 5 | ```louise |
| 6 | 6 | import std/io |
| 7 | | −import std/html.{type Html} |
| 7 | +import std/list |
| 8 | 8 | |
| 9 | | −effect log { fn log(msg: String) -> () } |
| 9 | +type Shape { |
| 10 | + Circle(radius: Float) |
| 11 | +, Rect(width: Float, height: Float) |
| 12 | +} |
| 10 | 13 | |
| 11 | | −pub fn greet(name: String) -> Html / <log> { |
| 12 | | − log("rendering " <> name) |
| 13 | | − <h1 class="title">Hello, {name}!</h1> |
| 14 | +effect log { |
| 15 | + fn log(msg: String) -> () |
| 14 | 16 | } |
| 15 | 17 | |
| 16 | | −fn with_console_log(action: fn() -> a / <log, io | e>) -> a / <io | e> { |
| 17 | | − handle { action() } with { log(msg) -> io.println("[log] " <> msg) } |
| 18 | +fn area(shape: Shape) -> Float / <log> { |
| 19 | + match shape { |
| 20 | + Circle(r) -> 3.14159 * r * r |
| 21 | + , Rect(w, h) -> { |
| 22 | + log("a {w}×{h} rectangle") |
| 23 | + w * h |
| 24 | + } |
| 25 | + } |
| 18 | 26 | } |
| 19 | 27 | |
| 20 | 28 | pub fn main() -> () / <io> { |
| 21 | | − use <- with_console_log |
| 22 | | − io.println(html.render(greet("Ada"))) |
| 29 | + handle { |
| 30 | + let total = [Circle(1.0), Rect(2.0, 3.0)] |> list.map(area) |> list.sum |
| 31 | + io.println("total area: {total}") |
| 32 | + } with { |
| 33 | + log(msg) -> io.println("[log] {msg}") |
| 34 | + } |
| 23 | 35 | } |
| 24 | 36 | ``` |
| 25 | 37 | |
| 38 | +`area` declares the `log` effect in its type; `main` decides what logging means. |
| 39 | + |
| 26 | 40 | ## Features |
| 27 | 41 | |
| 28 | | −- **Typed effects:** functions declare what they do (`/ <io, log>`), and handlers give effects their meaning. They cover exceptions, generators, dependency injection and mocking in tests, without monads. |
| 29 | | −- **Actors:** lightweight processes with typed messages, links, monitors and supervisors, in the style of Erlang/OTP. They are scheduled preemptively on every core. |
| 30 | | −- **No garbage collector:** Perceus reference counting frees memory as soon as it is unused, and updates values in place when nothing else refers to them. |
| 31 | | −- **Errors as values:** `Result` and `Option`, chained with `use`; panics are for bugs. |
| 32 | | −- **Familiar ergonomics:** type inference, traits with `@derive`, pattern matching with exhaustiveness checks, pipes (`x |> f(a, _)`) and Gleam's `use`. |
| 33 | | −- **HTML literals:** type-checked markup in expressions, escaped when rendered. |
| 34 | | −- **Tagged templates:** `pug\`.card\``, `html\`...\``, `xml\`...\`` — std's templaters are compiled to the typed HTML tree (user templaters are ordinary functions from a `std/template.Template`), with editor highlighting by tag. |
| 35 | | −- **C interop:** call C (and Rust) libraries, declare them as dependencies in `louise.toml`, and generate bindings from a header. |
| 36 | | −- **Tooling:** a formatter, a test runner, a language server with a VS Code extension, and a tree-sitter grammar for Neovim and Helix. |
| 42 | +- **Typed effects:** functions declare what they do (`/ <io, log>`) and handlers give it meaning: exceptions, generators, dependency injection and test mocks, without monads. |
| 43 | +- **Actors:** typed processes with links, monitors and supervisors in the style of Erlang/OTP, scheduled preemptively on every core. |
| 44 | +- **No garbage collector:** Perceus reference counting frees memory as soon as it is unused and updates unshared values in place. |
| 45 | +- **Familiar ergonomics:** type inference, traits with `@derive`, exhaustive pattern matching, pipes, Gleam's `use`, `Result`/`Option` for errors. |
| 46 | +- **HTML literals and templates:** type-checked markup in expressions, escaped when rendered. |
| 47 | +- **C interop:** call C and Rust libraries, declared in `louise.toml`, with bindings generated from headers. |
| 48 | +- **Tooling:** a formatter, a test runner, a language server (VS Code) and a tree-sitter grammar (Neovim, Helix). |
| 37 | 49 | |
| 38 | | −Louise is **pre-alpha**: the language and its standard library still change. |
| 50 | +On small benchmarks it runs in the range of GHC and Go and well ahead of Node and Java, in a few megabytes of memory, with static executables around 400 KB ([performance](docs/performance.md)). |
| 39 | 51 | |
| 40 | | −## Performance |
| 41 | | − |
| 42 | | −Four small programs, written idiomatically in each language ([`tests/compare`](tests/compare), run by `scripts/compare.sh`; every toolchain is pinned by [`tests/compare/Containerfile`](tests/compare/Containerfile)). Each prints the same number. **Instructions** are the stable signal where wall clock varies on a shared machine; wall clock is best of 5 runs. |
| 43 | | − |
| 44 | | −### `lists`: a map/filter/fold pipeline over a million integers, ten times |
| 45 | | − |
| 46 | | −| language | wall | instructions | peak memory | executable (stripped) | |
| 47 | | −|---|---:|---:|---:|---:| |
| 48 | | −| Haskell (GHC) | 0.05 s | 0.22G | 3 MB | 956 KB | |
| 49 | | −| **Louise** | **0.05 s** | **0.47G** | **6 MB** | **466 KB** | |
| 50 | | −| Go | 0.08 s | 0.27G | 34 MB | 1.5 MB | |
| 51 | | −| Rust | 0.09 s | 0.15G | 17 MB | 337 KB | |
| 52 | | −| Java | 0.90 s | 12.49G | 449 MB | runtime | |
| 53 | | −| Node | 1.36 s | 10.37G | 162 MB | runtime | |
| 54 | | −| Python | 1.54 s | 10.46G | 130 MB | runtime | |
| 55 | | −| Gleam (on node) | 19.96 s | 122.56G | 704 MB | runtime | |
| 56 | | − |
| 57 | | −### `fib`: calls and integer arithmetic (naive Fibonacci of 35) |
| 58 | | − |
| 59 | | −| language | wall | instructions | peak memory | executable (stripped) | |
| 60 | | −|---|---:|---:|---:|---:| |
| 61 | | −| Rust | 0.04 s | 0.29G | 1 MB | 337 KB | |
| 62 | | −| Haskell (GHC) | 0.07 s | 0.42G | 3 MB | 956 KB | |
| 63 | | −| Go | 0.07 s | 0.43G | 2 MB | 1.5 MB | |
| 64 | | −| Java | 0.10 s | 0.45G | 36 MB | runtime | |
| 65 | | −| **Louise** | **0.12 s** | **0.95G** | **6 MB** | **459 KB** | |
| 66 | | −| Node | 0.32 s | 1.90G | 55 MB | runtime | |
| 67 | | −| Gleam (on node) | 0.35 s | 2.05G | 58 MB | runtime | |
| 68 | | −| Python | 1.56 s | 15.81G | 8 MB | runtime | |
| 69 | | − |
| 70 | | −### `trees`: build and walk binary trees (allocation) |
| 71 | | − |
| 72 | | −| language | wall | instructions | peak memory | executable (stripped) | |
| 73 | | −|---|---:|---:|---:|---:| |
| 74 | | −| Haskell (GHC) | 0.15 s | 0.99G | 7 MB | 957 KB | |
| 75 | | −| Java | 0.26 s | 1.05G | 148 MB | runtime | |
| 76 | | −| **Louise** | **0.30 s** | **2.34G** | **8 MB** | **468 KB** | |
| 77 | | −| Node | 0.44 s | 2.62G | 85 MB | runtime | |
| 78 | | −| Rust | 0.68 s | 5.69G | 5 MB | 337 KB | |
| 79 | | −| Go | 0.79 s | 6.00G | 11 MB | 1.5 MB | |
| 80 | | −| Python | 2.46 s | 22.82G | 12 MB | runtime | |
| 81 | | −| Gleam (on node) | 5.22 s | 39.14G | 196 MB | runtime | |
| 82 | | − |
| 83 | | −### `floats`: arithmetic in a loop, three million times |
| 84 | | − |
| 85 | | −| language | wall | instructions | peak memory | executable (stripped) | |
| 86 | | −|---|---:|---:|---:|---:| |
| 87 | | −| Rust | 0.00 s | 0.02G | 1 MB | 357 KB | |
| 88 | | −| Go | 0.00 s | 0.02G | 2 MB | 1.5 MB | |
| 89 | | −| Haskell (GHC) | 0.00 s | 0.02G | 4 MB | 2.3 MB | |
| 90 | | −| **Louise** | **0.00 s** | **0.03G** | **6 MB** | **410 KB** | |
| 91 | | −| Java | 0.10 s | 0.38G | 42 MB | runtime | |
| 92 | | −| Node | 0.16 s | 0.44G | 58 MB | runtime | |
| 93 | | −| Gleam (on node) | 0.19 s | 0.53G | 60 MB | runtime | |
| 94 | | −| Python | 0.52 s | 4.99G | 8 MB | runtime | |
| 95 | | − |
| 96 | | −Before the unboxing milestone (#190) the same loop took 653M instructions and 83 ms: every `+` allocated a heap block. |
| 97 | | − |
| 98 | | −A release build of hello world is 387 KB: a static executable with the actor scheduler, the allocator and the runtime ([ADR 0042](docs/adr/0042-smaller-release-binaries.md)). |
| 99 | | − |
| 100 | | −What the numbers say: |
| 101 | | −- **Calls and arithmetic:** `Int`-heavy functions now run on unboxed machine integers (ADR 0045 Revision 2): a worker keeps raw `int64`s in registers and tags only at the boundary, bailing to the boxed path on overflow so promote-to-bigint semantics are exact. `fib`'s instructions fell by a third (1.40G → 0.95G): Louise is now about 3× Rust and 2.3× GHC on a call-heavy loop, and nearly 3× faster than Node. The remaining gap is per-call preemption and yield checks (#193) and devirtualising trait calls (#192) is next. |
| 102 | | −- **Float arithmetic:** a float loop's arithmetic runs on raw doubles, allocating nothing: 31M instructions, about twice Rust's (15M) and 1.3–1.4× Go's and GHC's, and an order of magnitude fewer than Node or Java. Until #190 every `+` allocated a heap block (the same loop: 653M instructions, 83 ms). |
| 103 | | −- **List pipelines:** the Core optimiser (#195–#200) fuses `range |> map |> filter |> fold` into one loop that allocates nothing per element — and now does so inside `if`/`match` arms too, which the benchmark's own pipeline had been missing (it built both intermediate lists: 2.66G instructions). Fused, the pipeline is 0.47G instructions (−82%) and 6 MB peak (−83%): Louise ties GHC's list fusion on wall clock and is ahead of Rust's collecting iterators, though Rust's unboxed `Vec` still leads on instructions (0.15G). `std/iter`'s lazy iterators fuse without rewrite rules (#199). |
| 104 | | −- **Allocation-heavy code:** reference counting with in-place reuse (Perceus) is faster than Rust's `Box` with the system allocator and close to GHC's garbage collector, in a fraction of Node's memory — and with a fraction of the instructions of everything but Haskell. |
| 105 | | − |
| 106 | | −Measured in the pinned container ([`tests/compare/Containerfile`](tests/compare/Containerfile)), on one machine: Intel Core Ultra 7 155H, with rustc 1.99, GHC, Go, OpenJDK, Node and Python from Fedora 44. The other languages are from 2026-10-15; the Louise rows are re-measured on 2026-10-19 (their instruction counts on the host — rootless containers cannot open perf events on this kernel — with the same binaries and the same user-space event). Instructions are user-space, counted once per program; wall clock is best of 5. Small programs show orders of magnitude, not a ranking. |
| 52 | +Louise is **pre-alpha**: the language and its standard library still change. |
| 107 | 53 | |
| 108 | 54 | ## Getting started |
| 109 | 55 | |
| 110 | | −**Prebuilt (x86-64 Linux):** the installer downloads the latest [release](https://toboggan.cloud/gabla108/louise/releases), checks its sha256 and puts `louise` and the runtime archives in `~/.local/bin`: |
| 56 | +**Prebuilt (x86-64 Linux):** installs the latest [release](https://toboggan.cloud/gabla108/louise/releases) into `~/.local/bin`, then `louise self update` keeps it current. |
| 111 | 57 | |
| 112 | 58 | ```sh |
| 113 | 59 | curl -fsSL https://toboggan.cloud/gabla108/louise/raw/main/scripts/install.sh | sh |
| 114 | 60 | ``` |
| 115 | 61 | |
| 116 | | −(by hand instead: extract `louise-<tag>-x86_64-linux.tar.xz` and copy `louise` and `liblouise_rt*.a` into `~/.local/bin`.) After that first install: |
| 62 | +**From source:** Rust (pinned in `rust-toolchain.toml`) and, for native builds, clang 13+ or GCC 15+. |
| 117 | 63 | |
| 118 | 64 | ```sh |
| 119 | | −louise self update # replace this installation with the latest release |
| 120 | | −louise self update --check # only report whether one is available |
| 121 | | −louise self update --version 0.1.0 --dry-run |
| 65 | +cargo build --release -p louise -p louise_rt |
| 66 | +alias louise=$PWD/target/release/louise |
| 122 | 67 | ``` |
| 123 | 68 | |
| 124 | | −**From source:** you need Rust (the version is pinned in `rust-toolchain.toml`) and, for native builds, clang 13+ or GCC 15+. |
| 69 | +Then: |
| 125 | 70 | |
| 126 | 71 | ```sh |
| 127 | | −cargo build --release -p louise -p louise_rt # the compiler and the runtime library |
| 128 | | − # (--profile dist: slower to build, faster to run) |
| 129 | | −alias louise=$PWD/target/release/louise |
| 130 | | − |
| 131 | | −louise run hello.lse # run a program with the interpreter |
| 132 | | −louise build # compile the package here to build/<name> |
| 133 | | −louise test # run the package's @test functions |
| 134 | | −louise fmt # format the package |
| 72 | +louise run hello.lse # run a program |
| 73 | +louise build # compile the package to build/<name> |
| 74 | +louise test # run its @test functions |
| 75 | +louise fmt # format it |
| 135 | 76 | ``` |
| 136 | 77 | |
| 137 | | −The [tour](docs/tutorial.md) walks through the language, and [`examples/http_demo`](examples/http_demo) is a supervised web server with logins. |
| 138 | | − |
| 139 | 78 | ## Documentation |
| 140 | 79 | |
| 141 | | −- [A tour of Louise](docs/tutorial.md) |
| 80 | +- [A tour of Louise](docs/tutorial.md), and [`examples/http_demo`](examples/http_demo), a supervised web server with logins |
| 142 | 81 | - [Language reference](docs/reference/language.md), [grammar](docs/reference/grammar.md) and [diagnostics](docs/reference/diagnostics.md) |
| 82 | +- [Performance](docs/performance.md): benchmarks against Rust, Go, GHC, Java, Node and Python |
| 143 | 83 | - [Design decisions](docs/adr/README.md) and the [runtime ABI](docs/runtime-abi.md) |
| 144 | | − |
| 145 | | −## Contributing |
| 146 | | − |
| 147 | | −The compiler, runtime and language server are written in Rust. [docs/contributing.md](docs/contributing.md) has the commands, the repository's layout, and how decisions are recorded. |
| 84 | +- [Contributing](docs/contributing.md): commands, layout, and how decisions are recorded |
| 148 | 85 | |
| 149 | 86 | Louise was named tilcayo until v1 ([ADR 0021](docs/adr/0021-the-name-louise.md)). |