Tcl_Eval(3) Tcl Library Procedures Tcl_Eval(3)______________________________________________________________________________NAME
Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval - execute Tcl com‐
mands
SYNOPSIS
#include <tcl.h>
int
Tcl_Eval(interp, cmd)
int
Tcl_VarEval(interp, string, string, ... (char *) NULL)
int
Tcl_EvalFile(interp, fileName)
int
Tcl_GlobalEval(interp, cmd)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to execute the
command. A string result will be
stored in interp->result.
char *cmd (in) Command (or sequence of commands)
to execute. Must be in writable
memory (Tcl_Eval makes temporary
modifications to the command).
char *string (in) String forming part of Tcl command.
char *fileName (in) Name of file containing Tcl command
string.
_________________________________________________________________DESCRIPTION
All four of these procedures execute Tcl commands. Tcl_Eval is the
core procedure and is used by all the others. It executes the commands
in the script held by cmd until either an error occurs or it reaches
the end of the script.
Note that Tcl_Eval and Tcl_GlobalEval have been largely replaced by the
object-based procedures Tcl_EvalObj and Tcl_GlobalEvalObj. 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 exe‐
cuted. Tcl_Eval is implemented using Tcl_EvalObj but is slower because
it must reparse the script each time since there is no object to retain
the bytecode instructions.
The return value from Tcl_Eval is one of the Tcl return codes TCL_OK,
TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, and interp->result
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 cmd.
Tcl_VarEval takes any number of string arguments of any length, con‐
catenates them into a single string, then calls Tcl_Eval to execute
that string as a Tcl command. It returns the result of the command and
also modifies interp->result in the usual fashion for Tcl commands.
The last argument to Tcl_VarEval must be NULL to indicate the end of
arguments.
Tcl_EvalFile reads the file given by fileName and evaluates its con‐
tents as a Tcl command by calling Tcl_Eval. 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.
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 TCL_OK is returned
from a nested Tcl_Eval 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 for, will check for certain return codes, like TCL_BREAK and
TCL_CONTINUE, and process them specially without returning.
Tcl_Eval keeps track of how many nested Tcl_Eval invocations are in
progress for interp. If a code of TCL_RETURN, TCL_BREAK, or TCL_CON‐
TINUE is about to be returned from the topmost Tcl_Eval invocation for
interp, it converts the return code to TCL_ERROR and sets
interp->result to point to an error message indicating that the return,
break, or continue command was invoked in an inappropriate place. This
means that top-level applications should never see a return code from
Tcl_Eval other then TCL_OK or TCL_ERROR.
SEE ALSO
Tcl_EvalObj, Tcl_GlobalEvalObj
KEYWORDS
command, execute, file, global, object, object result, variable
Tcl 7.0 Tcl_Eval(3)