Error Handling Guide

(ok 42)        ;; ok result
(err 99)       ;; err result

(ok?  r)       ;; => bool
(err? r)       ;; => bool

(ok-val  r)    ;; => int  (undefined behaviour if r is err)
(err-val r)    ;; => int  (undefined behaviour if r is ok)

(result-unwrap     r)            ;; ok value, or abort() with message to stderr
(result-unwrap-or  r default)    ;; ok value, or default
(result-expect     r "message")  ;; ok value, or abort() printing "message"
(result-must       r)            ;; ok value, or panic "result-must: called on err"
(result-must-msg   r "msg")      ;; ok value, or panic with "msg"

(result-map      r f)            ;; apply f to ok value; propagate err unchanged
(result-map-err  r f)            ;; apply f to err value; propagate ok unchanged
(result-flat-map r f)            ;; f receives ok value and returns a new result
(result-or       r alt)          ;; r if ok, else alt
(result-or-else  r f)            ;; r if ok, else (f err-value)

(result-eq? r1 r2 ok-cmp err-cmp)
;; ok-cmp  -- fn [a b :int] :bool  used when both are ok
;; err-cmp -- fn [a b :int] :bool  used when both are err
;; => bool; false if variants differ

(eq? (ok 1) (ok 1))   ;; => true
(eq? (ok 1) (err 1))  ;; => false

(ok-or   opt err-val)    ;; some(v) -> ok(v), none -> err(err-val)
(err-context r "prefix") ;; prepend "prefix: " to the err string; ok passes through

(result-collect    vec)    ;; (vec result) -> result<vec, E>; first err wins
(result-partition  vec)    ;; -> pair; separate ok and err elements
(result-partition-ok  pair)  ;; -> vec of ok values from the pair
(result-partition-err pair)  ;; -> vec of err values from the pair

(result-free r)    ;; free the heap struct (does not free the contained value)

(? expr)            ;; s-expression

(let [__q expr]
  (if (err? __q)
      (return __q)        ;; propagate the err Result unchanged
      (ok-val __q)))      ;; otherwise yield the unwrapped ok value

The lowering routes through the #fx{}-safe stdlib helpers __tur-q-is-err? and __tur-q-ok-val (in stdlib/result.tur), so call sites need no (unsafe ...) wrapper.

Scope rule

? is only valid inside a function body -- using it at the top level is a hard error (? operator is only allowed inside a function body). Because it expands to (return <err>), the enclosing function must itself return a Result so the propagated err is well-typed.

Applying ? to a non-Result literal is rejected up front:

(? 5)   ;; error [TUR-E0001]: ? operator requires a Result value, got int

Computed non-Result operands are caught by the same TUR-E0001 check when the __tur-q-is-err? helper fails to accept them.

Worked example

;; parse-config threads three fallible steps; any err short-circuits.
(defn parse-config [src : ptr<void>] : ptr<void>
  (let [raw    (? (read-source  src))]
    (let [toks (? (tokenize     raw))]
      (let [ast (? (parse-forms toks))]
        (ok ast)))))

If read-source, tokenize, or parse-forms returns an err, parse-config returns that err immediately; otherwise it returns (ok ast).

For the "transform the error, then propagate" use case, combine ? with result-or-else to rewrite the err payload before it bubbles up.

Option

An option is either (some value) or (none). none is represented as NULL.

Constructors

(some 42)    ;; some option
(none)       ;; none option (NULL)

(some? o)    ;; => bool

(option-unwrap o)            ;; value, or exit(1) with message to stderr
(option-must   o)            ;; value, or panic "option-must: called on none"
(option-expect o "message")  ;; value, or panic with "message"

(ok-or opt err-val)    ;; some(v) -> ok(v), none -> err(err-val)

(option-eq? o1 o2 cmp-fn)
;; cmp-fn -- fn [a b :int] :bool
;; => true if both none, or both some with cmp-fn returning true

(option-free o)    ;; free the heap struct

(panic "something went wrong")

(defn supervisor [] : int
  ;; #lint-panic-allow
  (panic "unrecoverable")   ;; not flagged
  0)

Catching a panic at a boundary: catch-unwind

catch-unwind runs a nullary thunk behind a panic boundary. If the thunk returns normally, the result is (ok value); if the thunk panics, the panic is intercepted and the result is (err panic), where the err slot carries an opaque Panic handle. Execution then continues after the boundary instead of aborting.

