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 |
---|