Tcl_CreateCommand(3)
Tcl_CreateCommand(3) Tcl Library Procedures Tcl_CreateCommand(3)
_________________________________________________________________
NAME
Tcl_CreateCommand - implement new commands in C
SYNOPSIS
#include <tcl.h>
Tcl_Command
Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in
which to create
new command.
const char *cmdName (in) Name of command.
Tcl_CmdProc *proc (in) Implementation
of new command:
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 to
call before
cmdName is
deleted from the
interpreter;
allows for
command-specific
cleanup. If
NULL, then no
procedure is
called before
the command is
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. It
Tcl Last change: 1
Tcl_CreateCommand(3) Tcl Library Procedures Tcl_CreateCommand(3)
differs from Tcl_CreateObjCommand in that a new string-based
command is defined; that is, a command procedure is defined
that takes an array of argument strings instead of objects.
The object-based command procedures registered by
Tcl_CreateObjCommand can execute significantly faster than
the string-based command procedures defined by
Tcl_CreateCommand. This is because they take Tcl objects as
arguments and those objects can retain an internal represen-
tation that can be manipulated more efficiently. Also,
Tcl's interpreter now uses objects internally. In order to
invoke a string-based command procedure registered by
Tcl_CreateCommand, it must generate and fetch a string
representation from each argument object before the call and
create a new Tcl object to hold the string result returned
by the string-based command procedure. New commands should
be defined using Tcl_CreateObjCommand. We support
Tcl_CreateCommand for backwards compatibility.
The procedures Tcl_DeleteCommand, Tcl_GetCommandInfo, and
Tcl_SetCommandInfo are used in conjunction with
Tcl_CreateCommand.
Tcl_CreateCommand will delete an existing command cmdName,
if one is already associated with the interpreter. It
returns a token that may be used to refer to the command in
subsequent calls to Tcl_GetCommandName. If cmdName contains
any :: namespace qualifiers, then the command is added to
the specified namespace; otherwise the command is added to
the global namespace. 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,
const 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.
Note that the argument strings should not be modified as
they may point to constant strings or may be shared with
other parts of the interpreter.
Tcl Last change: 2
Tcl_CreateCommand(3) Tcl Library Procedures Tcl_CreateCommand(3)
Note that the argument strings are encoded in normalized
UTF-8 since version 8.1 of Tcl.
Proc must return an integer code that is expected to be one
of 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 the
interpreter result to point to a string value; in the case
of a TCL_OK return code this gives the result of the com-
mand, and in the case of TCL_ERROR it gives an error mes-
sage. The Tcl_SetResult procedure provides an easy inter-
face for setting the return value; for complete details on
how the interpreter result field is managed, see the
Tcl_Interp man page. Before invoking a command procedure,
Tcl_Eval sets the interpreter 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 the interpreter 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 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.
SEE ALSO
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
KEYWORDS
bind, command, create, delete, interpreter, namespace
Tcl Last change: 3
Man(1) output converted with
man2html