[25] | 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 |
---|