# Tripon

> Tripon is a statically typed, compiled language for low-resource systems. A
> .tp file compiles to C99 (default) or x86-64 through one static binary, ralt.
> There is no null, no implicit conversion, no undefined behaviour and no
> garbage collector. Four tiers — kernel, core, std, full — decide how much
> runtime a file may assume. Every diagnostic carries a stable code, an exact
> span and a fix hint.

Tripon is designed to be driven by a program as much as by a person. The
compiler's output is deterministic, the diagnostic table is append-only, and
the commands that describe a program are cheaper than building it.

## The loop

1. Write the program in a `.tp` file. One file is one compilation unit.
2. Check it: `ralt check foo.tp --json`. This runs lex, parse and typecheck; it
   does not emit or link.
3. Parse the array. Each object has `code`, `kind`, `name`, `file`, `line`,
   `col`, `len`, `msg`, `hint`. An empty array is a clean check.
4. Fix by span. `line` and `col` are 1-based, `len` counts bytes from the start
   of the token. Fix the earliest diagnostic first; later ones are often cascade.
5. Run it: `ralt run foo.tp`. Exit 0 is success, 1 is a diagnostic, 101 is a
   trap (the program ran and hit a defined edge), 2 is a bad command line.
6. For a release: `ralt build foo.tp -o foo`.

Do not guess at a diagnostic's meaning from `msg`. `ralt explain E0202` prints
the stable name and hint, and every code has a page at
https://tripon.vspcoderz.tech/docs/diagnostics.

## The diagnostic object

    { "code": "E0202",
      "kind": "error",          // error | warn
      "name": "type-mismatch",
      "file": "bad.tp",
      "line": 5,                // 1-based
      "col": 13,                // 1-based, byte column
      "len": 7,                 // bytes covered
      "msg": "i32 and f64 do not share an operator; no implicit conversion exists",
      "hint": "types must match exactly; no implicit conversion exists; use cast<T>(x)" }

Codes are never renumbered and never reused. Match on `code`; never match on
`msg`.

## Rules that prevent most diagnostics

- Every type boundary is exact: binding to initializer, argument to parameter,
  operand to operand, return to signature. Write `cast<T>(x)`; there is no
  implicit widening, not even i32 to i64.
- No null. Use `opt<T>` and consume it with `match` or `?`.
- A `result<T, E>` may not be dropped: `match` it or spread it with `?`
  (E0205). `?` is legal only in a function whose return type matches.
- `match` over an enum must cover every variant or end in `_` (E0206).
- A condition must be `bool`. There is no truthiness and no `cast<bool>`.
- Integer literals are `i32` when they fit, otherwise `i64`. Floats are `f64`.
- Arrays are declared, never literal: `let a: [3]i32;` then `a[0] = 1;`.
  They are local-only — no array parameters. Index with `i32`; `len(a)` is
  `i32` and is a compile-time constant.
- Strings are NUL-terminated bytes. Six escapes: \n \t \r \0 \\ \". No
  single quotes, no interpolation, no concatenation.
- Integer arithmetic traps on overflow (E9001), division or remainder by zero
  (E9003). Indexing traps at run time (E9002); a constant index out of range is
  E0202 at check time. `ralt run -fast` selects wrapping instead of the
  overflow trap.
- Not in v0: `**`, bitwise and shift operators, `for`, `loop`, `break`,
  `continue`, slices `[]T`, references `&T`, top-level `const`, `pub`,
  modules, single-quoted strings, chained assignment. Tier ceilings are parsed
  but not enforced yet (E0301/E0302 are reserved, not emitted).

## Commands

- `ralt check <file.tp> [--json]` — lex, parse, typecheck. Clean exit 0.
- `ralt run <file.tp> [-fast]` — build in memory and execute.
- `ralt build <file.tp> [-o out] [-O fast] [-fast] [--backend native]` — write
  an executable. The default backend emits C99 and calls cc.
- `ralt emit <file.tp>` — write the generated C.
- `ralt explain <code>` — code, severity, name, hint.
- `ralt fmt <file.tp>` — the only formatter; two-space indent.
- `ralt doc [--json]` — the documented surface.
- `ralt init <name>` — scaffold ralt.yaml and src/main.tp.
- `ralt lsp` — language server on stdio.
- `ralt tokens <file.tp>` / `ralt tree <file.tp>` — lexer and parse-tree
  oracles: deterministic dumps for checking a port.

## Docs

### start

