Decorators

Decorators are annotations that modify the behavior of functions and structs. They use the @name syntax placed before a declaration.

@test #

Marks a function as a test. Test functions are collected and run with zolo test.

@test
fn test_addition() {
    assert_eq(2 + 2, 4, "basic math")
}

@test
fn test_string_concat() {
    let result = "hello" + " " + "world"
    assert_eq(result, "hello world", "string concat")
}

Running Tests #

zolo test my_tests.zolo              # run all tests
zolo test my_tests.zolo --filter fib # only matching tests
zolo test my_tests.zolo --list       # list test names

Test Assertions #

assert_eq(actual, expected, "message")   // assert equality
assert_ne(actual, expected, "message")   // assert inequality

@memoize #

Automatically caches function results. Repeated calls with the same arguments return the cached value instead of recomputing.

@memoize
fn fibonacci(n: int) -> int {
    if n <= 1 { n } else { fibonacci(n - 1) + fibonacci(n - 2) }
}

// First call computes normally
print(fibonacci(40))  // fast! cached intermediate results

// Subsequent calls with same args are instant
print(fibonacci(40))  // returns from cache

How It Works #

The compiler wraps the function with a cache table. Arguments are serialized as a key, and the result is stored. On repeated calls with the same arguments, the cached result is returned immediately.

Best For #

• Recursive functions (like fibonacci, tree traversals)
• Pure functions with expensive computation
• Functions called repeatedly with the same inputs

Limitations #

• Only works with serializable arguments
• Cache grows unbounded (no eviction)
• Not suitable for functions with side effects

@deprecated #

Marks a function as deprecated. When called, it prints a warning to stderr (once per function).

@deprecated("use new_calculate() instead")
fn old_calculate(x: int) -> int {
    x * 2
}

old_calculate(5)
// stderr: WARNING: 'old_calculate' is deprecated: use new_calculate() instead

Without Message #

@deprecated
fn legacy_api() {
    // ...
}

legacy_api()
// stderr: WARNING: 'legacy_api' is deprecated

Behavior #

• The warning is printed only once per deprecated function (not on every call)
• The function still executes normally after the warning
• Output goes to stderr, not stdout

@builder #

Generates a builder pattern for structs. The builder allows constructing structs field-by-field with method chaining.

@builder
struct Config {
    host: str,
    port: int,
    debug: bool,
}

let cfg = Config.builder()
    .host("localhost")
    .port(8080)
    .debug(true)
    .build()

print(cfg.host)   // "localhost"
print(cfg.port)   // 8080
print(cfg.debug)  // true

Generated Methods #

For each field name: Type in the struct, @builder generates:

• StructName.builder() — creates a new builder instance
• .field_name(value) — sets the field value, returns the builder
• .build() — creates the final struct instance

Example: Complex Builder #

@builder
struct Request {
    url: str,
    method: str,
    timeout: int,
    headers: {str: str},
}

let req = Request.builder()
    .url("https://api.example.com")
    .method("POST")
    .timeout(30)
    .build()

@op / @operator #

Marks a method inside an impl block as the implementation of a specific operator. The compiler wires the method to the matching Lua metamethod and — for the native backend — to the canonical operator method name. Unlike the name-convention path (fn add → __add), the decorator lets the method have any name; the intent stays explicit at the declaration site.

struct Vec2 {
    x: int,
    y: int,
}

impl Vec2 {
    @op("+")
    fn plus(self, other) {
        return Vec2 { x: self.x + other.x, y: self.y + other.y }
    }

    @op("-")
    fn minus(self, other) {
        return Vec2 { x: self.x - other.x, y: self.y - other.y }
    }

    @op("unary-")
    fn invert(self) {
        return Vec2 { x: -self.x, y: -self.y }
    }

    @op("==")
    fn same(self, other) {
        return self.x == other.x && self.y == other.y
    }
}

let a = Vec2 { x: 3, y: 4 }
let b = Vec2 { x: 1, y: 2 }
print((a + b).x)   // 4
print((-a).x)      // -3
print(a == b)      // false

@operator("symbol") is a verbose alias that produces the same effect.

Supported symbols #

