Kairo Language Reference

Built-in data types in Kairo integers, floats, booleans, characters, strings, pointers, collections, and their semantics.

Built-in collection types in Kairo arrays, slices, vectors, list literals, maps, sets, tuples, and function pointers.

Variable declarations, constants, static, type inference, shadowing, destructuring, const semantics, and scope rules in Kairo.

T? is sugar for Nullable<T>, a built-in type that holds either a value of type T or null.

Arithmetic, comparison, logical, bitwise, assignment, range, null-safe access, operator overloading, and precedence rules in Kairo.

Conditionals, match, loops, labeled breaks, try/catch/finally, panic, assert, jumps, compile-time branching, and branch hints in Kairo.

match in Kairo: value, enum, ADT, struct, and range patterns, where guards, match expressions, and exhaustiveness.

Function declarations, parameters, return types, overloading, modifiers, generics, variadic functions, and calling conventions in Kairo.

• Default, Named, and Variadic Parameters

  Default parameters, named arguments, and variadic functions in Kairo.

• Parameter Passing Modes

  The x: T, @inout, and @move parameter modes, call-site syntax, and reference returns from C++.

• Function Overloading

  Overloading by parameter types and modes, tie-breaks, unsafe overloads, and the const overloading restriction.

• Generators

  Generator functions declared with -> yield T, generator lifetimes, and special return types.

• Function Declarations

  Function modifiers, visibility, ABI and linkage, and forward declarations in Kairo.

Anonymous functions, capture modes, lambda syntax, and how closures interact with Tether in Kairo.

The Kairo type system: inference, implicit conversions, subtyping, TypeInfo, typeof, nullable nesting, void and never, and function types.

• Type Aliases

  Type aliases in Kairo: transparent and generic aliases, strict aliasing mode, visibility rules, and restrictions.

Struct declarations, aggregate initialization, field visibility, generics, extends, layout control, and how structs differ from classes in Kairo.

Enum declarations, discriminants, underlying types, ADT variants with payloads, generics, extends, and enum semantics in Kairo.

• Plain Enums

  Plain enums in Kairo - named integer constants, discriminant values, bit flags, underlying types, casting, and forward declarations.

• ADT Enums

  ADT enums in Kairo - variants with payloads, construction, destructuring with match, memory layout, lifecycle, generic and variadic enums, and casting.

Untagged union declarations, memory overlay semantics, trivial-type restriction, generics, and layout rules in Kairo.

Classes in Kairo: constructors, destructors, lifecycle categories, inheritance, virtual dispatch, abstract classes, generics, visibility and memory layout.

• Class Lifecycle

  Destructors (op delete) and lifecycle categories in Kairo classes: transfer constructors, COPY / MOVE / NON_TRANSFER, the Rule of Three and auto-derived assignment.

• Inheritance and Virtual Dispatch

  Class inheritance in Kairo: derives, inheritance visibility, multiple and virtual inheritance, virtual destructors, virtual dispatch, abstract classes and final.

• Forward Declarations and Out-of-Line Definitions

  Forward-declaring Kairo classes and defining their methods, constructors, destructors and operators out of line with Class::method syntax.

Interfaces in Kairo: structural conformance, generic interfaces, interface inheritance, operator and constructor requirements, and zero-cost contracts.

• Interface Requirements

  Operator, constructor, static method, and Self return type requirements in Kairo interfaces.

Extend blocks for adding methods, operators, static functions, and interface conformance to structs, enums, and classes in Kairo.

Generic type parameters in Kairo: how generic bodies are checked, implicit capabilities, kind bounds and interface bounds.

Requires clauses in Kairo: compile-time constraints on functions, types and interfaces, and how they restrict generic code.

Where clauses in Kairo attach runtime-conditional constraints to declarations. They are evaluated at runtime and can dispatch on values or types.

Defining operators on user-defined types with fn op methods, including const overloads, special operators, place operators and op delete.

Explicit type conversions with as, numeric truncation, pointer casts, downcasting, provenance rules, user-defined conversions, and cast safety rules in Kairo.

