diff options
Diffstat (limited to 'doc/Eval.3')
| -rw-r--r-- | doc/Eval.3 | 60 |
1 files changed, 31 insertions, 29 deletions
@@ -6,10 +6,8 @@ '\" 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.9 2000/09/19 19:36:55 davidg Exp $ -'\" -.so man.macros .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts @@ -17,7 +15,6 @@ Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, .nf \fB#include <tcl.h>\fR .sp -.VS int \fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR) .sp @@ -37,15 +34,15 @@ int \fBTcl_GlobalEval\fR(\fIinterp, script\fR) .sp int -\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr, flags\fR) +\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR) .sp int -\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR) +\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR) .sp int \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR) .SH ARGUMENTS -.AS Tcl_Interp **termPtr; +.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. @@ -54,7 +51,7 @@ 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 +.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; @@ -66,15 +63,13 @@ value of a single word in the command to execute. 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 (NULL terminated and UTF-8). -This script must be in writable memory: temporary modifications are made -to it during parsing. -.AP char *string in +.AP "const char" *script in +Points to first byte of script to execute (null-terminated and UTF-8). +.AP char *part 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. +An argument list which must have been initialized using +\fBva_start\fR, and cleared using \fBva_end\fR. .BE .SH DESCRIPTION @@ -93,33 +88,41 @@ can be skipped if the object is evaluated again in the future. 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. +\fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly some other +integer value originating in an extension. 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 +If the file could not be read then a Tcl error is returned to describe +why the file could not be read. +The eofchar for files is +.QW \e32 +(^Z) for all platforms. If you require a +.QW ^Z +in code for string comparison, you can use +.QW \e032 +or +.QW \eu001a , +which will be safely substituted by the Tcl interpreter into +.QW ^Z . .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. +The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the +elements of \fIobjv\fR, insuring that the objects are valid until +\fBTcl_EvalObjv\fR returns. .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 +to possibly contain upper ASCII characters whose 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 @@ -129,7 +132,7 @@ executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR. 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. +does not 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 @@ -166,8 +169,8 @@ 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. +bytecodes will not be reused in a future execution. In this case, +it is 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 @@ -200,7 +203,6 @@ 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 |