manpagez: man pages & more
man Tcl_CreateCommand(3)
Home | html | info | man
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

       Interpreter  in  which to create new command.  Name of command.  Imple-
       mentation of new command:  proc will  be  called  whenever  cmdName  is
       invoked  as  a  command.   Arbitrary one-word value to pass to proc and
       deleteProc.  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  associates  it
       with procedure proc such that whenever cmdName is invoked as a Tcl com-
       mand (via a call to Tcl_Eval) the Tcl interpreter  will  call  proc  to
       process  the  command.   It 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 proce-
       dures 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  inter-
       preter  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  com-
       patibility.

       The  procedures  Tcl_DeleteCommand, Tcl_GetCommandInfo, and Tcl_SetCom-
       mandInfo 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_GetCommand-
       Name.   If  cmdName contains any :: namespace qualifiers, then the com-
       mand 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  appli-
       cation-specific  data structure that describes what to do when the com-
       mand 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.

       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  over-
       view  man  page for details on what these codes mean.  Most normal com-
       mands 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  command,  and  in  the
       case  of TCL_ERROR it gives an error message.  The Tcl_SetResult proce-
       dure provides an easy interface for setting the return value;  for com-
       plete  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 com-
       mands 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 some-
       thing 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(3), Tcl_DeleteCommand(3), Tcl_GetCommandInfo(3),
       Tcl_SetCommandInfo(3), Tcl_GetCommandName(3), Tcl_SetObjResult(3)



KEYWORDS

       bind, command, create, delete, interpreter, namespace



Tcl                                                       Tcl_CreateCommand(3)

CrtCommand 8.5.4 - Generated Sun Aug 17 20:44:39 CDT 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.