NAME
Tcl_Eval - execute a Tcl command string

SYNOPSIS
#include <tcl.h>

int
Tcl_Eval(interp, cmd, flags, termPtr)

ARGUMENTS
Interpreter in which to execute the command. String result will be stored in interp->result. Command (or sequence of commands) to execute. Either TCL_BRACKET_TERM or 0. If 0, then Tcl_Eval will process commands from cmd until it reaches the null character at the end of the string; newlines will be treated as command separators. If TCL_BRACKET_TERM, then Tcl_Eval will process comands from cmd 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; newlines will treated as white space, not as command separators. Under normal conditions, flags should be 0. If termPtr is non-NULL, Tcl_Eval fills in *termPtr 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 cmd). If an error occurs in the first command in cmd, then *termPtr will be set to cmd.

DESCRIPTION

Tcl_Eval parses commands from cmd and executes them in order until either an error occurs or Tcl_Eval reaches a terminating character (']' or ' ', depending on the value of flags). 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 (result value or error message). This return information corresponds to the last command executed from cmd.

During the processing of a command it is legal to make nested calls to Tcl_Eval (this is how conditionals, loops, and procedures 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_CONTINUE is about to be returned from the topmost Tcl_Eval invocation for interp, then Tcl_Eval 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.

KEYWORDS
command, execute, interpreter