Tcl_SubstObj(3tcl)

💖 Tcl_SubstObj — bestie edition 💖

okay so this is a page from the Tcl Library Procedures manual, and it's all about Tcl_SubstObj(3tcl). buckle up, it's actually so good.

---

✨ NAME ✨

Tcl_SubstObj — do substitutions on Tcl values, literally the subst command's whole thing but as a C function 🫶

---

✨ SYNOPSIS ✨

#include <tcl.h>

Tcl_Obj *
Tcl_SubstObj(interp, objPtr, flags)

---

✨ ARGUMENTS ✨

• Tcl_Interp *interp (in) — the interpreter where the Tcl scripts run and the variables get looked up. if something goes wrong, its result gets overwritten with the error message. so it's the one holding the receipts 👑
• Tcl_Obj *objPtr (in) — a Tcl value whose string is the thing you want substitutions performed on. this is the main character of the operation 🌟
• int flags (in) — an OR'ed-together combo of flag bits saying which substitutions you actually want. the supported ones rn are TCL_SUBST_COMMANDS, TCL_SUBST_VARIABLES, and TCL_SUBST_BACKSLASHES, and there's TCL_SUBST_ALL as a little convenience for the super common case where you want, like, all of them. slay ✨

---

✨ DESCRIPTION ✨

so Tcl_SubstObj is the function that does substitutions on strings the exact same way the subst command does. it grabs the value of the string inside objPtr, scans it, and as it goes it copies characters and performs whichever substitutions you picked, building up an output value that gets returned as the function's result. lowkey elegant 💅

and if an error pops off during a command or variable substitution? the function returns NULL and drops an error message into interp's result. no cap, that's the deal.

there are three kinds of substitutions supported:

• when the TCL_SUBST_BACKSLASHES bit is set in flags, sequences that look like backslash substitutions for Tcl commands get swapped out for their corresponding character. 🦋
• when the TCL_SUBST_VARIABLES bit is set in flags, sequences that look like variable substitutions for Tcl commands get replaced by the contents of the named variable. 🎀
• when the TCL_SUBST_COMMANDS bit is set in flags, sequences that look like command substitutions for Tcl commands get replaced by the result of evaluating that script. 🍓

now the spicy part, listen up:

where an uncaught "continue exception" happens during the evaluation of a command substitution, an empty string is substituted in for that command. so it's just... gone. nothing there. 💀

where an uncaught "break exception" happens during the evaluation of a command substitution, the result of the whole substitution on objPtr gets truncated at the point immediately before the start of that command substitution. nothing gets added to the result after that point and no further substitutions get performed either. it's giving "we stop here, periodt." 🔥

---

✨ REFERENCE COUNT MANAGEMENT ✨

okay this part matters so don't skip it 🙈

the objPtr argument passed to Tcl_SubstObj must not have a reference count of zero. also, this function modifies the interpreter result — and it does that both when it succeeds and when it fails. the result of this function on success is exactly the current interpreter result, no more no less. and if you wanna hang onto a successful result? bump its reference count, bestie, otherwise it's not sticking around. 🫶

---

✨ SEE ALSO ✨

• subst(3tcl) — go read it, it's the sibling energy 💜

---

✨ KEYWORDS ✨

backslash substitution, command substitution, variable substitution 🌈

---

and that's the whole page, you understood it perfectly, I'm so proud of you. this one's from the Tcl 8.4 era of the manual — shoutout to that vintage, it ate — and yeah, that's Tcl_SubstObj(3tcl), we're done here. mwah 💖💅✨