tcl7.6 C API - CrtCommand






NAME

     Tcl_CreateCommand,  Tcl_DeleteCommand,   Tcl_GetCommandInfo,
     Tcl_SetCommandInfo - implement new commands in C


SYNOPSIS

     #include <tcl.h>

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

     int
     Tcl_DeleteCommand(interp, cmdName)

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

     char                *cmdName          (in)      Name of com-
                                                     mand.

     Tcl_CmdProc         *proc             (in)      Implementation
                                                     of  new com-
                                                     mand:   proc
                                                     will      be
                                                     called when-
                                                     ever 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
                                                     deleted from
                                                     the   inter-
                                                     preter;
                                                     allows   for
                                                     command-
                                                     specific
                                                     cleanup.  If
                                                     NULL,   then
                                                     no procedure
                                                     is    called
                                                     before   the
                                                     command   is
                                                     deleted.

     Tcl_CmdInfo         *infoPtr          (in/out)  Pointer   to
                                                     structure
                                                     containing
                                                     various
                                                     information
                                                     about  a Tcl
                                                     command.

     Tcl_Command         token             (in)      Token    for
                                                     command,
                                                     returned  by
                                                     previous
                                                     call      to
                                                     Tcl_CreateCommand.
                                                     The  command
                                                     must     not
                                                     have    been
                                                     deleted.





DESCRIPTION

     Tcl_CreateCommand defines a new command in interp and  asso-
     ciates  it with procedure proc such that whenever cmdName is
     invoked as a Tcl command (via a call to  Tcl_Eval)  the  Tcl
     interpreter will call proc to process the command.  If there
     is already a command  cmdName  associated  with  the  inter-
     preter,  it  is  deleted.  Tcl_CreateCommand returns a token
     that may be used to refer to the command in subsequent calls
     to  Tcl_GetCommandName.   If Tcl_CreateCommand 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_CmdProc:
          typedef int Tcl_CmdProc(
            ClientData clientData,
            Tcl_Interp *interp,
            int argc,
            char *argv[]);
     When proc is invoked the clientData  and  interp  parameters
     will  be copies of the clientData and interp arguments given
     to Tcl_CreateCommand.  Typically, clientData  points  to  an
     application-specific  data  structure that describes what to
     do when the command procedure is  invoked.   Argc  and  argv
     describe  the  arguments  to  the  command,  argc giving the
     number of arguments (including the command  name)  and  argv
     giving  the  values  of  the arguments as strings.  The argv
     array will contain argc+1  values;  the  first  argc  values
     point to the argument strings, and the last value is NULL.

     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, proc must set  interp->result  to  point  to  a
     string value; in the case of a TCL_OK return code this gives
     the result of the command, and in the case of  TCL_ERROR  it
     gives  an  error  message.  The Tcl_SetResult procedure pro-
     vides an easy interface for setting the return  value;   for
     complete details on how the interp->result field is managed,
     see the Tcl_Interp man page.  Before invoking a command pro-
     cedure,  Tcl_Eval  sets  interp->result to point to an empty
     string, so simple commands can return  an  empty  result  by
     doing nothing at all.

     The contents of the argv array belong to  Tcl  and  are  not
     guaranteed  to  persist  once proc returns:  proc should not
     modify them, nor should it set interp->result to point  any-
     where  within  the  argv  values.   Call  Tcl_SetResult with
     status TCL_VOLATILE if you want to return something from the
     argv array.

     DeleteProc will be invoked when  (if)  cmdName  is  deleted.
     This  can  occur  through  a  call  to  Tcl_DeleteCommand or
     Tcl_DeleteInterp, or by replacing cmdName in another call to
     Tcl_CreateCommand.  DeleteProc is invoked before the command
     is deleted, and gives  the  application  an  opportunity  to
     release   any   structures   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_CreateCommand.

     Tcl_DeleteCommand deletes a command from  a  command  inter-
     preter.  Once the call completes, attempts to invoke cmdName
     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 com-
     mand, an application-specific command, or a Tcl procedure.

     Tcl_GetCommandInfo checks to see whether its  cmdName  argu-
     ment  exists as a command in interp.  If not then it returns
     0.  Otherwise it places information about the command in the
     structure  pointed to by infoPtr and returns 1.  Tcl_CmdInfo
     structures  have  fields   named   proc,   clientData,   and
     deleteProc, which have the same meaning as the corresponding
     arguments to  Tcl_CreateCommand.   There  is  also  a  field
     deleteData,  which  is  the  ClientData  value  to  pass  to
     deleteProc;  it is normally the same as clientData  but  may
     be set independently using the Tcl_SetCommandInfo procedure.

     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.  If  this  com-
     mand does not exist then Tcl_SetCommandInfo returns 0.  Oth-
     erwise, 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  dele-
     tion  procedure  to  be  given  a  different  value than the
     ClientData for its command procedure.

     Tcl_GetCommandName provides a mechanism  for  tracking  com-
     mands  that  have  been  renamed.  Given a token returned by
     Tcl_CreateCommand   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.  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.



KEYWORDS

     bind, command, create, delete, interpreter