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