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 edit
The innermost core of any Tcl command is a Tcl_ObjCmdProc
, a C routine that matches the prototype:
typedef int (Tcl_ObjCmdProc) (
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
gets passed the associated ClientData
, the interp, and the full Tcl_Obj
, of the words of the command being evaluated.
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
however, for a few reasons. First it is a property of Tcl commands that they can be [rename]d. Thus the value of objv
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
as the Tcl_ObjType cmdName
. This means the internal rep of objv
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
is Tcl Bug 1016167. [1
Rather than objv
, 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
value can be used for is to construct syntax error messages. Often Tcl_WrongNumArgs
is used for this.
can count on the result of the interp having been reset. It is expected to return a return code value (TCL_OK
, 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
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.
has recently pointed out, the absence of this C API is all that prevents an extension from being able to provide its own [proc] replacement. The inability to create [proc]-like commands using only the public C API is one reason that important, powerful extensions like Itcl and XOTcl require access to Tcl's internals.
Layer 1: command dispatch: Tcl_ObjCmdProc callers edit
There are several routines in Tcl that currently call Tcl_ObjCmdProc's to perform command dispatch:
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
. 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...