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.

Types and values

Data types#

Faber has a static, type-first type system. Every declaration places the type before the name — the string comes first, then the identifier it names, not the other way round. The type system covers scalar primitives, generic collections, sized numerics, tensors, and GPU-facing register types.

Primitive types#

TypeRoleExample literal
stringUnicode string"Salve, munde"
asciiFixed machine token'solum:lege'
i32Signed integer42
f64Floating-point3.14
boolBooleantrue, false
voidUnit / no value—
noneNull / absent (the null value is null)null
instantDuration / time instant—
jsonCompile-time JSON value{ "key": "value" }
list<b8> (en list<b8>)Byte string: a run of raw bytes. There is no separate byte word (the old octeti / bytes is retired)\|00ff\|

Sized numeric types#

Write the width in type position. These are the numeric types — the same list as Math in the ether:

FamilyWidths
Signedi8 i16 i32 i64
Unsignedu8 u16 u32 u64
Decimald64
Unbounded integerinf
Floatingf16 bf16 f32 f64
reader locale
faber convert --to en — English reader surface
main {
    let i32 narrow ← 7 ∷ i32
    let u64 wide ← 255 ∷ u64
    let f32 single ← 1.5 ∷ f32
}
faber convert --to la — canonical Faber
incipit {
    sit i32 narrow ← 7 ∷ i32
    sit u64 wide ← 255 ∷ u64
    sit f32 single ← 1.5 ∷ f32
}
faber convert --to th-TH — Thai
เริ่ม {
    กำหนด i32 narrow ← 7 ∷ i32
    กำหนด u64 wide ← 255 ∷ u64
    กำหนด f32 single ← 1.5 ∷ f32
}
faber convert --to zh-Hans — Simplified Chinese
入口 {
    设 i32 narrow ← 7 ∷ i32
    设 u64 wide ← 255 ∷ u64
    设 f32 single ← 1.5 ∷ f32
}
faber convert --to zh-Hant — Traditional Chinese
入口 {
    設為 i32 narrow ← 7 ∷ i32
    設為 u64 wide ← 255 ∷ u64
    設為 f32 single ← 1.5 ∷ f32
}
faber convert --to vi — Vietnamese
bắt_đầu {
    đặt i32 narrow ← 7 ∷ i32
    đặt u64 wide ← 255 ∷ u64
    đặt f32 single ← 1.5 ∷ f32
}
faber convert --to ar — Arabic
بداية {
    ليكن i32 narrow ← 7 ∷ i32
    ليكن u64 wide ← 255 ∷ u64
    ليكن f32 single ← 1.5 ∷ f32
}
faber convert --to hi — Hindi
आरंभ {
    बैठा i32 narrow ← 7 ∷ i32
    बैठा u64 wide ← 255 ∷ u64
    बैठा f32 single ← 1.5 ∷ f32
}

The bare width marker is the type.

Raw bits#

The markers b8, b16, b32 and b64 are raw bits, not numbers, so they are not in the table above. A b8 is exactly eight bits, and a b8 is also the element of a byte string: |00ff| is a list<b8> (en list<b8>). There is no byte type: eight raw bits are b8, an eight-bit number is u8, and a run of bytes is list<b8>.

Raw bits take the bit operators ∧ ∨ ⊻ ¬ ⇐ ⇒ and nothing else. Each operation acts at the type's own width: a left shift drops bits off the top, and a shift by the full width or more gives all zeros. There is no arithmetic (SEM011 bits_arithmetic_refused) and no mixing with numbers or with another width. To read the bits as a number, convert to the same-width numeric type with ↦.

main {
    let b8 flags ← 240 ∷ b8
    let b8 low ← flags ⇒ 4
    let b8 both ← flags ∨ low
    let u8 count ← both ↦ u8
    print both, count
}

The conversion runs both ways between a bits type and a number of the same width: n ↦ b32 for a u32 or i32, and back with ↦ u32. A width that does not match is SEM016 bits_conversion_width_mismatch, and a literal negative shift count is SEM010 shift_count_negative. Converting into f16 or bf16 rounds to that format at the store.

