Tcl_Eval (3)
execute Tcl commands
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 **termPtr;
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 executed.
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, 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.
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_CONTINUE 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
'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
'\" RCS: @(#) $Id: TraceVar.3,v 1.2 1998/09/14 18:39:50 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|
