home | help 
Tcl_Eval(3)		     Tcl Library Procedures		     Tcl_Eval(3)

________________________________________________________________________________

NAME
     Tcl_EvalObjEx,  Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_Glob-
     alEval, Tcl_GlobalEvalObj, Tcl_VarEval - execute Tcl scripts

SYNOPSIS
     #include <tcl.h>

     int
     Tcl_EvalObjEx(interp, objPtr, flags)

     int
     Tcl_EvalFile(interp, fileName)

     int
     Tcl_EvalObjv(interp, objc, objv, flags)

     int
     Tcl_Eval(interp, script)

     int
     Tcl_EvalEx(interp, script, numBytes, flags)

     int
     Tcl_GlobalEval(interp, script)

     int
     Tcl_GlobalEvalObj(interp, objPtr)

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

ARGUMENTS
     Tcl_Interp *interp (in)		Interpreter  in  which	to  execute  the
					script.   The  interpreter's  result  is
					modified to hold  the  result  or  error
					message from the script.

     Tcl_Obj *objPtr (in)		A Tcl value containing the script to ex-
					ecute.

     int flags (in)			OR'ed  combination  of	flag  bits  that
					specify       additional	options.
					TCL_EVAL_GLOBAL  and TCL_EVAL_DIRECT are
					currently supported.

     const char *fileName (in)		Name of a file containing a Tcl script.

     Tcl_Size objc (in) 		The  number  of  values  in  the   array
					pointed  to  by  objv;	this is also the
					number of words in the command.

     Tcl_Obj **objv (in)		Points to an array of pointers	to  val-
					ues;  each  value  holds  the value of a
					single word in the command to execute.

     int numBytes (in)			The number of bytes in script,	not  in-
					cluding  any null terminating character.
					If -1, then all  characters  up  to  the
					first null byte are used.

     const char *script (in)		Points	to  first byte of script to exe-
					cute (null-terminated  TUTF-8  byte  se-
					quence).

     const char *part (in)		String forming part of a Tcl script.
________________________________________________________________________________

DESCRIPTION
     N.B.  Refer  to the Tcl_UniChar documentation page for a description of the
     TUTF-8 encoding and related terms referenced here.

     The procedures described here are invoked to execute Tcl scripts in various
     forms.  Tcl_EvalObjEx is the core procedure and is used by many of the oth-
     ers.  It executes the commands in the script stored in objPtr until  either
     an  error occurs or the end of the script is reached.  If this is the first
     time objPtr has been executed, its commands are compiled into bytecode  in-
     structions  which	are then executed.  The bytecodes are saved in objPtr so
     that the compilation step can be skipped if the value is evaluated again in
     the future.

     The return value from Tcl_EvalObjEx (and all the other procedures described
     here) is a Tcl completion code with one of the  values  TCL_OK,  TCL_ERROR,
     TCL_RETURN,  TCL_BREAK,  or  TCL_CONTINUE,  or  possibly some other integer
     value originating in an extension.  In addition, a result	value  or  error
     message is left in interp's result; it can be retrieved using Tcl_GetObjRe-
     sult.

     Tcl_EvalFile reads the file given by fileName and evaluates its contents as
     a	Tcl  script.   It returns the same information as Tcl_EvalObjEx.  If the
     file could not be read then a Tcl error is returned  to  describe	why  the
     file could not be read.  The eofchar for files is "\x1A" (^Z) for all plat-
     forms.  If  you  require  a "^Z" in code for string comparison, you can use
     "\x1A", which will be safely substituted by the Tcl interpreter into "^Z".

     Tcl_EvalObjv executes a single preparsed command instead of a script.   The
     objc  and	objv  arguments contain the values of the words for the Tcl com-
     mand, one word in each value in objv.  Tcl_EvalObjv evaluates  the  command
     and  returns  a  completion  code	and result just like Tcl_EvalObjEx.  The
     caller of Tcl_EvalObjv has to manage the reference count of the elements of
     objv, insuring that the values are valid until Tcl_EvalObjv returns.

     Tcl_Eval is similar to Tcl_EvalObjEx except that the script to be	executed
     is  supplied as a string instead of a value and no compilation occurs.  The
     string should be a proper TUTF-8 byte  sequence  as  converted  by  Tcl_Ex-
     ternalToUtfDString  or  Tcl_ExternalToUtf when it is known to possibly con-
     tain upper ASCII characters whose possible combinations might  be	a  UTF-8
     special  code.  The string is parsed and executed directly (using Tcl_Eval-
     Objv) instead of compiling it and executing the bytecodes.   In  situations
     where  it	is  known that the script will never be executed again, Tcl_Eval
     may be faster than Tcl_EvalObjEx.
      Tcl_Eval returns a completion code and result just like Tcl_EvalObjEx.

     Tcl_EvalEx is an extended version of Tcl_Eval that takes  additional  argu-
     ments numBytes and flags.

     Tcl_GlobalEval and Tcl_GlobalEvalObj are older procedures that are now dep-
     recated.	They are similar to Tcl_EvalEx and Tcl_EvalObjEx except that the
     script is evaluated in the global namespace and its variable  context  con-
     sists  of global variables only (it ignores any Tcl procedures that are ac-
     tive).  These functions are equivalent to using  the  TCL_EVAL_GLOBAL  flag
     (see below).

     Tcl_VarEval  takes  any  number of string arguments of any length, concate-
     nates 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
     the  interpreter  result in the same way as Tcl_Eval.  The last argument to
     Tcl_VarEval must be (char *)NULL to indicate the end of arguments.

