Skip to content

Types

Kod is statically typed. Every parameter needs a type annotation; a let without one takes the type of its value.

Naming a type that doesn't exist is an error wherever a type is written: an annotation, a parameter or return type, a struct field, an enum payload, an alias target or a type argument. The error carries a did-you-mean hint when a known type name is close.

An unannotated let takes the type of its value. If the compiler can't work out that type, the binding is an error (cannot infer the type of `x`; add a type annotation), and so is any other use of such a value, like a match subject or an argument. A value whose type is unknown because of an earlier error, such as a call to an unknown function or method, a misspelled field, an unknown variant or an unknown type, doesn't produce further errors where it's used.

Bindings and mutability

A let binding is immutable: once set, reassigning the name is a compile error. Use mut for a binding you need to reassign. += and -= count as reassignment, so they require mut too.

let max: int64 = 100
mut total: int64 = 0
total += max          // ok — total is mutable

max = 50              // error: cannot reassign immutable binding `max`

Mutability belongs to each binding. A let x in a block that hides an outer mut x (see Blocks and bindings) can't be reassigned inside that block, and after the block the outer x can be again. Likewise a mut x in a block leaves an outer let x immutable once the block ends. A for variable and the names a pattern binds, in a match arm, if … is or a let-else, can be reassigned without mut, whatever binding the name had in another block.

A local, whether a let, a parameter, a for variable or a pattern's binding, can't take the name of a type it can see: let str = 3 and for Circle in shapes are errors (`Circle` is the name of a type; give the local another name). In a pattern, a type's name is that type's pattern (see Type patterns).

Assigning to a name that was never declared is an error too (declare it with mut first), and so is assigning to anything other than a name, a field (p.x = 1) or an element (xs[0] = 1).

The value of an annotated let, of an assignment to a name and of an assignment to a field must have the declared type: let x: int64 = "s" is an error (expected `int64`, got `str`), and so is storing an int64 in a bool or an [int64] in a [str]. A T is accepted where a T? is declared and is checked as a T: with type Words = [str], let w: Words? = [] is fine and let w: Words? = [1] reports the element (expected `str`, got `int64`), while let x: int64? = "s" names the declared type (expected `int64?`, got `str`). none is accepted wherever an optional or none is declared, a struct or primitive other than bytes where an interface is, and [] as any array type. A T? isn't accepted where a T is declared; unwrap it first with must x or x? or default. An optional is passed on as it is, so a T? where a U? is declared needs T to be U: like an [Sq] isn't a [Shape], an Sq? or int64? isn't a Shape? even when Sq and int64 implement Shape; rewrap it instead, as in match sq { Some(v) -> v none -> none }. A function value must match a function type exactly, since a function is never adapted: a function taking a struct isn't a func(SomeInterface) -> ..., and one returning int64 isn't a func() -> int64?. Without an annotation, let x = none and let xs = [] are errors, since their type can't be inferred.

Function and method arguments, struct constructor fields and enum payloads are checked the same way (see Argument types), so m.set(5, 1) on a Map[str, int64] is an error. So are element stores (xs[i] = v, m[k] = v, see Indexing) and return values (see Return values).

Parameters are immutable too. A mut parameter is the caller's variable, passed with mut at the call site, and the caller sees what the function assigns to it (see mut parameters):

func bump(anon mut x: int64) -> none {
    x = x + 1
}

mut n = 1
bump(mut n)       // n is 2

A struct's fields are assigned only through a mut name, as an array's elements are; a shared struct's fields through any name that holds it (see Field mutation).

Module-level constants

A let at the top level of a module names a constant. It needs a type, and mut isn't allowed there:

let MAX_BLOCK: int64 = 65535
let SECONDS_PER_DAY: int64 = 24 * 60 * 60
let GREETING: str = "hello, " + "world"
let PRIMES: [int64] = [2, 3, 5, 7]
let DEFAULT_MODE: Mode = Mode.Fast

