1Tcl_CreateObjCommand(3) Tcl Library Procedures Tcl_CreateObjCommand(3)
2______________________________________________________________________________
6
8 Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken,
9 Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo,
10 Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFull‐
11 Name, Tcl_GetCommandFromObj - implement new commands in C
12
14 #include <tcl.h>
15 Tcl_Command
17 Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)
18 int
20 Tcl_DeleteCommand(interp, cmdName)
21 int
23 Tcl_DeleteCommandFromToken(interp, token)
24 int
26 Tcl_GetCommandInfo(interp, cmdName, infoPtr)
27 int
29 Tcl_SetCommandInfo(interp, cmdName, infoPtr)
30 int
32 Tcl_GetCommandInfoFromToken(token, infoPtr)
33 int
35 Tcl_SetCommandInfoFromToken(token, infoPtr)
36 const char *
38 Tcl_GetCommandName(interp, token)
39 void
41 Tcl_GetCommandFullName(interp, token, objPtr)
42 Tcl_Command
44 Tcl_GetCommandFromObj(interp, objPtr)
45
47 Tcl_Interp *interp (in) Interpreter in which to
48 create a new command or
49 that contains a command.
50 char *cmdName (in) Name of command.
52 Tcl_ObjCmdProc *proc (in) Implementation of the new
54 command: proc will be
55 called whenever cmdName is
56 invoked as a command.
57 ClientData clientData (in) Arbitrary one-word value to
59 pass to proc and
60 deleteProc.
61 Tcl_CmdDeleteProc *deleteProc (in) Procedure to call before
63 cmdName is deleted from the
64 interpreter; allows for
65 command-specific cleanup.
66 If NULL, then no procedure
67 is called before the com‐
68 mand is deleted.
69 Tcl_Command token (in) Token for command, returned
71 by previous call to
72 Tcl_CreateObjCommand. The
73 command must not have been
74 deleted.
75 Tcl_CmdInfo *infoPtr (in/out) Pointer to structure con‐
77 taining various information
78 about a Tcl command.
79 Tcl_Obj *objPtr (in) Value containing the name
81 of a Tcl command.
82______________________________________________________________________________
83
85 Tcl_CreateObjCommand defines a new command in interp and associates it
86 with procedure proc such that whenever name is invoked as a Tcl command
87 (e.g., via a call to Tcl_EvalObjEx) the Tcl interpreter will call proc
88 to process the command.
89 Tcl_CreateObjCommand deletes any existing command name already associ‐
91 ated with the interpreter (however see below for an exception where the
92 existing command is not deleted). It returns a token that may be used
93 to refer to the command in subsequent calls to Tcl_GetCommandName. If
94 name contains any :: namespace qualifiers, then the command is added to
95 the specified namespace; otherwise the command is added to the global
96 namespace. If Tcl_CreateObjCommand is called for an interpreter that
97 is in the process of being deleted, then it does not create a new com‐
98 mand and it returns NULL. proc should have arguments and result that
99 match the type Tcl_ObjCmdProc:
100 typedef int Tcl_ObjCmdProc(
102 ClientData clientData,
103 Tcl_Interp *interp,
104 int objc,
105 Tcl_Obj *const objv[]);
106 When proc is invoked, the clientData and interp parameters will be
108 copies of the clientData and interp arguments given to Tcl_CreateObj‐
109 Command. Typically, clientData points to an application-specific data
110 structure that describes what to do when the command procedure is
111 invoked. Objc and objv describe the arguments to the command, objc giv‐
112 ing the number of argument values (including the command name) and objv
113 giving the values of the arguments. The objv array will contain objc
114 values, pointing to the argument values. Unlike argv[argv] used in a
115 string-based command procedure, objv[objc] will not contain NULL.
116 Additionally, when proc is invoked, it must not modify the contents of
118 the objv array by assigning new pointer values to any element of the
119 array (for example, objv[2] = NULL) because this will cause memory to
120 be lost and the runtime stack to be corrupted. The const in the decla‐
121 ration of objv will cause ANSI-compliant compilers to report any such
122 attempted assignment as an error. However, it is acceptable to modify
123 the internal representation of any individual value argument. For
124 instance, the user may call Tcl_GetIntFromObj on objv[2] to obtain the
125 integer representation of that value; that call may change the type of
126 the value that objv[2] points at, but will not change where objv[2]
127 points.
128 proc must return an integer code that is either TCL_OK, TCL_ERROR,
130 TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. See the Tcl overview man page
131 for details on what these codes mean. Most normal commands will only
132 return TCL_OK or TCL_ERROR. In addition, if proc needs to return a
133 non-empty result, it can call Tcl_SetObjResult to set the interpreter's
134 result. In the case of a TCL_OK return code this gives the result of
135 the command, and in the case of TCL_ERROR this gives an error message.
136 Before invoking a command procedure, Tcl_EvalObjEx sets interpreter's
137 result to point to a value representing an empty string, so simple com‐
138 mands can return an empty result by doing nothing at all.
139 The contents of the objv array belong to Tcl and are not guaranteed to
141 persist once proc returns: proc should not modify them. Call Tcl_SetO‐
142 bjResult if you want to return something from the objv array.
143 Ordinarily, Tcl_CreateObjCommand deletes any existing command name
145 already associated with the interpreter. However, if the existing com‐
146 mand was created by a previous call to Tcl_CreateCommand, Tcl_CreateOb‐
147 jCommand does not delete the command but instead arranges for the Tcl
148 interpreter to call the Tcl_ObjCmdProc proc in the future. The old
149 string-based Tcl_CmdProc associated with the command is retained and
150 its address can be obtained by subsequent Tcl_GetCommandInfo calls.
151 This is done for backwards compatibility.
152 DeleteProc will be invoked when (if) name is deleted. This can occur
154 through a call to Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, or
155 Tcl_DeleteInterp, or by replacing name in another call to Tcl_CreateOb‐
156 jCommand. DeleteProc is invoked before the command is deleted, and
157 gives the application an opportunity to release any structures associ‐
158 ated with the command. DeleteProc should have arguments and result
159 that match the type Tcl_CmdDeleteProc:
160 typedef void Tcl_CmdDeleteProc(
162 ClientData clientData);
163 The clientData argument will be the same as the clientData argument
165 passed to Tcl_CreateObjCommand.
166 Tcl_DeleteCommand deletes a command from a command interpreter. Once
168 the call completes, attempts to invoke cmdName in interp will result in
169 errors. If cmdName is not bound as a command in interp then
170 Tcl_DeleteCommand does nothing and returns -1; otherwise it returns 0.
171 There are no restrictions on cmdName: it may refer to a built-in com‐
172 mand, an application-specific command, or a Tcl procedure. If name
173 contains any :: namespace qualifiers, the command is deleted from the
174 specified namespace.
175 Given a token returned by Tcl_CreateObjCommand, Tcl_DeleteCommandFrom‐
177 Token deletes the command from a command interpreter. It will delete a
178 command even if that command has been renamed. Once the call com‐
179 pletes, attempts to invoke the command in interp will result in errors.
180 If the command corresponding to token has already been deleted from
181 interp then Tcl_DeleteCommand does nothing and returns -1; otherwise it
182 returns 0.
183 Tcl_GetCommandInfo checks to see whether its cmdName argument exists as
185 a command in interp. cmdName may include :: namespace qualifiers to
186 identify a command in a particular namespace. If the command is not
187 found, then it returns 0. Otherwise it places information about the
188 command in the Tcl_CmdInfo structure pointed to by infoPtr and returns
189 1. A Tcl_CmdInfo structure has the following fields:
190 typedef struct Tcl_CmdInfo {
192 int isNativeObjectProc;
193 Tcl_ObjCmdProc *objProc;
194 ClientData objClientData;
195 Tcl_CmdProc *proc;
196 ClientData clientData;
197 Tcl_CmdDeleteProc *deleteProc;
198 ClientData deleteData;
199 Tcl_Namespace *namespacePtr;
200 } Tcl_CmdInfo;
201 The isNativeObjectProc field has the value 1 if Tcl_CreateObjCommand
203 was called to register the command; it is 0 if only Tcl_CreateCommand
204 was called. It allows a program to determine whether it is faster to
205 call objProc or proc: objProc is normally faster if isNativeObjectProc
206 has the value 1. The fields objProc and objClientData have the same
207 meaning as the proc and clientData arguments to Tcl_CreateObjCommand;
208 they hold information about the value-based command procedure that the
209 Tcl interpreter calls to implement the command. The fields proc and
210 clientData hold information about the string-based command procedure
211 that implements the command. If Tcl_CreateCommand was called for this
212 command, this is the procedure passed to it; otherwise, this is a com‐
213 patibility procedure registered by Tcl_CreateObjCommand that simply
214 calls the command's value-based procedure after converting its string
215 arguments to Tcl values. The field deleteData is the ClientData value
216 to pass to deleteProc; it is normally the same as clientData but may
217 be set independently using the Tcl_SetCommandInfo procedure. The field
218 namespacePtr holds a pointer to the Tcl_Namespace that contains the
219 command.
220 Tcl_GetCommandInfoFromToken is identical to Tcl_GetCommandInfo except
222 that it uses a command token returned from Tcl_CreateObjCommand in
223 place of the command name. If the token parameter is NULL, it returns
224 0; otherwise, it returns 1 and fills in the structure designated by
225 infoPtr.
226 Tcl_SetCommandInfo is used to modify the procedures and ClientData val‐
228 ues associated with a command. Its cmdName argument is the name of a
229 command in interp. cmdName may include :: namespace qualifiers to
230 identify a command in a particular namespace. If this command does not
231 exist then Tcl_SetCommandInfo returns 0. Otherwise, it copies the
232 information from *infoPtr to Tcl's internal structure for the command
233 and returns 1.
234 Tcl_SetCommandInfoFromToken is identical to Tcl_SetCommandInfo except
236 that it takes a command token as returned by Tcl_CreateObjCommand
237 instead of the command name. If the token parameter is NULL, it
238 returns 0. Otherwise, it copies the information from *infoPtr to Tcl's
239 internal structure for the command and returns 1.
240 Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken both allow
242 the ClientData for a command's deletion procedure to be given a differ‐
243 ent value than the ClientData for its command procedure.
244 Note that neither Tcl_SetCommandInfo nor Tcl_SetCommandInfoFromToken
246 will change a command's namespace. Use Tcl_Eval to call the rename
247 command to do that.
248 Tcl_GetCommandName provides a mechanism for tracking commands that have
250 been renamed. Given a token returned by Tcl_CreateObjCommand when the
251 command was created, Tcl_GetCommandName returns the string name of the
252 command. If the command has been renamed since it was created, then
253 Tcl_GetCommandName returns the current name. This name does not
254 include any :: namespace qualifiers. The command corresponding to
255 token must not have been deleted. The string returned by Tcl_GetCom‐
256 mandName is in dynamic memory owned by Tcl and is only guaranteed to
257 retain its value as long as the command is not deleted or renamed;
258 callers should copy the string if they need to keep it for a long time.
259 Tcl_GetCommandFullName produces the fully qualified name of a command
261 from a command token. The name, including all namespace prefixes, is
262 appended to the value specified by objPtr.
263 Tcl_GetCommandFromObj returns a token for the command specified by the
265 name in a Tcl_Obj. The command name is resolved relative to the cur‐
266 rent namespace. Returns NULL if the command is not found.
267
269 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
270
272 bind, command, create, delete, namespace, value
273Tcl 8.0 Tcl_CreateObjCommand(3)