X-Git-Url: http://git.osdn.net/view?a=blobdiff_plain;f=tcl%2Fdoc%2FEval.3;fp=tcl%2Fdoc%2FEval.3;h=70595e9b6f1fb855f7490ce0e847e22048469fe3;hb=ae4bf010374a9320497af260fa90af3fe8e2c5a5;hp=0000000000000000000000000000000000000000;hpb=3cc729069938336ea54d399c4bbbe7d197295f9a;p=pf3gnuchains%2Fpf3gnuchains3x.git diff --git a/tcl/doc/Eval.3 b/tcl/doc/Eval.3 new file mode 100644 index 0000000000..70595e9b6f --- /dev/null +++ b/tcl/doc/Eval.3 @@ -0,0 +1,204 @@ +'\" +'\" Copyright (c) 1989-1993 The Regents of the University of California. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" Copyright (c) 2000 Scriptics Corporation. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts +.SH SYNOPSIS +.nf +\fB#include \fR +.sp +.VS +int +\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR) +.sp +int +\fBTcl_EvalFile\fR(\fIinterp, fileName\fR) +.sp +int +\fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR) +.sp +int +\fBTcl_Eval\fR(\fIinterp, script\fR) +.sp +int +\fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR) +.sp +int +\fBTcl_GlobalEval\fR(\fIinterp, script\fR) +.sp +int +\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr, flags\fR) +.sp +int +\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR) +.sp +int +\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) +.SH ARGUMENTS +.AS Tcl_Interp **termPtr; +.AP Tcl_Interp *interp in +Interpreter in which to execute the script. The interpreter's result is +modified to hold the result or error message from the script. +.AP Tcl_Obj *objPtr in +A Tcl object containing the script to execute. +.AP int flags in +ORed combination of flag bits that specify additional options. +\fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported. +.AP "CONST char" *fileName in +Name of a file containing a Tcl script. +.AP int objc in +The number of objects in the array pointed to by \fIobjPtr\fR; +this is also the number of words in the command. +.AP Tcl_Obj **objv in +Points to an array of pointers to objects; each object holds the +value of a single word in the command to execute. +.AP int numBytes in +The number of bytes in \fIscript\fR, not including any +null terminating character. If \-1, then all characters up to the +first null byte are used. +.AP "CONST char" *script in +Points to first byte of script to execute (NULL terminated and UTF-8). +.AP char *string in +String forming part of a Tcl script. +.AP va_list argList in +An argument list which must have been initialised using +\fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR. +.BE + +.SH DESCRIPTION +.PP +The procedures described here are invoked to execute Tcl scripts in +various forms. +\fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others. +It executes the commands in the script stored in \fIobjPtr\fR +until either an error occurs or the end of the script is reached. +If this is the first time \fIobjPtr\fR has been executed, +its commands are compiled into bytecode instructions +which are then executed. The +bytecodes are saved in \fIobjPtr\fR so that the compilation step +can be skipped if the object is evaluated again in the future. +.PP +The return value from \fBTcl_EvalObjEx\fR (and all the other procedures +described here) is a Tcl completion code with +one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, +\fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. +In addition, a result value or error message is left in \fIinterp\fR's +result; it can be retrieved using \fBTcl_GetObjResult\fR. +.PP +\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates +its contents as a Tcl script. It returns the same information as +\fBTcl_EvalObjEx\fR. +If the file couldn't be read then a Tcl error is returned to describe +why the file couldn't be read. +.VS 8.4 +The eofchar for files is '\\32' (^Z) for all platforms. +If you require a ``^Z'' in code for string comparison, you can use +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl +interpreter into ``^Z''. +.VE 8.4 +.PP +\fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a +script. The \fIobjc\fR and \fIobjv\fR arguments contain the values +of the words for the Tcl command, one word in each object in +\fIobjv\fR. \fBTcl_EvalObjv\fR evaluates the command and returns +a completion code and result just like \fBTcl_EvalObjEx\fR. +.PP +\fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to +be executed is supplied as a string instead of an object and no compilation +occurs. The string should be a proper UTF-8 string as converted by +\fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known +to possibly contain upper ASCII characters who's possible combinations +might be a UTF-8 special code. The string is parsed and executed directly +(using \fBTcl_EvalObjv\fR) instead of compiling it and executing the +bytecodes. In situations where it is known that the script will never be +executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. + \fBTcl_Eval\fR returns a completion code and result just like +\fBTcl_EvalObjEx\fR. Note: for backward compatibility with versions before +Tcl 8.0, \fBTcl_Eval\fR copies the object result in \fIinterp\fR to +\fIinterp->result\fR (use is deprecated) where it can be accessed directly. + This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which +doesn't do the copy. +.PP +\fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes +additional arguments \fInumBytes\fR and \fIflags\fR. For the +efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred +over \fBTcl_Eval\fR. +.PP +\fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures +that are now deprecated. They are similar to \fBTcl_EvalEx\fR and +\fBTcl_EvalObjEx\fR except that the script is evaluated in the global +namespace and its variable context consists of global variables only +(it ignores any Tcl procedures that are active). These functions are +equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). +.PP +\fBTcl_VarEval\fR takes any number of string arguments +of any length, concatenates them into a single string, +then calls \fBTcl_Eval\fR to execute that string as a Tcl command. +It returns the result of the command and also modifies +\fIinterp->result\fR in the same way as \fBTcl_Eval\fR. +The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end +of arguments. \fBTcl_VarEval\fR is now deprecated. +.PP +\fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that +instead of taking a variable number of arguments it takes an argument +list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated. + +.SH "FLAG BITS" +Any ORed combination of the following values may be used for the +\fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR: +.TP 23 +\fBTCL_EVAL_DIRECT\fR +This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by +other procedures. If this flag bit is set, the script is not +compiled to bytecodes; instead it is executed directly +as is done by \fBTcl_EvalEx\fR. The +\fBTCL_EVAL_DIRECT\fR flag is useful in situations where the +contents of an object are going to change immediately, so the +bytecodes won't be reused in a future execution. In this case, +it's faster to execute the script directly. +.TP 23 +\fBTCL_EVAL_GLOBAL\fR +If this flag is set, the script is processed at global level. This +means that it is evaluated in the global namespace and its variable +context consists of global variables only (it ignores any Tcl +procedures at are active). + +.SH "MISCELLANEOUS DETAILS" +.PP +During the processing of a Tcl command it is legal to make nested +calls to evaluate other commands (this is how procedures and +some control structures are implemented). +If a code other than \fBTCL_OK\fR is returned +from a nested \fBTcl_EvalObjEx\fR invocation, +then the caller should normally return immediately, +passing that same return code back to its caller, +and so on until the top-level application is reached. +A few commands, like \fBfor\fR, will check for certain +return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them +specially without returning. +.PP +\fBTcl_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\fR +invocations are in progress for \fIinterp\fR. +If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is +about to be returned from the topmost \fBTcl_EvalObjEx\fR +invocation for \fIinterp\fR, +it converts the return code to \fBTCL_ERROR\fR +and sets \fIinterp\fR's result to an error message indicating that +the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was +invoked in an inappropriate place. +This means that top-level applications should never see a return code +from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.VE + +.SH KEYWORDS +execute, file, global, object, result, script