1 | '\" |
---|
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
4 | '\" Copyright (c) 2000 Scriptics Corporation. |
---|
5 | '\" |
---|
6 | '\" See the file "license.terms" for information on usage and redistribution |
---|
7 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
8 | '\" |
---|
9 | '\" RCS: @(#) $Id: Eval.3,v 1.27 2007/12/13 15:22:31 dgp Exp $ |
---|
10 | '\" |
---|
11 | .so man.macros |
---|
12 | .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" |
---|
13 | .BS |
---|
14 | .SH NAME |
---|
15 | Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts |
---|
16 | .SH SYNOPSIS |
---|
17 | .nf |
---|
18 | \fB#include <tcl.h>\fR |
---|
19 | .sp |
---|
20 | int |
---|
21 | \fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR) |
---|
22 | .sp |
---|
23 | int |
---|
24 | \fBTcl_EvalFile\fR(\fIinterp, fileName\fR) |
---|
25 | .sp |
---|
26 | int |
---|
27 | \fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR) |
---|
28 | .sp |
---|
29 | int |
---|
30 | \fBTcl_Eval\fR(\fIinterp, script\fR) |
---|
31 | .sp |
---|
32 | int |
---|
33 | \fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR) |
---|
34 | .sp |
---|
35 | int |
---|
36 | \fBTcl_GlobalEval\fR(\fIinterp, script\fR) |
---|
37 | .sp |
---|
38 | int |
---|
39 | \fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR) |
---|
40 | .sp |
---|
41 | int |
---|
42 | \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR) |
---|
43 | .sp |
---|
44 | int |
---|
45 | \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) |
---|
46 | .SH ARGUMENTS |
---|
47 | .AS Tcl_Interp **termPtr |
---|
48 | .AP Tcl_Interp *interp in |
---|
49 | Interpreter in which to execute the script. The interpreter's result is |
---|
50 | modified to hold the result or error message from the script. |
---|
51 | .AP Tcl_Obj *objPtr in |
---|
52 | A Tcl object containing the script to execute. |
---|
53 | .AP int flags in |
---|
54 | ORed combination of flag bits that specify additional options. |
---|
55 | \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. |
---|
56 | .AP "const char" *fileName in |
---|
57 | Name of a file containing a Tcl script. |
---|
58 | .AP int objc in |
---|
59 | The number of objects in the array pointed to by \fIobjPtr\fR; |
---|
60 | this is also the number of words in the command. |
---|
61 | .AP Tcl_Obj **objv in |
---|
62 | Points to an array of pointers to objects; each object holds the |
---|
63 | value of a single word in the command to execute. |
---|
64 | .AP int numBytes in |
---|
65 | The number of bytes in \fIscript\fR, not including any |
---|
66 | null terminating character. If \-1, then all characters up to the |
---|
67 | first null byte are used. |
---|
68 | .AP "const char" *script in |
---|
69 | Points to first byte of script to execute (null-terminated and UTF-8). |
---|
70 | .AP char *part in |
---|
71 | String forming part of a Tcl script. |
---|
72 | .AP va_list argList in |
---|
73 | An argument list which must have been initialized using |
---|
74 | \fBva_start\fR, and cleared using \fBva_end\fR. |
---|
75 | .BE |
---|
76 | |
---|
77 | .SH DESCRIPTION |
---|
78 | .PP |
---|
79 | The procedures described here are invoked to execute Tcl scripts in |
---|
80 | various forms. |
---|
81 | \fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others. |
---|
82 | It executes the commands in the script stored in \fIobjPtr\fR |
---|
83 | until either an error occurs or the end of the script is reached. |
---|
84 | If this is the first time \fIobjPtr\fR has been executed, |
---|
85 | its commands are compiled into bytecode instructions |
---|
86 | which are then executed. The |
---|
87 | bytecodes are saved in \fIobjPtr\fR so that the compilation step |
---|
88 | can be skipped if the object is evaluated again in the future. |
---|
89 | .PP |
---|
90 | The return value from \fBTcl_EvalObjEx\fR (and all the other procedures |
---|
91 | described here) is a Tcl completion code with |
---|
92 | one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, |
---|
93 | \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly some other |
---|
94 | integer value originating in an extension. |
---|
95 | In addition, a result value or error message is left in \fIinterp\fR's |
---|
96 | result; it can be retrieved using \fBTcl_GetObjResult\fR. |
---|
97 | .PP |
---|
98 | \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates |
---|
99 | its contents as a Tcl script. It returns the same information as |
---|
100 | \fBTcl_EvalObjEx\fR. |
---|
101 | If the file could not be read then a Tcl error is returned to describe |
---|
102 | why the file could not be read. |
---|
103 | The eofchar for files is |
---|
104 | .QW \e32 |
---|
105 | (^Z) for all platforms. If you require a |
---|
106 | .QW ^Z |
---|
107 | in code for string comparison, you can use |
---|
108 | .QW \e032 |
---|
109 | or |
---|
110 | .QW \eu001a , |
---|
111 | which will be safely substituted by the Tcl interpreter into |
---|
112 | .QW ^Z . |
---|
113 | .PP |
---|
114 | \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a |
---|
115 | script. The \fIobjc\fR and \fIobjv\fR arguments contain the values |
---|
116 | of the words for the Tcl command, one word in each object in |
---|
117 | \fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns |
---|
118 | a completion code and result just like \fBTcl_EvalObjEx\fR. |
---|
119 | The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the |
---|
120 | elements of \fIobjv\fR, insuring that the objects are valid until |
---|
121 | \fBTcl_EvalObjv\fR returns. |
---|
122 | .PP |
---|
123 | \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to |
---|
124 | be executed is supplied as a string instead of an object and no compilation |
---|
125 | occurs. The string should be a proper UTF-8 string as converted by |
---|
126 | \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known |
---|
127 | to possibly contain upper ASCII characters whose possible combinations |
---|
128 | might be a UTF-8 special code. The string is parsed and executed directly |
---|
129 | (using \fBTcl_EvalObjv\fR) instead of compiling it and executing the |
---|
130 | bytecodes. In situations where it is known that the script will never be |
---|
131 | executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. |
---|
132 | \fBTcl_Eval\fR returns a completion code and result just like |
---|
133 | \fBTcl_EvalObjEx\fR. Note: for backward compatibility with versions before |
---|
134 | Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to |
---|
135 | \fIinterp->result\fR (use is deprecated) where it can be accessed directly. |
---|
136 | This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which |
---|
137 | does not do the copy. |
---|
138 | .PP |
---|
139 | \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes |
---|
140 | additional arguments \fInumBytes\fR and \fIflags\fR. For the |
---|
141 | efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred |
---|
142 | over \fBTcl_Eval\fR. |
---|
143 | .PP |
---|
144 | \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures |
---|
145 | that are now deprecated. They are similar to \fBTcl_EvalEx\fR and |
---|
146 | \fBTcl_EvalObjEx\fR except that the script is evaluated in the global |
---|
147 | namespace and its variable context consists of global variables only |
---|
148 | (it ignores any Tcl procedures that are active). These functions are |
---|
149 | equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). |
---|
150 | .PP |
---|
151 | \fBTcl_VarEval\fR takes any number of string arguments |
---|
152 | of any length, concatenates them into a single string, |
---|
153 | then calls \fBTcl_Eval\fR to execute that string as a Tcl command. |
---|
154 | It returns the result of the command and also modifies |
---|
155 | \fIinterp->result\fR in the same way as \fBTcl_Eval\fR. |
---|
156 | The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end |
---|
157 | of arguments. \fBTcl_VarEval\fR is now deprecated. |
---|
158 | .PP |
---|
159 | \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that |
---|
160 | instead of taking a variable number of arguments it takes an argument |
---|
161 | list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. |
---|
162 | |
---|
163 | .SH "FLAG BITS" |
---|
164 | Any ORed combination of the following values may be used for the |
---|
165 | \fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR: |
---|
166 | .TP 23 |
---|
167 | \fBTCL_EVAL_DIRECT\fR |
---|
168 | This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by |
---|
169 | other procedures. If this flag bit is set, the script is not |
---|
170 | compiled to bytecodes; instead it is executed directly |
---|
171 | as is done by \fBTcl_EvalEx\fR. The |
---|
172 | \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the |
---|
173 | contents of an object are going to change immediately, so the |
---|
174 | bytecodes will not be reused in a future execution. In this case, |
---|
175 | it is faster to execute the script directly. |
---|
176 | .TP 23 |
---|
177 | \fBTCL_EVAL_GLOBAL\fR |
---|
178 | If this flag is set, the script is processed at global level. This |
---|
179 | means that it is evaluated in the global namespace and its variable |
---|
180 | context consists of global variables only (it ignores any Tcl |
---|
181 | procedures at are active). |
---|
182 | |
---|
183 | .SH "MISCELLANEOUS DETAILS" |
---|
184 | .PP |
---|
185 | During the processing of a Tcl command it is legal to make nested |
---|
186 | calls to evaluate other commands (this is how procedures and |
---|
187 | some control structures are implemented). |
---|
188 | If a code other than \fBTCL_OK\fR is returned |
---|
189 | from a nested \fBTcl_EvalObjEx\fR invocation, |
---|
190 | then the caller should normally return immediately, |
---|
191 | passing that same return code back to its caller, |
---|
192 | and so on until the top-level application is reached. |
---|
193 | A few commands, like \fBfor\fR, will check for certain |
---|
194 | return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them |
---|
195 | specially without returning. |
---|
196 | .PP |
---|
197 | \fBTcl_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\fR |
---|
198 | invocations are in progress for \fIinterp\fR. |
---|
199 | If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is |
---|
200 | about to be returned from the topmost \fBTcl_EvalObjEx\fR |
---|
201 | invocation for \fIinterp\fR, |
---|
202 | it converts the return code to \fBTCL_ERROR\fR |
---|
203 | and sets \fIinterp\fR's result to an error message indicating that |
---|
204 | the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was |
---|
205 | invoked in an inappropriate place. |
---|
206 | This means that top-level applications should never see a return code |
---|
207 | from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. |
---|
208 | |
---|
209 | .SH KEYWORDS |
---|
210 | execute, file, global, object, result, script |
---|