Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

Tcl_CreateObjCommand(3)                    Tcl Library Procedures                    Tcl_CreateObjCommand(3)



____________________________________________________________________________________________________________

NAME
       Tcl_CreateObjCommand,  Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCom-mandInfoFromToken, Tcl_GetCommandInfoFromToken,
       mandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken,  Tcl_GetCommandName,  Tcl_GetCom-mandFullName, Tcl_GetCommandFullName,
       mandFullName, 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 con-tains contains
                                                   tains a command.

       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_Cre-ateObjCommand. Tcl_CreateObjCommand.
                                                   ateObjCommand.  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)                        Object 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 (how-ever (however
       ever 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-spe-cific application-specific
       cific  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 objects (including the com-mand command
       mand  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 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 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_CON-TINUE. TCL_CONTINUE.
       TINUE.   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 repre-senting representing
       senting 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 inter-preter. interpreter.
       preter.   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 corre-sponding corresponding
       sponding 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_Cmd-Info Tcl_CmdInfo
       Info 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 com-mand; command;
       mand; 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 compatibility procedure regis-tered registered
       tered 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_SetCom-mandInfo Tcl_SetCommandInfo
       mandInfo 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_SetCommand-Info Tcl_SetCommandInfo
       Info 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  com-mand's command's
       mand's  deletion  procedure  to be given a different value than the ClientData for its command proce-dure. procedure.
       dure.

       Note that neither Tcl_SetCommandInfo nor Tcl_SetCommandInfoFromToken will change a  command's  names-pace. namespace.
       pace.  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  cor-responding corresponding
       responding  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 object specified by objPtr.

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

SEE ALSO
       Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult


KEYWORDS
       bind, command, create, delete, namespace, object



Tcl                                                  8.0                             Tcl_CreateObjCommand(3)