diff options
Diffstat (limited to 'tcl8.6/doc/CrtCommand.3')
-rw-r--r-- | tcl8.6/doc/CrtCommand.3 | 143 |
1 files changed, 0 insertions, 143 deletions
diff --git a/tcl8.6/doc/CrtCommand.3 b/tcl8.6/doc/CrtCommand.3 deleted file mode 100644 index bf76d48..0000000 --- a/tcl8.6/doc/CrtCommand.3 +++ /dev/null @@ -1,143 +0,0 @@ -'\" -'\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures" -.so man.macros -.BS -.SH NAME -Tcl_CreateCommand \- implement new commands in C -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Command -\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR) -.SH ARGUMENTS -.AS Tcl_CmdDeleteProc *deleteProc -.AP Tcl_Interp *interp in -Interpreter in which to create new command. -.AP "const char" *cmdName in -Name of command. -.AP Tcl_CmdProc *proc in -Implementation of new command: \fIproc\fR will be called whenever -\fIcmdName\fR is invoked as a command. -.AP ClientData clientData in -Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR. -.AP Tcl_CmdDeleteProc *deleteProc in -Procedure to call before \fIcmdName\fR is deleted from the interpreter; -allows for command-specific cleanup. If NULL, then no procedure is -called before the command is deleted. -.BE -.SH DESCRIPTION -.PP -\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates -it with procedure \fIproc\fR such that whenever \fIcmdName\fR is -invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter -will call \fIproc\fR to process the command. -It differs from \fBTcl_CreateObjCommand\fR in that a new string-based -command is defined; -that is, a command procedure is defined that takes an array of -argument strings instead of values. -The value-based command procedures registered by \fBTcl_CreateObjCommand\fR -can execute significantly faster than the string-based command procedures -defined by \fBTcl_CreateCommand\fR. -This is because they take Tcl values as arguments -and those values can retain an internal representation that -can be manipulated more efficiently. -Also, Tcl's interpreter now uses values internally. -In order to invoke a string-based command procedure -registered by \fBTcl_CreateCommand\fR, -it must generate and fetch a string representation -from each argument value before the call. -New commands should be defined using \fBTcl_CreateObjCommand\fR. -We support \fBTcl_CreateCommand\fR for backwards compatibility. -.PP -The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR, -and \fBTcl_SetCommandInfo\fR are used in conjunction with -\fBTcl_CreateCommand\fR. -.PP -\fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR, -if one is already associated with the interpreter. -It returns a token that may be used to refer -to the command in subsequent calls to \fBTcl_GetCommandName\fR. -If \fIcmdName\fR contains any \fB::\fR namespace qualifiers, -then the command is added to the specified namespace; -otherwise the command is added to the global namespace. -If \fBTcl_CreateCommand\fR is called for an interpreter that is in -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_CmdProc\fR: -.PP -.CS -typedef int \fBTcl_CmdProc\fR( - ClientData \fIclientData\fR, - Tcl_Interp *\fIinterp\fR, - int \fIargc\fR, - const char *\fIargv\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_CreateCommand\fR. -Typically, \fIclientData\fR points to an application-specific -data structure that describes what to do when the command procedure -is invoked. \fIArgc\fR and \fIargv\fR describe the arguments to -the command, \fIargc\fR giving the number of arguments (including -the command name) and \fIargv\fR giving the values of the arguments -as strings. The \fIargv\fR array will contain \fIargc\fR+1 values; -the first \fIargc\fR values point to the argument strings, and the -last value is NULL. -Note that the argument strings should not be modified as they may -point to constant strings or may be shared with other parts of the -interpreter. -.PP -Note that the argument strings are encoded in normalized UTF-8 since -version 8.1 of Tcl. -.PP -\fIProc\fR must return an integer code that is expected to be one of -\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or -\fBTCL_CONTINUE\fR. See the Tcl overview man page -for details on what these codes mean. Most normal commands will only -return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set -the interpreter result; -in the case of a \fBTCL_OK\fR return code this gives the result -of the command, and in the case of \fBTCL_ERROR\fR it gives an error message. -The \fBTcl_SetResult\fR procedure provides an easy interface for setting -the return value; for complete details on how the interpreter result -field is managed, see the \fBTcl_Interp\fR man page. -Before invoking a command procedure, -\fBTcl_Eval\fR sets the interpreter result to point to an empty string, -so simple commands can return an empty result by doing nothing at all. -.PP -The contents of the \fIargv\fR array belong to Tcl and are not -guaranteed to persist once \fIproc\fR returns: \fIproc\fR should -not modify them, nor should it set the interpreter result to point -anywhere within the \fIargv\fR values. -Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want -to return something from the \fIargv\fR array. -.PP -\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted. This can -occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR, -or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR. -\fIDeleteProc\fR is invoked before the command is deleted, and gives the -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 \fBTcl_CmdDeleteProc\fR( - ClientData \fIclientData\fR); -.CE -.PP -The \fIclientData\fR argument will be the same as the \fIclientData\fR -argument passed to \fBTcl_CreateCommand\fR. -.SH "SEE ALSO" -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, -Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult -.SH KEYWORDS -bind, command, create, delete, interpreter, namespace |