• Implicit Conversions

  Conversions Kairo applies without as numeric widening and derived-to-base pointer upcasts.

• Kairo Primitive Conversion Lattice

  Normative specification for implicit and explicit conversions between primitive types.

Pointers in Kairo: safe and unsafe raw pointers, null semantics, pointer arithmetic, smart pointer promotion, void and double pointers, and safety rules.

Transfer semantics, pointer aliasing, closure captures, and destruction order in Kairo's ownership model.

Tether, Kairo's compile-time proof engine for pointer safety: bounds, provenance, lifetime, ownership and data-race freedom proved over the whole program.

• Proof Model

  How Tether proves a dereference safe: the dereference obligation, the proof lattice, and the per-clause residual table.

• Bounds and Provenance

  Tether's bounds and use-after-free analysis: pointer arithmetic, hoisting, one-past-the-end, provenance and epochs, and interior pointers.

• Ownership and Promotion

  How Tether promotes heap pointers to std::Unique, std::Shared or std::Weak, and how stack-pointer escapes are handled in debug and release.

• Threading

  Tether's threading analysis: strict mode inside a task's extent, the race-freedom rule set, and sharing syntax for closures and async functions.

• Tether Internals

  Tether at the edges: C/C++ interop, generic code, .amt summaries, and soundness and testing.

Global, scoped and freestanding allocators in Kairo, the static Allocator interface, and how allocators meet C++.

Unsafe blocks, unsafe pointers, unsafe function overloads, Tether suspension, forget, and the safety boundary model in Kairo.

Async/await, spawn, yield, coroutines, atomic types, thread-local storage, and synchronization primitives in Kairo.

The panic specifier, error types and op panic, inferred and declared panic sets, try/catch exhaustiveness, panic propagation, main and crash!, and zero-cost codegen in Kairo.

Kairo compiler error messages explained: arrays, slices, overload resolution, default arguments, lifecycle, enums, scripts and value arms, and how to fix each one.

Eval variables, eval functions, eval if, eval for, compile-time evaluation rules, restrictions, and interaction with generics in Kairo.

Token-level macros, macro definitions, built-in macros, variadic helpers, source location, diagnostics, code generation, and macro hygiene in Kairo.

• Built-in Macros

  Compiler-provided macros in Kairo - token manipulation, variadic helpers, source location, diagnostics, code generation, conditional checks, and compiler intrinsic macros.

AST-level code transformations, attribute definitions, arguments, expansion order, overloading, built-in attributes, and the std::AST API in Kairo.

How Kairo modules work: file-to-module mapping, scripts, library entry files, module namespaces, visibility, circular dependencies and module reopening.

How imports work in Kairo: bringing names from other modules into scope, import forms, resolution semantics, visibility rules and FFI header imports.

Bidirectional C and C++ interop in Kairo: the kairo and kcc drivers, FFI imports, inline C++, templates, allocators, ownership and the kld ABI contract.

• kairo, kcc & Cross-compilation

  The Kairo toolchain model: the kairo and kcc drivers, the pinned Clang, cross-compilation with curated sysroots, and compiler flags across the C++ boundary.

• Calling C and C++ from Kairo

  Importing C and C++ headers with ffi, operators and argument conversions on C++ types, linkage, namespace mapping, inline assembly, pointers and references, strings, and templates and concepts.

• Using Kairo in C++

  Exposing Kairo to C++: including .k files with kcc, generated per-module headers, how Kairo declarations and generics appear in C++, and tuples across the boundary.

• Allocators & Ownership

  How heap ownership crosses the C++ boundary: class-specific operator new and delete, the global allocator, CxxNewAllocator, and ownership and lifetime annotations in generated headers.

• Exceptions & Panics

  How Kairo panics and C++ exceptions meet at the boundary: catching C++ exceptions in Kairo, why Kairo never throws, and converting Kairo results to exceptions on the C++ side.

• ABI Contract & Verification

  The Kairo C++ ABI contract: link-time ABI verification with kld, name mangling, platform ABI compatibility, stability across compiler stages, and declaration ordering in emitted headers.