subst(n) Tcl Built-In Commands subst(n)______________________________________________________________________________NAMEsubst - Perform backslash, command, and variable substitutions
SYNOPSISsubst ?-nobackslashes? ?-nocommands? ?-novariables? string
_________________________________________________________________DESCRIPTION
This command performs variable substitutions, command substitutions,
and backslash substitutions on its string argument and returns the
fully-substituted result. The substitutions are performed in exactly
the same way as for Tcl commands. As a result, the string argument is
actually substituted twice, once by the Tcl parser in the usual fashion
for Tcl commands, and again by the subst command.
If any of the -nobackslashes, -nocommands, or -novariables are speci‐
fied, then the corresponding substitutions are not performed. For
example, if -nocommands is specified, command substitution is not per‐
formed: open and close brackets are treated as ordinary characters
with no special interpretation.
Note that the substitution of one kind can include substitution of │
other kinds. For example, even when the -novariables option is speci‐ │
fied, command substitution is performed without restriction. This │
means that any variable substitution necessary to complete the command │
substitution will still take place. Likewise, any command substitution │
necessary to complete a variable substitution will take place, even │
when -nocommands is specified. See the EXAMPLES below. │
If an error occurs during substitution, then subst will return that │
error. If a break exception occurs during command or variable substi‐ │
tution, the result of the whole substitution will be the string (as │
substituted) up to the start of the substitution that raised the excep‐ │
tion. If a continue exception occurs during the evaluation of a com‐ │
mand 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. │
In this way, all exceptional return codes are ``caught'' by subst. The │
subst command itself will either return an error, or will complete suc‐ │
cessfully.
EXAMPLES
When it performs its substitutions, subst does not give any special
treatment to double quotes or curly braces (except within command sub‐
stitutions) so the script
set a 44
subst {xyz {$a}}
returns ``xyz {44}'', not ``xyz {$a}'' and the script │
set a "p\} q \{r" │
subst {xyz {$a}} │
return ``xyz {p} q {r}'', not ``xyz {p\} q \{r}''. │
When command substitution is performed, it includes any variable sub‐ │
stitution necessary to evaluate the script. │
set a 44 │
subst-novariables {$a [format $a]} │
returns ``$a 44'', not ``$a $a''. Similarly, when variable substitu‐ │
tion 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 continue and break exceptions allow command substitutions to pre‐ │
vent substitution of the rest of the command substitution and the rest │
of string respectively, giving script authors more options when pro‐ │
cessing text using subst. For example, the script │
subst {abc,[break],def} │
returns ``abc,'', not ``abc,,def'' and the script │
subst {abc,[continue;expr 1+2],def} │
returns ``abc,,def'', not ``abc,3,def''. │
Other exceptional return codes substitute the returned value │
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''.
SEE ALSOTcl(n), eval(n), break(n), continue(n)KEYWORDS
backslash substitution, command substitution, variable substitution
Tcl 7.4 subst(n)
