tcl/doc/Eval.3

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