tcl7.6 C API - CrtCommand
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) Interpreter
in which to
create new
command.
char *cmdName (in) Name of com-
mand.
Tcl_CmdProc *proc (in) Implementation
of new com-
mand: proc
will be
called when-
ever cmdName
is invoked
as a com-
mand.
ClientData clientData (in) Arbitrary
one-word
value to
pass to proc
and
deleteProc.
Tcl_CmdDeleteProc *deleteProc (in) Procedure to
call before
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
information
about a Tcl
command.
Tcl_Command token (in) Token for
command,
returned by
previous
call to
Tcl_CreateCommand.
The command
must not
have been
deleted.
DESCRIPTION
Tcl_CreateCommand defines a new command in interp and asso-
ciates it with procedure proc such that whenever cmdName 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 inter-
preter, it is deleted. Tcl_CreateCommand returns a token
that may be used to refer to the command in subsequent 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 it returns NULL. Proc
should have arguments and result that match the type
Tcl_CmdProc:
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 giving 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 pro-
vides 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 pro-
cedure, Tcl_Eval sets interp->result to point to an empty
string, so simple commands 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 any-
where 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 opportunity to
release any structures associated with the command.
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-
preter. Once the call completes, attempts to invoke cmdName
in interp will result in errors. If cmdName isn't 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 com-
mand, an application-specific command, or a Tcl procedure.
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 command 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 corresponding
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 procedure.
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. Oth-
erwise, 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 command's dele-
tion 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