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 says which constructs the current compiler accepts.
#The rules agents get wrong
- 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;) andextimports. Record and union fields end with;too. Newlines mean nothing. - Declarations are type first:
u32 n = 0;,f32 dt(parameter),u64 gcd(u64 a, u64 b) {. There is nofn,let,varor:before the type. Thefnkeyword appears only inside a function type:f32 fn(f32, f32). - The keywords are
ret,brk,nxt(notreturn,break,continue). There is nowhile; writefor cond { }. There is nonull; the null pointer isnil, andnulis the empty type (a function that returns nothing returnsnul). - There are no implicit conversions.
u32 + u64is an error; writeu64(a) + b. An integer converts to another type only withT(x). The one exception is an array becoming a slice of its elements. Abooldoes convert to any integer type, as the 0 or 1 it is (u32(a < b)); there is no conversion from an integer tobool, so writex != 0. - 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 isfor i in 0..10. Writeu32 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), andfor i in 0..s.lenis fine becauses.lenis ausz. - Access modes are repeated at the call. A parameter is read-only unless declared
wr(read and write) orout(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. - Conditions must be
bool.if n { }is an error; writeif n != 0 { }. No parentheses are needed:if a < b { }. - 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.
- No shadowing: a name that is visible cannot be declared again, parameters and loop variables included. After its block ends the name is free.
- 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. - 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 anoutor pointer parameter). There are no record or array literals yet; they are an open question in the specification. - 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
\xNNin a string or character literal. - Reserved names, exactly. (a) The keywords in the table below, and
ctandtry, are never identifiers. (b) The namessize_of,align_of,cast,slice,nuland 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 hintslikelyandassume, are ordinary identifiers. - A top-level declaration may come in any order and there are no headers or forward declarations.
mainisnul main()ori32 main(); thei32result is the exit code. - 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.
| 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
unorsn: clamp to the range, round to nearest even, NaN gives 0. packedarrays store these types at their real width (un8is one byte per element).- Example: a vertex normal as 3 x
sn8and a colour as 4 xun8take 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:
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.