Axle v0.22.0

Conventions

Idiomatic Axle. Patterns the compiler, stdlib, and built-in tooling all expect. Following them keeps your code consistent with the stdlib examples and the axle tooling output.

Naming

KindConventionExample
Types (classes, traits)PascalCaseArrayList, IOException, Closeable
Free functions, methodscamelCaseparseInt, readLine, getName
Variables, parameters, fieldscamelCaseuserName, lineCount
Boolean queriesis… / has… / can…isEmpty, hasNext, canRead
Constants (module-level)SCREAMING_SNAKEMAX_BUFFER_SIZE
Type parametersSingle uppercase letterT, K, V, E
Modules / fileslower_snakestd::text::json, std::core::util

Stdlib follows mainstream OO conventions deliberately — coming from C#, Kotlin or Swift, every name maps to its expected shape (size() not len, isEmpty() not is_empty, IOException not IoError).

File layout

A typical source file groups one logical concern:

// 1. Imports
use std::collections::ArrayList;
use std::io::File;

// 2. Top-level constants
const MAX_LINES : i32 = 1000;

// 3. Types (traits before classes that implement them)
trait Encoder {
    fn encode(self, s : string) : string;
}

class Base64 : Encoder {
    pub fn encode(self, s : string) : string {
        return s;
    }
}

// 4. Free functions
fn loadConfig(path : string) : ArrayList<string> ! IOException {
    let lines : ArrayList<string> = new ArrayList<string>();
    lines.add(path);
    return lines;
}

// 5. Entry point (last)
fn main() : i32 {
    let cfg : ArrayList<string> = loadConfig("app.conf") catch _ {
        new ArrayList<string>();         // a value statement of the guarded type
    };
    return cfg.size();
}

Ownership idioms

The default parameter mode is borrowed (no keyword). Reach for a prefix only when the contract really differs:

class Rectangle {
    pub w : f64;      // `pub` — `area` reads them from outside the class
    pub h : f64;
    constructor(w : f64, h : f64) {
        self.w = w;
        self.h = h;
    }
}

// Borrowed — the default. The caller keeps ownership and the
// borrow cannot escape the call.
fn area(rect : Rectangle) : f64 { return rect.w * rect.h; }

// You will mutate fields of the param; caller still owns it.
fn translate(mut rect : Rectangle, dx : f64, dy : f64) : void {
    rect.w = rect.w + dx;
    rect.h = rect.h + dy;
}

// You take ownership; caller must not use it afterwards. Rare —
// reserve for explicit hand-off (e.g. into a queue / collection).
fn enqueue(own r : Rectangle) : void { }

// You take a refcounted handle. Cheap to copy (bumps the refcount).
// A `Shared<T>` is also the form to hand to a spawned task.
fn schedule(rect : Shared<Rectangle>) : void { }

When in doubt, borrow. Promoting later (borrow → mut, borrow → own) is mechanical; demoting (own → borrow) breaks callers.

When to use which storage tier

Axle has four allocation tiers picked automatically by the compiler’s escape analysis:

TierWhen the compiler picks itWhen you write it explicitly
StackLocal that never escapes the fnNever — automatic
ArenaLocal that escapes its declaring block but not the function frameRare — automatic in most code
Heap (new T(…))Escape into a return value / long-lived storelet x = new Foo(…)
Shared (share new T(…))Needs to outlive a single owner, or be handed to a spawned tasklet x = share new Foo(…)

The escape analysis is conservative — when it can’t prove an allocation stays local, it leaves it on the heap rather than risk an unsound promotion. The two you choose explicitly are heap (new T(…)) and shared (share new T(…)).

class Point {
    pub x : f64;
    pub y : f64;
    constructor(x : f64, y : f64) {
        self.x = x;
        self.y = y;
    }
}

// The compiler picks stack — `pt` never leaves `area`.
fn area() : f64 {
    let pt : Point = new Point(1.0, 2.0);
    return pt.x * pt.y;
}

// The compiler picks heap — escaped through the return.
fn makePoint() : Point {
    return new Point(1.0, 2.0);
}

// You pick shared — pt will be handed to a spawned task.
fn shared_point() : Shared<Point> {
    return share new Point(1.0, 2.0);
}

See Memory model and Shared<T> reference counting for the lifecycle details.

Error handling

A function’s failure set lives in its return type — : R ! E1, E2. A function that can fail must list it there; callers must either propagate (declare it onward) or catch. This holds for every family — there is no unchecked exemption. For a bug you never want to surface, hard-abort with std::ffi::runtime::panicMsg.

class Config {
    name : string,

    constructor(name : string) {
        self.name = name;
    }

    pub static fn defaults() : Config {
        return new Config("default");
    }
}