main {
    let u32 n ← 7
    let b32 bits ← n ↦ b32
    let u32 back ← bits ↦ u32
    print bits, back

    let f16 h ← 0.1 ↦ f16
    print h ↦ f64

    let b8 flags ← 0xf0
    print flags ⇒ 4
}

This prints 0x00000007 7, then 0.0999755859375 (the nearest f16 to 0.1), then 0x0f.

Nullable types#

Nullable values use the union syntax T ∪ none:

fn find(string key) → int ∪ none {
    return null
}

fn maybe() → string ∪ none {
    return null
}

There is no T? or Option<T> syntax in Faber. The union is explicit.

Type aliases#

type UserId = int

Generics#

Functions, type aliases, class, and interface accept type parameters with <T> syntax:

fn identitas<T>(T value) → T {
    return value
}

fn primum<T>(list<T> res) → T ∪ none {
    return res.first()
}

Explicit call-site type arguments are supported:

reader locale
faber convert --to en — English reader surface
fn identitas<T>(T datum) → T {
    return datum
}

main {
    let int seven ← identitas<int>(7)
}
faber convert --to la — canonical Faber
functio identitas<T>(T datum) → T {
    redde datum
}

incipit {
    sit numerus seven ← identitas<numerus>(7)
}
faber convert --to th-TH — Thai
ฟังก์ชัน identitas<T>(T datum) → T {
    คืน datum
}

เริ่ม {
    กำหนด จํานวน seven ← identitas<จํานวน>(7)
}
faber convert --to zh-Hans — Simplified Chinese
函数 identitas<T>(T datum) → T {
    返回 datum
}

入口 {
    设 整数 seven ← identitas<整数>(7)
}
faber convert --to zh-Hant — Traditional Chinese
函式 identitas<T>(T datum) → T {
    傳回 datum
}

入口 {
    設為 整數 seven ← identitas<整數>(7)
}
faber convert --to vi — Vietnamese
hàm identitas<T>(T datum) → T {
    trả datum
}

bắt_đầu {
    đặt số seven ← identitas<số>(7)
}
faber convert --to ar — Arabic
دالة identitas<T>(T datum) → T {
    أعد datum
}

بداية {
    ليكن عدد seven ← identitas<عدد>(7)
}
faber convert --to hi — Hindi
फलन identitas<T>(T datum) → T {
    लौटाओ datum
}

आरंभ {
    बैठा संख्या seven ← identitas<संख्या>(7)
}

Interfaces#

An interface (la interface) is a contract of methods, and a class that says implements (la implements) must keep it. The compiler checks the contract: a missing method is SEM010 implet_missing_method, and a method whose signature differs from the contract's is SEM010 implet_method_signature_mismatch.

interface Shape {
    fn area() → f64
}

class Square implements Shape {
    let f64 side

    fn area() → f64 {
        return self.side * self.side
    }
}

main {
    let Square sq ← Square { side = 3.0 }
    print sq.area()
}

Collections#

TypeRoleSugar
list<T>Ordered dynamic collectionlf32, lu32
map<K, V>Key-value map—
tensor<T, Figura>Dense fixed-shape buffertf32[4], ti64[2,3]
sparse<T, Figura>Sparse fixed-shape buffersf32[4], si64[2,3]
rangeRange type—
record<label: T, …>Labeled record value (en record){ label = value }
set<T>Unordered set—
cursor<T>Lazy stream—
promise<T>Async finite result from async functions; promise<T ⇥ E> carries a delayed alternate channel—
main {
    let list<int> nums ← [1, 2, 3]
    let map<string, int> scores ← { "alice": 10, "bob": 20 }
}

Tensor types#

tensor<T, Figura> is the dense fixed-shape container:

FormMeaning
tensor<T, Figura>Canonical spelling
tensor<T, []>Rank-0 (scalar container)
tensor<T, _>Shape inference hole
tensor<T, [N]>Rank-1 vector
tensor<T, [N, M]>Rank-2 matrix
main {
    let tensor<f32, []> scalar ← empty
    let tensor<int, [4]> row ← [1, 2, 3, 4] ↦ tensor<int, [4]>
    let int ∪ none first ← row[0]
}

GPU core types#

These are recognised by the systems lane for GPU and register work. Package targets that lack hardware support reject them:

