error(3tcl)

💅 error — bestie, we're generating an error ✨

so this is error(3tcl), one of the Tcl Built-In Commands, and it's literally the drama queen of the interpreter — it shows up, it throws a fit, everything unwinds. iconic behaviour, ngl.

---

✨ SYNOPSIS ✨

error message ?info? ?code?

---

🎀 DESCRIPTION 🎀

okay so when you call error, it returns a TCL_ERROR code, which makes command interpretation get unwound. like, the whole thing just starts unwinding. message is a string that gets handed back to the application so it knows what went wrong — that's literally its whole job, telling everyone what happened. 🫶

Now the juicy part. The -errorinfo return option of an interpreter is what collects the stack trace of whatever was in progress when the error popped off. as nested commands unwind, the Tcl interpreter keeps adding info to that -errorinfo return option. it's giving receipts. 📜

if the info argument is there, then it gets used to initialize the -errorinfo return options, and the first increment of unwind information will not be added by the Tcl interpreter. in other words: the command that contains the error command won't show up in the stack trace — in its place you get info. cute little swap, right? 💅

historically, this feature was most useful when paired with the catch command: if a caught error can't be handled successfully, info can be used to return a stack trace that reflects the original point of occurrence of the error:

catch {...} errMsg
set savedInfo $::errorInfo
...
error $errMsg $savedInfo

but bestie, if you're working with Tcl 8.5 or later, use this instead:

catch {...} errMsg options
...
return -options $options $errMsg

and if the code argument is present, its value gets stored in the -errorcode return option. -errorcode is meant to hold a machine-readable description of the error, for when that kind of info is actually available. for the proper format of this option's value, go check the return manual page — iykyk. 🔥

---

🌸 EXAMPLE 🌸

generate an error if a basic mathematical operation fails:

if {1+2 != 3} {
    error "something is very wrong with addition"
}

(and honestly? if 1+2 != 3 then something is very wrong with addition. no cap. 😭)

---

🦋 SEE ALSO 🦋

• catch(3tcl)
• return(3tcl)

---

👑 KEYWORDS 👑

• error
• exception

---

ok that's the whole page, periodt. go forth and raise errors responsibly 💖

signing off from the Tcl manual, this was error(3tcl) — main character energy only. mwah. 💅✨