fn readFile(path : string) : string ! IOException {
    if (path.isEmpty()) {
        throw FileNotFoundException("no path given");
    }
    return "name=" + path;
}

// Declares what it can fail with — checked at compile time.
fn parseConfig(text : string) : Config ! ParseException {
    if (text.isEmpty()) {
        throw ParseException("config is empty");
    }
    return new Config(text);
}

// Caller propagates — the `!` set lists both, and the calls need no marker.
fn load() : Config ! ParseException, IOException {
    let text : string = readFile("/etc/app.conf");
    return parseConfig(text);
}

// Caller catches — must restore a meaningful state.
fn loadOrDefault() : Config {
    try {
        return load();
    } catch e : ParseException {
        return Config::defaults();
    } catch e : IOException {
        return Config::defaults();
    }
}

Rules:

  • Exceptions are exceptional — don’t use them for control flow on the happy path. Narrow a nullable with if (input == null) rather than reaching for exceptions: a null value is a T | null you must check, not a NullPointerException the language throws for you.
  • Always catch the most specific subtype first.
  • Use defer for cleanup — see below.
  • Don’t swallow exceptions silently. If you really mean “ignore”, say so with a one-line comment.

Stdlib operations are held to the same rule. ArrayList.removeAt raises a checked IndexOutOfBoundsException you must discharge. ArrayList.set does not throw: it returns false and writes nothing when the index is out of range. For a single call, the inline catch e { … } form is lighter than a full try block. Mind the trailing ;: the whole expr catch { … } is one statement, and the handler must either exit (return / throw / a call that never returns) or end on a value statement of the guarded type (value;). An empty {} is refused, and so is a handler that only prints: a guarded void call has no value for the handler to hand back, which is E0001 “the catch handler neither produces a value nor exits”.

When the handler only needs to report, use a try statement — its clause may fall through — and keep the expr catch form for a call whose value you want, or one you mean to abandon:

use std::collections::ArrayList;

fn demo() : void {
    let xs : ArrayList<i32> = new ArrayList<i32>();
    xs.add(10);
    try {
        xs.removeAt(3);                      // report and carry on
    } catch e : IndexOutOfBoundsException {
        println("out of range");
    }
    xs.removeAt(3) catch e { return; };      // or exit the fn
}

A fallible read is the mirror image — xs.get(i) returns T | null, not a throw, so you unwrap it with ?? default instead of catching.

See Reading compiler errors for diagnostic format and Error handling for patterns.

Cleanup with defer

Pair every acquisition with a defer for the release, immediately after acquisition:

use std::io::FileInputStream;
use std::io::FileOutputStream;
use std::io::FileOpenMode;

fn copyFile(src : string, dst : string)
    : void ! IOException, FileNotFoundException
{
    let input : FileInputStream = new FileInputStream(src);
    defer input.close();                    // releases on every exit path

    let output : FileOutputStream = new FileOutputStream(dst, FileOpenMode::WRITE);
    defer output.close();

    let mut b : i32 = input.read();
    while (b >= 0) {
        output.write(b);
        b = input.read();
    }
}

defer runs when the block that registered it exits — whether the exit is a return, an uncaught throw, a break / continue out of it, or plain fall-through. Written at the top level of a function body, that is function exit. Defers fire in LIFO order, so defer input.close() followed by defer output.close() closes output first, then input.

The same LIFO order interleaves your defers with the compiler’s own scope cleanup, and that is what makes the idiom above safe: a defer written under a declaration runs before that binding is torn down, so close() sees a live object rather than one whose buffers have already gone back to the allocator.

A defer written inside a nested if / for / { … } block fires at the end of that block, where the resource it names is still in scope. Cleanup that has to outlive the block belongs beside the acquisition, one level up.

Concurrency idioms

Shared<T> for lifetime, synchronized for access. The combination is the safe baseline — reach for atomics only when the state is a single value with no section around it:

class Counter {
    pub value : i32;
    constructor() {
        self.value = 0;
    }
}

fn worker(mut c : Shared<Counter>) : i32 {
    synchronized (c) { c.value = c.value + 1; }
    return 0;
}

fn main() : i32 ! InterruptedException {
    let c : Shared<Counter> = share new Counter();

    let f1 : Future<i32> = spawn worker(c);
    let f2 : Future<i32> = spawn worker(c);

    await f1;
    await f2;
    return c.value;                             // 2
}

A Shared<T> is used through its handle exactly as the object is used directly: its fields read and write (c.value), and its methods are called on the handle (c.bump()) — a self or mut self method borrows the object for the call while the handle keeps it alive. Only an own self method is refused (E0504), since it would take the object away from every other handle. The examples here keep the state in fields and the operations as free functions, so the reader sees a plain field read rather than a receiver conversion.

