Index of Section 3 Manual Pages
| Interix / SUA | Tcl_GetCommandInfoFromToken.3 | Interix / SUA |
Tcl_CreateObjCommand(3Tcl Library ProcedurTcl_CreateObjCommand(3)
_________________________________________________________________
NAME
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCom-
mandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFrom-
Token, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken,
Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCom-
mandFromObj - implement new commands in C
SYNOPSIS
#include
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 command:
proc will be
called whenever
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
interpreter;
allows for com-
mand-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_CreateObjCom-
mand. The com-
mand must not
have been
deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to struc-
ture containing
various informa-
tion 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_Eval-
ObjEx) 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 com-
mand is added to the specified namespace; otherwise the
command is added to the global namespace. If Tcl_Cre-
ateObjCommand 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 com- |
mand, objc giving the number of argument objects (includ- |
ing 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 |
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] 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 an object representing an empty string, so
simple commands can return an empty result by doing noth-
ing 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. How-
ever, 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 inter-
preter 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 com-
patibility.
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_Cmd-
DeleteProc:
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 command, an application-specific command, or a Tcl pro-
cedure. 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 noth-
ing and returns -1; otherwise it returns 0.
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 partic-
ular namespace. If the command is not found, then it
returns 0. Otherwise it places information about the com-
mand 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_Cre-
ateObjCommand 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
object-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_CreateCom-
mand 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 nor-
mally the same as clientData but may be set independently
using the Tcl_SetCommandInfo procedure. The field names-
pacePtr holds a pointer to the Tcl_Namespace that contains
the command.
Tcl_GetCommandInfoFromToken is identical to Tcl_GetCom-
mandInfo 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 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
information from *infoPtr to Tcl's internal structure for
the command and returns 1.
Tcl_SetCommandInfoFromToken is identical to Tcl_SetCom-
mandInfo 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_SetCommandInfoFromTo-
ken both allow the ClientData for a command's deletion
procedure to be given a different value than the Client-
Data for its command procedure.
Note that neither Tcl_SetCommandInfo nor Tcl_SetCommandIn-
foFromToken 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 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 speci-
fied 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 current namespace. Returns NULL
if the command is not found.
SEE ALSO
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
KEYWORDS
bind, command, create, delete, namespace, object
Tcl 8.0 Tcl_CreateObjCommand(3)