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 - 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-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)			   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 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 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	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 object argument.  For in-
       stance,	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_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 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_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 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 com-
       patibility 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 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 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  cur-
       rent 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)

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.tcl85&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help