The lock is just an object — its identity keys the runtime mutex, which is re-entrant and owned by the task that entered it (by the thread’s own frame outside any task). A common pattern is to lock on the same Shared<T> you’re mutating, so the lock travels with the data. spawn worker(c) takes a function call, packs its arguments into the task, and runs it; no lambda machinery is needed for this shape.

Keep the waits out of a critical section. A task yields to a sibling at an await and at any wait the runtime owns — a channel send / receive(), a lock, acquire(), waitFor(), Thread.join, a blocking socket call. Waiting does not release a lock the task holds: a sibling that wants the same lock parks until the owner comes back and leaves the section, so a section that waits holds every contender for as long as it waits. Take the lock, read or write, release, and wait outside. A task that parks frees its carrier for the others; see Concurrency primitives for which waits a task may make, and which still hold the carrier.

For a single value with no section around it, an atomic class is one indivisible operation instead of a lock dance:

use std::concurrent::AtomicI32;

fn main() : i32 {
    let counter : AtomicI32 = new AtomicI32(0);
    counter.incrementAndGet();   // one indivisible op — no lock around it
    return counter.get();
}

See Tasks and async for the two-worlds model and Concurrency primitives for which primitive to reach for, and when.

Strings

Strings are immutable UTF-8. string is a value type — passing one to a fn copies a handle, not the bytes.

== / != on strings compare content — two distinct heap strings with equal bytes are equal. .equals(...) / .equalsIgnoreCase(...) remain available (the latter for case-insensitive comparison).

use std::text::StringBuilder;

fn main() : i32 {
    let name : string = "Ada";

    // Concatenation — left-to-right
    let greeting : string = "Hello, " + name + "!";
    println(greeting);

    // Building large strings — use StringBuilder, not iterative concat.
    let sb : StringBuilder = new StringBuilder();
    for (i of 0..100) {
        sb.append("line ");
        sb.appendI32(i);
        sb.append("\n");
    }
    let result : string = sb.toString();
    println(result);
    return 0;
}

Iterative += on strings allocates a new string each time (O(n²) over n iterations). StringBuilder is O(n).

Classes — order of declarations

Inside a class:

enum Role {
    ADMIN,
    USER,
}

class User {
    // 1. Fields (immutable refs / data first, mutable state after)
    id   : i64;
    name : string;
    role : Role;

    // 2. Constructor(s)
    constructor(id : i64, name : string, own role : Role) {
        self.id = id;
        self.name = name;
        self.role = role;
    }

    // 3. Query methods (no side effects)
    pub fn isAdmin(self) : bool {
        return self.role == Role::ADMIN;
    }

    // 4. Mutators
    pub fn rename(mut self, newName : string) : void {
        self.name = newName;
    }
}

Prefer an enum over a string for a closed set of states — the compiler then rejects typos at compile time instead of letting "amdin" slip through to runtime.

Keep classes focused — one responsibility. If a class has more than 5–7 fields or 10–15 methods, split it.

Modules and use

// Group `use` declarations at the top, one per line.
use std::collections::ArrayList;     // a TYPE — import by name
use std::collections::HashMap;       // a TYPE — import by name
use std::io::File;                   // a TYPE — import by name
use std::text;                       // a MODULE — for its free functions

Import a type by its bare name; import a module for its free functions. The two forms are not interchangeable — pick by what you’re reaching for:

Reaching for…WriteCall site
A type (class / trait / exception)use std::collections::ArrayList;new ArrayList<i32>()
A module’s free functionsuse std::text;text::f64ToString(x)

Prefer importing the module for its free functions (use std::text;) and calling text::f64ToString(...) — the module:: prefix documents the origin at every call site, and one use line then covers the whole module’s surface. Importing a single free function (use std::text::f64ToString;) is accepted by the compiler, and is the natural form when a file reaches for exactly one symbol. Greps for callers are faster and the diff says exactly what each file pulls in.

Test programs

Axle has no separate unit-test harness; the working convention is one small program per behaviour, returning its verdict through the process exit code:

// Checks compound assignment on locals.
fn main() : i32 {
    let mut x : i32 = 40;
    x += 2;
    if (x == 42) { return 0; }       // 0 = pass
    return 1;                        // non-zero = which check failed
}

Conventions:

  • One behaviour per file, named after it (compound_assign.axle).
  • return 0 means “passed”; distinct non-zero codes identify which assertion failed.
  • A one-line // description at the top says what’s being exercised.
  • Each file is a standalone program — build and run it directly: axle build compound_assign.axle -o compound_assign and then run the produced binary.

Limits / Uncabled

FeatureStateDetail / workaround
Wildcard import (use std::collections::*;)Does not parseSpell every type name out. Each use names one symbol, or one module
Catch handler that falls through with no valueRefused (E0001)End the handler with a value of the guarded type, or return / throw

See also

conventionsstyleidiomsbest-practices