DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_CreateCommand(3)




Tcl_CreateCommand(3) Tcl Library Procedures  Tcl_CreateCommand(3)

_________________________________________________________________


NAME

     Tcl_CreateCommand - implement new commands in C


SYNOPSIS

     #include <tcl.h>

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


ARGUMENTS

     Tcl_Interp *interp (in)                     Interpreter   in
                                                 which  to create
                                                 new command.

     const char *cmdName (in)                    Name of command.

     Tcl_CmdProc *proc (in)                      Implementation
                                                 of  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.
_________________________________________________________________


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.  It

Tcl                       Last change:                          1

Tcl_CreateCommand(3) Tcl Library Procedures  Tcl_CreateCommand(3)

     differs from Tcl_CreateObjCommand in that a new string-based
     command  is defined; that is, a command procedure is defined
     that takes an array of argument strings instead of  objects.
     The    object-based   command   procedures   registered   by
     Tcl_CreateObjCommand can execute significantly  faster  than
     the    string-based    command    procedures    defined   by
     Tcl_CreateCommand.  This is because they take Tcl objects as
     arguments and those objects can retain an internal represen-
     tation that can  be  manipulated  more  efficiently.   Also,
     Tcl's  interpreter now uses objects internally.  In order to
     invoke  a  string-based  command  procedure  registered   by
     Tcl_CreateCommand,  it  must  generate  and  fetch  a string
     representation from each argument object before the call and
     create  a  new Tcl object to hold the string result returned
     by the string-based command procedure.  New commands  should
     be   defined   using   Tcl_CreateObjCommand.    We   support
     Tcl_CreateCommand for backwards compatibility.

     The procedures  Tcl_DeleteCommand,  Tcl_GetCommandInfo,  and
     Tcl_SetCommandInfo    are    used    in   conjunction   with
     Tcl_CreateCommand.

     Tcl_CreateCommand will delete an existing  command  cmdName,
     if  one  is  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 cmdName contains
     any :: namespace qualifiers, then the command  is  added  to
     the  specified  namespace; otherwise the command is added to
     the global namespace.  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,
                  const 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.
     Note that the argument strings should  not  be  modified  as
     they  may  point  to  constant strings or may be shared with
     other parts of the interpreter.

Tcl                       Last change:                          2

Tcl_CreateCommand(3) Tcl Library Procedures  Tcl_CreateCommand(3)

     Note that the argument strings  are  encoded  in  normalized
     UTF-8 since version 8.1 of Tcl.

     Proc must return an integer code that is expected to be  one
     of    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  the
     interpreter  result  to point to a string value; in the case
     of a TCL_OK return code this gives the result  of  the  com-
     mand,  and  in  the case of TCL_ERROR it gives an error mes-
     sage.  The Tcl_SetResult procedure provides an  easy  inter-
     face  for setting the return value;  for complete details on
     how  the  interpreter  result  field  is  managed,  see  the
     Tcl_Interp  man  page.  Before invoking a command procedure,
     Tcl_Eval sets the interpreter 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  the  interpreter  result  to
     point  anywhere  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.


SEE ALSO

     Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
     Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult


KEYWORDS

     bind, command, create, delete, interpreter, namespace

Tcl                       Last change:                          3


Man(1) output converted with man2html