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

FreeBSD Manual Pages


home | help
Tcl_Method(3)		    TclOO Library Functions		 Tcl_Method(3)


       Tcl_ClassSetConstructor,	   Tcl_ClassSetDestructor,   Tcl_MethodDeclar-
       erClass,	Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPri-
       vate,	Tcl_MethodIsType,    Tcl_MethodName,	Tcl_NewInstanceMethod,
       Tcl_NewMethod, Tcl_ObjectContextInvokeNext,  Tcl_ObjectContextIsFilter-
       ing,  Tcl_ObjectContextMethod,  Tcl_ObjectContextObject,	Tcl_ObjectCon-
       textSkippedArgs - manipulate methods and	method-call contexts

       #include	<tclOO.h>

       Tcl_NewMethod(interp, class, nameObj, flags, methodTypePtr,

       Tcl_NewInstanceMethod(interp, object, nameObj, flags, methodTypePtr,

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)



       Tcl_Obj *

       int								       |
       Tcl_MethodIsPublic(method)					       |


       Tcl_MethodIsType(method,	methodTypePtr, clientDataPtr)

       Tcl_ObjectContextInvokeNext(interp, context, objc, objv,	skip)





       Tcl_Interp *interp (in/out)	   The interpreter holding the	object
					   or  class  to  create  or  update a
					   method in.

       Tcl_Object object (in)		   The object to create	the method in.

       Tcl_Class class (in)		   The class to	create the method in.

       Tcl_Obj *nameObj	(in)		   The name of the method  to  create.
					   Should  not be NULL unless creating
					   constructors	or destructors.

       int flags (in)			   A flag saying (currently) what  the
					   visibility  of  the	method is. The
					   supported  public  values  of  this
					   flag	   are	  TCL_OO_METHOD_PUBLIC
					   (which is fixed at 1	 for  backward
					   compatibility)   for	  an  exported
					   method,    TCL_OO_METHOD_UNEXPORTED
					   (which  is  fixed at	0 for backward
					   compatibility) for  a  non-exported
					   method,  and	 TCL_OO_METHOD_PRIVATE |
					   for a private method.

       Tcl_MethodType *methodTypePtr (in)  A description of the	 type  of  the
					   method  to  create,	or the type of
					   method to compare against.

       ClientData clientData (in)	   A piece of data that	is  passed  to
					   the	implementation	of  the	method
					   without interpretation.

       ClientData *clientDataPtr (out)	   A pointer to	a variable in which to
					   write the clientData	value supplied
					   when	the  method  was  created.  If
					   NULL, the clientData	value will not
					   be retrieved.

       Tcl_Method method (in)		   A reference to a method to query.

       Tcl_ObjectContext context (in)	   A reference to a  method-call  con-
					   text.  Note	that  client code must
					   not retain a	reference  to  a  con-

       int objc	(in)			   The	number of arguments to pass to
					   the method implementation.

       Tcl_Obj *const *objv (in)	   An array of arguments  to  pass  to
					   the method implementation.

       int skip	(in)			   The	number	of arguments passed to
					   the method implementation  that  do
					   not represent "real"	arguments.

       A  method  is  an operation carried out on an object that is associated
       with the	object.	Every method must be attached to either	an object or a
       class;  methods	attached  to a class are associated with all instances
       (direct and indirect) of	that class.

       Given a method,	the  entity  that  declared  it	 can  be  found	 using
       Tcl_MethodDeclarerClass	which returns the class	that the method	is at-
       tached to (or NULL if the method	is not	attached  to  any  class)  and
       Tcl_MethodDeclarerObject	 which	returns	 the object that the method is
       attached	to (or NULL if the method is not attached to an	 object).  The
       name  of	 the  method can be retrieved with Tcl_MethodName, whether the
       method is exported is retrieved with  Tcl_MethodIsPublic,  and  whether |
       the  method is private is retrieved with	Tcl_MethodIsPrivate.  The type
       of the method can also be introspected upon to a	 limited  degree;  the
       function	 Tcl_MethodIsType  returns whether a method is of a particular
       type, assigning the per-method clientData to the	variable pointed to by
       clientDataPtr if	(that is non-NULL) if the type is matched.

       Methods	are  created by	Tcl_NewMethod and Tcl_NewInstanceMethod, which
       create a	method attached	to a class or an object	respectively. In  both
       cases, the nameObj argument gives the name of the method	to create, the
       flags argument states whether the method	should be  exported  initially |
       or  be marked as	a private method, the methodTypePtr argument describes
       the implementation of the method	(see the METHOD	TYPES  section	below)
       and  the	 clientData  argument  gives some implementation-specific data
       that is passed on to the	 implementation	 of  the  method  when	it  is

       When  the  nameObj argument to Tcl_NewMethod is NULL, an	unnamed	method
       is created, which is used for constructors and destructors.   Construc-
       tors  should  be	 installed into	their class using the Tcl_ClassSetCon-
       structor	function, and destructors (which must not  require  any	 argu-
       ments)  should  be installed into their class using the Tcl_ClassSetDe-
       structor	function. Unnamed methods should not be	 used  for  any	 other
       purpose,	and named methods should not be	used as	either constructors or
       destructors. Also note that a NULL methodTypePtr	is used	to provide in-
       ternal signaling, and should not	be used	in client code.

       When  a	method is called, a method-call	context	reference is passed in
       as one of the arguments to the implementation  function.	 This  context
       can  be	inspected  to provide information about	the caller, but	should
       not be retained beyond the moment when the method call terminates.

       The method that is being	called can be retrieved	from  the  context  by
       using Tcl_ObjectContextMethod, and the object that caused the method to
       be invoked can be retrieved with	Tcl_ObjectContextObject. The number of
       arguments  that are to be skipped (e.g. the object name and method name
       in a normal method call)	is read	with Tcl_ObjectContextSkippedArgs, and
       the  context  can also report whether it	is working as a	filter for an-
       other method through Tcl_ObjectContextIsFiltering.

       During the execution of a method, the method implementation may	choose
       to  invoke the stages of	the method call	chain that come	after the cur-
       rent method implementation. This	(the core of the next command) is done
       using Tcl_ObjectContextInvokeNext. Note that this function does not ma-
       nipulate	the call-frame stack, unlike the next command; if  the	method
       implementation has pushed one or	more extra frames on the stack as part
       of its implementation, it is also responsible for  temporarily  popping
       those frames from the stack while the Tcl_ObjectContextInvokeNext func-
       tion is executing. Note also that  the  method-call  context  is	 never
       deleted during the execution of this function.

       The  types  of  methods	are described by a pointer to a	Tcl_MethodType
       structure, which	is defined as:

	      typedef struct {
		  int version;
		  const	char *name;
		  Tcl_MethodCallProc *callProc;
		  Tcl_MethodDeleteProc *deleteProc;
		  Tcl_CloneProc	*cloneProc;
	      }	Tcl_MethodType;

       The version field allows	for future expansion  of  the  structure,  and
       should  always  be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
       name field provides a human-readable name for  the  type,  and  is  the
       value  that  is	exposed	 via the info class methodtype and info	object
       methodtype Tcl commands.

       The callProc field gives	a function that	is called when the  method  is
       invoked;	it must	never be NULL.

       The deleteProc field gives a function that is used to delete a particu-
       lar method, and is called when the method is replaced  or  removed;  if
       the  field is NULL, it is assumed that the method's clientData needs no
       special action to delete.

       The cloneProc field is either  a	 function  that	 is  used  to  copy  a
       method's	 clientData (as	part of	Tcl_CopyObjectInstance)	or NULL	to in-
       dicate that the clientData can just be copied directly.

       Functions matching this signature are called when  the  method  is  in-

	      typedef int Tcl_MethodCallProc(
		      ClientData clientData,
		      Tcl_Interp *interp,
		      Tcl_ObjectContext	objectContext,
		      int objc,
		      Tcl_Obj *const *objv);

       The  clientData	argument to a Tcl_MethodCallProc is the	value that was
       given when the method was created, the interp is	a place	 in  which  to
       execute	scripts	and access variables as	well as	being where to put the
       result of the method, and the objc and objv fields give	the  parameter
       objects to the method. The calling context of the method	can be discov-
       ered through the	objectContext argument,	and the	return	value  from  a
       Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).

       Functions  matching  this  signature are	used when a method is deleted,
       whether through a new method being created or  because  the  object  or
       class is	deleted.

	      typedef void Tcl_MethodDeleteProc(
		      ClientData clientData);

       The  clientData	argument to a Tcl_MethodDeleteProc will	be the same as
       the value  passed  to  the  clientData  argument	 to  Tcl_NewMethod  or
       Tcl_NewInstanceMethod when the method was created.

       Functions  matching  this  signature are	used to	copy a method when the
       object or class is copied using Tcl_CopyObjectInstance (or oo::copy).

	      typedef int Tcl_CloneProc(
		      Tcl_Interp *interp,
		      ClientData oldClientData,
		      ClientData *newClientDataPtr);

       The interp argument gives a place to write an error  message  when  the
       attempt	to clone the object is to fail,	in which case the clone	proce-
       dure must also return TCL_ERROR;	it  should  return  TCL_OK  otherwise.
       The  oldClientData  field  to  a	Tcl_CloneProc gives the	value from the
       method being copied from, and the newClientDataPtr field	will point  to
       a variable in which to write the	value for the method being copied to.

       The  nameObj  argument to Tcl_NewMethod and Tcl_NewInstanceMethod (when
       non-NULL) will have its reference count incremented if there is no  ex-
       isting method with that name in that class/object.

       The  result  of	Tcl_MethodName is a value with a reference count of at
       least one. It should not	be modified without first duplicating it (with

       The values in the first objc values of the objv argument	to Tcl_Object-
       ContextInvokeNext are assumed to	have a reference count of at least  1;
       the  containing array is	assumed	to endure until	the next method	imple-
       mentation (see next) returns. Be	aware that methods may yield;  if  any
       post-call  actions  are desired (e.g., decrementing the reference count
       of values passed	in here), they must be scheduled  with	Tcl_NRAddCall-

       The  callProc  of the Tcl_MethodType structure takes values of at least
       reference count 1 in its	objv argument. It may add its own  references,
       but must	not decrement the reference count below	that level; the	caller
       of the method will decrement the	reference count	once  the  method  re-
       turns properly (and the reference will be held if the method yields).

       Class(3), NRE(3), oo::class(n), oo::define(n), oo::object(n)

       constructor, method, object

TclOO				      0.1			 Tcl_Method(3)


Want to link to this manual page? Use this URL:

home | help