fn half(f16 x) → f16 { return x }

fn add(matrix<f32, [2, 2]> a, matrix<f32, [2, 2]> b) → matrix<f32, [2, 2]> {
    return a.added(b)
}

fn swap(mut atomic<i32> cell, i32 value) → i32 {
    return cell.exchange(value)
}

Borrow markers on types#

Access markers (ref, mut, own, copy; Latin de, varia, penes, exemplum) can appear on types in parameter positions to indicate how a value is passed. A parameter with no marker is ref:

# shared borrow — caller retains ownership
fn imprime(ref string label) → void {
}

# mutable borrow — caller lends mutable access
fn duplica(mut int value) → void {
    value ← value + 1
}

# move — caller gives up ownership
fn consume(own string buffer) → string {
    return buffer
}

main {
    mut int n ← 1
    let string s ← "salve"

    imprime(s)
    duplica(mut n)
    let _ t ← consume(own s)
}

The call site repeats the mut and own markers (Latin varia and penes): duplica(mut n), consume(own s). Leaving one off is SEM057 call_marker_missing. A parameter with no marker is ref: the function may read it and may not write it.

What copy will not duplicate#

copy makes an independent value, and some values have an identity that cannot be duplicated: a channel, which is how a file or other host resource reaches Faber, and a class that implements Closable. Since 1.18 a copy of a value that reaches one is a compile error, through a field, a collection element, a union or a tuple member, and the diagnostic names the member path. SEM066 copy_nonduplicable_member here reports Envelope.payload:

class Envelope {
    mut channel payload
}

main {
    let channel source ← call 'runtime:echo' ("hello")
    let Envelope packet ← Envelope { payload = source }
    mut Envelope duplicate ← copy packet
    print duplicate.payload
}

Share the value without copy, or hand the resource over with own where the consumer may own it. Deep copies of ordinary classes, lists and maps are unchanged.

Comparison policy#

OperatorFamilyBehaviour
≡, ≢Exact equalityIdentical types required; null bypass
≅, ≇Promoted exact equalityNumeric widths join, then exact compare
≈, ≉Fuzzy equalityTolerance match — isclose defaults (rel_tol 1e-09); numeric operands only
≺, ≤, ≻, ≥OrderingNumeric, instant, scalar text; ASCII < and > are generic delimiters, not comparisons
withinRange containmentNumeric in range
betweenCollection membershipElement in collection

Variables and binding#

Four binding words say how a name is bound, and a dedicated glyph attaches a value. The key distinctions are between a fixed name and a writable one, and between ← (runtime flow) and = (structural field shape).

EnglishLatinMeaning
let T x ← eleta fixed name
mut T x ← emutre-pointable and writable
ref T x ← erefre-pointable and read-only
const T X = econsta compile-time fact, set with =

Every binding word writes its type slot. There is no short form: let x ← 3 is PARSE010 binding_type_slot_required. Write the type, let int x ← 3, or write _ to have it inferred, let _ x ← 3.

let (let) — a fixed name#

A let binding cannot be assigned again once it is set. It may be declared with or without an initializer; if declared without, it must be assigned exactly once before reading. A second assignment is SEM020 immutable_second_assignment.

main {
    let int count ← 0
    let string name ← "Marcus"
    let _ inferred ← [1, 2, 3]
}

Deferred initialisation:

main {
    let int factor
    if true {
        factor ← 10
    }
    else {
        factor ← 100
    }
    print factor
}

mut (mut) — a writable name#

A mut binding can be assigned again, and its value can be written through the name. The retired word for this was var (PARSE010 var_retired):

main {
    mut int count ← 0
    count ← count + 1
    count ← count * 2
}

Inferred types with _#

_ in the type slot asks the compiler to infer the type. It works with every binding word, and with the deferred form, which is still written with the slot:

main {
    let _ salve ← "Salve"
    let _ name ← "Marcus"
    let _ x ← 42

    # Deferred form
    let _ label
    label ← "deferred"
}

A local may take the name of a value word such as true, false or null. The binding shadows the value for the rest of its scope, and the compiler warns WARN021 value_literal_shadowing instead of refusing it:

main {
    let string true ← "t"
    print true
}

