diff options
Diffstat (limited to 'doc/CrtObjCmd.3')
| -rw-r--r-- | doc/CrtObjCmd.3 | 101 |
1 files changed, 67 insertions, 34 deletions
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 838cbbe..005bf97 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -4,13 +4,11 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.5 2001/04/24 20:59:17 kennykb Exp $ -'\" -.so man.macros .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C +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 .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -30,17 +28,25 @@ int int \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR) .sp -.VS 8.4 -CONST char * -.VE +int +\fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR) +.sp +int +\fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR) +.sp +const char * \fBTcl_GetCommandName\fR(\fIinterp, token\fR) +.sp +void +\fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR) +.sp +Tcl_Command +\fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR) .SH ARGUMENTS -.AS Tcl_ObjCmdProc *deleteProc in/out +.AS Tcl_CmdDeleteProc *deleteProc in/out .AP Tcl_Interp *interp in Interpreter in which to create a new command or that contains a command. -.VS 8.4 .AP char *cmdName in -.VE Name of command. .AP Tcl_ObjCmdProc *proc in Implementation of the new command: \fIproc\fR will be called whenever @@ -57,6 +63,8 @@ The command must not have been deleted. .AP Tcl_CmdInfo *infoPtr in/out Pointer to structure containing various information about a Tcl command. +.AP Tcl_Obj *objPtr in +Object containing the name of a Tcl command. .BE .SH DESCRIPTION .PP @@ -82,11 +90,10 @@ and it returns NULL. \fBTcl_ObjCmdProc\fR: .CS typedef int Tcl_ObjCmdProc( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIobjc\fR, -.VS - Tcl_Obj *CONST \fIobjv\fR[]); + ClientData \fIclientData\fR, + Tcl_Interp *\fIinterp\fR, + int \fIobjc\fR, + Tcl_Obj *const \fIobjv\fR[]); .CE When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to @@ -103,7 +110,7 @@ Additionally, when \fIproc\fR is invoked, it must not modify the contents of the \fIobjv\fR array by assigning new pointer values to any element of the array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will cause memory to be lost and the runtime stack to be corrupted. The -\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant +\fBconst\fR in the declaration of \fIobjv\fR will cause ANSI-compliant compilers to report any such attempted assignment as an error. However, it is acceptable to modify the internal representation of any individual object argument. For instance, the user may call @@ -111,7 +118,6 @@ object argument. For instance, the user may call representation of that object; that call may change the type of the object that \fIobjv\fR[\fB2\fR] points at, but will not change where \fIobjv\fR[\fB2\fR] points. -.VE .PP \fIproc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. @@ -154,7 +160,8 @@ application an opportunity to release any structures associated with the command. \fIDeleteProc\fR should have arguments and result that match the type \fBTcl_CmdDeleteProc\fR: .CS -typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR); +typedef void Tcl_CmdDeleteProc( + ClientData \fIclientData\fR); .CE The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateObjCommand\fR. @@ -162,7 +169,7 @@ argument passed to \fBTcl_CreateObjCommand\fR. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter. Once the call completes, attempts to invoke \fIcmdName\fR in \fIinterp\fR will result in errors. -If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then +If \fIcmdName\fR is not bound as a command in \fIinterp\fR then \fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise it returns 0. There are no restrictions on \fIcmdName\fR: it may refer to @@ -192,14 +199,14 @@ pointed to by \fIinfoPtr\fR and returns 1. A \fBTcl_CmdInfo\fR structure has the following fields: .CS typedef struct Tcl_CmdInfo { - int isNativeObjectProc; - Tcl_ObjCmdProc *objProc; - ClientData objClientData; - Tcl_CmdProc *proc; - ClientData clientData; - Tcl_CmdDeleteProc *deleteProc; - ClientData deleteData; - Tcl_Namespace *namespacePtr; + int \fIisNativeObjectProc\fR; + Tcl_ObjCmdProc *\fIobjProc\fR; + ClientData \fIobjClientData\fR; + Tcl_CmdProc *\fIproc\fR; + ClientData \fIclientData\fR; + Tcl_CmdDeleteProc *\fIdeleteProc\fR; + ClientData \fIdeleteData\fR; + Tcl_Namespace *\fInamespacePtr\fR; } Tcl_CmdInfo; .CE The \fIisNativeObjectProc\fR field has the value 1 @@ -230,6 +237,12 @@ to pass to \fIdeleteProc\fR; it is normally the same as The field \fInamespacePtr\fR holds a pointer to the Tcl_Namespace that contains the command. .PP +\fBTcl_GetCommandInfoFromToken\fR is identical to +\fBTcl_GetCommandInfo\fR except that it uses a command token returned +from \fBTcl_CreateObjCommand\fR in place of the command name. If the +\fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1 +and fills in the structure designated by \fIinfoPtr\fR. +.PP \fBTcl_SetCommandInfo\fR is used to modify the procedures and ClientData values associated with a command. Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR. @@ -238,11 +251,22 @@ to identify a command in a particular namespace. If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0. Otherwise, it copies the information from \fI*infoPtr\fR to Tcl's internal structure for the command and returns 1. -Note that this procedure allows the ClientData for a command's -deletion procedure to be given a different value than the ClientData -for its command procedure. -Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace; -you must use \fBTcl_RenameCommand\fR to do that. +.PP +\fBTcl_SetCommandInfoFromToken\fR is identical to +\fBTcl_SetCommandInfo\fR except that it takes a command token as +returned by \fBTcl_CreateObjCommand\fR instead of the command name. +If the \fItoken\fR parameter is NULL, it returns 0. Otherwise, it +copies the information from \fI*infoPtr\fR to Tcl's internal structure +for the command and returns 1. +.PP +Note that \fBTcl_SetCommandInfo\fR and +\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a +command's deletion procedure to be given a different value than the +ClientData for its command procedure. +.PP +Note that neither \fBTcl_SetCommandInfo\fR nor +\fBTcl_SetCommandInfoFromToken\fR will change a command's namespace. +Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that. .PP \fBTcl_GetCommandName\fR provides a mechanism for tracking commands that have been renamed. @@ -254,9 +278,18 @@ This name does not include any \fB::\fR namespace qualifiers. The command corresponding to \fItoken\fR must not have been deleted. The string returned by \fBTcl_GetCommandName\fR is in dynamic memory owned by Tcl and is only guaranteed to retain its value as long as the -command isn't deleted or renamed; callers should copy the string if +command is not deleted or renamed; callers should copy the string if they need to keep it for a long time. - +.PP +\fBTcl_GetCommandFullName\fR produces the fully qualified name +of a command from a command token. +The name, including all namespace prefixes, +is appended to the object specified by \fIobjPtr\fR. +.PP +\fBTcl_GetCommandFromObj\fR returns a token for the command +specified by the name in a \fBTcl_Obj\fR. +The command name is resolved relative to the current namespace. +Returns NULL if the command is not found. .SH "SEE ALSO" Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult |