Scroll to navigation

Tcl_Method(3tcl) TclOO Library Functions Tcl_Method(3tcl) 





NAME


Tcl_ClassSetConstructor, Tcl_ClassSetDestructor,
    Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic,
    Tcl_MethodIsPrivate, 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, 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
Tcl_MethodIsPublic(method)

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)

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




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








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 existing 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_ObjectContextInvokeNext are assumed to have a
    reference count of at least 1; the containing array is assumed to endure
    until the next method implementation (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_NRAddCallback.


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 returns properly (and the reference will be held if the method
    yields).






SEE ALSO


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






KEYWORDS


constructor, method, object









  

    0.1
    TclOO