1Tcl_SubstObj(3)             Tcl Library Procedures             Tcl_SubstObj(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_SubstObj - perform substitutions on Tcl values
9

SYNOPSIS

11       #include <tcl.h>
12
13       Tcl_Obj *
14       Tcl_SubstObj(interp, objPtr, flags)
15

ARGUMENTS

17       Tcl_Interp *interp (in)            Interpreter  in which to execute Tcl
18                                          scripts and lookup variables.  If an
19                                          error  occurs, the interpreter's re‐
20                                          sult is modified to  hold  an  error
21                                          message.
22
23       Tcl_Obj *objPtr (in)               A Tcl value containing the string to
24                                          perform substitutions on.
25
26       int flags (in)                     ORed combination of flag  bits  that
27                                          specify  which substitutions to per‐
28                                          form.  The flags TCL_SUBST_COMMANDS,
29                                          TCL_SUBST_VARIABLES              and
30                                          TCL_SUBST_BACKSLASHES are  currently
31                                          supported, and TCL_SUBST_ALL is pro‐
32                                          vided as a convenience for the  com‐
33                                          mon case where all substitutions are
34                                          desired.
35______________________________________________________________________________
36

DESCRIPTION

38       The Tcl_SubstObj function is used to perform substitutions  on  strings
39       in  the  fashion of the subst command.  It gets the value of the string
40       contained in objPtr and scans it, copying characters and performing the
41       chosen substitutions as it goes to an output value which is returned as
42       the result of the function.  In the event of an error occurring  during
43       the  execution  of a command or variable substitution, the function re‐
44       turns NULL and an error message is left in interp's result.
45
46       Three kinds of substitutions are supported.  When  the  TCL_SUBST_BACK‐
47       SLASHES bit is set in flags, sequences that look like backslash substi‐
48       tutions for Tcl commands are replaced by their corresponding character.
49
50       When the TCL_SUBST_VARIABLES bit is set in flags, sequences  that  look
51       like  variable  substitutions for Tcl commands are replaced by the con‐
52       tents of the named variable.
53
54       When the TCL_SUBST_COMMANDS bit is set in flags,  sequences  that  look
55       like  command substitutions for Tcl commands are replaced by the result
56       of evaluating that script.  Where an uncaught “continue exception”  oc‐
57       curs  during  the evaluation of a command substitution, an empty string
58       is substituted for the command.  Where an  uncaught  “break  exception”
59       occurs  during  the evaluation of a command substitution, the result of
60       the whole substitution on objPtr will be truncated at the point immedi‐
61       ately  before  the start of the command substitution, and no characters
62       will be added to the  result  or  substitutions  performed  after  that
63       point.
64

SEE ALSO

66       subst(n)
67

KEYWORDS

69       backslash substitution, command substitution, variable substitution
70
71
72
73Tcl                                   8.4                      Tcl_SubstObj(3)