182 lines
7.4 KiB
Groff
182 lines
7.4 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) CrtCommand.3 1.22 96/03/25 19:58:44
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
.VS
|
|
.VE
|
|
Tcl_Command
|
|
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
|
|
.sp
|
|
.VS
|
|
int
|
|
\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
|
.sp
|
|
.VS
|
|
char *
|
|
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
|
|
.VE
|
|
.VE
|
|
.SH ARGUMENTS
|
|
.AS Tcl_CmdDeleteProc **deleteProcPtr
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter in which to create new command.
|
|
.AP 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.
|
|
.AP Tcl_CmdInfo *infoPtr in/out
|
|
.VS
|
|
Pointer to structure containing various information about a
|
|
Tcl command.
|
|
.AP Tcl_Command token in
|
|
Token for command, returned by previous call to \fBTcl_CreateCommand\fR.
|
|
The command must not have been deleted.
|
|
.VE
|
|
.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. If there is already a command \fIcmdName\fR
|
|
associated with the interpreter, it is deleted.
|
|
.VS
|
|
\fBTcl_CreateCommand\fR returns a token that may be used to refer
|
|
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
|
|
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.
|
|
.VE
|
|
\fIProc\fR should have arguments and result that match the type
|
|
\fBTcl_CmdProc\fR:
|
|
.CS
|
|
typedef int Tcl_CmdProc(
|
|
ClientData \fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
int \fIargc\fR,
|
|
char *\fIargv\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 \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.
|
|
.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. 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
|
|
\fIinterp->result\fR to point to a string value;
|
|
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 \fIinterp->result\fR
|
|
field is managed, see the \fBTcl_Interp\fR man page.
|
|
Before invoking a command procedure,
|
|
\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
|
|
commands can return an empty result by doing nothing at all.
|
|
.PP
|
|
.VS
|
|
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 \fIinterp->result\fR 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.
|
|
.VE
|
|
.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:
|
|
.CS
|
|
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
|
|
.CE
|
|
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
|
argument passed to \fBTcl_CreateCommand\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
|
|
\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
|
|
it returns 0.
|
|
There are no restrictions on \fIcmdName\fR: it may refer to
|
|
a built-in command, an application-specific command, or a Tcl procedure.
|
|
.PP
|
|
.VS
|
|
\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
|
|
exists as a command in \fIinterp\fR. If not then it returns 0.
|
|
Otherwise it places information about the command in the structure
|
|
pointed to by \fIinfoPtr\fR and returns 1.
|
|
Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
|
|
and \fIdeleteProc\fR, which have the same meaning as the corresponding
|
|
arguments to \fBTcl_CreateCommand\fR.
|
|
There is also a field \fIdeleteData\fR, which is the ClientData value
|
|
to pass to \fIdeleteProc\fR; it is normally the same as
|
|
\fIclientData\fR but may be set independently using the
|
|
\fBTcl_SetCommandInfo\fR procedure.
|
|
.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.
|
|
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.
|
|
.PP
|
|
\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
|
|
that have been renamed. Given a token returned by \fBTcl_CreateCommand\fR
|
|
when the command was created, \fBTcl_GetCommandName\fR returns the
|
|
string name of the command. If the command has been renamed since it
|
|
was created, then \fBTcl_GetCommandName\fR returns the current name.
|
|
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
|
|
they need to keep it for a long time.
|
|
.VE
|
|
|
|
.SH KEYWORDS
|
|
bind, command, create, delete, interpreter
|