2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 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
280 \fB#include <tcl.h>\fR
283 \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
286 \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
289 \fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
292 \fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
295 \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
298 \fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
301 \fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR)
304 \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
307 \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR)
310 \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
312 .AS Tcl_CmdDeleteProc *deleteProc in/out
313 .AP Tcl_Interp *interp in
314 Interpreter in which to create a new command or that contains a command.
317 .AP Tcl_ObjCmdProc *proc in
318 Implementation of the new command: \fIproc\fR will be called whenever
319 \fIcmdName\fR is invoked as a command.
320 .AP ClientData clientData in
321 Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
322 .AP Tcl_CmdDeleteProc *deleteProc in
323 Procedure to call before \fIcmdName\fR is deleted from the interpreter;
324 allows for command-specific cleanup. If NULL, then no procedure is
325 called before the command is deleted.
326 .AP Tcl_Command token in
327 Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
328 The command must not have been deleted.
329 .AP Tcl_CmdInfo *infoPtr in/out
330 Pointer to structure containing various information about a
332 .AP Tcl_Obj *objPtr in
333 Value containing the name of a Tcl command.
337 \fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
338 and associates it with procedure \fIproc\fR
339 such that whenever \fIname\fR is
340 invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
341 the Tcl interpreter will call \fIproc\fR to process the command.
343 \fBTcl_CreateObjCommand\fR deletes any existing command
344 \fIname\fR already associated with the interpreter
345 (however see below for an exception where the existing command
347 It returns a token that may be used to refer
348 to the command in subsequent calls to \fBTcl_GetCommandName\fR.
349 If \fIname\fR contains any \fB::\fR namespace qualifiers,
350 then the command is added to the specified namespace;
351 otherwise the command is added to the global namespace.
352 If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
353 the process of being deleted, then it does not create a new command
355 \fIproc\fR should have arguments and result that match the type
356 \fBTcl_ObjCmdProc\fR:
359 typedef int \fBTcl_ObjCmdProc\fR(
360 ClientData \fIclientData\fR,
361 Tcl_Interp *\fIinterp\fR,
363 Tcl_Obj *const \fIobjv\fR[]);
366 When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
367 will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
368 \fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
369 application-specific data structure that describes what to do when the
370 command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
371 arguments to the command, \fIobjc\fR giving the number of argument values
372 (including the command name) and \fIobjv\fR giving the values of the
373 arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
374 the argument values. Unlike \fIargv\fR[\fIargv\fR] used in a
375 string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
377 Additionally, when \fIproc\fR is invoked, it must not modify the contents
378 of the \fIobjv\fR array by assigning new pointer values to any element of the
379 array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
380 cause memory to be lost and the runtime stack to be corrupted. The
381 \fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
382 compilers to report any such attempted assignment as an error. However,
383 it is acceptable to modify the internal representation of any individual
384 value argument. For instance, the user may call
385 \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
386 representation of that value; that call may change the type of the value
387 that \fIobjv\fR[\fB2\fR] points at, but will not change where
388 \fIobjv\fR[\fB2\fR] points.
390 \fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
391 \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
392 See the Tcl overview man page
393 for details on what these codes mean. Most normal commands will only
394 return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
395 In addition, if \fIproc\fR needs to return a non-empty result,
396 it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
397 In the case of a \fBTCL_OK\fR return code this gives the result
399 and in the case of \fBTCL_ERROR\fR this gives an error message.
400 Before invoking a command procedure,
401 \fBTcl_EvalObjEx\fR sets interpreter's result to
402 point to a value representing an empty string, so simple
403 commands can return an empty result by doing nothing at all.
405 The contents of the \fIobjv\fR array belong to Tcl and are not
406 guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
408 Call \fBTcl_SetObjResult\fR if you want
409 to return something from the \fIobjv\fR array.
411 Ordinarily, \fBTcl_CreateObjCommand\fR deletes any existing command
412 \fIname\fR already associated with the interpreter.
413 However, if the existing command was created by a previous call to
414 \fBTcl_CreateCommand\fR,
415 \fBTcl_CreateObjCommand\fR does not delete the command
416 but instead arranges for the Tcl interpreter to call the
417 \fBTcl_ObjCmdProc\fR \fIproc\fR in the future.
418 The old string-based \fBTcl_CmdProc\fR associated with the command
419 is retained and its address can be obtained by subsequent
420 \fBTcl_GetCommandInfo\fR calls. This is done for backwards compatibility.
422 \fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
423 This can occur through a call to \fBTcl_DeleteCommand\fR,
424 \fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
425 or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
426 \fIDeleteProc\fR is invoked before the command is deleted, and gives the
427 application an opportunity to release any structures associated
428 with the command. \fIDeleteProc\fR should have arguments and
429 result that match the type \fBTcl_CmdDeleteProc\fR:
432 typedef void \fBTcl_CmdDeleteProc\fR(
433 ClientData \fIclientData\fR);
436 The \fIclientData\fR argument will be the same as the \fIclientData\fR
437 argument passed to \fBTcl_CreateObjCommand\fR.
439 \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
440 Once the call completes, attempts to invoke \fIcmdName\fR in
441 \fIinterp\fR will result in errors.
442 If \fIcmdName\fR is not bound as a command in \fIinterp\fR then
443 \fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
445 There are no restrictions on \fIcmdName\fR: it may refer to
446 a built-in command, an application-specific command, or a Tcl procedure.
447 If \fIname\fR contains any \fB::\fR namespace qualifiers,
448 the command is deleted from the specified namespace.
450 Given a token returned by \fBTcl_CreateObjCommand\fR,
451 \fBTcl_DeleteCommandFromToken\fR deletes the command
452 from a command interpreter.
453 It will delete a command even if that command has been renamed.
454 Once the call completes, attempts to invoke the command in
455 \fIinterp\fR will result in errors.
456 If the command corresponding to \fItoken\fR
457 has already been deleted from \fIinterp\fR then
458 \fBTcl_DeleteCommand\fR does nothing and returns -1;
459 otherwise it returns 0.
461 \fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
462 exists as a command in \fIinterp\fR.
463 \fIcmdName\fR may include \fB::\fR namespace qualifiers
464 to identify a command in a particular namespace.
465 If the command is not found, then it returns 0.
466 Otherwise it places information about the command
467 in the \fBTcl_CmdInfo\fR structure
468 pointed to by \fIinfoPtr\fR and returns 1.
469 A \fBTcl_CmdInfo\fR structure has the following fields:
472 typedef struct Tcl_CmdInfo {
473 int \fIisNativeObjectProc\fR;
474 Tcl_ObjCmdProc *\fIobjProc\fR;
475 ClientData \fIobjClientData\fR;
476 Tcl_CmdProc *\fIproc\fR;
477 ClientData \fIclientData\fR;
478 Tcl_CmdDeleteProc *\fIdeleteProc\fR;
479 ClientData \fIdeleteData\fR;
480 Tcl_Namespace *\fInamespacePtr\fR;
484 The \fIisNativeObjectProc\fR field has the value 1
485 if \fBTcl_CreateObjCommand\fR was called to register the command;
486 it is 0 if only \fBTcl_CreateCommand\fR was called.
487 It allows a program to determine whether it is faster to
488 call \fIobjProc\fR or \fIproc\fR:
489 \fIobjProc\fR is normally faster
490 if \fIisNativeObjectProc\fR has the value 1.
491 The fields \fIobjProc\fR and \fIobjClientData\fR
492 have the same meaning as the \fIproc\fR and \fIclientData\fR
493 arguments to \fBTcl_CreateObjCommand\fR;
494 they hold information about the value-based command procedure
495 that the Tcl interpreter calls to implement the command.
496 The fields \fIproc\fR and \fIclientData\fR
497 hold information about the string-based command procedure
498 that implements the command.
499 If \fBTcl_CreateCommand\fR was called for this command,
500 this is the procedure passed to it;
501 otherwise, this is a compatibility procedure
502 registered by \fBTcl_CreateObjCommand\fR
503 that simply calls the command's
504 value-based procedure after converting its string arguments to Tcl values.
505 The field \fIdeleteData\fR is the ClientData value
506 to pass to \fIdeleteProc\fR; it is normally the same as
507 \fIclientData\fR but may be set independently using the
508 \fBTcl_SetCommandInfo\fR procedure.
509 The field \fInamespacePtr\fR holds a pointer to the
510 Tcl_Namespace that contains the command.
512 \fBTcl_GetCommandInfoFromToken\fR is identical to
513 \fBTcl_GetCommandInfo\fR except that it uses a command token returned
514 from \fBTcl_CreateObjCommand\fR in place of the command name. If the
515 \fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1
516 and fills in the structure designated by \fIinfoPtr\fR.
518 \fBTcl_SetCommandInfo\fR is used to modify the procedures and
519 ClientData values associated with a command.
520 Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
521 \fIcmdName\fR may include \fB::\fR namespace qualifiers
522 to identify a command in a particular namespace.
523 If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
524 Otherwise, it copies the information from \fI*infoPtr\fR to
525 Tcl's internal structure for the command and returns 1.
527 \fBTcl_SetCommandInfoFromToken\fR is identical to
528 \fBTcl_SetCommandInfo\fR except that it takes a command token as
529 returned by \fBTcl_CreateObjCommand\fR instead of the command name.
530 If the \fItoken\fR parameter is NULL, it returns 0. Otherwise, it
531 copies the information from \fI*infoPtr\fR to Tcl's internal structure
532 for the command and returns 1.
534 Note that \fBTcl_SetCommandInfo\fR and
535 \fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
536 command's deletion procedure to be given a different value than the
537 ClientData for its command procedure.
539 Note that neither \fBTcl_SetCommandInfo\fR nor
540 \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
541 Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that.
543 \fBTcl_GetCommandName\fR provides a mechanism for tracking commands
544 that have been renamed.
545 Given a token returned by \fBTcl_CreateObjCommand\fR
546 when the command was created, \fBTcl_GetCommandName\fR returns the
547 string name of the command. If the command has been renamed since it
548 was created, then \fBTcl_GetCommandName\fR returns the current name.
549 This name does not include any \fB::\fR namespace qualifiers.
550 The command corresponding to \fItoken\fR must not have been deleted.
551 The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
552 owned by Tcl and is only guaranteed to retain its value as long as the
553 command is not deleted or renamed; callers should copy the string if
554 they need to keep it for a long time.
556 \fBTcl_GetCommandFullName\fR produces the fully qualified name
557 of a command from a command token.
558 The name, including all namespace prefixes,
559 is appended to the value specified by \fIobjPtr\fR.
561 \fBTcl_GetCommandFromObj\fR returns a token for the command
562 specified by the name in a \fBTcl_Obj\fR.
563 The command name is resolved relative to the current namespace.
564 Returns NULL if the command is not found.
566 Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
568 bind, command, create, delete, namespace, value