merged tcl 8.1 branch back into the main trunk

1 files changed, 130 insertions, 57 deletions

diff --git a/doc/Eval.3 b/doc/Eval.3
index 42e77ae..bc0effc 100644
--- a/doc/Eval.3
+++ b/doc/Eval.3
@@ -5,97 +5,173 @@
 '\" 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.3 1999/03/10 05:52:45 stanton Exp $
+'\" RCS: @(#) $Id: Eval.3,v 1.4 1999/04/16 00:46:31 stanton Exp $
 '\" 
 .so man.macros
-.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
+.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_Eval, Tcl_VarEval, Tcl_VarEvalVA, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
+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_Eval\fR(\fIinterp, cmd\fR)
+\fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
 .sp
 int
-\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
+\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
 .sp
 int
-\fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
+\fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR)
 .sp
 int
-\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
+\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_GlobalEval\fR(\fIinterp, cmd\fR)
+\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 command.
-A string result will be stored in \fIinterp->result\fR.
-.AP char *cmd in
-Command (or sequence of commands) to execute.  Must be in writable
-memory (\fBTcl_Eval\fR makes temporary modifications to the command).
+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 Tcl command.
+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.
-.AP char *fileName in
-Name of file containing Tcl command string.
 .BE
 
 .SH DESCRIPTION
 .PP
-All four of these procedures execute Tcl commands.
-\fBTcl_Eval\fR is the core procedure and is used by all the others.
-It executes the commands in the script held by \fIcmd\fR
-until either an error occurs or it reaches the end of the script.
+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
-Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR
-have been largely replaced by the
-object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR.
-Those object-based procedures evaluate a script held in a Tcl object
-instead of a string.
-The object argument can retain the bytecode instructions for the script
-and so avoid reparsing the script each time it is executed.
-\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR
-but is slower because it must reparse the script each time
-since there is no object to retain the bytecode instructions.
+\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
-The return value from \fBTcl_Eval\fR is one of the Tcl return codes
-\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
-\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
-a string with additional information (a result value or error message).
-If an error occurs during compilation, this return information
-describes the error.
-Otherwise, this return information corresponds to the last command
-executed from \fIcmd\fR.
+\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 usual fashion for Tcl commands.
+\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.
+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.
-.PP
-\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
-its contents as a Tcl command by calling \fBTcl_Eval\fR.  It returns
-a standard Tcl result that reflects the result of evaluating the file.
-If the file couldn't be read then a Tcl error is returned to describe
-why the file couldn't be read.
+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_Eval\fR invocation,
+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.
@@ -103,21 +179,18 @@ 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_Eval\fR keeps track of how many nested \fBTcl_Eval\fR
+\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_Eval\fR
+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->result\fR
-to point to an error message indicating that
+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_Eval\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
-
-.SH "SEE ALSO"
-Tcl_EvalObj, Tcl_GlobalEvalObj
+from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
+.VE
 
 .SH KEYWORDS
-command, execute, file, global, object, object result, variable
+execute, file, global, object, result, script