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

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.

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!`;

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}"

Control Flow ✅ Working

Standard if/else, unless, while, do-while, C-style for, range-based for-in, and comprehensions.

Example

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

// unless (inverted if)
unless (is_weekend) { go_to_work(); }

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

// do-while (executes at least once)
let input;
do { input = get_user_input(); } while (input == nil);

// 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;

Generics ✅ Working

Generic classes and functions use <T> type parameters. Type bounds use extends. 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]];

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`)
class MathUtils {
    static let callCount = 0;
    static def sqrt(x: Number): Number { /* ... */ }
}
MathUtils.sqrt(16);

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 +, -, *, **, /, %, ==, !=, <, >, <=, >=, <=>, and the unary -@ / !. There is no operator keyword.

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 or classes. Fully working in tree-walker. Bytecode support in progress.

Example

decorators.lox
// Decorator factory
def performance(fn) {
    return def(...args) {
        let start = DateTime.now();
        let result = fn(...args);
        print `${fn.name} took ${DateTime.now() - start}ms`;
        return result;
    };
}

@performance
def slow_function() { /* expensive work */ }

slow_function();  // prints timing info

// Stacking decorators (applied bottom-to-top)
@performance
@memoize
def fibonacci(n) {
    if (n <= 1) return n;
    return fibonacci(n - 1) + fibonacci(n - 2);
}

// Class decorator
@Singleton
class Config { settings: Map }

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 **), comparison (incl. strict === / !==), membership (~> / <~, Unicode ∈ ∋ ∉ ∌), logical, assignment, null-handling, pipeline, spread, and type-checking operators.

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

// 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)

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

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

// Pipeline — left value passed to right function
let response = raw_request |> parse |> validate |> handle;

// 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)
// 2. Exponent:     **  (right-associative; tighter than unary minus)
// 3. Unary:        !  -  typeof  await
// 4. Factor:       *  /  %
// 5. Term:         +  -
// 6. Range:        ..  ..=
// 7. Comparison:   <  >  <=  >=  <=>  is  ~>  <~  (∈ ∋ ∉ ∌)
// 8. Equality:     ==  !=  ===  !==  (=== / !== skip operator overloads)
// 9. Logical AND:  &&
// 10. Logical OR:  ||
// 11. Pipeline:    |>
// 12. Ternary:     ? :  (and if-expressions)
// 13. Null-coalesce: ??  ?:
// 14. 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)

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) or arr[1..=3] (inclusive).

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
let slice = nums[1..3];   // [2, 3]  (exclusive end)
let incl  = nums[1..=3];  // [2, 3, 4] (inclusive)

// 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);

// Other useful methods
nums.reverse();
nums.sort();
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().

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
if ("Alice" in 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
ages.keys();    // ["Alice", "Bob", ...]
ages.values();  // [30, 25, ...]
ages.entries(); // [["Alice", 30], ...]
ages.size();
ages.empty();
ages.clear();

Sets & Tuples 🚧 In Progress

Sets store unique values with union/intersection/difference operations. Tuples are fixed-structure named pairs.

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
// Named tuple
let point = (x: 10, y: 20);

print point.x;  // 10
print point.y;  // 20

// Destructure
let (x, y) = point;

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

Multilingual Keywords ✅ Working

Write code in 7 languages. Keywords and type names are internationalized. Run with loxel run --lang es.

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

Language	Function	Class	String	Number
English	`def`	`class`	`String`	`Number`
Español	`def`	`clase`	`Cadena`	`Numero`
Français	`def`	`classe`	`Chaîne`	`Nombre`
Deutsch	`def`	`klasse`	`Zeichenkette`	`Zahl`
Português	`def`	`classe`	`Cadeia`	`Numero`
日本語	`def`	`クラス`	`文字列`	`数値`
中文	`def`	`类`	`字符串`	`数字`

Error Handling ✅ Working

Standard try/catch/finally blocks, custom error types via class inheritance, and try as an expression.

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

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

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"]);  // rank 8, alpha 16
let opt = AdamW(lora_parameters(set), 1e-3);          // only adapters train

let loss = lora_train_step(model, set, opt, X, Y, lr);  // 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";

let model = load_pretrained_q4("SmolLM2-360M.gguf");
let set   = load_adapter("loxel_adapter.gguf", model);   // 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);

// 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);
dense.dealloc();

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

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

let a = Tensor(256, 512); a.fill_normal(0.0, 0.02);
let b = Tensor(512, 128); b.fill_normal(0.0, 0.02);
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();

Execution Modes ✅ Working

Three modes: tree-walking interpreter (default, full feature support), bytecode VM (faster, most features), and LLVM compiler (native code, 50–100× speedup).

Mode	Speed	Features	Usage
Tree-walker	Baseline	All features	`loxel script.lox`
Bytecode VM	18× faster	Core features	`loxel script.lox --bytecode`
LLVM	50–100× faster	Native binary	`loxel compile script.lox -o out`
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.

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("DEBUG")   // log calls and returns at DEBUG level
    @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"

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

LLVM: Compiler in progress (Phase 7). Use --bytecode for production.
Channels / spawn: Not yet implemented. Async uses Promises; channel-based concurrency in progress.
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.
Object pattern guards in bytecode: Guards on object/map patterns work in tree-walker; bytecode support in progress.
Promise.all / race: Not yet implemented in any mode.

Workarounds

Use loxel script.lox --tree-walker for full feature access.