This prints t.

ref (ref) and const (const)#

ref names a value that can be re-pointed but not written. It is the mode of a bare parameter. const is no longer a run-time binding: it declares a compile-time fact with =, never ←. A run-time const T x ← e (Latin const) is PARSE010 runtime_const_retired; write let.

const int LIMIT = 3

fn first(list<int> xs) → int {
    ref list<int> view ← xs
    return view[0]
}

main {
    let int n ← 4
    mut int total ← 0
    total ← total + n
    print first([5, 6]), LIMIT, total
}

Runtime binding vs structural definition#

Faber splits what most languages collapse into =:

GlyphRoleUse for
←Runtime flowInitial binding, reassignment, mutation
=Structural shapeField names inside literals and metadata
class Point {
    let int x
    let int y
}

main {
    # Runtime: ← attaches a value to a name at execution time
    mut int count ← 0
    mut string label ← "ready"
    count ← count + 1

    # Structural: = defines field values inside a type literal
    let _ p ← Point { x = 10, y = 20 }
}

Field extraction (from)#

from extracts fields from a value into local bindings:

class Persona {
    let string nomen
    let int aetas
}

main {
    let _ p ← Persona { nomen = "Marcus", aetas = 30 }
    let string nomen ← p.nomen
    let int aetas ← p.aetas
    # prints "Marcus"
    print nomen
}

Mutable numeric updates#

Use binary + and - with runtime assignment ← to update mutable int places. Both operators take two operands; they are not postfix statements:

main {
    mut int i ← 0
    # i becomes 1
    i ← i + 1
    # i becomes 0
    i ← i - 1
}

Collections#

Faber has several compiler-owned collection types. Their canonical methods live in the compiler, not in the standard library.

Lista — ordered dynamic collection#

main {
    let list<int> empty ← empty
    let _ numbers ← [1, 2, 3, 4, 5]
    let _ names ← ["Marcus", "Julia", "Gaius"]
    let _ nested ← [[1, 2], [3, 4]]
}

Spread with spread:

main {
    let list<int> a ← [1, 2, 3]
    let list<int> b ← [4, 5, 6]
    let _ combined ← [spread a, spread b]
    let _ headed ← [0, spread a, 99]
}

Key methods: length, get, append, extend, find, sum, first, last, take, slice.

xs.extend(ys) appends every element of another list of the same element type, in order and in place; the argument is read once first, so a list can extend itself. xs.find(T x ∴ predicate) (la reperta) returns the first element where the predicate holds as T ∪ none, calling the predicate left to right and stopping at the first match. Since 1.17.

take(n) and slice(a, b) are checked windows. A window that runs past the end of the list is reported, not clamped, so both are failable: outside main the call needs a handler (a ⊥ recovery value, a do { } catch, or a failable enclosing function), or it is SEM011 failable_call_requires_handler. Inside main an unhandled failure ends the program with take_out_of_range or slice_out_of_range.

fn head(list<int> xs, int n) → list<int> {
    return xs.take(n) ⊥ xs
}

main {
    let list<int> xs ← [1, 2, 3, 4, 5]
    print head(xs, 2)
    print head(xs, 9)
    print xs.slice(1, 3) ⊥ []
}

This prints [1, 2], [1, 2, 3, 4, 5] and [2, 3]. Before 1.15 the second call clamped silently; it now falls back to xs because the window failed. The runner, Rust, TypeScript and Python all check windows this way (generated TypeScript and Python clamped until 1.16).

Bounded lists — size#

A list can carry a length limit in its type. The limit is written after size (la size): list<int, size 4> holds at most four elements. A bare list<int, 4> is retired by name (SEM008 list_count_needs_size), and so is a bare lo‥hi range, which bounds a value rather than a count. The same rule covers every bounded container: vector<f32, size 4> (the vf32[4] sugar is unchanged), queue<int, size 4>, stack<int, size 4>, string<size 8> and ascii<size 8> (SEM008 vector_width_needs_size, SEM008 capacity_needs_size).

A range after size bounds the length. ‥ leaves the upper bound out and … includes it, so list<int, size 2 ‥ 5> holds two to four elements and list<int, size 1…∞> is never empty: first and last return plain values. Growing past the maximum or removing below the minimum reports on the error channel. list<int, size 3> and list<int, size 0…3> are the same type.

