util/src/TclTk/tcl8.6.12/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 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 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
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 Tcl_Command
  17 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  18 .sp
  19 int
  20 \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  21 .sp
  22 int
  23 \fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
  24 .sp
  25 int
  26 \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  27 .sp
  28 int
  29 \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
  30 .sp
  31 int
  32 \fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
  33 .sp
  34 int
  35 \fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
  36 .sp
  37 const char *
  38 \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
  39 .sp
  40 void
  41 \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR)
  42 .sp
  43 Tcl_Command
  44 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
  45 .SH ARGUMENTS
  46 .AS Tcl_CmdDeleteProc *deleteProc in/out
  47 .AP Tcl_Interp *interp in
  48 Interpreter in which to create a new command or that contains a command.
  49 .AP "const char" *cmdName in
  50 Name of command.
  51 .AP Tcl_ObjCmdProc *proc in
  52 Implementation of the new command: \fIproc\fR will be called whenever
  53 \fIcmdName\fR is invoked as a command.
  54 .AP ClientData clientData in
  55 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  56 .AP Tcl_CmdDeleteProc *deleteProc in
  57 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  58 allows for command-specific cleanup. If NULL, then no procedure is
  59 called before the command is deleted.
  60 .AP Tcl_Command token in
  61 Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
  62 The command must not have been deleted.
  63 .AP Tcl_CmdInfo *infoPtr in/out
  64 Pointer to structure containing various information about a
  65 Tcl command.
  66 .AP Tcl_Obj *objPtr in
  67 Value containing the name of a Tcl command.
  68 .BE
  69 .SH DESCRIPTION
  70 .PP
  71 \fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
  72 and associates it with procedure \fIproc\fR
  73 such that whenever \fIname\fR is
  74 invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
  75 the Tcl interpreter will call \fIproc\fR to process the command.
  76 .PP
  77 \fBTcl_CreateObjCommand\fR deletes any existing command
  78 \fIname\fR already associated with the interpreter
  79 (however see below for an exception where the existing command
  80 is not deleted).
  81 It returns a token that may be used to refer
  82 to the command in subsequent calls to \fBTcl_GetCommandName\fR.
  83 If \fIname\fR contains any \fB::\fR namespace qualifiers,
  84 then the command is added to the specified namespace;
  85 otherwise the command is added to the global namespace.
  86 If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
  87 the process of being deleted, then it does not create a new command
  88 and it returns NULL.
  89 \fIproc\fR should have arguments and result that match the type
  90 \fBTcl_ObjCmdProc\fR:
  91 .PP
  92 .CS
  93 typedef int \fBTcl_ObjCmdProc\fR(
  94         ClientData \fIclientData\fR,
  95         Tcl_Interp *\fIinterp\fR,
  96         int \fIobjc\fR,
  97         Tcl_Obj *const \fIobjv\fR[]);
  98 .CE
  99 .PP
 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 values
 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 values.  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 value argument.  For instance, the user may call
 119 \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
 120 representation of that value; that call may change the type of the value
 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 a value 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 .PP
 165 .CS
 166 typedef void \fBTcl_CmdDeleteProc\fR(
 167         ClientData \fIclientData\fR);
 168 .CE
 169 .PP
 170 The \fIclientData\fR argument will be the same as the \fIclientData\fR
 171 argument passed to \fBTcl_CreateObjCommand\fR.
 172 .PP
 173 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
 174 Once the call completes, attempts to invoke \fIcmdName\fR in
 175 \fIinterp\fR will result in errors.
 176 If \fIcmdName\fR is not bound as a command in \fIinterp\fR then
 177 \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
 178 it returns 0.
 179 There are no restrictions on \fIcmdName\fR:  it may refer to
 180 a built-in command, an application-specific command, or a Tcl procedure.
 181 If \fIname\fR contains any \fB::\fR namespace qualifiers,
 182 the command is deleted from the specified namespace.
 183 .PP
 184 Given a token returned by \fBTcl_CreateObjCommand\fR,
 185 \fBTcl_DeleteCommandFromToken\fR deletes the command
 186 from a command interpreter.
 187 It will delete a command even if that command has been renamed.
 188 Once the call completes, attempts to invoke the command in
 189 \fIinterp\fR will result in errors.
 190 If the command corresponding to \fItoken\fR
 191 has already been deleted from \fIinterp\fR then
 192 \fBTcl_DeleteCommand\fR does nothing and returns -1;
 193 otherwise it returns 0.
 194 .PP
 195 \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
 196 exists as a command in \fIinterp\fR.
 197 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 198 to identify a command in a particular namespace.
 199 If the command is not found, then it returns 0.
 200 Otherwise it places information about the command
 201 in the \fBTcl_CmdInfo\fR structure
 202 pointed to by \fIinfoPtr\fR and returns 1.
 203 A \fBTcl_CmdInfo\fR structure has the following fields:
 204 .PP
 205 .CS
 206 typedef struct Tcl_CmdInfo {
 207     int \fIisNativeObjectProc\fR;
 208     Tcl_ObjCmdProc *\fIobjProc\fR;
 209     ClientData \fIobjClientData\fR;
 210     Tcl_CmdProc *\fIproc\fR;
 211     ClientData \fIclientData\fR;
 212     Tcl_CmdDeleteProc *\fIdeleteProc\fR;
 213     ClientData \fIdeleteData\fR;
 214     Tcl_Namespace *\fInamespacePtr\fR;
 215 } \fBTcl_CmdInfo\fR;
 216 .CE
 217 .PP
 218 The \fIisNativeObjectProc\fR field has the value 1
 219 if \fBTcl_CreateObjCommand\fR was called to register the command;
 220 it is 0 if only \fBTcl_CreateCommand\fR was called.
 221 It allows a program to determine whether it is faster to
 222 call \fIobjProc\fR or \fIproc\fR:
 223 \fIobjProc\fR is normally faster
 224 if \fIisNativeObjectProc\fR has the value 1.
 225 The fields \fIobjProc\fR and \fIobjClientData\fR
 226 have the same meaning as the \fIproc\fR and \fIclientData\fR
 227 arguments to \fBTcl_CreateObjCommand\fR;
 228 they hold information about the value-based command procedure
 229 that the Tcl interpreter calls to implement the command.
 230 The fields \fIproc\fR and \fIclientData\fR
 231 hold information about the string-based command procedure
 232 that implements the command.
 233 If \fBTcl_CreateCommand\fR was called for this command,
 234 this is the procedure passed to it;
 235 otherwise, this is a compatibility procedure
 236 registered by \fBTcl_CreateObjCommand\fR
 237 that simply calls the command's
 238 value-based procedure after converting its string arguments to Tcl values.
 239 The field \fIdeleteData\fR is the ClientData value
 240 to pass to \fIdeleteProc\fR;  it is normally the same as
 241 \fIclientData\fR but may be set independently using the
 242 \fBTcl_SetCommandInfo\fR procedure.
 243 The field \fInamespacePtr\fR holds a pointer to the
 244 Tcl_Namespace that contains the command.
 245 .PP
 246 \fBTcl_GetCommandInfoFromToken\fR is identical to
 247 \fBTcl_GetCommandInfo\fR except that it uses a command token returned
 248 from \fBTcl_CreateObjCommand\fR in place of the command name.  If the
 249 \fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1
 250 and fills in the structure designated by \fIinfoPtr\fR.
 251 .PP
 252 \fBTcl_SetCommandInfo\fR is used to modify the procedures and
 253 ClientData values associated with a command.
 254 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
 255 \fIcmdName\fR may include \fB::\fR namespace qualifiers
 256 to identify a command in a particular namespace.
 257 If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
 258 Otherwise, it copies the information from \fI*infoPtr\fR to
 259 Tcl's internal structure for the command and returns 1.
 260 .PP
 261 \fBTcl_SetCommandInfoFromToken\fR is identical to
 262 \fBTcl_SetCommandInfo\fR except that it takes a command token as
 263 returned by \fBTcl_CreateObjCommand\fR instead of the command name.
 264 If the \fItoken\fR parameter is NULL, it returns 0.  Otherwise, it
 265 copies the information from \fI*infoPtr\fR to Tcl's internal structure
 266 for the command and returns 1.
 267 .PP
 268 Note that \fBTcl_SetCommandInfo\fR and
 269 \fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
 270 command's deletion procedure to be given a different value than the
 271 ClientData for its command procedure.
 272 .PP
 273 Note that neither \fBTcl_SetCommandInfo\fR nor
 274 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
 275 Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that.
 276 .PP
 277 \fBTcl_GetCommandName\fR provides a mechanism for tracking commands
 278 that have been renamed.
 279 Given a token returned by \fBTcl_CreateObjCommand\fR
 280 when the command was created, \fBTcl_GetCommandName\fR returns the
 281 string name of the command.  If the command has been renamed since it
 282 was created, then \fBTcl_GetCommandName\fR returns the current name.
 283 This name does not include any \fB::\fR namespace qualifiers.
 284 The command corresponding to \fItoken\fR must not have been deleted.
 285 The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
 286 owned by Tcl and is only guaranteed to retain its value as long as the
 287 command is not deleted or renamed;  callers should copy the string if
 288 they need to keep it for a long time.
 289 .PP
 290 \fBTcl_GetCommandFullName\fR produces the fully qualified name
 291 of a command from a command token.
 292 The name, including all namespace prefixes,
 293 is appended to the value specified by \fIobjPtr\fR.
 294 .PP
 295 \fBTcl_GetCommandFromObj\fR returns a token for the command
 296 specified by the name in a \fBTcl_Obj\fR.
 297 The command name is resolved relative to the current namespace.
 298 Returns NULL if the command is not found.
 299 .SH "SEE ALSO"
 300 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
 301 .SH KEYWORDS
 302 bind, command, create, delete, namespace, value