ABCDEFGHIJKLMNOPQRSTUVWXYZ

CrtObjCmd

Tcl_CreateObjCommand(3)     Tcl Library Procedures     Tcl_CreateObjCommand(3)



______________________________________________________________________________

NAME
       Tcl_CreateObjCommand,   Tcl_DeleteCommand,  Tcl_DeleteCommandFromToken,
       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 com-
                                                mand:  proc  will  be   called
                                                whenever cmdName is invoked as
                                                a command.

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

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

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

       Tcl_CmdInfo      *infoPtr      (in/out)  Pointer to structure  contain-
                                                ing  various information 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_EvalObjEx) the Tcl interpreter will call  proc
       to process the command.

       Tcl_CreateObjCommand  deletes any existing command name already associ-
       ated 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 command is added to
       the specified namespace; otherwise the command is added to  the  global
       namespace.   If  Tcl_CreateObjCommand is called for an interpreter that
       is in the process of being deleted, then it does not create a new  com-
       mand  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_CreateObj- |
       Command.  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 giv- |
       ing  the  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 decla- |
       ration  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 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_SetO-
       bjResult if you want to return something from the objv array.

       Ordinarily, Tcl_CreateObjCommand  deletes  any  existing  command  name
       already associated with the interpreter.  However, if the existing com-
       mand was created by a previous call to Tcl_CreateCommand, Tcl_CreateOb-
       jCommand  does  not delete the command but instead arranges for the Tcl
       interpreter 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 compatibility.

       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_CreateOb-
       jCommand.  DeleteProc is invoked before the  command  is  deleted,  and
       gives  the application an opportunity to release any structures associ-
       ated 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  interpreter.   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.  If name
       contains any :: namespace qualifiers, the command is deleted  from  the
       specified namespace.

       Given  a token returned by Tcl_CreateObjCommand, Tcl_DeleteCommandFrom-
       Token deletes the command from a command interpreter.  It will delete a
       command  even  if  that  command  has been renamed.  Once the call com-
       pletes, 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 argument 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 program 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
       clientData hold information about the  string-based  command  procedure
       that  implements the command.  If Tcl_CreateCommand was called for this
       command, this is the procedure passed to it; otherwise, this is a  com-
       patibility  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 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 val-
       ues 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
       that.

       Tcl_GetCommandName provides a mechanism for tracking commands 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_GetCom-
       mandName 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



Tcl                                   8.0              Tcl_CreateObjCommand(3)