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

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 extends. 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 extends 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;
}

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
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 (@onPropertyGet, @computed) 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 the tree-walker applies class decorators; @cached hits no longer corrupt the VM stack and @deprecated("reason") reasons are preserved. The remaining gap is narrower: the VM still ignores user-defined method decorators (built-ins work).

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.

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 (VM + compiled)
// 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.

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. Support in progress.

Example

channels.lox
// Buffered channel
let ch = Channel<Number>(10);

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

// Async for-await over a channel
for await (item in ch) { print(item); }

// Spawn a concurrent task
let future = spawn(() => expensive_computation());
let result = await future;

// 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 ✅ Working

Structs are value types — copied on assignment. Use them for small, immutable data (Point, Color, Vec2). Use classes for objects with identity and inheritance.

Value semantics vs. class reference semantics

structs.lox
struct Point {
    x: Number
    y: Number

    def distance(): Number {
        return (self.x * self.x + self.y * self.y) ** 0.5;
    }
}

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
let s = Set();
s.add(1); s.add(2); s.add(1);  // duplicate ignored
print(s.size());   // 2

if (s.has(1)) { print("Found 1"); }
s.remove(1);

// Set operations
let a = Set([1, 2, 3]);
let b = Set([3, 4, 5]);
let union        = a.union(b);       // {1,2,3,4,5}
let intersection = a.intersect(b);   // {3}
let difference   = a.difference(b);  // {1,2}

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 std::numpy;

// 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
clase Persona {
    nombre: Cadena
    edad:   Numero
    def inicio(n: Cadena, e: Numero) {
        esto.nombre = n;
        esto.edad   = e;
    }
    def saludar(): Cadena { retornar "Hola, " + esto.nombre; }
}

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

// French
classe Personne {
    nom: Chaîne
    age: Nombre
    def initialiser(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), custom error types via class inheritance, 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.

Example

errors.lox
// try / catch / finally
try {
    let result = risky_operation();
    process(result);
} catch (e: NetworkError) {
    print("Network error: " + e.message);
} catch (e: ParseError) {
    print("Parse error: " + e.message);
} catch (e) {
    print("Unknown error: " + e);
} finally {
    cleanup();
}

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

// Custom error type
class ValidationError extends Error {
    def init(message, field) {
        super.init(message);
        self.field = field;
    }
}
throw ValidationError("Invalid email", "email");

// 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");
println "with newline";

// Type conversion
Number("42");      // 42
String(42);        // "42"
Boolean(1);        // true

// Type introspection
typeof value;          // Get type name as String
value is Number;       // true / false

// Utilities
range(1, 10);          // iterable [1..9]
len(array_or_string);  // length

String & Math ✅ Working

String methods

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

str.length;                       // 13
str.upper();                      // "HELLO, WORLD!"
str.lower();                      // "hello, world!"
str.trim();                       // removes leading/trailing whitespace
str.split(",");                   // ["Hello", " World!"]
str.replace("World", "Loxel");    // "Hello, Loxel!"
str.substr(0, 5);                 // "Hello"
str.contains("World");            // true
str.starts_with("Hello");         // true
str.ends_with("!");

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
import { np } from std::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;

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

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

// Linear regression
let lr = LinearRegression();
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. The native compiler and the VM implement all five hooks (@onCall, @onReturn, @onThrow, @onPropertySet, @onInstantiate) — natively they fire through the runtime dispatcher, inherit to subclasses, and a throwing @onPropertySet validation hook aborts the write catchably. All three modes fire all five hooks (@onThrow in the tree-walker was the last gap to be fixed — user throws now trigger the hook and the catch body runs exactly once). Tree-walker wrinkle: a throwing @onPropertySet validation hook does not yet abort the field write there. @onPropertyGet/@onInherit remain interpreted-only (native warns at compile time). 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`

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

// Null methods
null.isNull()        // true
null.orElse(42)      // 42
null.toString()      // "null"

Core-Class Subclassing ✅ Working

Every core class (Number, String, Boolean, Array, Map, Set) 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 tree-walker modes;
// the bytecode VM still skips them (issue #399) — the un-decorated
// body must therefore tolerate raw operands, 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'

Quick Reference

Feature support matrix across execution modes.

Feature	Tree-walker	Bytecode VM	LLVM
Variables / const	✅	✅	🚧
Functions & closures	✅	✅	🚧
Classes & inheritance	✅	✅	🚧
Interfaces & traits	✅	✅	✅
Generics	✅	✅	✅
All 9 pattern types	✅	✅	🚧
Default parameters	✅	✅	✅
Named arguments	✅	✅	✅
Rest parameters	✅	✅	✅
Async / await	✅	✅	🚧
i18n support	✅	✅	🚧
Module system	✅	✅	🚧
Language events	✅	✅	🚧
Unified object model	✅	✅	🚧
Channels / spawn	❌	❌	🚧
Abstract classes	📋	📋	📋
Static properties	📋	✅	🚧

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 implements the full surface and earlier interpreted-mode gaps are resolved (VM function decorators, tree-walker class decorators + @onThrow, @cached/@deprecated fixes). Remaining: VM user method decorators; tree-walker throwing-@onPropertySet abort; interpreted-only @onPropertyGet/@onInherit.
Planned syntax: map comprehensions, do-while. (try-as-expression has shipped — identical in all three modes.)