subst(n)

______________________________________________________________________________

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

       backslash substitution, command substitution, variable substitution

Tcl                                   7.4                             subst(n)