> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kairo Operators and Control Expressions Reference

> Reference for all Kairo v0.1 operators: boolean, comparison, and arithmetic operators, with precedence rules, match expressions, and member access.

Kairo provides a focused set of operators for boolean logic, equality, comparison, and arithmetic. The language deliberately keeps the operator surface small in v0.1 — there is no operator overloading, so every operator has a single, unambiguous meaning. This page documents every operator, the `match` expression form, member access, and precedence rules.

## Boolean Operators

Boolean operators work on `Bool` values and return `Bool`. Kairo does not support truthy/falsy coercion — conditions must be explicitly `Bool`.

| Operator | Description                     | Example                           |
| -------- | ------------------------------- | --------------------------------- |
| `not`    | Logical negation (unary prefix) | `not active`                      |
| `==`     | Equality                        | `status == OrderStatus.Confirmed` |
| `!=`     | Inequality                      | `name != "unknown"`               |

```kairo theme={null}
let active: Bool = true
let inactive: Bool = not active   // false

let a: Int32 = 5
let b: Int32 = 10

if a != b {
    Pulse.Console.out.writeLine("values differ")
}

if not (a == b) {
    Pulse.Console.out.writeLine("also different")
}
```

<Note>
  Kairo uses the keyword `not` for logical negation, not `!`. Writing `!active` is a syntax error.
</Note>

## Comparison Operators

Comparison operators work on ordered types (`Int32`, `Int64`, `Decimal`, `Float64`, `Text`, and temporal types) and return `Bool`.

| Operator | Description           | Example          |
| -------- | --------------------- | ---------------- |
| `<`      | Less than             | `count < 10`     |
| `<=`     | Less than or equal    | `age <= 17`      |
| `>`      | Greater than          | `score > 100`    |
| `>=`     | Greater than or equal | `balance >= 0.0` |

```kairo theme={null}
let count: Int32 = 7

if count >= 5 {
    Pulse.Console.out.writeLine("threshold met")
}

let price: Decimal = 49.99
let budget: Decimal = 50.00

if price <= budget {
    Pulse.Console.out.writeLine("within budget")
}
```

## Arithmetic Operators

Arithmetic operators work on numeric types (`Int32`, `Int64`, `Decimal`, `Float64`) and return the same type as the operands.

| Operator | Description    | Example            |
| -------- | -------------- | ------------------ |
| `+`      | Addition       | `a + b`            |
| `-`      | Subtraction    | `total - discount` |
| `*`      | Multiplication | `price * quantity` |
| `/`      | Division       | `total / count`    |

```kairo theme={null}
let base: Decimal = 100.0
let rate: Decimal = 0.15
let tax: Decimal = base * rate
let total: Decimal = base + tax

let half: Int32 = 10 / 2   // 5
let diff: Int32 = 10 - 3   // 7
```

<Warning>
  Integer division truncates toward zero. `7 / 2` produces `3`, not `3.5`. Use `Decimal` operands when you need fractional results.
</Warning>

## Operator Precedence

Operators are evaluated in the following order (highest precedence first). Use parentheses to override the default order.

| Precedence  | Operators            | Associativity |
| ----------- | -------------------- | ------------- |
| 1 (highest) | `not` (unary)        | Right         |
| 2           | `*`, `/`             | Left          |
| 3           | `+`, `-`             | Left          |
| 4           | `<`, `<=`, `>`, `>=` | Left          |
| 5 (lowest)  | `==`, `!=`           | Left          |

```kairo theme={null}
let result: Bool = 2 + 3 * 4 == 14   // 3*4=12, 2+12=14, 14==14 → true
let guarded: Bool = not result == false   // not is applied to result first
```

<Tip>
  When an expression mixes arithmetic and comparison, add parentheses to make your intent clear — it helps readers and avoids subtle bugs.
</Tip>

## `match` as an Expression

The `match` keyword works both as a statement and as an expression. In expression form, each arm uses `=>` and the whole construct produces a value that you can bind to a `let` or use inline.

```kairo theme={null}
let direction: Direction = Direction.North

// Expression form — produces a Text value
let label: Text = match direction {
    North => "North"
    South => "South"
    East  => "East"
    West  => "West"
}

// Statement form — executes a block per arm
match direction {
    North { Pulse.Console.out.writeLine("Heading north") }
    South { Pulse.Console.out.writeLine("Heading south") }
    else { Pulse.Console.out.writeLine("Heading elsewhere") }
}
```

The `else` arm is the catch-all. In expression form, omitting `else` when the match is not exhaustive is a compile error.

## Member Access — `.`

Use `.` to access a member, property, or method on a type instance, a `type func` on the type itself, or a module-qualified name.

```kairo theme={null}
let inv: Invoice = Invoice(number: "INV-001", total: 299.99)
let n: Text = inv.number        // stored member
let t: Decimal = inv.total

let parsed = Email.parse("a@b.com")   // type func
let ok: Bool = parsed.isSuccess       // Result property
```

Member access chains left-to-right and has higher precedence than any operator.

## No Operator Overloading

Kairo v0.1 does not support operator overloading. Every operator listed on this page has a fixed, built-in meaning. You cannot define custom `+`, `-`, or `==` behaviour for your own types.

<Note>
  Operator overloading is under consideration for a future version of Kairo. Until then, express custom combination logic with named methods (e.g., `price.add(other)` rather than `price + other`).
</Note>

## Complete Example

```kairo theme={null}
module My.App.Billing

import Pulse.Console

public value LineItem {
    unitPrice: Decimal
    quantity: Decimal
}

func lineTotal(item: LineItem): Decimal {
    return item.unitPrice * item.quantity
}

func discounted(total: Decimal, percent: Decimal): Decimal {
    let reduction: Decimal = total * (percent / 100.0)
    return total - reduction
}

func main() {
    let item: LineItem = LineItem { unitPrice: 12.50, quantity: 3.0 }
    let total: Decimal = lineTotal(item)      // 37.50
    let final: Decimal = discounted(total, 10.0) // 33.75

    if final > 30.0 {
        Pulse.Console.out.writeLine("Large order")
    }

    let label: Text = match (final > 20.0) {
        true  => "qualifies for shipping"
        false => "below threshold"
    }
    Pulse.Console.out.writeLine(label)
}
```