Axle v0.22.0

Hello, Axle

A complete first program, then the build and run commands:

// hello.axle
fn main() : i32 {
    println("Hello, Axle!");
    return 0;
}
./target/release/axle build hello.axle -o hello
./hello
# Hello, Axle!

The commands on this page call the from-source binary by its path, ./target/release/axle. If you installed axle from apt or the Windows MSI, it is already on your PATH. Drop the prefix and run axle build hello.axle -o hello.

Read the program

  • fn main() : i32: every program starts at main. The : i32 return type is the process exit code. 0 means success. A non-zero value signals an error to the shell. The axle new scaffold uses fn main() : void instead, for a program that always succeeds.
  • println(...): prints a line to standard output. It is part of the prelude, so it needs no use. The explicit form Console::println(...) calls the same builtin. Console is one of the few classes that are always in scope. The axle new scaffold writes the explicit form. Declaring your own top-level fn println(...) shadows the prelude word: from then on, a bare println(...) calls your function.
  • :: reaches a namespace member: a static method on a class (Random::seed(42)), a module function (math::pi(), after use std::numeric::math;), or an enum variant (Color::Red). . is for instance members. The language tour covers both in more depth.
  • No free, no garbage collector. The compiler decides where each value lives, and inserts its cleanup for you. See the Memory model.

Note: axle run hello.axle builds a native binary and executes it in one step. It does the same inside a project directory. axle build performs the same build, and keeps the binary.

Inspect what the compiler produced

# LLVM IR, after the optimiser when -O > 0
./target/release/axle build hello.axle -O 2 --emit llvm -o hello.ll

# Native assembly
./target/release/axle build hello.axle -O 2 --emit asm -o hello.s

# Intermediate-representation debug dumps (provisional shape)
./target/release/axle build hello.axle --emit hir -o hello.hir
./target/release/axle build hello.axle --emit ast -o hello.ast

The full list of --emit kinds, and what each one shows, is in the command-line reference.

A slightly bigger example

use std::collections::ArrayList;

fn main() : i32 {
    let squares : ArrayList<i32> = new ArrayList<i32>();
    for (i of 0..10) {
        squares.add(i * i);                  // 0, 1, 4, 9, ..., 81
    }

    let mut sum : i32 = 0;
    for (s of squares) {
        sum = sum + s;
    }
    println(sum);                            // 285
    return 0;
}

for (i of 0..n) walks a range. It is the idiomatic loop in Axle. The same for (s of squares) head visits the elements of a collection, an array, or a class of your own that declares hasNext() : bool and next(). When you need the position too, index it over 0..xs.size() and read xs.get(j).

println is one prelude builtin, not a family of overloads. It is variadic, and the compiler picks the format from the argument’s static type at the call site. There is therefore no per-type variant name to remember. It accepts:

Argument typeHow it prints
bool, char, stringits text
every sized integer (i8 to i64, u8 to u64)its decimal value
f32, f64its floating-point value
a class instance, Shared<T> or Weak<T> referenceits address
a borrow, or a T \| null of one of the abovethe value, or its address

ArrayList lives in std::collections. The API reference has the complete method list.

Model data with enum and match

A closed set of cases is an enum. match selects an arm, and it is an expression in its own right, so it returns directly. The compiler checks that every variant is covered. A missing case is a compile error, not a runtime surprise:

enum Color { Red, Green, Blue }

fn name(c : Color) : string {
    return match c {
        Color::Red   => "red",
        Color::Green => "green",
        Color::Blue  => "blue",
    };
}

fn main() : i32 {
    println(name(Color::Green));             // green
    return 0;
}

Two chapters cover these constructs. Enums covers variant payloads, backing types and enum methods. Pattern matching covers every pattern kind, and the exhaustiveness rule. The rest of the type system (struct value types, trait contracts, generics and @derive) is in the language tour and in Generics and traits.

Limits / Uncabled

FeatureStateDetail / workaround
println of a struct valueRefused (E0775)A value-type struct has no text form. Print its fields (p.x), or a toString that the struct provides
println of a class instancePrints its addressThe output is a pointer, not a rendering. Give the class a toString and print that when the address is not what you meant
for (c of s) over a stringRefused (E0517)for ... of takes a range, an array, a collection, or a class that declares hasNext and next. Walk a string by index: for (j of 0..s.length)

See also

getting-startedtutorialhello-world