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  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 ALSO
       Tcl(n), eval(n), break(n), continue(n)


KEYWORDS
