Attributes

Attributes

Attributes are compile-time AST transformations. They modify the structure of declarations renaming fields, injecting code, adding members with full access to the parsed syntax tree and type information. Unlike macros, which operate on raw tokens before parsing, attributes run after parsing and can inspect and modify typed AST nodes.

PropertyGuarantee
Type safetyYes
HygieneYes
ScopeYes
Expansion timeCompile time
Expansion orderInner to outer
Expansion contextThe node the attribute is attached to

Defining Attributes

Attribute macros parse, but the compiler does not expand them yet: using one is rejected with SC116E rather than doing nothing. See Status.

Attributes are defined with the macro keyword followed by @name and a parameter list. The first parameter is always a pointer to the AST node being transformed:

import std::AST

macro @add_logging(node: *AST::FunctionDecl) {
    node->body.prepend(
        AST::parse!(std::io::println(f"entering {stringify!(node->name)}"))
    )
    node->body.append(
        AST::parse!(std::io::println(f"exiting {stringify!(node->name)}"))
    )
}
@add_logging
fn process_data(x: i32) -> i32 {
    return x * 2
}

After expansion:

fn process_data(x: i32) -> i32 {
    std::io::println("entering process_data")
    var __result = x * 2
    std::io::println("exiting process_data")
    return __result
}

Node preservation rule

Attributes must preserve the node type. An attribute attached to a function declaration receives a *AST::FunctionDecl and must leave it as a function declaration it cannot replace it with a class or a variable. This ensures the expansion process is deterministic and the AST remains structurally consistent.

To add new nodes, create them with @create AST::NodeType() and attach them to the existing node (e.g., appending statements to a function body, adding members to a class).


Attribute Arguments

Attributes can take additional arguments beyond the implicit node parameter:

macro @repeat(block: *AST::Block, times: i32) {
    var original = block->clone()
    var *expanded = @create AST::Block()

    for i in 0..times {
        expanded->body.append(original.clone())
    }

    *block = *expanded
}

@repeat(3)
{
    std::io::println("hello")
}

After expansion:

{
    { std::io::println("hello") }
    { std::io::println("hello") }
    { std::io::println("hello") }
}

Arguments are passed in parentheses after the attribute name at the use site. The node parameter is implicit it is always the declaration or block the attribute is attached to.


Overloading

Attribute definitions can be overloaded by node type or argument types. The compiler selects the correct overload based on what the attribute is attached to:

macro @serialize(node: *AST::ClassDecl) {
    // generate serialization for a class
}

macro @serialize(node: *AST::StructDecl) {
    // generate serialization for a struct
}
@serialize
class Config { ... }    // calls the ClassDecl overload

@serialize
struct Point { ... }    // calls the StructDecl overload

Expansion Order

When multiple attributes are stacked on a single declaration, they expand inner to outer the attribute closest to the declaration runs first:

@deserialize    // runs second, on the result of @serializable
@serializable   // runs first, on the original class
class Config {
    var host: string
    var port: i32
}

This allows attributes to compose @serializable can add serialization methods, and @deserialize can then inspect those methods to generate the inverse.


Attaching Attributes

Attributes can be attached to any AST node:

// On a function
@no_unwind
fn checksum(data: [u8;]) -> u32 { ... }

// On a class
@packed
class Header { ... }

// On a struct
@align(16)
struct SimdData { ... }

// On a block
@repeat(3)
{ std::io::println("repeated") }

// On a variable (if the attribute accepts VariableDecl)
@deprecated("use new_config instead")
var old_config: Config

An attribute can also be applied to an expression: @name operand, or @name(args) operand. The operand is one unary expression, including its calls, member accesses and initializers, so @create Config(8080) applies to the whole constructor call. Binary operators bind looser (@a x + 1 is (@a x) + 1), and a member access on the result needs parentheses: (@create Config(8080))->port. At the start of a statement, an @name is an expression attribute when an expression follows it on the same line (@destroy p, @create Config(8080)); it attaches to the statement or declaration instead when what follows is a declaration (@deprecated var, @copy fn), a keyword statement (@likely if), a block (@repeat(3) { ... }), a loop label, or a line break.

Two expression attributes have a meaning: @create T(args) and @destroy p (see Heap Allocation). Every other one parses but is rejected with SC116E, as is the initializer form @create T{...}. See Status.


Built-in Attributes

Kairo provides built-in attributes that are handled directly by the compiler:

Layout attributes

AttributeDescriptionApplies to
@packedRemove padding between membersClasses, structs, unions
@align(N)Set minimum alignment to N bytesClasses, structs, unions, fields, variables

@packed lays the members out back to back at alignment 1, with no padding between them or at the end, as C's __attribute__((packed)) does. @align(N) raises the alignment to N (it never lowers it below the natural alignment), and the size rounds up to a multiple of it. N is an integer literal, a power of two, at most 2^28; anything else is an error. On a field or a variable, @align(N) raises that member's or variable's alignment the same way. Together on one record, @packed @align(N) packs the members and aligns the whole to N, like __attribute__((packed, aligned(N))).

