Tcl_SubstObj(3tcl)

______________________________________________________________________________

NAME

       Tcl_SubstObj - perform substitutions on Tcl objects

SYNOPSIS

       #include <tcl.h>

       Tcl_Obj *
       Tcl_SubstObj(interp, objPtr, flags)

ARGUMENTS

       Tcl_Interp   *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.

       Tcl_Obj      *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   TCL_SUBST_COM-
                                           MANDS,    TCL_SUBST_VARIABLES   and
                                           TCL_SUBST_BACKSLASHES are currently
                                           supported,   and  TCL_SUBST_ALL  is
                                           provided as a convenience  for  the
                                           common case where all substitutions
                                           are desired.
_________________________________________________________________

DESCRIPTION

       The Tcl_SubstObj function is used to perform substitutions  on  strings
       in  the  fashion of the subst 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  TCL_SUBST_BACK-
       SLASHES bit is set in flags, sequences that look like backslash substi-
       tutions for Tcl commands are replaced by their corresponding character.

       When  the  TCL_SUBST_VARIABLES 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  TCL_SUBST_COMMANDS  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)

KEYWORDS

       backslash substitution, command substitution, variable substitution

Tcl                                   8.4                      Tcl_SubstObj(3)