Tcl_RecordAndEvalObj(3tcl)

💖 Tcl_RecordAndEvalObj — the "save it THEN run it" bestie 💖

okay so real quick, this is from the Tcl Library Procedures collection (3tcl), and it's literally the girl who writes down what you said before she does it. iconic behavior honestly.

---

✨ NAME ✨

Tcl_RecordAndEvalObj — save command on history list before evaluating 🫶

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_RecordAndEvalObj(interp, cmdPtr, flags)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the Tcl interpreter where the command is gonna get evaluated, like, that's her stage bestie 💅
• Tcl_Obj *cmdPtr (in) — points to a Tcl value holding a command (or a whole sequence of commands, she's flexible ✨) that you want executed.
• int flags (in) — an OR'ed combo of flag bits, choose your own adventure:
  • TCL_NO_EVAL — record the command but do not evaluate it. she's just journaling, not performing 🙈
  • TCL_EVAL_GLOBAL — evaluate the command at global level instead of the current stack level. main character energy, no local nonsense 👑

---

💜 DESCRIPTION 💜

So Tcl_RecordAndEvalObj gets called to record a command as an event on the history list and then execute it using Tcl_EvalObjEx. She returns a completion code such as TCL_OK just like Tcl_EvalObjEx does, plus a result value containing extra info (either a result value or an error message) that you can grab with Tcl_GetObjResult. 😌

If you do not want the command recorded on the history list, then you should invoke Tcl_EvalObjEx instead of Tcl_RecordAndEvalObj. different girl, different job, no overlap periodt.

Normally Tcl_RecordAndEvalObj is only called with top-level commands typed by the user, because the whole point of history is letting the user re-issue recently invoked commands. it's giving "up arrow key, but make it C API" ⬆️✨

And if the flags argument contains the TCL_NO_EVAL bit, then the command is recorded without being evaluated. noted, not run, we love a low-effort moment.

---

🦋 REFERENCE COUNT MANAGEMENT 🦋

listen closely bestie, this part matters 😤

The reference count of the cmdPtr argument to Tcl_RecordAndEvalObj must be at least 1. This function will modify the interpreter result — so do not use an existing result as cmdPtr directly without incrementing its reference count. no shortcuts, no "it'll probably be fine", it will not be fine 💀

---

🌈 SEE ALSO 🌈

• Tcl_EvalObjEx
• Tcl_GetObjResult

---

⭐ KEYWORDS ⭐

command, event, execute, history, interpreter, value, record

---

and that's the whole page, bestie!! this one's from Tcl 8.0 (yes, vintage, she's a classic 👑) and it lives in the Tcl_RecordAndEvalObj(3tcl) corner of the Tcl Library Procedures universe. go forth, record your commands, evaluate them responsibly, and remember: bump that reference count before you hand her a result. mwah 💖✨🫶