(let [r (catch-unwind (fn [] : int (risky)))]
  (if (err? r)
    (recover)
    (use (ok-val r))))

(load "stdlib/panic.tur")

(let [r (catch-unwind (fn [] : int (panic "boom")))]
  (when (err? r)
    (println (panic-message (result-panic r)))))  ; => boom

stdlib/panic exposes result-panic (extract the Panic from an err result), panic-message, panic-file, panic-line, and panic-type.

Interaction with defer. Defer thunks registered inside the thunk fire during unwinding, before catch-unwind produces its err result -- a defer can observe that a panic is in progress. Because the thunk runs in its own call frame, only its defers fire; defers above the boundary are untouched (partial unwind).

Double panic. If a defer thunk that fires during unwinding itself panics, the double-panic guard triggers abort() -- the inner panic is fatal and is not caught (matching Rust's catch_unwind + Drop-panic semantics).

Typed catches: catch-panic-of. (catch-panic-of Type thunk) is like catch-unwind but only catches panics whose payload type matches Type; panics of any other type are re-raised to the next outer boundary.

(catch-panic-of :cstr (fn [] : int (panic "string panic")))  ;; caught
(catch-panic-of :int  (fn [] : int (panic "string panic")))  ;; re-raised

See docs/design/error-handling-rationale.md for the exception-vs-panic boundary catch-unwind is meant to sit on.

Unwrap helpers: must! and must-msg!

These macros unwrap an option value, panicking on none:

(must!     (some 42))                   ;; => 42
(must!     (none))                      ;; panic: option-must: called on none

(must-msg! (some 42) "expected value")  ;; => 42
(must-msg! (none)    "expected value")  ;; panic: expected value

(option-must   (some 42))               ;; => 42
(option-must   (none))                  ;; panic: option-must: called on none
(option-expect (some 42) "want value")  ;; => 42
(option-expect (none)    "want value")  ;; panic: want value

(ignore! (some-fn-returning-result))

(defn main [] : int
  (write-record r)   ;; warning: discarded result value of type ptr<void>;
                     ;;          use ignore! to suppress this warning
  0)

The warning is off by default and is silenced three ways:

• ignore! -- (ignore! (write-record r)) expands to (do expr nil), so the discarded value is nil, not a result. Use this when discarding is intentional.
• Binding it -- (let [_ (write-record r)] ...). A let binding (even to _) is an explicit discard and never warns.
• Using the value -- e.g. propagating it with the ? operator. Because (? expr) binds its operand in a let, a ?-wrapped call is never in statement position and never triggers the warning.

Contract macros

Contract macros live in stdlib/macros.tur (module tur/macros) and are auto-imported. They all expand to tur-contract-check or tur-contract-check-inv from stdlib/contract.tur, which call tur_panic on failure.

By default contracts are enabled (contract-enabled? returns true). Pass --no-contracts to strip them from a release build: every assert! / require! / ensure! / invariant! is dropped at elaboration time, so the contract's predicate expression is never evaluated, and contract-enabled? folds to false.

Side-effect warning. Because the predicate is removed entirely, any side effect inside a contract condition disappears under --no-contracts -- this matches the C / Rust assert convention. Keep contract predicates pure; never rely on a side effect that lives inside (assert! ...).

The codegen preamble also defines TUR_CONTRACTS_ENABLED (1 normally, 0 under --no-contracts) so inline-C blocks can branch on the build mode. See the compiler flags guide for the release-build recipe.

assert! and assert-msg!

Unconditional sanity check. Use anywhere you want to verify an intermediate condition holds:

(assert! (= x 1))
;; panics with "Assertion failed" if x != 1

(assert-msg! (= x 1) "x must be 1")
;; panics with "x must be 1" if x != 1

(defn sqrt [n : int] : int
  (require! (>= n 0))
  ...)
;; panics with "Precondition failed" if n < 0

(defn sqrt [n : int] : int
  (require-msg! (>= n 0) "sqrt: n must be non-negative")
  ...)

(defn abs [n : int] : int
  (let [result (if (< n 0) (- 0 n) n)]
    (ensure! (>= result 0))
    result))
;; panics with "Postcondition failed" if the result is somehow negative

(invariant! my-list non-empty?)
;; panics with "Invariant failed" if (non-empty? my-list) is false

(invariant-msg! my-list non-empty? "list must not be empty")