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

NAME

8       Tcl_EvalObjEx,   Tcl_EvalFile,   Tcl_EvalObjv,   Tcl_Eval,  Tcl_EvalEx,
9       Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA - execute
10       Tcl scripts
11

SYNOPSIS

13       #include <tcl.h>
14
15       int
16       Tcl_EvalObjEx(interp, objPtr, flags)
17
18       int
19       Tcl_EvalFile(interp, fileName)
20
21       int
22       Tcl_EvalObjv(interp, objc, objv, flags)
23
24       int
25       Tcl_Eval(interp, script)
26
27       int
28       Tcl_EvalEx(interp, script, numBytes, flags)
29
30       int
31       Tcl_GlobalEval(interp, script)
32
33       int
34       Tcl_GlobalEvalObj(interp, objPtr)
35
36       int
37       Tcl_VarEval(interp, part, part, ... (char *) NULL)
38
39       int
40       Tcl_VarEvalVA(interp, argList)
41

ARGUMENTS

43       Tcl_Interp *interp (in)            Interpreter  in which to execute the
44                                          script.  The interpreter's result is
45                                          modified to hold the result or error
46                                          message from the script.
47
48       Tcl_Obj *objPtr (in)               A Tcl value containing the script to
49                                          execute.
50
51       int flags (in)                     ORed  combination  of flag bits that
52                                          specify     additional      options.
53                                          TCL_EVAL_GLOBAL  and TCL_EVAL_DIRECT
54                                          are currently supported.
55
56       const char *fileName (in)          Name of  a  file  containing  a  Tcl
57                                          script.
58
59       int objc (in)                      The  number  of  values in the array
60                                          pointed to by objPtr; this  is  also
61                                          the number of words in the command.
62
63       Tcl_Obj **objv (in)                Points  to  an  array of pointers to
64                                          values; each value holds  the  value
65                                          of  a  single word in the command to
66                                          execute.
67
68       int numBytes (in)                  The number of bytes in  script,  not
69                                          including any null terminating char‐
70                                          acter.  If -1, then  all  characters
71                                          up to the first null byte are used.
72
73       const char *script (in)            Points  to  first  byte of script to
74                                          execute (null-terminated and UTF-8).
75
76       char *part (in)                    String forming part of a Tcl script.
77
78       va_list argList (in)               An argument  list  which  must  have
79                                          been initialized using va_start, and
80                                          cleared using va_end.
81______________________________________________________________________________
82
83

DESCRIPTION