- [Overview](https://tripon.vspcoderz.tech/docs)
- [Getting started](https://tripon.vspcoderz.tech/docs/getting-started)
- [Hello, Tripon](https://tripon.vspcoderz.tech/docs/hello-tripon)

### language

- [The language](https://tripon.vspcoderz.tech/docs/language)
- [Types and inference](https://tripon.vspcoderz.tech/docs/language/types)
- [Structs, enums, match](https://tripon.vspcoderz.tech/docs/language/data)
- [opt, result and ?](https://tripon.vspcoderz.tech/docs/language/errors)
- [Arrays and strings](https://tripon.vspcoderz.tech/docs/language/arrays)
- [Tiers](https://tripon.vspcoderz.tech/docs/language/tiers)
- [Traps and no-UB](https://tripon.vspcoderz.tech/docs/language/traps)

### toolchain

- [ralt reference](https://tripon.vspcoderz.tech/docs/toolchain)
- [Diagnostic codes](https://tripon.vspcoderz.tech/docs/diagnostics)
- [The agent interface](https://tripon.vspcoderz.tech/docs/agents)

### reference

- [Reference](https://tripon.vspcoderz.tech/docs/reference)
- [Builtins](https://tripon.vspcoderz.tech/docs/reference/builtins)
- [Operators](https://tripon.vspcoderz.tech/docs/reference/operators)
- [Statements](https://tripon.vspcoderz.tech/docs/reference/statements)
- [Literals and names](https://tripon.vspcoderz.tech/docs/reference/literals)
- [extern "C"](https://tripon.vspcoderz.tech/docs/reference/extern)

### more

- [The spec](https://tripon.vspcoderz.tech/docs/spec)
- [Self-hosting](https://tripon.vspcoderz.tech/docs/self-hosting)
- [Roadmap](https://tripon.vspcoderz.tech/docs/roadmap)

## Diagnostic codes

- [E0001 unterminated-string](https://tripon.vspcoderz.tech/docs/diagnostics/E0001): string must close with a double quote on the same line
- [E0002 invalid-character](https://tripon.vspcoderz.tech/docs/diagnostics/E0002): ASCII identifiers only; table in spec/tripon.md
- [E0003 bad-number-literal](https://tripon.vspcoderz.tech/docs/diagnostics/E0003): forms: 123, 0x1F, 0o17, 0b1010, 3.14, 1e-9
- [E0101 unexpected-token](https://tripon.vspcoderz.tech/docs/diagnostics/E0101): see spec/grammar.ebnf for what is legal here
- [E0102 missing-token](https://tripon.vspcoderz.tech/docs/diagnostics/E0102): expected the token named in the message
- [E0201 unknown-identifier](https://tripon.vspcoderz.tech/docs/diagnostics/E0201): define it, use the right module, or fix spelling
- [E0202 type-mismatch](https://tripon.vspcoderz.tech/docs/diagnostics/E0202): types must match exactly; no implicit conversion exists; use cast<T>(x)
- [E0203 mutability-required](https://tripon.vspcoderz.tech/docs/diagnostics/E0203): declared const but reassigned; switch to let
- [E0204 no-null](https://tripon.vspcoderz.tech/docs/diagnostics/E0204): null and undefined do not exist; use opt<T>
- [E0205 unhandled-result](https://tripon.vspcoderz.tech/docs/diagnostics/E0205): Result value ignored; spread with ? or match
- [E0206 non-exhaustive-match](https://tripon.vspcoderz.tech/docs/diagnostics/E0206): match must cover every enum variant or add a deliberate _ arm
- [E0207 implicit-conversion-denied](https://tripon.vspcoderz.tech/docs/diagnostics/E0207): no implicit conversions exist; use cast<T>(x) for exact or explicit lossy casts
- [E0212 duplicate-match-arm](https://tripon.vspcoderz.tech/docs/diagnostics/E0212): remove or reorder the repeated arm; match arms are checked top to bottom
- [E0301 tier-violation](https://tripon.vspcoderz.tech/docs/diagnostics/E0301): feature requires a higher tier; raise the tier target or rewrite the call
- [E0302 tier-not-declared](https://tripon.vspcoderz.tech/docs/diagnostics/E0302): add a top-of-file use tier <name>; statement
- [E0501 entry-point-missing](https://tripon.vspcoderz.tech/docs/diagnostics/E0501): define fn main() -> i32
- [E0601 unused-binding](https://tripon.vspcoderz.tech/docs/diagnostics/E0601): prefix with _ to mute
- [E0602 unreachable-code](https://tripon.vspcoderz.tech/docs/diagnostics/E0602): unreachable after earlier return/branch
- [E0603 shadowing](https://tripon.vspcoderz.tech/docs/diagnostics/E0603): name shadows an existing binding in scope; rename
- [E9001 integer-overflow-trap](https://tripon.vspcoderz.tech/docs/diagnostics/E9001): arithmetic overflow is a defined trap; pass -fast to wrap
- [E9002 index-out-of-bounds](https://tripon.vspcoderz.tech/docs/diagnostics/E9002): indexing is bounds-checked everywhere; slice.len() before indexing
- [E9003 division-by-zero-trap](https://tripon.vspcoderz.tech/docs/diagnostics/E9003): div and mod by zero are defined traps; guard the divisor
- [E9004 cast-overflow-trap](https://tripon.vspcoderz.tech/docs/diagnostics/E9004): float-to-integer casts outside the target range are defined traps

## Source

- [tripon](https://github.com/TriponOSS/tripon): compiler, spec, examples, tests
- [docs](https://github.com/TriponOSS/docs): this site
- The spec is three files: `spec/grammar.ebnf`, `spec/tripon.md`,
  `spec/errors.csv`. The compiler is held to them, not the other way around.