Seth Woolley's Man Viewer

subst(n) - subst, subst - Perform backslash, command, and variable substitutions - man n subst

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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



NAME
       subst - Perform backslash, command, and variable substitutions

SYNOPSIS
       subst ?-nobackslashes? ?-nocommands? ?-novariables? string(3,n)


DESCRIPTION
       This  command  performs  variable substitutions, command substitutions,
       and backslash substitutions on its  string(3,n)  argument  and  returns  the
       fully-substituted  result.   The substitutions are performed in(1,8) exactly
       the same way as for Tcl commands.  As a result, the string(3,n) argument  is
       actually substituted twice, once by the Tcl parser in(1,8) 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(3,n) -nocommands is specified, command substitution is not  per-
       formed:   open(2,3,n)  and  close(2,7,n)  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(8,n) 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(3,n)  (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(3,n) 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(8,n), 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(7,n,1 builtins) a  44  subst  {xyz  {$a}}  returns  ``xyz
       {44}'',  not  ``xyz  {$a}'' and the script set(7,n,1 builtins) 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(7,n,1 builtins) a 44 subst -novari-
       ables {$a [format $a]} returns ``$a 44'', not  ``$a  $a''.   Similarly,
       when  variable  substitution is performed, it includes any command sub-
       stitution necessary to retrieve the value of the variable.  proc(5,n)  b  {}
       {return c} array set(7,n,1 builtins) 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(3,n) 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,3,n)   1+2],def}   returns   ``abc,,def'',   not
       ``abc,3,def''.

       Other exceptional return codes  substitute  the  returned  value  subst
       {abc,[return    foo;expr(1,3,n)   1+2],def}   returns   ``abc,foo,def'',   not
       ``abc,3,def'' and subst {abc,[return -code 10 foo;expr(1,3,n)  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)

References for this manual (incoming links)