trusty (3) Tcl_SubstObj.3tcl.gz

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
                                           perform.   The  flags  TCL_SUBST_COMMANDS,  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 during 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_BACKSLASHES  bit is set in flags,
       sequences that look like backslash substitutions 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 contents 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(3tcl)

KEYWORDS

       backslash substitution, command substitution, variable substitution