Tcl - Tcl_Eval (3)

Tcl Library Procedures

NAME

Tcl_Eval, Tcl_EvalObj, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval, Tcl_GlobalEvalObj - execute Tcl commands

SYNOPSIS

#include <tcl.h>

int
Tcl_EvalObj(interp, objPtr)

int
Tcl_Eval(interp, cmd)

int
Tcl_VarEval(interp, string, string, ... (char *) NULL)

int
Tcl_EvalFile(interp, fileName)

int
Tcl_GlobalEvalObj(interp, objPtr)

int
Tcl_GlobalEval(interp, cmd)

ARGUMENTS

Tcl_Interp *interp (in): Interpreter in which to execute the command. An object result will be stored in interp->objResult by Tcl_EvalObj and Tcl_GlobalEvalObj. Otherwise, a string result will be stored in interp->result.
Tcl_Obj *objPtr (in): A Tcl object containing a command string (or sequence of commands in a string) to execute.
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 six of these procedures execute Tcl commands. Tcl_EvalObj is the core procedure and is used by all the others. 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 executed, 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 interp->objResult will point to a Tcl object containing 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 objPtr. The return object can be retrieved using Tcl_GetObjResult.

Tcl_Eval resembles Tcl_EvalObj but executes commands in the string cmd and returns a string result in interp->result. Tcl_EvalObj is faster, especially if the commands are evaluated more than once. Tcl_Eval executes commands until either an error occurs or it reaches the end of the string. The return value from Tcl_Eval is one of the return codes TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE, and interp->result will point to a string with additional information (result value or error message). This return information corresponds to the last command executed from cmd.

Tcl_VarEval takes any number of string arguments of any length, concatenates 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 contents 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.

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 procedure that is active). This produces an effect similar to the Tcl command ``uplevel 0''.

Tcl_GlobalEval is similar to Tcl_GlobalEvalObj but it executes commands in a string rather than a Tcl object and returns a result in interp->result instead of interp->objResult. Tcl_GlobalEvalObj is usually faster, especially if the commands are evaluated more than once. Tcl_GlobalEval processes the command at global level: the variable context consists of global variables only (it ignores any Tcl procedure that is active). This also 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 or 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.

Both Tcl_EvalObj and Tcl_Eval keep 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 or Tcl_Eval invocation for interp, the two procedures convert the return code to TCL_ERROR and set interp->objResult or interp->result, respectively, 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.

KEYWORDS

command, execute, file, global, object, object result, variable

Last change: 7.0