Initial revision

1 files changed, 114 insertions, 0 deletions

diff --git a/doc/Eval.3 b/doc/Eval.3
new file mode 100644
index 0000000..f100697
--- /dev/null
+++ b/doc/Eval.3
@@ -0,0 +1,114 @@
+'\"
+'\" 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.
+'\" 
+'\" SCCS: @(#) Eval.3 1.21 97/01/22 14:22:03
+'\" 
+.so man.macros
+.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+int
+\fBTcl_Eval\fR(\fIinterp, cmd\fR)
+.sp
+int
+\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
+.sp
+int
+\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
+.sp
+int
+\fBTcl_GlobalEval\fR(\fIinterp, cmd\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).
+.AP char *string in
+String forming part of Tcl command.
+.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.
+.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.
+.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.
+.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.
+The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
+of arguments.
+.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.
+.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,
+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_Eval\fR keeps track of how many nested \fBTcl_Eval\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
+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
+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
+
+.SH KEYWORDS
+command, execute, file, global, object, object result, variable