1subst(n)                     Tcl Built-In Commands                    subst(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       subst - Perform backslash, command, and variable substitutions
9

SYNOPSIS

11       subst ?-nobackslashes? ?-nocommands? ?-novariables? string
12______________________________________________________________________________
13

DESCRIPTION

15       This  command  performs  variable substitutions, command substitutions,
16       and backslash substitutions on its  string  argument  and  returns  the
17       fully-substituted  result.   The substitutions are performed in exactly
18       the same way as for Tcl commands.  As a result, the string argument  is
19       actually substituted twice, once by the Tcl parser in the usual fashion
20       for Tcl commands, and again by the subst command.
21
22       If any of the -nobackslashes, -nocommands, or -novariables  are  speci‐
23       fied,  then  the  corresponding  substitutions  are not performed.  For
24       example, if -nocommands is specified, command substitution is not  per‐
25       formed:   open  and  close  brackets are treated as ordinary characters
26       with no special interpretation.
27
28       Note that the substitution of one  kind  can  include  substitution  of
29       other  kinds.  For example, even when the -novariables option is speci‐
30       fied, command substitution  is  performed  without  restriction.   This
31       means  that any variable substitution necessary to complete the command
32       substitution will still take place.  Likewise, any command substitution
33       necessary  to  complete  a  variable substitution will take place, even
34       when -nocommands is specified.  See the EXAMPLES below.
35
36       If an error occurs during substitution, then  subst  will  return  that
37       error.   If a break exception occurs during command or variable substi‐
38       tution, the result of the whole substitution will  be  the  string  (as
39       substituted) up to the start of the substitution that raised the excep‐
40       tion.  If a continue exception occurs during the evaluation of  a  com‐
41       mand  or variable substitution, an empty string will be substituted for
42       that entire command or variable substitution (as long as  it  is  well-
43       formed Tcl.)  If a return exception occurs, or any other return code is
44       returned during command or variable  substitution,  then  the  returned
45       value  is  substituted  for that substitution.  See the EXAMPLES below.
46       In this way, all exceptional return codes are “caught” by  subst.   The
47       subst command itself will either return an error, or will complete suc‐
48       cessfully.
49

EXAMPLES

51       When it performs its substitutions, subst does  not  give  any  special
52       treatment  to double quotes or curly braces (except within command sub‐
53       stitutions) so the script
54
55              set a 44
56              subst {xyz {$a}}
57
58       returns “xyz {44}”, not “xyz {$a}” and the script
59
60              set a "p\} q \{r"
61              subst {xyz {$a}}
62
63       returns “xyz {p} q {r}”, not “xyz {p\} q \{r}”.
64
65       When command substitution is performed, it includes any  variable  sub‐
66       stitution necessary to evaluate the script.
67
68              set a 44
69              subst -novariables {$a [format $a]}
70
71       returns “$a 44”, not “$a $a”.  Similarly, when variable substitution is
72       performed, it includes any command substitution necessary  to  retrieve
73       the value of the variable.
74
75              proc b {} {return c}
76              array set a {c c [b] tricky}
77              subst -nocommands {[b] $a([b])}
78
79       returns “[b] c”, not “[b] tricky”.
80
81       The  continue  and break exceptions allow command substitutions to pre‐
82       vent substitution of the rest of the command substitution and the  rest
83       of  string  respectively,  giving script authors more options when pro‐
84       cessing text using subst.  For example, the script
85
86              subst {abc,[break],def}
87
88       returns “abc,”, not “abc,,def” and the script
89
90              subst {abc,[continue;expr {1+2}],def}
91
92       returns “abc,,def”, not “abc,3,def”.
93
94       Other exceptional return codes substitute the returned value
95
96              subst {abc,[return foo;expr {1+2}],def}
97
98       returns “abc,foo,def”, not “abc,3,def” and
99
100              subst {abc,[return -code 10 foo;expr {1+2}],def}
101
102       also returns “abc,foo,def”, not “abc,3,def”.
103

SEE ALSO

105       Tcl(n), eval(n), break(n), continue(n)
106

KEYWORDS

108       backslash substitution, command  substitution,  quoting,  substitution,
109       variable substitution
110
111
112
113Tcl                                   7.4                             subst(n)