diff options
Diffstat (limited to 'doc/CrtObjCmd.3')
| -rw-r--r-- | doc/CrtObjCmd.3 | 53 |
1 files changed, 25 insertions, 28 deletions
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 18e417c..e94c8cd 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -4,10 +4,8 @@ '\" 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.11 2004/10/07 15:15:36 dkf 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_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C @@ -30,17 +28,13 @@ int int \fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR) .sp -.VS 8.4 int \fBTcl_GetCommandInfoFromToken\fR(\fItoken, infoPtr\fR) .sp int \fBTcl_SetCommandInfoFromToken\fR(\fItoken, infoPtr\fR) -.VE .sp -.VS 8.4 const char * -.VE \fBTcl_GetCommandName\fR(\fIinterp, token\fR) .sp void @@ -70,7 +64,7 @@ The command must not have been deleted. Pointer to structure containing various information about a Tcl command. .AP Tcl_Obj *objPtr in -Object containing the name of a Tcl command. +Value containing the name of a Tcl command. .BE .SH DESCRIPTION .PP @@ -94,38 +88,38 @@ the process of being deleted, then it does not create a new command and it returns NULL. \fIproc\fR should have arguments and result that match the type \fBTcl_ObjCmdProc\fR: +.PP .CS -typedef int Tcl_ObjCmdProc( +typedef int \fBTcl_ObjCmdProc\fR( ClientData \fIclientData\fR, Tcl_Interp *\fIinterp\fR, int \fIobjc\fR, -.VS Tcl_Obj *const \fIobjv\fR[]); .CE +.PP 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 \fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an application-specific data structure that describes what to do when the command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the -arguments to the command, \fIobjc\fR giving the number of argument objects +arguments to the command, \fIobjc\fR giving the number of argument values (including the command name) and \fIobjv\fR giving the values of the arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to -the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a +the argument values. Unlike \fIargv\fR[\fIargv\fR] used in a string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL. .PP 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 +value argument. For instance, the user may call \fBTcl_GetIntFromObj\fR on \fIobjv\fR[\fB2\fR] to obtain the integer -representation of that object; that call may change the type of the object +representation of that value; that call may change the type of the value 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. @@ -139,7 +133,7 @@ of the command, and in the case of \fBTCL_ERROR\fR this gives an error message. Before invoking a command procedure, \fBTcl_EvalObjEx\fR sets interpreter's result to -point to an object representing an empty string, so simple +point to a value representing an empty string, so simple commands can return an empty result by doing nothing at all. .PP The contents of the \fIobjv\fR array belong to Tcl and are not @@ -167,17 +161,19 @@ or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR. 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: +.PP .CS -typedef void Tcl_CmdDeleteProc( +typedef void \fBTcl_CmdDeleteProc\fR( ClientData \fIclientData\fR); .CE +.PP The \fIclientData\fR argument will be the same as the \fIclientData\fR argument passed to \fBTcl_CreateObjCommand\fR. .PP \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 @@ -205,6 +201,7 @@ Otherwise it places information about the command in the \fBTcl_CmdInfo\fR structure pointed to by \fIinfoPtr\fR and returns 1. A \fBTcl_CmdInfo\fR structure has the following fields: +.PP .CS typedef struct Tcl_CmdInfo { int \fIisNativeObjectProc\fR; @@ -215,8 +212,9 @@ typedef struct Tcl_CmdInfo { Tcl_CmdDeleteProc *\fIdeleteProc\fR; ClientData \fIdeleteData\fR; Tcl_Namespace *\fInamespacePtr\fR; -} Tcl_CmdInfo; +} \fBTcl_CmdInfo\fR; .CE +.PP The \fIisNativeObjectProc\fR field has the value 1 if \fBTcl_CreateObjCommand\fR was called to register the command; it is 0 if only \fBTcl_CreateCommand\fR was called. @@ -227,7 +225,7 @@ if \fIisNativeObjectProc\fR has the value 1. The fields \fIobjProc\fR and \fIobjClientData\fR have the same meaning as the \fIproc\fR and \fIclientData\fR arguments to \fBTcl_CreateObjCommand\fR; -they hold information about the object-based command procedure +they hold information about the value-based command procedure that the Tcl interpreter calls to implement the command. The fields \fIproc\fR and \fIclientData\fR hold information about the string-based command procedure @@ -237,7 +235,7 @@ this is the procedure passed to it; otherwise, this is a compatibility procedure registered by \fBTcl_CreateObjCommand\fR that simply calls the command's -object-based procedure after converting its string arguments to Tcl objects. +value-based procedure after converting its string arguments to Tcl values. The field \fIdeleteData\fR is the ClientData value to pass to \fIdeleteProc\fR; it is normally the same as \fIclientData\fR but may be set independently using the @@ -286,20 +284,19 @@ 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\fP. +is appended to the value specified by \fIobjPtr\fR. .PP \fBTcl_GetCommandFromObj\fR returns a token for the command -specified by the name in a \fBTcl_Obj\fP. +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 - +Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3) .SH KEYWORDS -bind, command, create, delete, namespace, object +bind, command, create, delete, namespace, value |