Macros

A function whose name starts with # is a macro. Its body is put into the caller, instead of being called.

A simple macro

fn #temp_memory($size: i64): []u8 {
    buf: [$size]u8 = #memory_garbage;
    return buf.^ |> slice();
}

fn main() {
    {
        temp_buf := #temp_memory(512);
        // temp_buf points to a 512 byte array on the stack
    }
    // the array is gone here
}

The array lives in the caller’s scope, so the returned slice is valid until the end of that scope. A normal function could not do this.

Names are hidden by default

Variables inside a macro are not visible to the caller. So a macro can not break the caller’s variables by accident. These are called hygienic macros.

Sharing with the caller

Put a backtick ` before a name to make it visible to the caller:

fn #make_x(): void {
    `x : i32 = 0;
}

fn main() {
    #make_x();
    x += 1; // x comes from the macro
}

The backtick works for defer and control flow too. They then act in the caller’s scope:

fn #example(): void {
    `x : i32 = 0;

    {
        // runs at the end of the caller's scope,
        // not at the end of this block
        `defer `x += 1;
    }

    // returns from the caller
    `return;
    // `break; and `continue; also work
}

Example: fail and return

From examples/4_sdl3.mox. On error, it prints a message and returns -1 from the function that used it:

fn #fail($fmt: []u8, values: $T) {
    println($fmt, values);
    println(from_c_string(SDL_GetError().cast(*u8)));

    `return -1;
}

#linkc fn main(): i32 {
    if (!SDL_Init(SDL_INIT_VIDEO)) {
        #fail("sdl init failed", .{});
    }
    // ...
    return 0;
}

Taking code as an argument

A macro can take code (__ast_ptr) and insert it with #land_ast:

fn #repeat(n: u64, code: __ast_ptr) {
    `it: u64 = 0;
    while (`it < n) {
        `#land_ast code;
        `it = `it + 1;
    }
}

fn main() {
    total : u64 = 0;
    #repeat(10, #ast total += it);
}

`#land_ast inserts the code as if it was written in the caller, so it sees the caller’s names, like total. Plain #land_ast inside a macro sees only the macro’s own names.

it comes from the macro with a backtick, so the code you pass can use it.

Aliases

#alias name = expression; gives a name to an expression. It can be in a module, in a function or in a struct:

struct Something {
    ptr: *i32;
    len: i64;

    // inside a struct, self is a pointer to the struct
    #alias as_slice = slice(self.ptr, self.len);
    #alias size = self.len;
};

s.size = 10; // writes s.len

The expression is compiled where the alias is declared, not where it is used. So unlike C defines, it can not see the caller’s variables.

Aliase’s expression is compiled again each time it is used and also makes code less predictable. Use them only when you really need them.