throw(3tcl)

💥 throw — generate a machine-readable error 💥

okay bestie, buckle up, we're in the throw page of the Tcl Built-In Commands manual and honestly? this one is a whole mood. it's giving "i am going to ruin this evaluation's entire day, on purpose, with structure." 💅

✨ SYNOPSIS ✨

throw type message

two args. that's it. that's the whole vibe. 🎀

🦋 DESCRIPTION 🦋

so like, this command causes the current evaluation to be unwound with an error. fr fr, you're not asking nicely — you're throwing. 💀

the error that gets created is described by the type and message arguments, and no cap, these two are doing very different jobs:

• type — this one must contain a list of words describing the error, in a form that is machine-readable (and which will form the error-code part of the result dictionary). so it's the nerdy one. it's the one the computer reads. 🤖
• message — this one should contain text that is intended for display to a human being. so it's the pretty one. it's the one your friend reads at 2am and goes "oh no bestie". 😭

then the stack gets unwound until the error is trapped by a suitable catch or try command. like, somebody's gotta catch it, or it just keeps going. 👑

and if nobody catches it:

• if it reaches the event loop without being trapped, it will be reported through the bgerror mechanism. 📣
• if it reaches the top level of script evaluation in tclsh, it will be printed on the console before, in the non-interactive case, causing an exit 🚪 — and just so you know, the behavior in other programs will depend on the details of how Tcl is embedded and used. so like, ymmv, it depends on the embedding. 🙈

also, by convention, the words in the type argument should go from most general to most specific. so like, big category first, tiny detail last. general → specific, periodt. 💖

🌸 EXAMPLES 🌸

the following produces an error that is identical to that produced by expr when trying to divide a value by zero. iconic behavior, honestly:

throw {ARITH DIVZERO {divide by zero}} {divide by zero}

see how the type is the general-to-specific list and the message is the human-readable bit? that's the whole pattern. slay. ✨

👑 SEE ALSO 👑

• catch(3tcl)
• error(3tcl)
• errorCode(3tcl)
• errorInfo(3tcl)
• return(3tcl)
• try(3tcl)

🎀 KEYWORDS 🎀

error, exception

and that's the page, bestie 🫶 this was Tcl 8.6, the throw(3tcl) manual page — go forth and throw responsibly, mwah 💖🌸🦋