1 files changed, 106 insertions, 0 deletions
diff --git a/contrib/tcl/doc/Eval.3 b/contrib/tcl/doc/Eval.3
new file mode 100644
index 0000000..f1a78c8
--- /dev/null
+++ b/contrib/tcl/doc/Eval.3
@@ -0,0 +1,106 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 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.17 96/03/25 20:02:33
+'\" 
+.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
+.VS
+\fBTcl_Eval\fR(\fIinterp, cmd\fR)
+.VE
+.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.  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:  it parses commands
+from \fIcmd\fR and executes them in
+.VS
+order until either an error occurs or it reaches the end of the string.
+.VE
+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 (result value or error message).
+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
+\fBTcl_GlobalEval\fR is similar to \fBTcl_Eval\fR except that it
+processes the command at global level.
+This means that the variable context for the command consists of
+global variables only (it ignores any Tcl procedure that is active).
+This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
+.PP
+During the processing of a Tcl command it is legal to make nested
+calls to evaluate other commands (this is how conditionals, loops,
+and procedures 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 Tcl_Eval 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, then \fBTcl_Eval\fR 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 KEYWORDS
+command, execute, file, global, interpreter, variable