Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all bug

NAME

       Tcl_CreateObjCommand,  Tcl_DeleteCommand,  Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo,
       Tcl_GetCommandInfoFromToken,       Tcl_SetCommandInfo,        Tcl_SetCommandInfoFromToken,
       Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj - 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)

       int
       Tcl_GetCommandInfoFromToken(token, infoPtr)

       int
       Tcl_SetCommandInfoFromToken(token, infoPtr)

       const char *
       Tcl_GetCommandName(interp, token)

       void
       Tcl_GetCommandFullName(interp, token, objPtr)

       Tcl_Command
       Tcl_GetCommandFromObj(interp, objPtr)

ARGUMENTS

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

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

       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  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 previous call
                                                   to Tcl_CreateObjCommand.  The command must not
                                                   have been deleted.

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

       Tcl_Obj *objPtr (in)                        Value containing the name of 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  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 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 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  describes what to do when the
       command procedure is invoked. Objc and objv describe the arguments to  the  command,  objc
       giving  the  number  of  argument  values (including the command name) and objv giving the
       values of the arguments.  The objv  array  will  contain  objc  values,  pointing  to  the
       argument  values.   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  value  argument.   For  instance,  the  user may call
       Tcl_GetIntFromObj on objv[2] to obtain the integer representation of that value; that call
       may change the type of the value 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 a value 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.

       Ordinarily, Tcl_CreateObjCommand deletes any existing command name already associated with
       the interpreter.  However, 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 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_CreateObjCommand.  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_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 is not 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 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 command 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 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 value-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 compatibility
       procedure registered by Tcl_CreateObjCommand that simply calls the  command's  value-based
       procedure  after  converting  its string arguments to Tcl values.  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_GetCommandInfoFromToken is identical to  Tcl_GetCommandInfo  except  that  it  uses  a
       command  token  returned  from  Tcl_CreateObjCommand in place of the command name.  If the
       token parameter is NULL, it returns 0; otherwise, it returns 1 and fills in the  structure
       designated by infoPtr.

       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.

       Tcl_SetCommandInfoFromToken  is  identical  to  Tcl_SetCommandInfo  except that it takes a
       command token as returned by Tcl_CreateObjCommand instead of the  command  name.   If  the
       token parameter is NULL, it returns 0.  Otherwise, it copies the information from *infoPtr
       to Tcl's internal structure for the command and returns 1.

       Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken both allow the ClientData for
       a  command's  deletion procedure to be given a different value than the ClientData for its
       command procedure.

       Note  that  neither  Tcl_SetCommandInfo  nor  Tcl_SetCommandInfoFromToken  will  change  a
       command's namespace.  Use Tcl_Eval to call the rename command 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_GetCommandName is in dynamic  memory  owned
       by Tcl and is only guaranteed to retain its value as long as the command is not deleted or
       renamed;  callers should copy the string if they need to keep it for a long time.

       Tcl_GetCommandFullName produces the fully qualified name  of  a  command  from  a  command
       token.   The name, including all namespace prefixes, is appended to the value specified by
       objPtr.

       Tcl_GetCommandFromObj returns a token for the command specified by the name in a  Tcl_Obj.
       The  command  name  is  resolved  relative  to the current namespace.  Returns NULL if the
       command is not found.

SEE ALSO

       Tcl_CreateCommand(3tcl), Tcl_ResetResult(3tcl), Tcl_SetObjResult(3tcl)

KEYWORDS

       bind, command, create, delete, namespace, value