Subversion Repositories or1k

'\"

'\" Copyright (c) 1996-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.

'\"

'\" RCS: @(#) $Id: CrtObjCmd.3,v 1.1.1.1 2002-01-16 10:25:23 markom Exp $

'\"

.so man.macros

.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"

.BS

.SH NAME

Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C

.SH SYNOPSIS

.nf

\fB#include \fR

.sp

Tcl_Command

\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)

.sp

int

\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)

.sp

int

\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)

.sp

int

\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)

.sp

int

\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)

.sp

char *

\fBTcl_GetCommandName\fR(\fIinterp, token\fR)

.SH ARGUMENTS

.AS Tcl_ObjCmdProc *deleteProc in/out

.AP Tcl_Interp *interp in

Interpreter in which to create a new command or that contains a command.

.AP char *cmdName in

Name of command.

.AP Tcl_ObjCmdProc *proc in

Implementation of the 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_Command token in

Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.

The command must not have been deleted.

.AP Tcl_CmdInfo *infoPtr in/out

Pointer to structure containing various information about a

Tcl command.

.BE

.SH DESCRIPTION

.PP

\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR

and associates it with procedure \fIproc\fR

such that whenever \fIname\fR is

invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)

the Tcl interpreter will call \fIproc\fR to process the command.

.PP

\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR

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 \fIname\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_CreateObjCommand\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_ObjCmdProc\fR:

.CS

typedef int Tcl_ObjCmdProc(

        ClientData \fIclientData\fR,

        Tcl_Interp *\fIinterp\fR,

        int \fIobjc\fR,

.VS

        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

\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

(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

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

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

\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer

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.

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, if \fIproc\fR needs to return a non-empty result,

it can call \fBTcl_SetObjResult\fR to set the interpreter's 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 this gives an error message.

Before invoking a command procedure,

\fBTcl_EvalObj\fR sets interpreter's result to

point to an object 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

guaranteed to persist once \fIproc\fR returns: \fIproc\fR should

not modify them.

Call \fBTcl_SetObjResult\fR if you want

to return something from the \fIobjv\fR array.

.PP

\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.

This can occur through a call to \fBTcl_DeleteCommand\fR,

\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,

or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\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_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

\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.

If \fIname\fR contains any \fB::\fR namespace qualifiers,

the command is deleted from the specified namespace.

.PP

Given a token returned by \fBTcl_CreateObjCommand\fR,

\fBTcl_DeleteCommandFromToken\fR deletes the command

from a command interpreter.

It will delete a command even if that command has been renamed.

Once the call completes, attempts to invoke the command in

\fIinterp\fR will result in errors.

If the command corresponding to \fItoken\fR

has already been deleted from \fIinterp\fR then

\fBTcl_DeleteCommand\fR does nothing and returns -1;

otherwise it returns 0.

.PP

\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument

exists as a command in \fIinterp\fR.

\fIcmdName\fR may include \fB::\fR namespace qualifiers

to identify a command in a particular namespace.

If the command is not found, then it returns 0.

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:

.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;

} Tcl_CmdInfo;

.CE

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.

It allows a program to determine whether it is faster to

call \fIobjProc\fR or \fIproc\fR:

\fIobjProc\fR is normally faster

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

that the Tcl interpreter calls to implement the command.

The fields \fIproc\fR and \fIclientData\fR

hold information about the string-based command procedure

that implements the command.

If \fBTcl_CreateCommand\fR was called for this command,

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.

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

\fBTcl_SetCommandInfo\fR procedure.

The field \fInamespacePtr\fR holds a pointer to the

Tcl_Namespace that contains the command.

.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.

\fIcmdName\fR may include \fB::\fR namespace qualifiers

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_GetCommandName\fR provides a mechanism for tracking commands

that have been renamed.

Given a token returned by \fBTcl_CreateObjCommand\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.

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

they need to keep it for a long time.

.PP

.SH "SEE ALSO"

Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult

.SH KEYWORDS

bind, command, create, delete, namespace, object