About Us Documentation

Contact Site Map




Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateObjCommand(3Tcl Library Procedures 8.0



Tcl_CreateObjCommand,                     Tcl_DeleteCommand,
     Tcl_DeleteCommandFromToken,              Tcl_GetCommandInfo,
     Tcl_SetCommandInfo, Tcl_GetCommandName - implement new  com-
     mands in C


#include <tcl.h>

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

     Tcl_DeleteCommand(interp, cmdName)

     Tcl_DeleteCommandFromToken(interp, token)

     Tcl_GetCommandInfo(interp, cmdName, infoPtr)

     Tcl_SetCommandInfo(interp, cmdName, infoPtr)

     char *
     Tcl_GetCommandName(interp, token)


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-

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

     Tcl_CmdDeleteProc              *deleteProc(in)
                                              Procedure  to  call
                                              before  cmdName  is

Tcl                                                             1

Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateObjCommand(3Tcl Library Procedures 8.0

                                              deleted  from   the
                                              interpreter; allows
                                              for        command-
                                              specific   cleanup.
                                              If  NULL,  then  no
                                              procedure is called
                                              before the  command
                                              is deleted.

     Tcl_Command      token         (in)      Token for  command,
                                              returned  by previ-
                                              ous     call     to
                                              The  command   must
                                              not    have    been

     Tcl_CmdInfo      *infoPtr      (in/out)  Pointer  to  struc-
                                              ture     containing
                                              various information
                                              about  a  Tcl  com-


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_EvalObj)
     the Tcl interpreter will call proc to process the command.

     Tcl_CreateObjCommand will delete any  command  name  already
     associated  with  the  interpreter.  It returns a token that
     may be used to refer to the command in subsequent  calls  to
     Tcl_GetCommandName.  If name contains any :: namespace qual-
     ifiers,  then  the  command  is  added  to   the   specified
     namespace;  otherwise  the  command  is  added to the global
     namespace.  If Tcl_CreateObjCommand is called for an  inter-
     preter 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
          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 describes what to  |
     do when the command procedure  is  invoked.  Objc  and  objv  |
     describe  the  arguments  to  the  command,  objc giving the  |

Tcl                                                             2

Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateObjCommand(3Tcl Library Procedures 8.0

     number of argument objects (including 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_GetIntFromObject   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 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_EvalObj  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.

     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.

     DeleteProc will be invoked when (if) name is deleted.   This
     can    occur    through   a   call   to   Tcl_DeleteCommand,
     Tcl_DeleteCommandFromToken,  or  Tcl_DeleteInterp,   or   by
     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_CmdDeleteProc:
          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 cmdName

Tcl                                                             3

Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateObjCommand(3Tcl Library Procedures 8.0

     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  restric-
     tions  on  cmdName:   it may refer to a built-in command, an
     application-specific command, or a Tcl procedure.   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 nothing 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  particular
     namespace.   If the command is not found, then it returns 0.
     Otherwise it places information about  the  command  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_CreateObjCommand  was called to register the command; it
     is 0 if only Tcl_CreateCommand was called.  It allows a pro-
     gram  to  determine  whether it is faster to call objProc or
     proc: objProc is normally faster if  isNativeObjectProc  has
     the  value 1.  The fields objProc and objClientData have the
     same  meaning  as  the  proc  and  clientData  arguments  to
     Tcl_CreateObjCommand;   they   hold  information  about  the
     object-based command  procedure  that  the  Tcl  interpreter
     calls to implement the command.  The fields proc and client-
     Data hold information about the  string-based  command  pro-
     cedure  that  implements  the command.  If Tcl_CreateCommand
     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 normally the same as

Tcl                                                             4

Prepared by Ready-to-Run Software, Inc. 

Tcl_CreateObjCommand(3Tcl Library Procedures 8.0

     clientData  but  may  be   set   independently   using   the
     Tcl_SetCommandInfo  procedure.  The field namespacePtr 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_RenameCommand to do

     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


Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult


bind, command, create, delete, namespace, object

Tcl                                                             5

Prepared by Ready-to-Run Software, Inc. 

To return to the Ready-to-Run Software Super ReadyPak Table of contents please presshere


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002