NAME

       Tcl_CreateObjCommand,   Tcl_DeleteCommand,  Tcl_DeleteCom­
       mandFromToken,   Tcl_GetCommandInfo,   Tcl_SetCommandInfo,
       Tcl_GetCommandName - implement new commands in C


SYNOPSIS

       #include <tcl.h>

       Tcl_Command
       Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)

       int
       Tcl_DeleteCommand(interp, cmdName)

       int
       Tcl_DeleteCommandFromToken(interp, token)

       int
       Tcl_GetCommandInfo(interp, cmdName, infoPtr)

       int
       Tcl_SetCommandInfo(interp, cmdName, infoPtr)

       char *
       Tcl_GetCommandName(interp, token)


ARGUMENTS

       Tcl_Interp       *interp       (in)      Interpreter    in
                                                which to create a
                                                new   command  or
                                                that  contains  a
                                                command.

       char             *cmdName      (in)      Name  of command.

       Tcl_ObjCmdProc   *proc         (in)      Implementation of
                                                the  new command:
                                                proc   will    be
                                                called   whenever
                                                cmdName        is
                                                invoked as a com­
                                                mand.

       ClientData       clientData    (in)      Arbitrary    one-
                                                word   value   to
                                                pass to proc  and
                                                deleteProc.

       Tcl_CmdDeleteProc              *deleteProc(in)
                                                Procedure to call
                                                before cmdName is
                                                allows  for  com­
                                                mand-specific
                                                cleanup. If NULL,
                                                then no procedure
                                                is  called before
                                                the  command   is
                                                deleted.

       Tcl_Command      token         (in)      Token   for  com­
                                                mand, returned by
                                                previous  call to
                                                Tcl_CreateObjCom­
                                                mand.   The  com­
                                                mand   must   not
                                                have         been
                                                deleted.

       Tcl_CmdInfo      *infoPtr      (in/out)  Pointer to struc­
                                                ture   containing
                                                various  informa­
                                                tion  about a Tcl
                                                command.
_________________________________________________________________


