Wado

Control Flow

This chapter covers what decides which code runs next: conditionals, loops, break and continue, labeled blocks, match and matches, branch hints, and error handling. The patterns these statements take apart are in Patterns.

Conditional Statements

The condition of an if, a while, or a C-style for is a bool or a let chain, under the same rules in all three. No other type converts to a bool.

let x = 7;
let mut sign = "";
if x < 0 {
    sign = "negative";
} else if x == 0 {
    sign = "zero";
} else {
    sign = "positive";
}
assert sign == "positive";

If Expression

let x = -3;
let abs = if x < 0 { -x } else { x };
assert abs == 3;

let score = 85;
let grade = if score >= 90 { "A" } else if score >= 80 { "B" } else { "C" };
assert grade == "B";

If Let Pattern Matching

let opt: Option<i32> = Option::<i32>::Some(42);
let mut got = 0;
if let Some(x) = opt {
    got = x;
} else {
    got = -1;
}
assert got == 42;

Let Chains

A condition may be a let chain, as in Rust. A let chain is a list of operands joined by &&. Each operand is either a bool expression or let PATTERN = EXPR, and at least one is a let. if let and while let are the chains with one operand.

The operands run left to right. A bool that is false, or a pattern that does not match, stops the chain: the operands after it do not run, if takes its else, and the loop ends. The condition holds when every operand holds.

A let binds its names for the operands after it and for the body: the if's then-block, or the loop body and a for's update. The else block and the operands before the let do not see them. A later let may bind a name again, and the later binding holds from there on.

let a: Option<i32> = Option::Some(4);
let b: Option<i32> = Option::Some(6);
let mut got = 0;
if let Some(x) = a && x % 2 == 0 && let Some(y) = b && y > x {
    got = x + y;            // `x` and `y` are in scope here
} else {
    got = -1;               // neither is in scope here
}
assert got == 10;

// A later `let` may rebind a name an earlier one bound.
if let Some(x) = a && let Some(x) = Option::Some(x * 10) {
    got = x;
}
assert got == 40;

A chain may start with a bool. Here the failing bool keeps the let from calling next a third time:

let items: List<i32> = [1, 2, 3, 4];
let mut iter = items.into_iter();

let mut taken: List<i32> = [];
while taken.len() < 2 && let Some(x) = iter.next() {
    taken.push(x);
}
assert taken == [1, 2];
assert iter.next() == Option::Some(3);   // the failing `bool` skipped the `let`

Each operand, and each let's scrutinee, is an expression with no top-level && or ||. A top-level && always separates two operands, so let true = a && b is the chain of let true = a and b. A top-level || is a compile error. An operand that needs either operator puts it in parentheses, as in let Some(x) = o && (a || b). An operator looser than ||, such as a range, takes parentheses the same way.

