diff options
Diffstat (limited to 'doc/Eval.3')
| -rw-r--r-- | doc/Eval.3 | 196 |
1 files changed, 0 insertions, 196 deletions
diff --git a/doc/Eval.3 b/doc/Eval.3 deleted file mode 100644 index bc0effc..0000000 --- a/doc/Eval.3 +++ /dev/null @@ -1,196 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: Eval.3,v 1.4 1999/04/16 00:46:31 stanton Exp $ -'\" -.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 <tcl.h>\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 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 char *script in -Points to first byte of script to execute. This script must be in -writable memory: temporary modifications are made to it during -parsing. -.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. -.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 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 -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 |