TclSubstObj(3) Tcl Library Procedures TclSubstObj(3)

NAME
       TclSubstObj - perform substitutions on Tcl objects

SYNOPSIS
       ##iinncclluuddee <>

       TclObj *
       TTccllSSuubbssttOObbjj(interp, objPtr, flags)

AARRGGUUMMEENNTTSS
       TclInterp   *interp      (in)      Interpreter in which to execute Tcl
                                           scripts and lookup  variables.   If
                                           an  error occurs, the interpreter's
                                           result is modified to hold an error
                                           message.

       TclObj      *objPtr      (in)      A  Tcl object containing the string
                                           to perform substitutions on.

       int          flags        (in)      ORed combination of flag bits  that
                                           specify which substitutions to per-
                                           form.   The  flags   TTCCLLSSUUBBSSTTCCOOMM-
                                           MMAANNDDSS,    TTCCLLSSUUBBSSTTVVAARRIIAABBLLEESS   and
                                           TTCCLLSSUUBBSSTTBBAACCKKSSLLAASSHHEESS are currently
                                           supported,   and  TTCCLLSSUUBBSSTTAALLLL  is
                                           provided as a convenience  for  the
                                           common case where all substitutions
                                           are desired.



DESCRIPTION
       The TTccllSSuubbssttOObbjj function is used to perform substitutions  on  strings
       in  the  fashion of the ssuubbsstt command.  It gets the value of the string
       contained in objPtr and scans it, copying characters and performing the
       chosen  substitutions  as it goes to an output object which is returned
       as the result of the function.  In the event of an error occurring dur-
       ing  the  execution of a command or variable substitution, the function
       returns NULL and an error message is left in interp's result.

       Three kinds of substitutions are supported.  When  the  TTCCLLSSUUBBSSTTBBAACCKK-
       SSLLAASSHHEESS bit is set in flags, sequences that look like backslash substi-
       tutions for Tcl commands are replaced by their corresponding character.

       When  the  TTCCLLSSUUBBSSTTVVAARRIIAABBLLEESS bit is set in flags, sequences that look
       like variable substitutions for Tcl commands are replaced by  the  con-
       tents of the named variable.

       When  th  TTCCLLSSUUBBSSTTCCOOMMMMAANNDDSS  bit  is set in flags, sequences that look
       like command substitutions for Tcl commands are replaced by the  result
       of evaluating that script.  Where an uncaught continue exception occurs
       during the evaluation of a command substitution,  an  empty  string  is
       substituted  for the command.  Where an uncaught break exception occurs
       during the evaluation of a command  substitution,  the  result  of  the
       whole substitution on objPtr will be truncated at the point immediately
       before the start of the command substitution, and no characters will be
       added to the result or substitutions performed after that point.


SEE ALSO
       subst(n)


KKEEYYWWOORRDDSS
       backslash substitution, command substitution, variable substitution



Tcl                                   8.4                      TclSubstObj(3)