'\"
'\" 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.2.4.1 1999/03/03 00:38:36 stanton Exp $
'\" 
.so man.macros
.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_Eval, Tcl_VarEval, Tcl_VarEvalVA, 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_VarEvalVA\fR(\fIinterp, argList\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 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.
.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_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.
.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