Tcl_EvalObj(3) Tcl Library Procedures Tcl_EvalObj(3)______________________________________________________________________________NAME
Tcl_EvalObj, Tcl_GlobalEvalObj - execute Tcl commands
SYNOPSIS
#include <tcl.h>
int
Tcl_EvalObj(interp, objPtr)
int
Tcl_GlobalEvalObj(interp, objPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to execute the
command. The command's result will
be stored in the interpreter's
result object and can be retrieved
using Tcl_GetObjResult.
Tcl_Obj *objPtr (in) A Tcl object containing a command
string (or sequence of commands in
a string) to execute.
_________________________________________________________________DESCRIPTION
These two procedures execute Tcl commands. Tcl_EvalObj is the core
procedure and is used by Tcl_GlobalEvalObj. It executes the commands
in the script held by objPtr until either an error occurs or it reaches
the end of the script. If this is the first time objPtr has been exe‐
cuted, its commands are compiled into bytecode instructions that are
then executed if there are no compilation errors.
The return value from Tcl_EvalObj is one of the Tcl return codes
TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, and a result
object containing additional information (a result value or error mes‐
sage) that can be retrieved using Tcl_GetObjResult. If an error occurs
during compilation, this return information describes the error. Oth‐
erwise, this return information corresponds to the last command exe‐
cuted from objPtr.
Tcl_GlobalEvalObj is similar to Tcl_EvalObj 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 pro‐
cedure that is active). This produces an effect similar to the Tcl
command ``uplevel 0''.
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_EvalObj 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_EvalObj keeps track of how many nested Tcl_EvalObj invocations are
in progress for interp. If a code of TCL_RETURN, TCL_BREAK, or
TCL_CONTINUE is about to be returned from the topmost Tcl_EvalObj invo‐
cation for interp, it converts the return code to TCL_ERROR and sets
the interpreter's result object to point to an error message indicating
that the return, break, or continue command was invoked in an inappro‐
priate place. This means that top-level applications should never see
a return code from Tcl_EvalObj other then TCL_OK or TCL_ERROR.
SEE ALSO
Tcl_GetObjResult, Tcl_SetObjResult
KEYWORDS
command, execute, file, global, object, object result, variable
Tcl 8.0 Tcl_EvalObj(3)
