Tcl Built-In Commands                                   subst(1T)





NAME
     subst - Perform backslash, command, and  variable  substitu-
     tions

SYNOPSIS
     subst ?-nobackslashes? ?-nocommands? ?-novariables? string



DESCRIPTION
     This command performs variable substitutions,  command  sub-
     stitutions,  and backslash substitutions on its string argu-
     ment and returns the fully-substituted result.  The  substi-
     tutions  are  performed  in  exactly the same way as for Tcl
     commands.  As a result, the string argument is actually sub-
     stituted  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,  com-
     mand substitution is not performed:  open and close brackets
     are treated as ordinary characters with no special interpre-
     tation.

     Note that the substitution of one kind can include substitu-  
     tion  of  other  kinds.  For example, even when the -novari-  
     ables option is specified, command substitution is performed  
     without restriction.  This means that any variable substitu-  
     tion necessary to complete  the  command  substitution  will  
     still take place.  Likewise, any command substitution neces-  
     sary 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 com-  
     mand or variable substitution, the result of the whole  sub-  
     stitution  will  be  the  string  (as substituted) up to the  
     start of the substitution that raised the exception.   If  a  
     continue exception occurs during the evaluation of a command  
     or variable substitution, an empty string  will  be  substi-  
     tuted  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 substi-  
     tuted  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 successfully.




Tcl                     Last change: 7.4                        1






Tcl Built-In Commands                                   subst(1T)



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         
          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 substitution necessary to evaluate the script.       
          set a 44                                                 
          subst -novariables {$a [format $a]}                      
     returns ``$a 44'', not ``$a $a''.  Similarly, when  variable  
     substitution is performed, it includes any command substitu-  
     tion 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  substitu-  
     tions  to  prevent  substitution  of the rest of the command  
     substitution and the rest  of  string  respectively,  giving  
     script  authors  more  options  when  processing  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(1T), eval(1T), break(1T), continue(1T)


KEYWORDS
     backslash substitution, command substitution, variable  sub-
     stitution

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:




Tcl                     Last change: 7.4                        2






Tcl Built-In Commands                                   subst(1T)



     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.













































Tcl                     Last change: 7.4                        3