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
| Kind | Convention | Example |
|---|---|---|
| Types (classes, traits) | PascalCase | ArrayList, IOException, Closeable |
| Free functions, methods | camelCase | parseInt, readLine, getName |
| Variables, parameters, fields | camelCase | userName, lineCount |
| Boolean queries | is… / has… / can… | isEmpty, hasNext, canRead |
| Constants (module-level) | SCREAMING_SNAKE | MAX_BUFFER_SIZE |
| Type parameters | Single uppercase letter | T, K, V, E |
| Modules / files | lower_snake | std::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:
| Tier | When the compiler picks it | When you write it explicitly |
|---|---|---|
| Stack | Local that never escapes the fn | Never — automatic |
| Arena | Local that escapes its declaring block but not the function frame | Rare — automatic in most code |
Heap (new T(…)) | Escape into a return value / long-lived store | let x = new Foo(…) |
Shared (share new T(…)) | Needs to outlive a single owner, or be handed to a spawned task | let 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 aT | nullyou must check, not aNullPointerExceptionthe language throws for you. - Always catch the most specific subtype first.
- Use
deferfor 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… | Write | Call site |
|---|---|---|
| A type (class / trait / exception) | use std::collections::ArrayList; | new ArrayList<i32>() |
| A module’s free functions | use 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 0means “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_assignand then run the produced binary.
Limits / Uncabled
| Feature | State | Detail / workaround |
|---|---|---|
Wildcard import (use std::collections::*;) | Does not parse | Spell every type name out. Each use names one symbol, or one module |
| Catch handler that falls through with no value | Refused (E0001) | End the handler with a value of the guarded type, or return / throw |
See also
- Language tour — the syntax reference.
- Memory model — escape analysis and tiers.
Shared<T>reference counting — refcount lifecycle.- Reading compiler errors — diagnostic format.
- Recipes — task-oriented examples.
- Concept index — every concept on one page.