subst(3tcl)

💖 NAME 💖

subst — bestie, it does backslash, command, and variable substitutions. all three. at once. iconic behavior honestly.

---

✨ SYNOPSIS ✨

subst ?-nobackslashes? ?-nocommands? ?-novariables? string

---

🦋 DESCRIPTION 🦋

okay so here's the tea. subst takes its string argument and does variable substitutions, command substitutions, and backslash substitutions on it, then hands you back the fully-substituted result. no notes.

and the way it does those substitutions? exactly the same way as for Tcl commands. literally identical. which means — and this is the part that makes people go "wait, WHAT" — your string argument actually gets substituted twice. once by the Tcl parser, in the usual fashion for Tcl commands, and then again by the subst command itself. two passes. double the slay, double the chaos. 🙈

now if any of the -nobackslashes, -nocommands, or -novariables flags are specified, then the corresponding substitutions just... don't happen. so if you say -nocommands, command substitution is not performed, and open and close brackets are treated as ordinary characters with no special interpretation. they're just lil guys. brackets who aren't doing anything. 💅

🫶 heads up bestie: the substitution of one kind can include substitution of other kinds. it's giving layers, it's giving onion.

for example, even when the -novariables option is specified, command substitution is performed without restriction. which means any variable substitution necessary to complete that command substitution will still take place. no cap. and likewise, any command substitution necessary to complete a variable substitution will take place, even when -nocommands is specified. the flags are not a force field, okay?? see the EXAMPLES below, i promise it makes sense there. 🌈

---

now the drama section. 🎭 if an error occurs during substitution, then subst will return that error. simple.

• if a break exception occurs during command or variable substitution, the result of the whole substitution will be the string (as substituted) up to the start of the substitution that raised the exception.
• if a continue exception occurs during the evaluation of a command or variable substitution, an empty string will be substituted for that entire command or variable substitution (as long as it is well-formed Tcl).
• if a return exception occurs, or any other return code is returned during command or variable substitution, then the returned value is substituted for that substitution.

see the EXAMPLES below. 📖 and in this way, all exceptional return codes are "caught" by subst. every single one. caught. held. handled. the subst command itself will either return an error, or will complete successfully. there is no third option, periodt. 👑

---

🌸 EXAMPLES 🌸

when it performs its substitutions, subst does not give any special treatment to double quotes or curly braces (except within command substitutions). so like, the script

set a 44
subst {xyz {$a}}

returns "xyz {44}", not "xyz {$a}". the curly braces? not respected. sorry babe. 🎀

and the script

set a "p\} q \{r"
subst {xyz {$a}}

returns "xyz {p} q {r}", not "xyz {p} q {r}". see how the backslashes got eaten? yeah. that's the vibe. 💀

---

when command substitution is performed, it includes any variable substitution necessary to evaluate the script.

set a 44
subst -novariables {$a [format $a]}

returns "$a 44", not "$a $a". even though you said -novariables!! the variable inside the command sub still got substituted, because the command sub needed it. i told you. layers. 🧅✨

similarly, when variable substitution is performed, it includes any command substitution necessary to retrieve the value of the variable.

proc b {} {return c}
array set a {c c [b] tricky}
subst -nocommands {[b] $a([b])}

returns "[b] c", not "[b] tricky". the [b] inside the array index had to run so the variable could be read. the -nocommands flag said no but the variable sub said actually yes. iconic power move tbh. 👑

---

the continue and break exceptions allow command substitutions to prevent substitution of the rest of the command substitution and the rest of the string respectively, giving script authors more options when processing text using subst. so like, tools. options. freedom. 🦋

for example, the script

subst {abc,[break],def}

returns "abc,", not "abc,,def". break said we're DONE here and the rest of the string just... stopped. 😭

and the script

subst {abc,[continue;expr {1+2}],def}

returns "abc,,def", not "abc,3,def". continue yeeted the whole command substitution and left an empty string in its place, but kept going. no quitter energy. 💪

---

other exceptional return codes substitute the returned value. so

subst {abc,[return foo;expr {1+2}],def}

returns "abc,foo,def", not "abc,3,def". and

subst {abc,[return -code 10 foo;expr {1+2}],def}

also returns "abc,foo,def", not "abc,3,def". the return value slides in, the expr {1+2} never gets to shine. rest in peace 3. 🪦✨

---

👀 SEE ALSO 👀

Tcl(3tcl), eval(3tcl), break(3tcl), continue(3tcl)

---

🔑 KEYWORDS 🔑

backslash substitution, command substitution, quoting, substitution, variable substitution

---

okay that's the whole page bestie, go substitute something responsibly 💖✨🎀🦋🌸💅🫶

this was subst(3tcl) from the Tcl Built-In Commands manual, living in Tcl 7.4 — mwah, go forth and double-substitute, ily 🍓🧚💜