1Tcl_Method(3)               TclOO Library Functions              Tcl_Method(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_ClassSetConstructor,    Tcl_ClassSetDestructor,   Tcl_MethodDeclar‐
9       erClass,  Tcl_MethodDeclarerObject,  Tcl_MethodIsPublic,  Tcl_MethodIs‐
10       Type, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_Object‐
11       ContextInvokeNext,     Tcl_ObjectContextIsFiltering,     Tcl_ObjectCon‐
12       textMethod,   Tcl_ObjectContextObject,  Tcl_ObjectContextSkippedArgs  -
13       manipulate methods and method-call contexts
14

SYNOPSIS

16       #include <tclOO.h>
17
18       Tcl_Method
19       Tcl_NewMethod(interp, class, nameObj, isPublic,
20                     methodTypePtr, clientData)
21
22       Tcl_Method
23       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
24                             methodTypePtr, clientData)
25
26       Tcl_ClassSetConstructor(interp, class, method)
27
28       Tcl_ClassSetDestructor(interp, class, method)
29
30       Tcl_Class
31       Tcl_MethodDeclarerClass(method)
32
33       Tcl_Object
34       Tcl_MethodDeclarerObject(method)
35
36       Tcl_Obj *
37       Tcl_MethodName(method)
38
39       int
40       Tcl_MethodIsPublic(method)
41
42       int
43       Tcl_MethodIsType(method, methodTypePtr, clientDataPtr)
44
45       int
46       Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip)
47
48       int
49       Tcl_ObjectContextIsFiltering(context)
50
51       Tcl_Method
52       Tcl_ObjectContextMethod(context)
53
54       Tcl_Object
55       Tcl_ObjectContextObject(context)
56
57       int
58       Tcl_ObjectContextSkippedArgs(context)
59

ARGUMENTS

61       Tcl_Interp *interp (in/out)         The interpreter holding the  object
62                                           or  class  to  create  or  update a
63                                           method in.
64
65       Tcl_Object object (in)              The object to create the method in.
66
67       Tcl_Class class (in)                The class to create the method in.
68
69       Tcl_Obj *nameObj (in)               The name of the method  to  create.
70                                           Should  not be NULL unless creating
71                                           constructors or destructors.
72
73       int isPublic (in)                   A flag saying what  the  visibility
74                                           of  the  method  is.  The only sup‐
75                                           ported public values of  this  flag
76                                           are  0  for  a non-exported method,
77                                           and 1 for an exported method.
78
79       Tcl_MethodType *methodTypePtr (in)  A description of the  type  of  the
80                                           method  to  create,  or the type of
81                                           method to compare against.
82
83       ClientData clientData (in)          A piece of data that is  passed  to
84                                           the  implementation  of  the method
85                                           without interpretation.
86
87       ClientData *clientDataPtr (out)     A pointer to a variable in which to
88                                           write the clientData value supplied
89                                           when the  method  was  created.  If
90                                           NULL, the clientData value will not
91                                           be retrieved.
92
93       Tcl_Method method (in)              A reference to a method to query.
94
95       Tcl_ObjectContext context (in)      A reference to a  method-call  con‐
96                                           text.  Note  that  client code must
97                                           not retain a reference  to  a  con‐
98                                           text.
99
100       int objc (in)                       The  number of arguments to pass to
101                                           the method implementation.
102
103       Tcl_Obj *const *objv (in)           An array of arguments  to  pass  to
104                                           the method implementation.
105
106       int skip (in)                       The  number  of arguments passed to
107                                           the method implementation  that  do
108                                           not represent "real" arguments.
109______________________________________________________________________________
110

DESCRIPTION

