Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

Errors and testing

Error handling#

Faber separates three related ideas that many languages collapse into one shape:

ConstructMeaning
→ TNormal success return channel
T ∪ noneAbsence in the success value domain
⇥ ERecoverable alternate-exit channel for errors

Normal return#

fn porta(int x) → int {
    if x ≺ 0 then return 0
    return x * 2
}

Failable functions#

Use ⇥ when a function can leave by an error channel:

fn divide(int a, int b) → int ⇥ string {
    if b ≡ 0 {
        throw "division by zero"
    }
    return a / b
}

The type after ⇥ is the payload. The value that travels on the channel is the compiler-owned carrier error<T> (en error<T>), which has one field, payload, and nothing else. catch (en catch) binds the payload T, never the carrier, so programs that do not name the carrier read exactly as before.

Throwing — throw#

throw sends a value on the error channel:

fn exigePositivum(int value) → void ⇥ string {
    if value ≺ 0 {
        throw "negative value"
    }
}

Guards — require / reject#

Guard statements pair a condition with a throw in one line. require (English reader spelling require) throws when the condition fails — it demands that the condition hold:

fn divide(int a, int b) → int ⇥ string {
    require b ≢ 0 throw "division by zero"
    return a / b
}

reject (English reader spelling reject) is its boolean opposite: it throws when the condition holds. Read it as an early rejection — the happy path is whatever the condition rules out:

fn exigePositivum(int value) → int ⇥ string {
    reject value ≺ 0 throw "negative value"
    return value
}

Both compile to the same shape as an if around throw — `reject cond throw err is exactly if cond { throw err } — and, like throw` itself, they require the enclosing function to declare a ⇥ channel.

Recovery — do / catch#

Callers recover locally with a do block and a catch handler:

fn divide(int a, int b) → int {
    if b ≡ 0 then return 0
    return a / b
}

fn tutum(int a, int b) → int {
    do {
        return divide(a, b)
    }
    catch err {
        warn err
        return 0
    }
}

A direct failable call is not an ordinary expression. Place calls to → T ⇥ E functions inside an active do / catch boundary.

Capturing — trap#

trap { … } (Latin trap) runs its block and turns the error channel into a value. Since 1.18 the value is the tagged trapped<R, T>, with the variants returned and thrown, read with an ordinary match. R and T are separate slots, so a string success with a string error is legal: the variants carry the difference. Arms that name member types, case int or case string, no longer work.

fn half(int n) → int ⇥ string {
    if n % 2 ≢ 0 {
        throw "odd"
    }
    return n / 2
}

main {
    let _ missed ← trap { half(7) }
    match missed {
        case returned let value {
            print "returned §"(value)
        }
        case thrown let err {
            print "thrown §"(err)
        }
    }
}

This prints thrown odd. trap captures only the ⇥ channel: a panic stays fatal. A boundary around nothing failable is WARN036 trap_error_channel_empty.

The alternate channel in async surfaces#

The same ⇥ E channel rides inside Faber's async types rather than as a separate mechanism. A async function returns promise<T> — the infallible shorthand for promise<T ⇥ numquam> — and promise<T ⇥ E> preserves the delayed alternate alongside the eventual value. Awaiting a failable promise is itself a failable operation: the success value binds inside a do / catch boundary while the failure stays observable, exactly like a failable sync call.

Async and sync streams carry the channel too: async_generator → T ⇥ E makes every pull a promise that can yield, end, or fail (the first failure ends the stream, handled by for from); generator → T ⇥ E makes the stream call itself failable, recovered with do / catch.

See Functions — two-channel promises for the full treatment.

Inline conversion recovery#

⊥ specifies an inline default value on ↦ conversions (⇥ only ever names an error type):

main {
    let string raw ← "42"
    let _ n ← raw ↦ int ⊥ 0
}

Effect-only failable#

For functions that error but do not return a success value, omit → T:

fn exigePositivum(int value) → void ⇥ string {
    if value ≺ 0 {
        throw "negative value"
    }
}

Fault unions#

The type after ⇥ is not limited to string. Norma's I/O functions fail with a union: fs.read_file<T>(path) is → T ⇥ fault.IoFault, and IoFault has one variant per kind of failure (NotFound, Permission, IsADirectory, and so on), each carrying the path it failed on. A catch binding of that type is matched with match:

import from "norma:fs" fs

fn read_or_empty(string path) → string {
    do {
        return fs.read_file<string>(path)
    } catch err {
        match err {
            case NotFound let missing {
                print "no such file: §"(missing)
                return ""
            }
            case Permission let denied {
                print "not allowed: §"(denied)
                return ""
            }
            default {
                print "I/O failure"
                return ""
            }
        }
    }
}

main {
    print "read: [§]"(read_or_empty("/no/such/file.txt"))
}
$ faber run
no such file: /no/such/file.txt
read: []

Current status#

