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_MethodIs-
       Type, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_Object-
       ContextInvokeNext,     Tcl_ObjectContextIsFiltering,	Tcl_ObjectCon-
       textMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs - ma-
       nipulate	methods	and method-call	contexts

       #include	<tclOO.h>

       Tcl_NewMethod(interp, class, nameObj, isPublic,
		     methodTypePtr, clientData)

       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
			     methodTypePtr, clientData)

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)



       Tcl_Obj *


       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 isPublic (in)		   A flag saying what  the  visibility
					   of  the  method  is.	 The only sup-
					   ported public values	of  this  flag
					   are	0  for	a non-exported method,
					   and 1 for an	exported 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 and whether the
       method is exported is retrieved with Tcl_MethodIsPublic.	 The  type  of
       the method can also be introspected upon	to a limited degree; the func-
       tion 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
       isPublic	 argument  states  whether  the	method should be exported ini-
       tially, 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	imple-
       mentation of the	method when it is called.

       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.

       Class(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