# Lane in one page

> Every construct with one minimal example, and the exact rules an agent gets wrong without them.

Lane is statically typed, compiled ahead of time, with plain data and no hidden work: nothing allocates, bounds-checks or converts behind your back. Source files are ASCII, one file is one module, extension `.ln`. The Status section of the [agent docs](/docs/agents.md) says which constructs the current compiler accepts.

## The rules agents get wrong

1. **Every simple statement ends with `;`**, including the last one in a block. A construct that ends with a `}` block takes none: a function, `rec`, `enum`, `union`, `if`, `for`, `vec`, `par`, `match`, `when`, `asm`, `test`, `bench`. Declarations without a body end with `;`: `use`, constants (`N :: 1;`) and `ext` imports. Record and union fields end with `;` too. Newlines mean nothing.
2. **Declarations are type first**: `u32 n = 0;`, `f32 dt` (parameter), `u64 gcd(u64 a, u64 b) {`. There is no `fn`, `let`, `var` or `:` before the type. The `fn` keyword appears only inside a function type: `f32 fn(f32, f32)`.
3. **The keywords are `ret`, `brk`, `nxt`** (not `return`, `break`, `continue`). There is no `while`; write `for cond { }`. There is no `null`; the null pointer is `nil`, and `nul` is the empty type (a function that returns nothing returns `nul`).
4. **There are no implicit conversions.** `u32 + u64` is an error; write `u64(a) + b`. An integer converts to another type only with `T(x)`. The one exception is an array becoming a slice of its elements. A `bool` does convert to any integer type, as the 0 or 1 it is (`u32(a < b)`); there is no conversion from an integer to `bool`, so write `x != 0`.
5. **A bare literal has no type of its own.** It takes its type from where it is used and must fit. `a := 1;` is an error, so is `for i in 0..10`. Write `u32 a = 1;`, `a := u32(1);`, `for i in u32(0)..10`. A literal next to a typed operand takes that operand's type (`x + 1`), and `for i in 0..s.len` is fine because `s.len` is a `usz`.
6. **Access modes are repeated at the call.** A parameter is read-only unless declared `wr` (read and write) or `out` (write, must be assigned on every path). The caller writes the same word in front of the argument: `run(code, wr vm)`. A missing or different mode is an error.
7. **Conditions must be `bool`.** `if n { }` is an error; write `if n != 0 { }`. No parentheses are needed: `if a < b { }`.
8. **Arithmetic wraps** (two's complement, never undefined). Division by zero is not checked; the processor faults. Shifts take the count modulo the width. There are **no bounds checks** on arrays and slices.
9. **No shadowing**: a name that is visible cannot be declared again, parameters and loop variables included. After its block ends the name is free.
10. **A function that returns a value must end every path with `ret`.** The check looks at the shape of the code, not at values: `for true { }` can be left, `for { }` cannot.
11. **Arrays are memory, never copied.** You cannot assign, compare or return a whole array; a record can be assigned (`a = b;` copies it) but cannot be returned yet or passed through the C ABI (use an `out` or pointer parameter). There are no record or array literals yet; they are an open question in the specification.
12. **Source is ASCII only**: tab, line feed, carriage return and bytes 0x20 to 0x7e. Any other byte is a lexical error, even inside a string or comment. Write other bytes as `\xNN` in a string or character literal.
13. **Reserved names, exactly.** (a) The keywords in the table below, and `ct` and `try`, are never identifiers. (b) The names `size_of`, `align_of`, `cast`, `slice`, `nul` and the scalar type names (`i8` ... `usz`, `bool`, `f16`, `f32`, `f64`) cannot be declared as a function, constant, record, enum, parameter, variable or loop variable, because they would be in scope by their own name. (c) A field or an enum variant may have any of those names, since it is only reached through its record or enum. (d) Other predeclared names, such as the hints `likely` and `assume`, are ordinary identifiers.
14. **A top-level declaration may come in any order** and there are no headers or forward declarations. `main` is `nul main()` or `i32 main()`; the `i32` result is the exit code.
15. **An expression statement must be a call.** `a + 1;` is an error.

## Reserved names: what is refused and what is allowed

Refused (rule 13b): declaring one of the reserved predeclared names as something in scope.

```lane
i8 :: 1;
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:1: error: `i8` is a predeclared type and cannot be declared
```

```lane
cast :: 1; 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:1: error: `cast` is a predeclared function and cannot be declared
```

Allowed (rule 13c): the same names as a field or an enum variant. This program is built and run by the test suite.

```lane
rec R { u8 u8; }
enum E { usz, cast }
nul main() { }
```

Verified: builds and runs. Exit code 0. No stdout.

## Program, exit code, output

```lane
i32 main() { i8 a = 127; a += 1; ret i32(a); }
```

Verified: builds and runs. Exit code -128 (0xffffff80). No stdout.

```lane
use io;

nul main() {
    io.print("hello, world\n");
}
```

## Variables and inferred types

A variable declared without a value is zero (integers 0, `bool` false, pointers `nil`, slices empty, arrays all zero). `name := expr;` infers the type from the expression, which must have one.

```lane
        u64 n = 0;
        v := x;
        for v != 0 {
```

```lane
nul main() { a := 1 + 2; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:19: error: the type of this integer is not known here; convert it, as in `u32(1)`
```

## Constants

`NAME :: expr;` at the top of a module or inside a block. Compile-time only, exact on 128 bits while untyped.

```lane
STACK :: 64;
MEM :: 16;
```

## Functions, ret

```lane
u32 fib(u32 n) { if n < 2 { ret n; } ret fib(n - 1) + fib(n - 2); }
```

Verified: part of a program that builds and runs. For the whole program, exit code 6765. No stdout.

## if, elif, else

```lane
i32 pick(i32 n) { i32 r = 9; if n == 1 { r = 1; } elif n == 2 { r = 2; } ret r; }
```

Verified: part of a program that builds and runs. For the whole program, exit code 129. No stdout.

`elif` continues an `if`, and `else` is followed only by a block, so a chain has exactly one spelling. `else if` is refused with the message "`else if` is written `elif`".

## Loops: for, brk, nxt

`for cond { }` is a while loop, `for { }` runs forever, `for i in a..b { }` runs `a` up to but not including `b`, and `a..=b` includes `b`. `brk` leaves the innermost loop, `nxt` goes to its next iteration.

```lane
u32 n = 0; u32 odd = 0;
for n < 10 { n += 1; if n % 2 == 0 { nxt; } odd += n; }
u32 k = 0; u32 hits = 0;
for { k += 1; if k > 20 { brk; } if k % 3 != 0 { nxt; } hits += 1; }
```

Verified: part of a program that builds and runs. For the whole program, exit code 2506. No stdout.

```lane
i32 main() { u32 s = 0; for i in u32(1)..=5 { s = s * 10 + i; } ret i32(s); }
```

Verified: builds and runs. Exit code 12345. No stdout.

```lane
nul main() { for i in 0..10 { } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:23: error: the type of this integer is not known here; convert it, as in `u32(1)`
```

## Records and enums

A record is a C-layout struct. An enum is a `u32`; its first variant is the zero value. `.name` is a variant whose enum comes from context.

```lane
enum Op { push, add, sub, mul, dup, swap, drop, load, store, jmp, jnz, halt }
rec Instr { Op op; i32 arg; }
```

```lane
[16]Instr code;
code[0].op = .push; code[0].arg = 100;
```

## match

`match subject { pattern, pattern { ... } else { ... } }` on an integer or enum. No fall-through; an integer `match` needs `else`; an enum `match` without `else` must name every variant. Patterns may be ranges `a..=b`.

```lane
Class classify(u8 b) {
    match b {
        '0'..='9' { ret .digit; }
        'a'..='z' { ret .lower; }
        'A'..='Z' { ret .upper; }
        ' ', '\t', '\n', '\r' { ret .space; }
        '!'..='/', ':'..='@', '['..='`', '{'..='~' { ret .punct; }
        else { ret .other; }
    }
}
```

```lane
enum C { red, green, blue } 
nul main() { C c; match c { .red { } } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:19: error: this `match` does not cover the variants `green`, `blue` of `C`; name them or add an `else` arm
```

## Arrays, slices, strings

`[N]T` is `N` values in memory (`N` a constant). `[]T` is a pointer and a length (`s.ptr`, `s.len`, a `usz`). A string literal is a `[]u8` with no terminator.

```lane
i32 main() { []u8 s = "hello"; usz total = 0; for i in 0..s.len { total += i; } ret i32(total); }
```

Verified: builds and runs. Exit code 10. No stdout.

`x[a..b]` is a sub-slice of the same memory (not copied, not bounds-checked).

## Pointers, cast, slice, size_of

`*T` is a pointer, `&place` takes an address, `*p` dereferences, `p + n` moves by `n` elements. `cast(x)` changes a pointer type or converts a pointer to and from `usz`; its target type comes from context. `slice(p, n)` makes a `[]T` from a pointer.

```lane
*bool p = &b[0];
*p = true;
```

```lane
[3]i8 a;
[]u8 raw = slice(cast(&a[0]), 3);
```

```lane
hex(size_of(A));
hex(align_of(A));
```

Verified: part of a program that builds and runs. For the whole program, exit code 0. Stdout: Lines 1 to 2 of 8.

```text
000000000000000c
0000000000000004
```

## Access modes: wr and out

```lane
i32 run([]Instr code, wr Vm vm) {
```

```lane
i32 result = run(code, wr vm);
```

```lane
nul set(out Dir d, u32 n) { d = Dir(n); }
```

```lane
rec A { u8 a; } 
rec B { u8 a; } 
nul g(wr A a) { } 
nul main() { A r; g(r); }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:4:21: error: parameter `a` of `g` takes `wr`, but the argument has no access mode
```

A parameter without a mode is read-only, and so is everything reached through it:

```lane
nul f(u32 a) { a += 1; } nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:16: error: parameter `a` is read-only
```

## Several results, variadic parameters, discarding

```lane
(f32, bool) find([]u64 keys, u64 key) {
    for i in 0..keys.len {
        if keys[i] == key { ret f32(i), true; }
    }
    ret 0.0, false;
}
```

```lane
    pos, ok := find(keys, 7);
    pos, slots[1] = find(keys, 8);
    _, ok = find(keys, 9);
```

```lane
f32 sum_all(f32 first, ..[]f32 rest) {
```

## Function types (no closures)

```lane
nul each(wr []f32 v, f32 fn(f32) op) {
```

## Modules and C imports

`use name;` imports `name.ln` next to the file, or the standard module of that name; call its `pub` functions as `name.f(...)`. Only `pub` declarations are visible. `ext` imports (or exports) a C-ABI function; `@lib` names the library.

```lane
pub CAP :: 8;
HIDDEN :: 3;
pub enum Open { a }
enum Closed { a }
pub rec Pub { u8 a; }
rec Priv { u8 a; }
```

Verified: one module of a multi-module program.

```lane
use limits; 
nul main() { limits.Priv p; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:2:14: error: `limits.Priv` is not `pub`
```

```lane
@lib("kernel32") ext *nul VirtualAlloc(*nul address, usz size, u32 kind, u32 protect);
```

From the standard library module `mem`. It is written in Lane.

## defer, union, generics, tests

```lane
    defer io.close(f);
```

```lane
union Bits { f32 f; u32 u; }
```

```lane
test "clamp keeps a value inside its range" {
    io.expect(clamp(5, 0, 3), 3);
    io.expect(clamp('a', 'b', 'z'), 'b');
}
```

## Layout, SIMD and threads

```lane
rec Body { f32 x; f32 vx; }

nul step(wr soa []Body b, f32 dt) {
    par vec i in 0..b.len {
        b.x[i] += b.vx[i] * dt;
    }
}
```

`soa []T` stores one array per field; `aos []T` stores records back to back. `f32x4` is a register value, `[4]f32` four floats in memory, `f32xw` the target's widest vector. A `vec` loop must vectorize or the build fails. `par` runs a loop or block across cores and joins.

## Per-target code, hints, float rules

```lane
u64 popcnt(u64 x) {
    when isa >= .bmi2 {
        ret x86.popcnt64(x);
    } else when arch == .aarch64 {
        ret arm.cnt64(x);
    } else {
```

```lane
@fp(fma, reassoc)
f32 dot([]f32 a, []f32 b) {
```

## Contracts

```lane
i32 clamp(i32 v, i32 lo, i32 hi)
    assume lo <= hi, "lo must not exceed hi";
    test (5, 0, 3) == 3, "expected 3 when given 5 for range 0 to 3";
    test (-1, 0, 3) == 0;
    test (7, 3, 3) == 3;
    test (5, 3, 0) fails;
{
```

## Number types

One rule: **arithmetic happens in `f32`, and a value is rounded once when it is stored**, so results are bit-identical on every processor.

| Type | Stored as | Means |
|---|---|---|
| `f32`, `f64` | IEEE binary32, binary64 | the float; strict by default, relaxed per function with `@fp` |
| `f16` | IEEE binary16 | the float; each operation is computed in `f32` and rounded once, so it is correctly rounded |
| `un8`, `un16` | unsigned integer `n` | `n / (2^k - 1)`, 0.0 to 1.0 |
| `sn8`, `sn16` | signed integer `n` | `max(n / (2^(k-1) - 1), -1.0)`, -1.0 to 1.0 (-128 means -1.0) |
| `bf16`, `f8e4m3`, `f8e5m2` | 16-bit and 8-bit floats | machine-learning data, converted with the same rule |

- From a float to `un` or `sn`: clamp to the range, round to nearest even, NaN gives 0.
- `packed` arrays store these types at their real width (`un8` is one byte per element).
- Example: a vertex normal as 3 x `sn8` and a colour as 4 x `un8` take 7 bytes in a record.

## Keywords

| Group | Keywords |
|---|---|
| Declarations | `fn` `rec` `enum` `union` `use` `pub` `ext` |
| Layout | `soa` `aos` |
| Control | `if` `elif` `else` `for` `in` `match` `brk` `nxt` `ret` `defer` |
| Data-parallel | `vec` `par` `wr` `out` |
| Compile-time | `when` |
| Tooling | `test` `bench` |
| Escape hatch | `asm` |
| Literals | `true` `false` `nil` |

Reserved and never usable as identifiers: `ct` `try`.

## Operators, loosest first

| Level | Operators | Note |
|---|---|---|
| 0 | `..` `..=` | do not chain |
| 1 | `\|\|` |  |
| 2 | `&&` |  |
| 3 | `==` `!=` `<` `<=` `>` `>=` | do not chain |
| 4 | `+` `-` `\|` `^` |  |
| 5 | `*` `/` `%` `<<` `>>` `&` |  |

Bitwise operators bind tighter than comparisons, so `a & b == c` means `(a & b) == c`:

```lane
i32 main() { i32 a = 6; if a & 3 == 2 { ret 1; } ret 2; }
```

Verified: builds and runs. Exit code 1. No stdout.

Comparison operators do not chain. Unary `-` `!` `~` `*` `&` bind tighter than any binary operator. `a op= b` needs a variable of integer type.

## More refusals worth knowing

```lane
nul main() { u32 a = 1; if true { a := true; } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:35: error: `a` is already declared
```

```lane
nul main() { if 1 { } }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:17: error: expected `bool`, found an integer
```

```lane
nul main() { u8 a = -1; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:21: error: `-1` does not fit in `u8`
```

```lane
N :: u8(1) + u16(1); 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:12: error: `+` needs operands of the same type, found `u8` and `u16`
```

```lane
nul main() { brk; }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:14: error: `brk` outside a loop
```

More in the [error reference](/docs/agents/errors.md) and [verified examples](/docs/agents/examples.md).
