Provided by: tcl8.6-doc_8.6.9+dfsg-2_all bug

NAME

       Tcl_ClassSetConstructor,          Tcl_ClassSetDestructor,         Tcl_MethodDeclarerClass,
       Tcl_MethodDeclarerObject,    Tcl_MethodIsPublic,     Tcl_MethodIsType,     Tcl_MethodName,
       Tcl_NewInstanceMethod,             Tcl_NewMethod,             Tcl_ObjectContextInvokeNext,
       Tcl_ObjectContextIsFiltering,      Tcl_ObjectContextMethod,       Tcl_ObjectContextObject,
       Tcl_ObjectContextSkippedArgs - manipulate methods and method-call contexts

SYNOPSIS

       #include <tclOO.h>

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

       Tcl_Method
       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
                             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
       Tcl_MethodIsPublic(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)

       int
       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 isPublic (in)                   A  flag  saying  what the visibility of the method is.
                                           The only supported 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 context. Note that client
                                           code must not retain a reference to a context.

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

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 attached 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  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 isPublic argument states whether the  method  should
       be  exported  initially,  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.  Constructors should be installed into their class
       using the Tcl_ClassSetConstructor function, and destructors (which must  not  require  any
       arguments) should be installed into their class using the Tcl_ClassSetDestructor 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 internal 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 another 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 current method implementation. This
       (the core of the next command) is done using Tcl_ObjectContextInvokeNext. Note  that  this
       function  does not manipulate 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 function 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 particular 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 indicate that the clientData can just be copied
       directly.

   TCL_METHODCALLPROC FUNCTION SIGNATURE
       Functions matching this signature are called when the method is invoked.

              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 discovered
       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(
                      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.

   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,
                      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 procedure 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.

SEE ALSO

       Class(3tcl), oo::class(3tcl), oo::define(3tcl), oo::object(3tcl)

KEYWORDS

       constructor, method, object