if let Some(x) = o && a || x > 0 {

let PATTERN = EXPR is not an expression. It appears only as an operand of a chain, never inside parentheses or anywhere else.

Let Else

let PATTERN = EXPR else { ... }; binds a refutable pattern whose bindings escape into the enclosing scope. On a match they cover the rest of the block. Otherwise the else block runs, and it must diverge (return, break, continue, panic, …). The else block does not see the bindings.

fn parse_port(s: String) -> i32 {
    let Ok(port) = i32::from_str(&s) else {
        return -1;
    };
    return port;                // `port` is in scope here
}

test {
    assert parse_port("8080") == 8080;
    assert parse_port("http") == -1;
}

An irrefutable pattern is an error, since its else could never run. Write a plain let instead.

While Loop

let mut i = 0;
let mut sum = 0;
while i < 10 {
    sum += i;
    i = i + 1;
}
assert sum == 45;

While Let Pattern Matching

while let allows iterating while a pattern matches:

let items: List<i32> = [1, 2, 3];
let mut iter = items.into_iter();

let mut seen: List<i32> = [];
while let Some(x) = iter.next() {
    seen.push(x);
}
assert seen == [1, 2, 3];

The loop runs while the pattern matches, and ends the first time it does not.

For Loop

C-style for loop with initialization, condition, and update. Parentheses are optional:

let mut sum = 0;
for let mut i = 0; i < 10; i = i + 1 {
    sum += i;
}
assert sum == 45;

// With parentheses (also valid)
for (let mut i = 0; i < 10; i = i + 1) {
    sum += i;
}
assert sum == 90;

// All parts are optional
let mut n = 0;
for ;; {
    n += 1;
    if n == 3 { break; }
}
assert n == 3;

Semantics

for init; cond; update { body } runs init once. Each iteration then checks cond, runs body if it holds, and runs update. continue ends the body and still runs update, as in C.

Each iteration has its own copy of the bindings init declares, as ECMA-262's for (let …) does. Before update runs, the next iteration's bindings are created holding the current values, and update and the next cond act on them. So a closure or a reference taken in one iteration keeps that iteration's binding, and later iterations do not change it:

let mut fs: List<fn() -> i32> = [];
for let mut i = 0; i < 3; i += 1 {
    fs.push(|| i);
}
assert fs[0]() == 0 && fs[1]() == 1 && fs[2]() == 2;   // not 3, 3 and 3

For with a Let Chain

The condition may be a let chain, as in if and while. The loop ends when the chain fails. The chain's bindings are in scope in the body and in the update, which runs after each iteration:

let items: List<i32> = [10, 20, 30];
let mut iter = items.into_iter();

let mut sum = 0;
for ; let Some(x) = iter.next(); {
    sum += x;
}
assert sum == 60;

// With update expression
let mut again = items.into_iter();
let mut count = 0;
for ; let Some(x) = again.next(); count += 1 {
    assert x == items[count];
}
assert count == 3;
// `i < items.len()` failing keeps `items[i]` from running out of bounds.
let mut taken: List<i32> = [];
for let mut i = 0; i < items.len() && let x = items[i] && x < 30; i += 1 {
    taken.push(x);
}
assert taken == [10, 20];

For-Of Loop

for-of walks any value whose type implements IntoIterator:

let numbers: List<i32> = [1, 2, 3, 4, 5];
let mut sum = 0;
for let n of numbers {
    sum += n;
}
assert sum == 15;

// With mutable binding
for let mut item of numbers {
    item = item * 2;  // Can modify the local binding
    sum += item;
}
assert sum == 45 && numbers[0] == 1;

// Custom types that implement IntoIterator also work
let my_collection = Countdown { n: 3 };
let mut order: List<i32> = [];
for let x of my_collection {
    order.push(x);
}
assert order == [3, 2, 1];

Semantics

for let item of collection { body } calls collection.into_iter() once, before the first iteration. Each iteration then calls next() on the result, binds the element to item and runs the body. The loop ends when next() returns None.

An affine operand whose type implements the prelude trait ForOf is walked through it instead. The loop passes the operand by value to ForOf::start once, then calls next() on the state it returns. So the loop owns what it walks: the operand moves into the loop, each element moves into the binding, and leaving the loop early drops the elements it did not reach. List<T> and Array<T> implement ForOf for an affine T, and so does every affine Iterator, which is its own state. for let x of &xs and for let x of &mut xs walk an affine list by reference and leave it with its owner.

The binding is a copy of each element (Value Semantics), so changing it does not change the collection. for let x of &xs and for let x of &mut xs bind references instead, as iteration by reference states. Each iteration binds it anew, so a closure or a reference taken in one iteration keeps that iteration's element.

Iterating a List reads the list's own storage, so a body that shrinks the list it walks breaks the contract a shrinking list puts on its views. The walk covers the elements the list held when it began: an element the body appends is not visited.

The binding must match every element, as a let pattern must (see Patterns That Cannot Fail). A pattern that can fail (for let Some(x) of xs, a narrowing type pattern) is a compile error. Match on the element in the body instead.

Tuple for-of (compile-time expansion)

When the iterable is a tuple, the body runs once per element, and each run types the binding as that element's type. So one loop walks elements of different types, and each call in the body dispatches on its element's type.

let t = [42, "hello", true];
let mut out = "";
for let v of t {
    out.push_str(`${v} `);  // expanded to three blocks, each with the correct type
}
assert out == "42 hello true ";

break and continue are errors inside a tuple for-of body, since the runs are not iterations of one loop.

In a generic body, a walk over a pack ([..T]) types its binding as the pack's element, which is rigid, as a type parameter is. Each walk binds an element of its own. Two nested walks over one pack bind two element types. They are distinct even though the walks share the pack, since over [1, "a"] one run pairs an i32 with a String.

.enumerate() binds the index beside the element: for let [i, v] of t.enumerate(). The index is a compile-time constant, so it is the one non-literal a tuple accepts as a subscript (t[i]), for reads and writes alike. A mut index can change, so it is not a subscript.

Tuple comprehension

Wrapping the same walk in [...] collects one result element per source element. The braces hold a single expression, the element's value, since every position of the result tuple has one.

impl<..T: Doubled> Doubled for [..T] {
    fn doubled(&self) -> [..T] {
        return [for let v of *self { v.doubled() }];
    }
}

test {
    assert [1, "ab"].doubled() == [2, "abab"];
}

The .enumerate() form works here too: [for let [i, v] of t.enumerate() { ... }].

The source must be a variadic tuple ([..T]). A concrete tuple cannot be walked this way.

Infinite Loop

let mut n = 0;
loop {
    // runs forever until break
    n += 1;
    if n == 5 {
        break;
    }
}
assert n == 5;

Break and Continue

break exits the innermost enclosing loop. continue skips to the next iteration.

// break example
let mut i = 0;
while i < 100 {
    if i == 10 {
        break;  // exit the loop
    }
    i = i + 1;
}
assert i == 10;

// continue example
let mut kept: List<i32> = [];
for let mut j = 0; j < 10; j = j + 1 {
    if j == 5 {
        continue;  // skip 5
    }
    kept.push(j);
}
assert kept.len() == 9 && kept[5] == 6;

Both work with while, for, and loop, and are errors outside a loop. A loop carries no label, and continue never takes one. break LABEL is a different statement: it leaves an enclosing labeled block, and is how to leave more than the innermost loop. A closure body starts its own loop scope, so a loop around a closure binds nothing written inside it.

Labeled Blocks

A labeled block is a named block that break LABEL leaves from anywhere inside it. It is Wado's only non-local jump, and it replaces loop labels, labeled continue, and goto. It is also the block form that carries a value.

Syntax

LABEL: { ... }, in statement or expression position.

The label is an identifier followed by a colon. break LABEL; leaves the block, and break LABEL: expr; leaves it with a value. () is a value like any other, so break LABEL: () says what break LABEL says, and break () says what break says. Nested blocks may reuse a label, and a break targets the innermost block with that label. The block opens a new scope, and a name declared inside may shadow an outer one.

The label is required because { field: value } on its own could be a block or a struct literal. An unlabeled { ... } block is a parse error.

Escaping and Early Exit

break LABEL inside a loop nest leaves all of it at once, and the block's tail is the path no break took. Inside a block, break LABEL skips the rest, so a chain of guards stays flat instead of nesting one inside the next. A break may also leave an effect handler's do block (see Handler Scope).

let grid: List<List<i32>> = [[1, 2], [3, 4]];
let needle = 3;
let mut hit = [0, 0];
search: {
    for let r of 0..<grid.len() {
        for let c of 0..<grid[r].len() {
            if grid[r][c] == needle {
                hit = [r, c];
                break search;   // leaves both loops
            }
        }
    }
    hit = [-1, -1];             // reached only when no break was taken
}
assert hit == [1, 0];

As an Expression

A labeled block used as a value yields two ways: through break LABEL: expr, and through its trailing statement on the path that reaches the end. Both are branches, so every path must agree on one type. They unify against the type expected where the block sits, so a literal coerces to that rather than to its own default. Where nothing is expected, a numeric literal takes the type a sibling branch fixes, as an if's branches do. Any expression position takes one, not only the right-hand side of a let.

let items: List<Entry> = [{ key: "a", value: 1 }, { key: "b", value: 2 }];
let key = "b";
let found = search: {
    for let item of items {
        if item.key == key {
            break search: item.value;
        }
    }
    -1  // the value when no break is taken
};
assert found == 2;

A trailing statement that is not a value yields (). A block whose branches all yield () has the type (), and one mixing () with a value is the same type error as any other disagreement.

A path that cannot reach the end is no branch at all. When the trailing statement is a loop that only break LABEL leaves, nothing reaches the tail, so the breaks alone type the block. This is how a loop computes a value:

let mut n = 0;
let found = scan: {
    loop {
        n += 1;
        if n * n > 50 { break scan: n; }
    }
};
assert found == 8;

Jumps Stay Inside a Detached Expression

Some expressions run apart from the code written around them: a default value of a parameter or a field runs at each use, a global initializer runs before the first read, an associated constant's value runs where it is read, and a contract clause runs at each call. A jump in one of them must land inside it. return, resume, task return and ? are compile errors there, and so is a break or continue that no loop or labeled block inside the expression binds. Otherwise the jump would leave whatever surrounds the use: the caller, a loop around the call, or no function at all. A closure written in such an expression is a function of its own, so its return is allowed.

fn f(x: i32 = pick: { if builtin::black_box(true) { continue; } 1 }) -> i32 {
    return x;
}

Match Expression

A match tests its scrutinee against each arm's pattern in order and runs the first arm that matches. Its arms must be exhaustive. A match produces a value, or stands as a statement:

// Match expression (produces a value)
let result = match opt {
    Some(x) => x * 2,
    None => 0,
};
assert result == 42;

// Match with custom variants
let area = match shape {
    Circle(r) => 3.14159 * r * r,
    Rectangle([w, h]) => w * h,
    Point => 0.0,
};
assert area == 6.0;

// Match statement (no value produced)
match command {
    Start => engine.start(),
    Stop => engine.stop(),
}
assert engine.running;

Matches Operator

The infix matches operator answers whether a value matches a pattern, as a bool:

// Basic usage
let is_some = opt matches { Some(_) };
let is_circle = shape matches { Circle(_) };
assert is_some && is_circle;

// With guard
let is_large = shape matches { Circle(r) && r > 10.0 };
assert !is_large;

// In conditions
let mut has_value = false;
if opt matches { Some(_) } {
    has_value = true;
}
assert has_value;

Scope

Pattern bindings are scoped to the guard only and do not escape, so x is not in scope after the pattern:

if opt matches { Some(x) } && x > 0 { }

Use a guard inside the pattern instead:

assert opt matches { Some(x) && x > 0 };

Branch Hints

builtin::cold_path() marks the path that contains it as rarely run, so the other side of its branch is the likely one. It does not change what the program computes.

That path is every point each run through which passes the marker. It takes what follows the marker in its block, and what precedes it back to the last statement that can leave the block first, by a return, a break, a continue or a ?.

It is a statement rather than a condition wrapper, so it works anywhere a branch body does. That includes an if let or match arm, where no boolean condition is available:

impl Buffer {
    // Error/abort guard: the taken branch is cold.
    fn get(&self, i: i32) -> i32 {
        if i >= self.len {
            builtin::cold_path();
            panic("index out of bounds");
        }
        return self.data[i];
    }
}

// `match` arm with no boolean condition.
fn run(command: Command) -> i32 {
    return match command {
        Command::Run => execute(),
        Command::Crash => {
            builtin::cold_path();
            panic("crashed");
        },
    };
}

test {
    let b = Buffer { data: [1, 2], len: 2 };
    assert b.get(1) == 2 && run(Command::Run) == 1;
}

Placed on the fall-through after a guard whose taken branch diverges, it hints that the guard is likely taken:

impl Cache {
    fn lookup(&self, key: String) -> i32 {
        if let Some(v) = self.fast_path(key) {
            return v;
        }
        builtin::cold_path(); // the slow path below is rarely reached
        return self.slow_path(key);
    }
}

test {
    let cache = Cache { hot: "a" };
    assert cache.lookup("a") == 1 && cache.lookup("bc") == 3;
}

A profile may override the marker (Markers).

Optimization Barrier

builtin::black_box(value) returns value unchanged but never as a compile-time constant, so the compiler does not fold away a computation reading it. Use it to keep a test or benchmark measuring the work it names:

test "sign extension folds the redundant mask" {
    assert to_i8(builtin::black_box(300)) == 44;
}

Without it, to_i8(300) folds to 44 and the test no longer reaches to_i8.

The barrier binds the Wado compiler only. The Wasm engine that runs the program is still free to fold the value.

Error Handling

An error either traps, which ends the program, or is a value the caller handles.

Unrecoverable Errors (Traps)

A trap ends the program on a fatal error. Nothing recovers from it.

Two prelude functions trap on purpose:

They differ in what reaching them means. panic and assert check a contract: a caller that breaks it reaches them, so a test may too. unreachable() claims that no input reaches it, not even one that breaks a contract. Reaching it is a bug in the code around it, and test coverage plans no region that leads only to the call.

#[expect_trap]
test "panic logs the message to stderr, then traps" {
    panic("Fatal error");
}

#[expect_trap]
test "unreachable traps" {
    unreachable();
}

#[expect_trap]
test "a failed assert traps" {
    let condition = false;
    assert condition;
}

Recoverable Errors (Result Type)

A function that can fail returns a Result, and its caller decides what an Err means:

variant ConfigError {
    Io(FsError),
    Parse(ParseIntError),
}

impl From<ParseIntError> for ConfigError;

fn parse_config(text: String) -> Result<Config, ParseIntError> {
    return Ok(Config { port: i32::from_str(text.trim())? });
}

fn read_config(path: String) -> Result<Config, ConfigError> with Preopens {
    let content = fs::read_to_string(path)
        .map_err(|e| ConfigError::Io(e))?;
    let config = parse_config(content)?;
    return Ok(config);
}

test {
    // Handle with pattern matching
    let message = match read_config("missing.toml") {
        Ok(config) => `port ${config.port}`,
        Err(Io(e)) => `cannot read: ${e}`,
        Err(Parse(e)) => `bad port: ${e}`,
    };
    assert message.starts_with("cannot read");
}

Error Propagation

The postfix ? operator unwraps a Result or an Option. Where there is nothing to unwrap, it returns from the enclosing function:

The function's error type must implement From of the error ? meets, as Conversions Without an Impl counts it. A ? it does not is an error, whether or not anything calls the function:

fn unreached() -> Result<i32, String> {
    let v = fails()?;
    return Ok(v);
}

? on a Result needs a function that returns a Result, and ? on an Option one that returns an Option. Any other pairing is an error:

fn outer() -> Result<i32, String> {
    let x = inner()?;
    return Result::<i32, String>::Ok(x);
}

Inside a closure, ? returns from the closure (Closures).

The early return is marked as rarely run, as builtin::cold_path() marks a path. A profile may override the mark (Markers).

Rationale: WEP: Conversion Traits.