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