try(3tcl)

💖 try — bestie, we're catching exceptions 💖

okay so this is try(3tcl), a page from the tcllib manual, and it's the forward compatibility implementation of [try]. pull up a chair, we're doing error handling and it's gonna be gorgeous 💅

---

✨ NAME ✨

try — trap and process errors and exceptions. like, catch your chaos before it catches you 🫶

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require try ?1.1?

::try body ?handler...? ?finally script?

---

✨ DESCRIPTION ✨

okay bestie, here's the tea ☕ this package gives you a forward-compatibility implementation of Tcl 8.6's try/finally command (that's TIP 329, iykyk) but for Tcl 8.5. and the code? it was directly pulled from Tcl 8.6 revision ?, back when try/finally was implemented as a Tcl procedure instead of in C. no cap.

🦋 ::try body ?handler...? ?finally script?

this command runs the script body and then, depending on what the outcome of that script is — normal exit, error, or some other exceptional result — it runs a handler script to deal with the case. main character energy fr fr 👑

once all that's happened, if the finally clause is present, the script it includes will be run, and the result of the handler (or the body if no handler matched) is allowed to continue to propagate. and listen — the finally clause gets processed even if an error occurs and irrespective of which, if any, handler is used. it's loyal like that 💖

the handler clauses are each expressed as several words, and they must have one of the following forms:

🌸 on code variableList script

this clause matches if the evaluation of body completed with the exception code code. the code may be expressed as an integer or one of the following literal words: ok, error, return, break, or continue. those literals correspond to the integers 0 through 4 respectively. cute, right?

🌸 trap pattern variableList script

this clause matches if the evaluation of body resulted in an error and the prefix of the -errorcode from the interpreter's status dictionary is equal to the pattern. the number of prefix words taken from the -errorcode is equal to the list-length of pattern, and inter-word spaces are normalized in both the -errorcode and pattern before comparison. so it's a whole vibe-check match, basically ⭐

---

okay now the details that apply to every handler, pay attention bestie:

• the variableList word in each handler is always interpreted as a list of variable names.
  • if the first word of the list is present and non-empty, it names a variable into which the result of the evaluation of body (from the main try) will be placed. this will contain the human-readable form of any errors. 😭
  • if the second word of the list is present and non-empty, it names a variable into which the options dictionary of the interpreter at the moment of completion of execution of body will be placed.
• the script word of each handler is also always interpreted the same way: as a Tcl script to evaluate if the clause is matched.
  • if script is a literal - and the handler is not the last one, the script of the following handler is invoked instead — just like with the switch command. iconic behavior tbh.
• note that handler clauses are matched against in order, and the first matching one is always selected. at most one handler clause will be selected. as a consequence, an on error will mask any subsequent trap in the try. 🙈 also note that on error is equivalent to trap {}. periodt.

⚠️ okay this one matters: if an exception (i.e. any non-ok result) occurs during the evaluation of either the handler or the finally clause, the original exception's status dictionary will be added to the new exception's status dictionary under the -during key. so nothing gets lost, it just gets nested. 💜

---

✨ EXAMPLES ✨

🎀 example one: make sure a file gets closed no matter what

set f [open /some/file/name a]
try {
    puts \$f "some message"
    # ...
} finally {
    close \$f
}

🎀 example two: handle different reasons a file can't be opened for reading

try {
    set f [open /some/file/name]
} trap {POSIX EISDIR} {} {
    puts "failed to open /some/file/name: it's a directory"
} trap {POSIX ENOENT} {} {
    puts "failed to open /some/file/name: it doesn't exist"
}

---

✨ BUGS, IDEAS, FEEDBACK ✨

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving "we're all just doing our best". please report such in the category try of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the feedback, fr fr 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. slay.

---

✨ SEE ALSO ✨

• catch(3tcl)
• error(3tcl)
• return(3tcl)
• throw(3tcl)

---

✨ KEYWORDS ✨

cleanup, error, exception, final, resource management 💅

---

✨ CATEGORY ✨

Utility

---

✨ COPYRIGHT ✨

Copyright (c) 2008 Donal K. Fellows, BSD licensed

---

and that's the whole page bestie 🦋 this was try(3tcl) from tcllib version 1.1 — go forth and catch your exceptions responsibly, you've got this 👑💖