A number of difficult questions have arisen, and
continue to arise concerning the details about
how Tcl commands are evaluated.

This page has been created to lay out the
details of Tcl command evaluation in order
to see the various points at which existing
behavior might be modified, or new behavior
might be attached.

I find it easiest to follow the details by
working from the inside out.

----
'''Layer 0: Tcl_ObjCmdProc'''

The innermost core of any Tcl command is a '''Tcl_ObjCmdProc''', a C routine that matches the prototype:

   typedef int (Tcl_ObjCmdProc) (
      ClientData clientData,
      Tcl_Interp *interp,
      int objc,
      Tcl_Obj * const objv[]);

A new Tcl command gets created by writing a '''Tcl_ObjCmdProc''',
associating it with a '''ClientData''', and with a command
name in an ''interp'', via a call to '''Tcl_CreateObjCommand'''.

The '''Tcl_ObjCmdProc''' gets passed the 
associated '''ClientData''',
the interp, and the full '''Tcl_Obj''' array, ''objv'',
of the words of the command being evaluated.  

The ''objv[[1]]'' ... ''objv[[objc-1]]'' values are the arguments to
the command, and can influence the result.
The '''Tcl_ObjCmdProc''' should avoid changing behavior
based on the value of ''objv[[0]]'' however, for a few
reasons.  First it is a property of Tcl commands that they
can be [[rename]]d.  Thus the value of ''objv[[0]]'' may very
well not be the command name originally passed to
'''Tcl_CreateObjCommand'''.  Second, as part of command
evaluation, the Tcl internals will have interpreted the
'''Tcl_Obj''' ''objv[[0]]'' as the '''Tcl_ObjType''' ''cmdName''.
This means the internal rep of ''objv[[0]]'' will be
that of a ''cmdName'', and any other internal rep someone
tried to pass will be lost.

Another particularly nasty example of the bugs that
can arise depending on the value of ''objv[[0]]''
is Tcl Bug 1016167. [http://sf.net/tracker/?func=detail&aid=1016167&group_id=10894&atid=110894]

Rather than ''objv[[0]]'', any state information needed
to influence the command operations beyond the values of
the arguments should be kept in the '''ClientData'''.

Note also the '''const''' restriction on the ''objv''
argument.  You should not (and the compiler should
not let you) write to any of the ''objv[[i]]'' slots.
The '''Tcl_Obj''''s themselves might be modified
(typically by [shimmering]), but the pointers may
not be overwritten.

One thing that the ''objv[[0]]'' value can be used
for is to construct syntax error messages.  Often
'''Tcl_WrongNumArgs''' is used for this.

The '''Tcl_ObjCmdProc''' can count on the result of the
interp having been reset. It is expected to return a return code value ('''TCL_OK''', '''TCL_ERROR''', etc.). 
It may set the interp result, if the reset state
is not correct. ('''Tcl_SetObjResult''', etc.)
It may also set the errorInfo and/or errorCode values if it is returning TCL_ERROR.  ('''Tcl_AddErrorInfo''', 
'''Tcl_SetErrorCode''', etc.)

'''Possible Enhancements'''

Might need a C API to set values in the return options dictionary. Currently this is possible at the script level using [[return]], but there's no C API currently for that. Such a routine would cover errorInfo and errorCode setting, but would also be more general.

----
'''Layer 1: command dispatch: Tcl_ObjCmdProc callers'''

There are several routines in Tcl that currently
call Tcl_ObjCmdProc's to perform command dispatch:

   TclEvalObjvInternal
   TclInvokeObjectCommand
   TclObjInvoke
   Tcl_Import
   InvokeImportedCmd

They are not fully consistent with one another in how they manage command dispatch.

Over the years, Tcl has grown a large set of duties
for the command dispatcher code to attend to.  It is
supposed to manage interpreter traces set by '''Tcl_CreateTrace'''
and '''Tcl_CreateObjTrace'''.  It is supposed to manage
command execution traces.  It is supposed to manage
interpreter limits.  It is supposed to see the asynchronous
code gets a chance to execute.  And probably more...


----

[[ [Category Internals] ]]