NAME
Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
Tcl_SetCommandInfo - implement new commands in C
SYNOPSIS
#include <tcl.h>
Tcl_Command
Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)
int
Tcl_DeleteCommand(interp, cmdName)
int
Tcl_GetCommandInfo(interp, cmdName, infoPtr)
int
Tcl_SetCommandInfo(interp, cmdName, infoPtr)
char *
Tcl_GetCommandName(interp, token)
ARGUMENTS
Tcl_Interp *interp (in) Inter-
preter in
which to
create new
command.
char *cmdName (in) Name of
command.
Tcl_CmdProc *proc (in) Implemen-
tation of
new com-
mand:
proc will
be called
whenever
cmdName is
invoked as
a command.
ClientData clientData (in) Arbitrary
one-word
value to
pass to
proc and
deleteProc.
Tcl_CmdDeleteProc *deleteProc (in) Procedure
cmdName is
deleted
from the
inter-
preter;
allows for
command-
specific
cleanup.
If NULL,
then no
procedure
is called
before the
command is
deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to
structure
containing
various
informa-
tion about
a Tcl com-
mand.
Tcl_Command token (in) Token for
command,
returned
by previ-
ous call
to
Tcl_CreateCommand.
The com-
mand must
not have
been
deleted.
_________________________________________________________________
DESCRIPTION
Tcl_CreateCommand defines a new command in interp and
associates it with procedure proc such that whenever cmd-
Name is invoked as a Tcl command (via a call to Tcl_Eval)
the Tcl interpreter will call proc to process the command.
If there is already a command cmdName associated with the
interpreter, it is deleted. Tcl_CreateCommand returns a
token that may be used to refer to the command in subse-
quent calls to Tcl_GetCommandName. If Tcl_CreateCommand
is called for an interpreter that is in the process of
being deleted, then it does not create a new command and
typedef int Tcl_CmdProc(
ClientData clientData,
Tcl_Interp *interp,
int argc,
char *argv[]);
When proc is invoked the clientData and interp parameters
will be copies of the clientData and interp arguments
given to Tcl_CreateCommand. Typically, clientData points
to an application-specific data structure that describes
what to do when the command procedure is invoked. Argc
and argv describe the arguments to the command, argc giv-
ing the number of arguments (including the command name)
and argv giving the values of the arguments as strings.
The argv array will contain argc+1 values; the first argc
values point to the argument strings, and the last value
is NULL.
Proc must return an integer code that is either TCL_OK,
TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See
the Tcl overview man page for details on what these codes
mean. Most normal commands will only return TCL_OK or
TCL_ERROR. In addition, proc must set interp->result to
point to a string value; in the case of a TCL_OK return
code this gives the result of the command, and in the case
of TCL_ERROR it gives an error message. The Tcl_SetResult
procedure provides an easy interface for setting the
return value; for complete details on how the
interp->result field is managed, see the Tcl_Interp man
page. Before invoking a command procedure, Tcl_Eval sets
interp->result to point to an empty string, so simple com-
mands can return an empty result by doing nothing at all.
The contents of the argv array belong to Tcl and are not
guaranteed to persist once proc returns: proc should not
modify them, nor should it set interp->result to point
anywhere within the argv values. Call Tcl_SetResult with
status TCL_VOLATILE if you want to return something from
the argv array.
DeleteProc will be invoked when (if) cmdName is deleted.
This can occur through a call to Tcl_DeleteCommand or
Tcl_DeleteInterp, or by replacing cmdName in another call
to Tcl_CreateCommand. DeleteProc is invoked before the
command is deleted, and gives the application an opportu-
nity to release any structures associated with the com-
mand. DeleteProc should have arguments and result that
match the type Tcl_CmdDeleteProc:
typedef void Tcl_CmdDeleteProc(ClientData clientData);
The clientData argument will be the same as the clientData
argument passed to Tcl_CreateCommand.
Tcl_DeleteCommand deletes a command from a command inter-
bound as a command in interp then Tcl_DeleteCommand does
nothing and returns -1; otherwise it returns 0. There
are no restrictions on cmdName: it may refer to a built-
in command, an application-specific command, or a Tcl pro-
cedure.
Tcl_GetCommandInfo checks to see whether its cmdName argu-
ment exists as a command in interp. If not then it
returns 0. Otherwise it places information about the com-
mand in the structure pointed to by infoPtr and returns 1.
Tcl_CmdInfo structures have fields named proc, clientData,
and deleteProc, which have the same meaning as the corre-
sponding arguments to Tcl_CreateCommand. There is also a
field deleteData, which is the ClientData value to pass to
deleteProc; it is normally the same as clientData but may
be set independently using the Tcl_SetCommandInfo proce-
dure.
Tcl_SetCommandInfo is used to modify the procedures and
ClientData values associated with a command. Its cmdName
argument is the name of a command in interp. If this com-
mand does not exist then Tcl_SetCommandInfo returns 0.
Otherwise, it copies the information from *infoPtr to
Tcl's internal structure for the command and returns 1.
Note that this procedure allows the ClientData for a com-
mand's deletion procedure to be given a different value
than the ClientData for its command procedure.
Tcl_GetCommandName provides a mechanism for tracking com-
mands that have been renamed. Given a token returned by
Tcl_CreateCommand when the command was created,
Tcl_GetCommandName returns the string name of the command.
If the command has been renamed since it was created, then
Tcl_GetCommandName returns the current name. The command
corresponding to token must not have been deleted. The
string returned by Tcl_GetCommandName is in dynamic memory
owned by Tcl and is only guaranteed to retain its value as
long as the command isn't deleted or renamed; callers
should copy the string if they need to keep it for a long
time.
KEYWORDS
bind, command, create, delete, interpreter