A short list literal takes the capacity of the cell it is stored into, whether the cell is a variable, a field or a call argument: [1, 2] stored into list<int, size 0…3> is a list with room for three. A literal longer than the maximum is refused by name.

main {
    # Never empty: first and last are plain ints.
    mut list<int, size 1…∞> xs ← [1, 2, 3]
    print xs.first()
    print xs.last()
    print xs.length()
    xs.append(4)
    print xs

    # Lengths 2 to 4: the fifth push does not fit.
    mut list<int, size 2 ‥ 5> ys ← [10, 20]
    do {
        ys.append(30)
        ys.append(40)
        ys.append(50)
        print "unreachable"
    }
    catch err {
        print "full: §"(err)
    }
    print ys

    # A short literal takes the cell's capacity.
    let list<int, size 0…3> pair ← [1, 2]
    print pair
}

This prints 1, 3, 3, [1, 2, 3, 4], then `full: list length range: push past the maximum, [10, 20, 30, 40] and [1, 2]`.

Tabula — key-value map#

main {
    let map<string, int> scores ← { "alice": 10, "bob": 20 }
}

The : there is not map syntax. A bare { … } with quoted keys and : is inline JSON — a compile-time json document. Declaring the binding as a map ascribes that document to a map type, which lowers it to a real constant map.

Faber's own key-value shape uses =: on a named type, Point { x = 10 }, or with no type name as a record, { x = 10 }. A record is a value with labeled, read-only fields, not a map: it has no keys to look up at run time.

For a map you build up rather than declare whole, start from empty and assign by key:

main {
    mut map<string, int> puncta ← empty
    puncta["alpha"] ← 1
    puncta["beta"] ← 2
    print puncta.length()
}

Records — labeled values#

A record is a value made of labeled fields. The English type word is record (Latin ratio). Fields are read by label, never by position, and a record is not a class: two record types are the same when they have the same labels with exactly the same field types, in any order.

A bare { label = value } in a cell with no declared type is a record whose fields take their default types; record<*> names that type. A record prints like a class value without the type name, in the order the fields were written. A destructuring rest binding of a typed record is a record of the fields that were not named.

main {
    let record<x: f64, y: int> typed ← record<x: f64, y: int> { x = 1.5, y = 2 }
    let _ point ← { x = 1.5, y = 2 }
    print typed.x
    print point

    let {x, rest others} ← typed
    print x
    print others
}

This prints 1.5, { x = 1.5, y = 2 }, 1.5 and { y = 2 }.

Records are values, so their fields are read-only. Writing through a field is SEM020 assignment_to_fixum_field, even when the binding is mut; build a new record, or use a class with a mut field.

main {
    mut _ point ← { x = 1.5, y = 2 }
    point.x ← 3.0
}

Tensor — dense fixed-shape buffer#

main {
    let tensor<f32, []> scalar ← empty
    let tensor<int, [4]> row ← [1, 2, 3, 4] ↦ tensor<int, [4]>
    let int ∪ none first ← row[0]
}

Tensor sugar (numeric-heavy code):

main {
    let tf32[4] lanes ← [1.0, 2.0, 3.0, 4.0] ↦ tf32[4]
}

A rank-1 tensor takes a range in brackets and gives that window as a new tensor. A literal range that falls outside a literal shape is SEM011 index_provably_out_of_bounds.

main {
    let tf32[6] v ← [1.0, 2.0, 3.0, 4.0, 5.0, 6.0] ↦ tf32[6]
    let tf32[3] mid ← v[1‥4]
    print mid
}

This prints [2.0, 3.0, 4.0].

A matrix reads and writes one element by row and column with a double bracket, m[[row, col]], and the coordinates may be computed. The method forms follow the three list reads: m.get([r, c]) gives none for a coordinate outside the shape, m.at([r, c]) reports it on the error channel, and m.set([r, c], v) stores. A literal coordinate that is provably outside the shape is refused at compile time.

A vector and a matrix are values, so ← copies them. Since 1.18 every target agrees: a write through the copy never reaches the original. There is no storage for a marker to name, so ref over a vector is refused (SEM008 scalar_access_marker).