@packed struct P { var a: u8; var b: u32 }      // sizeof 5, alignof 1
@align(16) struct Q { var a: u8 }               // sizeof 16, alignof 16
@packed @align(4) struct PA { var a: u8; var b: u32 }   // sizeof 8, alignof 4
struct F { var a: u8; @align(8) var b: u8 }     // b at offset 8; sizeof 16

The layout the compiler computes for sizeof and alignof in a declaration-scope eval if is the same one the generated C++ has, so a branch chosen on a record's size matches the size at run time. A heap allocation of an @align(N) type through create is N-aligned: it asks the allocator for alignof T.

See Classes and Structures for layout details.

Branch hints

AttributeDescriptionApplies to
@likelyCondition is expected to be trueif statements
@unlikelyCondition is expected to be falseif statements
@unreachableBranch should never execute (UB if reached). Not implemented yet: rejected with SC116Ematch/if branches
@likely / @unlikely before elseHint for the else or else if branch that followselse, else if
@assume(cond)The optimizer may take cond as true from here on (UB if it is false)A statement of its own

@likely and @unlikely also go between a branch's closing } and the else after it; each hint is for the branch it precedes. @assume(cond) is not an attribute on anything: it is a statement on its own line.

@likely if a {
    fast()
} @unlikely else if b {
    rare()
} @unlikely else {
    rarer()
}

@assume(n > 0)

See Control Flow for branch prediction hints.

Diagnostics

AttributeDescriptionApplies to
@no_warn(CODE)Suppress a specific compiler warningAny declaration
@deprecated(msg)Mark a declaration as deprecatedAny declaration

@deprecated (with no argument) or @deprecated("message") makes every use of the declaration a warning that names it and the message, with a note at the attribute. The declaration itself is not reported, and neither is a use inside it.

@deprecated("use read_all instead")
fn read() -> i32 { return 0 }

fn main() -> i32 { return read() }   // warning: 'read' is deprecated: use read_all instead

@no_warn(CODE, ...) drops those warnings wherever they are reported inside the declaration, by any stage of the compiler. Each code must be a warning code (SC031W): an unknown code is an error, and so is an error code, since an error cannot be suppressed.

@no_warn(SC031W)
fn f() -> i32 { var y: i32 = 1 as i32; return y }   // no redundant-cast warning

Unwinding

AttributeDescriptionApplies to
@unwindLet a C++ exception pass through this functionFunctions, methods
@no_unwindKeep the function noexcept, even under -funwindFunctions, methods

Every Kairo function is noexcept in its generated C++ declaration and definition: a C++ exception that reaches a Kairo frame terminates the program (std::terminate). @unwind removes the noexcept from one function, so a C++ exception thrown by a C++ callee unwinds through it to the next frame up. The -funwind flag removes it from every Kairo function, closures included; @no_unwind keeps it on one function even then. Marking one function both is an error.

fn add(a: i32, b: i32) -> i32 { return a + b }        // C++: int add(int a, int b) noexcept
@unwind fn relay(x: i32) -> i32 { return cxx_may_throw(x) }   // C++: int relay(int x)

Writing @unwind or @no_unwind on any one declaration of a function covers all of them: a forward declaration, the declaration inside a class, or the out-of-line definition.

class Counter {
    var n: i32
    @unwind fn get(const self) -> i32     // declared here...
}

fn Counter::get(const self) -> i32 { return self.n }   // ...so this definition is not noexcept either

A closure cannot carry @unwind yet: written before a closure, it is an expression attribute, which is not supported. A closure follows -funwind.

See Exceptions for how C++ exceptions move through Kairo code.

Function hints

AttributeDescriptionC++Applies to
@hot_pathThe function runs often: optimize it for speed and keep it close to other hot code[[gnu::hot]]Functions, methods
@cold_pathThe function runs rarely (error handling, setup): optimize it for size and keep it out of the way[[gnu::cold]]Functions, methods
@pureThe function's result depends only on its inputs and memory it can read, and it writes nothing else[[gnu::pure]]Functions, methods
@no_inlineNever inline the function: it keeps its own symbol and its own code, as for a benchmark kernel or a rarely taken path kept out of its caller__attribute__((noinline))Functions, methods
@hot_path fn next(state: *Rng) -> u64 { /* ... */ }
@cold_path fn report_failure(code: i32) { /* ... */ }
@pure fn length_sq(v: *Vec3) -> f64 { return v->x * v->x + v->y * v->y + v->z * v->z }

Each is a promise to the optimizer, written on the function and checked where the compiler can. @hot_path together with @cold_path on one function is an error, and any of the three on something that is not a function ('@hot_path applies only to a function') is an error with a fix-it that removes it.

