Kairo Language Reference

The complete Kairo language reference, assembled into one page. Use the Language/ section for each topic seprated.

Source: https://www.kairolang.org/docs/ · Generated: 2026-06-05

Contents

• Primitives Built-in data types in Kairo integers, floats, booleans, characters, strings, pointers, collections, and their semantics.
• Variables & Bindings Variable declarations, constants, static, type inference, shadowing, destructuring, const semantics, and scope rules in Kairo.
• Operators Arithmetic, comparison, logical, bitwise, assignment, range, null-safe access, operator overloading, and precedence rules in Kairo.
• Control Flow Conditionals, match, loops, labeled breaks, try/catch/finally, panic, assert, jumps, compile-time branching, and branch hints in Kairo.
• Functions Function declarations, parameters, return types, overloading, modifiers, generics, variadic functions, and calling conventions in Kairo.
• Closures Anonymous functions, capture modes, lambda syntax, and how closures interact with AMT in Kairo.
• Classes Class declarations, constructors, destructors, lifecycle categories, inheritance, virtual dispatch, abstract classes, generics, visibility, memory layout, and out-of-line definitions in Kairo.
• Structures Struct declarations, aggregate initialization, field visibility, generics, extends, layout control, and how structs differ from classes in Kairo.
• Enums Enum declarations, discriminants, underlying types, ADT variants with payloads, generics, extends, and enum semantics in Kairo.
• Unions Untagged union declarations, memory overlay semantics, trivial-type restriction, generics, and layout rules in Kairo.
• Interfaces Interface declarations, structural conformance, generic interfaces, interface inheritance, operator and constructor requirements, and zero-cost contract semantics in Kairo.
• Type System Type aliases, type inference, implicit conversions, subtyping, TypeInfo, typeof, nullable nesting, void and never types, function types, and type identity in Kairo.
• Casting Explicit type conversions with as, numeric truncation, pointer casts, downcasting, nullable collapsing, user-defined conversions, and cast safety rules in Kairo.
• Requires Clauses Compile-time constraints on functions, types, and interfaces in Kairo.
• Where Clauses Where clauses attach runtime-conditional constraints to declarations. They are evaluated at runtime, and can be used for dispatching on values or types.
• Pointers & Raw Pointers Safe pointers, unsafe raw pointers, null semantics, pointer arithmetic, smart pointer promotion, void pointers, double pointers, and pointer safety rules in Kairo.
• Ownership Transfer semantics, pointer aliasing, closure captures, and destruction order in Kairo’s ownership model.
• AMT Automatic Memory Tracking full-program lifetime analysis, smart pointer promotion, allocator integration, and compile-time safety guarantees in Kairo.
• Unsafe Unsafe blocks, unsafe pointers, unsafe function overloads, AMT suspension, forget, and the safety boundary model in Kairo.
• Panic The panic specifier, Panickable return type, try/catch exhaustiveness, panic propagation, error types, and zero-cost codegen in Kairo.
• Compile-Time Eval Eval variables, eval functions, eval if, eval for, compile-time evaluation rules, restrictions, and interaction with generics in Kairo.
• Modules Module system, imports, file-to-module mapping, directories as libraries, namespaces, visibility, module extending, and C++ header imports in Kairo.
• Extends Extend blocks for adding methods, operators, static functions, and interface conformance to structs, enums, and classes in Kairo.
• Attributes AST-level code transformations, attribute definitions, arguments, expansion order, overloading, built-in attributes, and the std::AST API in Kairo.
• Macros Token-level macros, macro definitions, built-in macros, variadic helpers, source location, diagnostics, code generation, and macro hygiene in Kairo.
• Concurrency Async/await, spawn, yield, coroutines, atomic types, thread-local storage, and synchronization primitives in Kairo.
• C & C++ Interoperability Native bidirectional interop between Kairo and C/C++ FFI declarations, the kcc driver, inline C++, pointer safety, templates, exceptions, and ABI details.

Primitives