main {
    let vf32[3] a ← [1.0, 2.0, 3.0] ↦ vf32[3]
    mut vf32[3] b ← a
    b[0] ← 9.0
    print a[0]
    print b[0]
}

This prints 1.0 and 9.0.

main {
    mut matrix<f32, [2, 2]> m ← [[1.0, 2.0], [3.0, 4.0]] ↦ matrix<f32, [2, 2]>
    let int row ← 1
    print m[[0, 1]]
    m[[row, 0]] ← 7.5
    print m.get([row, 5]) coalesce 0.0
    print m.at([row, 1]) ⊥ 0.0
    print m
}

This prints 2.0, 0.0, 4.0 and [[1.0, 2.0], [7.5, 4.0]]. A bracket range on a vector or a matrix slices to a vector or a matrix, and ↦ converts between tensors, vectors and matrices of the same shape.

Known issue in 1.18: element access runs on faber run, but generated Rust does not compile it yet, and the Swift and LLVM targets refuse it by name rather than approximate it.

Reductions (reduce via), ordered scans (scan via) and edge policies (.edge<clamp>()) are covered in Tensor computation.

Key methods: reshape, get, set, create, tensor.structa (Latin namespace lookup, not a receiver method), plus elementwise added/subtract/multiply/divide/negate, matrix multiplication (matmul), and reductions (sum, mean).

Sparsa — sparse fixed-shape buffer#

The English spelling is sparse (since 1.15; an English file that writes the Latin sparsa is PARSE040 wrong_locale_type).

main {
    mut sparse<f32, [2, 3]> sparse ← empty
    sparse.set([0, 1], 4.0)
    sparse.set([1, 2], 9.0)

    # get returns the stored value, here 4.0
    print sparse.get([0, 1])
    # count of stored entries
    print sparse.count_nonzero()
}

Conversion between dense and sparse:

main {
    let tf32[2, 2] dense ← [[1.0, 0.0], [0.0, 2.0]] ↦ tensor<f32, [2, 2]>
    let sf32[2, 2] sparse ← dense ↦ sparse<f32, [2, 2]>
    let tf32[2, 2] roundtrip ← sparse ↦ tensor<f32, [2, 2]>
}

Cursors — lazy streams#

cursor<T> is a lazy stream type. Created from collection iterators, recv views, or generator functions. Consumed via for from:

main {
    let _ items ← [1, 2, 3]
    for from items let item {
        print item
    }
}

Generator functions declare their stream posture in the signature slot: generator is a synchronous stream and async_generator an asynchronous stream; the body yields values with yield (see Functions — async and streams).

Sinks — ⇜#

Sink<T> is the contract for "take one item". A class opts in with implements Sink<T> and supplies sink(T) and flush(), both failable. s ⇜ x is the operator form of s.sink(x): the method reports a failed write on the error channel, and the operator stops the program. The item must be exactly the sink's T; there is no implicit conversion. The sink must be writable, so a let sink is refused.

The contract is declared in the source file today (an import of norma:sink checks but does not run yet):

@ radix contract "sinking"
interface Sink<T> {
    fn sink(T item) → void ⇥ string
    fn flush() → void ⇥ string
}

class Tally implements Sink<int> {
    mut int total = 0

    fn sink(int item) → void ⇥ string {
        self.total ← self.total + item
    }

    fn flush() → void ⇥ string {
    }
}

main {
    mut Tally tally ← Tally { total = 0 }
    tally.sink(3)
    tally ⇜ 4
    print tally.total
}

This prints 7. Lists and sets are sinks too: ⇜ appends to a list (duplicates kept) and adds a missing item to a set. On a bounded list<T, size N> that is already full, .sink(v) reports.

main {
    mut list<string> log ← []
    log.append("begin")
    log ⇜ "step"
    log ⇜ "step"
    print log
}

This prints ["begin", "step", "step"]; log.append(v) and log ⇜ v do the same thing here.

Known issue in 1.18: the Go, TypeScript, Swift and Python targets refuse ⇜ by name (CODEGEN001).

Intervallum — ranges#

