Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019

subst (1t)


subst - Perform backslash, command, and variable substitutions


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


subst(1t)                    Tcl Built-In Commands                   subst(1t)


       subst - Perform backslash, command, and variable substitutions

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

       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-

       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}}

       returns "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 substitution 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 attributes(7) for descriptions of the following attributes:

       |Availability   | runtime/tcl-8    |
       |Stability      | Uncommitted      |
       Tcl(n), eval(n), break(n), continue(n)

       backslash substitution, command  substitution,  quoting,  substitution,
       variable substitution

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.

Tcl                                   7.4                            subst(1t)