1Tcl_Method(3) TclOO Library Functions Tcl_Method(3)
2______________________________________________________________________________
6
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
16 #include <tclOO.h>
17 Tcl_Method
19 Tcl_NewMethod(interp, class, nameObj, isPublic,
20 methodTypePtr, clientData)
21 Tcl_Method
23 Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
24 methodTypePtr, clientData)
25 Tcl_ClassSetConstructor(interp, class, method)
27 Tcl_ClassSetDestructor(interp, class, method)
29 Tcl_Class
31 Tcl_MethodDeclarerClass(method)
32 Tcl_Object
34 Tcl_MethodDeclarerObject(method)
35 Tcl_Obj *
37 Tcl_MethodName(method)
38 int
40 Tcl_MethodIsPublic(method)
41 int
43 Tcl_MethodIsType(method, methodTypePtr, clientDataPtr)
44 int
46 Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip)
47 int
49 Tcl_ObjectContextIsFiltering(context)
50 Tcl_Method
52 Tcl_ObjectContextMethod(context)
53 Tcl_Object
55 Tcl_ObjectContextObject(context)
56 int
58 Tcl_ObjectContextSkippedArgs(context)
59
61 Tcl_Interp *interp (in/out) The interpreter holding the object
62 or class to create or update a
63 method in.
64 Tcl_Object object (in) The object to create the method in.
66 Tcl_Class class (in) The class to create the method in.
68 Tcl_Obj *nameObj (in) The name of the method to create.
70 Should not be NULL unless creating
71 constructors or destructors.
72 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 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 ClientData clientData (in) A piece of data that is passed to
84 the implementation of the method
85 without interpretation.
86 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 Tcl_Method method (in) A reference to a method to query.
94 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 int objc (in) The number of arguments to pass to
101 the method implementation.
102 Tcl_Obj *const *objv (in) An array of arguments to pass to
104 the method implementation.
105 int skip (in) The number of arguments passed to
107 the method implementation that do
108 not represent "real" arguments.
109______________________________________________________________________________
110
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 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 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 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 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 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 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
175 The types of methods are described by a pointer to a Tcl_MethodType
176 structure, which is defined as:
177 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 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 The callProc field gives a function that is called when the method is
193 invoked; it must never be NULL.
194 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 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 TCL_METHODCALLPROC FUNCTION SIGNATURE
205 Functions matching this signature are called when the method is
206 invoked.
207 typedef int Tcl_MethodCallProc(
209 ClientData clientData,
210 Tcl_Interp *interp,
211 Tcl_ObjectContext objectContext,
212 int objc,
213 Tcl_Obj *const *objv);
214 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 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 typedef void Tcl_MethodDeleteProc(
229 ClientData clientData);
230 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 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 typedef int Tcl_CloneProc(
240 Tcl_Interp *interp,
241 ClientData oldClientData,
242 ClientData *newClientDataPtr);
243 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
252 Class(3), oo::class(n), oo::define(n), oo::object(n)
253
255 constructor, method, object
256TclOO 0.1 Tcl_Method(3)