→, return, ⇥, throw, and do / catch are live grammar and checker surfaces, and faber run executes them. Rust lowers a failable function to a Result<T, E> and handles do / catch around it. Go and TypeScript lowering is partial: Go reports CODEGEN001 go_structured_cape_handlers_unsupported for some catch shapes, and the corpus suite pins the remaining failable-call gaps on those targets as known failures. Check a program with faber emit -t <target> before relying on a target other than Rust.

Inline testing#

Faber has a first-class testing framework built into the language with three keywords: describe declares a test suite, test declares a single test case, and assert asserts a condition. Tests live alongside the code they test — either in the same .fab file or in colocated *.proba test-source files — run through faber test on the MIR runner, and support the same compiler pipeline as production code: locale-aware, type-checked, and target-neutral.

The three keywords#

KeywordRoleApproximate equivalent
describeDeclares a named test suitedescribe, #[cfg(test)] mod
testDeclares a single test caseit, #[test]
assertAsserts a condition at runtimeassert!, assert_eq!

describe — test suite#

A describe block groups related test cases. Suites can be nested to organise tests hierarchically:

describe "arithmetica" {
    test "unum plus unum" {
        assert 1 + 1 ≡ 2
    }

    test "multiplicatio" {
        assert 3 * 4 ≡ 12
    }

    describe "implicata" {
        test "comparatio" {
            let _ x ← 10
            assert x ≥ 10
        }
    }
}

test — test case#

A test block contains the test logic. It can use any Faber code — variable bindings, function calls, control flow — and ends with one or more assert assertions. Tests can be tagged with an optional tag marker for selective execution:

test "echo formats operands with one space" tag "coreutils" {
    assert echo_textus(["hello", "world"]) ≡ "hello world"
}

assert — assertion#

assert evaluates a boolean expression and reports failure if it is false. An optional message string provides context on failure:

main {
    let _ x ← 10

    # Simple assertion
    assert x ≻ 0

    # With custom message
    assert x ≡ 10 panic "x decem esse debet"

    # Multiple assertions in sequence
    let _ name ← "Marcus"
    assert name ≡ "Marcus"
    assert name ≢ "" panic "nomen vacuum non sit"
}

Workflow#

Tests run through the faber test command, which executes test cases on the MIR runner — no Cargo or rustc is invoked for the package:

faber test                        # run all tests in the current package
faber test path/to/package        # run tests for a specific package
faber test . --filter smoke       # substring filter on case path or title
faber test . --include math       # load only *.proba sources matching a path pattern
faber test . --exclude 'nested/*' # skip *.proba sources matching a path pattern
faber test . --name my_case       # select by test name
faber test . --suite suite/path   # select by describe suite path
faber test . --tag slow           # select by tag modifier

Tests can live in the same .fab file as the code they test, or in colocated *.proba files (the preferred home for stdlib and public-contract suites). .proba files are test-only: discovered only by faber test, never importable from product modules, and excluded from Cista package snapshots. There is no separate test directory structure and no test module declaration. The compiler knows which blocks are test code and which are production code by the keywords used — describe and test are parsed but excluded from production builds.

Warnings can be promoted to errors with --deny-warnings or --deny <CODE> (repeatable), on faber test and faber build alike.

Real-world example#

The coreutils echo package demonstrates the testing framework in practice. Tests live in the same file as the implementation, covering option parsing, escape expansion, and edge cases:

describe "echo formatting" tag "coreutils" {
    test "empty operands format as empty text" {
        let list<string> words ← empty
        assert echo_textus(words) ≡ ""
    }

    test "single operand is unchanged" {
        assert echo_textus(["hello"]) ≡ "hello"
    }

    test "-E is a leading no-op option" {
        assert echo_textus(["-E", "hello", "world"]) ≡ "hello world"
    }

    test "-n suppresses the trailing newline flag" {
        assert echo_novam_lineam(["-n", "hello"]) ≡ false
    }

    test "-e expands the declared escape subset" {
        assert echo_textus(["-e", "a\\nb"]) ≡ "a\nb"
        assert echo_textus(["-e", "a\\tb"]) ≡ "a\tb"
    }
}

Design notes#

Several design choices distinguish Faber's testing framework from conventional approaches:

  • No separate test binary. Tests are declarations in the same source file (or in *.proba test sources), not a separate compilation target. The compiler filters test blocks from production output.
  • Tags, not directories. Tests are organised by tag markers rather than directory structure. A test can belong to multiple organisational axes without being moved.
  • Full compiler pipeline. Tests are type-checked, analysed, and locale-aware — the same --locale code-locale flag applies.
  • Runner-executed. faber test runs test cases on the MIR runner; no generated test crate, Cargo, or Rust toolchain is required.
  • Target-neutral. The runner analysis is independent of any codegen target.
  • Nested suites. describe blocks can nest, mirroring the structure of the code they test.

References#

  1. radix/corpus/probandum/ — describe exemplar files
  2. radix/corpus/proba/ — test exemplar files
  3. radix/corpus/adfirma/ — assert exemplar files