# exclusive range: 0, 1, 2, 3, 4
for range 0 ‥ 5 let i {
    print i
}
# inclusive range: 0, 1, 2, 3, 4, 5
for range 0 … 5 let i {
    print i
}

‥ is exclusive range endpoint; … is inclusive.

A range is also a value. The English type word is range (since 1.15; an English file that writes the Latin intervallum is PARSE040 wrong_locale_type). A range stored in a cell can be walked, and printing it shows its construction:

main {
    let range<int> r ← 2‥5
    print r
    for range r let i {
        print i
    }
}

This prints 2‥5, then 2, 3 and 4.

A stored range can carry a step (since 1.16). The step is part of the type: range<int> has step 1, and range<int, 2> steps by 2. length() counts only the members on the step, and contains(v) is true only for a value on the step.

main {
    let range<int, 2> evens ← 0…10 step 2
    print evens.length()
    print evens.contains(4)
    print evens.contains(3)
}

This prints 6, true and false. A stored step must be a positive integer literal and the bounds must be integers; a step known only at run time stays inline in for range and in bracket windows (SEM010 intervallum_value_step_unsupported elsewhere). Operations that cannot keep a step (clamp, coercere, between, union) refuse a stepped range by name rather than dropping the step.

String and template literals#

Faber uses delimiter semantics — each quote form means a different source shape. They are not interchangeable synonyms.

Literal forms#

FormTypeRole
'…'asciiFixed machine tokens; no §; no (…)
"…"stringShort Unicode line strings; (…) renders
«…»stringBlock/multiline Unicode; (…) renders
… formaCaptured templates; (…) captures
{ … }jsonCompile-time JSON document
\|…\|list<b8> (en list<b8>)Compile-time hex bytes
regex /…/regexInline pattern literal; raw body, \/ writes a slash (inside a class too: [\/])
_ /…/regexThe same literal where the cell gives the type
[ … ]list<T>Faber list literal

A bounded text cell such as ascii<size N> keeps text behaviour: + joins and the ordering operators compare as text.

main {
    let ascii<size 8> a ← 'ab'
    let ascii<size 8> b ← 'cd'
    print a + b
    print a ≺ b
    print 'ab' ≥ 'cd'
}

This prints abcd, true and false.

Text windows — slice#

s.slice(a, b) is the half-open window of characters a up to b. Like the list window, it is checked and reports on the error channel when the window does not lie inside the text: an end past the length, a negative bound, or a start past the end. The text is never clamped to what exists. An empty window at a legal position is fine: s.slice(2, 2) is "". Outside main the call needs a handler (a ⊥ recovery value, a do { } catch, or a failable enclosing function), or it is SEM011 failable_call_requires_handler. A window the checker can prove is in range, from an integer guard or a loop bound, needs no handler.

fn window(string s, int lo, int hi) → string {
    return s.slice(lo, hi) ⊥ "reported"
}

main {
    let string s ← "héllo"
    print s.slice(1, 3) ⊥ "reported"
    print window(s, 2, 99)
    print window(s, 4, 2)
    do {
        print s.slice(6, 7)
    }
    catch err {
        print "start past the end reported"
    }
}

This prints él, reported, reported and start past the end reported. Positions count characters, so s.slice(1, 3) of héllo is él.

String-template application#

Faber formats text with string-template application: a "…" or «…» literal with § holes, then parenthesised arguments:

fn greet(string name) → string {
    return "Salve, §!"(name)
}

main {
    let int pagina ← 3
    let int totum ← 10
    let string code ← "200"
    let string label ← "OK"

    let _ msg ← "Page § of §"(pagina, totum)
    let _ block ← "status: § (§)"(code, label)
    let _ again ← "§1 of §0, §1"(pagina, totum)
}

Key rules:

  • § (U+00A7) is the template hole
  • Numbered holes: §N selects argument N, counting from 0, and may repeat. "§1 of §0, §1"(a, b) reads b, then a, then b again
  • A numbered template needs max(N)+1 values, and every index below the highest must be read by some hole; a gap is SEM008 template_hole_index_gap
  • Trailing ! selects display formatting: "Salve, §!"(name)
  • The (args) suffix is template application, not a function call

Escapes#

