Language Features

Complete reference for Loxel v2 — a modern, expression-oriented language with optional static typing, multilingual keywords, and built-in concurrency.

The statuses listed on the page are for developers only, and do not reflect the delivered binary. Everything is currently in beta, and subject to change.

✅ Working — Fully functional in all modes ⚠️ Partial — Works in some modes 🚧 In Progress — Under active development 📋 Planned — Designed but not started

Variables & Constants ✅ Working

Use let for mutable variables and const for immutable constants. Type annotations are optional; Loxel infers types automatically.

Example

variables.lox
// Mutable variable — inferred as Number
let count = 0;
count += 1;

// Explicit type annotation
let name: String = "Alice";
let active: Boolean = true;
let score: Number = 99.5;

// Immutable constant
const PI = 3.14159;
const MAX_SIZE = 100;

// Constants cannot be reassigned
// PI = 3.14;  // ❌ ERROR: Cannot reassign constant

// Optional nullable type
let email: String? = nil;  // Can be String or nil
email = "alice@example.com";

Comments ✅ Working

Three comment styles: // single-line, /* */ multi-line (nestable), and /** */ documentation comments.

Example

comments.lox
// Single-line comment
let x = 5;  // Inline comment

/* Multi-line comment
   that spans several lines */

/**
 * Calculates the sum of two numbers.
 * @param a  First number
 * @param b  Second number
 * @return   Sum of a and b
 */
def sum(a: Number, b: Number): Number {
    return a + b;
}

Keywords: Strict vs Contextual ✅ Working

