249 lines
11 KiB
Groff
249 lines
11 KiB
Groff
'\"
|
|
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) @(#) CrtObjCmd.3 1.10 97/07/31 14:10:38
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
Tcl_Command
|
|
\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
|
.sp
|
|
char *
|
|
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_ObjCmdProc *deleteProc in/out
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter in which to create a new command or that contains a command.
|
|
.AP char *cmdName in
|
|
Name of command.
|
|
.AP Tcl_ObjCmdProc *proc in
|
|
Implementation of the new command: \fIproc\fR will be called whenever
|
|
\fIcmdName\fR is invoked as a command.
|
|
.AP ClientData clientData in
|
|
Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
|
|
.AP Tcl_CmdDeleteProc *deleteProc in
|
|
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
|
|
allows for command-specific cleanup. If NULL, then no procedure is
|
|
called before the command is deleted.
|
|
.AP Tcl_Command token in
|
|
Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
|
|
The command must not have been deleted.
|
|
.AP Tcl_CmdInfo *infoPtr in/out
|
|
Pointer to structure containing various information about a
|
|
Tcl command.
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
|
|
and associates it with procedure \fIproc\fR
|
|
such that whenever \fIname\fR is
|
|
invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)
|
|
the Tcl interpreter will call \fIproc\fR to process the command.
|
|
.PP
|
|
\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR
|
|
already associated with the interpreter.
|
|
It returns a token that may be used to refer
|
|
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
|
|
If \fIname\fR contains any \fB::\fR namespace qualifiers,
|
|
then the command is added to the specified namespace;
|
|
otherwise the command is added to the global namespace.
|
|
If \fBTcl_CreateObjCommand\fR 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.
|
|
\fIproc\fR should have arguments and result that match the type
|
|
\fBTcl_ObjCmdProc\fR:
|
|
.CS
|
|
typedef int Tcl_ObjCmdProc(
|
|
ClientData \fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
int \fIobjc\fR,
|
|
.VS
|
|
Tcl_Obj *CONST \fIobjv\fR[]);
|
|
.CE
|
|
When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
|
|
will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
|
|
\fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
|
|
application-specific data structure that describes what to do when the
|
|
command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
|
|
arguments to the command, \fIobjc\fR giving the number of argument objects
|
|
(including the command name) and \fIobjv\fR giving the values of the
|
|
arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
|
|
the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a
|
|
string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
|
|
.PP
|
|
Additionally, when \fIproc\fR is invoked, it must not modify the contents
|
|
of the \fIobjv\fR array by assigning new pointer values to any element of the
|
|
array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
|
|
cause memory to be lost and the runtime stack to be corrupted. The
|
|
\fBCONST\fR in the declaration of \fIobjv\fR 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
|
|
\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
|
|
representation of that object; that call may change the type of the object
|
|
that \fIobjv\fR[\fB2\fR] points at, but will not change where
|
|
\fIobjv\fR[\fB2\fR] points.
|
|
.VE
|
|
.PP
|
|
\fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
|
|
\fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
|
|
See the Tcl overview man page
|
|
for details on what these codes mean. Most normal commands will only
|
|
return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
|
|
In addition, if \fIproc\fR needs to return a non-empty result,
|
|
it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
|
|
In the case of a \fBTCL_OK\fR return code this gives the result
|
|
of the command,
|
|
and in the case of \fBTCL_ERROR\fR this gives an error message.
|
|
Before invoking a command procedure,
|
|
\fBTcl_EvalObj\fR 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.
|
|
.PP
|
|
The contents of the \fIobjv\fR array belong to Tcl and are not
|
|
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
|
|
not modify them.
|
|
Call \fBTcl_SetObjResult\fR if you want
|
|
to return something from the \fIobjv\fR array.
|
|
.PP
|
|
\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
|
|
This can occur through a call to \fBTcl_DeleteCommand\fR,
|
|
\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
|
|
or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
|
|
\fIDeleteProc\fR is invoked before the command is deleted, and gives the
|
|
application an opportunity to release any structures associated
|
|
with the command. \fIDeleteProc\fR should have arguments and
|
|
result that match the type \fBTcl_CmdDeleteProc\fR:
|
|
.CS
|
|
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
|
|
.CE
|
|
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
|
argument passed to \fBTcl_CreateObjCommand\fR.
|
|
.PP
|
|
\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
|
|
Once the call completes, attempts to invoke \fIcmdName\fR in
|
|
\fIinterp\fR will result in errors.
|
|
If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
|
|
\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
|
|
it returns 0.
|
|
There are no restrictions on \fIcmdName\fR: it may refer to
|
|
a built-in command, an application-specific command, or a Tcl procedure.
|
|
If \fIname\fR contains any \fB::\fR namespace qualifiers,
|
|
the command is deleted from the specified namespace.
|
|
.PP
|
|
Given a token returned by \fBTcl_CreateObjCommand\fR,
|
|
\fBTcl_DeleteCommandFromToken\fR deletes the command
|
|
from a command interpreter.
|
|
It will delete a command even if that command has been renamed.
|
|
Once the call completes, attempts to invoke the command in
|
|
\fIinterp\fR will result in errors.
|
|
If the command corresponding to \fItoken\fR
|
|
has already been deleted from \fIinterp\fR then
|
|
\fBTcl_DeleteCommand\fR does nothing and returns -1;
|
|
otherwise it returns 0.
|
|
.PP
|
|
\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
|
|
exists as a command in \fIinterp\fR.
|
|
\fIcmdName\fR may include \fB::\fR 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 \fBTcl_CmdInfo\fR structure
|
|
pointed to by \fIinfoPtr\fR and returns 1.
|
|
A \fBTcl_CmdInfo\fR structure has the following fields:
|
|
.CS
|
|
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;
|
|
.CE
|
|
The \fIisNativeObjectProc\fR field has the value 1
|
|
if \fBTcl_CreateObjCommand\fR was called to register the command;
|
|
it is 0 if only \fBTcl_CreateCommand\fR was called.
|
|
It allows a program to determine whether it is faster to
|
|
call \fIobjProc\fR or \fIproc\fR:
|
|
\fIobjProc\fR is normally faster
|
|
if \fIisNativeObjectProc\fR has the value 1.
|
|
The fields \fIobjProc\fR and \fIobjClientData\fR
|
|
have the same meaning as the \fIproc\fR and \fIclientData\fR
|
|
arguments to \fBTcl_CreateObjCommand\fR;
|
|
they hold information about the object-based command procedure
|
|
that the Tcl interpreter calls to implement the command.
|
|
The fields \fIproc\fR and \fIclientData\fR
|
|
hold information about the string-based command procedure
|
|
that implements the command.
|
|
If \fBTcl_CreateCommand\fR was called for this command,
|
|
this is the procedure passed to it;
|
|
otherwise, this is a compatibility procedure
|
|
registered by \fBTcl_CreateObjCommand\fR
|
|
that simply calls the command's
|
|
object-based procedure after converting its string arguments to Tcl objects.
|
|
The field \fIdeleteData\fR is the ClientData value
|
|
to pass to \fIdeleteProc\fR; it is normally the same as
|
|
\fIclientData\fR but may be set independently using the
|
|
\fBTcl_SetCommandInfo\fR procedure.
|
|
The field \fInamespacePtr\fR holds a pointer to the
|
|
Tcl_Namespace that contains the command.
|
|
.PP
|
|
\fBTcl_SetCommandInfo\fR is used to modify the procedures and
|
|
ClientData values associated with a command.
|
|
Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
|
|
\fIcmdName\fR may include \fB::\fR namespace qualifiers
|
|
to identify a command in a particular namespace.
|
|
If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
|
|
Otherwise, it copies the information from \fI*infoPtr\fR to
|
|
Tcl's internal structure for the command and returns 1.
|
|
Note that this procedure allows the ClientData for a command's
|
|
deletion procedure to be given a different value than the ClientData
|
|
for its command procedure.
|
|
Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace;
|
|
you must use \fBTcl_RenameCommand\fR to do that.
|
|
.PP
|
|
\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
|
|
that have been renamed.
|
|
Given a token returned by \fBTcl_CreateObjCommand\fR
|
|
when the command was created, \fBTcl_GetCommandName\fR returns the
|
|
string name of the command. If the command has been renamed since it
|
|
was created, then \fBTcl_GetCommandName\fR returns the current name.
|
|
This name does not include any \fB::\fR namespace qualifiers.
|
|
The command corresponding to \fItoken\fR must not have been deleted.
|
|
The string returned by \fBTcl_GetCommandName\fR 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.
|
|
.PP
|
|
|
|
.SH "SEE ALSO"
|
|
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
|
|
|
|
.SH KEYWORDS
|
|
bind, command, create, delete, namespace, object
|