blt::watch(3tcl)

💖 blt::watch — the manual page, but make it make sense 💖

okay bestie, gather round, because this is blt::watch(3tcl) from the BLT Built-In Commands set and it's genuinely one of the most underrated little tools in Tcl land. lowkey iconic. let's get into it. 🦋

---

✨ NAME ✨

watch — call Tcl procedures before and after each command. yes, each command. she's watching everything, she's the main character. 👑

---

🌸 SYNOPSIS 🌸

watch create watchName ?options?

watch activate watchName

watch deactivate watchName

watch delete watchName

watch configure watchName ?options

watch info watchName

watch names

look at her. seven whole moods. 💅

---

🎀 DESCRIPTION 🎀

so basically, the watch command arranges for Tcl procedures to be invoked before and after the execution of each Tcl command. that's it. that's the whole vibe. she's the girl standing behind you going "okay and now what are you doing" for every single line. 🫶

---

🧚 INTRODUCTION 🧚

okay so here's the situation that made this whole thing necessary. when an error happens in Tcl, the global variable errorInfo will contain a stack-trace of the active procedures when the error occured. and like… usually that's fine. usually that's enough.

but sometimes it is not enough. 😭

sometimes you need to know exactly where in the program's execution the error occured, and a stack trace is just giving vague. in cases like this, a more general tracing facility would be useful — and that's her. that's the watch command.

the watch command lets you designate Tcl procedures to be invoked before and after the execution of each Tcl command. so you can display the command line and its results for each command as it executes. another use is to profile your Tcl commands — and ngl this is the part that ate: you can profile any Tcl command (like if and set), not just Tcl procedures. not just the fancy ones. all of them. periodt. 🔥

---

⭐ EXAMPLE ⭐

the following example use watch to trace Tcl commands (printing to standard error) both before and after they are executed.

proc preCmd { level command argv } {
    set name [lindex $argv 0]
    puts stderr "$level $name => $command"
}

proc postCmd { level command argv retcode results } {
    set name [lindex $argv 0]
    puts stderr "$level $name => $argv0= ($retcode) $results"
}
watch create trace \
  -postcmd postCmd -precmd preCmd

she's printing the tea to stderr before AND after. obsessed. 🌈

---

💜 OPERATIONS 💜

the following operations are available for the watch command:

• watch activate watchName — activates the watch, causing Tcl commands the be traced to the maximum depth selected. wake her up, she's going in. ✨
• watch create watchName ?options?... — creates a new watch watchName. it's an error if another watch watchName already exists and an error message will be returned. (no duplicates bestie, we don't do that here. 💀) options may have any of the values accepted by the watch configure command. this command returns the empty string.
• watch configure watchName ?options...? — queries or modifies the configuration options of the watch watchName. WatchName is the name of a watch. options may have any of the following values:
  • -active boolean — specifies if the watch is active. by default, watches are active when created. (yes, she comes out the box ready. eager. 💅)
  • -postcmd string — specifies a Tcl procedure to be called immediately after each Tcl command. String is name of a Tcl procedure and any extra arguments to be passed to it. before string is invoked, five more arguments are appended: 1) the current level 2) the current command line 3) a list containing the command after substitutions and split into words 4) the return code of the command, and 5) the results of the command. the return status of the postcmd procedure is always ignored. 🫥 (she does not care what you return. she's above it.)
  • -precmd string — specifies a Tcl procedure to be called immediately before each Tcl command. String is name of a Tcl procedure and any extra arguments to be passed to it. before string is invoked, three arguments are appended: 1) the current level 2) the current command line, and 3) a list containing the command after substitutions and split into words. the return status of the -precmd procedure is always ignored. 🙈
  • -maxlevel number — specifies the maximum evaluation depth to watch Tcl commands. the default maximum level is 10000. that's a lot of levels. she will go that deep. 🌊
• watch deactivate watchName — deactivates the watch. the -precmd and -postcmd procedures will no longer be invoked. she's taking a nap. do not disturb. 😴
• watch info watchName — returns the configuration information associated with the watch watchName. WatchName is the name of a watch.
• watch names ?state? — lists the names of the watches for a given state. State may be one of the following: active, idle, or ignore. if a state argument isn't specified, all watches are listed. 🎀

---

🔑 KEYWORDS 🔑

debug, profile

---

okay one tiny thing — the synopsis up top lists watch delete watchName too, so don't come for me, I listed every operation exactly as the page gave them. 💖

---

and that's the whole page, bestie!! this was blt::watch from BLT, version 2.5 — a certified classic, a real one, an icon, and honestly? we love her. go trace something. go profile something. go be nosy about your own code. 💜✨🦋