Reference for writing correct loft code. Apply whenever writing, editing, or reviewing .loft files. Covers types, syntax, known bugs, workarounds, naming rules, and error→fix table.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Reference for writing correct loft code. Apply whenever writing, editing, or reviewing .loft files. Covers types, syntax, known bugs, workarounds, naming rules, and error→fix table.
user-invocable
false
Loft Language Writing Reference
Always consult this before writing or reviewing .loft files.
Before reimplementing stdlib-or-library functionality, check doc/claude/LIBRARIES.md and loft install <name> — a registered library may already provide it.
Naming conventions — enforced by the parser
Construct
Convention
Examples
Functions, variables
lower_case
my_fn, item_count
Types, structs, enums, variants
CamelCase
Point, Color, Red
Constants (file-scope)
UPPER_CASE
PI, MAX_SIZE
Operator definitions
OpXxx prefix
OpAdd, OpEqInt
The parser rejects code that violates these rules.
Primitive types
Type
Description
Null sentinel
integer
64-bit signed int (the base integer type; i64 at rest)
i64::MIN
float
64-bit float; literal must contain .: 1.0
NaN
single
32-bit float; literal suffix f: 1.0f
NaN (32-bit)
boolean
true / false (2-state by default under DN1; boolean? adds null → three-state, @PLN17)
boolean? null is byte 255 (test with b == null; !b is true for both null and false; null == false is false)
character
Single Unicode char; literal: 'a', '😊'; c as integer → codepoint
'\0'
text
UTF-8 string (primary string type)
internal null pointer
There is no long type and no l literal suffix — both were
removed. integer is already 64-bit (i64), so integer literals are
plain (86400000, not 86400000l), and now() / File.size return a
full-range integer. Writing long or 10l is a parse error
("Undefined type long" / "Expect token ;").
Narrow / sized integers are aliases of integer (defined in
default/01_code.loft), for byte-width-sensitive file / wire formats:
i8size(1), i16/u16size(2), i32/u32size(4). Cast with
x as i32 etc. Use plain integer for ordinary arithmetic — it has
the full 64-bit range.
Uncomputable arithmetic → null, and the program KEEPS RUNNING (C80, the
spreadsheet model): divide / modulo by zero, and integer overflow
(i64::MAX + 1), are uncomputable, so they yield null and execution CONTINUES
— no trap, no halt, identically in dev / test / production. Any arithmetic
landing exactly on i64::MIN also reads as null (the in-band sentinel).
Defend a site with ?? <fallback> to turn the null into a value; an unguarded
divide-by-zero additionally logs a Warn (overflow is silent — the null is the
signal). A function returning integer may return null (it yields i64::MIN,
detectable with !result).
Prefer x? when the fallback is just the type's zero (@PLN116). Postfix ?
discharges T? to T using the type's own default, so ?? 0 / ?? 0.0 /
?? "" / ?? Pixel{r:0,g:0,b:0} boilerplate collapses to one character. ??
supplies the default you give; ? supplies the default the type gives — that
pairing is the mnemonic.
name = row.label? // text? → "" (was: ?? "")
first = points[i]? // Point? → Point{} (every field defaulted)
count = (a / b)? // integer? → 0 (parens — see below)
Defaults: scalar → 0/0.0/false/'\0', text → "", collection → empty,
record → every field defaulted, nullable U? → null, bare enum → its
first-declared variant.
Three things to know before reaching for it:
? binds TIGHTEST, ?? binds LOOSEST — opposite ends. On a binary
result that flips the parens: a / b ?? 0 discharges the division, but
a / b? is a / (b?) and evaluates to null. Write (a / b)?. So ? is
a clear win on a primary (row.label?, v[i]?, x? — no parens) and a
wash on arithmetic.
On an enum it is positional.c? is the first-declared variant, so
reordering the enum silently changes it. Use ?? Colour.Red when the variant
matters.
Two types have no default, so x? is a COMPILE error (never a runtime one):
a bare reference, and a record with a bare enum field lacking = <variant>.
The error names the fixes; ?? or match is the fallback.
At a text parse, put ? after the CHECKED cast:
n = (s as integer?)? // integer — checked cast, then default ⇒ 0 on a bad parse
n = s as integer ?? 0 // integer — the assert-or-default form
n = s as integer? // integer? — the nullable CAST (that `?` belongs to the type)
n = (s as integer)? // COMPILE ERROR — a bare `as` on text is an assertion
A bare text as integer is an assertion the compiler refuses (a parse can't be
proven), so (s as integer)? fails on the inner cast — not because ? is
unavailable. Write the checked cast first.
Parsing text is fallible, so text as integer types integer? (as float →
float?, as single → single?). "42" as integer is a parse, not a numeric
cast — a non-numeric string yields null, so the compiler types the result nullable
and rejects storing it into a non-null slot. Discharge at the parse site:
n = s as integer ?? 0 (default), n = s as integer? (keep it nullable), or match.
This is the same reachable-fault rule as ÷0 / out-of-bounds indexing (@PLN25
(N-Parse)). A numericas (3.14 as integer, x as u8) is not a parse and does
not add ? on its own (a narrowing numeric cast that can miss uses as u8?).
Nullability defaults (@PLN25 DN1) — every scalar and vector is NON-NULL by default. A plain
integer / float / single / boolean / character / text (and vector<T>) field, local, or
return REJECTS null: storing null — or an undischarged τ? from a fit-failing op (parse, /,
v[i]) — into it is a compile error. To ALLOW null, append ? to the type (integer?, text?,
vector<T>?). A vector<T> field defaults to [] (empty, non-null). The old not null modifier
is a RETIRED accepted no-op — it now means what the default already is, so don't write it; write
? when (and only when) you want the slot to hold null.
text vs string: The canonical string type is text. Using string in struct fields causes errors.
Field modifiers (struct fields only)
struct Point {
const id: integer, // binding-const PREFIX: write-once at construction
const cells: vector<Cell>, // BUILDER: slot write-once, `cells += […]` still grows it
coord: const Coord, // value-const on the TYPE: frozen value (contents read-only)
x: float, // non-null by default (DN1) — no `not null` needed
r: integer limit(0, 255),
label: text = "default",
area: float virtual($.x * $.y),
note: text?, // append `?` to ALLOW null
}
Modifiers: limit(min, max), default(expr) / = expr, virtual(expr). (not null still parses
but is a retired no-op — see the DN1 defaults note above; use ? for the nullable case.)
Two const axes (@PLN40) — const before the NAME freezes the binding; const before the
TYPE freezes the value. They are opposites and compose:
declaration
rebind t.v=
append t.v+=
element t.v[i]=
use
v: T
✓
✓
✓
plain
const v: T
✗
✓
✓
builder (grow in place)
v: const T
✓
✗
✗
frozen value (rebindable slot)
const v: const T
✗
✗
✗
fully immutable
binding-const (const v: T, prefix): write-once slot, contents stay mutable — the builder
shape. Reach for it when a field is assembled once then grown/edited in place (const cells: vector<Cell> with cells += […]). const virtual(...) is rejected; works on enum-variant fields.
value-const (v: const T, on the type): the value is read-only — append / element / nested
writes (t.v+=, t.v[i]=, t.r.x= through it) are rejected; a whole-value rebind t.v = other
is allowed. Reach for it on a genuine value/record (shared config, a compound key, a par()-shared
value). Enforced for DIRECT writes; laundering via a local/return/generic is Phase 3 (not yet).
scalar collapse: a by-value scalar (integer/float/…) freezes fully under EITHER axis —
const n: integer and n: const integer both reject t.n= and t.n+=.
Owner policy (libraries): const every never-reassigned field. Use const v: T for builder fields
you still append to; v: const T for true value/record fields; whole-value keys/config → both.
Variable declarations
Variables declared by assignment — type is inferred from the initialiser.
x = 5;
s = "hello";
f = 3.14;
Explicit type annotations (sometimes required for empty collections):
v: vector<integer> = [];
n: integer = null as integer; // a null integer must be cast; bare `= null` is rejected
const variables
const x = 5; // immutable local — reassignment is a compile error
const t = "hello"; // works for any type
Constants
The const keyword is accepted at file scope as well, alongside the
bare-name form. Both produce the same file-scope immutable constant:
PI = 3.14159265358979; // bare-name form
const E = 2.71828182845905; // const-keyword form (P246, 2026-05-11)
pub const MAX_SIZE = 256; // pub + const combine for exported constants
Constants must be UPPER_CASE. Prefer the const form when you
want the immutability intent visible at the declaration site
(the bare-name form relies on the UPPER_CASE convention as the only
visual signal); both forms behave identically.
UPPER_CASE locals warn unless declared const. Inside a
function body, FOO = 5; (an assignment with an UPPER_CASE name and
no const keyword) emits a warning telling you to add const or
rename to lower_case. The convention "UPPER_CASE means immutable"
is enforced by this check at every scope.
const T — immutable (compile error to assign to it inside function)
&T — a live reference to the caller's argument: reads see the caller's current value,
writes write the caller, field/element mutation mutates the caller. Call WITHOUT & — the
reference comes from the param's TYPE: fn inc(n: &integer){ n = n + 1 } is called inc(x), not
inc(&x) (& is a binding marker, not a general operator). & to a temporary or in a general
expression is an error.
& that is never mutated is a compile error — drop it if the param is read-only
Omit modifier — pass by value/copy (heap values still alias: field/element mutation propagates)
A local reference is bound with a = &b (or a: &T = b); the operand must be addressable (a
variable / struct field / vector element). Full model: LOFT.md § References.
A function body ending in an expression (no ;) returns that value. Functions without -> return void.
Nested fn definitions are forbidden.fn declarations must be at file
scope. Code like
fn outer() {
fn inner() { ... } // PARSE ERROR
}
produces "'fn' definitions must be at file scope, not inside a function or
block". Move helper fns alongside the caller, not inside it. Lambdas
(|x| { ... } or fn(x: T) { ... }) are the only "function-shaped" thing
allowed inside a fn body.
Imports
use arguments; // wildcard: all pub names bare + `arguments::` qualifier
use arguments::*; // explicit wildcard (same as above)
use arguments::parse_args; // selective: just one name, bare
use arguments::(parse_args, Flag); // selective group — MULTIPLE names need parentheses
use arguments::Flag as Opt; // alias an imported name (bare `Opt`)
use arguments::(Flag as Opt, parse_args); // per-name aliases inside the group
use arguments as args; // library alias → `args::parse_args` (qualified-only,
// does NOT import names bare)
Multiple names MUST be parenthesised — use lib::a, b; (flat comma list) is a
hard error; write use lib::(a, b);. (@PLN22 Phase 4.)
use lib as m; gives a qualifier alias only (m::fn); it does not wildcard-import.
A qualified lib::fn() auto-loads the library — an explicit use is optional for
qualified access.
use declarations must appear before any other declarations in the file.
Finding a library's API (do this BEFORE writing use calls)
Libraries live OUTSIDE the project (~/.loft/registry/<name>-<version>/,
~/.loft/lib/<name>/), so the project tree alone does not show what they
export. Discovery surface, nearest first:
.loft/api/<name>.api in the project — generated public-API stubs
(signatures + doc comments) for every locked dependency. Written by
loft install / loft update / loft pin; read these first.
.loft/api/_available.api — the registry CATALOG: every package you
could loft install (name, latest version, one-line description), written
alongside the per-dep stubs. Read this to see what EXISTS, not just what's
installed.
loft api — list every library reachable from the cwd (project deps,
installed registry packages, user libraries) with their source paths.
loft api <name> — print one library's full public surface.
loft api --registry — print the whole installable catalog on demand
(the live form of _available.api). The catalog is cached ~1h; add
--refresh to force a re-fetch (e.g. after a package was just published
or its description changed).
loft search <query> / loft info <name> — query the registry
for libraries not installed yet; loft install <name> fetches one and
refreshes the stubs.
Never guess a library function's signature: check the stub or loft api
output, and read the real source at the path they name when you need the
implementation.
Field names may overlap across structs — lookups are type-scoped.
Tuples
Anonymous, fixed-arity, stack-allocated compound values. Use them to
return multiple values without naming a struct. Shipped in 0.8.3
(T1.1–T1.11); see doc/claude/TUPLES.md.
// Type notation — two or more element types (single-element tuples
// are not allowed; use the bare type instead).
t: (integer, text) = (3, "hi");
// Literal
pair = (1, "hello");
// Element access (zero-based integer literal — NOT a variable index).
a = pair.0; // integer
b = pair.1; // text
// Element assignment
pair.0 = 5;
pair.0 += 3;
// Destructuring
(lo, hi) = min_max(values);
// Function return
fn classify(t: (integer, text)) -> text {
match t {
(0, _) => "zero",
(n, msg) => "{n}: {msg}",
}
}
// Nested tuples — chain the `.N` accessors.
nested: ((integer, integer), boolean) = ((1, 2), true);
inner_first = nested.0.0; // 1
inner_second = nested.0.1; // 2
flag = nested.1; // true
Restrictions:
No single-element tuples — (integer) is just integer.
No named tuple fields — use a struct.
No tuple iteration / whole-tuple formatting — access elements one
by one.
Scalar elements are NON-NULL by default (@PLN25 DN1) — a tuple
integer / text / … element rejects null; append ? to the element
type ((integer?, text)) to allow it. (not null is a retired no-op.)
Compound assignment on tuple LHS is rejected — (a, b) += (1, 2)
is a compile error; rewrite as a += 1; b += 2; or rebuild the tuple.
Comparing a tuple-element character against a literal (t.0 == 'a')
works on both backends — the old P207 native E0308 was fixed 2026-05-04;
no cast or destructure workaround is needed.
Enums
Simple enum (value type, no fields):
enum Color { Red, Green, Blue }
c = Color.Red; // qualify when DEFINING a new variable
// ordering follows declaration order: Red < Green < Blue
Bare variants need a type context (@PLN22 Phase 1). A bare Red resolves only
against a known enum — a match subject, a typed target (c: Color = Red), a
typed reassignment / field, a parameter, a return type, an == LHS, or an is
subject. Defining a NEW untyped variable from a bare variant (c = Red) is a hard
error — qualify it (c = Color.Red) or annotate (c: Color = Red). Match arms and
the other context positions still use the bare form (match c { Red => … }). Two
enums MAY share a variant name (enum Color { Red } + enum Berry { Red }); the
bare Red resolves by its context enum.
Struct-enum (each variant has fields; polymorphic dispatch via methods):
enum Shape {
Circle { radius: float },
Rect { w: float, h: float },
}
fn area(self: Circle) -> float { 3.14159 * self.radius * self.radius }
fn area(self: Rect) -> float { self.w * self.h }
s = Circle { radius: 2.0 };
a = area(s); // dispatches to correct variant
Plain enums cannot have methods — use struct-enum variants for polymorphic dispatch.
Trailing commas in variant field lists are accepted: Circle { radius: float, }.
JSON round-trip: "{shape:j}" produces {"Circle":{"radius":3.14}}; Shape.parse(json) reconstructs the correct variant.
Vectors
empty: vector<integer> = [];
nums = [for i in 0..10 { i * 2 }]; // comprehension
items = [1, 2, 3];
v += [element]; // append
v += other_vec; // concatenate
len(v); // length
v[i]; // index read
Empty vectors need a type annotation so the compiler knows the element type.
Slices are iterators, materialised on assignment.sub = arr[lo..hi] (annotated or not) builds a fresh vector, and negative bounds count from the end (arr[2..-1], @P384). A slice still cannot be passed directly where a vector<T>argument is expected — assign to a local first, or pass the array with index bounds.
v[i] with a possibly-negative index does NOT null-guard. Scalar indexing counts from the end for negative i, exactly like slices: v[-1] is the LAST element, v[-len] the first — NOT null. Only i >= len (and i < -len) yield null. So if v[i] { … } and v[i] ?? d catch an over-range index but NOT a negative one — a -1 "not-found" sentinel or a a - b underflow silently reads a real element from the end. When i can go negative, test if i >= 0 FIRST (that >= 0 check is not redundant with a later null-guard).
Never swap vector<STRUCT> elements in-place via a temp (#338).tmp = v[j] is a VIEW of slot j (not a copy), but v[j] = v[k] COPIES into the slot — so tmp = v[j]; v[j] = v[k]; v[k] = tmp; silently loses j's record and duplicates k's. Swap scalar fields one by one, or build a fresh vector (selection instead of in-place insertion sort).
Hash collections
Hash must be a struct field — not a standalone local variable:
struct Entry { key: text, value: integer }
struct Table { data: hash<Entry[key]> }
t = Table { data: [] };
t.data += [Entry { key: "x", value: 1 }];
e = t.data["x"];
if e == null { /* not found */ }
else { e.value += 1; }
t.data["x"] = null; // remove entry
Hash cannot be iterated directly — track aggregates separately.
Never use key as a field name in a hash-value struct — it conflicts with hash iteration internals.
Structural satisfaction: if the methods exist, the type satisfies the interface.
No impl block needed. Built-in types satisfy Ordered, Equatable, Addable,
Numeric, Scalable, Printable automatically.
The both parameter name
Name the first parameter both instead of self to register a function as
both a method and a free function:
name = record.field ?? "default" // null-coalescing
name = record.field? // …or the TYPE's default ("" for text)
x as i32 // cast to a 4-byte sized integer
flags & ~32 // bitwise NOT — clears bit 5
? and ?? are at opposite ends of this table, so they parenthesise
oppositely on a binary result: a / b ?? 0 discharges the division, a / b? is
a / (b?) and yields null — write (a / b)?.
is variant check
if d is North { ... } // boolean check
assert(!(shape is Rect)); // negation
// field capture — binds variant fields as locals scoped to the if-body
if shape is Circle { radius } {
area = PI * radius * radius;
}
// multiple fields + else
if shape is Rect { width, height } {
area = width * height;
} else {
area = 0.0;
}
String / text literals
Double-quoted strings ("...")
Single-line. Supports {expr} interpolation and \n, \t, \\, \" escapes.
Use println() for line-oriented output and print() for output without a newline.
Control flow
if cond { } else if cond { } else { }
result = if x > 0 { x } else { -x } // if as expression
// null check
if !x { } // x is null (or false for boolean)
val = a ?? b // null-coalescing
while cond { }
return expr;
break;
break expr; // break with value (requires non-void function)
For loops
for i in 0..n { } // exclusive: 0 to n-1
for i in 0..=n { } // inclusive: 0 to n
for item in collection { }
for c in some_text { } // character iteration
for item in col if item.active { } // filtered iteration
for i in rev(0..n) { } // reverse range
Loop attributes
for v in collection {
v#index // 0-based position (vector/sorted); byte offset (text)
v#count // iterations completed so far (all types)
v#first // true for first element (all types)
v#next // byte offset after current char (text only)
v#remove // remove current element (filtered loops only)
}
#index is NOT supported on index collections — use #count there.
Match
match color {
Red => println("red"),
Green | Blue => println("cool"),
_ => {},
}
match shape {
Circle { radius } => println("r={radius}"),
Rect { w, h } if w == h => println("square"),
_ => {},
}
// Tuple match — destructure into element patterns.
match (3, 7) {
(0, _) => "zero",
(n, m) => "{n},{m}",
}
Match is an expression — all arms must produce the same type (or void).
The arm separator is =>, never ->.-> is the lambda /
function return-type arrow; using it in a match arm produces a clear
diagnostic ("match arm separator is =>, not ->") — but only because
the parser was hardened against it. Older drafts of TUPLES.md showed
-> for arms; that was always wrong. If a match arm in your code
uses ->, fix it before running anything.
Scalar-match arms need commas between them; enum and tuple match
also accept newline-separated arms. When in doubt, comma-separate —
it's universally accepted.
Higher-order functions
Two lambda syntaxes, each with a clear job:
Shorthand |x| — types inferred from the call-site context
(e.g. the map/filter signature). Use inside higher-order
calls where the types flow in.
Explicit fn(...) — full type annotations. Use when the
lambda is stored in a local variable, or anywhere types can't
be inferred. Omit -> for void-returning lambdas (-> void
is not valid syntax — there is no void type).
fn double(x: integer) -> integer { x * 2 }
doubled = map(nums, double); // named function ref — bare name, no `fn` prefix
positive = filter(nums, |x| { x > 0 }); // inferred lambda
total = reduce(nums, 0, |a, b| { a + b });
// Method form on vectors
doubled = nums.map(|x| { x * 2 });
evens = nums.filter(|x| { x % 2 == 0 });
// Typed lambda stored in a local: use the explicit fn(...) form.
emit = fn(x: integer, y: integer) { total += x + y; };
emit(1, 2);
Type annotations on |x| shorthand are rejected by design
(see doc/claude/DESIGN_DECISIONS.md § C62). If you need
types, switch to fn(name: <type>) { ... } — the shorthand
exists specifically because the types are inferred; adding
annotations collapses the distinction between the two forms.
Variable scoping — one type per name, per function
Variable names are per-function, and loft has no block scoping: a
for/if body does not open a fresh binding — every local (loop variables
included) lives in the enclosing function's scope for the whole function. So the
rule that matters is narrow: within one function, a name maps to a single
slot + type. The same name in a different function is completely free.
All of the violations below are clean compile-time errors with fix hints —
never a codegen panic or silent corruption, on either backend:
A name reused with a different type in one function → error, even across
disjoint blocks: if … { x = 1 } if … { x = "hi" } →
Variable 'x' cannot change type from integer to text. Re-assigning the same
type is fine (x = 1; x = 2).
A loop variable reused with a different element type (@P344) →
for i in [1,2,3] {…} then for i in ["a","b"] {…} in the same function →
loop variable 'i' has type text but was previously used as integer. Same
element type is fine ([1,2,3] then [4,5,6]); the same name in a different
function is fine. Two same-function loops over different types → distinct names
(for n in nums {…} for s in strs {…}).
A loop variable named like an existing local →
loop variable 'x' shadows a local named 'x' — rename the loop variable (e.g. loop_x). Rename it, or drop the dead outer local.
Loop variables are inference-only (@P345) — for i: integer in … does not
parse (loop variable 'i' is type-inferred from the iterable — remove the ': <type>' annotation). Drop the annotation.
This is accepted-as-intended (CAVEATS.md § P344); true per-loop scoping is a
deferred resolver change, not a bug to work around. The zero-cost habit:
descriptive, distinct names (fib_i, mb_x) — it sidesteps every case above
and reads better anyway. (You do not need names unique across the whole file;
the constraint is per-function.)
Unused variable = warning, not an error — the program still runs (exit 0).
Use _ for an unused loop variable to keep the build warning-clean.
Builtin names — shadowing rules (@PLN22 Phase 2)
Definitions CAN shadow a stdlib/library name.enum E, struct File,
pub PI = 3 are legal even though the stdlib has E/File/PI; your name wins
bare resolution and std::Name still reaches the original.
Built-in TYPE-KEYWORDS are reserved — you cannot define struct integer,
enum vector, etc. (it errors: "conflicts with a type"). Reserved: integer,
float, single, text, boolean, character, vector, hash, sorted,
index, radix, spatial, iterator, i8/i16/i32, u8/u16/u32,
reference. This holds for struct, enum, and type alike.
A few builtin names break as a local variable name — the literal null
(Not implemented operation = for type null), the special ticks
(Cannot redefine function 'ticks' as a variable), and the higher-order method
names map/filter/reduce (a local of that name derails the later
v.map(x => …) lambda parse → Expect token )). Most builtins are safe as
variable names — len, round, rev, and sorted (as a value) all work — but
distinct, descriptive names sidestep the question entirely.
Text pitfalls
character == text is a compile error — use "{c}" == t to compare as text.
Cannot reassign text parameter — copy to local first: local = param; local = ...
Prefer h += expr over h = h + expr for text building.
File I/O patterns
Path resolution — relative means program-relative
A relative path resolves against the program's own directory
(source_dir() — source dir under --interpret, exe dir under --native), not
the process cwd. So file("assets/x") loads the asset bundled beside the
program on every backend, regardless of launch directory. Absolute paths are
untouched. The file builtins (file, exists, read_file/write_file,
delete/move/mkdir, image loads) all resolve this way — so don't hand-roll
"{source_dir()}/{path}" joins in normal loft; just pass the relative path.
(Do the explicit join only when handing a path to a non-loft consumer, e.g. a
native asset loader that reads the filesystem directly.)
A program that must resolve a user-supplied relative path against the working
directory (CLI tools — loft tidy.loft data.csv) declares #cwd as the
file-top directive (before the first declaration). LOFT_PATHS=program|cwd
overrides per-invocation.
Text files (UTF-8)
f = file("path/to/file.txt");
content = f.content(); // full text content (UTF-8)
lines = f.lines(); // vector<text> of lines
out = file("output.txt");
out.write(content);
dir = file("some/directory");
for ef in dir.files() {
path = ef.path;
}
if f.exists() { }
size_bytes = f.size; // integer (i64) — works for any file
f.content() is UTF-8-only. It silently returns "" on a
binary file. For non-text data, use the binary idiom below.
Binary files (structured reads and writes)
Set f#format to LittleEndian or BigEndian, then use f#read
for reads and f += value for writes. #next seeks to an
absolute byte offset. All file-handle operations should live
inside a { ... } scope block so the handle flushes/closes at
block exit:
// --- Read a 12-byte GLB header ---
{
f = file("model.glb");
f#format = LittleEndian;
magic = f#read as i32; // 0x46546C67 = 'glTF'
version = f#read as i32;
total = f#read as i32; // declared file length
// Seek past the header + JSON data to a later chunk:
f#next = (20 + json_len) as integer;
bin_len = f#read as i32;
}
// --- Write a binary chunk-structured file ---
{
f = file("model.glb");
f#format = LittleEndian;
f += (0x46546C67 as i32); // 4 bytes: i32 magic
f += (2 as i32); // 4 bytes: i32 version
f += (32 as u8); // 1 byte (ASCII space)
f += "chunk of text"; // raw UTF-8 bytes
f += my_float_vector; // vector<single> → 4 bytes per element
}
Notes:
Prefer f#read as <type> (no parens) for fixed-width reads.
The byte count is inferred from the type — as i32 reads 4
bytes, as u8 reads 1, as u16 reads 2, as integer reads 8.
The legacy f#read(n) as T form still works but the (n) must
match the type's storage width exactly or the runtime panics in
src/database/io.rs:276. The inferred form makes that mismatch
impossible. as text still needs f#read(n) as text because
text has no fixed width.
s.field = f#read (no as T) infers width from the LHS field's
declared type — symmetric with f += s.field. For a struct
S { a: i32, b: u8, c: u16 }, both sides become:
f += s.a; f += s.b; f += s.c to write, s.a = f#read; s.b = f#read; s.c = f#read to read. Changing a field's declared type
(i32 → i64) automatically updates both sites at the next compile —
no manual cast edits needed.
Always cast scalar writes to the intended width. Bare
f += int_var writes 8 bytes (loft stores integers as i64). To
write 4 bytes use f += (int_var as i32); for 1 / 2 bytes use
as u8 / as u16. Strongly-typed struct fields (u8, u16, or a
range-limited integer limit(0, 255)) write at their declared width
automatically.
f += expr appends expr to the file, respecting the #format
endianness. text → raw bytes, vector<T> → each element in
sequence at its declared width.
f.size returns an integer (i64); compare with 0.
f#next = offset as integer seeks. Reading position advances
automatically after each f#read — don't manually advance it
between sequential reads.
No f.bytes() API — there's no "read all N bytes into a
vector" helper. If you need the whole buffer, call f#read(n)
in a loop or read into a typed record via OpReadFile.
Example binary reader/writer patterns live in
lib/graphics/src/glb.loft (writer) and
lib/graphics/tests/glb.loft (reader).
Warning-clean idioms (LOFT_DENY_WARNINGS=1)
When LOFT_DENY_WARNINGS=1 (set by the canonical chunk-repo
library-ci.yml), three idioms surface repeatedly during a clean-up
sweep. These are the patterns to reach for first. Sourced from the
loft-libs-core::arguments sweep, 2026-05-30.
Vector fields are non-null ([]) by default — no not null needed
Obsolete under @PLN25 DN1. A plain vector<T> field is already non-null
and defaults to [], and reading a non-null field never triggers the old
@PLN46 "read N times and never defended" warning (that warning only ever
concerned NULLABLE fields, and there are none by default now). So just
declare the field plainly:
Write vector<T>? only when the field must genuinely be able to hold null
(distinct from empty). The not null modifier still parses but is a retired
no-op — don't add it.
Capture-into-local before indexing (skip-pattern 5)
The parser's skip-pattern 5 recognises if idx < len(vec) { … vec[idx] … }
and silences the v[i] may-be-null warning inside the then-block.
The pattern only matches when vec is a bare local Var, not a
struct-field deref. So if i < len(self.results) { self.results[i] }
does NOT match. Capture into a local first:
// BAD — warning fires on self.results[i]:
if i < len(self.results) {
self.results[i] = "true";
}
// GOOD — capture self.results into `results`, then bound-guard:
results = self.results; // local Var; same backing vector
if i < len(results) {
results[i] = "true"; // skip-pattern 5 silences the warning
}
The local aliases the same underlying vector, so indexed writes
propagate. Field-level writes still go through self.field (the
capture's slot doesn't track appends).
When the value can legitimately be null and the consumer checks
if !val { … }, the warning text suggests x = v[i]; if x != null { … }
as one of the safe forms. Use this when ?? defaults would change
semantics (e.g. ?? "" collapses null and empty-string into the
same path):
// BAD — warning fires on self.results[mi]:
if !self.results[mi] {
self.err = "Required option missing";
return false
}
// GOOD — capture and null-check, preserves the "missing → null" contract:
results = self.results;
if mi < len(results) {
val = results[mi];
if val == null {
self.err = "Required option missing";
return false
}
}
The capture into a local is required (for skip-pattern 5 to recognise
the bound guard); the null check then satisfies the parser's "x = v[i];
if x != null" hint.
Why these idioms specifically
The warning text itself names three fixes for v[i]:
v[i] ?? <fallback>, if i < len(v) { v[i] }, or
x = v[i]; if x != null { ... }. The three idioms above are
when-to-reach-for-which:
?? fallback — use when a non-null sentinel makes sense
(e.g. ?? Pixel{r:0,g:0,b:0}). Changes runtime behaviour:
on OOB you get the sentinel back instead of null.
if i < len(v) bound — use when the access is index-bounded
in practice but the parser can't see it. Requires bare-Var vec
(capture into a local). Zero-cost — dead-code guard the optimizer
drops when the bound is provable.
capture-and-null-check — use when the value is genuinely
nullable and the consumer's contract is "missing → null".
Preserves the null semantics.
Known error messages → fixes
Error message
Fix
Too few parameters on n_<fn>
Per-function name collision — give the loop/local a name distinct from the function's params; avoid for in const vector<T> recursive fns
Variable <x> is never read
A warning (program still runs, exit 0) — use the variable, or name an unused loop var _
loop variable 'i' has type … but was previously used as …
Two same-function loops over different element types share one name — give them distinct names
Indexing a non vector
You indexed a scalar (x = 5; x[0]) — index a vector/collection, not a single value
Not implemented operation = for type null
A local named null (a literal keyword) — rename it
Cannot iterate a hash directly
Track aggregate separately
Undefined type string
Use text, not string
Allocating a used store
Field named key in hash-value struct — rename the field
<fn> is not found for say(...)
Use println()
Cannot pass a literal or expression to a '&' parameter
Assign to a named variable first, then pass it. v[i] and s.field work directly (P160).
match arm separator is \=>`, not `->``
Replace -> with => in the arm. (P206 — was a parser hang before the recovery helper landed.)
'fn' definitions must be at file scope, not inside a function or block
Move the helper fn out of the enclosing fn body. Lambdas (`
compound assignment is not supported for tuple destructuring — use (a, b) = expr instead
Rebuild the tuple: (a, b) = (a + 1, b + 2) — or update each element directly.
Native E0308 on t.0 == 'a' where t is (character, …)
Fixed (P207, 2026-05-04) — if seen on an old build, update loft; current builds compile this on both backends.
