# OxigenLang Syntax Quick Reference

This is a concise reference for OxigenLang syntax. For detailed explanations, follow the links to the individual guides.

## Variables — [Full Guide](https://www.oxigenlang.org/docs/variables/)

```oxi
x := 10                    // untyped, mutable
x <int> = 10               // typed, immutable value
x <int> := 10              // typed, mutable value
x <int>                    // typed, zero-value init
x as <int>                 // alternative form (optional `as`)
a, b := [1, 2]             // array/tuple unpacking
```

## Data Types — [Full Guide](https://www.oxigenlang.org/docs/data-types/)

| Type    | Example                    | Type Keyword |
|---------|----------------------------|--------------|
| Integer | `42`, `-7`                 | `int`        |
| Float   | `3.14`, `-0.5`             | `float`      |
| String  | `"hello"`, `'world'`, `"line\n"`, `"""multi\nline"""` | `str`  |
| Char    | `` `a` ``, `` `Z` ``      | `char`       |
| Boolean | `True`, `False`            | `bool`       |
| Array   | `[1, 2, 3]`               | `array`      |
| Tuple   | `(1, "hello", True)`       | `tuple`      |
| Map     | `{"key": "value"}`         | `map`        |
| Set     | `set(1, 2, 3)`             | `set`        |
| Byte    | `byte(65)`                 | `byte`       |
| Uint    | `uint(42)`                 | `uint`       |
| None    | `None`                     | —            |

## Operators — [Full Guide](https://www.oxigenlang.org/docs/operators/)

```oxi
x + y    x - y    x * y    x / y    x % y       // arithmetic
x == y   x != y   x < y    x > y    x <= y  x >= y  // comparison
x and y  x or y                                  // logical
(x or y) == val                                  // distributed comparison
!x       not x    -x                             // prefix
x++      x--                                     // postfix
arr[0]   arr[1:3]   obj.field                    // access
m[key] = val   arr[0] = val                      // index assignment
```

## Control Flow — [Full Guide](https://www.oxigenlang.org/docs/control-flow/)

```oxi
option { cond -> value, default }                // conditional expression
option { cond, true_val, false_val }             // ternary shorthand
unless condition { body }                        // inverse conditional
value unless condition then fallback             // unless expression with fallback
println("hi") when condition                     // postfix when guard
println("hi") unless condition                   // postfix unless guard
println("hi") unless condition then println()    // postfix unless with alternative
expr guard err -> fallback                       // recover from an error value
expr <guard>(fallback)                           // preferred angle-effect recovery
<log>("message")                                 // log to stderr with timestamp
<log<tag>>("message")                            // log with tag: [TAG] message
<fail>("message")                                // preferred angle-effect failure
fail "message"                                   // produce a runtime error
each item in collection { body }                 // iteration
repeat when condition { body }                   // while loop
skip                                             // continue
stop                                             // break
main { body }                                   // runs only when file is executed directly
```

## Functions — [Full Guide](https://www.oxigenlang.org/docs/functions/)

```oxi
fun name(a, b) { a + b }                        // named function
f := fun(x) { x * 2 }                           // anonymous function
fun add(a <int>, b <int>) { a + b }             // typed parameters
fun greet(name <str>, msg <str> = "Hi") { ... } // default value
fun connect(host <str>, port? <int>) { ... }     // optional parameter
greet("Alice", msg="Hey")                        // named argument
give value                                       // return early (there is no `return`; the last expression is returned)
give value when condition                        // conditional return
```

## Pattern Matching — [Full Guide](https://www.oxigenlang.org/docs/pattern-matching/)

```oxi
pattern is_even(n) when n % 2 == 0              // define pattern

choose val {                                      // match against patterns
    is_even -> println("even"),
    pattern is_odd(n) when n % 2 != 0 -> println("odd"),
    else -> println("fallback")
}
```

## Structs — [Full Guide](https://www.oxigenlang.org/docs/structs/)

```oxi
struct Person { name <str>  age <int> }          // definition
p := Person("Alice", 30)                         // positional
p := Person { name: "Alice", age: 30 }           // named
p.name                                           // field access
p.age = 31                                       // field mutation

Person includes {                                // methods
    fun greet() { "Hello, " + name }
}

struct Student(Person) { school <str> }          // inheritance
```

## Type System — [Full Guide](https://www.oxigenlang.org/docs/type-system/)

```oxi
x <int> = 10               // strict (immutable, no conversion)
x <int> := 3.9             // walrus (mutable, converts to 3)
x <int>                    // zero-value init
result <Error || Value> := <type<Error || Value>>(read_file("config"))
err := <Error<network>>("connection lost")
wrapped := <Value>("ok")
type(x)                    // type introspection
is_mut(x)                  // value mutability check
is_type_mut(x)             // type mutability check
```

## Angle Forms — [Full Guide](https://www.oxigenlang.org/docs/angle-forms/)

```oxi
name <str> := "Oxigen"                             // type annotation in declaration position
count <int>                                        // zero-init typed binding
num <int> := "10"                                  // typed walrus conversion
<Error>("failed to initialize")                    // construct an error value
<Error<retry_error>>("retry failed")               // construct a tagged error value
<Value>("ok")                                      // construct an explicit success wrapper
<type<Error || Value>>(read_file("config"))        // normalize into expected-result space
read_file("config") <guard>("")                    // recover from runtime error
<log<Error>>("read failed")                        // log with Error tag to stderr
<fail>("missing config")                           // propagate a runtime error
main { ... }                                      // entry point (skipped when imported)
```

## Escape Sequences

```oxi
"\n"   "\t"   "\r"   "\\"   "\""   "\'"   "\0"
```

## Multi-line Strings

Triple quotes (`"""..."""` or `'''...'''`) span multiple lines and keep raw
newlines verbatim. They support the same `{}` interpolation and escapes as
single-line strings. See [data_types.md](https://www.oxigenlang.org/docs/data-types/#multi-line-strings).

```oxi
banner := """
Welcome, {name}!
Lines are kept as written.
"""
```

## Comments

```oxi
// single-line comment
x := 10  // inline comment
/* multi-line
   comment */
```

## Block Styles

```oxi
each i in [1, 2, 3] {      // brace-based (default)
    println(i)
}
```

```oxi
#[indent]                   // indentation-based
each i in [1, 2, 3]:
    println(i)
```

```oxi
#!/usr/bin/env oxigen        // direct execution
#[location=/usr/bin/env oxigen] // preserved interpreter metadata
#[indent]
each i in [1, 2, 3]:
    println(i)
```

Each statement ends at the end of its line (or at the `}` of a one-line
block); two statements on one line are an error. In `#[indent]` files, lines
holding only a comment don't count towards indentation, a dedent must return to
a column an enclosing block used, and indentation inside `(...)`, `[...]` and
written `{...}` is layout only — so a multi-line call, list or map works as it
does in brace style.

## Built-in Functions — [Full Guide](https://www.oxigenlang.org/docs/builtins/)

| Category     | Functions                                          |
|--------------|----------------------------------------------------|
| I/O          | `print`, `println`                                 |
| Collections  | `len`, `first`, `last`, `rest`, `has`, `copy`      |
| Add / remove | `push`, `insert`, `remove`, `pop`, `extend`, `clear` |
| Iteration    | `range`                                            |
| Conversion   | `ord`, `chr`, `str`, `chars`                       |
| Constructors | `byte`, `uint`, `set`, `tuple`                     |
| Map          | `keys`, `values`                                   |
| Introspection| `type`, `is_mut`, `is_type_mut`                    |