Loxel splits its keywords into two classes (the C#/TypeScript/Kotlin tradition). Hard (strict) keywords always mean their grammar construct and can never name a variable, parameter, function, or class — binding one is an immediate parse error. Contextual keywords only act as keywords in their exact grammar position; everywhere else they are ordinary identifiers.

Hard (24): if else for while break continue return throw try catch match await typeof def class let const import export true false nil self super

Contextual (21): as from in is extends implements uses case default static readonly public private protected async unsafe namespace type struct interface trait

Two extra rules: member position is always free — after ., in field declarations, and as map keys, every keyword (hard ones included) is an ordinary name. And all translations of a keyword behave identically: Spanish si is exactly as reserved as if, while tipo is exactly as bindable as type — and builtins like .namespace respond to every language's spelling. print is no longer a keyword at all — it is a builtin function (print(x), any language spelling), so let print = 42; binds and reads normally.

Example

keywords.lox
// Contextual keywords are ordinary identifiers
let type = "user";           // ✅ binds and reads
let from = 3;
def uses(x) { return x * 2; }

// Hard keywords never bind — clear error, in any spelling
let match = 3;               // ❌ 'match' is a reserved keyword — it cannot be used as a name
let si = 5;                  // ❌ 'si' is a spelling of the reserved keyword 'if' — ...

// Member position is free for ALL keywords
let m = {};
m["match"] = 1;              // ✅ map key
self.class;                  // ✅ builtin: the class definition
obj.if;                      // ✅ ordinary property

// i18n equivalence reaches builtins too
widget.class.namespace;      // "myapp::widgets"
widget.class.namensraum;     // same (German spelling)

Expressions & Blocks ✅ Working

Everything in Loxel is an expression that returns a value — if, match, try, and blocks all yield results.

Example

expressions.lox
// Block expression — returns last expression
let result = {
    let x = compute();
    let y = process(x);
    x + y   // this value is returned
};

// if as expression
let max = if (a > b) a else b;

// match as expression
let grade = match score {
    case 90..=100 => "A"
    case 80..=89  => "B"
    case 70..=79  => "C"
    case _        => "F"
};

// try as expression
let data = try { parse(input) } catch (e) { default_value };

// Ternary
let label = count == 1 ? "item" : "items";

// Comprehension (also an expression)
let squares = [x * x for x in 1..11];

Only a bare trailing expression becomes the block's value — a trailing def is a declaration, not an expression, so it is not picked up:

block-gotcha.lox
let aFunction = {
    let count = 0;
    def fromJson(json) { return 1; }
};
print(aFunction);  // nil — the last statement is a declaration, not an expression

let aFunction = {
    let count = 0;
    def fromJson(json) { return 1; }
    fromJson  // bare identifier reference — THIS is the trailing expression
};
print(aFunction);  // <function fromJson>

Strings & HEREDOC ✅ Working

Backtick strings and HEREDOC both interpolate with ${}. HEREDOC (<<<END) just lets that span multiple lines. The nowdoc form (<<<'END') treats ${} as literal text instead of interpolating it. In a backtick string, a backslash escapes the ` and the ${ — see below.

String interpolation

strings.lox
let name = "Alice";
let age = 30;

// Backtick interpolation
let message = `Hello, ${name}! You are ${age} years old.`;

// Expressions inside ${}
let result = `Sum: ${10 + 20}, Product: ${5 * 4}`;

// Nested properties
let user = { name: "Bob", score: 100 };
let text = `User ${user.name} scored ${user.score} points!`;

Escaping ` and ${

A run of backslashes immediately in front of a $ follows parity: pairs collapse, and an odd leftover escapes the ${. That position is the only one where backslashes behave differently, because it is the only one where they are about interpolation.

escapes.lox
const world = 'yolo';

`hello ${world}`          // hello yolo
`hello \${world}`         // hello ${world}
`hello \\${world}`        // hello \yolo
`hello \\\${world}`       // hello \${world}

// A $ that does not open a ${...} is not functional, so the
// backslashes in front of it were never escaping anything.
`hello $world`            // hello $world
`hello \$world`           // hello \$world
`hello \\$world`          // hello \\$world

// Same when the ${ has no closing } — nothing to escape.
// (A LIVE ${ with no closing brace is still a compile error.)
`hello \\\${world`        // hello \\\${world

// Away from a $, the ordinary escapes apply untouched.
`a \` b`                  // a ` b
`C:\\path`                // C:\path
`a\\nb`                   // a\nb
`a\db`                    // a\db   unknown escapes keep their backslash

// Quoted strings never interpolate, so ${ is inert and needs
// no escape there.
"a ` b ${x}"              // a ` b ${x}

// Braces inside the expression are matched with awareness of
// string literals and comments.
`hello \\${world + '}'}`  // hello \yolo}
`${ 1 /* } */ + 2 }`      // 3

HEREDOC multi-line strings

heredoc.lox
// HEREDOC — supports ${} interpolation
let title = "Report";
let template = <<<END
    Sales Summary
    =============
    Period: ${start} to ${end}
    Total: ${format_currency(total)}
END;

// Nowdoc — ${} is NOT interpolated (raw string)
let pattern = <<<'REGEX'
Amount: ${value}
REGEX;
// pattern is the literal text  "Amount: ${value}"

Character-aware indexing & byteLength (v3.5.0)

unicode.lox
// Strings index by CHARACTER (Unicode code point) — i18n-first.
"日本語".length()        // 3   characters, not 9 bytes
"日本語".charAt(1)       // "本" a whole character, never a fragment
"日本語".indexOf("本")   // 1   character index — composes with substring
"a😀b".substring(1, 2)   // "😀"

// byteLength() is the UTF-8 wire size — what Content-Length,
// buffers and byte-oriented protocols need.
"日本語".byteLength()    // 9
"hello".byteLength()     // 5   (ASCII: same as length())

Control Flow ✅ Working

Standard if/else, while, C-style for, range-based for-in, and comprehensions. (do-while is 📋 planned.)

Example

control-flow.lox
// if / else
if (age >= 18) {
    print("Adult");
} else if (age >= 13) {
    print("Teen");
} else {
    print("Child");
}

// while
let i = 0;
while (i < 10) { print(i); i += 1; }

// For-in (range and collection)
for (i in 0..5) { print(i); }          // 0 1 2 3 4
for (num in [10, 20, 30]) { print(num); }

// Key-value map iteration
let ages = {"Alice": 30, "Bob": 25};
for (name, age in ages) { print(`${name}: ${age}`); }

// Comprehension
let evens = [x for x in 1..11 if x % 2 == 0];

// break / continue
for (let i = 0; i < 10; i = i + 1) {
    if (i == 5) continue;
    if (i == 8) break;
    print(i);
}

Type Annotations ✅ Working

Types are optional but recommended for public APIs. Loxel supports three type-checking modes: OFF, WARN, and STRICT.

Primitive types & inference

types.lox
// Primitive types
let count: Number  = 0;
let label: String  = "hello";
let flag:  Boolean = true;
let empty: Nil     = nil;

// Type inference — no annotation needed
let x = 5;       // inferred: Number
let y = "test";  // inferred: String

// Function parameter and return types
def add(a: Number, b: Number): Number {
    return a + b;
}

// Optional / nullable (shorthand for T | Nil)
let name: String? = nil;

// Type aliases
type UserId = Number;
type UserName = String;
let id: UserId = 123;

Function (callable) types

A function type (A, B) => R can be written inline on a parameter, aliased with type, applied to a binding, and nested inside other types (Map<String, MathOp>). In the native compiler the signature is enforced at compile time — both when a function is assigned to a function-typed binding and when a value is called through such a type. Enforcement is best-effort and conservative: arity is always checked; parameter types are checked when the lambda annotates them (an unannotated (a, b) => … infers Any params — Loxel has no contextual typing); the return type is checked when annotated or inferable; lambdas with default or rest parameters stay permissive. The VM/tree-walker do not run the static checker, matching every other typed-binding contract.

callable-types.lox
// A function-type alias
type MathOp = (Number, Number) => Number;

// Applied to a binding, then called
let add: MathOp = (a, b) => a + b;
print(add(3, 4));   // 7

// Inline function type on a parameter (higher-order)
def apply(fn: (Number) => Number, x: Number): Number {
    return fn(x);
}
print(apply((n) => n * 2, 21));   // 42

// Composed inside another type
let ops: Map<String, MathOp> = { add: (a, b) => a + b };
print(ops["add"](2, 3));   // 5

// Native compile-time signature enforcement:
// let bad: MathOp = (a) => a;   // ❌ wrong arity
// add(3);                       // ❌ expects 2 arguments, got 1
// add("x", 1);                  // ❌ argument 1 is String, expects Number

Exact types & checked narrowing

exact-types.lox
// `Number` admits any subclass (class Meters < Number); `Number!` is
// exactly the primitive — the form the native compiler can unbox.
// Exactness is mostly inferred: literals, arithmetic on exact operands
// and constructions are exact, and an annotated binding keeps the proof.
let a: Number! = 5;
let b: Number! = a * 2 + 1;
let c: Number = 7;          // declared Number, currently proven Number!
let d: Number! = c;

// An open value needs the checked cast, which throws for a subclass:
def total(): Number { return 1; }
let e: Number! = total() :> Number!;

// `Any` never satisfies a concrete slot by itself; `:>` narrows it.
def opaque(x) { return x; }
let n: Number = opaque(1) :> Number;

// A nil test narrows an optional on the path it proves.
def shout(s: String): String { return s + "!"; }
def greet(name: String?): String {
    if (name == nil) { return "nobody"; }
    return shout(name);        // name is a String here
}

Generics ✅ Working

Generic classes and functions use <T> type parameters. Type bounds use extends. Since v3.4.0 a superclass reference can carry type arguments (class Orders < Map<String, Number>) — closing, forwarding, or partially closing the parent's parameters — with wrong arity or bound violations reported as clear errors. Works in the tree-walker, bytecode VM, and native/LLVM backend. Box<Number> is a first-class parameterized-class value in all three modes — it can be aliased, passed around, and called later (including with named constructor arguments). Method-level type arguments (obj.method<Number>(x)) are validated in all three modes: type-argument arity, declared bounds, and parameter types. Type arguments are erased for execution (as in most dynamically-typed languages) but recorded on instances for runtime checking of generic method parameters; the native backend additionally validates instantiation arity, non-generic misuse, and type bounds at compile time when the class is statically known, and at runtime otherwise.

Example

generics.lox
// Generic class
class Box<T> {
    def init(v: T) { self.value = v; }
    def get(): T   { return self.value; }
}

let intBox = Box<Number>(42);
let strBox = Box<String>("hello");

// Multiple type parameters
class Pair<K, V> {
    def init(k: K, v: V) {
        self.key = k;
        self.value = v;
    }
}

let pair = Pair<String, Number>("age", 30);

// Type bounds
class NumberBox<T extends Number> {
    def double(): T { return self.value * 2; }
}

// Generic function
def first<T>(arr: Array<T>): T { return arr[0]; }

// Nested generics
let matrix: Array<Array<Number>> = [[1, 2], [3, 4]];

// Parameterized superclasses (v3.4.0) — a subclass can pass type
// arguments to its parent: close them, forward its own, or partially
// close. A general feature of any generic hierarchy; the core classes
// declare parameters too (Map<K, V>, Array<T>).
class NumberBox2 < Box<Number> { }        // closed for every instance
class Cache<K, V> < Map<K, V> { }   // forwarded
class Half<V> < Map<String, V> { }     // partially closed

// Inherited generic signatures check against the bound types:
let nb = NumberBox2();
nb.set(5);        // ok — inherited set(v: T) with T = Number
// nb.set("no");  // Type mismatch: expected Number, got String
// class Wrong < Map<String> {}  // ERROR: Map expects 2 type
//                                     // argument(s) (K, V) but got 1

Union & Optional Types ✅ Working

Union types express "this OR that" with |. T? is shorthand for T | Nil.

Example

union-types.lox
// Union type alias
type ID = String | Number;

def printID(id: ID) { print("ID: " + id); }
printID("abc123");  // ✅ OK
printID(42);        // ✅ OK

// Optional (nullable) shorthand
let email: String? = nil;
email = "user@example.com";  // ✅ OK
email = nil;                 // ✅ OK

// Function returning union
def find(id: Number): User | Error {
    let user: User? = db.get(id);
    return user ?? Error("Not found");
}

// Intersection types
type Admin = User & Permissions;

Classes ✅ Working

Classes use def init for constructors and self (not this) for the instance reference. The @field syntax is not supported in v2.

Example

classes.lox
class User {
    name:  String
    email: String
    age:   Number

    def init(name: String, email: String, age: Number) {
        self.name  = name;
        self.email = email;
        self.age   = age;
    }

    def describe(): String {
        return `${self.name} (${self.email})`;
    }

    def is_adult(): Boolean {
        return self.age >= 18;
    }
}

let user = User("Alice", "alice@example.com", 30);
print(user.describe());   // "Alice (alice@example.com)"
print(user.is_adult());   // true

// Static methods and fields (`static` comes before `def`/`let`/`const`).
// Statics live in their OWN namespace, so a static and an instance
// method may share a name (v3.4.0).
class MathUtils {
    static let callCount = 0;
    static def sqrt(x: Number): Number { /* ... */ }
}
MathUtils.sqrt(16);

// `Self` in a static = the class the call was made THROUGH (v3.4.0),
// so constructing statics return the invoked subclass:
class Model     { static def make() { return Self(); } }
class UserModel < Model { }
UserModel.make() is UserModel;   // true — no redeclaration needed

// Declared method names are RESERVED on instances (v3.4.0): a field
// assignment that would shadow a declared (or inherited) method raises
// at the assignment site, so duck typing can rely on a class's interface.
// user.describe = "oops";   // ERROR: Cannot assign field 'describe' on
//                           // User: it would shadow method 'describe'
//                           // declared by class 'User'
// (Map and its subclasses are exempt — data must keep winning there.)

Inheritance ✅ Working

Single inheritance with <, or its alias extends (accepted in class headers since #907; it also remains the generic type bound, <T extends Number>). Use super.init() to call the parent constructor and super.method() to call overridden methods.

Example

inheritance.lox
class Vehicle {
    def init(brand: String) { self.brand = brand; }
    def description(): String { return "A vehicle from " + self.brand; }
}

class Car < Vehicle {
    def init(brand: String, model: String) {
        super.init(brand);      // chain parent constructor
        self.model = model;
    }

    def description(): String {
        return super.description() + ", model " + self.model;
    }
}

let car = Car("Toyota", "Camry");
print(car.description());
// "A vehicle from Toyota, model Camry"

Interfaces & Traits ✅ Working

Interfaces define contracts. Traits (mixins) provide reusable implementation. A class implements interfaces and uses traits.

Interface

interfaces.lox
interface Drawable {
    def draw(): void;
    def area(): Number;
}

// `implements` is a clause INSIDE the class body (before fields/methods)
class Circle {
    implements Drawable;
    def init(r: Number) { self.radius = r; }
    def draw(): void { print("Drawing circle"); }
    def area(): Number { return 3.14159 * self.radius * self.radius; }
}

Traits (mixins)

traits.lox
trait Loggable {
    def log(message: String) {
        print("[LOG] " + message);
    }
}

trait Timestamped {
    def get_age(): Number {
        return DateTime.now() - self.created_at;
    }
}

// Use multiple traits — `uses` is a clause INSIDE the class body
class Article {
    uses Timestamped, Loggable;
    def init(title: String) {
        self.title = title;
        self.created_at = DateTime.now();
        self.log("Article created: " + title);
    }
}

Property Promotion ✅ Working

Annotate constructor parameters with visibility/mutability modifiers to auto-create fields. Supported in the tree-walker, bytecode VM, and native/LLVM backend.

Example

promotion.lox
// Parameters prefixed with visibility become fields automatically
class User {
    def init(public name: String, public email: String) {
        // self.name and self.email are auto-created
    }
}

let user = User("Alice", "alice@example.com");
print(user.name);   // "Alice"

// With readonly and private, plus default values
class BankAccount {
    def init(
        public readonly account_number: String,
        private balance: Number = 0
    ) {}

    def deposit(amount: Number) {
        self.balance += amount;
    }
}

Visibility Modifiers ✅ Working

public (default), private, and protected control access to fields and methods. Enforced in all three modes, including the native/LLVM backend. Native (and the tree-walker) raise catchable errors; the bytecode VM raises the same messages but treats them as fatal. Note on inheritance: native resolves the calling class lexically, so a base-class method (e.g. via super.init) can always touch the base's own private/protected fields, and subclasses can access inherited protected (but not private) fields — the tree-walker and VM currently derive the calling class dynamically and each rejects one of those base-method patterns.

Example

visibility.lox
class BankAccount {
    public  let balance:        Number
    private let account_number: String

    def init(bal: Number, acct: String) {
        self.balance        = bal;
        self.account_number = acct;
    }

    // Private — internal use only
    private def hash_acct(): String { return /* ... */ ""; }

    // Protected — accessible by subclasses
    protected def audit_log(msg: String) { print("[AUDIT] " + msg); }
}

let account = BankAccount(1000, "ACC-123");
print(account.balance);          // ✅ public
// print account.account_number // ❌ Runtime error: Cannot access private field

Operator Overloading ✅ Working

Define a method whose name is the operator symbol — def +(other) — to customize behavior for +, -, *, **, /, %, ==, !=, <, >, <=, >=, <=>, the bitwise |, &, ^, <<, >>, and the unary -@ / !.

Example

operator-overloading.lox
class Vector {
    def init(x: Number, y: Number) {
        self.x = x;
        self.y = y;
    }

    def +(other: Vector): Vector {
        return Vector(self.x + other.x, self.y + other.y);
    }

    def *(scalar: Number): Vector {
        return Vector(self.x * scalar, self.y * scalar);
    }

    def ==(other: Vector): Boolean {
        return self.x == other.x && self.y == other.y;
    }
}

let v1 = Vector(3, 4);
let v2 = Vector(1, 2);
let v3 = v1 + v2;   // Vector(4, 6)
let v4 = v1 * 2;    // Vector(6, 8)

if (v1 == Vector(3, 4)) { print("Equal!"); }

Compound-assignment contract: in-place += vs. allocating +

A class may also define +=, -=, *=, /=, or %= directly, distinct from its +-style method — mirroring Python's __iadd__ vs. __add__. x += y tries the class's own += method first (mutate self in place, no allocation) and falls back to + when += isn't defined.

compound-overload.lox
class Vector {
    def init(x: Number, y: Number) { self.x = x; self.y = y; }

    def +(other: Vector): Vector {
        return Vector(self.x + other.x, self.y + other.y);  // allocates
    }

    def +=(other: Vector): Vector {
        self.x += other.x;
        self.y += other.y;
        return self;  // mutates in place
    }
}

let v = Vector(1, 2);
let alias = v;      // same object
v += Vector(3, 4);  // calls +=, mutates v (and alias) in place
print(alias.x);      // 4 — alias sees the mutation

let w = v + Vector(1, 1);  // calls +, allocates a new Vector
print(v.x);                 // 4 — v itself untouched by +

Decorators ⚠️ Partial

Decorators wrap functions, classes, or methods. The native compiler implements the full surface: user function decorators (stacking, decorated recursion — the @memoize fibonacci pattern — and use as values), class decorators, user-defined method decorators, and the built-in method decorators @cached/@deprecated/@logged/@timed; still-unsupported decorators (@computed, @onInherit) emit a compile-time warning instead of silently dropping. Method-decorator convention: the decorator receives the unbound method — the receiver is its explicit first parameter (any name; self is a keyword) — and returns a callable invoked as (receiver, args...); decorations inherit to subclasses and compose under the built-ins (@cached memoizes the wrapped call). Earlier interpreted-mode gaps are resolved: the VM applies user function decorators (stacking, factory form) and user method decorators (#399 fixed), and the tree-walker applies function and class decorators; @cached hits no longer corrupt the VM stack and @deprecated("reason") reasons are preserved. The remaining gap is the tree-walker's user method decorators: it calls the wrapper without the receiver, so the unbound convention breaks there (#947; built-ins work in all three modes).

Example

decorators.lox
// Decorator: takes the function, returns its replacement (use arrows)
def performance(fn) {
    return (x) => {
        let start = Time.now();
        let result = fn(x);
        print(`took ${Time.now() - start}ms`);
        return result;
    };
}

@performance
def slow_function(n) { let s = 0; for (i in 0..n) { s = s + i; } return s; }

slow_function(100000);  // prints timing info

// User-defined memoization — decorated RECURSION goes through the wrapper
def memoize(fn) {
    let cache = {};
    return (n) => {
        let k = "" + n;
        if (cache.has(k)) { return cache.get(k); }
        let r = fn(n);
        cache.set(k, r);
        return r;
    };
}
@memoize
def fibonacci(n) {
    if (n <= 1) { return n; }
    return fibonacci(n - 1) + fibonacci(n - 2);   // memoized recursion
}
fibonacci(30);   // 832040, linear time

// Class decorator: receives the class, returns its replacement
def Singleton(cls) { return cls; }
@Singleton
class Config { def init() { self.settings = {}; } }

// METHOD decorator: receives the UNBOUND method — the receiver is its
// explicit first parameter (any name; `self` is a keyword)
def clamp(maxv) {
    return (fn) => {
        return (me, x) => {
            let r = fn(me, x);
            if (r > maxv) { return maxv; }
            return r;
        };
    };
}
class Meter {
    def init() { self.base = 10; }
    @clamp(100)
    def scale(x) { return self.base * x; }
}
Meter().scale(50);   // 100 (clamped)

Match Expressions ✅ Working

Nine pattern types: literal, variable, wildcard, array, object/map, type, range, guard, and OR. Works in all modes, including the array rest sub-pattern ([head, ...tail], promoted to the VM and native by #946) — the rest binds the remaining elements as a new array, and guards can reference it.

Core patterns

patterns.lox
// Literal, wildcard, and variable binding
match x {
    case 0    => "zero"
    case 1    => "one"
    case n    => "got: " + n   // binds to n
}

// Range patterns (inclusive ..= and exclusive ..)
match score {
    case 90..=100 => "A"
    case 80..=89  => "B"
    case 70..=79  => "C"
    case _        => "F"
}

// OR patterns
match day {
    case "Saturday" | "Sunday" => "weekend"
    case _                     => "weekday"
}

// Array patterns with rest
match arr {
    case []           => "empty"
    case [x]          => "one item: " + x
    case [head, ...t] => "head=" + head
}

// Object/map destructuring with guard
match user {
    case { age: a, name: n } if a >= 18 => "Adult: " + n
    case { age: a, name: n }            => "Minor: " + n
}

// Type patterns
match value {
    case n: Number => "Number: " + n
    case s: String => "String: " + s
}

Match as expression with complex example

match-expr.lox
// Match is an expression — assign its result
let category = match age {
    case n if n < 13  => "child"
    case n if n < 18  => "teenager"
    case _            => "adult"
};

// Comprehensive request handler
def process_request(request) {
    match request {
        case nil                              => "No request"
        case { type: "user", id: uid } if uid > 0 => load_user(uid)
        case ["batch", ...items]              => process_batch(items)
        case { status: "pending" } | { status: "processing" } => queue_request(request)
        case _                                => "Unknown request"
    }
}

Operators ✅ Working

Arithmetic (incl. exponentiation **), bitwise (| & ^ << >>), comparison (incl. strict === / !==), membership (~> / <~, Unicode ∈ ∋ ∉ ∌), logical, assignment, null-handling, pipeline, spread, and type-checking operators.

The ? family, one rule: thirteen constructs spell “this operand might not be what you want” — access (?. ?.[] ?.() T?), choice (? : ?: ??), conditional assignment (??= ?= =?? =?), and railway (?> ?!). In every one, the ? sits next to the operand being questioned, so the symbol itself tells you what gets tested. The assignment and railway forms are detailed below; access and Result behavior have their own sections.

All operators quick reference

operators.lox
// Arithmetic
5 + 3  // 8    5 - 3  // 2    5 * 3  // 15
6 / 3  // 2    7 % 3  // 1    2 ** 8 // 256

// Bitwise — ✅ native (compiled) mode, v2.25.0; VM and tree-walker report
// a clear "not yet supported" error until promoted.
// 64-bit signed integer ops: Number operands truncate toward zero
// (saturating, NaN -> 0); result converts back to Number (exact within ±2^53).
12 | 3      // 15   — OR
255 & 15    // 15   — AND
5 ^ 3       // 6    — XOR (exponentiation is **, not ^)
1 << 10     // 1024 — left shift
-16 >> 2    // -4   — right shift is ARITHMETIC (sign-propagating)
1 << 64     // 1    — shift counts mask to 0..63 (x86/JS style)

// Rust-style precedence — every bitwise level binds TIGHTER than
// comparison, so the C footgun doesn't exist:
2 | 4 == 6           // true — (2 | 4) == 6, not 2 | (4 == 6)
flags & MASK == MASK // (flags & MASK) == MASK

// There is no bitwise NOT ~ (the character is reserved by membership ~>)
x ^ -1      // 64-bit complement instead

// In TYPE position | and & still mean union/intersection, and in match
// PATTERNS | still means or-patterns — those parse separately.
// All five are overloadable: def |(other) ... def >>(other).

// Comparison
5 == 5   // true    5 != 3  // true
5 === 5  // true — strict: built-in comparison only, never dispatches
5 !== 6  // true    def == / def != overloads; heap values by identity
5 <=> 3  // 1  (spaceship: -1 | 0 | 1)
"a" <=> "b"  // -1 (spaceship works on strings)

// Ordered comparison on Strings — ✅ working (all three modes, v3.24.0)
// Byte-order (UTF-8) comparison; never numeric coercion
"2027-01-31" < "2028-02-14"  // true — ISO dates sort correctly
"Z" < "a"     // true — codepoint order (uppercase first)
"1e10" < "9"  // true — byte '1' < '9'; strings never coerce to numbers
"abc" < 5     // ERROR — operands must both be Numbers or both be Strings

// Logical
age >= 18 && has_license   // AND
is_admin  || is_moderator  // OR
!is_banned                 // NOT

// Assignment
count += 1;  count -= 1;  count *= 2;
self.balance += amount;     // properties too
arr[0] += 10;               // and array/map elements
config ??= get_default();   // assign only if nil (short-circuits: rhs not
                             // evaluated, no write, when config isn't nil)
// Four conditional assignments — the ? sits on the operand questioned:
name  ??= fallback();       // guards name: assign if name is nil
name   ?= fallback();       // guards name: assign if name is falsy
name  =?? lookup(user);     // guards value: assign if lookup() is non-nil
name   =? lookup(user);     // guards value: assign if lookup() is truthy

// Null-handling
let name  = user.name ?? "Anonymous";    // null coalesce
let city  = user?.address?.city;         // optional chain
let label = title ?: "Untitled";         // Elvis: falls back on ANY falsy value

// ?? and ?: are NOT synonyms. Falsy is nil, false, 0, and EMPTY containers
// ("", [], {}) — the Python-style rule, not JavaScript's.
0     ?? "d";   // 0      — only nil falls back
0     ?: "d";   // "d"    — 0 is falsy
false ?: "d";   // "d"
""    ?: "d";   // "d"    — empty string is falsy
""    ?? "d";   // ""     — but it is not nil
[]    ?: "d";   // "d"    — empty array is falsy

// The ? marks the guarded operand. Left of = guards the TARGET (and
// short-circuits); right of = guards the VALUE (always evaluated).
let a = 0; a ??= 9;   // 0  — a is not nil, so kept
let b = 0; b  ?= 9;   // 9  — a falsy target IS filled
let c = 1; c =?? 0;   // 0  — 0 is non-nil, so assigned
let d = 1; d  =? 0;   // 1  — 0 is falsy, so skipped

// With Result values, both unwrap Ok first — then ?: applies truthiness to the
// PAYLOAD, so the two disagree exactly when the payload is falsy:
Ok(5)    ?: "d";   // 5     unwraps; payload truthy
Ok(0)    ?: "d";   // "d"   unwraps; payload FALSY
Ok(0)    ?? "d";   // 0     unwraps; nil-ness decides, so 0 is kept
Err("e") ?: "d";   // "d"
Err("e") ?? "d";   // "d"

let d = 1;   d  ?= Ok(0);   // 1    (Ok(0) unwraps to a falsy 0)
let e = 1;   e  ?= Ok(9);   // 9
let f = nil; f ??= Ok(0);   // Ok(0) — ??= does NOT unwrap: its guard is on the
                            //         TARGET, so the right side is stored raw

// Railway (Result values — see Error Handling section)
let res  = Ok(x) ?> parse ?> validate;   // bind: Err skips remaining stages
let val  = load()?!;                     // propagate: Ok unwraps, Err early-returns

// Ternary
let status = age >= 18 ? "adult" : "minor";

// Pipeline — left value passed to right function's FIRST argument.
// x |> f is exactly f(x): pure parse-time sugar, no runtime identity.
// Left-associative — a |> f |> g is g(f(a)).
let response = raw_request |> parse |> validate |> handle;

// Errors do NOT short-circuit or propagate. A stage that fails (runtime
// error, type error, or `throw`) raises and aborts the WHOLE pipe — later
// stages never run — identical to g(f(x)). Wrap the pipe in a try/catch
// expression to intercept, or use the failure-aware railway pipe ?> with
// Result values (see "Result & Railway Operators"):
let out = try { raw_request |> parse |> validate }
          catch (e) { fallback };

// Railway bind — Err short-circuits remaining stages as a VALUE, no throw
let res = Ok(raw_request) ?> parse ?> validate;   // Ok(...) or first Err(...)

// Propagate — unwrap Ok or early-return the Err from the enclosing function
def handle(req) { return Ok(parse_row(req)?!); }

// Spread / rest
let merged = [...defaults, ...overrides];
def log(level, ...messages) { /* ... */ }

// Type checking
if (value is Number) { print("It's a number"); }

// Membership — directional, language-neutral symbols (no English keyword):
//   value ~> container    "value is in container"     (Unicode: ∈)
//   container <~ value    "container contains value"  (Unicode: ∋)
if (age ~> 18..65)       { print("Working age"); }   // range: continuous interval
if (18..65 <~ age)       { print("Working age"); }   // same test, reversed
"b" ~> ["a", "b"]        // array element            // true
"host" ~> config         // map key                  // true
"ell" ~> "hello"         // substring                // true
age ∈ 18..65             // Unicode aliases: ∈ ∋ and negated ∉ ∌
70 ∉ 18..65              // true

Operator precedence (highest → lowest)

precedence.lox
// 1. Postfix:      ()  []  .  ?.  ?!  (calls, indexing, member access, propagate)
// 2. Exponent:     **  (right-associative; tighter than unary minus)
// 3. Unary:        !  -  typeof  await
// 4. Factor:       *  /  %
// 5. Term:         +  -
// 6. Shift:        <<  >>   (bitwise levels are Rust-style: all four sit
// 7. Bitwise AND:  &         between + - and ranges/comparisons, so
// 8. Bitwise XOR:  ^         a & b == c means (a & b) == c — no C footgun)
// 9. Bitwise OR:   |
// 10. Range:       ..  ..=
// 11. Comparison:  <  >  <=  >=  <=>  is  ~>  <~  (∈ ∋ ∉ ∌)
// 12. Equality:    ==  !=  ===  !==  (=== / !== skip operator overloads)
// 13. Logical AND: &&
// 14. Logical OR:  ||
// 15. Pipeline:    |>  ?>  (plain pipe and railway bind, same precedence)
// 16. Ternary:     ? :  (and if-expressions)
// 17. Coalesce:    ??  (nil)   ?:  (falsy) — same precedence, different guards
// 18. Assignment:  =  +=  -=  *=  /=  %=  ??=  ?=  =?  =??

let x = 5 + 3 * 2;       // 11 (not 16)
let y = 2 ** 3 ** 2;     // 512 (** is right-associative)
let w = -2 ** 2;         // -4  (** binds tighter than unary minus;
                         //      unary still allowed in the exponent: 2 ** -1 == 0.5)
let z = true || false && true;  // true (AND before OR)
let b = 1 << 3 | 1;      // 9  ((1 << 3) | 1 — shift before OR)
let m = 2 | 4 == 6;      // true ((2 | 4) == 6 — bitwise before comparison)

Functions & Parameters ✅ Working

Named functions with def, arrow shorthand, default parameters, named arguments (colon syntax only), rest parameters (PHP-style unified map), lambdas, and higher-order functions.

Function syntax overview

functions.lox
// Named function
def add(a: Number, b: Number): Number {
    return a + b;
}

// Arrow shorthand (single expression)
def double(x) => x * 2;
def max(a, b) => if (a > b) a else b;

// Default parameters
def greet(name, greeting = "Hello") {
    return `${greeting}, ${name}!`;
}
greet("Alice");            // "Hello, Alice!"
greet("Bob", "Hi");       // "Hi, Bob!"

// Named arguments (colon syntax)
def create_user(name, age, city) { /* ... */ }
create_user(city: "NYC", name: "Alice", age: 30);

// Rest parameters — unified Map (positional + named overflow)
def log(level, ...context) {
    print("[" + level + "]");
    for (k in context) { print(context[k]); }
}
log("ERROR", "detail1", "detail2");
log("ERROR", component: "DB", code: 500);

Lambdas, closures & higher-order functions

lambdas.lox
// Lambda
let square = (x) => x * x;

// Closure captures enclosing scope
def make_counter() {
    let count = 0;
    return () => { count += 1; return count; };
}

let counter = make_counter();
print(counter());  // 1
print(counter());  // 2

// Higher-order functions
let numbers = [1, 2, 3, 4, 5];
let squares = numbers.map((x)   => x * x);         // [1, 4, 9, 16, 25]
let evens   = numbers.filter((x) => x % 2 == 0);    // [2, 4]
let sum     = numbers.reduce(0, (a, b) => a + b);   // 15

// Pipeline with lambdas
const OnlyPositive = (vals) => vals.filter((n) => n > 0);
const DoubleAll    = (vals) => vals.map((n)    => n * 2);
let result = [-1, 2, 3] |> OnlyPositive |> DoubleAll;  // [4, 6]

Async / Await ✅ Working

Async functions return Promise<T>. await suspends execution until the Promise resolves. Use Promise.all for concurrent requests. Known tree-walker bug: a top-level await fn() currently runs the async body twice there (#948); the VM and native run it once.

Example

async.lox
async def fetch_user(id: Number): Promise<User> {
    let response = await http.get(`/api/users/${id}`);
    return parse_user(response);
}

// Concurrent requests with Promise.all
async def load_dashboard() {
    let [users, posts, comments] = await Promise.all([
        fetch_user(1),
        load_posts(),
        load_comments()
    ]);
    return { users, posts, comments };
}

// Error handling — try/catch style
async def safe_fetch(url: String) {
    try {
        let response = await http.get(url);
        return response.body;
    } catch (e) {
        return nil;
    }
}

// Error handling — chained Promise style
async def safe_fetch_chained(url: String) {
    return await http.get(url)
        .then((r) => r.body)
        .catch((e) => nil);
}

Channels & Spawn 🚧 In Progress

Channel-based concurrency and thread spawning. Channel and Thread.spawn/Thread.join work in the bytecode VM and native mode (the tree-walker cannot call them — #747); for await over a channel and a global spawn() are 📋 planned syntax, not yet parsed.

Example

channels.lox
// Buffered channel (not generic — capacity is the only argument)
let ch = Channel(10);

await ch.send(42);
let value = await ch.receive();  // 42
ch.close();

// Spawn a thread and hand results back through a channel
let out = Channel(1);
let t = Thread.spawn(() => { Channel.send(out, expensive_computation()); });
let result = await out.receive();
Thread.join(t);

// 📋 Planned: async iteration over a channel
// for await (item in ch) { print(item); }

// Worker pool pattern
def worker_loop(queue, id: Number): Nil {
    while (true) {
        let client = Channel.receive(queue);
        if (client == nil) return;
        TcpSocket.send_sync(client, handle(client));
    }
}

async def main(): Nil {
    let queue   = Channel(100);
    let workers = [Thread.spawn(() => worker_loop(queue, i)) for i in 0..4];
    let server  = TcpServer(8080);
    while (true) {
        Channel.send(queue, await TcpServer.accept(server));
    }
}

Enums 🚧 In Progress

Enums define a fixed set of named variants. Variants can carry associated data (like Rust enums) and work with pattern matching.

Example

enums.lox
// Simple enum
enum Status { Pending, Approved, Rejected }

let s = Status.Pending;

match s {
    case Status.Pending  => "Waiting"
    case Status.Approved => "Accepted"
    case Status.Rejected => "Denied"
}

// Enum with associated values
enum HttpResponse {
    Ok(body),
    NotFound,
    ServerError(code, message)
}

let res = HttpResponse.Ok("Success!");

match res {
    case HttpResponse.Ok(body)              => process(body)
    case HttpResponse.NotFound              => show_404()
    case HttpResponse.ServerError(code, msg) => log_error(code, msg)
}

Structs 📋 Planned

Structs are designed as value types — copied on assignment — for small, immutable data (Point, Color, Vec2). Design only today: the parser accepts comma-separated field declarations, but methods in a struct body and struct construction are not implemented in any backend yet (see issue #912). Use classes in the meantime.

Value semantics vs. class reference semantics

structs.lox
// DESIGN SKETCH — construction and struct methods are not implemented yet
struct Point {
    x: Number,
    y: Number,
}

let p1 = Point(x: 5, y: 10);
let p2 = p1;      // ← COPY (not a reference)
p2.x = 100;
print(p1.x);       // still 5 — p1 is unaffected

// vs. class (reference semantics)
class PointClass { public x: Number; public y: Number }
let pc1 = PointClass(); pc1.x = 5;
let pc2 = pc1;    // ← shared reference
pc2.x = 100;
print(pc1.x);      // 100 — both see the change

Destructuring ✅ Working

Extract values from arrays, maps, and structs using destructuring assignment and function parameter patterns.

Array & object destructuring

destructuring.lox
// Array destructuring
let [a, b, c] = [1, 2, 3];
let [first, ...rest] = [1, 2, 3, 4, 5];

// Swap variables
let x = 5; let y = 10;
[x, y] = [y, x];    // x=10, y=5

// Object destructuring
let { name, age } = { name: "Alice", age: 30 };

// Rename on destructure
let { name: userName, age: userAge } = user;

// Nested
let { user: { name, address: { city } } } = data;

// Function parameter destructuring
def print_point({ x, y }) {
    print(`(${x}, ${y})`);
}
print_point({ x: 5, y: 10 });

Arrays ✅ Working

Dynamic arrays with rich built-in methods. Slice with arr[1:3] (exclusive end), stride with arr[::2], reverse with arr[::-1], and select or filter numpy-style with fancy indexing (arr[[0, 2]] or a boolean mask). Since v3.4.0, sort/sortBy/reverse return a new array and leave the receiver untouched, and the comparator sort is a stable O(n log n) merge sort in every backend.

Array operations

arrays.lox
let nums = [1, 2, 3, 4, 5];
let typed: Array<String> = ["Alice", "Bob"];

// Access & mutate
nums.push(6);             // [1,2,3,4,5,6]
let last = nums.pop();    // 6
let first = nums[0];      // 1

// Slicing — [start:end] with exclusive end; open/negative bounds allowed
let slice = nums[1:3];    // [2, 3]
let tail  = nums[2:];     // [3, 4, 5]
let last2 = nums[-2:];    // [4, 5]

// Step slicing [start:end:step] (Python/numpy semantics)
let odds = nums[::2];     // [1, 3, 5]
let rev  = nums[::-1];    // [5, 4, 3, 2, 1]

// Fancy indexing — index arrays select, boolean masks filter
let picked = nums[[0, 2]];                     // [1, 3]
let big    = nums[nums.map((x) => x > 2)];  // [3, 4, 5]

// Iteration
for (n in nums) { print(n); }

// Functional methods
let squares = nums.map((x)   => x * x);
let evens   = nums.filter((x) => x % 2 == 0);
let sum     = nums.reduce(0, (a, b) => a + b);

// sort / sortBy / reverse return a NEW array — the receiver is untouched
// (v3.4.0). The comparator form is a stable O(n log n) merge sort.
let sorted     = nums.sort();                     // ascending numbers/strings
let descending = nums.sort((a, b) => b - a);   // comparator: >0 means a after b
let spans      = [{ "t": 10 }, { "t": 30 }];
let newest     = spans.sortBy((a, b) => b["t"] - a["t"]);
let backwards  = nums.reverse();
// Pitfall: a bare `nums.sort();` statement discards the result and
// changes nothing — always use the return value.

// Other useful methods
let min = nums.min();
let max = nums.max();
print(nums.contains(3));   // true
print(nums.length);        // 5

Maps ✅ Working

Key-value dictionaries with property shorthand, spread, and comprehensive methods including entries(), clear(), and empty(). Data keys always win over method names on dot access, so v3.4.0 added non-shadowable static forms (Map.keys(m), Map.fromEntries(pairs), …) for code that must survive arbitrary JSON — and Self in a static resolves to the class it was invoked through, so subclasses inherit constructing statics that build the subclass.

Map operations

maps.lox
let ages = { "Alice": 30, "Bob": 25 };

// Property shorthand
let name = "Charlie"; let age = 28;
let user = { name, age };   // { name: "Charlie", age: 28 }

// Access
let a = ages["Alice"];      // 30
let b = ages.get("Bob");    // 25

// Mutate
ages["David"] = 40;
ages.set("Eve", 22);
ages.delete("Charlie");

// Membership: value ~> container (or container <~ value; Unicode ∈ / ∋ also work)
if ("Alice" ~> ages) { print("Found"); }
if (ages.has("Bob")) { print("Also found"); }

// Iteration
for (name in ages) { print(name); }              // keys
for (name, age in ages) { print(`${name}: ${age}`); }  // pairs

// Collection methods. `delete` is the single canonical removal name
// (the short-lived `remove` alias was dropped in v3.4.0).
ages.keys();    // ["Alice", "Bob", ...]
ages.values();  // [30, 25, ...]
ages.entries(); // [["Alice", 30], ...]
ages.size();
ages.empty();
ages.clear();

// Statics — the NON-SHADOWABLE interface (v3.4.0). On a Map, dot access
// resolves DATA first, so a JSON key named "keys" buries the instance
// method; the static forms always work:
let body = { "keys": "user data", "a": 1 };
body.keys;              // "user data"  — data wins on dot access
Map.keys(body);         // ["keys", "a"] — cannot be shadowed
Map.values(body);
Map.entries(body);      // [["keys", "user data"], ["a", 1]]
let m2 = Map.fromEntries(Map.entries(body));   // round-trips

// `Self` makes fromEntries polymorphic over subclasses — the static
// constructs the class it was CALLED on:
class Orders < Map { }
let coffee = Orders.fromEntries([["Nicholas", "frappe"]]);
coffee is Orders;       // true — no redeclaration, no call-site type arg

Sets & Tuples ✅ Working

Sets store unique values with union/intersection/difference operations. Tuples (v3.4.0) are fixed-arity, immutable, per-position-typed sequences — a distinct core class with the array read surface (indexing, length, iteration, destructuring) and every mutator rejected.

Sets

sets.lox
// Construction takes no arguments; add() chains
let s = Set();
s.add(1).add(2).add(1);  // duplicate ignored
print(s.size());   // 2

if (s.has(1)) { print("Found 1"); }
s.delete(1);       // removal is delete(), matching Map

// Set operations
let a = Set().add(1).add(2).add(3);
let b = Set().add(3).add(4).add(5);
let union        = a.union(b);         // {1,2,3,4,5}
let intersection = a.intersection(b);  // {3}
let difference   = a.difference(b);    // {1,2}
// Also: isSubsetOf, isSupersetOf, values(), toArray()

Tuples

tuples.lox
// Explicit construction — variadic, like Array(...)
let t = Tuple("a", 1);
print(t[0]);            // "a"
print(t.length());      // 2
print(t is Tuple);      // true

// Typed: Tuple<A, B>, with [A, B] as sugar in any type position.
// An ARRAY value in a Tuple-typed declaration converts automatically
// (annotation-driven) — elsewhere [a, b] stays an ordinary array.
let p: Tuple<String, Number> = ["a", 1];
let q: [String, Number]      = ["b", 2];
let pairs: Array<[String, Number]> = [];   // composes with generics

// Per-position validation — the point of a tuple over Array<Any>:
// wrong arity or element types are rejected (compile-time in native,
// runtime in the VM / tree-walker).
// let bad: Tuple<String, Number> = ["a", "b"];   // ERROR

// Destructuring binds each position
let [k, v] = p;         // k = "a", v = 1

// Immutable: index writes and mutators raise
// t[0] = "x";          // ERROR: Tuples are immutable
// t.push(2);           // ERROR: Tuples are immutable
let sorted = Tuple(3, 1, 2).sort();   // fine — sort returns a NEW array

Module System ✅ Working

Per-module scope isolation, export-only visibility, and singleton execution. Supports stdlib (std::), relative paths (./), and bare package names.

Defining & importing a module

math_utils.lox
namespace my_app::utils;

// Private — not visible to importers
let PRECISION = 0.0001;

def add(a, b)      { return a + b; }
def multiply(a, b) { return a * b; }

let PI = 3.14159;

// Only exported symbols are visible
export { add, multiply, PI };

Import forms & module singletons

main.lox
// Named imports
import { add, multiply } from "./math_utils.lox";

// With alias
import { add as plus } from "./math_utils.lox";

// Star import (all exports as a Map)
import * as helpers from "./math_utils.lox";
helpers["add"](1, 2);

// Stdlib — namespace imports take NO quotes (quotes are for path imports)
import { Stack } from std::collections;
import { np }    from numpy;   // numpy lives at the bare `numpy` namespace

// Modules are singletons — state persists across imports
import { increment, get } from "./counter.lox";
increment();
print(get());   // 1

import { get as getAgain } from "./counter.lox";
print(getAgain());  // 1 — same instance!

Function-body imports & breaking module cycles

import is an ordinary statement — inside a function body it runs at call time, after all modules have loaded. Since loaded modules are cached and the circular-dependency check only guards loads in progress, this is the sanctioned way for two modules to refer to each other. The same pair with both imports at top level fails with Circular dependency detected.

a.lox
namespace app::a;
// Top-level: loads b eagerly at import time
import { pong } from "./b";

def ping(n) {
    if (n <= 0) { return "a-done"; }
    return pong(n - 1);
}
export { ping };

b.lox
namespace app::b;
// Importing a at TOP LEVEL here would be a circular-dependency
// error. Inside the function it resolves lazily — by the time
// pong() is called, a.lox is loaded and cached.
def pong(n) {
    import { ping } from "./a";
    if (n <= 0) { return "b-done"; }
    return ping(n - 1);
}
export { pong };

Runtime dynamic loading — Module.load_exports / Module.load_source

A module can be resolved at runtime — from a path or from source text already in hand — and its export table returned as a Map. Same loader as static import: namespace requirement, export-only visibility, singleton caching, circular-import detection. Load failures (missing file, parse error, a module body that throws) are ordinary catchable errors.

Example project — a host program that discovers and loads plugins it was not compiled with:

file tree
plugin-host/
├── host.lox              # compiled once — never needs to know the plugins
└── plugins/
    ├── shout.lox         # dropped in at any time, no recompile
    └── reverse.lox

plugins/shout.lox
namespace plugins::shout;

def meta(): Map { return { "name": "shout" }; }
def run(input: String): String { return input.toUpperCase() + "!"; }

export { meta, run };

host.lox
// The host lists a directory and loads whatever is there — the plugin
// set is decided at RUN time, not compile time.
def load_plugins(dir: String): Array {
    let out = [];
    if (!File.exists(dir)) { return out; }
    for (entry in File.list_directory(dir)) {
        let base = File.filename(entry);
        if (base.endsWith(".lox")) {
            // A bad plugin must not kill the host: load errors -- parse
            // failure, a throwing module body -- are catchable.
            let ex = try { Module.load_exports(dir + "/" + base) }
                     catch (e) { nil };
            if (ex != nil && ex.has("meta") && ex.has("run")) { out.push(ex); }
        }
    }
    return out;
}

let plugins = load_plugins("plugins");
print("loaded: " + plugins.length);
for (p in plugins) {
    print(p["meta"]()["name"] + " -> " + p["run"]("hello"));
}

// Or run source text you authored at runtime, under a virtual name:
let src = "
namespace virt::adder;
def add2(n) { return n + 2; }
export { add2 };
";
let m = Module.load_source(src, "adder_v1");
print(m["add2"](40));

Compile the host natively — dynamic loading works in compiled binaries too (the loaded modules execute in an embedded interpreter; see the notes below):

terminal
$ loxel compile --multi-module host.lox -o host
$ ./host
loaded: 2
reverse -> olleh
shout -> HELLO!
42

# Drop a new plugin in — NO recompile of the host:
$ cp ~/new_plugin.lox plugins/
$ ./host
loaded: 3
...

Notes that matter:

Execution modes. In the bytecode VM the full surface works — exported classes are constructible from the returned Map. In a compiled binary, runtime-loaded modules run in an embedded bytecode VM: data and functions bridge across (functions arrive as callable closures), but class exports fail with an explicit error — export a factory function returning a Map instead. Native speed applies only to statically-compiled modules.
Singletons. A load_source name maps to one module for the life of the process, like a file path; re-registering a used name is an explicit error, never a silent replace.
Security. Loaded source runs with the full privileges of the host program — filesystem, network, process spawning. There is no sandbox. Load only source you trust or have vetted through your own gates; never feed it network input.

Multilingual Keywords ✅ Working

Write code in 7 languages. Keywords, type names, and (since v3.4.0) builtin method names are internationalized. There is no --lang flag: every language's spellings are active simultaneously, and languages can be mixed freely in one file — English is the canonical form.

Examples in multiple languages

i18n.lox
// English
def greet(name: String) => `Hello, ${name}`;

// Spanish — keywords translate; the constructor is always `def init`
// (init is a method NAME, not a keyword, so it has no translations)
clase Persona {
    nombre: Cadena
    edad:   Numero
    def init(n: Cadena, e: Numero) {
        esto.nombre = n;
        esto.edad   = e;
    }
    def saludar(): Cadena { retornar "Hola, " + esto.nombre; }
}

// Japanese
クラス 人 {
    名前: 文字列
    年齢: 数値
    def init(n: 文字列, a: 数値) {
        自分.名前 = n;
        自分.年齢 = a;
    }
}

// French
classe Personne {
    nom: Chaîne
    age: Nombre
    def init(n: Chaîne, a: Nombre) { moi.nom = n; }
}

// Builtin METHOD names too (v3.4.0): every supported language's
// spelling resolves exactly as the English form does, in all three
// backends. Resolution happens at runtime on the MISS path
// (data key → builtin method → alias → nil), never by rewriting:
let lista = [3, 1, 2];
lista.ordenar();          // es — exactly lista.sort(): returns [1, 2, 3]
lista.trier();            // fr — same
lista.整列();             // ja — same
"hola".longitud();        // 4
let mapa = { "a": 1 };
mapa.claves();            // ["a"] — Map keys

// Because data wins first, an alias can never steal a data key —
// and a class defining both `sort` and `ordenar` keeps them distinct:
let body = { "ordenar": 5 };
body.ordenar;             // 5 — the JSON data, untouched

Language	Function	Class	String	Number	.sort()	.keys()
English	`def`	`class`	`String`	`Number`	`sort`	`keys`
Español	`def`	`clase`	`Cadena`	`Numero`	`ordenar`	`claves`
Français	`def`	`classe`	`Chaîne`	`Nombre`	`trier`	`clés`
Deutsch	`def`	`klasse`	`Zeichenkette`	`Zahl`	`sortieren`	`schlüssel`
Português	`def`	`classe`	`Cadeia`	`Numero`	`ordenar`	`chaves`
日本語	`def`	`クラス`	`文字列`	`数値`	`整列`	`キー`
中文	`def`	`类`	`字符串`	`数字`	`排序`	`键`

Error Handling ✅ Working

Standard try/catch blocks (there is no finally clause in the language), and try as an expression — the try block's final expression is the result, the catch block's on a caught throw, identical in all three modes. Error is a real core class (#907): Error("msg") constructs an instance carrying .message, it is subclassable (class ValidationError extends Error, or < Error), thrown errors reach catch unchanged in all three modes, and typed catch clauses — catch (e: NetworkError), tried in order, untyped catch-all last — dispatch on the error's class.

Example

errors.lox
// try / catch (there is no finally clause)
try {
    let result = risky_operation();
    process(result);
} catch (e) {
    print("Error: " + e.message);
}

// throw
def divide(a, b) {
    if (b == 0) throw Error("Division by zero");
    return a / b;
}

// Custom error types: subclass Error (#907)
class ValidationError extends Error {      // `< Error` also works
    def init(message, field) {
        super.init(message);
        self.field = field;
    }
}

// Typed catch clauses dispatch on the error's class, in order;
// the untyped catch-all must come last. No match rethrows outward.
try {
    throw ValidationError("Invalid email", "email");
} catch (e: NetworkError) {
    retry();
} catch (e: ValidationError) {
    print(e.field + ": " + e.message);     // the instance arrives unchanged
} catch (e) {
    print("unexpected: " + e);
}

// e is ValidationError / e is Error answer through the class chain;
// an uncaught error crashes as "ClassName: message".

// std::error's map factories (tagging a "type" field) still work for
// legacy dispatch: catch (e) { if (e["type"] == "ValueError") ... }

// try as expression
let data = try { parse(input) } catch (e) { default_value };

Result & Railway Operators ✅ Working

Recoverable failures as values: Ok(v) and Err(e) build a Result<T, E>, and the railway operators thread it through pipelines. ?> is the failure-aware sibling of |> — an Err skips every remaining stage (the stage is never evaluated), while an Ok payload flows into the next function, which must itself return a Result (bind semantics; use .map() for plain transforms). Postfix ?! unwraps an Ok or early-returns the Err from the enclosing function (like Rust's ?), and ?? gains unwrap-or: Ok(v) ?? d yields v, Err(_) ?? d yields d. Identical in all three modes; ?! at module top level is rejected at compile time in VM and native modes.

Example

railway.lox
// Constructors — a Result is Ok(value) or Err(reason)
let hit  = Ok(42);          // Ok(42)
let miss = Err("not found"); // Err(not found)
print(typeof hit);           // Result
print(hit.isOk());           // true
print(miss.error);           // "not found"  (miss.value is nil)

// Railway bind ?> — stops at the first Err
def parse(s)    { return s == "bad" ? Err("unparseable") : Ok(s + ":parsed"); }
def validate(v) { return v == "x:parsed" ? Ok(v + ":valid") : Err("invalid"); }

Ok("x")   ?> parse ?> validate;   // Ok(x:parsed:valid)
Ok("bad") ?> parse ?> validate;   // Err(unparseable) — validate never runs

// Mixes freely with the plain pipe
def wrap(s) { return Ok(s); }
"x" |> wrap ?> parse;             // Ok(x:parsed)

// Propagate ?! — unwrap Ok, or early-return the Err (Rust's ?)
def pipeline(input) {
    let v = parse(input)?!;        // Err(...) returns here unchanged
    return Ok(v + ":done");
}
pipeline("x");    // Ok(x:parsed:done)
pipeline("bad");  // Err(unparseable)

// Unwrap-or ?? — Ok unwraps, Err falls back (nil behavior unchanged)
Ok(42)   ?? 0;    // 42
Err("e") ?? 0;    // 0
nil      ?? "d";  // "d"

// Methods — transforms that stay on their track
Ok(2).map((v) => v * 10);              // Ok(20)
Err("e").map((v) => v * 10);           // Err(e)      (untouched)
Err("e").mapErr((e) => "why: " + e);   // Err(why: e)
Ok(2).mapErr((e) => "nope");           // Ok(2)       (untouched)

// A raising stage is still an exception — catch it with try
def boom(v) { return Ok(1 / 0); }
try { Ok(1) ?> boom } catch (e) { "caught: " + e };  // caught: Division by zero

Built-in Functions ✅ Working

Core built-ins always available without an import.

Output, type conversion & utilities

builtins.lox
// Output
print("Hello");

// Conversion constructors (v3.24) — return primitives
Number("42");      // 42       (throws on unparseable input)
String(42);        // "42"     (calls the argument's toString() for objects)
Boolean(1);        // true     (the language truthiness rule: nil, false,
                   //           0 and empty containers are falsy)

// Type introspection
typeof value;          // Get type name as String
value is Number;       // true / false
value is Object;       // true for every value (Object is the root)
// `is` takes a type EXPRESSION: | (or), & (and), ! (not), ( ) to group
value is Number | String;         // union: is Number OR is String
value is Number & !Dollar;        // a Number, but NOT a Dollar (exclusion)
value is (Drawable | Widget) & !Legacy;   // ! tightest, then &, then |

// Lengths and ranges are methods and syntax, not global functions:
[1, 2, 3].length();    // 3
"abc".length();        // 3
for (i in 1..10) {}    // range syntax: exclusive .., inclusive ..=

String & Math ✅ Working

String methods

strings-methods.lox
let str = "Hello, World!";

str.length;                       // 13
str.toUpperCase();                // "HELLO, WORLD!"
str.toLowerCase();                // "hello, world!"
str.trim();                       // removes leading/trailing whitespace
str.split(",");                   // ["Hello", " World!"]
str.replace("World", "Loxel");    // "Hello, Loxel!"  (replaceAll for every hit)
str.substring(0, 5);              // "Hello"
str.contains("World");            // true  (alias of includes)
str.startsWith("Hello");          // true
str.endsWith("!");                // true
str.indexOf("World");             // 7  (character index; lastIndexOf too)
str.charAt(1);                    // "e"

Math module

math.lox
// Math lives in the std::math module (there is no global `Math` object)
import { pow, sqrt, abs, floor, ceil, round, sin, cos, log, exp, PI } from std::math;

sqrt(16);          // 4
pow(2, 8);         // 256
2 ** 8;            // 256 — the ** operator is equivalent to pow
                   //       (right-associative: 2 ** 3 ** 2 == 512)
(2).pow(8);        // 256 — also available as a Number method
abs(-5);           // 5
floor(3.7);        // 3
ceil(3.2);         // 4
round(3.5);        // 4
sin(angle);  cos(angle);  log(x);  exp(x);
// Also exported: sign, max, min, clamp, factorial, gcd, lcm, isPrime,
// toRadians, toDegrees, fibonacci, lerp, random, E, TAU, ...

File, HTTP & JSON 🚧 In Progress

File I/O

file-io.lox
let content = File.read("data.txt");
File.write("output.txt", "Hello, World!");
File.append("log.txt", "New entry\n");
if (File.exists("config.json")) { /* ... */ }
let info = File.stat("document.pdf");
print(info.size);

HTTP Client & JSON

http-json.lox
// HTTP
let response = await HTTP.get("https://api.example.com/users");
print(response.status);  // 200

let res2 = await HTTP.post(
    "https://api.example.com/users",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "Alice", age: 30 })
);

// JSON
let data = JSON.parse('{"name":"Alice","age":30}');
print(data.name);  // "Alice"

let json = JSON.stringify({ name: "Bob" });
let pretty = JSON.stringify(data, indent: 2);

Data Structures ✅ Working (V2)

Import from std::collections, std::trees, and std::graphs.

Stack, Heap, Deque

collections.lox
import { Stack, MinHeap, MaxHeap, Deque } from std::collections;

// Stack (LIFO)
let stack = Stack<Number>();
stack.push(1); stack.push(2);
print(stack.pop());       // 2
print(stack.peek());      // 1

// Min/Max Heap (priority queue)
let min_heap = MinHeap<Number>();
min_heap.insert(5); min_heap.insert(3); min_heap.insert(8);
print(min_heap.extract());   // 3 (minimum)

// Deque (double-ended queue)
let deque = Deque<String>();
deque.push_back("middle");
deque.push_front("first");
print(deque.pop_front());    // "first"

Binary Search Tree, AVL Tree, Trie

trees.lox
import { BinarySearchTree, AVLTree, Trie } from std::trees;

let bst = BinarySearchTree<Number>();
bst.insert(10); bst.insert(5); bst.insert(15);
print(bst.contains(5));  // true
print(bst.min());        // 5

// Trie (prefix tree / autocomplete)
let trie = Trie();
trie.insert("apple");
trie.insert("application");
let matches = trie.autocomplete("app", 5);

NumPy & Machine Learning ✅ Working (V2)

N-dimensional arrays (std::numpy), ML algorithms (std::ml), and statistical computing (std::statistics).

NumPy-style arrays

numpy.lox
// NDArray lives at the bare `numpy` namespace (not std::numpy)
import { np } from numpy;

let arr    = np.array([1, 2, 3, 4, 5]);
let matrix = np.array([[1, 2, 3], [4, 5, 6]]);
let zeros  = np.zeros([3, 3]);
let eye    = np.eye(4);

// Element-wise operations
let a = np.array([1, 2, 3]);
let b = np.array([4, 5, 6]);
print(a.add(b));       // [5, 7, 9]
print(a.multiply(b));  // [4, 10, 18]
print(a.add(10));      // [11, 12, 13]  (scalar broadcast)

// Reshaping
let m = np.arange(12, nil, nil).reshape([3, 4]);
print(m.transpose().flatten().sum(nil));

ML classifiers & regression

ml.lox
import { DecisionTreeClassifier, KMeans, LinearRegression } from std::ml;

// Constructors take all their hyperparameters (no defaults yet) —
// named arguments keep the call sites readable.

// Decision tree
let clf = DecisionTreeClassifier(max_depth: 5, min_samples_split: 2,
                                 min_samples_leaf: 1);
clf.fit(X_train, y_train);
let predictions = clf.predict(X_test);

// K-Means clustering
let km = KMeans(n_clusters: 2, max_iter: 100, tol: 0.001);
km.fit(data);
print(km.labels);
print(km.cluster_centers);

// Linear regression
let lr = LinearRegression(learning_rate: 0.01, n_iterations: 2000,
                          fit_intercept: true);
lr.fit(X, y);
print(lr.score(X, y));   // R²

AI Training & LLMs ✅ Working (V2 · compiled)

A full pure-Loxel deep-learning stack — no PyTorch. Threaded f32 tensors and a fused 4-bit kernel (std::tensor), and real-model QLoRA fine-tuning plus Q4 KV-cache inference (std::llm), validated end-to-end on SmolLM2-360M. Instruct models are covered by two submodules: std::llm::qwen3 loads Qwen3-architecture GGUFs (ternary Bonsai Q2_0 and stock llama.cpp K-quant Q4_K_M), and std::llm::chat assembles conversations (templates, transcripts, stop tokens) for GGUF instruct models. This stack targets the LLVM-compiled backend (the reference for these modules) — compile with -O2 --cpu=native; it is not run through the interpreter.

QLoRA fine-tuning (4-bit frozen base + trainable adapters)

finetune.lox
import { load_pretrained_q4, create_adapters, freeze, lora_parameters,
         lora_train_step, save_adapter } from std::llm;
import { AdamW } from std::autograd;
import { Random } from std::random;

let rng   = Random(1);                                // seeded RNG for adapter init
let model = load_pretrained_q4("SmolLM2-360M.gguf");  // base quantized to Q4 on load
freeze(model);                                        // base weights frozen
let set = create_adapters(model, 8, 16, ["attn_q", "attn_v"], rng);  // rank 8, alpha 16
let opt = AdamW(lora_parameters(set), 1e-3);          // only adapters train

let loss = lora_train_step(model, opt, X, Y, lr, set);  // backprops through frozen Q4 base
save_adapter(set, "loxel_adapter.gguf");                // ~MB per-user artifact

Q4 KV-cache generation (temperature + top-k)

chat.lox
import { load_pretrained_q4, load_adapter, generate_cached, materialize_base } from std::llm;
import { Random } from std::random;

let model = load_pretrained_q4("SmolLM2-360M.gguf");
let set   = load_adapter("loxel_adapter.gguf", model);
let rng   = Random();                                    // sampling RNG (required)

// Adapters are passed as an ARRAY (they stack) — use [] or nil for the raw base.
// Low-memory path: fused Q4 decode, base stays Q4-size in RAM (the on-device path)
let out = generate_cached(model, prompt_ids, [set], 64, 0.8, 40, eos_id, nil, rng);

// Speed path: dequantize the base ONCE, reuse across calls (RAM-heavy desktop path)
let dense = materialize_base(model);
let out2  = generate_cached(model, prompt_ids, [set], 64, 0.8, 40, eos_id, dense, rng);
dense.dealloc();

// Optional trailing sampler params: top_p (nucleus, default 1.0) and
// presence_penalty (default 0.0). generate_cached_stream takes an extra
// on_token callback (before rng) and invokes it per decoded token.

Instruct models — std::llm::qwen3 loaders & std::llm::chat templates

std::llm::chat is pure conversation assembly — it never generates and never touches the filesystem. std::llm::qwen3 loads Qwen3-architecture GGUFs into the same decoder core that generate_cached runs on.

instruct.lox
import { load_pretrained_kquant } from std::llm::qwen3;   // stock llama.cpp Q4_K_M
// (load_pretrained_ternary loads Bonsai Q2_0 ternary GGUFs the same way)
import { Transcript, template_for, detect_family, render_ids, primary_stop_id } from std::llm::chat;
import { load_tokenizer_gguf } from std::tokenizer;

let MODEL = "Qwen3-0.6B-Q4_K_M.gguf";
let model = load_pretrained_kquant(MODEL);
let tok   = load_tokenizer_gguf(MODEL);

// Build the conversation, render it through the model family's template
let tr = Transcript();
tr.system = "be brief";
tr.user("What is a closure?");
let T   = template_for(detect_family(tok)); // "chatml" for the Qwen family
let ids = render_ids(tr, T, tok);           // prompt token ids, template applied
let eos = primary_stop_id(T, tok);          // the template's stop token

// ...then generate with the usual KV-cache path (see previous example)

std::tensor — threaded matmul & fused 4-bit kernel

tensor.lox
import { Tensor, quantize } from std::tensor;
import { Random } from std::random;

let rng = Random(1);
let a = Tensor(256, 512); a.fill_normal(0.0, 0.02, rng);
let b = Tensor(512, 128); b.fill_normal(0.0, 0.02, rng);
let c = a.matmul(b, 4);              // threaded matmul (4 workers); bit-identical per thread count

// 4-bit (Q4_0-style) block quantization: 32 weights/block, value = (code - 8) * scale
let q = quantize(b);                 // Tensor -> Quant  (~4 bits/weight)
let y = q * a;                       // fused dequant-matmul: never materializes dense f32

a.dealloc(); b.dealloc(); c.dealloc(); q.dealloc(); y.dealloc();

Hardware Acceleration ✅ Working (V2 · compiled)

One port — std::device — and per-platform adapters behind it. Callers select and interrogate compute (select() / supports() / describe()) without naming a backend; select() never fails — a missing GPU is a slower route, not an error, and the CPU path is the reference every accelerator is gated against. Measured on qwen3-4b Q4_K_M: 0.42 → 33–35 tok/s end-to-end (device-resident decode on an RTX 2080).

Desktop performance is the CUDA adapter's job (containers cannot reach a discrete GPU via Vulkan under WSL2); Vulkan serves Android's unified memory and llvmpipe CI runs. Full guide: docs/runtime/gpu-acceleration.md.

Selecting and probing a device (std::device)

import { select, register_vulkan_adapter } from std::device;
import { register_cuda_adapter } from std::ml::device_adapter;  // ML builds

register_cuda_adapter();      // opt-in; probes GGML's own CUDA init
register_vulkan_adapter();    // opt-in; probes loxel_gpu_available()

let dev = select("prefer-gpu");            // NEVER fails; cpu is the floor
print(dev.kind);                           // "cuda" | "vulkan" | "cpu"
print(dev.describe());                     // why THIS device — greppable
if (dev.supports("gemv.q4k.sb256")) {      // capability = exact kernel contract
    // route the hot path through the device
}

Environment variables (the complete acceleration surface)

Variable	Read by	Meaning
`LOXEL_PERF_MODE=gpu`	runtime (one gate)	THE opt-in: permits Vulkan zero-copy buffers, the K-quant CUDA session, and device-resident decode. Unset = pure CPU, always.
`LOXEL_DEVICE`	`std::device.select()`	Selection policy when no explicit arg: `cpu`, `vulkan`, `cuda`, `prefer-gpu`.
`LOXEL_CHAT_SESSION_CAP`	loxel-chat infer worker	Session length in tokens. Unset + CUDA: auto-sized to free VRAM (up to the model's native context). Unset + CPU: 1024.
`LOXEL_CHAT_INFER_HOST`	loxel-chat web tier	Which worker serves chat: `infer` (CPU, default) or `infer-gpu` (compose `--profile gpu`).
`LOXEL_COMPUTE_DEVICE`	GGML backend strategy	image-gen's CPU/CUDA choice: `gpu`, `cpu`, `auto`.
`LOXEL_DECODE_PROF=1`	`std::llm`	Per-phase decode profiler (µs buckets: gemv/attn/rope/…). `LOXEL_PREFILL_PROF=1` for prefill.
`LOXEL_WORKER_CPU`	Dockerfile build arg	CPU tuning for the worker's non-device half; the gpu profile passes `native`.
`LOXEL_EXTRA_LINK_LIBS`	`loxel compile` link step	How a build image hands its GGML/CUDA libraries to every compile it runs.

Execution Modes ✅ Working

Three modes, in priority order: the native LLVM compiler is the primary mode (most capable, ships production binaries), the bytecode VM is second (the default for loxel script.lox), and the tree-walking interpreter is third (simplest; useful for prototyping semantics). New features land native-first; a feature existing only in a lower mode is a gap, not a design.

Mode	Speed	Role	Usage
Native (LLVM)	50–100× tree-walker	Primary — production binaries; debug builds via `-g`	`loxel compile script.lox -o out`
Bytecode VM	18× tree-walker	Secondary — the default interpreted mode	`loxel script.lox`
Tree-walker	Baseline	Third — prototyping / semantics reference	`loxel script.lox --tree-walker`
REPL	N/A	Interactive	`loxel` or `loxel repl`

REPL special commands

repl-session.txt
loxel> let x = 5
loxel> def square(n) => n * n
loxel> square(x)
25
loxel> :mode        // show execution mode
loxel> :history     // show command history
loxel> :reset       // reset interpreter state
loxel> :exit

Language-Level Events ✅ Working

Event decorators on class methods intercept lifecycle events for AOP, logging, validation, and metaprogramming. All three modes implement six of the seven hooks (@onCall, @onReturn, @onThrow, @onPropertyGet, @onPropertySet, @onInstantiate): they fire through the runtime dispatcher, inherit to subclasses, and a throwing @onPropertySet validation hook aborts the write catchably — verified in the tree-walker too, where both the @onThrow and aborting-write gaps have since been fixed. @onPropertyGet fires natively as of 2026-07-30 (same hook table as @onPropertySet, suppressed inside hooks so a hook reading self.* can't recurse). Only @onInherit remains interpreted-only (native warns at compile time, as it does for @computed). Native nuance: hooks fire on dispatched method calls, not on super.method() fast paths.

Event hook decorators

events.lox
class BankAccount {
    def init(owner: String, balance: Number) {
        self.owner   = owner;
        self.balance = balance;
    }

    // Fires before any method call
    @onCall
    def audit(method_name, args) {
        print("[audit] " + self.owner + " -> " + method_name);
    }

    // Fires whenever a property is written
    @onPropertySet
    def validate(prop, value) {
        if (prop == "balance" && value < 0) {
            throw Error("Balance cannot go negative");
        }
    }

    // Fires once after init() completes
    @onInstantiate
    def setup() { self.tx_count = 0; }

    def deposit(amount: Number): Number {
        self.tx_count  += 1;
        self.balance   += amount;
        return self.balance;
    }
}

let acct = BankAccount("Alice", 100);
acct.deposit(50);   // prints: [audit] Alice -> deposit
print(acct.balance); // 150

Built-in method decorators

builtin-decorators.lox
class Calculator {
    @logged            // log calls and returns to stderr ([LOG] lines)
    @timed             // measure and print execution time
    def fibonacci(n) {
        if (n <= 1) return n;
        return self.fibonacci(n - 1) + self.fibonacci(n - 2);
    }

    @cached            // memoize — only computed once per unique args
    def expensive(x) { return x * x * x; }

    @deprecated("Use computeNew() instead")
    def computeOld() { return 42; }
}

Decorator	Trigger	Parameters
`@onCall`	Before any method call	`method_name`, `args`
`@onReturn`	After method returns	`method_name`, `result`
`@onThrow`	Exception thrown	`method_name`, `error`
`@onPropertyGet`	Property read	`property_name`
`@onPropertySet`	Property written	`property_name`, `new_value`
`@onInstantiate`	After `init()`	none
`@onInherit`	Class subclassed	`child_class`

These class-level hooks take no arguments and fire for every property. To hook a single field — and to see the value it replaced — decorate the field, below.

Per-field hooks — `@onInitialize`, `@onUpdate`

A decorator on a field declaration hooks writes to that one field. Like the rest of the family they are named for the event, not for what a handler does with it: @onInitialize fires on the field's first write (typically in init), @onUpdate on every later write. A field may declare either, both, or neither.

The handler receives one event map: e.field (the field's name), e.priorValue (the value being replaced — nil for @onInitialize), and e.newValue.

field-hooks.lox
class Address {
    @onInitialize((e) => {
        if (e.newValue.length() != 5) { throw "zip must be 5 digits"; }
    })
    @onUpdate((e) => {
        print(`${e.field}: ${e.priorValue} → ${e.newValue}`);
    })
    let zip: String;

    def init(zip: String) { self.zip = zip; }
}

let a = Address("12345");   // @onInitialize runs; @onUpdate does NOT
a.zip = "99999";            // zip: 12345 → 99999
Address("1");               // throws "zip must be 5 digits"

Rejecting a write is a throw — the same veto @onPropertySet has. There is no return-value convention: a handler that returns normally accepts the write, whatever it returned, and a rejected write leaves the field's previous value in place.

Hooks never fire from inside hooks. A write performed by a handler does not itself fire a handler, so a handler that writes cannot recurse — the same rule the class-level hooks obey.

A handler is evaluated once, at class-definition time, in the class's defining scope, so it is one closure shared by every instance and it has no self. It sees only its event map; reach anything else through a captured variable.

Which to use: @onPropertySet is the broader instrument — it fires for every property, including fields created dynamically by assignment, which a field decorator cannot see because it attaches to a declaration. Per-field hooks are narrower, know which field they guard, and are the only way to see the replaced value.

Unified Object Model ✅ Working

All primitive values behave as objects with methods. Internally they remain efficient (NaN-boxed doubles, bit-pattern booleans) — method calls dispatch directly to C++.

Primitive class contracts: every inline primitive is an instance of its core Loxel class (String, Number, Boolean, Array, Map, Set), and every core class extends Object. The class definitions in stdlib/core/*.lox are the declared contract — including operator methods with typed parameters like def <(other: String). Class methods may delegate to native functions, and the engines fast-path primitive receivers equivalently, but the semantics are the ones written on the class; subclass overrides dispatch through the method table and win. (Single-source build-time embedding of the core classes and typed operator contracts: ✅ landed 2026-07-03.)

Primitive methods

unified-object-model.lox
// Number methods
5.abs()              // 5
(-3).abs()           // 3
3.14.floor()         // 3
3.14.ceil()          // 4
3.14.round()         // 3
3.14159.toFixed(2)   // "3.14"
5.toString()         // "5"
5.isInteger()        // true
(-5).isNegative()    // true
15.clamp(0, 10)      // 10

// Method chaining
(-3.7).abs().floor() // 3
16.sqrt().pow(2)     // 16

// Boolean methods
true.toString()      // "true"
false.not()          // true
true.and(false)      // false
true.or(false)       // true
true.xor(true)       // false

// Nil methods (null is an accepted alias spelling of nil)
nil.isNull()         // true
nil.orElse(42)       // 42
nil.toString()       // "nil"

Core-Class Subclassing ✅ Working

Every core class (Number, String, Boolean, Array, Map, Set, and Error — see Error Handling) is subclassable in all three execution modes. A subclass instance wraps its primitive, inherits the core class's methods and typed operator contracts (abs(), <, toString(), …), participates in arithmetic through them, and answers is through its class chain (Meters(3) is Number is true; typeof still reports the boxed kind). Combine with a decorator factory to normalize operands before a method body runs — units-style types in a few lines.

Example — unit-safe arithmetic via a coercion decorator

meters.lox
// A decorator factory: wraps a method so its operand is normalized
// BEFORE the body runs. The wrapper receives (me, other) unbound.
def coercing(convert) {
    return (fn) => {
        return (me, other) => {
            return fn(me, convert(other));   // normalize, then delegate
        };
    };
}

class Meters < Number {
    @coercing((x) => x is Meters ? x : Meters(x))
    def add(other) {
        // `other` is ALWAYS Meters here — plain numbers were coerced.
        return Meters(self + other);         // wrapped values unwrap in arithmetic
    }
}

let m = Meters(3);
m.add(4);                  // Ok: plain Number coerced -> Meters(7)
m.add(Meters(5));          // passthrough               -> Meters(8)
m.add(4) is Meters;        // true — the subtype survives arithmetic
Meters(0 - 7).abs();       // 7   — inherited from Number
m < Meters(5);             // true — Number's typed `<` contract

// Method decorators run in compiled (native) and bytecode-VM modes
// (#399 fixed the VM); the tree-walker still breaks the unbound
// receiver convention (issue #947) — the un-decorated body must
// therefore tolerate raw operands there, as add() above does.

Abstract Classes 📋 Planned

Abstract classes define partial implementations. Subclasses must implement all abstract methods. Instantiating an abstract class is a runtime error.

Planned syntax

abstract.lox (planned)
abstract class Shape {
    def init(name: String) { self.name = name; }

    // Concrete method — has implementation
    def describe(): String { return "A shape: " + self.name; }

    // Abstract methods — subclasses must implement
    abstract def area(): Number;
    abstract def perimeter(): Number;
}

class Circle extends Shape {
    def init(r: Number) { super.init("Circle"); self.radius = r; }
    def area():      Number { return 3.14159 * self.radius ** 2; }
    def perimeter(): Number { return 2 * 3.14159 * self.radius; }
}

// new Shape();  // ❌ Cannot instantiate abstract class

Static Properties & Methods ⚠️ Partial

The static keyword works in the bytecode VM and the native/LLVM compiled backend. static let/static const fields may have an initializer, evaluated once when the class is defined. Both the bytecode VM and the native/LLVM backend enforce visibility and const/readonly mutability on static fields with matching error messages (write-once: the initializer or first assignment succeeds, later writes throw; native errors are catchable, VM errors are fatal). Static members are accessed via the class name, not self.

Static keyword (working)

static.lox
class Math {
    static let PI = 3.14159265359;
    static const E = 2.71828182846;
    static def abs(x: Number): Number { return if (x < 0) -x else x; }
}
print(Math.PI);       // 3.14159265359
print(Math.abs(-5));  // 5

class User {
    static let count = 0;

    def init(name: String, email: String) {
        self.name  = name;
        self.email = email;
        User.count += 1;
    }
}

print(User.count);                     // 0
let u = User("Alice", "alice@example.com");
print(User.count);                     // 1

Static variable: visibility & mutability

static-variable.lox
// A plain static variable — shared state on the class itself, not per-instance
class AppConfig {
    static let debugMode = false;
    static readonly version = "1.0.0";
    private static let internalFlag = true;
}

print(AppConfig.debugMode);    // false
AppConfig.debugMode = true;
print(AppConfig.debugMode);    // true

print(AppConfig.version);      // 1.0.0
// AppConfig.version = "2.0.0";  // ❌ Runtime error: Cannot modify readonly field 'version'

// print(AppConfig.internalFlag); // ❌ Runtime error: Cannot access private static field 'internalFlag'

Definitions

The words the type system's documentation and diagnostics lean on, and — one paragraph each, no internals — how Loxel achieves them.

Type annotation

A written type on a binding, parameter, return or element (let n: Number, def f(s: String?): Boolean, Array<Number>). In Loxel an annotation is a contract, not a hint: the compiler checks every value that reaches it, and in compiled code a value that provably breaks the promise stops the build. What an annotation asks for is a kind of value — Number means a Number or any subclass of it.

Type inference

Working out a type that was not written: let x = 5 is a Number; a function that only ever returns Strings returns a String. Inferred types are descriptive — assigning something else to an unannotated variable widens it rather than failing — so an annotation is how you ask for the contract instead.

Soundness

A type system is sound when a type it states is never wrong at runtime: if the checker says s is a String at some point, then on every path that reaches that point s holds a String. Soundness is what lets a compiler act on a type — skip a check, unbox a value, call directly — without a safety net underneath. Loxel achieves it four ways. An unknown value (Any) never satisfies a concrete annotation on its own; it has to be narrowed with a checked cast (value :> Number). Classes are nominal: a Vec is a value built by the Vec class or a subclass of it, never something merely shaped like one. Where control paths merge — after an if, at the top and the bottom of a loop — only what every path proves survives. And at every declared boundary — a variable's declaration and each reassignment, a parameter, a return — as well as a cast, the runtime checks the value itself, in all three execution modes; so a declared type holds even where the checker could not see (a value arriving from an untyped module, an Any), and what the compiler specializes on is exactly what the runtime admitted.

Exactness

Knowing a value's exact representation, not just its kind. Because every core type is subclassable (class Meters < Number), a Number may be a plain double or an object wrapping one; Number! says it is the double and nothing else. The exact form is what the native compiler needs to keep a value unboxed and to call an operator directly, so exactness is how an annotated program stays as fast as an unannotated one. Loxel achieves it mostly by inference: a literal is exact, arithmetic on exact operands is exact, a construction Vec(…) is exactly a Vec, and a binding declared Number that currently holds an exact value keeps that proof until something open is assigned. You write T! only where inference cannot cross — a parameter, a field, an element type — and value :> Number! is the checked cast, which throws for a subclass instance.

Narrowing

Refining a type on one path from evidence on that path. A nil test narrows an optional — if (s == nil) { return; } proves s is a String afterwards, and while (node != nil) proves it inside the body and proves it nil after a normal exit; !, && and || compose; and the checked cast :> narrows anything, at the price of a runtime check. Narrowing follows variables, not fields.

Gradual typing, and `Any`

Types are optional. Any is the type of a value nothing is known about — an unannotated parameter, a field, a value from an untyped module — and it is unknown, not wrong: it flows freely into other Any slots, and into a concrete slot only through :>. A program can be typed one function at a time, and each annotation is checked from the moment it is written.

Contract violation vs. type error

Diagnostics come in two strengths. A contract violation is a provable mismatch — a String assigned to a Number, a call with the wrong number of arguments — and it fails every native compile, whatever the --type-check setting. A type error is a value the checker cannot prove either way, an Any reaching a concrete slot without a cast; it is reported under --type-check=warn and fails the program under --type-check=strict. Both name the value and the promise it fails.

Quick Reference

Feature support matrix across execution modes. Every ✅ row below was re-verified against the current binary in all three modes (2026-09, the #912 sweep); footnoted cells carry the known divergence.

Feature	Tree-walker	Bytecode VM	LLVM
Variables / const	✅	✅	✅
Functions & closures	✅	✅	✅
Classes & inheritance	✅	✅	✅
Interfaces & traits	✅	✅	✅
Generics	✅	✅	✅
All 9 pattern types (rest included, #946)	✅	✅	✅
Default parameters	✅	✅	✅
Named arguments	✅	✅	✅
Rest parameters	✅	✅	✅
Async / await	✅ ¹	✅	✅
i18n support	✅	✅	✅
Module system	✅	✅	✅
Language events	✅	✅	✅
Decorators (user, on methods)	❌ ²	✅	✅
Unified object model	✅	✅	✅
Channels / Thread.spawn	❌ ³	✅	✅
Abstract classes	📋	📋	📋
Static properties	📋 ⁴	✅	✅

¹ A top-level await fn() currently runs the async body twice in the tree-walker (#948).
² The tree-walker breaks the unbound receiver convention for user method decorators (#947); built-in method decorators and function/class decorators work in all three modes.
³ Channel/Thread are not callable in the tree-walker (#747).
⁴ static def methods work in the tree-walker; static fields do not exist there yet.

Best Practices

Type annotations

best-practices-types.lox
// ✅ Good — annotate public API parameters and return types
def calculate_total(items: Array<Item>): Number {
    return items.reduce(0, (sum, item) => sum + item.price);
}

// ✅ OK — skip types for simple internal helpers
def helper(x, y) { return x + y; }

// ❌ Bad — missing annotation on complex public function
def process_data(input, options) { /* ... */ }

Error handling

best-practices-errors.lox
// ✅ Good — specific error types
try {
    let data = parse_json(input);
} catch (e: ParseError) {
    log.error("Failed to parse: " + e.message);
    return nil;
} catch (e: NetworkError) {
    retry();
}

// ❌ Bad — swallowing errors silently
try { risky_operation(); } catch (e) { }

Pattern matching vs. if/else

best-practices-match.lox
// ✅ Prefer pattern matching for structural conditions
let result = match request {
    case { type: "user", id: uid } if uid > 0 => load_user(uid)
    case { type: "admin" }                    => load_admin()
    case _                                    => error("Unknown")
};

// ❌ Equivalent if/else — harder to read and extend
let result;
if (request.type == "user" && request.id > 0) {
    result = load_user(request.id);
} else if (request.type == "admin") {
    result = load_admin();
} else {
    result = error("Unknown");
}

Known Limitations

Native (LLVM) is the primary mode: production binaries come from loxel compile; use -g for Loxel-level backtraces and bounds-checked buffers when debugging (see v2/docs/DEBUGGING.md). The interpreted modes are for iteration and prototyping.
Channels / threads: Implemented (native + VM): Thread spawn/join and Channel send/receive work in compiled code; a couple of known concurrency bugs remain in stress scenarios.
Visibility/mutability across modes: Enforced in all three modes (native records per-class field metadata and checks it at every field access). Divergences that remain: VM errors are fatal while native/tree-walker errors are catchable; the tree-walker has no static fields; and for inherited fields the lower modes derive the calling class dynamically (each rejecting a legitimate base-method access pattern that native's lexical resolution allows).
Abstract classes: Designed but not yet implemented (Phase 19).
Generics in LLVM: Generic instantiation works, and Box<Number> is a first-class parameterized-class value (aliasing let B = Box<Number>; B(x) and named/spread constructor arguments keep the type arguments). Arity/non-generic/bound errors are reported at compile time when the class is statically known; arity and non-generic misuse are also validated at runtime for dynamic class values. Type arguments are erased for execution, but each generic instance records its concrete type arguments, so a method parameter typed as a class type parameter (def set(v: T)) is validated at runtime in all three modes — Box<Number>().set("x") raises the same Type mismatch for parameter error natively, in the VM, and in the tree-walker. Method-level type arguments (obj.method<Number>() — arity, bounds, and parameter validation) and concrete/composite parameter types on generic receivers (v: Number, vs: Array<T> — container kind checked, element types unchecked) are likewise enforced in all three modes. Remaining nuances: native validates method-level type-argument bounds by type NAME (registered class hierarchies and primitives are exact; unresolvable names are accepted conservatively), and element types of Array<T>/Map<K,V> arguments are not deep-checked in any mode.
Decorators / event hooks: native and the VM implement the full user surface (VM method decorators fixed by #399), and the earlier tree-walker gaps for class decorators, @onThrow, and the throwing-@onPropertySet abort are resolved; @onPropertyGet now fires in all three modes. Remaining: tree-walker user method decorators break the unbound receiver convention (#947); @onInherit/@computed stay interpreted-only (native warns).
Tree-walker parity bugs (open): a top-level await fn() runs the async body twice (#948); Channel/Thread are not callable (#747). (Array rest patterns in match were the inverse case — tree-walker-only — and have been promoted to the VM and native, #946.)
Planned syntax: map comprehensions, do-while, for await over channels. (try-as-expression has shipped — identical in all three modes.)

Language Features

Variables & Constants ✅ Working

Comments ✅ Working

Keywords: Strict vs Contextual ✅ Working

Expressions & Blocks ✅ Working

Strings & HEREDOC ✅ Working

Control Flow ✅ Working

Type Annotations ✅ Working

Generics ✅ Working

Union & Optional Types ✅ Working

Classes ✅ Working

Inheritance ✅ Working

Interfaces & Traits ✅ Working

Property Promotion ✅ Working

Visibility Modifiers ✅ Working

Operator Overloading ✅ Working

Decorators ⚠️ Partial

Match Expressions ✅ Working

Operators ✅ Working

Functions & Parameters ✅ Working

Async / Await ✅ Working

Channels & Spawn 🚧 In Progress

Enums 🚧 In Progress

Structs 📋 Planned

Destructuring ✅ Working

Arrays ✅ Working

Maps ✅ Working

Sets & Tuples ✅ Working

Module System ✅ Working

Multilingual Keywords ✅ Working

Error Handling ✅ Working

Result & Railway Operators ✅ Working

Built-in Functions ✅ Working

String & Math ✅ Working

File, HTTP & JSON 🚧 In Progress

Data Structures ✅ Working (V2)

NumPy & Machine Learning ✅ Working (V2)

AI Training & LLMs ✅ Working (V2 · compiled)

Hardware Acceleration ✅ Working (V2 · compiled)

Execution Modes ✅ Working

Language-Level Events ✅ Working

Per-field hooks — @onInitialize, @onUpdate

Unified Object Model ✅ Working

Core-Class Subclassing ✅ Working

Abstract Classes 📋 Planned

Static Properties & Methods ⚠️ Partial

Definitions

Type annotation

Type inference

Soundness

Exactness

Narrowing

Gradual typing, and Any

Contract violation vs. type error

Quick Reference

Best Practices

Known Limitations

Per-field hooks — `@onInitialize`, `@onUpdate`

Gradual typing, and `Any`