Tcl_CreateObjCommand(3) Tcl Library Procedures Tcl_CreateObjCommand(3)______________________________________________________________________________NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken,
Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo,
Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFull‐
Name, 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_ObjCmdProc *proc (in) Implementation of the 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 com‐
mand is deleted.
Tcl_Command token (in) Token for command, 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 command.
Tcl_Obj *objPtr (in) Value containing 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) the Tcl interpreter will call proc
to process the command.
Tcl_CreateObjCommand deletes any existing command name already associ‐
ated 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 com‐
mand 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_CreateObj‐
Command. 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 giv‐
ing the number of argument values (including the command name) and objv
giving the values of the arguments. The objv array will contain objc
values, pointing to the argument values. 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 decla‐
ration 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 value argument. For
instance, the user may call Tcl_GetIntFromObj on objv[2] to obtain the
integer representation of that value; that call may change the type of
the value 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
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 a value representing an empty string, so simple com‐
mands 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_SetO‐
bjResult if you want to return something from the objv array.
Ordinarily, Tcl_CreateObjCommand deletes any existing command name
already associated with the interpreter. However, if the existing com‐
mand was created by a previous call to Tcl_CreateCommand, Tcl_CreateOb‐
jCommand 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_CreateOb‐
jCommand. DeleteProc is invoked before the command is deleted, and
gives the application an opportunity to release any structures associ‐
ated 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 interpreter. 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 restrictions on cmdName: it may refer to a built-in com‐
mand, 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_DeleteCommandFrom‐
Token deletes the command from a command interpreter. It will delete a
command even if that command has been renamed. Once the call com‐
pletes, 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_GetCommandInfo checks to see whether its cmdName argument 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 program 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 value-based command procedure that the
Tcl interpreter calls to implement the command. The fields proc and
clientData hold information about the string-based command procedure
that implements the command. If Tcl_CreateCommand was called for this
command, this is the procedure passed to it; otherwise, this is a com‐
patibility procedure registered by Tcl_CreateObjCommand that simply
calls the command's value-based procedure after converting its string
arguments to Tcl values. 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; otherwise, it returns 1 and fills in the structure designated by
infoPtr.
Tcl_SetCommandInfo is used to modify the procedures and ClientData val‐
ues 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
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. Otherwise, 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 differ‐
ent 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 commands 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_GetCom‐
mandName 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 value specified by objPtr.
Tcl_GetCommandFromObj returns a token for the command specified by the
name in a Tcl_Obj. The command name is resolved relative to the cur‐
rent namespace. Returns NULL if the command is not found.
SEE ALSOTcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)KEYWORDS
bind, command, create, delete, namespace, value
Tcl 8.0 Tcl_CreateObjCommand(3)
