# Edva Programming Language (llms.txt)

> Edva is a zero-keyword, expression-oriented systems programming language featuring
> deterministic memory, algebraic ramifications, and native LLVM code generation.
> This file is a curated language guide and reference index. For the extended language
> specification and core standard library guide, see [llms-full.txt](llms-full.txt).
> Complete module-by-module references are maintained under `doc/reference/stdlib/`.

---

# 1. Core Principles & Hard Rules

- **Zero Bare Keywords**: Control flow words (`if`, `else`, `for`, `while`, `fn`, `return`,
  `break`) are normal identifiers. All control flow is unified into symbolic expressions.
- **No RTTI, Ever**: Types are erased at runtime; function values are `{ fn_ptr, env_ptr }`.
- **Integer Literals & Types**:
  - `Int` is fixed 64-bit (`i64`) on all CPU architectures (no target-dependent `isize`/`usize`).
    Machine pointer width is represented by `Addr`.
  - Unsuffixed integer literals default to `Int` (or the type set by `#pragma number <type>`).
  - The type system never silently coerces ambiguous expressions or unresolved type variables
    to `Int`. Unresolved types emit `E3103`.
- **Binary Comparisons**: `<`, `>`, `==`, `!=`, `!<` (greater-or-equal), `!>` (less-or-equal).
  `>=` and `<=` do not exist. On floats, `!<` and `!>` are ordered comparisons (OGE/OLE) that
  evaluate to false (`<->`) if either operand is NaN (distinct from `!(x < y)`).
- **Binding Mutability**: `=` binds immutably by default. Rebindable local variables use
  trailing prime (`'`) identifiers (`x' = 1; x' = x' + 1`).
- **Clean Choices**: Single-branch choices `cond | action` evaluate as statements. Never supply
  dummy `| 0` fallbacks. In expression position, choices whose branches all return `RamPN`
  (`< T | >`) or `RamNP` (`< | E >`) synthesize an implicit `| <-->` or `| <++>` fallback.
- **Unquoted Imports**: `#use net`, `#use io`, `#use libc`.
- **Unified Strings & Interpolation**: Double-quoted strings `"..."` support single-line and
  multiline (margin stripping when starting with `"\n`). Dynamic interpolation `${expr}` supports
  scalar primitives (`Int`, `UInt`, `Float`, `Rune`, `String`), desugaring to `%to_str(expr)`
  without requiring `#use str`. Triple-quotes `"""` are retired (`E1018`).
- **Line Length**: Lines must not exceed 100 characters.

---

# 2. Operators & Precedence Table

<!-- BEGIN operators.yaml -->
| Tier | LBP | RBP | Operators | Associativity |
|---|---|---|---|---|
| cycle | 10 | 20 | `@` `@@` `>--` `-->` `--^` | left |
| sequence | 20 | 30 | `;` | left |
| apply | 30 | 30 | `$` `$:` | right |
| feed | 40 | 50 | `$>` `$>>` | left |
| choice | 50 | 60 | `|` `[pattern]` `!|` `|->` `|+>` `|-->` `|++>` | left |
| assignment | 60 | 50 | `=` `:=` `+=` `::=` | right |
| range | 70 | 80 | `..` | left |
| logical or | 80 | 90 | `||` | left |
| logical and | 90 | 100 | `&&` | left |
| bitwise or | 100 | 105 | `.|.` | left |
| bitwise xor | 105 | 110 | `.^.` | left |
| bitwise and | 110 | 120 | `.&.` | left |
| comparison | 120 | 130 | `<` `>` `==` `!=` `!<` `!>` | left, same-line |
| shift | 130 | 140 | `.<.` `.>.` | left |
| addition | 140 | 150 | `+` `-` | left |
| multiplication | 150 | 160 | `*` `/` `%` | left |
| unary prefix | 160 | 180 | `!` `+` `&` `++` `.!.` `~~` `?` `??` `-x` `#size` | right |
| postfix / apply | 170 | 180 | `call ()` `.` `::` `: cast` `{N}` `@[...]` `!!` `--!` | left |
| primary | 180 | 180 | `primary` | left |

<!-- END operators.yaml -->

Notable precedence rules:
- Infix apply `$` and feed `$>` sit below the choice tier.
- Postfix error propagation `--!` sits in the postfix tier (tier 18).
- Cycle jumps (`-->`, `--^`) and cycle escape (`>--`) sit in the cycle tier (tier 1).
- Bitwise precedence is C-style: `||` < `&&` < `.|.` < `.&.` < comparison < `.<.` `.>.`
  < `+` `-` < `*` `/` `%`.

---

# 3. Algebraic Ramifications & Constructors

Ramifications represent binary outcomes with zero-cost runtime representations:
- `RamNN` (`<>`): Bare `i1` Flag (`<+>` true, `<->` false).
- `RamPN` (`< T | >`): Value presence or absence. Positive constructor `<+ val +>`,
  negative unit `<-->`.
- `RamNP` (`< | E >`): Success or error payload. Positive unit `<++>`, negative constructor
  `<- err ->`.
- `RamPP` (`< T | E >`): Two-payload unboxed register aggregate `{ i1 tag, i64 payload }`.
  Positive constructor `<+ val ->`, negative constructor `<- err +>`.

All payload constructors close with `+>` or `->` (never bare `>`). The four shapes are distinct
types and cannot be implicitly coerced between one another.

---

# 4. Essential Control Flow & Error Handling

- **Choice**: `x [100] "perfect" [> 89] "pass" | "fail"`
- **Cycle**: `0..count @ i => (i == 5 | -->)`
- **Cycle Escape**: `found = 0..10 @ i => (i == 3 | -->) >-- 3` (returns `< Int | >`)
- **Early Return**: `--| value` returns value immediately; bare `--|` returns from void functions.
- **Branch Return Sugars**: `|->` (returns `<->`), `|+>` (returns `<+>`), `|-->` (returns `<-->`),
  `|++>` (returns `<++>`).
- **Error Propagation (`--!`)**:
  ```dva partial reason="error propagation fragment with placeholder step functions"
  compute: Int, Int => < Int | String >
  compute = a, b =>
     v1 = step_a(a)--!
     v2 = step_b(b)--!
     <+ v1 + v2 ->
  ```

---

# 5. Documentation Index

- [Curated Full Guide](llms-full.txt): Extended language guide, grammar, and standard library modules.
- [Quickstart](start/quickstart.qmd): Introduction to syntax and essential concepts.
- [Operators](reference/language/operators.qmd): Detailed operator documentation.
- [Ramifications Guide](guide/ramifications.qmd): Comprehensive ramification concepts.
- [Standard Library](reference/stdlib/index.qmd): Full module reference (`io`, `fs`, `in`, `net`, `json`, `sort`, `math`, `str`, `unicode`, `utf`, `event`, `uring`, `color`, `fp`, `type`).