Error Handling
Control Flow introduced try and catch. This page covers what you can throw, what Stof's own errors look like, and how errors reach your app.
Throw Anything
throw takes any value. A string is the simplest. An object carries structure, which is useful when the code that catches it needs to decide what to do:
fn charge(amount: float) {
if (amount > 500) throw(new { code: 402, reason: 'over the card limit' });
}
#[main]
fn main() {
try {
self.charge(900);
} catch (error: obj) {
pln(`${error.code}: ${error.reason}`);
}
}Catch by Type
catch (e: type) catches errors of that type. A union catches more than one, and a plain catch (or catch (e)) catches everything:
#[main]
fn main() {
try { throw(404); }
catch (code: int | str) { pln(`caught ${code}`); }
try { throw('timeout'); }
catch { pln('caught something'); }
}Stof's Own Errors
When Stof itself raises an error, like assigning to a const or calling a function that doesn't exist, the value you catch is a short error code:
const plan: 'pro'
fn total(units: int) -> float { units * 2 }
#[main]
fn main() {
try { self.plan = 'free'; }
catch (e: str) { pln(e); } // AssignConst
try { self.refund(); }
catch (e: str) { pln(e); } // FuncDne: no such function
try { self.total(); }
catch (e: str) { pln(e); } // FuncArgs: wrong arguments
}Match on these codes, not on the readable message: the codes stay the same, while messages may get better over time. The readable message is what your app and the CLI show (below).
Propagation
An error that isn't caught moves up through each function that called the one that threw it, until something catches it. If nothing does, the call fails:
fn load() {
throw('file not found');
}
fn start() {
self.load();
}
#[main]
fn main() {
try {
self.start();
} catch (message: str) {
pln(`start failed: ${message}`);
}
}Rethrowing
Catch an error, add to it, and throw again:
fn load_plan() {
try {
throw('missing price');
} catch (message: str) {
throw(`plan 'pro': ${message}`);
}
}
#[main]
fn main() {
try { self.load_plan(); }
catch (message: str) { pln(message); }
}Errors in Your App
An error that isn't caught inside the document makes the app's call or run fail with a readable message and the Stof call stack:
cannot multiply null: the left value is null or missing (use ?? to give a default)
at root.total (pricing.stof:4:5)
at root.main (pricing.stof:9:5)
The CLI shows the failing line too. Messages are written to be understood by people and by models, so when a model wrote the document, give the error back to it and ask for a fix. See Using Stof in Your App.
A function that throws doesn't undo what it already did, so changes made before the error stay in the document. Next, The Document Graph.