'\"
'\" Copyright 1989 Regents of the University of California
'\" Permission to use, copy, modify, and distribute this
'\" documentation for any purpose and without fee is hereby
'\" granted, provided that this notice appears in all copies.
'\" The University of California makes no representations about
'\" the suitability of this material for any purpose.  It is
'\" provided "as is" without express or implied warranty.
'\" 
'\" $Id$
'\" 
.so man.macros
.HS Tcl_Eval tcl
.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, flags, termPtr\fR)
.sp
int
\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
.sp
int
\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
.sp
.VS
int
\fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
.VE
.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 (Tcl_Eval makes temporary modifications to the command).
.AP int flags in
Either \fBTCL_BRACKET_TERM\fR or 0.
If 0, then \fBTcl_Eval\fR will process commands from \fIcmd\fR until
it reaches the null character at the end of the string.
If \fBTCL_BRACKET_TERM\fR,
then \fBTcl_Eval\fR will process comands from \fIcmd\fR until either it
reaches a null character or it encounters a close bracket that isn't
backslashed or enclosed in braces, at which point it will return.
Under normal conditions, \fIflags\fR should be 0.
.AP char **termPtr out
If \fItermPtr\fR is non-NULL, \fBTcl_Eval\fR fills in *\fItermPtr\fR with
the address of the character just after the last one in the last command
successfully executed (normally the null character at the end of \fIcmd\fR).
If an error occurs in the first command in \fIcmd\fR, then \fI*termPtr\fR
will be set to \fIcmd\fR.
.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
order until either an error occurs or \fBTcl_Eval\fR reaches a terminating
character (']' or '\e0', depending on the value of \fIflags\fR).
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
.VS
\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''.
.VE
.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