DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_Eval(3)




Tcl_Eval(3)          Tcl Library Procedures           Tcl_Eval(3)

_________________________________________________________________


NAME

     Tcl_EvalObjEx,   Tcl_EvalFile,    Tcl_EvalObjv,    Tcl_Eval,
     Tcl_EvalEx,  Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval,
     Tcl_VarEvalVA - 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)

     int
     Tcl_VarEvalVA(interp, argList)


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  object  containing
                                        the script to execute.

     int flags (in)                     ORed combination of  flag
                                        bits  that  specify addi-
                                        tional           options.
                                        TCL_EVAL_GLOBAL       and

Tcl                     Last change: 8.1                        1

Tcl_Eval(3)          Tcl Library Procedures           Tcl_Eval(3)

                                        TCL_EVAL_DIRECT       are
                                        currently supported.

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

     int objc (in)                      The number of objects  in
                                        the  array  pointed to by
                                        objPtr; this is also  the
                                        number  of  words  in the
                                        command.

     Tcl_Obj **objv (in)                Points  to  an  array  of
                                        pointers to objects; each
                                        object holds the value of
                                        a single word in the com-
                                        mand to execute.

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

     const char *script (in)            Points to first  byte  of
                                        script  to execute (null-
                                        terminated and UTF-8).

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

     va_list argList (in)               An  argument  list  which
                                        must  have  been initial-
                                        ized using va_start,  and
                                        cleared using va_end.
_________________________________________________________________


DESCRIPTION

     The procedures described here are  invoked  to  execute  Tcl
     scripts  in  various  forms.  Tcl_EvalObjEx is the core pro-
     cedure and is used by many of the others.  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 instructions which are then executed.
     The  bytecodes  are  saved in objPtr so that the compilation
     step can be skipped if the object is evaluated again in  the
     future.

Tcl                     Last change: 8.1                        2

Tcl_Eval(3)          Tcl Library Procedures           Tcl_Eval(3)

     The return value from Tcl_EvalObjEx (and all the other  pro-
     cedures 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 originat-
     ing in an extension.  In addition, a result value  or  error
     message  is  left  in  interp's  result; it can be retrieved
     using Tcl_GetObjResult.

     Tcl_EvalFile reads the file given by fileName and  evaluates
     its  contents as a Tcl script.  It returns the same informa-
     tion 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 "\32"  (^Z)  for  all  plat-
     forms.  If you require a "^Z" in code for string comparison,
     you can use "\032" or "\u001a", which will be safely substi-
     tuted by the Tcl interpreter into "^Z".

     Tcl_EvalObjv executes a single pre-parsed command instead of
     a script.  The objc and objv arguments contain the values of
     the words for the Tcl command, one word in  each  object  in
     objv.  Tcl_EvalObjv evaluates the command and returns a com-
     pletion 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 objects 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 an object
     and no compilation occurs.  The string should  be  a  proper
     UTF-8  string  as  converted  by Tcl_ExternalToUtfDString or
     Tcl_ExternalToUtf when it is known to possibly contain upper
     ASCII  characters  whose  possible  combinations  might be a
     UTF-8 special code.   The  string  is  parsed  and  executed
     directly  (using  Tcl_EvalObjv)  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.   Note:  for backward compatibility with ver-
     sions before Tcl 8.0, Tcl_Eval copies the object  result  in
     interp to interp->result (use is deprecated) where it can be
     accessed directly.
      This makes Tcl_Eval somewhat slower than Tcl_EvalEx,  which
     does not do the copy.

     Tcl_EvalEx is an extended version  of  Tcl_Eval  that  takes
     additional arguments numBytes and flags.  For the efficiency
     reason given above, Tcl_EvalEx is generally  preferred  over
     Tcl_Eval.

     Tcl_GlobalEval and Tcl_GlobalEvalObj  are  older  procedures
     that are now deprecated.  They are similar to Tcl_EvalEx and

Tcl                     Last change: 8.1                        3

Tcl_Eval(3)          Tcl Library Procedures           Tcl_Eval(3)

     Tcl_EvalObjEx except that the script  is  evaluated  in  the
     global namespace and its variable context consists of global
     variables only (it  ignores  any  Tcl  procedures  that  are
     active).   These  functions  are  equivalent  to  using  the
     TCL_EVAL_GLOBAL flag (see below).

     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 same way as Tcl_Eval.  The last  argument  to
     Tcl_VarEval  must  be NULL to indicate the end of arguments.
     Tcl_VarEval is now deprecated.

     Tcl_VarEvalVA is the same as Tcl_VarEval except that instead
     of  taking  a variable number of arguments it takes an argu-
     ment list. Like Tcl_VarEval, Tcl_VarEvalVA is deprecated.


FLAG BITS

     Any ORed combination of the following values may be used for
     the flags argument to procedures such as Tcl_EvalObjEx:

     TCL_EVAL_DIRECT        This   flag   is   only    used    by
                            Tcl_EvalObjEx; it is ignored 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 an
                            object are going  to  change  immedi-
                            ately,  so  the bytecodes will not be
                            reused in  a  future  execution.   In
                            this  case,  it  is faster to execute
                            the script directly.

     TCL_EVAL_GLOBAL        If this flag is set,  the  script  is
                            processed   at  global  level.   This
                            means that it  is  evaluated  in  the
                            global  namespace  and  its  variable
                            context consists of global  variables
                            only  (it  ignores any Tcl procedures
                            at 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 pro-
     cedures 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

Tcl                     Last change: 8.1                        4

Tcl_Eval(3)          Tcl Library Procedures           Tcl_Eval(3)

     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_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_CONTINUE  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  inap-
     propriate  place.   This  means  that top-level applications
     should never see a return code from Tcl_EvalObjEx other then
     TCL_OK or TCL_ERROR.


KEYWORDS

     execute, file, global, object, result, script

Tcl                     Last change: 8.1                        5


Man(1) output converted with man2html