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