85       The procedures described here are invoked to  execute  Tcl  scripts  in
86       various forms.  Tcl_EvalObjEx is the core procedure and is used by many
87       of the others.  It executes the commands in the script stored in objPtr
88       until  either  an error occurs or the end of the script is reached.  If
89       this is the first time objPtr has been executed, its commands are  com‐
90       piled  into  bytecode  instructions which are then executed.  The byte‐
91       codes are saved in objPtr so that the compilation step can  be  skipped
92       if the value is evaluated again in the future.
93
94       The  return  value  from  Tcl_EvalObjEx  (and  all the other procedures
95       described here) is a Tcl completion code with one of the values TCL_OK,
96       TCL_ERROR,  TCL_RETURN,  TCL_BREAK,  or  TCL_CONTINUE, or possibly some
97       other integer value originating in an extension.  In addition, a result
98       value  or error message is left in interp's result; it can be retrieved
99       using Tcl_GetObjResult.
100
101       Tcl_EvalFile reads the file given by fileName and  evaluates  its  con‐
102       tents  as a Tcl script.  It returns the same information as Tcl_EvalOb‐
103       jEx.  If the file could not be read then a Tcl  error  is  returned  to
104       describe  why  the  file  could  not be read.  The eofchar for files is
105       “\32” (^Z) for all platforms. If you require a “^Z” in code for  string
106       comparison,  you  can use “\032” or “\u001a”, which will be safely sub‐
107       stituted by the Tcl interpreter into “^Z”.
108
109       Tcl_EvalObjv executes a single pre-parsed command instead of a  script.
110       The objc and objv arguments contain the values of the words for the Tcl
111       command, one word in each value in objv.   Tcl_EvalObjv  evaluates  the
112       command  and returns a completion code and result just like Tcl_EvalOb‐
113       jEx.  The caller of Tcl_EvalObjv has to manage the reference  count  of
114       the  elements  of  objv,  insuring  that  the  values  are  valid until
115       Tcl_EvalObjv returns.
116
117       Tcl_Eval is similar to Tcl_EvalObjEx except that the script to be  exe‐
118       cuted  is  supplied  as  a string instead of a value and no compilation
119       occurs.  The string should be a proper UTF-8  string  as  converted  by
120       Tcl_ExternalToUtfDString  or Tcl_ExternalToUtf when it is known to pos‐
121       sibly contain upper ASCII characters whose possible combinations  might
122       be  a  UTF-8  special code.  The string is parsed and executed directly
123       (using Tcl_EvalObjv) instead of compiling it and  executing  the  byte‐
124       codes.   In  situations where it is known that the script will never be
125       executed again, Tcl_Eval may be faster than Tcl_EvalObjEx.
126        Tcl_Eval returns a completion code and result just like Tcl_EvalObjEx.
127       Note: for backward compatibility with versions before Tcl 8.0, Tcl_Eval
128       copies the value result in interp to interp->result (use is deprecated)
129       where it can be accessed directly.
130        This makes Tcl_Eval somewhat slower than Tcl_EvalEx, which does not do
131       the copy.
132
133       Tcl_EvalEx is an extended version of  Tcl_Eval  that  takes  additional
134       arguments  numBytes  and flags.  For the efficiency reason given above,
135       Tcl_EvalEx is generally preferred over Tcl_Eval.
136
137       Tcl_GlobalEval and Tcl_GlobalEvalObj are older procedures that are  now
138       deprecated.   They  are  similar to Tcl_EvalEx and Tcl_EvalObjEx except
139       that the script is evaluated in the global namespace and  its  variable
140       context  consists  of  global variables only (it ignores any Tcl proce‐
141       dures that are active).  These functions are equivalent  to  using  the
142       TCL_EVAL_GLOBAL flag (see below).
143
144       Tcl_VarEval  takes  any  number of string arguments of any length, con‐
145       catenates them into a single string, then  calls  Tcl_Eval  to  execute
146       that string as a Tcl command.  It returns the result of the command and
147       also modifies interp->result in the same way  as  Tcl_Eval.   The  last
148       argument  to Tcl_VarEval must be NULL to indicate the end of arguments.
149       Tcl_VarEval is now deprecated.
150
151       Tcl_VarEvalVA is the same as Tcl_VarEval except that instead of  taking
152       a  variable  number  of  arguments  it  takes  an  argument  list. Like
153       Tcl_VarEval, Tcl_VarEvalVA is deprecated.
154
155

FLAG BITS

157       Any ORed combination of the following values may be used for the  flags
158       argument to procedures such as Tcl_EvalObjEx:
159
160       TCL_EVAL_DIRECT        This  flag  is only used by Tcl_EvalObjEx; it is
161                              ignored by other procedures.  If this  flag  bit
162                              is set, the script is not compiled to bytecodes;
163                              instead it is executed directly as  is  done  by
164                              Tcl_EvalEx.   The TCL_EVAL_DIRECT flag is useful
165                              in situations where the contents of a value  are
166                              going  to  change  immediately, so the bytecodes
167                              will not be reused in a  future  execution.   In
168                              this  case,  it  is faster to execute the script
169                              directly.
170
171       TCL_EVAL_GLOBAL        If this flag is set, the script is processed  at
172                              global  level.   This means that it is evaluated
173                              in the global namespace and its variable context
174                              consists  of  global  variables only (it ignores
175                              any Tcl procedures that are active).
176
177

MISCELLANEOUS DETAILS

179       During the processing of a Tcl command it is legal to make nested calls
180       to  evaluate  other  commands  (this is how procedures and some control
181       structures are implemented).  If a code other than TCL_OK  is  returned
182       from a nested Tcl_EvalObjEx invocation, then the caller should normally
183       return immediately, passing that same return code back to  its  caller,
184       and  so on until the top-level application is reached.  A few commands,
185       like for, will check for  certain  return  codes,  like  TCL_BREAK  and
186       TCL_CONTINUE, and process them specially without returning.
187
188       Tcl_EvalObjEx  keeps track of how many nested Tcl_EvalObjEx invocations
189       are in progress for interp.  If a code  of  TCL_RETURN,  TCL_BREAK,  or
190       TCL_CONTINUE  is  about  to  be returned from the topmost Tcl_EvalObjEx
191       invocation for interp, it converts the return  code  to  TCL_ERROR  and
192       sets  interp's  result  to an error message indicating that the return,
193       break, or continue command was invoked in an inappropriate place.  This
194       means  that  top-level applications should never see a return code from
195       Tcl_EvalObjEx other than TCL_OK or TCL_ERROR.
196
197

KEYWORDS

199       execute, file, global, result, script, value
200
201
202
203Tcl                                   8.1                          Tcl_Eval(3)
Impressum