Tcl_RecordAndEvalObj(3)

💖 Tcl_RecordAndEvalObj — bestie, it's a Tcl Library Procedure 💖

okay so real talk, this one lives in section 3 of the Tcl manual and it's lowkey one of the most useful lil functions in the whole interpreter toolbox. let's get into it 🫶

---

✨ NAME ✨

Tcl_RecordAndEvalObj — save a command on the history list before evaluating it. that's it. that's the whole vibe. 📝

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_RecordAndEvalObj(interp, cmdPtr, flags)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the Tcl interpreter where we're gonna go evaluate this command. it's giving "the stage" 💅
• Tcl_Obj *cmdPtr (in) — points to a Tcl value that holds a command (or honestly a whole sequence of commands, we don't judge) to execute. this is the main character of the function, fr fr 👑
• int flags (in) — an OR'ed combination of flag bits. yes, OR'ed, as in you can stack them, we love a flexible girlie:
  • TCL_NO_EVAL — record the command but do not evaluate it. just write it down and move on, no execution, nope 🙈
  • TCL_EVAL_GLOBAL — evaluate the command at the global level instead of at the current stack level. so it's going straight to the top, no local nonsense 🌍

---

🦋 DESCRIPTION 🦋

so you invoke Tcl_RecordAndEvalObj when you wanna do a little two-step: record a command as an event on the history list, then execute it using Tcl_EvalObjEx. it's a combo move. a one-two punch. iconic behavior ✨

it returns a completion code such as TCL_OK, exactly like Tcl_EvalObjEx does, and it also drops a result value containing extra info (could be a result value, could be an error message) that you can grab with Tcl_GetObjResult.

now listen — if you do not want the command recorded on the history list, then bestie you should be calling Tcl_EvalObjEx instead of Tcl_RecordAndEvalObj. that's the whole difference. pick your fighter 🥊

normally Tcl_RecordAndEvalObj is only called with top-level commands typed by the user, because the entire point of history is letting the user re-issue commands they recently ran. like, that's the assignment. that's why it exists 💖

and if the flags argument contains the TCL_NO_EVAL bit? then the command gets recorded without being evaluated. recorded and left alone. noted but not acted upon. very "I saw your text and I'm not replying" energy 💀

---

🧚 REFERENCE COUNT MANAGEMENT 🧚

okay this part is IMPORTANT, pay attention, no scrolling past 🚨

• 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 first.

fr fr, if you skip that increment you are asking for chaos and the chaos will answer. 🙏

---

🌈 SEE ALSO 🌈

• Tcl_EvalObjEx
• Tcl_GetObjResult

---

⭐ KEYWORDS ⭐

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

---

and that's the whole page, bestie!! 💅 this one came straight out of Tcl 8.0, dated with the classic Tcl_RecordAndEvalObj(3) footer energy — go forth and record those commands responsibly 🎀💜