Unix/Linux Go Back    


CentOS 7.0 - man page for tcl_deletecommandfromtoken (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Tcl_CreateObjCommand(3) 	      Tcl Library Procedures		  Tcl_CreateObjCommand(3)

_________________________________________________________________________________________________

NAME
       Tcl_CreateObjCommand,  Tcl_DeleteCommand,  Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo,
       Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken,  Tcl_GetCom-
       mandName, 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.

       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-spe-
						   cific  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 infor-
						   mation 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 inter-
       preter (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_Get-
       CommandName.  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  client-
       Data  and interp arguments given to Tcl_CreateObjCommand.  Typically, clientData points to
       an application-specific data structure that describes what to do when the  command  proce-
       dure is invoked. Objc and objv describe the arguments to the command, objc giving the num-
       ber 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 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 repre-
       sentation of any individual object argument.  For instance, the user may call  Tcl_GetInt-
       FromObj	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_Eval-
       ObjEx  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_SetObjResult if you want to return some-
       thing 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_Cre-
       ateObjCommand.

       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 qual-
       ifiers, 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  informa-
       tion  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  regis-
       ter  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  informa-
       tion  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  com-
       mand procedure that implements the command.  If Tcl_CreateCommand was called for this com-
       mand, this is the procedure passed to it; otherwise, this  is  a  compatibility	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 Client-
       Data  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 com-
       mand 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 desig-
       nated 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 com-
       mand  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 com-
       mand'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_GetCom-
       mandName 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 object 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  com-
       mand is not found.

SEE ALSO
       Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult

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

Tcl					       8.0			  Tcl_CreateObjCommand(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:08 AM.