Tcl_DeleteCommandFromToken(3)
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
_________________________________________________________________
NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand,
Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo,
Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo,
Tcl_SetCommandInfoFromToken, Tcl_GetCommandName,
Tcl_GetCommandFullName, Tcl_GetCommandFromObj - implement
new commands in C
SYNOPSIS
#include <tcl.h>
Tcl_Command
Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)
int
Tcl_DeleteCommand(interp, cmdName)
int
Tcl_DeleteCommandFromToken(interp, token)
int
Tcl_GetCommandInfo(interp, cmdName, infoPtr)
int
Tcl_SetCommandInfo(interp, cmdName, infoPtr)
int
Tcl_GetCommandInfoFromToken(token, infoPtr)
int
Tcl_SetCommandInfoFromToken(token, infoPtr)
const char *
Tcl_GetCommandName(interp, token)
void
Tcl_GetCommandFullName(interp, token, objPtr)
Tcl_Command
Tcl_GetCommandFromObj(interp, objPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in
which to create
a new command or
that contains a
command.
char *cmdName (in) Name of command.
Tcl Last change: 8.0 1
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
Tcl_ObjCmdProc *proc (in) Implementation
of the new com-
mand: proc will
be called when-
ever 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.
Tcl_Command token (in) Token for com-
mand, returned
by previous call
to
Tcl_CreateObjCommand.
The command must
not have been
deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to
structure con-
taining various
information
about a Tcl com-
mand.
Tcl_Obj *objPtr (in) Object contain-
ing the name of
a Tcl command.
_________________________________________________________________
DESCRIPTION
Tcl_CreateObjCommand defines a new command in interp and
associates it with procedure proc such that whenever name is
invoked as a Tcl command (e.g., via a call to Tcl_EvalObjEx)
Tcl Last change: 8.0 2
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
the Tcl interpreter will call proc to process the command.
Tcl_CreateObjCommand deletes any existing command name
already associated with the interpreter (however see below
for an exception where the existing command is not deleted).
It returns a token that may be used to refer to the command
in subsequent calls to Tcl_GetCommandName. If name contains
any :: namespace qualifiers, then the command is added to
the specified namespace; otherwise the command is added to
the global namespace. If Tcl_CreateObjCommand 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_ObjCmdProc:
typedef int Tcl_ObjCmdProc(
ClientData clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[]);
When proc is invoked, the clientData and interp parameters
will be copies of the clientData and interp arguments given
to Tcl_CreateObjCommand. Typically, clientData points to an
application-specific data structure that describes what to
do when the command procedure is invoked. Objc and objv
describe the arguments to the command, objc giving the
number of argument objects (including the command name) and
objv giving the values of the arguments. The objv array
will contain objc values, pointing to the argument objects.
Unlike argv[argv] used in a string-based command procedure,
objv[objc] will not contain NULL.
Additionally, when proc is invoked, it must not modify the
contents of the objv array by assigning new pointer values
to any element of the array (for example, objv[2] = NULL)
because this will cause memory to be lost and the runtime
stack to be corrupted. The const in the declaration of objv
will cause ANSI-compliant compilers to report any such
attempted assignment as an error. However, it is acceptable
to modify the internal representation of any individual
object argument. For instance, the user may call
Tcl_GetIntFromObj on objv[2] to obtain the integer represen-
tation of that object; that call may change the type of the
object that objv[2] points at, but will not change where
objv[2] points.
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, if proc needs to return a non-empty result, it
can call Tcl_SetObjResult to set the interpreter's result.
In the case of a TCL_OK return code this gives the result of
Tcl Last change: 8.0 3
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
the command, and in the case of TCL_ERROR this gives an
error message. Before invoking a command procedure,
Tcl_EvalObjEx sets interpreter's result to point to an
object representing an empty string, so simple commands can
return an empty result by doing nothing at all.
The contents of the objv array belong to Tcl and are not
guaranteed to persist once proc returns: proc should not
modify them. Call Tcl_SetObjResult if you want to return
something from the objv array.
Ordinarily, Tcl_CreateObjCommand deletes any existing com-
mand name already associated with the interpreter. However,
if the existing command was created by a previous call to
Tcl_CreateCommand, Tcl_CreateObjCommand does not delete the
command but instead arranges for the Tcl interpreter to call
the Tcl_ObjCmdProc proc in the future. The old string-based
Tcl_CmdProc associated with the command is retained and its
address can be obtained by subsequent Tcl_GetCommandInfo
calls. This is done for backwards compatibility.
DeleteProc will be invoked when (if) name is deleted. This
can occur through a call to Tcl_DeleteCommand,
Tcl_DeleteCommandFromToken, or Tcl_DeleteInterp, or by
replacing name in another call to Tcl_CreateObjCommand.
DeleteProc is invoked before the command is deleted, and
gives the application an opportunity to release any struc-
tures 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_CreateObjCommand.
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 is not bound as
a command in interp then Tcl_DeleteCommand does nothing and
returns -1; otherwise it returns 0. There are no restric-
tions on cmdName: it may refer to a built-in command, an
application-specific command, or a Tcl procedure. If name
contains any :: namespace qualifiers, the command is deleted
from the specified namespace.
Given a token returned by Tcl_CreateObjCommand,
Tcl_DeleteCommandFromToken deletes the command from a com-
mand interpreter. It will delete a command even if that
command has been renamed. Once the call completes, attempts
to invoke the command in interp will result in errors. If
the command corresponding to token has already been deleted
from interp then Tcl_DeleteCommand does nothing and returns
-1; otherwise it returns 0.
Tcl Last change: 8.0 4
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
Tcl_GetCommandInfo checks to see whether its cmdName argu-
ment exists as a command in interp. cmdName may include ::
namespace qualifiers to identify a command in a particular
namespace. If the command is not found, then it returns 0.
Otherwise it places information about the command in the
Tcl_CmdInfo structure pointed to by infoPtr and returns 1.
A Tcl_CmdInfo structure has the following fields:
typedef struct Tcl_CmdInfo {
int isNativeObjectProc;
Tcl_ObjCmdProc *objProc;
ClientData objClientData;
Tcl_CmdProc *proc;
ClientData clientData;
Tcl_CmdDeleteProc *deleteProc;
ClientData deleteData;
Tcl_Namespace *namespacePtr;
} Tcl_CmdInfo;
The isNativeObjectProc field has the value 1 if
Tcl_CreateObjCommand was called to register the command; it
is 0 if only Tcl_CreateCommand was called. It allows a pro-
gram to determine whether it is faster to call objProc or
proc: objProc is normally faster if isNativeObjectProc has
the value 1. The fields objProc and objClientData have the
same meaning as the proc and clientData arguments to
Tcl_CreateObjCommand; they hold information about the
object-based command procedure that the Tcl interpreter
calls to implement the command. The fields proc and client-
Data hold information about the string-based command pro-
cedure that implements the command. If Tcl_CreateCommand
was called for this command, this is the procedure passed to
it; otherwise, this is a compatibility procedure registered
by Tcl_CreateObjCommand that simply calls the command's
object-based procedure after converting its string arguments
to Tcl objects. The field deleteData 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. The field namespacePtr holds
a pointer to the Tcl_Namespace that contains the command.
Tcl_GetCommandInfoFromToken is identical to
Tcl_GetCommandInfo except that it uses a command token
returned from Tcl_CreateObjCommand in place of the command
name. If the token parameter is NULL, it returns 0; other-
wise, it returns 1 and fills in the structure designated by
infoPtr.
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. cmdName may
include :: namespace qualifiers to identify a command in a
particular namespace. If this command does not exist then
Tcl_SetCommandInfo returns 0. Otherwise, it copies the
Tcl Last change: 8.0 5
Tcl_CreateObjCommand(3Tcl Library ProcedureTcl_CreateObjCommand(3)
information from *infoPtr to Tcl's internal structure for
the command and returns 1.
Tcl_SetCommandInfoFromToken is identical to
Tcl_SetCommandInfo except that it takes a command token as
returned by Tcl_CreateObjCommand instead of the command
name. If the token parameter is NULL, it returns 0. Other-
wise, it copies the information from *infoPtr to Tcl's
internal structure for the command and returns 1.
Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken
both allow the ClientData for a command's deletion procedure
to be given a different value than the ClientData for its
command procedure.
Note that neither Tcl_SetCommandInfo nor
Tcl_SetCommandInfoFromToken will change a command's
namespace. Use Tcl_Eval to call the rename command to do
that.
Tcl_GetCommandName provides a mechanism for tracking com-
mands that have been renamed. Given a token returned by
Tcl_CreateObjCommand 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. This name does
not include any :: namespace qualifiers. 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 is not deleted or renamed; callers
should copy the string if they need to keep it for a long
time.
Tcl_GetCommandFullName produces the fully qualified name of
a command from a command token. The name, including all
namespace prefixes, is appended to the object specified by
objPtr.
Tcl_GetCommandFromObj returns a token for the command speci-
fied by the name in a Tcl_Obj. The command name is resolved
relative to the current namespace. Returns NULL if the com-
mand is not found.
SEE ALSO
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
KEYWORDS
bind, command, create, delete, namespace, object
Tcl Last change: 8.0 6
Man(1) output converted with
man2html