_{https://www.kairolang.org/docs/language/primitives/}

Primitives

Kairo’s primitive types are built into the language and available without imports. They map directly to hardware-supported representations where possible, falling back to software emulation for extended-width types.

Integers

All integer types have a fixed, guaranteed size. The default integer type is i32 if a literal doesn’t fit in i32, the compiler promotes it to the smallest signed type that can hold the value, up to i512.

Integer literals default to signed. Use a type suffix to specify:

var a = 42          // i32 (default)
var b = 42u8        // u8
var c = 42i64       // i64
var d = 1_000_000   // i32 underscores are ignored, use freely as separators
var e = 0xFF        // i32 hexadecimal
var f = 0b1010_0011 // i32 binary
var g = 0o77        // i32 octal

Overflow behavior

Unsigned integer overflow wraps around (modular arithmetic). Signed integer overflow behavior depends on the build mode:

• Debug: crashes with a diagnostic.
• Release: wraps around silently.

This matches Rust’s overflow model and catches bugs during development without paying for checks in production.

Extended-width integers (u128-u512, i128-i512)

If the target hardware supports wide registers (e.g., AVX-512), these types map directly to hardware. Otherwise, the compiler stores them as structs of smaller integers and emits SIMD-accelerated arithmetic when available, falling back to scalar multi-word operations.

Extended-width integers are always stack-allocated they are value types, not heap-allocated objects.

Floating-Point

All floating-point types follow the IEEE 754 standard. The default float type is f64 if a literal doesn’t fit in f64, the compiler promotes to the smallest float type that can hold the value, up to f512.

var x = 3.14        // f64 (default)
var y = 3.14f32     // f32
var z = 1.0e-10     // f64 scientific notation

Overflow produces inf, underflow produces 0.0. Operations that produce NaN (e.g., 0.0 / 0.0, sqrt(-1.0)) propagate NaN per IEEE 754 no crash, no trap. Check for NaN explicitly with std::is_nan() when needed.

Implicit Conversions

Integer and float types can be implicitly widened i32 to i64, f32 to f64 but narrowing conversions require an explicit cast. See Casting for details.

var a: i32 = 42
var b: i64 = a      // ok: implicit widening

var c: i64 = 1000
var d: i8 = c        // compile error: narrowing requires explicit cast
var e: i8 = c as i8  // ok: explicit, may truncate

Bool

var flag = true
var other = false

bool is 1 byte in memory (not 1 bit) for addressability. Only true and false are valid values no implicit conversion from integers.

Char

A char holds a single decoded Unicode codepoint. It is always 4 bytes regardless of which codepoint it represents.

var letter = 'A'
var emoji = '😶‍🌫'
var cjk = '漢'

Byte

byte is semantically identical to u8 in size and representation but restricted to bitwise operations and comparisons no arithmetic. It represents raw data where the value is not meant to be interpreted as a number.

var b: byte = 0xFF
var mask: byte = 0x0F
var result = b & mask   // ok: bitwise AND
// var bad = b + mask   // compile error: arithmetic not allowed on byte

Strings

Strings are UTF-8 encoded byte sequences. The string type uses small string optimization (SSO) strings up to 23 bytes are stored inline without a heap allocation. Longer strings are heap-allocated.

var greeting = "Hello, Kairo! 📣"   // 18 UTF-8 bytes fits in SSO
var name = "Dhruvan"                 // 7 bytes SSO

Because UTF-8 is a variable-width encoding, indexing by codepoint (s[i]) is O(1) amortized (since it looks up the nearest codepoint boundary and decodes from there), while indexing by byte (s.bytes[i]) is O(1) always, but returns raw bytes, not characters.

var s = "Hello 📣"
s.bytes[0]    // byte: 0x48 ('H') O(1)
s[6]          // char: '📣' codepoint indexing, O(1) **amortized**

for ch in s {
    // ch is char decoded codepoint, yielded sequentially
}

Void

void indicates the absence of a value. It can be used as a function return type and as the target of an unsafe pointer (unsafe *void), but it cannot be used as a type parameter or variable type.

fn log(msg: string) -> void {
    // ...
}

var opaque: unsafe *void = get_handle()  // raw, untyped pointer

Pointers

*T is a thin pointer (8 bytes). It is non-null by construction and supports pointer arithmetic when the compiler can track its provenance via AMT. See Pointers for full details.

unsafe *T is a raw C-style pointer with no compiler tracking. It can be null, and dereferencing a null

unsafe *T is undefined behavior. Use unsafe *T for C/C++ interop, custom allocators, and other low-level scenarios. See Pointers and Unsafe for full details.

var x = 42
var p: *i32 = &x                // safe pointer to x
var q: unsafe *i32 = unsafe &x  // raw pointer, no tracking

Collections

Collections are built-in generic types with literal syntax. All are heap-allocated except fixed-size arrays.

Vectors [T]

A growable, owning, contiguous array. Layout: ptr + len + cap (24 bytes).

var nums: [i32] = [1, 2, 3]
nums.push(4)
nums[0]    // 1 bounds-checked

When borrowed as const [T], a vector acts as a non-owning view with cap set to zero no growth permitted, no deallocation on drop. See Ownership for borrowing semantics.

Arrays [T; N]

A fixed-size array allocated inline (stack or struct). N must be a compile-time constant.

var rgb: [u8; 3] = [255, 128, 0]
// rgb.push(42)  // compile error: fixed size

Maps {K: V}

A hash map from keys of type K to values of type V.

var ages: {string: i32} = {"Alice": 30, "Bob": 25}
ages["Charlie"] = 35

Sets {T}

A hash set of unique elements.

var primes: {i32} = {2, 3, 5, 7, 11}

Tuples (T1, T2, ...)

A fixed-size, heterogeneous, ordered group of values. Stored contiguously with padding for alignment.

var point: (f64, f64) = (1.0, 2.0)
var record: (i32, string, bool) = (42, "Answer", true)

Function Pointers fn (T1, T2, ...) -> R

A pointer to a function with the given signature. Platform-dependent size.

fn add(a: i32, b: i32) -> i32 { return a + b }
var operator: fn (i32, i32) -> i32 = add
op(3, 4)  // 7

Platform-Dependent Sizes

usize and isize match the target platform’s pointer width:

Summary

// Integers
var a = 42              // i32
var b = 42u8            // u8
var c = 0xFF            // i32 (hex)
var d = 0b1010          // i32 (binary)
var e = 1_000_000       // i32 (underscores as separators)

// Floats
var f = 3.14            // f64
var g = 3.14f32         // f32

// Bool, char, string
var h = true            // bool
var i = '📣'            // char (4 bytes, Unicode scalar)
var j = "Hello, Kairo!" // string (UTF-8, SSO up to 23 bytes)

// Byte
var k: byte = 0xFF      // raw byte, no arithmetic

// Pointers
var x = 42
var p = &x              // *i32
var q: unsafe *i32 = unsafe &x

// Collections
var nums: [i32] = [1, 2, 3]                           // vector
var rgb: [u8; 3] = [255, 128, 0]                      // array
var ages: {string: i32} = {"Alice": 30, "Bob": 25}    // map
var primes: {i32} = {2, 3, 5, 7}                      // set
var point: (f64, f64) = (1.0, 2.0)                    // tuple

// Function pointer
fn add(a: i32, b: i32) -> i32 { return a + b }
var operator: fn (i32, i32) -> i32 = add

Variables & Bindings

_{https://www.kairolang.org/docs/language/variables/}

Variables & Bindings

Variables in Kairo are mutable by default. const bindings at local scope require an initializer, but class-level const members can be left uninitialized at declaration and assigned exactly once in the constructor body. See Classes for details.

var x = 42
var y: string = "Hello, World!"

Multi-variable declarations on a single line are not supported. Each binding gets its own statement.

Naming Conventions

Kairo recommends the following conventions. They are not enforced as hard errors, but the compiler emits readability warnings when they are not followed.

Type Inference

The compiler infers the type from the initializer when no annotation is provided. Explicit annotations are optional but can be used to force a specific type.

var a = 42          // inferred as i32
var b = 3.14        // inferred as f64
var c: u8 = 42      // explicitly u8
var d = "hello"     // inferred as string

See Primitives for default type rules integer literals default to i32, float literals default to f64.

Declaration Shorthands

When the type is fully determined by the initializer, the * or unsafe * qualifier can be placed on the variable name instead of writing out the full type annotation:

var *ptr = std::create<i32>(10)
// equivalent to: var ptr: *i32 = std::create<i32>(10)

var unsafe *raw = unsafe std::alloc<i32>(sizeof i32 * 1)
// equivalent to: var raw: unsafe *i32 = unsafe std::alloc<i32>(sizeof i32 * 1)

The nullable shorthand ? works the same way:

var name? = get_name()
// equivalent to: var name: string? = get_name()

These are purely syntactic sugar the compiler infers the full type from the right-hand side. The long form is always valid and preferred when clarity matters.

Default Initialization

All types with a default constructor are zero-initialized when declared without an initializer. Integers default to 0, booleans to false, strings to "", collections to empty.

var a: i32        // 0
var b: string     // ""
var c: bool       // false
var d: [i32]      // []

If a type has its default constructor explicitly deleted, declaring a variable without an initializer produces a compiler warning for uninitialized state.

class Token {
    fn Token() = delete
}

var t: Token   // warning: t is uninitialized (suppress with @no_warn(UNINIT))

Constants

Immutable bindings use const. A const variable cannot be reassigned after initialization.

const x = 42
const name: string = "Kairo"
// x = 100  // compile error: x is const

Unlike var, a const binding without an initializer is a hard compile error constants must always be explicitly initialized.

const x: i32       // compile error: const requires an initializer

Compile-Time Constants (eval)

For values that must be resolved at compile time, use eval. This is equivalent to C++‘s consteval the expression must be evaluable at compile time, and a compile error is raised if it cannot be.

eval PI = 3.14159
eval MAX_SIZE = 1024 * 1024

eval bindings are implicitly const. See Eval for full details on compile-time evaluation, including eval functions and restrictions.

Static Variables

static declares a binding with static storage duration it lives for the entire program. Unlike var, static requires an explicit type annotation.

static counter: i32 = 0

static can be combined with const for immutable static data. See Modules for static at module scope.

Shadowing

Constants can shadow previous bindings of the same name. Each const declaration creates a new binding the previous one becomes inaccessible.

const raw = "42"
const raw = std::parse<i32>(raw)   // shadows string with i32 valid
const raw = raw * 2                // shadows again valid

Mutable variables cannot shadow. Redeclaring a var with the same name in the same scope is a compile error.

var x = 42
var x = 100   // compile error: var cannot shadow

Destructuring

Tuples and structs can be destructured into individual bindings. Use parentheses for tuples and curly braces for structs.

Tuples

var point = (10, 20, 30)
var (x, y, z) = point
// x = 10, y = 20, z = 30

Structs

struct Color {
    var r: u8
    var g: u8
    var b: u8
}

var color = Color { r: 255, g: 128, b: 0 }
var {r, g, b} = color
// r = 255, g = 128, b = 0

Destructured names must match the field names in the struct definition. The binding order follows the definition order.

Discards

Use _ to ignore values you don’t need. _ is not a variable it cannot be referenced after destructuring.

var (x, _, z) = (1, 2, 3)     // discard the second element
var {r, _, _} = color         // keep only r

for _ in 0..10 {
    // loop body doesn't need the index
}

The compiler will error if you attempt to use _ as a value.

Nullable Types

T? is sugar for Nullable<T> a compiler-intrinsic tagged union that holds either a value of type T or null. It applies to any type, not just pointers.

var name: string? = get_name()   // may be null
var count: i32? = null           // explicitly null

Shorthand declaration

The ? suffix on the variable name infers the nullable type from the initializer:

var name? = get_name()           // inferred as string?
// var x? = null                 // compile error: no underlying type to infer

Null checking

The ? suffix on a variable name in a condition checks for non-null:

var result? = find_user("alice")

if result? {
    // result is non-null here
    std::println(result.name)
}

Accessing members on an unchecked nullable is a compile error:

var user? = find_user("alice")
user.name   // compile error: user has not been null-checked

Safe access (?.)

The ?. operator calls a method or accesses a member only if the value is non-null. If null, it default-constructs the type and calls the method on that instead:

var config? = load_config()
config?.timeout   // if null, uses Config().timeout

If the type is not trivially default-constructible (deleted default constructor, contains atomic types), ?. is a compile error.

Null coalescing (??)

?? provides a fallback value when the left side is null. Both sides must be the same underlying type:

var value = get_f32() ?? 0.212   // value is f32, not f32?
var name = get_name() ?? "anonymous"

Force unwrap

unwrap!() extracts the value or panics if null:

var x = unwrap!(maybe_value)   // panics if null

unwrap!() desugars to a null check followed by a panic on the null path. The caller must be inside a try block or in a function with the panic specifier. See Panic for the panic model.

const interaction

const on a nullable binding works the same as on any other type the binding cannot be reassigned after initialization:

const x: i32? = 42
x = null   // compile error: x is const
x = 100    // compile error: x is const

var y: i32? = null
y = 42     // ok: var is mutable
y = null   // ok: can go back to null

Pointers and nullability

*T is non-null by construction, it cannot hold &null. No null checks are needed on dereference because the pointer is always valid:

var x = 42
var ptr: *i32 = &x
*ptr = 10              // guaranteed valid, no check

var bad: *i32 = &null  // compile error: *T is non-null

To represent a pointer that might not exist, use *T?. This wraps the pointer in the standard Nullable<T> system with full support for ?, ?., ??, and unwrap!():

var ptr: *i32? = find_pointer()

if ptr? {
    std::println(*ptr)          // compiler knows ptr is non-null here
}

var val = ptr ?? &fallback      // use fallback if null
var forced = unwrap!(ptr)       // panics if null

For raw nullable pointers with no compiler tracking, use unsafe *T with manual null comparison:

var raw: unsafe *i32 = &null
if raw != &null {
    std::println(*raw)
}

See Pointers for the full pointer model and how AMT tracks pointer provenance.

The const Binding Rule

const in Kairo follows a strict left-to-right binding rule: one const applies to the thing immediately to its right. This eliminates the ambiguity that plagues C/C++ const placement.

On simple variables

const x: i32 = 42
//    ^ x cannot be reassigned
//       ^^^ i32 is the type immediately right of const the value is immutable

On pointers

const on the binding and const on the pointed-to type are independent axes:

var ptr: *i32 = &x
// ptr is mutable, *ptr is mutable can reassign ptr and modify the target

const ptr: *i32 = &x
// ptr is const cannot reassign ptr to point elsewhere
// *ptr is mutable can still modify the target value
*ptr = 10    // ok: allowed
ptr = &y     // compile error:

const ptr: *const i32 = &x
// ptr is const cannot reassign
// *ptr is const cannot modify the target
*ptr = 10    // compile error:
ptr = &y     // compile error:

The rule scales to any depth:

const ptr: *const *i32 = &ptr2
ptr = &ptr3    // ptr is: const
*ptr = &x      // *ptr is: const
**ptr = 10     // ok: the i32 at the end is not const

A practical example

Consider a configuration object that should be readable through a pointer but never modified:

class Config {
    pub var host: string
    pub var port: i32

    fn Config(self, host: string, port: i32) {
        self.host = host
        self.port = port
    }

    fn address(const self) -> string {
        return f"{self.host}:{self.port}"
    }

    fn set_port(self, port: i32) {
        self.port = port
    }
}

var config = Config("localhost", 8080)

const ptr: *const Config = &config
ptr->address()       // ok: address() is a const method
ptr->set_port(9090)  // compile error: set_port() mutates, ptr points to const Config

// in most cases tho you would only want this:
var ptr: *const Config = &config
// cause you would have a const type but still be able to reassign the pointer if needed.

On types

const applied to a type restricts the instance to const methods only methods not marked const cannot be called.

const server = Config("localhost", 8080)
server.address()       // ok: const method
server.set_port(9090)  // compile error: set_port() is not const

Scope and Lifetime

Variables are block-scoped and destroyed at the end of their enclosing block.

{
    var x = 42
    // x is live here
}
// x is no longer accessible

AMT performs full-program analysis to track lifetimes automatically no lifetime annotations are required. If AMT determines that a pointer outlives its referent and cannot automatically promote the pointer (to a shared, weak, or unique smart pointer), it emits a compile error.

var x = 10
var y = &x
{
    *y = 15    // ok: x is still alive, y is valid
}
std::println(*y)      // AMT error: y's safety cannot be guaranteed at this point

See AMT and Ownership for the full lifetime and borrowing model.

All four declaration keywords var, const, static, eval work in both local and class/struct scope.

Operators

_{https://www.kairolang.org/docs/language/operators/}

Operators

Kairo’s operators follow C-style precedence and semantics with a few additions: exponentiation (^^), deep equality (===), null-safe access (?., ?->), and ranges (.., ..=). All operators can be overloaded for user-defined types.

Arithmetic

Integer division truncates toward zero, matching C++.

^^ works on any integer combination (i32 ^^ i32, u64 ^^ u8, etc.) and on float bases with integer exponents (f64 ^^ i32). Overflow follows the same rules as other arithmetic see below.

Integer overflow

Unsigned overflow wraps around (modular arithmetic). Signed overflow depends on the build mode:

• Debug: crashes with a diagnostic.
• Release: wraps around silently.

See Primitives for full details on numeric type behavior.

Floating-point overflow

Overflow produces inf, underflow produces 0.0. Operations that produce NaN (e.g., 0.0 / 0.0, sqrt(-1.0)) propagate NaN per IEEE 754 no crash, no trap. Check explicitly with std::is_nan().

Comparison

<=> returns an ordering value, matching C++20 spaceship operator semantics.

== vs ===

On pointers, == compares addresses whether two pointers point to the same memory location. === dereferences both pointers and compares the values they point to. === is defined only on *T, which is non-null by construction, so no null check is needed. For a pointer that might be null, use *T? and the nullable operators (?, ??) before comparing.

var z = 42
var x = &z
var y = &z

x == y    // true same address
x === y   // true dereferenced values are equal

var a = 42
var b = 42
var p = &a
var q = &b

p == q    // false different addresses
p === q   // true both point to 42

For user-defined types, === can be overloaded to implement deep equality. By default it is only defined for pointer types.

Logical

Short-circuit evaluation applies: && does not evaluate the right operand if the left is false, and || does not evaluate the right operand if the left is true. This is identical to C++.

Bitwise

Right shift is arithmetic (sign-extending) for signed types and logical (zero-filling) for unsigned types.

Assignment

All compound assignment operators desugar to x = x op y.

Increment and Decrement

Ranges

Range operators produce a Range object that implements iteration. Any type that satisfies the Steppable interface can be used with range operators:

interface <T> Steppable {
    fn op l++ (self) -> Steppable   // step forward (prefix increment)
    fn op == (self, other: T) -> bool
}

Ranges also work with slicing on strings and collections:

"hello"[1..4]         // "ell"
[1, 2, 3, 4][0..2]   // [1, 2]

Null-Safe Access

Kairo provides null-safe operators for working with nullable types (T?).

If the left-hand side is null, the entire expression evaluates to null instead of crashing.

var user: User? = find_user("alice")
var name = user?.get_name()   // string? null if user is null

The non-null equivalents follow the same pattern without the safety check:

Type Inspection

typeof has dual behavior depending on context:

var x = 42
var y: typeof x = 100     // type position compiler substitutes i32

var info = typeof x        // expression position returns a TypeInfo struct
info.get_pretty_name()     // "i32"
info.get_size()            // 4

See Type System for full TypeInfo details.

Type Casting as

as performs explicit type conversion. No implicit narrowing conversions exist in Kairo all narrowing casts must use as. Implicit widening (e.g., i32 to i64) is permitted without as.

var x: i64 = 1000
var y: i8 = x as i8     // explicit narrowing may truncate

var f: f64 = 3.14
var i: i32 = f as i32   // 3 truncates toward zero

as is overloadable for user-defined types:

class Vector2D {
    var x: f32
    var y: f32

    fn op as (self) -> string {
        return f"Vector2D({self.x}, {self.y})"
    }
}

var v = Vector2D { x: 1.0, y: 2.0 }
var s = v as string   // "Vector2D(1.0, 2.0)"

See Casting for the full conversion rules.

Operator Overloading

Operators are overloaded by defining fn op methods on a class, struct OR (via extends). The syntax mirrors the operator being defined.

Standard binary and unary operators

class Vec3 {
    var x: f32
    var y: f32
    var z: f32

    fn op + (self, other: Vec3) -> Vec3 {
        return Vec3 { x: self.x + other.x, y: self.y + other.y, z: self.z + other.z }
    }

    fn op - (self) -> Vec3 {   // unary negation
        return Vec3 { x: -self.x, y: -self.y, z: -self.z }
    }

    fn op == (self, other: Vec3) -> bool {
        return self.x == other.x && self.y == other.y && self.z == other.z
    }
}

Increment and decrement

Use the l (left/prefix) or r (right/postfix) modifier to specify which variant you are overloading. The compiler warns if the modifier is omitted.

fn op r-- (self) -> T    // postfix: x--
fn op l-- (self) -> T    // prefix:  --x
fn op l++ (self) -> T    // prefix:  ++x the ++ is on the left of the operand
fn op r++ (self) -> T    // postfix: x++ the ++ is on the right of the operand

Special operators

The two in signatures are distinguished by context: the compiler uses the -> bool variant in if expressions and the -> yield T variant in for loops.

class IntSet {
    priv var data: [i32]

    fn op in (self, value: i32) -> bool {
        // containment check: "if 5 in my_set"
        for item in self.data {
            if item == value { return true }
        }
        return false
    }

    fn op in (self) -> yield i32 {
        // iteration: "for x in my_set"
        for item in self.data {
            yield item
        }
    }
}

var s = IntSet { data: [1, 2, 3] }

if 2 in s { /* ... */ }      // calls the bool variant

for x in s {                 // calls the yield variant
    std::println(f"{x}")
}

op delete

op delete defines custom destruction logic. If not defined, the compiler generates a default destructor. If any member has a deleted destructor (fn op delete() = delete), the containing type’s destructor is also deleted and instances must be managed in an unsafe context.

class FileHandle {
    priv var fd: i32

    fn op delete (self) {
        close(self.fd)
    }
}

See AMT for details on destruction order and allocator interaction.

Precedence

Operators are listed from highest precedence (tightest binding) to lowest. Operators on the same row have equal precedence and associate in the direction shown.

When in doubt, use parentheses. The compiler does not warn about precedence ambiguity, but explicit grouping improves readability.

Evaluation Order

Evaluation order of subexpressions is undefined in Kairo. Given f(a(), b()), there is no guarantee that a() executes before b(). This is inherited from C++ semantics.

Operators Not in Kairo

For C++ developers the following C++ operators have no equivalent in Kairo:

Control Flow

_{https://www.kairolang.org/docs/language/control-flow/}

Control Flow

Kairo’s control flow is block-scoped and brace-delimited. Every branch, loop, and error-handling construct uses { ... } there are no single-statement bodies. Conditions are bare expressions (no parentheses required, though permitted for clarity).

Conditionals

if / else if / else

if x > 0 {
    std::println("positive")
} else if x == 0 {
    std::println("zero")
} else {
    std::println("negative")
}

Braces are mandatory on all branches. The condition must evaluate to bool no implicit conversion from integers or pointers.

if as an expression (ternary equivalent)

Kairo has no ternary ? : operator. Use if/else as an expression instead, the expression in each branch is the result:

var x = if condition { 10 } else { 20 }

var y = if a > b { a } else if a == b { 0 } else { b }

When used as an expression, the else branch is required and all branches must produce the same type. Empty branches are not permitted in expression form.

Empty branches

Empty branches are legal in statement form. The compiler will not warn this is intentional for cases where only one side of a conditional has work to do:

if condition {
    // intentionally empty
} else {
    handle_false_case()
}

match

match is Kairo’s multi-way dispatch construct. It handles value matching, enum variant dispatch, ADT destructuring, struct field extraction, and range checks all with compiler-enforced exhaustiveness.

match status_code {
    case 200 { std::println("OK") }
    case 404 { std::println("Not Found") }
    case 500 { std::println("Internal Server Error") }
    default  { std::println(f"Unknown: {status_code}") }
}

Value matching

match operates on integers, strings, and booleans by comparing against literal values:

match command {
    case "start" { engine.start() }
    case "stop"  { engine.stop() }
    case "reset" { engine.reset() }
    default      { log_unknown(command) }
}

match is_valid {
    case true  { proceed() }
    case false { abort() }
}

Enum variant matching

For plain enums, use the .Variant shorthand when the type is inferred from the match operand:

match dir {
    case .North { go_up() }
    case .South { go_down() }
    case .East  { go_right() }
    case .West  { go_left() }
}

The fully qualified form Direction::North also works. The compiler verifies all variants are covered.

ADT destructuring

ADT enum variants carry payloads. Destructure them in match with var or const bindings inside parentheses. Field names must match the variant declaration:

enum <K, V> LookupResult {
    Found    { key: K, value: V },
    NotFound { key: K },
    Error    { message: string },
}

match result {
    case .Found(var key, var value) {
        std::println(f"{key} = {value}")
    }
    case .NotFound(var key) {
        std::println(f"{key} not found")
    }
    case .Error(const message) {
        // message cannot be reassigned bound as const
        log_error(message)
    }
}

You can omit fields you do not need exhaustive field extraction is not required:

match result {
    case .Found(var value) {
        // only value is bound, key is ignored
        process(value)
    }
    default { }
}

See Enums for ADT enum declarations and construction.

where guards

Append where followed by a boolean expression to add a condition to a case. The branch only matches if both the pattern and the guard are satisfied:

match result {
    case .Found(var key, var value) where value > 0 {
        std::println(f"{key} has positive value")
    }
    case .Found(var key, var value) {
        std::println(f"{key} has non-positive value")
    }
    default { }
}

Guards are evaluated after the pattern matches. A case with a guard that fails falls through to the next case this is the only situation where control moves between cases.

Struct matching

Structs have a single shape (no variants), so match on a struct is destructuring combined with guards. A struct case without a where guard always matches and is a compile error unless it is the only case or the last case (acting as a catch-all):

struct Response {
    var status: i32
    var body: string
}

match response {
    case Response(var status, var body) where status == 200 {
        process(body)
    }
    case Response(var status) where status >= 400 {
        log_error(f"HTTP {status}")
    }
    default {
        // catch-all
    }
}

Range matching

Integer cases can match a range using .. (exclusive end) or ..= (inclusive end):

match http_status {
    case 200..=299 { std::println("success") }
    case 300..=399 { std::println("redirect") }
    case 400..=499 { std::println("client error") }
    case 500..=599 { std::println("server error") }
    default        { std::println("unknown") }
}

match as an expression

Like if, match can be used as an expression. The last expression in each branch is the result value. All branches must produce the same type:

var label = match level {
    case .Debug   { "debug" }
    case .Info    { "info" }
    case .Warning { "warning" }
    case .Error   { "error" }
    case .Fatal   { "fatal" }
}

var priority = match code {
    case 200..=299 { 0 }
    case 400..=499 { 1 }
    case 500..=599 { 2 }
    default        { -1 }
}

var message = match result {
    case .Found(var key, var value) { f"{key}: {value}" }
    case .NotFound(var key)        { f"{key} not found" }
    case .Error(var message)       { message }
}

In expression form, exhaustiveness is required every possible value must be covered. For integers and strings, this means default is mandatory.

Exhaustiveness

The compiler verifies that all possible values are covered:

A default case matches any value not covered by preceding cases. It must be the last case.

No fall-through

Each case is an isolated block. There is no fall-through between cases and no @fallthrough attribute. If you need multiple values to execute the same code, list them in a single case separated by commas:

match priority {
    case 1, 2, 3 { handle_high() }
    case 4, 5    { handle_medium() }
    default      { handle_low() }
}

break in match inside a loop

Inside a match nested within a loop, break exits the loop, not the match. Match cases are already isolated blocks with no fall-through, so there is nothing to “break” out of within the match itself.

for item in items {
    match item.kind {
        case .Sentinel {
            break   // exits the for loop
        }
        case .Data(var payload) {
            process(payload)
        }
        default { }
    }
}

Loops

for range and iterator

Range-based and iterator-based for loops use the in keyword:

for i in 0..10 {
    // i = 0, 1, 2, ..., 9
}

for i in 0..=10 {
    // i = 0, 1, 2, ..., 10
}

for item in collection {
    // iterates using the collection's fn op in (self) -> yield T
}

The range operators .. and ..= produce a Range object that implements the iterator protocol. Any type that defines fn op in (self) -> yield T is iterable. See Operators for the Steppable interface and Operators for the op in overload.

Multi-variable iteration

If the collection yields tuples, destructure directly in the loop header:

for (key, value) in some_map {
    std::println(f"{key} = {value}")
}

for (a, b) in pairs {
    // a and b are the first and second elements of each yielded tuple
}

The tuple arity in the loop header must match the arity yielded by the collection.

for C-style

Traditional three-part for loops are also supported:

for var i = 0; i < 10; i++ {
    // classic index loop
}

The init clause declares a new variable scoped to the loop body. The condition and step are bare expressions.

while

while condition {
    // loop body
}

The condition is evaluated before each iteration. No implicit conversion from integers must be bool.

loop

loop is an unconditional infinite loop. It runs until an explicit break or return:

loop {
    var input = read_line()
    if input == "quit" {
        break
    }
    process(input)
}

Labeled loops

Labels allow break and continue to target a specific enclosing loop. The syntax is label: for/while/loop:

outer: for i in 0..10 {
    inner: for j in 0..10 {
        if some_condition {
            break outer    // exits the outer loop entirely
        }
        if other_condition {
            continue inner // skips to next iteration of the inner loop
        }
    }
}

Labels follow the same naming conventions as variables (snake_case). break and continue without a label target the innermost enclosing loop.

break and continue

break and continue are statements, not expressions they do not produce values. Inside a match nested within a loop, break exits the loop, not the match (match cases are already isolated blocks with no fall-through by default).

Error Handling

try / catch

try/catch handles panics from functions annotated with the panic specifier. The compiler statically verifies that catch blocks cover all panic types that can propagate from the try body uncovered types are a compile error. See Panic for the full panic model.

try {
    risky_operation()
} catch {
    // catch-all any panic type
    std::println("something went wrong")
}

Catch blocks can filter by specific error types. The compiler checks exhaustiveness against the set of panic types declared by the called functions:

try {
    read_file("data.txt")
} catch e: std::Error::IO {
    std::println(f"IO error: {e}")
} catch e: std::Error::Runtime {
    std::println(f"Runtime error: {e}")
}

A bare catch (no type) acts as a catch-all and satisfies exhaustiveness for any remaining types.

try/catch as an expression

Like if, try/catch can be used as an expression. The last expression in each block is the result value:

var result = try {
    parse_int("42")
} catch e: std::Error::Runtime {
    -1   // fallback value
} catch {
    0    // default for any other error
}

All branches must produce the same type. finally is not permitted in expression form.

finally

finally defines cleanup code that always runs whether the try body completes normally, panics, or returns early.

try {
    acquire_resource()
    do_work()
} catch e: std::Error::Runtime {
    handle_error(e)
} finally {
    release_resource()   // always executes
}

Standalone finally (scope exit)

finally can also appear inside any function body without a preceding try. In this form, it acts as a scope exit block the body executes when the enclosing function returns, regardless of how it exits:

fn process_file(path: string) panic -> void {
    var fd = open(path)
    finally {
        close(fd)   // runs on normal return, panic, or early return
    }

    // ... work with fd ...
    if bad_data {
        return   // finally still runs
    }
    // ... more work ...
}

This is equivalent to Go’s defer the body executes when the enclosing function exits, regardless of how it exits (normal return, panic, or early return). Multiple finally blocks in the same function execute in reverse declaration order (LIFO), matching destructor semantics.

assert

assert evaluates a condition and panics if it is false. It takes an expression and an optional diagnostic message:

assert index < len, "index out of bounds"
assert ptr != null

Assert behavior is globally configurable via the -fassert-mode compiler flag:

Asserts cannot appear at file scope they are only valid inside function bodies.

panic

panic is a statement that triggers an unrecoverable error in the current function. Functions that can panic must be annotated with the panic specifier in their signature, and the compiler enforces that callers handle the panic via try/catch.

fn divide(a: i32, b: i32) panic -> i32 {
    if b == 0 {
        panic std::Error::Runtime("division by zero")
    }
    return a / b
}

See Panic for the full panic model, including Panickable<T>, desugaring semantics, and the zero-cost codegen strategy.

return

return exits the current function with a value. If the function returns void, return takes no operand.

fn max(a: i32, b: i32) -> i32 {
    return if a > b { a } else { b }
}

Blocks and Scope

A block is a brace-delimited sequence of statements. Every block introduces a new lexical scope variables declared inside are not visible outside, and destructors run at the closing brace in reverse declaration order.

{
    var x = 42
    var y = compute(x)
    // x and y are live here
}
// x and y are destroyed and no longer accessible

Blocks are expressions when used as the right-hand side of a binding. The last expression in the block is the result value:

var result = {
    var tmp = expensive_computation()
    tmp * 2   // result = tmp * 2
}

Anonymous blocks are useful for limiting the lifetime of temporary resources without introducing a function:

fn process() {
    var config = load_config()

    {
        var lock = acquire_mutex()
        // critical section
        write_shared_state(config)
    }
    // lock is destroyed here mutex released

    do_unrelated_work()
}

All control flow constructs (if, match, for, while, loop, try) create implicit blocks their bodies follow the same scoping and destruction rules.

See Variables and AMT for full lifetime semantics.

Jumps

For low-level control flow (state machines, interpreters, hot loops), Kairo provides labeled jumps via compiler intrinsics:

label!(entry)
// ... code ...
jump!(entry)   // unconditional jump to 'entry'

jump! can only target labels within the same function cross-function jumps are a compile error. Labels declared with label! are not the same as loop labels; they are raw branch targets with no structured control flow guarantees.

Kairo does not have a goto keyword. label! and jump! are compiler intrinsics surfaced with macro syntax to make jump usage explicit and greppable in a codebase. They are not user-defined macros see Macros for the macro system.

Compile-Time Branching

eval if selects a branch at compile time. The condition must be a compile-time constant expression if it is not, the compiler emits an error. Only the selected branch is included in the final program; the other branches are discarded entirely (no codegen, no type-checking).

eval if platform == "linux" {
    fn init() { /* linux-specific init */ }
} else if platform == "windows" {
    fn init() { /* windows-specific init */ }
} else {
    fn init() { /* fallback */ }
}

This is equivalent to #if / #elif / #else in C/C++, but operates on Kairo’s compile-time evaluation system rather than a preprocessor. See Eval for details on what qualifies as a compile-time constant.

Branch Hints

Kairo provides attributes to communicate branch likelihood to the compiler’s optimizer. These map directly to LLVM’s branch weight metadata and __builtin_expect semantics in the generated code.

@likely if hot_path {
    fast_operation()
} else {
    slow_fallback()
}

@unlikely if rare_error {
    handle_error()
}

@unreachable is a hard assertion to the optimizer that the marked branch is dead code. If execution reaches an @unreachable branch at runtime, the behavior is undefined the compiler is free to eliminate the branch entirely and may miscompile surrounding code under that assumption.

match direction {
    case .North { /* ... */ }
    case .South { /* ... */ }
    case .East  { /* ... */ }
    case .West  { /* ... */ }
    @unreachable default {
        // optimizer assumes this is dead code
    }
}

Branch hints cannot be applied to eval if branches compile-time branches are resolved before codegen and have no runtime cost to optimize.

The Never Type

Functions that never return they always panic, loop forever, or call a noreturn function use ! as their return type:

fn fatal(msg: string) panic -> ! {
    panic std::Error::Runtime(msg)
}

fn event_loop() -> ! {
    loop {
        process_events()
    }
}

! is the never type. It is a subtype of every type, meaning it can appear anywhere a value is expected. This makes it valid in expression contexts:

var x: i32 = if valid { compute() } else { fatal("invalid state") }
// fatal() returns ! which coerces to i32

See Functions for return type syntax and Type System for how ! interacts with type inference.

return

return exits the current function with a value. See Functions for full details on return types, void returns, and expression-bodied functions.

Short-Circuit Evaluation

&& and || are guaranteed left-to-right with short-circuit evaluation. The right operand is not evaluated if the left operand determines the result:

if ptr != null || *ptr == 42 {
    // safe: *ptr is only evaluated if ptr is non-null
}

This is identical to C/C++ behavior and is guaranteed by the language specification, not an optimizer artifact.

Control Flow Not in Kairo

For C++ developers the following C++ constructs have no equivalent in Kairo:

Functions

_{https://www.kairolang.org/docs/language/functions/}

Functions

Functions in Kairo follow a consistent declaration syntax for both free functions and class methods. The full grammar covers visibility, ABI linkage, generics, modifiers, bounds, and return types all optional except the fn keyword, the name, and the parameter list.

Declaration Syntax

fn name(param1: Type1, param2: Type2) -> ReturnType {
    // body
}

The full grammar:

function_declaration ::= visibility? abi_mod? "fn" generics? identifier
                         "(" parameter_list? ")" function_mods? "->" return_type? bounds? block

visibility   ::= "pub" | "priv" | "prot"
abi_mod      ::= ("ffi" string_literal) | "static" | "virtual" | "override"
generics     ::= "<" generic_param_list ">"
function_mods ::= "const" | "volatile" | "unsafe" | "eval" | "async" | "final" | "panic" | "inline"
bounds       ::= "where" expression
return_type  ::= type | "!"

All parts except fn, the name, and the parenthesized parameter list are optional. When the return type is omitted, it defaults to void.

Parameters

Parameters are declared as name: Type. Each parameter requires an explicit type annotation there is no parameter type inference.

fn greet(name: string, loud: bool) {
    if loud {
        std::println(f"HELLO, {name}!")
    } else {
        std::println(f"Hello, {name}.")
    }
}

Default parameters

Parameters can have default values. When a caller omits a defaulted argument, the default is used:

fn greet(name: string = "world") {
    std::println(f"Hello, {name}!")
}

greet()          // "Hello, world!"
greet("Alice")   // "Hello, Alice!"

Defaults are evaluated at the call site. Parameters with defaults must appear after non-defaulted parameters.

Named arguments

Arguments can be passed by name at the call site. Positional arguments must come before named arguments, matching C++ conventions:

fn create_user(name: string, age: i32 = 18, country: string = "USA") -> User {
    return User { name, age, country }
}

create_user("Alice")                              // age=18, country="USA"
create_user("Bob", 25)                            // country="USA"
create_user(name: "Eve", country: "UK")           // age=18
create_user("Grace", 22)                          // country="USA"
create_user(name: "Frank", age: 30, country: "CA") // all explicit

Return Types

Explicit return

fn add(a: i32, b: i32) -> i32 {
    return a + b
}

Implicit void

When no return type is specified, the function returns void:

fn log(msg: string) {
    std::println(msg)
}

fn log_explicit(msg: string) -> void {   // equivalent
    std::println(msg)
}

No-return !

Functions that never return they always panic, loop forever, or call a no-return function use ! as their return type:

fn fatal(msg: string) -> ! {
    std::println(f"Fatal: {msg}")
    std::crash(1)
}

fn event_loop() -> ! {
    loop {
        process_events()
    }
}

! is the no-return type. It is a subtype of every type, meaning it can appear anywhere a value is expected:

var x: i32 = if valid { compute() } else { fatal("bad state") }
// fatal() returns ! which coerces to i32

Special return types

These return type modifiers interact with Kairo’s concurrency and type system. Each is covered in detail on its respective page:

fn generate_numbers() -> yield i32 {
    for i in 0..10 {
        yield i   // yield, not return function must have a yield return type
    }
}

Expression-Bodied Functions

Single-expression functions can use the = shorthand, omitting braces and return:

fn add(a: i32, b: i32) -> i32 = a + b
fn square(x: f64) -> f64 = x * x
fn greeting(name: string) -> string = f"Hello, {name}!"

The return type annotation is optional for expression-bodied functions it is inferred from the expression when omitted. This is the only form of return type inference in Kairo; block-bodied functions always require an explicit return type (or default to void).

fn add(a: i32, b: i32) = a + b              // inferred as i32
fn greeting(name: string) = f"Hi, {name}!"  // inferred as string

Explicit annotations are still useful when you want to constrain or widen the inferred type:

fn promote(x: i32) -> i64 = x as i64        // would otherwise infer i32

return

return exits the current function with a value. For void functions, return takes no operand.

fn max(a: i32, b: i32) -> i32 {
    if a > b {
        return a
    }
    return b
}

fn log(msg: string) {
    std::println(msg)
    return   // explicit return from void function valid but optional
}

Early returns are permitted anywhere in a function body. The compiler verifies that all code paths return a value of the declared return type.

Function Overloading

Functions can be overloaded by parameter types, matching C++ overload resolution rules:

fn add(a: i32, b: i32) -> i32 = a + b
fn add(a: f64, b: f64) -> f64 = a + b
fn add(a: string, b: string) -> string = a + b

Unsafe overloads

The unsafe modifier creates a separate overload in its own namespace. Safe and unsafe versions of the same function coexist the caller explicitly selects which one to invoke:

fn add(a: i32, b: i32) -> i32 {
    return a + b
}

fn add(a: i32, b: i32) unsafe -> i32 {
    return a << 1 + b << 1   // faster but semantically different
}

var x = add(10, 20)          // calls the safe version
var y = unsafe add(10, 20)   // calls the unsafe overload

const overloading restriction

const and non-const methods with the same name and parameter types cannot coexist. They live in the same scope use distinct names like get() and get_mut() instead:

class Foo {
    fn bar(const self) -> i32 { return 42 }
    fn bar(self) -> i32 { return 24 }               // compile error: cannot overload const
    fn bar(const self, a: i32) -> i32 { return a }  // ok: different parameter list ok
}

Variadic Functions

The ... prefix on a parameter name accepts an arbitrary number of arguments of the same type. The parameter is accessible as a tuple inside the function body:

fn sum(...numbers: i32) -> i32 {
    var total = 0
    for num in numbers {
        total += num
    }
    return total
}

sum(1, 2, 3)        // 6
sum(10, 20, 30, 40) // 100

Generic variadic functions

Combine ... with generic type packs to accept arguments of different types:

fn <...T> print_all(...args: T) {
    for arg in args {
        std::println(arg as string)
    }
}

print_all(42, "hello", true)   // prints each on a new line

The parameter is a tuple of heterogeneous types. Each element in the pack must satisfy the constraints used in the function body in the example above, every T must be convertible to string via as.

Generic Functions

Generic functions declare type parameters in angle brackets before the function name:

fn <T> identity(x: T) -> T {
    return x
}

Constrain type parameters with impl (interface conformance) or derives (class inheritance):

fn <T impl Comparable> max(a: T, b: T) -> T {
    return if a > b { a } else { b }
}

fn <T derives Serializable> serialize(value: T) -> [byte] {
    return value.to_bytes()
}

where clauses

For constraints beyond type parameter bounds, use a where clause:

fn <T impl ToString> print_value(value: T) where T.value == "MyThing" {
    std::println(value as string)
}

where conditions are evaluated at compile time when possible the branch is eliminated entirely. When the condition depends on runtime values, the function becomes conditionally callable and the compiler inserts a check at the call site. See Bounds for the full constraint system.

Function Modifiers

Modifiers appear after the parameter list and before the return type arrow. Multiple modifiers can be combined, subject to the compatibility rules below.

fn compute(x: i32) const inline -> i32 { return x * x }
fn dangerous() unsafe -> void          { /* ... */ }
fn compile_time() eval -> i32          { return 42 }
fn may_fail() panic -> i32             { /* ... */ }
fn background() async -> Data          { /* ... */ }

Modifier reference

Modifier compatibility

Not all modifiers can be combined:

Visibility

pub fn public_api()       { /* ... */ }
priv fn internal_helper() { /* ... */ }
prot fn for_subclasses()  { /* ... */ }

Visibility applies to both free functions and methods. See Modules for how visibility interacts with imports.

ABI and Linkage

ABI modifiers control name mangling, dispatch mechanism, and symbol visibility at the object code level.

static, virtual, and override are mutually exclusive with each other. ffi can be combined with any of them.

class Shape {
    virtual fn area(self) const -> f64 { return 0.0 }
}

class Circle : Shape {
    var radius: f64

    override fn area(self) const -> f64 {
        return 3.14159 * self.radius * self.radius
    }
}

class Math {
    static fn sqrt(x: f64) -> f64 { /* ... */ }
}

Math::sqrt(16.0)   // called without an instance

Function Pointers

Functions are first-class values. The type of a function pointer is fn(ParamTypes) -> ReturnType:

fn add(a: i32, b: i32) -> i32 = a + b
fn sub(a: i32, b: i32) -> i32 = a - b

var op: fn(i32, i32) -> i32 = add
op(3, 4)   // 7

op = sub
op(10, 3)  // 7

Functions can be nested inner functions are scoped to the enclosing function:

fn outer(x: i32) -> i32 {
    fn inner(y: i32) -> i32 = y * 2
    return inner(x) + 1
}

Closures

Anonymous functions (lambdas) capture variables from the enclosing scope. Default capture is by copy; use |&| for capture-by-reference or specify per-variable:

var multiplier = 3
var scale = fn (x: i32) -> i32 { return x * multiplier }   // captures multiplier by copy

scale(10)   // 30

See Closures for capture modes (|&|, |a, &b|), lifetime rules, and how closures interact with AMT.

Operator Functions

Operators are overloaded with the fn op syntax:

class Vec2 {
    var x: f64
    var y: f64

    fn op +(self, other: Vec2) -> Vec2 {
        return Vec2 { x: self.x + other.x, y: self.y + other.y }
    }
}

See Operators for the full list of overloadable operators, special operator syntax (l++/r++, op as, op in, op delete), and restrictions.

Forward Declarations

A function can be declared without a body a signature followed by no block:

fn parse_expression(tokens: [Token]) -> Expr
fn parse_statement(tokens: [Token]) -> Stmt

Within a single module, forward declarations are rarely needed. Kairo hoists all top-level declarations before type checking, so mutual recursion works without them:

fn is_even(n: u32) -> bool = if n == 0 { true } else { is_odd(n - 1) }
fn is_odd(n: u32) -> bool  = if n == 0 { false } else { is_even(n - 1) }

Forward declarations are used when the definition lives elsewhere:

• FFI imports the body is provided by a C or C++ library. See C/C++ Interop.

• Separate translation units the declaration is visible to callers; the definition is linked in from another .kro file.

• Out-of-line class methods declared in the class body, defined outside it using the Class::method qualified-name syntax:

  class Parser {
      var pos: usize
      fn advance(self)    -> Token
      fn peek(self) const -> Token
  }
  
  fn Parser::advance(self) -> Token {
      var t = self.tokens[self.pos]
      self.pos += 1
      return t
  }
  
  fn Parser::peek(self) const -> Token = self.tokens[self.pos]

  See Classes for the full rules.

Signature matching

When a definition follows a forward declaration, the two must match exactly:

• Parameter types, return type, and all function modifiers (const, unsafe, panic, eval, async, inline, final, volatile)
• Visibility (pub, priv, prot)
• ABI linkage (ffi "c", ffi "c++", static, virtual, override)

Parameter names and default values may differ the declaration’s names and defaults are used at call sites that see only the declaration; the definition’s are used everywhere else. For consistency, keep them the same.

A mismatch in any other element is a compile error.

Summary

// Basic function
fn add(a: i32, b: i32) -> i32 = a + b

// Default parameters + named arguments
fn connect(host: string = "localhost", port: i32 = 8080) { /* ... */ }
connect(port: 9090)

// Generic with bounds
fn <T impl Printable> show(value: T) { std::println(value as string) }

// Variadic
fn <...T> log(...args: T) { /* ... */ }

// Overloaded
fn process(x: i32) -> i32 { /* ... */ }
fn process(x: string) -> string { /* ... */ }

// Unsafe overload
fn process(x: i32) unsafe -> i32 { /* ... */ }

// Method with modifiers
class Server {
    pub fn start(self) async panic { /* ... */ }
    pub fn status(self) const -> string { /* ... */ }
    pub static fn default_port() -> i32 = 8080
}

// Function pointer
var handler: fn(Request) -> Response = handle_request

// No-return
fn abort() -> ! { std::crash(1) }

Closures

_{https://www.kairolang.org/docs/language/closures/}

Closures

A closure is an anonymous function that captures variables from its enclosing scope. In Kairo, lambdas and closures use the same syntax the only distinction is whether the function captures anything. If it does, it’s a closure. If it doesn’t, it’s a plain lambda.

Basic Syntax

Anonymous functions are declared with fn followed by a parameter list, an optional return type, and a body. The return type is inferred when omitted.

var add = fn (a: i32, b: i32) -> i32 {
    return a + b
}

var double = fn (x: i32) -> i32 {
    return x * 2
}

add(3, 4)     // 7
double(10)    // 20

Closures have the same type as function pointers fn(ParamTypes) -> ReturnType. There is no separate closure type:

var op: fn(i32, i32) -> i32 = fn (a: i32, b: i32) -> i32 { return a + b }

Capture Modes

By default, closures capture variables by copy. The closure receives its own copy of each captured variable mutations inside the closure do not affect the original.

var x = 10
var add_x = fn (y: i32) -> i32 {
    return y + x   // x is captured by copy
}

x = 999
add_x(5)   // 15 uses the copied value of x (10), not 999

Capture by reference |&|

To capture all variables by reference, append |&| after the parameter list. The closure can read and modify the original variables:

var count = 0
var increment = fn ()|&| {
    count += 1   // modifies the original count
}

increment()
increment()
count   // 2

Mixed capture |a, &b|

Specify capture mode per variable. Unqualified names are captured by copy, &-prefixed names by reference:

var a = 10
var b = 20

var closure = fn (x: i32)|a, &b| -> i32 {
    b += 1       // modifies the original b
    return x + a + b   // a is a copy, b is a reference
}

closure(5)   // 5 + 10 + 21 = 36
a            // still 10
b            // 21

Capture summary

Default Parameters

Closures support default parameter values, matching the behavior of regular functions:

var greet = fn (name: string = "world") {
    std::println(f"Hello, {name}!")
}

greet()          // "Hello, world!"
greet("Alice")   // "Hello, Alice!"

Generic Closures

Closures can be generic, declaring type parameters before the parameter list:

var identity = fn <T>(x: T) -> T {
    return x
}

identity(42)        // i32
identity("hello")   // string

panic Specifier

Closures can be marked panic to indicate they may panic. Callers must handle the panic via try/catch, the same as with regular functions:

var risky = fn () panic -> i32 {
    if bad_condition {
        panic std::Error::Runtime("failed")
    }
    return 42
}

try {
    risky()
} catch e {
    std::println(f"Caught: {e}")
}

See Panic for the full panic model.

AMT and Lifetime Safety

AMT tracks closure captures the same way it tracks any other borrow. If a closure captures a variable by reference and the closure outlives the variable, AMT will attempt to auto-promote the capture to a smart pointer (shared, weak, or unique). If promotion is not possible, the compiler emits a hard error.

fn make_closure() -> fn() -> i32 {
    var x = 42
    return fn ()|&x| -> i32 { return x }
    // AMT error: x is a stack local, closure would outlive it,
    //   and there is no safe promotion path for a stack variable
}

Capture by copy avoids this entirely the closure owns its own copy and has no lifetime dependency on the original:

fn make_closure() -> fn() -> i32 {
    var x = 42
    return fn () -> i32 { return x }   // ok x is copied into the closure
}

Closures vs Inner Functions

Inner functions (named functions declared inside another function) do not capture from the enclosing scope they are self-contained:

fn outer() -> i32 {
    var x = 10

    fn inner(y: i32) -> i32 = y + 1     // cannot access x inner is a plain function
    // fn inner(y: i32) -> i32 = y + x  // compile error: x is not in scope

    return inner(x)   // pass x explicitly
}

If you need to reference enclosing variables, use a closure. If you don’t, prefer an inner function it has no capture overhead and makes the data flow explicit.

Passing Closures to Functions

Since closures share the fn pointer type, they can be passed to any function expecting a function pointer:

fn apply(f: fn(i32) -> i32, x: i32) -> i32 {
    return f(x)
}

apply(fn (x: i32) -> i32 { return x * 2 }, 21)   // 42

var triple = fn (x: i32) -> i32 { return x * 3 }
apply(triple, 10)   // 30