Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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_GetCommandName,  Tcl_GetCommandFull-
       Name, Tcl_GetCommandFromObj,  Tcl_RegisterCommandTypeName,  Tcl_GetCom-
       mandTypeName - 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)

       void								       |
       Tcl_RegisterCommandTypeName(proc, typeName)			       |

       const char *							       |
       Tcl_GetCommandTypeName(token)					       |

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-specific   cleanup.
						   If NULL, then no  procedure
						   is  called  before the com-
						   mand	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  con-
						   taining various information
						   about a Tcl command.

       Tcl_Obj *objPtr (in)			   Value containing  the  name
						   of a	Tcl command.

       const char *typeName (in)		   Indicates  the  name	of the
						   type	of command implementa-
						   tion	associated with	a par-
						   ticular proc,  or  NULL  to
						   break the association.
______________________________________________________________________________

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  associ-
       ated 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 com-
       mand 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_CreateObj-
       Command.	  Typically, clientData	points to an application-specific data
       structure that describes	what to	do when	the command procedure  is  in-
       voked. 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	decla-
       ration  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 in-
       stance, 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 com-
       mands 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_SetO-
       bjResult	if you want to return something	from the objv array.

       Ordinarily, Tcl_CreateObjCommand	deletes	any existing command name  al-
       ready  associated  with the interpreter.	 However, if the existing com-
       mand was	created	by a previous call to Tcl_CreateCommand, Tcl_CreateOb-
       jCommand	 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_CreateOb-
       jCommand.  DeleteProc is	invoked	before the  command  is	 deleted,  and
       gives  the application an opportunity to	release	any structures associ-
       ated 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  com-
       mand,  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_DeleteCommandFrom-
       Token deletes the command from a	command	interpreter.  It will delete a
       command	even  if  that	command	 has been renamed.  Once the call com-
       pletes, attempts	to invoke the command in interp	will result in errors.
       If the command corresponding to token has already been deleted from in-
       terp 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  com-
       patibility  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 in-
       foPtr.

       Tcl_SetCommandInfo is used to modify the	procedures and ClientData val-
       ues 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 in-
       formation 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  in-
       stead  of the command name.  If the token parameter is NULL, it returns
       0.  Otherwise, it copies	the information	from *infoPtr to Tcl's	inter-
       nal 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 differ-
       ent 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 in-
       clude 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 cur-
       rent namespace.	Returns	NULL if	the command is not found.

       Tcl_RegisterCommandTypeName is used to associate	a name	(the  typeName |
       argument) with a	particular implementation function so that it can then |
       be looked up with Tcl_GetCommandTypeName, which in turn is called  with |
       a  command  token  that information is wanted for and which returns the |
       name of the type	that was registered for	 the  implementation  function |
       used  for that command. (The lookup functionality is surfaced virtually |
       directly	in Tcl via info	cmdtype.) If there is no  function  registered |
       for  a  particular function, the	result will be the string literal "na- |
       tive".  The registration	of a name can be undone	by registering a  map- |
       ping  to	 NULL  instead.	The result from	Tcl_GetCommandTypeName will be |
       exactly that string which was registered, and not a copy; use of	a com- |
       pile-time constant string is strongly recommended.

SEE ALSO
       Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)

KEYWORDS
       bind, command, create, delete, namespace, value

Tcl				      8.0	       Tcl_CreateObjCommand(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_CreateObjCommand.tcl87&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help