D 2016-09-17T13:38:14.194
L Doc:\sTcl_Method
N text/x-markdown
P 434a3faf0a564ad9dc95a1be2a098b06b1250fff
U dkf
W 12527
<h1>Tcl\_Method and supporting functions</h1>
<DL style="font-size:.85em">
<DD><A HREF="#M2" NAME="L476">NAME</A>
<DD><A HREF="#M3" NAME="L477">SYNOPSIS</A>
<DD><A HREF="#M5" NAME="L479">DESCRIPTION</A>
<DD><A HREF="#M6" NAME="L480">METHOD CREATION</A>
<DD><A HREF="#M7" NAME="L481">METHOD CALL CONTEXTS</A>
<DD><A HREF="#M8" NAME="L482">METHOD TYPES</A>
<DD><A HREF="#M9" NAME="L483">TCL\_METHODCALLPROC FUNCTION SIGNATURE</A>
<DD><A HREF="#M10" NAME="L484">TCL\_METHODDELETEPROC FUNCTION SIGNATURE</A>
<DD><A HREF="#M11" NAME="L485">TCL\_CLONEPROC FUNCTION SIGNATURE</A>
<DD><A HREF="#M12" NAME="L486">SEE ALSO</A>
<DD><A HREF="#M13" NAME="L487">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
<b>Tcl\_ClassSetConstructor</b>, <b>Tcl\_ClassSetDestructor</b>, <b>Tcl\_MethodDeclarerClass</b>, <b>Tcl\_MethodDeclarerObject</b>, <b>Tcl\_MethodIsPublic</b>, <b>Tcl\_MethodIsType</b>, <b>Tcl\_MethodName</b>, <b>Tcl\_NewInstanceMethod</b>, <b>Tcl\_NewMethod</b>, <b>Tcl\_ObjectContextInvokeNext</b>, <b>Tcl\_ObjectContextIsFiltering</b>, <b>Tcl\_ObjectContextMethod</b>, <b>Tcl\_ObjectContextObject</b>, <b>Tcl\_ObjectContextSkippedArgs</b> — manipulate methods and method-call contexts
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include <tclOO.h></B><BR><br>
Tcl\_Method <B>Tcl\_NewMethod</B>(<I>interp, class, nameObj, isPublic, methodTypePtr, clientData</I>)<BR>
Tcl\_Method <B>Tcl\_NewInstanceMethod</B>(<I>interp, object, nameObj, isPublic, methodTypePtr, clientData</I>)<BR>
void <B>Tcl\_ClassSetConstructor</B>(<I>interp, class, method</I>)<BR>
void <B>Tcl\_ClassSetDestructor</B>(<I>interp, class, method</I>)<BR>
<A HREF="?name=Doc:+Tcl_Class">Tcl\_Class</A> <B>Tcl\_MethodDeclarerClass</B>(<I>method</I>)<BR>
<A HREF="?name=Doc:+Tcl_Class">Tcl\_Object</A> <B>Tcl\_MethodDeclarerObject</B>(<I>method</I>)<BR>
Tcl\_Obj \*<B>Tcl\_MethodName</B>(<I>method</I>)<BR>
int <B>Tcl\_MethodIsPublic</B>(<I>method</I>)<BR>
int <B>Tcl\_MethodIsType</B>(<I>method, methodTypePtr, clientDataPtr</I>)<BR>
int <B>Tcl\_ObjectContextInvokeNext</B>(<I>interp, context, objc, objv, skip</I>)<BR>
int <B>Tcl\_ObjectContextIsFiltering</B>(<I>context</I>)<BR>
Tcl\_Method <B>Tcl\_ObjectContextMethod</B>(<I>context</I>)<BR>
<A HREF="?name=Doc:+Tcl_Class">Tcl\_Object</A> <B>Tcl\_ObjectContextObject</B>(<I>context</I>)<BR>
int <B>Tcl\_ObjectContextSkippedArgs</B>(<I>context</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT>Tcl\_Interp <B>\*interp</B> (in/out)<DD>
The interpreter holding the object or class to create or update a method in.
<P><DT><A HREF="?name=Doc:+Tcl_Class">Tcl\_Object</A> <B>object</B> (in)<DD>
The object to create the method in.
<P><DT><A HREF="?name=Doc:+Tcl_Class">Tcl\_Class</A> <B>class</B> (in)<DD>
The class to create the method in.
<P><DT>Tcl\_Obj <B>\*nameObj</B> (in)<DD>
The name of the method to create. Should not be NULL unless creating
constructors or destructors.
<P><DT>int <B>isPublic</B> (in)<DD>
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.
<P><DT>Tcl\_MethodType <B>\*methodTypePtr</B> (in)<DD>
A description of the type of the method to create, or the type of method to
compare against.
<P><DT>ClientData <B>clientData</B> (in)<DD>
A piece of data that is passed to the implementation of the method without
interpretation.
<P><DT>ClientData <B>\*clientDataPtr</B> (out)<DD>
A pointer to a variable in which to write the <I>clientData</I> value supplied
when the method was created. If NULL, the <I>clientData</I> value will not be
retrieved.
<P><DT>Tcl\_Method <B>method</B> (in)<DD>
A reference to a method to work with. This is an opaque token.
<P><DT>Tcl\_ObjectContext <B>context</B> (in)<DD>
A reference to a method-call context. This is an opaque token. Note that client code <I>must not</I>
retain a reference to a context; its lifespan is coupled to the Tcl execution stack.
<P><DT>int <B>objc</B> (in)<DD>
The number of arguments to pass to the method implementation.
<P><DT>Tcl\_Obj \*const <B>\*objv</B> (in)<DD>
An array of arguments to pass to the method implementation.
<P><DT>int <B>skip</B> (in)<DD>
The number of arguments passed to the method implementation that do not
represent "real" arguments.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
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.
<P>
Given a method, the entity that declared it can be found using
<B>Tcl\_MethodDeclarerClass</B> which returns the class that the method is
attached to (or NULL if the method is not attached to any class) and
<B>Tcl\_MethodDeclarerObject</B> 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 <B>Tcl\_MethodName</B> and whether the method
is exported is retrieved with <B>Tcl\_MethodIsPublic</B>. The type of the method
can also be introspected upon to a limited degree; the function
<B>Tcl\_MethodIsType</B> returns whether a method is of a particular type,
assigning the per-method <I>clientData</I> to the variable pointed to by
<I>clientDataPtr</I> if (that is non-NULL) if the type is matched.
<H4><A NAME="M6">METHOD CREATION</A></H4>
Methods are created by <B>Tcl\_NewMethod</B> and <B>Tcl\_NewInstanceMethod</B>,
which
create a method attached to a class or an object respectively. In both cases,
the <I>nameObj</I> argument gives the name of the method to create, the
<I>isPublic</I> argument states whether the method should be exported
initially, the <I>methodTypePtr</I> argument describes the implementation of
the method (see the <B><A HREF="#M8">METHOD TYPES</A></B> section below) and the <I>clientData</I>
argument gives some implementation-specific data that is passed on to the
implementation of the method when it is called.
<P>
When the <I>nameObj</I> argument to <B>Tcl\_NewMethod</B> is NULL, an
unnamed method is created, which is used for constructors and destructors.
Constructors should be installed into their class using the
<B>Tcl\_ClassSetConstructor</B> function, and destructors (which must not
require any arguments) should be installed into their class using the
<B>Tcl\_ClassSetDestructor</B> 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 <I>methodTypePtr</I> is used to provide
internal signaling, and should not be used in client code.
<H4><A NAME="M7">METHOD CALL CONTEXTS</A></H4>
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.
<P>
The method that is being called can be retrieved from the context by using
<B>Tcl\_ObjectContextMethod</B>, and the object that caused the method to be
invoked can be retrieved with <B>Tcl\_ObjectContextObject</B>. 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 <B>Tcl\_ObjectContextSkippedArgs</B>, and the
context can also report whether it is working as a filter for another method
through <B>Tcl\_ObjectContextIsFiltering</B>.
<P>
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 <B><A HREF="?name=Doc:+next">next</A></B> command) is done using
<B>Tcl\_ObjectContextInvokeNext</B>. Note that this function does not manipulate
the call-frame stack, unlike the <B><A HREF="?name=Doc:+next">next</A></B> 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 <B>Tcl\_ObjectContextInvokeNext</B> function is
executing. Note also that the method-call context is <I>never</I> deleted
during the execution of this function.
<H3><A NAME="M8">METHOD TYPES</A></H3>
The types of methods are described by a pointer to a Tcl\_MethodType structure,
which is defined as:
<P>
<PRE>typedef struct {
int <I>version</I>;
const char \*<I>name</I>;
Tcl\_MethodCallProc \*<I>callProc</I>;
Tcl\_MethodDeleteProc \*<I>deleteProc</I>;
Tcl\_CloneProc \*<I>cloneProc</I>;
} <B>Tcl\_MethodType</B>;</PRE>
<P>
The <I>version</I> field allows for future expansion of the structure, and
should always be declared equal to TCL\_OO\_METHOD\_VERSION\_CURRENT. The
<I>name</I> field provides a human-readable name for the type, and is the value
that is exposed via the <B>info class methodtype</B> and
<B>info object methodtype</B> Tcl commands.
<P>
The <I>callProc</I> field gives a function that is called when the method is
invoked; it must never be NULL.
<P>
The <I>deleteProc</I> 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 <I>clientData</I> needs no
special action to delete.
<P>
The <I>cloneProc</I> field is either a function that is used to copy a method's
<I>clientData</I> (as part of <B><A HREF="?name=Doc:+Tcl_Class">Tcl\_CopyObjectInstance</A></B>) or NULL to indicate
that the <I>clientData</I> can just be copied directly.
<H4><A NAME="M9">TCL\_METHODCALLPROC FUNCTION SIGNATURE</A></H4>
Functions matching this signature are called when the method is invoked.
<P>
<PRE>typedef int <B>Tcl\_MethodCallProc</B>(
ClientData <I>clientData</I>,
Tcl\_Interp \*<I>interp</I>,
Tcl\_ObjectContext <I>objectContext</I>,
int <I>objc</I>,
Tcl\_Obj \*const \*<I>objv</I>);</PRE>
<P>
The <I>clientData</I> argument to a Tcl\_MethodCallProc is the value that was
given when the method was created, the <I>interp</I> 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 <I>objc</I> and <I>objv</I> fields give the parameter
objects to the method. The calling context of the method can be discovered
through the <I>objectContext</I> argument, and the return value from a
Tcl\_MethodCallProc is any Tcl return code (e.g., TCL\_OK, TCL\_ERROR).
<H4><A NAME="M10">TCL\_METHODDELETEPROC FUNCTION SIGNATURE</A></H4>
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.
<P>
<PRE>typedef void <B>Tcl\_MethodDeleteProc</B>(
ClientData <I>clientData</I>);</PRE>
<P>
The <I>clientData</I> argument to a Tcl\_MethodDeleteProc will be the same as
the value passed to the <I>clientData</I> argument to <B>Tcl\_NewMethod</B> or
<B>Tcl\_NewInstanceMethod</B> when the method was created.
<H4><A NAME="M11">TCL\_CLONEPROC FUNCTION SIGNATURE</A></H4>
Functions matching this signature are used to copy a method when the object or
class is copied using <B><A HREF="?name=Doc:+Tcl_Class">Tcl\_CopyObjectInstance</A></B> (or <B><A HREF="?name=Doc:+oo::copy">oo::copy</A></B>).
<P>
<PRE>typedef int <B>Tcl\_CloneProc</B>(
Tcl\_Interp \*<I>interp</I>,
ClientData <I>oldClientData</I>,
ClientData \*<I>newClientDataPtr</I>);</PRE>
<P>
The <I>interp</I> 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 <I>oldClientData</I> field to a Tcl\_CloneProc gives the value from the
method being copied from, and the <I>newClientDataPtr</I> field will point to
a variable in which to write the value for the method being copied to.
<H3><A NAME="M12">SEE ALSO</A></H3>
<B><A HREF="?name=Doc:+Tcl_Class">Tcl\_Class</a></B>, <B><A HREF="?name=Doc:+oo::class">oo::class</A></B>, <B><A HREF="?name=Doc:+oo::define">oo::define</A></B>, <B><A HREF="?name=Doc:+oo::object">oo::object</A></B>
<H3><A NAME="M13">KEYWORDS</A></H3>
constructor, method, object
Z 1909bb8913ecce7fbef2656a20e4ff53
