Lane in one page

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

Markdown version of this page

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 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.

i8 :: 1;
nul main() { }

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

main.ln:1:1: error: `i8` is a predeclared type and cannot be declared
cast :: 1; 
nul main() { }

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

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.

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

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

#Program, exit code, output

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

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

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.

        u64 n = 0;
        v := x;
        for v != 0 {
nul main() { a := 1 + 2; }

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

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.

STACK :: 64;
MEM :: 16;

#Functions, ret

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

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.

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.

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.

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

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

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.

enum Op { push, add, sub, mul, dup, swap, drop, load, store, jmp, jnz, halt }
rec Instr { Op op; i32 arg; }
[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.

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; }
    }
}
enum C { red, green, blue } 
nul main() { C c; match c { .red { } } }

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

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.

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.

*bool p = &b[0];
*p = true;
[3]i8 a;
[]u8 raw = slice(cast(&a[0]), 3);
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.

000000000000000c
0000000000000004

#Access modes: wr and out

i32 run([]Instr code, wr Vm vm) {
i32 result = run(code, wr vm);
nul set(out Dir d, u32 n) { d = Dir(n); }
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:

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:

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

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

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

#Several results, variadic parameters, discarding

(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;
}
    pos, ok := find(keys, 7);
    pos, slots[1] = find(keys, 8);
    _, ok = find(keys, 9);
f32 sum_all(f32 first, ..[]f32 rest) {

#Function types (no closures)

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.

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.

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

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

main.ln:2:14: error: `limits.Priv` is not `pub`
@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

    defer io.close(f);
union Bits { f32 f; u32 u; }
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

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

u64 popcnt(u64 x) {
    when isa >= .bmi2 {
        ret x86.popcnt64(x);
    } else when arch == .aarch64 {
        ret arm.cnt64(x);
    } else {
@fp(fma, reassoc)
f32 dot([]f32 a, []f32 b) {

#Contracts

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.

TypeStored asMeans
f32, f64IEEE binary32, binary64the float; strict by default, relaxed per function with @fp
f16IEEE binary16the float; each operation is computed in f32 and rounded once, so it is correctly rounded
un8, un16unsigned integer nn / (2^k - 1), 0.0 to 1.0
sn8, sn16signed integer nmax(n / (2^(k-1) - 1), -1.0), -1.0 to 1.0 (-128 means -1.0)
bf16, f8e4m3, f8e5m216-bit and 8-bit floatsmachine-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

GroupKeywords
Declarationsfn rec enum union use pub ext
Layoutsoa aos
Controlif elif else for in match brk nxt ret defer
Data-parallelvec par wr out
Compile-timewhen
Toolingtest bench
Escape hatchasm
Literalstrue false nil

Reserved and never usable as identifiers: ct try.

#Operators, loosest first

LevelOperatorsNote
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:

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

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

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

main.ln:1:35: error: `a` is already declared
nul main() { if 1 { } }

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

main.ln:1:17: error: expected `bool`, found an integer
nul main() { u8 a = -1; }

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

main.ln:1:21: error: `-1` does not fit in `u8`
N :: u8(1) + u16(1); 
nul main() { }

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

main.ln:1:12: error: `+` needs operands of the same type, found `u8` and `u16`
nul main() { brk; }

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

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

More in the error reference and verified examples.