Skip to content
RESONON

Assertions

An assertion is a claim about your program that must hold. You write down something you believe is always true; if it ever isn’t, the script stops immediately and tells you where. It’s the fastest way to turn a silent wrong-note bug into a loud, located error — and a handy way to prove to yourself that a generator really is deterministic.

assert

Section titled “assert”

Write assert followed by a condition. If the condition is true, nothing happens and the script carries on. If it’s false, the script aborts with an assertion error.

assert 1 + 1 == 2;
print("reached — the assertion held");

The condition must be an actual Boolean. A non-Boolean is a type error, not a falsy value — the same rule if and match guards follow (see Truthiness). So compare, don’t just name a value:

assert 1;            // type error — 1 is a Number, not a Boolean
assert count > 0;    // ok — > yields a Boolean
assert x != NUL;     // ok — != yields a Boolean

A failure message

Section titled “A failure message”

Add a comma and a second expression to say what went wrong. It can be any value; it’s formatted into the error just like print() would show it.

let gain = 0.8;
assert gain >= 0.0 && gain <= 1.0, "gain must be in [0, 1]";
print("gain ok");

When the condition is false, the message is what you see:

assert 2 > 3, "two is not greater than three";
// → Assertion failed: two is not greater than three

Without a message you still get a located error, just a terser one — so a message is worth it whenever the reason wouldn’t be obvious from the line alone.

When to reach for it

Section titled “When to reach for it”

Preconditions. Check a function’s inputs at the top, so a bad call fails at the call site instead of somewhere deep inside:

fn set_tempo(bpm) {
    assert bpm > 0, "tempo must be positive";
    return bpm;
}
print(set_tempo(120));

Proving determinism. Resonon’s generators are seed-driven and reproducible (Generative Patterns). An assertion turns that promise into a check you can run:

use "std/random" { rand };
assert rand(7) == rand(7), "same seed must give the same value";
print("deterministic");

Use assertions for things you expect to always hold. For ordinary run-time conditions that can legitimately go either way, use if instead — an assertion is a claim, not a branch.

Next Steps

Section titled “Next Steps”