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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       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

SYNOPSIS
       #include	<tclOO.h>

       Tcl_Method
       Tcl_NewMethod(interp, class, nameObj, flags, methodTypePtr,
		     clientData)

       Tcl_Method
       Tcl_NewInstanceMethod(interp, object, nameObj, flags, methodTypePtr,
			     clientData)

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)

       Tcl_Class
       Tcl_MethodDeclarerClass(method)

       Tcl_Object
       Tcl_MethodDeclarerObject(method)

       Tcl_Obj *
       Tcl_MethodName(method)

       int								       2
       Tcl_MethodIsPublic(method)					       2

       int
       Tcl_MethodIsPrivate(method)

       int
       Tcl_MethodIsType(method,	methodTypePtr, clientDataPtr)

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

       int
       Tcl_ObjectContextIsFiltering(context)

       Tcl_Method
       Tcl_ObjectContextMethod(context)

       Tcl_Object
       Tcl_ObjectContextObject(context)

       Tcl_Size
       Tcl_ObjectContextSkippedArgs(context)

ARGUMENTS
       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 visi-
				      bility 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 ex-
				      ported  method, TCL_OO_METHOD_UNEXPORTED
				      (which is	fixed at 0 for	backward  com-
				      patibility)  for	a non-exported method, 2
				      and TCL_OO_METHOD_PRIVATE	for a  private 2
				      method.

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

       void *clientData	(in)	      A	piece of data that is  passed  to  the
				      implementation of	the method without in-
				      terpretation.

       void **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 context.
				      Note that	client code must not retain  a
				      reference	to a context.

       Tcl_Size	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.

       Tcl_Size	skip (in)	      The  number  of  arguments passed	to the
				      method implementation that do not	repre-
				      sent "real" arguments.
______________________________________________________________________________

DESCRIPTION
       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 2
       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.

   METHOD CREATION
       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 2
       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
       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.

   METHOD CALL CONTEXTS
       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.

METHOD TYPES
       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.

   TCL_METHODCALLPROC FUNCTION SIGNATURE
       Functions matching this signature are called when  the  method  is  in-
       voked.

	      typedef int Tcl_MethodCallProc(
		      void *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).

   TCL_METHODDELETEPROC	FUNCTION SIGNATURE
       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(
		      void *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.

   TCL_CLONEPROC FUNCTION SIGNATURE
       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,
		      void *oldClientData,
		      void **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.

REFERENCE COUNT	MANAGEMENT
       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
       Tcl_DuplicateObj).

       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-
       back.

       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).

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

KEYWORDS
       constructor, method, object

TclOO				      0.1			 Tcl_Method(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_ObjectContextObject.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help