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 *cmd- |
Name (in) | |
Name of command.
Tcl_ObjCmdProc *proc (in) Implementation of the new com-
mand: proc will be called
whenever cmdName is invoked as
a command.
jCommand. The command must
not have been deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to structure contain-
ing various information about
a Tcl command.
Tcl_Obj *objPtr (in) Object 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 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 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 object argument. For |
instance, the user may call Tcl_GetIntFromObj on objv[2] to obtain the |
integer representation of that object; that call may change the type of |
the object that objv[2] points at, but will not change where objv[2] |
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 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. 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;
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 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; 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 isn't 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.
Man(1) output converted with
man2html
|