Manual Pages for UNIX Operating System command usage for man subst

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

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




Tcl                     Last change: 7.4                        2






Tcl Built-In Commands                                   subst(1T)



     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

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













































Tcl                     Last change: 7.4                        3