FLAG BITS
     Any OR'ed combination of the following values may be used for the flags ar-
     gument to procedures such as Tcl_EvalObjEx:

     TCL_EVAL_DIRECT	    This flag is only used by Tcl_EvalObjEx; it  is  ig-
			    nored by other procedures.	If this flag bit is set,
			    the  script is not compiled to bytecodes; instead it
			    is executed directly as is done by Tcl_EvalEx.   The
			    TCL_EVAL_DIRECT  flag  is useful in situations where
			    the contents of a value are going to change  immedi-
			    ately,  so the bytecodes will not be reused in a fu-
			    ture execution.  In this case, it is faster to  exe-
			    cute the script directly.

     TCL_EVAL_GLOBAL	    If	this flag is set, the script is evaluated in the
			    global namespace instead of  the  current  namespace
			    and  its  variable	context consists of global vari-
			    ables only (it ignores any Tcl procedures  that  are
			    active).

MISCELLANEOUS DETAILS
     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_EvalObjEx  invocation,  then  the caller should normally return immedi-
     ately, 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_EvalObjEx  keeps track of how many nested Tcl_EvalObjEx 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_EvalObjEx invocation for
     interp,  it  converts the return code to TCL_ERROR and sets interp's result
     to an error message indicating that the return, break, or continue  command
     was  invoked in an inappropriate place.  This means that top-level applica-
     tions should never see a return code from Tcl_EvalObjEx other  than  TCL_OK
     or TCL_ERROR.

REFERENCE COUNT MANAGEMENT
     Tcl_EvalObjEx and Tcl_GlobalEvalObj both increment and decrement the refer-
     ence  count of their objPtr argument; you must not pass them any value with
     a reference count of zero. They also manipulate the interpreter result; you
     must not count on the interpreter result to hold the reference count of any
     value over these calls.

     Tcl_EvalObjv may increment and decrement the reference count of  any  value
     passed  via its objv argument; you must not pass any value with a reference
     count of zero. This function also manipulates the interpreter  result;  you
     must not count on the interpreter result to hold the reference count of any
     value over this call.

KEYWORDS
     execute, file, global, result, script, value

Tcl				       8.1			     Tcl_Eval(3)
home | help