The value is built only from literals, operators, array literals, enum variants without a payload, and other constants. A call, a constructor, an f-string, a match or anything else is an error (this can't be part of a module-level constant), so a constant never has a side effect, and a constant that refers to itself, directly or through others, is an error (constant `A` refers to itself).

A constant is used by its name. Another module's is import "limits" { MAX_BLOCK } or limits.MAX_BLOCK, like a function's. A local variable or parameter of the same name hides it, as it does a function, and a constant and a function can't share a name in one module. A constant can't be assigned, and neither can its elements (`PRIMES` is a constant and can't be assigned; a module-level `mut` can be).

Each use of an array constant is an array of its own, so changing one changes nothing else: after mut p = PRIMES and p[0] = 1, PRIMES[0] is still 2. A use that can't change the array, indexing it, len of it or a for over it, reads one copy that the program builds the first time and keeps, so a lookup table read in a loop allocates nothing. Indexing an array of arrays still makes a new array, since the element read could be changed. A string can't be changed, so a string constant is built once.

An int64 or bool constant whose value is literals and the operators +, -, *, &, |, ^, << and >> on them, like MAX_BLOCK and SECONDS_PER_DAY above, is worked out when the program is compiled and put in place at each use, and so is a float64 constant that is one literal: reading one costs what the literal would.

Module-level variables

A mut at the top level of a module names a variable that every function of the program shares. Like a constant, it needs a type:

mut calls: int64 = 0
mut seen: Map[str, bool] = Map[str, bool]()
mut log_lines: [str] = []

func remember(anon name: str) -> bool {
    calls += 1
    if seen.contains(name) {
        return false
    }
    seen.set(name, true)
    log_lines += [name]
    return true
}

The value can be any expression, calls included. It is worked out once, the first time the program uses the variable (reads it or assigns it), so a variable nothing uses costs nothing, and the order in which modules are declared or imported doesn't matter. A value that needs its own variable to be worked out first, directly or through a function it calls, stops the program with panic: `calls` is used while its value is being worked out.

Another module reads a variable the way it reads a constant (import "stats" { calls } or stats.calls), but only the declaring module assigns it: `calls` can only be assigned in stats.kod, and only it changes an array, map or struct the variable holds (seen.set(...)). A shared struct the variable holds can be changed through its fields from anywhere, as with any shared struct. A name that starts with _ keeps the variable private to its module. A local of the same name hides it, and a variable, constant or function can't share a name in one module. A constant can't use a variable, since a constant has no side effects (a module-level constant can't use the variable `calls`). A variable or constant that holds a function is called like one: mut on_error: func(str) -> none = log, then on_error("disk full").

Tests run in one program, one after another, so a test sees what the tests before it left in a module-level variable.

Primitive types

Type Description Example
int64 64-bit signed integer 42, -7
float64 64-bit IEEE 754 float, see Floating point 1.5, 2e9
str UTF-8 string "hello"
bool Boolean true, false
none No value (unit type) —

Integer literals

let n: int64 = 42
let m: int64 = -1

Base prefixes for non-decimal forms:

let hex: int64 = 0xff           // 255
let oct: int64 = 0o755          // 493
let bin: int64 = 0b1010         // 10

Decimal literals may use a space as a thousands separator. The grouping is strict — a head of 1-3 digits followed by space-prefixed groups of exactly 3 digits each:

let pop: int64 = 1 000 000      // ok
let bad: int64 = 1 23 456       // error — `23 456` isn't a group of 3, so it's another literal

A literal must fit in int64, in any base: 9223372036854775808 or 0x8000000000000000 is an error at the literal, not a value that wraps around. The one exception is the smallest int64, written as a prefix - and its digits, with or without a space between them: -9223372036854775808 or - 9223372036854775808. In x - 9223372036854775808 the - subtracts, and in -9223372036854775808.to_str() it negates the call, so in both the literal stands alone and is an error; the second suggests (-9223372036854775808).

Arithmetic operators: +, -, *, /, %. Compound assignment += and -= update a variable, field, or array element in place (n -= 3 is n = n - 3). An assignment binds looser than every operator, so ok = a and b assigns a and b. A prefix - negates the whole call, field access, index or ? after it, and binds tighter than any binary operator: -xs[0] is -(xs[0]), -p.get() is -(p.get()), and -a * b is (-a) * b. That includes an unwrap's default, so -x? or 3 is -(x? or 3) and gives -3 for a none. It also makes -n.to_str() the negation of a str, an error whose hint suggests (-n).to_str().

Integer / rounds toward zero and % takes the sign of its left operand, so -7 / 2 is -3 and -7 % 2 is -1, and (a / b) * b + a % b is always a. Dividing by zero, with / or %, panics: panic: integer division by zero, with a backtrace. The one quotient that doesn't fit, the smallest int64 divided by -1, wraps around to the smallest int64, and its remainder is 0.

>> shifts in zeros, so it treats an int64 as 64 bits rather than a signed number, and so do these methods, each a single instruction:

Method Gives
n.leading_zeros() how many zero bits are above the highest one bit; 64 for 0
n.trailing_zeros() how many zero bits are below the lowest one bit; 64 for 0
n.count_ones() how many bits are one; 64 for -1
n.mul_high(m) the top 64 bits of the 128-bit product of n and m as unsigned numbers; n * m is the bottom 64
print(1.leading_zeros())                // 63
print(40.trailing_zeros())              // 3
print(0xff.count_ones())                // 8
print((1 << 62).mul_high(8))            // 2

Boolean literals

let flag: bool = true
let other: bool = false

Logical operators: and, or, not. Comparison: ==, !=, <, <=, >, >=. Comparisons, and/or/not and is always produce a bool, so let ok = a < b is a bool binding and f"{a < b}" prints true or false.

not binds looser than comparisons and is, and tighter than and and or: not a == b is not (a == b), not x is .Red is not (x is .Red), and not a and b is (not a) and b. Its operand must be a bool; test an optional with x is none.

bool and int64 don't mix, and nothing else stands in for a bool. Both operands of and and or must be bool, and so must the condition of an if, a for loop and an assert: test a number with n != 0 and an optional with x is not none. Arithmetic, bitwise and ordering operators don't take bool operands, and ==/!= compare a bool only with another bool, so b == 1, true + 1 and if flags & 1 are errors. Comparisons bind tighter than &, | and ^, so a bit test is written (flags & 1) != 0.

Chained comparisons are supported Python-style: a < b < c is (a < b) and (b < c) with b evaluated once. The operands are evaluated left to right, and a chain stops at the first comparison that is false, so in a < b < f() f isn't called when a < b is false. Any comparison chain works — 0 <= i < len(xs) is the canonical bounds check.

Operators

An operator never converts its operands; both must be of a type it takes, and of the same type:

Operator Operands Result
+ two int64, two float64, two str, two bytes or two arrays of one type the operands' type
- * / two int64 or two float64 the operands' type
% two int64 int64
& \| ^ << >> two int64 int64
< <= > >= two int64, two float64, two str or two bytes bool
== != two int64, two float64, bool, str or bytes, two values of a payload-free enum, an enum value and a unit variant, an optional and none, or a union and a value that goes into it bool
and or two bool bool

So "n = " + 5 is an error (cannot add `str` and `int64`); write "n = " + str(5) or f"n = {5}". s - t on two strings, xs * "2" on an array (an array repeats by an int64: see Repetition), -s on a string, s + b with b: bytes and red < blue on an enum are errors too. += and -= follow the rules of + and -. An index, as in xs[i], s[i] and xs[i] = v, and the bounds of a slice must be int64, so xs["a"] and xs[true] are errors, and so is an int64? index; unwrap it first.

== and != compare str and bytes by content, enums by variant (see Equality) and arrays by their elements (see Comparing). Nothing else has an ==: comparing two structs, interface values or function values is an error, so compare a struct's fields instead, or declare op_eq on it. Comparing values of two different types, like an int64 with a str or values of two different enums, is an error too.

none

none is the unit value. Functions that return nothing are declared -> none:

func say_hi() -> none {
    print("hi")
}

Optional types

Append ? to any type to make it optional:

let x: int64? = none
let y: int64? = 42

The ? goes after the whole type, so [str]? is an optional array and Box[int64]? an optional generic struct. names? or [] is the array, or an empty one when there is none.

Test with is and destructure with Some(binding):

if x is none {
    print("nothing")
}
if y is not none {
    print("got something")
}
match y {
    Some(v) -> print_int(v)
    none -> print("nothing")
}

is not Pat reads as one operator — is negated by the trailing not — and works anywhere is Pat does (expression context and the if … is … form). It's the predicate spelling of "does this not match"; for the if form, the body runs when the pattern does not match.

is and is not bind like comparisons, tighter than and and or, so if ready and x is none reads as ready and (x is none). A pattern that binds a name, like Some(v), only works when the is is the whole if condition: if a and x is Some(v) is an error, since v would be unset when a is false. Some(_) or Some(_v) binds nothing and works anywhere.

Or peel off the Some with let .Some(v) = y else { ... }:

let .Some(v) = y else { return -1 }
// v is in scope and has type int64

An optional of an optional is that optional, since T? is T | none and a union is a set: with type MaybeInt = int64?, MaybeInt? is int64?, and so is T? in a generic function where T is int64?. So none means one thing. A Map[str, int64?]'s get returns none both for a missing key and for a stored none; contains tells them apart. Where the difference matters, an enum that names both cases says it better.

Unwrapping: x? or default and must x

x? or default on a T? value evaluates to T, or to the default when x is none. must x evaluates to T, and stops the program on none with the position of the value, as it stops on a failed T or Error:

let n: int64? = "hello".find("l")
let idx: int64  = n? or -1     // -1 if none
let idx2: int64 = must n       // stops if none

? is always the safe side: it goes before or or . (see Optional chaining), and a bare x? is an error that says to write must x or x? or default. Whatever can stop the program is spelled must. must takes the expression and its ., [...] and (...) steps, so must m.get(k) unwraps what get returns, and indexing the unwrapped value needs parentheses: (must m.get(k))[0].

The default is evaluated lazily (only when the value is none), and its type must match the unwrapped T, unless it's a call that never returns, such as panic(...) or a helper that ends in one (see Return values). It's built as a T: with T an interface, a struct default becomes an interface value, and with T an enum, .Up names T's variant. x? or d on a value that isn't optional is an error. A following or outside the unwrap stays a boolean operator: x? or 1 substitutes 1 for none, but (must x) or some_bool is a boolean-or on the unwrapped value (and a type error unless T is bool).

Operators don't look inside an optional. With n: int64?, n == 3, n < 4 and n + 1 are errors, and so is comparing a bool? such as m.get(key) with true; unwrap first, as in must n == 3 or (n? or 0) + 1. Only == none and != none compare the optional itself.

Optional chaining

On a struct T?, x?.field and x?.method(...) evaluate to an optional of the field or return type, and to none without touching the field when x is none. x?.method(...) works on any T? whose T has methods: n?.to_str() on an int64?, s?.find("l") on a str?, or a method of an interface value. A field or return type that is already optional stays one level deep, so chains read through: with a: A? whose b: B? has n: int64?, a?.b?.n is an int64?. The rest of a chain after ?. runs on the unwrapped value, so x?.name.upper(), x?.items[0] and json.parse(s)?.get("k").as_str() reach past the first step and are none as soon as x is; a ?. is needed again only where a step gives an optional itself, as a?.b?.n does. The chain ends at a ? that isn't followed by ., so x?.name.upper()? or "" defaults the whole chain. x?.method(...) takes arguments like an ordinary method call: arguments it leaves out take the method's defaults, and none of them is evaluated when x is none. A T? doesn't stand in for a T: returning t?.name from a function declared -> str or -> str or Error is an error, so unwrap it first with t?.name? or t?.name? or "", or declare the function -> str?. t?.name = v isn't an assignment; unwrap first. For a shared struct that is if t is Some(u) { u.name = v }; a struct is a value, so change a mut copy and store it back: mut u = must t, u.name = v, t = u.

Arrays

[T] is a resizable array of element type T:

let nums: [int64] = [1, 2, 3]
let names: [str] = ["alice", "bob"]

See Arrays for indexing, slicing, and concatenation.

Structs

Named product types:

type Point = struct {
    x: int64
    y: int64
}

See Structs.

Enums

Tagged unions:

type Shape = enum {
    Circle(radius: int64)
    Rect(w: int64, h: int64)
}

See Enums.

Generics

Type-parametric structs are monomorphised at compile time:

type Pair[A, B] = struct {
    first: A
    second: B
}

let p: Pair[str, int64] = Pair[str, int64](first: "hello", second: 42)

The type arguments of a constructor call pick the instantiation, so let p = Pair[str, int64](first: "hello", second: 42) needs no annotation. A generic struct always needs them: a bare Pair(first: "hello", second: 42) is an error that says to write Pair[A, B](...). A generic struct's method signatures are always checked, but a method body is compiled only for each instantiation, so the body of a struct that nothing instantiates isn't checked. An error in a body is reported once, for the first instantiation that hits it, and names that instantiation, like Pair[str, int64]. A type argument is a name (str, ast.Expr), an array ([str]), an optional of either (int64?, [str]?) or another instantiation (Map[str, Pair[int64, str]]()). Function types (func(int64) -> str) and optional instantiations (Pair[str, int64]?) aren't accepted. Passing the wrong number of type arguments, or type arguments to a struct that isn't generic, is an error, and so is a Type[A, B] that isn't followed by (. The same goes for a generic written as a type: let m: Map = ... is an error that says to write Map[K, V], and Map[str] is one for the missing type argument.

Map[K, V] (in builtins) is the canonical example.

Functions can be generic too, with their type arguments usually inferred from the call: see Generic functions.

Interfaces

Method-based contracts that types can opt into by declaring the right methods. Primitives implement them implicitly via boxing.

interface Printable {
    func to_str(self) -> str
}

func show(anon x: Printable) -> none {
    print(x.to_str())
}

show(42)        // works — int64 implements Printable via primitives/int64.kod
show(true)      // same for bool

A call on an interface value must name one of the interface's methods, with arguments that match its signature; an unknown method is an error. A trailing argument the call leaves out takes the default the interface declares for it (func greet(self, times: int64 = 2) -> str), so give each implementation the same default.

A struct, an enum, int64, str or bool becomes an interface value wherever one is expected (a bytes value or a union can't be one): an annotated let, an argument, a field, an array element, a value stored with m[k] = v, and a return value, including the value of a -> Shape? or -> Shape or Error function.

The type must declare every method of the interface, with the same parameter and return types (labels and defaults may differ). Otherwise using it as the interface is an error at that spot, such as struct `P` doesn't implement interface `Shape`: missing method `area` (enum `E` ... for an enum) or method `area` is `func(int64) -> int64`, not `func() -> int64`. throw counts too, since it makes its value an Error.

Provided methods

A method in an interface can have a body. It is provided: every type that implements the interface has it, without declaring it:

interface Reader {
    func read(self, anon max: int64) -> bytes or Error

    // Read until the end of the stream.
    func read_all(self) -> bytes or Error {
        mut out: bytes = kod_str_to_bytes("")
        for true {
            let chunk = try self.read(4096)
            if len(chunk) == 0 {
                return out
            }
            out += chunk
        }
    }
}

let f = try posix.open_read("data.bin")     // a posix.Fd, which has `read`
let data = try f.read_all()                  // the Reader's `read_all`
  • In the body, self is the interface: it can call the interface's methods, provided or not, be passed where the interface is expected, and be downcast with is. It has no fields, and the implementing type's other methods aren't reachable through it.
  • Only the methods without a body are required: a type with read is a Reader, and has read_all too.
  • A type that declares a method of the same name overrides it; the signature must match the interface's, and calls through the interface run the type's own method.
  • On a value of the type itself, as f.read_all() above, a method the type doesn't declare is looked up among the provided methods of the interfaces it implements that the calling module can see: its own and those of the modules it imports, directly or not. When more than one of them provides a method of that name, the call is an error that names them; convert the value to the one you mean, as in let r: Reader = f.
  • The body runs once for all types: its calls on self go through the method table, as for any interface value.

An interface value converts to another interface that declares only methods the first one has, with the same parameter and return types, in any order. It goes wherever a struct would (an argument, an annotated let, a field, a return value), and a downcast still works on the result:

interface Reader {
    func read(self) -> int64
}
interface ReadCloser {
    func close(self) -> none
    func read(self) -> int64
}

func drain(anon r: Reader) -> int64 {
    return r.read()
}

let rc: ReadCloser = File(n: 7)
drain(rc)                      // 7
let r: Reader = rc
if r is File(f) {              // still the File
    print_int(f.n)
}

The second interface's provided methods don't have to be in the first. For each one the first lacks, the converted value gets its type's own method of that name, when the type declares one with the same parameter and return types, as it would have been boxed straight into the second interface; else the body in the second interface. (An instance of a generic type is the one exception: it gets the second interface's body, since only the methods it uses are compiled.) A method the first interface has keeps what that table holds, except that a provided body the value got from an earlier conversion is looked up again the same way. A method the first interface provides can't stand in for one the second requires: that converts nothing, and is the usual expected `B`, got `A` error.

Converting builds the new interface's method table when it runs, so it costs a small allocation. Arrays and optionals of interface values don't convert element by element: a [ReadCloser] is not a [Reader].

Union types

A | B holds a value of any one of its member types. A match or is says which one it holds:

type Id = int64 | str

func show(anon id: Id) -> str {
    match id {
        int64(n) -> return f"#{n}"
        str(s) -> return s
    }
}

let id: Id = 42
if id is str(s) {
    print(s)
}

A member can be any type: a primitive, a struct, an enum, an interface, an array, a generic instance or a function type. See Pattern matching for the patterns.

A union is a set, so order, repeats and nesting don't matter. int64 | str and str | int64 are one type, in every module, and with type Id = int64 | str, Id | bool is int64 | str | bool. A union with only one member left is that member.

none in a union makes it optional: T | none is exactly T?, and A | B | none is the optional of A | B, which can also be written (A | B)?. An optional member counts the same way, so A? | B is that type too. Its arms sit side by side, with no Some: A(a), B(b) and none.

In a type, | binds tighter than or, so int64 | str or Error is a fallible int64 | str. A function type's return type takes every member after the ->, so func() -> int64 | str returns a union. To put such a function in a union, put it in parentheses: (func() -> int64) | str. Parentheses group any type this way, and a ? after them makes the group optional.

A value goes into a union by being written where the union is declared, as a T goes into a T?. It goes to the member of its own type. Without one, a struct, enum or primitive goes to an interface member it implements, and implementing two of them is an error, since it could be either. An enum's .Variant goes to the one enum member that declares that variant, and [] to the one array member. A value with no member reports the mismatch (expected `int64 | str`, got `bool`).

A union goes where a union with all of its members is declared: an A | B is accepted as an A | B | C, and holds the same member there. Only the value itself widens. An [A | B] isn't an [A | B | C], as an [Sq] isn't a [Shape], and an (A | B)? isn't an (A | B | C)?; match those and put each member in instead. Nor is a union accepted where one of its members is declared.

A union prints as the member it holds, with print(x), f"{x}" or str(x), when every member can be printed. == and != compare two unions, or a union and a value that goes into it (x == 3, x == "a", x == .Red): they're equal when they hold the same member and those members are ==. Every member needs a == of its own, so a union with a struct member that doesn't declare op_eq, or an array member, can't be compared. A union widens for == as it does elsewhere, so an A | B compares with an A | B | C. A union whose members can all be hashed (int64, str, bytes, bool, enums without payloads) can be hashed and be a Map key: Map[int64 | str, V] (see hash). Otherwise a union has no fields, methods or operators of its own.

A union can mention a type parameter, in a generic function, struct or enum:

func label[T](anon x: T | str) -> str {
    match x {
        str(s) -> return f"text {s}"
        T(t) -> return f"other {t}"
    }
}

print(label(3))                  // other 3
print(label[int64]("a"))         // text a

Each instance is the union of what the parameters stand for, as a set. With T = int64 the parameter above is an int64 | str; with T = str it is just str, so label[str]("a") takes the first arm that matches, text a; and with T = int64 | bool it is bool | int64 | str, where T(t) matches an int64 or a bool and binds it as an int64 | bool (see type patterns). A call infers T from an argument for such a parameter: T is the argument's members that the parameter doesn't list, so label(3) is label[int64], and an argument of type int64 | str makes it int64 too. When that leaves nothing, as in label("a"), the type arguments have to be written.

A union alias can't refer to itself, so a recursive type such as a JSON value is still an enum.

Type aliases

type Name = T gives an existing type a second name. An alias is transparent: a value of the alias type is a value of T, with all of its methods, fields and operators. The target can be any type, including one declared further down the module or one from the module's own imports (type Num2 = dep.Num, usable as mid.Num2 from a module that imports only mid, or type Num = dep.Num to pass the name on as mid.Num). Each module's aliases are its own: two modules may declare aliases of one name whether or not they stand for the same type, and a module's alias may take the name of a struct, enum or interface another module declares (see Modules):

type Name = str
type Ids = [int64]
type MaybeNode = Node?
type Callback = func(int64) -> int64
type StrMap = Map[str, str]
type Outcome = int64 or Error
type Key = int64 | str

type Node = struct {
    label: str
}

let n: Name = "kod"
print_int(n.char_count())    // 3

An alias of T or Error works wherever T or Error does, including as the return type of a function or of main, so throw, try and must behave the same through it. That holds for an imported alias too, written dep.Outcome or listed in import "./dep" { Outcome }.

An alias whose target names an unknown type is an error, and so is one that refers back to itself through other aliases (type A = B with type B = A). So is a target that gets a generic's type arguments wrong, such as type B = Map[str], type P = Pair or type D = [Box[int64]] for a Box that isn't generic. Each of these is reported once, at the alias.

Fallible types: T or Error

A function declared -> T or Error returns a Result cell — either an Ok(T) or an Err(Error). Use try to propagate, must to panic, or pattern-match the result directly.

try and must take a T or Error value, and try only works inside a function that returns T or Error itself; anything else is an error. must also takes a T? (see Unwrapping). Either can appear anywhere a value can, as in out += [try parse(s)] or xs[try first(xs)..]; on an Err, try returns from the function there. An explicit Result[T, E] with an E other than Error doesn't count, since its error isn't an Error to report or pass on; match it instead.

A call whose result is a T or Error can't be used as a statement on its own, because that would drop an error without a word:

file.close()               // error: the `none or Error` result of this call is dropped
try file.close()           // propagate it
must file.close()          // panic on it
let _ = file.close()       // ignore it, on purpose

try r or must r on its own line, with r a plain name, narrows r for the rest of the block: it is let r = try r, so r is the T from there on. must o narrows a T? the same way. Like the other narrowing in Narrowing, this doesn't apply when the rest of the block assigns to r, and after the block r has its declared type again:

func size_plus(anon path: str) -> int64 or Error {
    let size = file_size(path)
    try size                    // size is an int64 from here on
    return size + 1
}

let _ = expr evaluates expr, whatever its type, and keeps nothing: it binds no name, so it can be written any number of times in a block, and _ can't be read afterwards. It is for fallible calls whose failure doesn't matter, like closing a connection that already failed. Any other value can be dropped by calling it as a statement, as before.

A none or Error function that ends without a return, or with a bare return, returns Ok(none), as return none does.

A T goes where a T or Error is declared as its Ok, the way a T goes into a T?. That holds in a return, an annotated let, an assignment, an argument, a struct field, an array element, and an arm of a match whose value goes to one of them:

let r: int64 or Error = 3                // Ok(3)
let rs: [int64 or Error] = [1, read_size("a.txt")]

A value that is already a T or Error goes as it is, and a nested result wraps as often as it takes: let r: (int64 or Error) or Error = 3 is Ok(Ok(3)). Without the parentheses, int64 or Error or Error is just int64 or Error. A failure is never implicit. An Error where an int64 or Error is declared is an error that says to throw it, or to write .Err(error: e). Only when T itself takes the value, as with Error or Error, is it the Ok. .Ok(value: 3) still works, and so does .Err(error: e).

Error is the only type that can follow or: -> int64 or IoError is a parse error. Throw a struct or enum that implements Error instead, and recover it with a downcast (see below). throw takes an Error value, so throwing an array, an optional, or an enum without a to_str is an error, such as enum `Color` doesn't implement interface `Error`: missing method `to_str`.

type IoError = struct {
    message: str
    func to_str(self) -> str { return self.message }
}

func read_size(anon path: str) -> int64 or Error {
    throw IoError(message: f"file not found: {path}")
}

func main() -> int64 {
    let n: int64 = must read_size("missing.txt")  // panics on Err
    return n
}

To inspect a result instead of propagating or panicking, pattern-match it with Ok / Err (the two-armed analog of Some / none). Ok's binding has the result's value type; Err's is the Error interface (on an explicit Result[T, E], it's an E):

match read_size("missing.txt") {
    Ok(n)  -> print_int(n)
    Err(e) -> print(e.to_str())
}

A type pattern on a result tests what it holds when it succeeded, so a result matches like the value it carries. Error(e) is another way to write Err(e):

match parse(s) {                         // -> int64 | str or Error
    int64(n) -> use(n)
    str(t) -> show(t)
    Error(e) -> print(e.to_str())
}

T(t) matches an Ok whose value matches T(t) as a pattern on the success type: a member of a union, a union or optional of several, the success type itself (any Ok), a downcast when it is an interface, and none when it is optional. A type pattern never looks inside the error, even for a type that implements Error: NotFound(nf) on an int64 or Error is an error that points at Err(NotFound(nf)), which downcasts it.

The same patterns work with if … is and the bare is operator, which is handy in tests:

let r = read_size("missing.txt")
assert r is Err(_)              // it failed
if r is Err(e) { print(e.to_str()) }

A default for a failure: ? on a result

r? or default, r?.field and r?.method() work on a T or Error as they do on a T?. Each takes the success value, and on a failure gives up the error right there, where the code says so:

let n = read_size("a.txt")? or 0
let name = load(path)?.name? or "?"

r?.field and r?.method() give an optional, none for a failure, so a chain ends in ? or default as an optional's does. When T is itself optional, a failure and a none look the same, as for a T??. To stop on a failure, write must r, which prints the error's message.

Recovering the concrete error type

Err(e) binds e as the Error interface. To get back the concrete error struct, downcast with is StructType(binding) — a general interface downcast that tests the boxed type and, on a match, binds the typed value:

match read_size(path) {
    Ok(n)  -> use(n)
    Err(e) ->
        if e is NotFound(nf) {
            print(f"missing: {nf.path}")
        } else {
            print(e.to_str())
        }
}

It works in match, if … is, and the bare is operator (a match on an interface needs an else, since its set of implementors isn't enumerable). A struct that doesn't implement the interface can never be in one, so naming it is an error: `Point` doesn't implement `Shape`, so a `Shape` is never a `Point`. x is T and a T(b) pattern hold only for a value of exactly that declaration, or that generic instance, whichever module boxed it, so an error struct that an imported function throws matches its type in the caller. T may be an alias of a struct or of a generic instance (type IntBox = Box[int64]), written dep.T through another module. Naming a generic type itself (is Box) is an error: `Box` is generic; downcast to one of its instances through a type alias such as `type IntBox = Box[int64]`. The pattern names such a struct through its module (e is errs.NotFound(nf), which needs errs to declare NotFound) or, when it is imported as an item, by its own name (e is NotFound(nf)). Either way it binds one name, the struct, whose fields are read from it. A local or parameter named like the module hides it, so errs.NotFound(nf) after let errs = 3 is an error.