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 contain
- ing the string to per
form 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_BACK SLASHES are currently supported, and
TCL_SUBST_ALL is pro vided as a convenience
for the common case
where all substitu
tions 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 occur
ring during the execution of a command or variable substi
tution, 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 vari
able.
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 evalua
tion of a command substitution, an empty string is substi
tuted 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