@pure is checked. The function must return a value, must not be -> !, @unwind, virtual or an interface requirement (an override would not be held to the promise), and its result type must not own memory. In its body the compiler reports:

  • a write to a global or static variable;
  • an assignment through a pointer (*p = x, p->field = x, p[i] = x), to a field of self, or to an @inout parameter;
  • a call to anything that is not a const function, another @pure function, an eval fn or a side-effect-free compiler intrinsic; a user operator is a call too, and a call through a function value or an interface requirement is always an error;
  • making a value that owns memory (a string, an f-string, a vector, a local of such a type, a by-value copy of one);
  • assert, unwrap!, an asserting downcast, delete, inline C++, spawn, thread and await;
  • a for ... in loop over anything but a range (0..n) or a fixed-size array.

Reading globals and reading through pointers is allowed; that is the difference between @pure and a const function, which may read only its own inputs. A @pure function whose result changes between calls with the same arguments because something else wrote the memory it reads is fine: the optimizer only merges calls when no write could have happened in between.

By default the compiler also finds the functions that keep the const or @pure promise without saying so, by the same rules, and gives them the same C++ attribute, on their declaration in every file that imports them. -fno-infer-purity turns this off.

Calling conventions

AttributeDescriptionC++Applies to
@preserve_mostThe callee saves nearly every general-purpose register: for a rarely taken slow path called from hot integer code__attribute__((preserve_most))priv functions and methods
@preserve_allAs @preserve_most, and the callee also saves the floating-point and vector registers__attribute__((preserve_all))priv functions and methods
@preserve_noneThe callee saves nothing: for tail-call-heavy dispatch, such as an interpreter's opcode handlers__attribute__((preserve_none))priv functions and methods

At most one per function, never on a function C or C++ can see, and only on x86-64 and AArch64. See Calling conventions for the rules and the register table.

Enums

AttributeDescriptionApplies to
@openThe enum may hold any value of its underlying type: no checked as, no nichePlain enums

A plain enum is closed by default; see Closed and open enums. @open on anything else is an error.

Conversions

AttributeDescriptionApplies to
@implicitLets a conversion operator apply without asfn op as in a type's body

See Implicit op as for the rules.

Other

AttributeDescriptionApplies to
@core::where_handlerCustom handler for where-clause failures. Not implemented yetFunctions

See Where Clauses for the where handler system.

Unknown and misplaced attributes

An attribute is never accepted and ignored. An attribute name the compiler does not know is an error, unknown attribute '@name', with a fix-it that removes it and a suggestion when the name is close to a built-in one (@pakced: did you mean @packed?). A built-in attribute written where it does not apply is an error that says where it does ('@packed' applies only to a class, struct or union), also with a fix-it that removes it. A user-defined attribute is rejected with SC116E for now: attribute macros parse, but they are not expanded yet.


The std::AST API

Attribute definitions interact with the AST through the std::AST module. This module provides types representing each kind of AST node (FunctionDecl, ClassDecl, StructDecl, Block, VariableDecl, etc.) and methods for inspecting and modifying them.

Important

The std::AST API is under development. The full set of node types, their fields, and available methods will be documented once the API is finalized. The examples on this page demonstrate the intended usage patterns.

Key operations available on AST nodes:

OperationDescription
node->nameAccess the declaration name
node->bodyAccess the body (for functions, blocks)
node->body.append(stmt)Add a statement to the end
node->body.prepend(stmt)Add a statement to the beginning
node->clone()Deep-copy the node
AST::parse!(code)Parse a code fragment into an AST node
@create AST::T()Create a new AST node of type T

Macros vs Attributes

MacrosAttributes
Operates onRaw tokensAST nodes
Type awarenessNoYes
Expansion timeBefore parsingAfter parsing
Can modify structureToken substitution onlyCan transform the AST
Syntaxname!(args)@name on declarations
Must preserve node typeN/AYes

Use macros for simple substitutions and conditional compilation. Use attributes for structural transformations that need to inspect or modify declarations.

See Macros for the token-level macro system.


Summary

// Define an attribute
import std::AST

macro @timer(node: *AST::FunctionDecl) {
    node->body.prepend(
        AST::parse!(var __start = std::time::now())
    )
    node->body.append(
        AST::parse!(std::io::println(f"elapsed: {std::time::now() - __start}ms"))
    )
}

// Use an attribute
@timer
fn expensive_computation() {
    // ... work ...
}

// Attribute with arguments
macro @version(node: *AST::ClassDecl, ver: string) {
    // add a static VERSION member to the class
}

@version("2.1.0")
class MyLibrary { ... }

// Stacked attributes (inner to outer)
@json_output
@validate_fields
struct ApiResponse {
    var status: i32
    var body: string
}

// Built-in attributes
@packed
@align(16)
struct CacheLine {
    var data: [u8; 64]
}

@likely if hot_path {
    fast_operation()
}

@no_warn also covers warnings the parser reports inside the declaration, such as S055W. Lexer and preprocessor warnings, such as S025W, are not covered.

See also