DESCRIPTION

       Tcl_CreateObjCommand defines a new command in  interp  and
       associates  it with procedure proc such that whenever name
       is invoked as a Tcl command (e.g., via a call to Tcl_Eval­
       ObjEx)  the  Tcl interpreter will call proc to process the
       command.

       Tcl_CreateObjCommand deletes  any  existing  command  name
       already associated with the interpreter (however see below
       for  an  exception  where  the  existing  command  is  not
       deleted).  It returns a token that may be used to refer to
       the command in subsequent calls to Tcl_GetCommandName.  If
       name  contains  any :: namespace qualifiers, then the com­
       mand is added to the specified  namespace;  otherwise  the
       command  is  added  to  the global namespace.  If Tcl_Cre­
       ateObjCommand 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.  proc should  have  arguments
       and result that match the type Tcl_ObjCmdProc:
              typedef int Tcl_ObjCmdProc(
                ClientData clientData,
                Tcl_Interp *interp,
                int objc,
                Tcl_Obj *CONST objv[]);                           |
       When proc is invoked, the clientData and interp parameters |
       will be copies of  the  clientData  and  interp  arguments |
       given   to  Tcl_CreateObjCommand.   Typically,  clientData |
       points to  an  application-specific  data  structure  that |
       mand,  objc giving the number of argument objects (includ­ |
       ing the command name) and objv giving the  values  of  the |
       arguments.   The  objv  array  will  contain  objc values, |
       pointing to the argument objects.  Unlike argv[argv]  used |
       in  a  string-based command procedure, objv[objc] will not |
       contain NULL.                                              |

       Additionally, when proc is invoked, it must not modify the |
       contents of the objv array by assigning new pointer values |
       to any element of the array (for example, objv[2] =  NULL) |
       because  this will cause memory to be lost and the runtime |
       stack to be corrupted.  The CONST in  the  declaration  of |
       objv  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  Tcl_GetIntFromObj  on  objv[2] to obtain the integer |
       representation of that object; that call  may  change  the |
       type  of  the  object that objv[2] points at, but will not |
       change where objv[2] points.

       proc must return an integer code that  is  either  TCL_OK,
       TCL_ERROR,  TCL_RETURN,  TCL_BREAK,  or TCL_CONTINUE.  See
       the Tcl overview man page for details on what these  codes
       mean.   Most  normal  commands  will only return TCL_OK or
       TCL_ERROR.  In addition, if proc needs to  return  a  non-
       empty  result,  it  can  call  Tcl_SetObjResult to set the
       interpreter's result.  In the case of a TCL_OK return code
       this  gives  the result of the command, and in the case of
       TCL_ERROR this gives an error message.  Before invoking  a
       command procedure, Tcl_EvalObjEx sets interpreter's result
       to point to an object representing  an  empty  string,  so
       simple  commands can return an empty result by doing noth­
       ing at all.

       The contents of the objv array belong to Tcl and  are  not
       guaranteed  to  persist once proc returns: proc should not
       modify them.  Call Tcl_SetObjResult if you want to  return
       something from the objv array.

       Ordinarily, Tcl_CreateObjCommand deletes any existing com­
       mand name already associated with the  interpreter.   How­
       ever,  if  the  existing command was created by a previous
       call to Tcl_CreateCommand, Tcl_CreateObjCommand  does  not
       delete the command but instead arranges for the Tcl inter­
       preter to call the Tcl_ObjCmdProc proc in the future.  The
       old  string-based  Tcl_CmdProc associated with the command
       is retained and its address can be obtained by  subsequent
       Tcl_GetCommandInfo  calls. This is done for backwards com­
       patibility.

       DeleteProc will be invoked  when  (if)  name  is  deleted.
       replacing  name  in  another call to Tcl_CreateObjCommand.
       DeleteProc is invoked before the command is  deleted,  and
       gives the application an opportunity to release any struc­
       tures associated with the command.  DeleteProc should have
       arguments   and   result  that  match  the  type  Tcl_Cmd­
       DeleteProc:
              typedef void Tcl_CmdDeleteProc(ClientData clientData);
       The clientData argument will be the same as the clientData
       argument passed to Tcl_CreateObjCommand.

       Tcl_DeleteCommand  deletes a command from a command inter­
       preter.  Once the call completes, attempts to invoke  cmd­
       Name  in  interp  will result in errors.  If cmdName isn't
       bound as a command in interp then  Tcl_DeleteCommand  does
       nothing  and  returns  -1;  otherwise it returns 0.  There
       are no restrictions on cmdName:  it may refer to a  built-
       in command, an application-specific command, or a Tcl pro­
       cedure.  If name contains any :: namespace qualifiers, the
       command is deleted from the specified namespace.

       Given    a   token   returned   by   Tcl_CreateObjCommand,
       Tcl_DeleteCommandFromToken deletes the command from a com­
       mand  interpreter.   It will delete a command even if that
       command  has  been  renamed.   Once  the  call  completes,
       attempts  to  invoke  the command in interp will result in
       errors.  If the command corresponding to token has already
       been deleted from interp then Tcl_DeleteCommand does noth­
       ing and returns -1; otherwise it returns 0.

       Tcl_GetCommandInfo checks to see whether its cmdName argu­
       ment  exists  as a command in interp.  cmdName may include
       :: namespace qualifiers to identify a command in a partic­
       ular  namespace.   If  the  command  is not found, then it
       returns 0.  Otherwise it places information about the com­
       mand  in  the  Tcl_CmdInfo structure pointed to by infoPtr
       and returns 1.  A Tcl_CmdInfo structure has the  following
       fields:
              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;
       The  isNativeObjectProc  field has the value 1 if Tcl_Cre­
       ateObjCommand was called to register the command; it is  0
       if only Tcl_CreateCommand was called.  It allows a program
       to determine whether it is faster to call objProc or proc:
       objProc  is  normally faster if isNativeObjectProc has the
       Tcl_CreateObjCommand;  they  hold  information  about  the
       object-based  command  procedure  that the Tcl interpreter
       calls to implement  the  command.   The  fields  proc  and
       clientData hold information about the string-based command
       procedure that implements the command.  If  Tcl_CreateCom­
       mand  was  called  for this command, this is the procedure
       passed to it; otherwise, this is a compatibility procedure
       registered  by  Tcl_CreateObjCommand that simply calls the
       command's  object-based  procedure  after  converting  its
       string  arguments to Tcl objects.  The field deleteData is
       the ClientData value to pass to deleteProc;   it  is  nor­
       mally  the same as clientData but may be set independently
       using the Tcl_SetCommandInfo procedure.  The field  names­
       pacePtr holds a pointer to the Tcl_Namespace that contains
       the command.

       Tcl_SetCommandInfo is used to modify  the  procedures  and
       ClientData  values associated with a command.  Its cmdName
       argument is the name of a command in interp.  cmdName  may
       include :: namespace qualifiers to identify a command in a
       particular namespace.  If this command does not exist then
       Tcl_SetCommandInfo  returns  0.   Otherwise, it copies the
       information from *infoPtr 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  Tcl_SetCmdInfo  will  not
       change  a command's namespace; you must use Tcl_RenameCom­
       mand to do that.

       Tcl_GetCommandName provides a mechanism for tracking  com­
       mands  that  have been renamed.  Given a token returned by
       Tcl_CreateObjCommand  when  the   command   was   created,
       Tcl_GetCommandName returns the string name of the command.
       If the command has been renamed since it was created, then
       Tcl_GetCommandName  returns  the  current name.  This name
       does not include any :: namespace qualifiers.  The command
       corresponding  to  token  must not have been deleted.  The
       string returned by Tcl_GetCommandName 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.



SEE ALSO

       Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult



KEYWORDS

       bind, command, create, delete, namespace, object