112       A  method  is  an operation carried out on an object that is associated
113       with the object. Every method must be attached to either an object or a
114       class;  methods  attached  to a class are associated with all instances
115       (direct and indirect) of that class.
116
117       Given a method,  the  entity  that  declared  it  can  be  found  using
118       Tcl_MethodDeclarerClass  which  returns  the  class  that the method is
119       attached to (or NULL if the method is not attached to  any  class)  and
120       Tcl_MethodDeclarerObject  which  returns  the object that the method is
121       attached to (or NULL if the method is not attached to an  object).  The
122       name of the method can be retrieved with Tcl_MethodName and whether the
123       method is exported is retrieved with Tcl_MethodIsPublic.  The  type  of
124       the method can also be introspected upon to a limited degree; the func‐
125       tion Tcl_MethodIsType returns whether a method is of a particular type,
126       assigning  the  per-method  clientData  to  the  variable pointed to by
127       clientDataPtr if (that is non-NULL) if the type is matched.
128
129   METHOD CREATION
130       Methods are created by Tcl_NewMethod and  Tcl_NewInstanceMethod,  which
131       create  a method attached to a class or an object respectively. In both
132       cases, the nameObj argument gives the name of the method to create, the
133       isPublic  argument  states  whether  the method should be exported ini‐
134       tially, the methodTypePtr argument describes the implementation of  the
135       method (see the METHOD TYPES section below) and the clientData argument
136       gives some implementation-specific data that is passed on to the imple‐
137       mentation of the method when it is called.
138
139       When  the  nameObj argument to Tcl_NewMethod is NULL, an unnamed method
140       is created, which is used for constructors and destructors.   Construc‐
141       tors  should  be  installed into their class using the Tcl_ClassSetCon‐
142       structor function, and destructors (which must not  require  any  argu‐
143       ments)  should  be installed into their class using the Tcl_ClassSetDe‐
144       structor function. Unnamed methods should not be  used  for  any  other
145       purpose, and named methods should not be used as either constructors or
146       destructors. Also note that a NULL methodTypePtr  is  used  to  provide
147       internal signaling, and should not be used in client code.
148
149   METHOD CALL CONTEXTS
150       When  a  method is called, a method-call context reference is passed in
151       as one of the arguments to the implementation  function.  This  context
152       can  be  inspected  to provide information about the caller, but should
153       not be retained beyond the moment when the method call terminates.
154
155       The method that is being called can be retrieved from  the  context  by
156       using Tcl_ObjectContextMethod, and the object that caused the method to
157       be invoked can be retrieved with Tcl_ObjectContextObject. The number of
158       arguments  that are to be skipped (e.g. the object name and method name
159       in a normal method call) is read with Tcl_ObjectContextSkippedArgs, and
160       the  context  can  also  report  whether  it is working as a filter for
161       another method through Tcl_ObjectContextIsFiltering.
162
163       During the execution of a method, the method implementation may  choose
164       to  invoke the stages of the method call chain that come after the cur‐
165       rent method implementation. This (the core of the next command) is done
166       using  Tcl_ObjectContextInvokeNext.  Note  that  this function does not
167       manipulate the call-frame stack, unlike the next command; if the method
168       implementation has pushed one or more extra frames on the stack as part
169       of its implementation, it is also responsible for  temporarily  popping
170       those frames from the stack while the Tcl_ObjectContextInvokeNext func‐
171       tion is executing. Note also that  the  method-call  context  is  never
172       deleted during the execution of this function.
173

METHOD TYPES

175       The  types  of  methods  are described by a pointer to a Tcl_MethodType
176       structure, which is defined as:
177
178              typedef struct {
179                  int version;
180                  const char *name;
181                  Tcl_MethodCallProc *callProc;
182                  Tcl_MethodDeleteProc *deleteProc;
183                  Tcl_CloneProc *cloneProc;
184              } Tcl_MethodType;
185
186       The version field allows for future expansion  of  the  structure,  and
187       should  always  be declared equal to TCL_OO_METHOD_VERSION_CURRENT. The
188       name field provides a human-readable name for  the  type,  and  is  the
189       value  that  is  exposed  via the info class methodtype and info object
190       methodtype Tcl commands.
191
192       The callProc field gives a function that is called when the  method  is
193       invoked; it must never be NULL.
194
195       The deleteProc field gives a function that is used to delete a particu‐
196       lar method, and is called when the method is replaced  or  removed;  if
197       the  field is NULL, it is assumed that the method's clientData needs no
198       special action to delete.
199
200       The cloneProc field is either  a  function  that  is  used  to  copy  a
201       method's  clientData  (as  part  of  Tcl_CopyObjectInstance) or NULL to
202       indicate that the clientData can just be copied directly.
203
204   TCL_METHODCALLPROC FUNCTION SIGNATURE
205       Functions matching  this  signature  are  called  when  the  method  is
206       invoked.
207
208              typedef int Tcl_MethodCallProc(
209                      ClientData clientData,
210                      Tcl_Interp *interp,
211                      Tcl_ObjectContext objectContext,
212                      int objc,
213                      Tcl_Obj *const *objv);
214
215       The  clientData  argument to a Tcl_MethodCallProc is the value that was
216       given when the method was created, the interp is a place  in  which  to
217       execute  scripts and access variables as well as being where to put the
218       result of the method, and the objc and objv fields give  the  parameter
219       objects to the method. The calling context of the method can be discov‐
220       ered through the objectContext argument, and the return  value  from  a
221       Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).
222
223   TCL_METHODDELETEPROC FUNCTION SIGNATURE
224       Functions  matching  this  signature are used when a method is deleted,
225       whether through a new method being created or  because  the  object  or
226       class is deleted.
227
228              typedef void Tcl_MethodDeleteProc(
229                      ClientData clientData);
230
231       The  clientData  argument to a Tcl_MethodDeleteProc will be the same as
232       the value  passed  to  the  clientData  argument  to  Tcl_NewMethod  or
233       Tcl_NewInstanceMethod when the method was created.
234
235   TCL_CLONEPROC FUNCTION SIGNATURE
236       Functions  matching  this  signature are used to copy a method when the
237       object or class is copied using Tcl_CopyObjectInstance (or oo::copy).
238
239              typedef int Tcl_CloneProc(
240                      Tcl_Interp *interp,
241                      ClientData oldClientData,
242                      ClientData *newClientDataPtr);
243
244       The interp argument gives a place to write an error  message  when  the
245       attempt  to clone the object is to fail, in which case the clone proce‐
246       dure must also return TCL_ERROR; it  should  return  TCL_OK  otherwise.
247       The  oldClientData  field  to  a Tcl_CloneProc gives the value from the
248       method being copied from, and the newClientDataPtr field will point  to
249       a variable in which to write the value for the method being copied to.
250

SEE ALSO

252       Class(3), oo::class(n), oo::define(n), oo::object(n)
253

KEYWORDS

255       constructor, method, object
256
257
258
259
260TclOO                                 0.1                        Tcl_Method(3)
Impressum