1Tcl_CreateObjCommand(3)     Tcl Library Procedures     Tcl_CreateObjCommand(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

14       #include <tcl.h>
15
16       Tcl_Command
17       Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)
18
19       int
20       Tcl_DeleteCommand(interp, cmdName)
21
22       int
23       Tcl_DeleteCommandFromToken(interp, token)
24
25       int
26       Tcl_GetCommandInfo(interp, cmdName, infoPtr)
27
28       int
29       Tcl_SetCommandInfo(interp, cmdName, infoPtr)
30
31       int
32       Tcl_GetCommandInfoFromToken(token, infoPtr)
33
34       int
35       Tcl_SetCommandInfoFromToken(token, infoPtr)
36
37       const char *
38       Tcl_GetCommandName(interp, token)
39
40       void
41       Tcl_GetCommandFullName(interp, token, objPtr)
42
43       Tcl_Command
44       Tcl_GetCommandFromObj(interp, objPtr)
45

ARGUMENTS

47       Tcl_Interp *interp (in)                     Interpreter  in  which   to
48                                                   create  a  new  command  or
49                                                   that contains a command.
50
51       const char *cmdName (in)                    Name of command.
52
53       Tcl_ObjCmdProc *proc (in)                   Implementation of  the  new
54                                                   command:   proc   will   be
55                                                   called whenever cmdName  is
56                                                   invoked as a command.
57
58       ClientData clientData (in)                  Arbitrary one-word value to
59                                                   pass    to     proc     and
60                                                   deleteProc.
61
62       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
70       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
76       Tcl_CmdInfo *infoPtr (in/out)               Pointer  to  structure con‐
77                                                   taining various information
78                                                   about a Tcl command.
79
80       Tcl_Obj *objPtr (in)                        Value  containing  the name
81                                                   of a Tcl command.
82______________________________________________________________________________
83

DESCRIPTION

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
90       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
101              typedef int Tcl_ObjCmdProc(
102                      ClientData clientData,
103                      Tcl_Interp *interp,
104                      int objc,
105                      Tcl_Obj *const objv[]);
106
107       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 in‐
111       voked. Objc and objv describe the arguments to the command, objc giving
112       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
117       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  in‐
124       stance,  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
129       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
140       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
144       Ordinarily,  Tcl_CreateObjCommand deletes any existing command name al‐
145       ready 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
153       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
161              typedef void Tcl_CmdDeleteProc(
162                      ClientData clientData);
163
164       The clientData argument will be the same  as  the  clientData  argument
165       passed to Tcl_CreateObjCommand.
166
167       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
176       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 in‐
181       terp  then  Tcl_DeleteCommand does nothing and returns -1; otherwise it
182       returns 0.
183
184       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
191              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
202       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
221       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 in‐
225       foPtr.
226
227       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  in‐
232       formation from *infoPtr to Tcl's internal structure for the command and
233       returns 1.
234
235       Tcl_SetCommandInfoFromToken is identical to  Tcl_SetCommandInfo  except
236       that  it  takes a command token as returned by Tcl_CreateObjCommand in‐
237       stead of the command name.  If the token parameter is NULL, it  returns
238       0.   Otherwise, it copies the information from *infoPtr to Tcl's inter‐
239       nal structure for the command and returns 1.
240
241       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
245       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
249       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  in‐
254       clude  any :: namespace qualifiers.  The command corresponding to token
255       must not have been deleted.  The string returned by  Tcl_GetCommandName
256       is  in dynamic memory owned by Tcl and is only guaranteed to retain its
257       value as long as the command is not deleted or renamed;  callers should
258       copy the string if they need to keep it for a long time.
259
260       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
264       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

SEE ALSO

269       Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
270

KEYWORDS

272       bind, command, create, delete, namespace, value
273
274
275
276Tcl                                   8.0              Tcl_CreateObjCommand(3)
Impressum