This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

Tcl_SubstObj(3)                            Tcl Library Procedures                            Tcl_SubstObj(3)



____________________________________________________________________________________________________________

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  sub-stitutions substitutions
                                           stitutions 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  sub-stitution, substitution,
       stitution, 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 excep-tion exception
       tion 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)