error(n)

✨ error(n) — the Tcl Built-In Commands era 💅

okay bestie, so this is error, a built-in command from the Tcl Built-In Commands manual set, and it does exactly one thing and does it loudly: it makes an error happen. let's get into it 🎀

---

🌸 NAME 🌸

error — generate an error. yes, that's the whole job. iconic behavior honestly.

---

⭐ SYNOPSIS ⭐

error message ?info? ?code?

three little slots, one big dramatic exit. 🦋

---

💖 DESCRIPTION 💖

So here's the tea: error returns a TCL_ERROR code, and that code is what makes command interpretation get unwound. Like, the whole thing starts collapsing back up the stack. message is a string, and it gets returned to the application to say what went wrong. that's its moment, let it have it. 💅

Now, the -errorinfo return option of an interpreter? that's the one that accumulates a stack trace of what was in progress when the error happened. As nested commands unwind, the Tcl interpreter keeps adding info to the -errorinfo return option. so it's like a little receipt trail of everything that was going down. 🧾

If the info argument is present, it's used to initialize the -errorinfo return options — and the first increment of unwind information will not be added by the Tcl interpreter. Translation bestie: the command that contains the error command will not show up in the stack trace. instead, in its place, you get info. so info is basically stepping in and saying "I'll take it from here." 👑

Historically, this feature had been most useful in conjunction with the catch command: if a caught error cannot be handled successfully, info can be used to return a stack trace reflecting the original point of occurrence of the error:

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

When working with Tcl 8.5 or later, the following code should be used instead:

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

no cap, if you're on Tcl 8.5+ use the second one. the first one is giving vintage. 🕰️

If the code argument is present, then its value is stored in the -errorcode return option. The -errorcode return option is intended to hold a machine-readable description of the error in cases where such information is available. for the proper format for this option's value, go read the return manual page — it has the whole format situation laid out. 📖

---

🦋 EXAMPLE 🦋

Generate an error if a basic mathematical operation fails:

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

like… if math itself is broken, we have bigger problems, but okay, at least the error message is honest. 😭

---

🫶 SEE ALSO 🫶

• catch(n)
• return(n)

the whole friend group, honestly. ✨

---

👑 KEYWORDS 👑

• error
• exception

---

Tcl made this one, it lives in the error(n) slot of the manual, and that's the whole vibe check — slay, and remember: errors are just ✨information✨ with main character energy. 🌈💜