NAME

       subst - Perform backslash, command, and variable substitutions

SYNOPSIS

       subst ?-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  specified, then the corresponding
       substitutions are not performed.  For example, if -nocommands is specified, command substitution  is  not
       performed:  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 2
       the -novariables option is specified, command substitution is performed without restriction.  This  means 2
       that  any  variable  substitution  necessary  to complete the command substitution will still take place. 2
       Likewise, any command substitution necessary to complete a variable substitution will  take  place,  even 2
       when -nocommands is specified.  See the EXAMPLES below.                                                   2

       If  an  error occurs during substitution, then subst will return that error.  If a break exception occurs 2
       during command or variable substitution, the result of the whole substitution  will  be  the  string  (as 2
       substituted)  up  to  the  start  of the substitution that raised the exception.  If a continue exception 2
       occurs during the evaluation of a command or variable substitution, an empty string will  be  substituted 2
       for  that  entire  command  or  variable  substitution  (as  long as it is well-formed Tcl.)  If a return 2
       exception occurs, or any other return code is returned during command or variable substitution, then  the 2
       returned  value  is  substituted  for  that  substitution.   See  the  EXAMPLES  below.  In this way, all 2
       exceptional return codes are ``caught'' by subst.  The subst command itself will either return an  error, 2
       or will complete successfully.

EXAMPLES

       When  it  performs its substitutions, subst does not give any special treatment to double quotes or curly
       braces (except within command substitutions) so the script
              set a 44
              subst {xyz {$a}}
       returns ``xyz {44}'', not ``xyz {$a}'' and the script                                                     2
              set a "p\} q \{r"                                                                                  2
              subst {xyz {$a}}                                                                                   2
       return ``xyz {p} q {r}'', not ``xyz {p\} q \{r}''.                                                        2

       When command substitution is performed, it includes any variable substitution necessary to  evaluate  the 2
       script.                                                                                                   2
              set a 44                                                                                           2
              subst -novariables {$a [format $a]}                                                                2
       returns  ``$a  44'',  not ``$a $a''.  Similarly, when variable substitution is performed, it includes any 2
       command substitution necessary to retrieve the value of the variable.                                     2
              proc b {} {return c}                                                                               2
              array set a {c c [b] tricky}                                                                       2
              subst -nocommands {[b] $a([b])}                                                                    2
       returns ``[b] c'', not ``[b] tricky''.                                                                    2

       The continue and break exceptions allow command substitutions to prevent substitution of the rest of  the 2
       command  substitution  and  the  rest  of  string  respectively,  giving script authors more options when 2
       processing text using subst.  For example, the script                                                     2
              subst {abc,[break],def}                                                                            2
       returns ``abc,'', not ``abc,,def'' and the script                                                         2
              subst {abc,[continue;expr 1+2],def}                                                                2
       returns ``abc,,def'', not ``abc,3,def''.                                                                  2

       Other exceptional return codes substitute the returned value                                              2
              subst {abc,[return foo;expr 1+2],def}                                                              2
       returns ``abc,foo,def'', not ``abc,3,def'' and                                                            2
              subst {abc,[return -code 10 foo;expr 1+2],def}                                                     2
       also returns ``abc,foo,def'', not ``abc,3,def''.

SEE ALSO

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

KEYWORDS

       backslash substitution, command substitution, variable substitution

Tcl                                                    7.4                                           subst(3tcl)