subst(n) Tcl Built-In Commands subst(n)

NAME
       subst - Perform backslash, command, and variable substitutions

SYNOPSIS
       ssuubbsstt ?-nnoobbaacckkssllaasshheess? ?-nnooccoommmmaannddss? ?-nnoovvaarriiaabblleess? 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 -nnoobbaacckkssllaasshheess, -nnooccoommmmaannddss, or -nnoovvaarriiaabblleess  are  speci-
       fied,  then  the  corresponding  substitutions  are not performed.  For
       example, if -nnooccoommmmaannddss 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 -nnoovvaarriiaabblleess 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 -nnooccoommmmaannddss is specified.  See the EXAMPLES below.                 |

       If an error occurs during substitution, then  ssuubbsstt  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 ssuubbsstt.  The |
       ssuubbsstt command itself will either return an error, or will complete suc- |
       cessfully.

EEXXAAMMPPLLEESS
       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
              sseett aa 4444
              ssuubbsstt {{xxyyzz {{$$aa}}}}
       returns ``xxyyzz {{4444}}'', not ``xxyyzz {{$$aa}}'' and the script                   |
              sseett aa ""pp\\}} qq \\{{rr""                                                |
              ssuubbsstt {{xxyyzz {{$$aa}}}}                                                 |
       return ``xxyyzz {{pp}} qq {{rr}}'', not ``xxyyzz {{pp\\}} qq \\{{rr}}''.                      |

       When command substitution is performed, it includes any  variable  sub- |
       stitution necessary to evaluate the script.                             |
              sseett aa 4444                                                         |
              ssuubbsstt -nnoovvaarriiaabblleess {{$$aa [[ffoorrmmaatt $$aa]]}}                              |
       returns  ``$$aa  4444'', not ``$$aa $$aa''.  Similarly, when variable substitu- |
       tion is performed, it includes any command  substitution  necessary  to |
       retrieve the value of the variable.                                     |
              pprroocc bb {{}} {{rreettuurrnn cc}}                                             |
              aarrrraayy sseett aa {{cc cc [[bb]] ttrriicckkyy}}                                     |
              ssuubbsstt -nnooccoommmmaannddss {{[[bb]] $$aa(([[bb]]))}}                                  |
       returns ``[[bb]] cc'', not ``[[bb]] ttrriicckkyy''.                                  |

       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                      |
              ssuubbsstt {{aabbcc,,[[bbrreeaakk]],,ddeeff}}                                          |
       returns ``aabbcc,,'', not ``aabbcc,,,,ddeeff'' and the script                       |
              ssuubbsstt {{aabbcc,,[[ccoonnttiinnuuee;;eexxpprr 11++22]],,ddeeff}}                              |
       returns ``aabbcc,,,,ddeeff'', not ``aabbcc,,33,,ddeeff''.                                |

       Other exceptional return codes substitute the returned value            |
              ssuubbsstt {{aabbcc,,[[rreettuurrnn ffoooo;;eexxpprr 11++22]],,ddeeff}}                            |
       returns ``aabbcc,,ffoooo,,ddeeff'', not ``aabbcc,,33,,ddeeff'' and                          |
              ssuubbsstt {{aabbcc,,[[rreettuurrnn -ccooddee 1100 ffoooo;;eexxpprr 11++22]],,ddeeff}}                   |
       also returns ``aabbcc,,ffoooo,,ddeeff'', not ``aabbcc,,33,,ddeeff''.


SEE ALSO
       Tcl(n), eval(n), break(n), continue(n)


KKEEYYWWOORRDDSS
       backslash substitution, command substitution, variable substitution



Tcl                                   7.4                             subst(n)