tcl/doc/CrtObjCmd.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id$
   8 '\"
   9 .so man.macros
  10 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
  11 .BS
  12 .SH NAME
  13 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
  14 .SH SYNOPSIS
  15 .nf
  16 \fB#include <tcl.h>\fR
  17 .sp
  18 Tcl_Command
  19 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  20 .sp
  21 int
  22 \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  23 .sp
  24 int
  25 \fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
  26 .sp
  27 int
  28 \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  29 .sp
  30 int
  31 \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  32 .sp
  33 char *
  34 \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
  35 .SH ARGUMENTS
  36 .AS Tcl_ObjCmdProc *deleteProc in/out
  37 .AP Tcl_Interp *interp in
  38 Interpreter in which to create a new command or that contains a command.
  39 .AP char *cmdName in
  40 Name of command.
  41 .AP Tcl_ObjCmdProc *proc in
  42 Implementation of the new command: \fIproc\fR will be called whenever
  43 \fIcmdName\fR is invoked as a command.
  44 .AP ClientData clientData in
  45 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  46 .AP Tcl_CmdDeleteProc *deleteProc in
  47 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  48 allows for command-specific cleanup. If NULL, then no procedure is
  49 called before the command is deleted.
  50 .AP Tcl_Command token in
  51 Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
  52 The command must not have been deleted.
  53 .AP Tcl_CmdInfo *infoPtr in/out
  54 Pointer to structure containing various information about a
  55 Tcl command.
  56 .BE
  57 .SH DESCRIPTION
  58 .PP
  59 \fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
  60 and associates it with procedure \fIproc\fR
  61 such that whenever \fIname\fR is
  62 invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
  63 the Tcl interpreter will call \fIproc\fR to process the command.
  64 .PP
  65 \fBTcl_CreateObjCommand\fR deletes any existing command
  66 \fIname\fR already associated with the interpreter
  67 (however see below for an exception where the existing command
  68 is not deleted).
  69 It returns a token that may be used to refer
  70 to the command in subsequent calls to \fBTcl_GetCommandName\fR.
  71 If \fIname\fR contains any \fB::\fR namespace qualifiers,
  72 then the command is added to the specified namespace;
  73 otherwise the command is added to the global namespace.
  74 If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
  75 the process of being deleted, then it does not create a new command
  76 and it returns NULL.
  77 \fIproc\fR should have arguments and result that match the type
  78 \fBTcl_ObjCmdProc\fR:
  79 .CS
  80 typedef int Tcl_ObjCmdProc(
  81         ClientData \fIclientData\fR,
  82         Tcl_Interp *\fIinterp\fR,
  83         int \fIobjc\fR,
  84 .VS
  85         Tcl_Obj *CONST \fIobjv\fR[]);
  86 .CE
  87 When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
  88 will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
  89 \fBTcl_CreateObjCommand\fR.  Typically, \fIclientData\fR points to an
  90 application-specific data structure that describes what to do when the
  91 command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
  92 arguments to the command, \fIobjc\fR giving the number of argument objects
  93 (including the command name) and \fIobjv\fR giving the values of the
  94 arguments.  The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
  95 the argument objects.  Unlike \fIargv\fR[\fIargv\fR] used in a
  96 string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
  97 .PP
  98 Additionally, when \fIproc\fR is invoked, it must not modify the contents
  99 of the \fIobjv\fR array by assigning new pointer values to any element of the
 100 array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
 101 cause memory to be lost and the runtime stack to be corrupted.  The
 102 \fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
 103 compilers to report any such attempted assignment as an error.  However,
 104 it is acceptable to modify the internal representation of any individual
 105 object argument.  For instance, the user may call
 106 \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
 107 representation of that object; that call may change the type of the object
 108 that \fIobjv\fR[\fB2\fR] points at, but will not change where
 109 \fIobjv\fR[\fB2\fR] points.
 110 .VE
 111 .PP
 112 \fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
 113 \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
 114 See the Tcl overview man page
 115 for details on what these codes mean.  Most normal commands will only
 116 return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 117 In addition, if \fIproc\fR needs to return a non-empty result,
 118 it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
 119 In the case of a \fBTCL_OK\fR return code this gives the result
 120 of the command,
 121 and in the case of \fBTCL_ERROR\fR this gives an error message.
 122 Before invoking a command procedure,
 123 \fBTcl_EvalObjEx\fR sets interpreter's result to
 124 point to an object representing an empty string, so simple
 125 commands can return an empty result by doing nothing at all.
 126 .PP
 127 The contents of the \fIobjv\fR array belong to Tcl and are not
 128 guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
 129 not modify them.
 130 Call \fBTcl_SetObjResult\fR if you want
 131 to return something from the \fIobjv\fR array.
 132 .PP
 133 Ordinarily, \fBTcl_CreateObjCommand\fR deletes any existing command
 134 \fIname\fR already associated with the interpreter.
 135 However, if the existing command was created by a previous call to
 136 \fBTcl_CreateCommand\fR,
 137 \fBTcl_CreateObjCommand\fR does not delete the command
 138 but instead arranges for the Tcl interpreter to call the
 139 \fBTcl_ObjCmdProc\fR \fIproc\fR in the future.
 140 The old string-based \fBTcl_CmdProc\fR associated with the command
 141 is retained and its address can be obtained by subsequent
 142 \fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility.
 143 .PP
 144 \fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
 145 This can occur through a call to \fBTcl_DeleteCommand\fR,
 146 \fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
 147 or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
 148 \fIDeleteProc\fR is invoked before the command is deleted, and gives the
 149 application an opportunity to release any structures associated
 150 with the command.  \fIDeleteProc\fR should have arguments and
 151 result that match the type \fBTcl_CmdDeleteProc\fR:
 152 .CS
 153 typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
 154 .CE
 155 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 156 argument passed to \fBTcl_CreateObjCommand\fR.
 157 .PP
 158 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
 159 Once the call completes, attempts to invoke \fIcmdName\fR in
 160 \fIinterp\fR will result in errors.
 161 If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
 162 \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
 163 it returns 0.
 164 There are no restrictions on \fIcmdName\fR:  it may refer to
 165 a built-in command, an application-specific command, or a Tcl procedure.
 166 If \fIname\fR contains any \fB::\fR namespace qualifiers,
 167 the command is deleted from the specified namespace.
 168 .PP
 169 Given a token returned by \fBTcl_CreateObjCommand\fR,
 170 \fBTcl_DeleteCommandFromToken\fR deletes the command
 171 from a command interpreter.
 172 It will delete a command even if that command has been renamed.
 173 Once the call completes, attempts to invoke the command in
 174 \fIinterp\fR will result in errors.
 175 If the command corresponding to \fItoken\fR
 176 has already been deleted from \fIinterp\fR then
 177 \fBTcl_DeleteCommand\fR does nothing and returns -1;
 178 otherwise it returns 0.
 179 .PP
 180 \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
 181 exists as a command in \fIinterp\fR.
 182 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 183 to identify a command in a particular namespace.
 184 If the command is not found, then it returns 0.
 185 Otherwise it places information about the command
 186 in the \fBTcl_CmdInfo\fR structure
 187 pointed to by \fIinfoPtr\fR and returns 1.
 188 A \fBTcl_CmdInfo\fR structure has the following fields:
 189 .CS
 190 typedef struct Tcl_CmdInfo {
 191     int isNativeObjectProc;
 192     Tcl_ObjCmdProc *objProc;
 193     ClientData objClientData;
 194     Tcl_CmdProc *proc;
 195     ClientData clientData;
 196     Tcl_CmdDeleteProc *deleteProc;
 197     ClientData deleteData;
 198     Tcl_Namespace *namespacePtr;
 199 } Tcl_CmdInfo;
 200 .CE
 201 The \fIisNativeObjectProc\fR field has the value 1
 202 if \fBTcl_CreateObjCommand\fR was called to register the command;
 203 it is 0 if only \fBTcl_CreateCommand\fR was called.
 204 It allows a program to determine whether it is faster to
 205 call \fIobjProc\fR or \fIproc\fR:
 206 \fIobjProc\fR is normally faster
 207 if \fIisNativeObjectProc\fR has the value 1.
 208 The fields \fIobjProc\fR and \fIobjClientData\fR
 209 have the same meaning as the \fIproc\fR and \fIclientData\fR
 210 arguments to \fBTcl_CreateObjCommand\fR;
 211 they hold information about the object-based command procedure
 212 that the Tcl interpreter calls to implement the command.
 213 The fields \fIproc\fR and \fIclientData\fR
 214 hold information about the string-based command procedure
 215 that implements the command.
 216 If \fBTcl_CreateCommand\fR was called for this command,
 217 this is the procedure passed to it;
 218 otherwise, this is a compatibility procedure
 219 registered by \fBTcl_CreateObjCommand\fR
 220 that simply calls the command's
 221 object-based procedure after converting its string arguments to Tcl objects.
 222 The field \fIdeleteData\fR is the ClientData value
 223 to pass to \fIdeleteProc\fR;  it is normally the same as
 224 \fIclientData\fR but may be set independently using the
 225 \fBTcl_SetCommandInfo\fR procedure.
 226 The field \fInamespacePtr\fR holds a pointer to the
 227 Tcl_Namespace that contains the command.
 228 .PP
 229 \fBTcl_SetCommandInfo\fR is used to modify the procedures and
 230 ClientData values associated with a command.
 231 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
 232 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 233 to identify a command in a particular namespace.
 234 If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
 235 Otherwise, it copies the information from \fI*infoPtr\fR to
 236 Tcl's internal structure for the command and returns 1.
 237 Note that this procedure allows the ClientData for a command's
 238 deletion procedure to be given a different value than the ClientData
 239 for its command procedure.
 240 Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace;
 241 you must use \fBTcl_RenameCommand\fR to do that.
 242 .PP
 243 \fBTcl_GetCommandName\fR provides a mechanism for tracking commands
 244 that have been renamed.
 245 Given a token returned by \fBTcl_CreateObjCommand\fR
 246 when the command was created, \fBTcl_GetCommandName\fR returns the
 247 string name of the command.  If the command has been renamed since it
 248 was created, then \fBTcl_GetCommandName\fR returns the current name.
 249 This name does not include any \fB::\fR namespace qualifiers.
 250 The command corresponding to \fItoken\fR must not have been deleted.
 251 The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
 252 owned by Tcl and is only guaranteed to retain its value as long as the
 253 command isn't deleted or renamed;  callers should copy the string if
 254 they need to keep it for a long time.
 255
 256 .SH "SEE ALSO"
 257 Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
 258
 259 .SH KEYWORDS
 260 bind, command, create, delete, namespace, object