- is binary subtraction; use "unary-" for the unary minus operator (Lua's __unm).

Coexists with the name convention #

The existing convention still works: a method literally named add is still wired to __add automatically — no decorator needed. The decorator is only required when you want a different method name or want to be explicit about the binding.

impl Money {
    @op("+")
    fn combine(self, other) {     // any name
        return Money { cents: self.cents + other.cents }
    }

    fn mul(self, other) {         // name convention — no decorator
        return Money { cents: self.cents * other.cents }
    }
}

Custom Decorators #

Decorators follow the syntax:

@name
@name(arg1, arg2)

The decorator name and arguments are stored in the AST and processed during compilation. The built-in decorators above are handled by the compiler. To define your own decorators in Zolo, use mixin functions (below).

Mixin Functions #

A mixin is a user-defined decorator written in plain Zolo. You declare it with @mixin fn name() { ... } and apply it to any function with @name. Inside the mixin body, super() calls the wrapped target.

@mixin
fn traced() -> int {
    print(">> enter")
    let r = super()   // calls the wrapped function
    print("<< exit")
    return r           // the mixin's return value is the call's result
}

@traced
fn square(n: int) -> int {
    return n * n
}

print(square(5))
// >> enter
// << exit
// 25

How it works #

Applying @traced rebinds square to a wrapper. Calling square(5) runs the mixin body; super() invokes the original square, re-passing the same arguments. The mixin can run code before and after super(), transform its result, or skip it entirely.

Passing arguments through #

super() with no arguments forwards the original call's arguments unchanged — you don't repeat the parameter list:

@mixin
fn logged() -> int { return super() }

@logged
fn add(a: int, b: int) -> int { return a + b }

print(add(2, 3))   // 5

Short-circuit: skip the target #

A mixin that returns without calling super() never runs the target. This is the basis for feature flags, circuit breakers, and dry-runs:

@mixin
fn disabled() -> int {
    return 0       // super() is never called — the target body is skipped
}

@disabled
fn dangerous() -> int {
    return 999     // never runs
}

print(dangerous())   // 0

Composition #

Mixins stack like any decorator, bottom-up — the mixin closest to the fn is the innermost layer:

@mixin
fn plus_one() -> int { return super() + 1 }

@mixin
fn times_three() -> int { return super() * 3 }

@times_three   // outermost
@plus_one      // innermost
fn base() -> int { return 10 }

print(base())   // (10 + 1) * 3 = 33

times_three.super() runs plus_one, and plus_one.super() runs base.

Parameterised mixins #

Declare parameters on @mixin(...) and pass values at the application site. This is the shape of @retry(n), @cache(ttl), @rate_limit(rps), and friends. The parameter is an ordinary local in the body; super() still forwards the target's own arguments.

@mixin(times: int)
fn repeated() -> int {
    var total = 0
    for _ in 0..times {
        total = total + super()   // run the target `times` times
    }
    return total
}

@repeated(3)
fn one() -> int { return 1 }

print(one())   // 3

Modifying the arguments #

super(a, b) calls the wrapped function with explicit arguments instead of forwarding the originals — useful for sanitising or defaulting inputs. This composes through a stack: an outer mixin's super(x) flows down to the next layer.

@mixin
fn clamp_positive() -> int {
    let n = super(0)   // ignore the caller's value, force 0
    return n
}

Mixins on methods #

A mixin applies to an impl method too. super() forwards the receiver automatically, and if the mixin body touches self, it reads the receiver directly:

@mixin
fn audited() -> int {
    let before = self.balance   // the receiver is in scope
    return super() + before
}

struct Account { balance: int }

impl Account {
    @audited
    fn snapshot(self) -> int { return self.balance }
}

A mixin that uses self is a method mixin and can only be applied to methods (not free functions).

Diagnostics #

zolo check reports:

• TM100 — super used outside a @mixin fn body.
• TM112 — a self-using (method) mixin applied to a free function.

Current scope and limitations #

Mixins are new; the first cut covers the core (see specs/mixin-functions.html for the full design and roadmap):

• Parameter types on @mixin(name: type) are advisory — they're not yet enforced by the type checker.
• A mixin's effect set (with E) is not yet propagated onto the wrapped function's type — effect tracking is still advisory (v1).
• A mixin name can't shadow a built-in decorator name (@memoize, @retry, @log, @test, @bench, @cached, @benchmark, @deprecated, @validate, ...). Pick a different name.
• Supported on the VM/Lua backend.

Combining Decorators #

Multiple decorators can be applied to a single declaration:

@test
@memoize
fn test_cached_fibonacci() {
    assert_eq(fibonacci(10), 55, "fib(10)")
}

Decorators are applied in bottom-up order (closest to the function first).