1define(n) TclOO Commands define(n)
2______________________________________________________________________________
6
8 oo::define, oo::objdefine - define and configure classes and objects
9
11 package require TclOO
12 oo::define class defScript
14 oo::define class subcommand arg ?arg ...?
15 oo::objdefine object defScript
16 oo::objdefine object subcommand arg ?arg ...?
17______________________________________________________________________________
18
21 The oo::define command is used to control the configuration of classes,
22 and the oo::objdefine command is used to control the configuration of
23 objects (including classes as instance objects), with the configuration
24 being applied to the entity named in the class or the object argument.
25 Configuring a class also updates the configuration of all subclasses of
26 the class and all objects that are instances of that class or which mix
27 it in (as modified by any per-instance configuration). The way in which
28 the configuration is done is controlled by either the defScript argu‐
29 ment or by the subcommand and following arg arguments; when the second
30 is present, it is exactly as if all the arguments from subcommand
31 onwards are made into a list and that list is used as the defScript
32 argument.
33 CONFIGURING CLASSES
35 The following commands are supported in the defScript for oo::define,
36 each of which may also be used in the subcommand form:
37 constructor argList bodyScript
39 This creates or updates the constructor for a class. The formal
40 arguments to the constructor (defined using the same format as
41 for the Tcl proc command) will be argList, and the body of the
42 constructor will be bodyScript. When the body of the constructor
43 is evaluated, the current namespace of the constructor will be a
44 namespace that is unique to the object being constructed. Within
45 the constructor, the next command should be used to call the
46 superclasses' constructors. If bodyScript is the empty string,
47 the constructor will be deleted.
48 deletemethod name ?name ...?
50 This deletes each of the methods called name from a class. The
51 methods must have previously existed in that class. Does not
52 affect the superclasses of the class, nor does it affect the
53 subclasses or instances of the class (except when they have a
54 call chain through the class being modified) or the class object
55 itself.
56 destructor bodyScript
58 This creates or updates the destructor for a class. Destructors
59 take no arguments, and the body of the destructor will be
60 bodyScript. The destructor is called when objects of the class
61 are deleted, and when called will have the object's unique
62 namespace as the current namespace. Destructors should use the
63 next command to call the superclasses' destructors. Note that
64 destructors are not called in all situations (e.g. if the inter‐
65 preter is destroyed). If bodyScript is the empty string, the
66 destructor will be deleted.
67 Note that errors during the evaluation of a destructor are not
68 returned to the code that causes the destruction of an object.
69 Instead, they are passed to the currently-defined bgerror han‐
70 dler.
71 export name ?name ...?
73 This arranges for each of the named methods, name, to be
74 exported (i.e. usable outside an instance through the instance
75 object's command) by the class being defined. Note that the
76 methods themselves may be actually defined by a superclass; sub‐
77 class exports override superclass visibility, and may in turn be
78 overridden by instances.
79 filter ?-slotOperation? ?methodName ...?
81 This slot (see SLOTTED DEFINITIONS below) sets or updates the │
82 list of method names that are used to guard whether method call
83 to instances of the class may be called and what the method's
84 results are. Each methodName names a single filtering method
85 (which may be exposed or not exposed); it is not an error for a
86 non-existent method to be named since they may be defined by
87 subclasses. By default, this slot works by appending. │
88 forward name cmdName ?arg ...?
90 This creates or updates a forwarded method called name. The
91 method is defined be forwarded to the command called cmdName,
92 with additional arguments, arg etc., added before those argu‐
93 ments specified by the caller of the method. The cmdName will
94 always be resolved using the rules of the invoking objects'
95 namespaces, i.e., when cmdName is not fully-qualified, the com‐
96 mand will be searched for in each object's namespace, using the
97 instances' namespace's path, or by looking in the global names‐
98 pace. The method will be exported if name starts with a lower-
99 case letter, and non-exported otherwise.
100 method name argList bodyScript
102 This creates or updates a method that is implemented as a proce‐
103 dure-like script. The name of the method is name, the formal
104 arguments to the method (defined using the same format as for
105 the Tcl proc command) will be argList, and the body of the
106 method will be bodyScript. When the body of the method is evalu‐
107 ated, the current namespace of the method will be a namespace
108 that is unique to the current object. The method will be
109 exported if name starts with a lower-case letter, and non-
110 exported otherwise; this behavior can be overridden via export
111 and unexport.
112 mixin ?-slotOperation? ?className ...?
114 This slot (see SLOTTED DEFINITIONS below) sets or updates the │
115 list of additional classes that are to be mixed into all the
116 instances of the class being defined. Each className argument
117 names a single class that is to be mixed in. By default, this │
118 slot works by replacement.
119 renamemethod fromName toName
121 This renames the method called fromName in a class to toName.
122 The method must have previously existed in the class, and toName
123 must not previously refer to a method in that class. Does not
124 affect the superclasses of the class, nor does it affect the
125 subclasses or instances of the class (except when they have a
126 call chain through the class being modified), or the class
127 object itself. Does not change the export status of the method;
128 if it was exported before, it will be afterwards.
129 self subcommand arg ...
131 self script
133 This command is equivalent to calling oo::objdefine on the class
134 being defined (see CONFIGURING OBJECTS below for a description
135 of the supported values of subcommand). It follows the same gen‐
136 eral pattern of argument handling as the oo::define and
137 oo::objdefine commands, and “oo::define cls self subcommand ...”
138 operates identically to “oo::objdefine cls subcommand ...”.
139 superclass ?-slotOperation? ?className ...?
141 This slot (see SLOTTED DEFINITIONS below) allows the alteration │
142 of the superclasses of the class being defined. Each className
143 argument names one class that is to be a superclass of the
144 defined class. Note that objects must not be changed from being
145 classes to being non-classes or vice-versa, that an empty parent
146 class is equivalent to oo::object, and that the parent classes
147 of oo::object and oo::class may not be modified. By default, │
148 this slot works by replacement.
149 unexport name ?name ...?
151 This arranges for each of the named methods, name, to be not
152 exported (i.e. not usable outside the instance through the
153 instance object's command, but instead just through the my com‐
154 mand visible in each object's context) by the class being
155 defined. Note that the methods themselves may be actually
156 defined by a superclass; subclass unexports override superclass
157 visibility, and may be overridden by instance unexports.
158 variable ?-slotOperation? ?name ...?
160 This slot (see SLOTTED DEFINITIONS below) arranges for each of │
161 the named variables to be automatically made available in the │
162 methods, constructor and destructor declared by the class being │
163 defined. Each variable name must not have any namespace separa‐ │
164 tors and must not look like an array access. All variables will │
165 be actually present in the instance object on which the method │
166 is executed. Note that the variable lists declared by a super‐ │
167 class or subclass are completely disjoint, as are variable lists │
168 declared by instances; the list of variable names is just for │
169 methods (and constructors and destructors) declared by this │
170 class. By default, this slot works by appending.
171 CONFIGURING OBJECTS
173 The following commands are supported in the defScript for oo::objde‐
174 fine, each of which may also be used in the subcommand form:
175 class className
177 This allows the class of an object to be changed after creation.
178 Note that the class's constructors are not called when this is
179 done, and so the object may well be in an inconsistent state
180 unless additional configuration work is done.
181 deletemethod name ?name ...
183 This deletes each of the methods called name from an object. The
184 methods must have previously existed in that object (e.g.,
185 because it was created through oo::objdefine method). Does not
186 affect the classes that the object is an instance of, or remove
187 the exposure of those class-provided methods in the instance of
188 that class.
189 export name ?name ...?
191 This arranges for each of the named methods, name, to be
192 exported (i.e. usable outside the object through the object's
193 command) by the object being defined. Note that the methods
194 themselves may be actually defined by a class or superclass;
195 object exports override class visibility.
196 filter ?-slotOperation? ?methodName ...?
198 This slot (see SLOTTED DEFINITIONS below) sets or updates the │
199 list of method names that are used to guard whether a method
200 call to the object may be called and what the method's results
201 are. Each methodName names a single filtering method (which may
202 be exposed or not exposed); it is not an error for a non-exis‐
203 tent method to be named. Note that the actual list of filters
204 also depends on the filters set upon any classes that the object
205 is an instance of. By default, this slot works by appending. │
206 forward name cmdName ?arg ...?
208 This creates or updates a forwarded object method called name.
209 The method is defined be forwarded to the command called cmd‐
210 Name, with additional arguments, arg etc., added before those
211 arguments specified by the caller of the method. Forwarded meth‐
212 ods should be deleted using the method subcommand. The method
213 will be exported if name starts with a lower-case letter, and
214 non-exported otherwise.
215 method name argList bodyScript
217 This creates, updates or deletes an object method. The name of
218 the method is name, the formal arguments to the method (defined
219 using the same format as for the Tcl proc command) will be
220 argList, and the body of the method will be bodyScript. When the
221 body of the method is evaluated, the current namespace of the
222 method will be a namespace that is unique to the object. The
223 method will be exported if name starts with a lower-case letter,
224 and non-exported otherwise.
225 mixin ?-slotOperation? ?className ...?
227 This slot (see SLOTTED DEFINITIONS below) sets or updates a per- │
228 object list of additional classes that are to be mixed into the
229 object. Each argument, className, names a single class that is
230 to be mixed in. By default, this slot works by replacement. │
231 renamemethod fromName toName
233 This renames the method called fromName in an object to toName.
234 The method must have previously existed in the object, and
235 toName must not previously refer to a method in that object.
236 Does not affect the classes that the object is an instance of
237 and cannot rename in an instance object the methods provided by
238 those classes (though a oo::objdefine forwarded method may pro‐
239 vide an equivalent capability). Does not change the export sta‐
240 tus of the method; if it was exported before, it will be after‐
241 wards.
242 unexport name ?name ...?
244 This arranges for each of the named methods, name, to be not
245 exported (i.e. not usable outside the object through the
246 object's command, but instead just through the my command visi‐
247 ble in the object's context) by the object being defined. Note
248 that the methods themselves may be actually defined by a class;
249 instance unexports override class visibility.
250 variable ?-slotOperation? ?name ...?
252 This slot (see SLOTTED DEFINITIONS below) arranges for each of │
253 the named variables to be automatically made available in the │
254 methods declared by the object being defined. Each variable │
255 name must not have any namespace separators and must not look │
256 like an array access. All variables will be actually present in │
257 the object on which the method is executed. Note that the vari‐ │
258 able lists declared by the classes and mixins of which the │
259 object is an instance are completely disjoint; the list of vari‐ │
260 able names is just for methods declared by this object. By │
261 default, this slot works by appending. │
262
264 Some of the configurable definitions of a class or object are slotted │
265 definitions. This means that the configuration is implemented by a slot │
266 object, that is an instance of the class oo::Slot, which manages a list │
267 of values (class names, variable names, etc.) that comprises the con‐ │
268 tents of the slot. The class defines three operations (as methods) that │
269 may be done on the slot:
270 slot -append ?member ...?
272 This appends the given member elements to the slot definition. │
273 slot -clear
275 This sets the slot definition to the empty list. │
276 slot -set ?member ...?
278 This replaces the slot definition with the given member ele‐ │
279 ments. │
280 A consequence of this is that any use of a slot's default operation │
282 where the first member argument begins with a hyphen will be an error. │
283 One of the above operations should be used explicitly in those circum‐ │
284 stances. │
285 SLOT IMPLEMENTATION │
287 Internally, slot objects also define a method --default-operation which │
288 is forwarded to the default operation of the slot (thus, for the class │
289 “variable” slot, this is forwarded to “my -append”), and these methods │
290 which provide the implementation interface:
291 slot Get
293 Returns a list that is the current contents of the slot. This │
294 method must always be called from a stack frame created by a │
295 call to oo::define or oo::objdefine.
296 slot Set elementList
298 Sets the contents of the slot to the list elementList and │
299 returns the empty string. This method must always be called from │
300 a stack frame created by a call to oo::define or oo::objdefine. │
301 The implementation of these methods is slot-dependent (and responsible │
303 for accessing the correct part of the class or object definition). │
304 Slots also have an unknown method handler to tie all these pieces │
305 together, and they hide their destroy method so that it is not invoked │
306 inadvertently. It is recommended that any user changes to the slot │
307 mechanism be restricted to defining new operations whose names start │
308 with a hyphen.
309
311 This example demonstrates how to use both forms of the oo::define and
312 oo::objdefine commands (they work in the same way), as well as illus‐
313 trating four of the subcommands of them.
314 oo::class create c
316 c create o
317 oo::define c method foo {} {
318 puts "world"
319 }
320 oo::objdefine o {
321 method bar {} {
322 my Foo "hello "
323 my foo
324 }
325 forward Foo ::puts -nonewline
326 unexport foo
327 }
328 o bar → prints "hello world"
329 o foo → error "unknown method foo"
330 o Foo Bar → error "unknown method Foo"
331 oo::objdefine o renamemethod bar lollipop
332 o lollipop → prints "hello world"
333 This example shows how additional classes can be mixed into an object.
335 It also shows how mixin is a slot that supports appending:
336 oo::object create inst
338 inst m1 → error "unknown method m1"
339 inst m2 → error "unknown method m2"
340 oo::class create A {
342 method m1 {} {
343 puts "red brick"
344 }
345 }
346 oo::objdefine inst {
347 mixin A
348 }
349 inst m1 → prints "red brick"
350 inst m2 → error "unknown method m2"
351 oo::class create B {
353 method m2 {} {
354 puts "blue brick"
355 }
356 }
357 oo::objdefine inst {
358 mixin -append B
359 }
360 inst m1 → prints "red brick"
361 inst m2 → prints "blue brick"
362
364 next(n), oo::class(n), oo::object(n)
365
367 class, definition, method, object, slot
368TclOO 0.3 define(n)