A string literal may escape only its own delimiter, the backslash, n, t, r and u{…}. Any other escape is LEX003 unknown_escape; the old pass-through is gone. Text that contains quotes can use guillemets, «say "hi"», with no escapes, and the lint WARN034 suggests that rewrite.

Block strings#

Multiline blocks use guillemets «…»:

main {
    let _ sql ← «
        select id, email
        from accounts
    »
}

Guillemets are the only block-string spelling since Radix v0.79.0 — the retired """ and ❝…❞ spellings fail as ordinary lex errors.

Captured templates (forma)#

Backtick templates capture text and parameters without rendering. Safe for bound SQL/URL payloads:

main {
    let int user_id ← 42
    let _ query ← `select * from users where id = §`(user_id)
}

Inline JSON#

A bare { … } with quoted keys and : is inline JSON: a compile-time json document. (With label = value fields it is a record instead.) Values are JSON constants only — no variable references, no Faber expressions. Ascribing one to a map lowers it to a real constant map; ↦ value widens it to the dynamic carrier instead:

main {
    let json blank ← {}
    let _ user ← { "name": "Marcus", "age": 30, "active": true }
    let _ nested ← { "meta": { "version": 1 }, "tags": ["alpha", "beta"] }
}

For typed class construction, use the type name and = field shape:

class Point {
    let int x
    let int y
}

main {
    let _ p ← Point { x = 10, y = 20 }
}

Nullability and optionality#

Faber distinguishes absence in a value from optional provision at a declaration site.

Nullable values — T ∪ none#

Use T ∪ none when the value can be absent:

fn find(string key) → int ∪ none {
    return null
}

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

Optional declaration slots — optional#

Use optional after the name when a parameter or field may be omitted by the caller or constructor:

fn connect(string host, int port optional) → void {
}

class User {
    let string email optional
}

Borrow markers can combine with optional parameters:

fn process(ref int depth optional) → void {
}

Non-null assertion — !#

Use !., ![, !( to assert a nullable value is not null:

class Box {
    let int ∪ none val
}

main {
    let Box ∪ none maybe_name ← Box { val = 7 }
    let _ name ← maybe_name!.val
}

A non-null assertion on null aborts at runtime.

Nullish coalescing — vel#

main {
    let string ∪ none provided ← null
    let _ name ← provided coalesce "default"
}

unknown#

unknown is the top-level unknown type for escape hatches and incomplete knowledge. It is not a nullability mechanism.

Conversion and construction#

Two important conversion operators, one for runtime and one for compile-time:

main {
    # runtime conversion
    let _ parsed ← "42" ↦ int ⊥ 0
    # static ascription
    let int count ← 7
    let _ text ← count ∷ string
}

Runtime conversion — ↦#

Use ↦ for runtime conversion, especially parsing or coercion that may fail. Supply an inline default with ⊥:

main {
    let string input ← "9"
    let _ n ← "42" ↦ int ⊥ 0
    let _ safe ← input ↦ int ⊥ 0
}

Type-directed materialization:

main {
    let string path ← "/etc/hosts"
    let _ lanes ← [1.0, 2.0, 3.0, 4.0] ↦ vector<f32, size 4>
    let _ body ← call 'solum:lege' (path) ↦ string
}

Text converts to a boolean only when it is the code locale's word: in an English file "true" ↦ bool and "false" ↦ bool succeed, and any other text fails and takes the ⊥ value. Without a ⊥ the failure stops the program. Every target agrees (since 1.16; Go, TypeScript, Swift, LLVM and Racket used to test truthiness or emptiness instead).

main {
    print "true" ↦ bool ⊥ false
    print "yes" ↦ bool ⊥ false
}

This prints true and false.

Not every pair converts. Text does not convert to a list of characters with ↦; that is refused by name (SEM016 textus_to_lista_unsupported).

Static ascription — ∷#

Use ∷ for explicit static type ascription. It is postfix and target-type driven:

main {
    let int count ← 7
    let _ x ← 7 ∷ i32
    let _ text ← count ∷ string
}

Nullish coalescing — vel#

Use coalesce for nullish coalescing when a value is null:

main {
    let string ∪ none provided_name ← null
    let _ name ← provided_name coalesce "default"
}