1define(n)                       TclOO Commands                       define(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       oo::define, oo::objdefine - define and configure classes and objects
9

SYNOPSIS

11       package require TclOO
12
13       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
19

DESCRIPTION

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
34   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
38       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
49       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
56       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
71       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
79       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
88       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
100       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
112       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
119       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
129       self subcommand arg ...
130
131       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
139       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
149       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
158       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
171   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
175       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
181       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
186       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
193       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
203       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
212       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
222       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
228       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
236       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
244       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

SLOTTED DEFINITIONS │

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
264       slot -append ?member ...?
265              This appends the given member elements to the slot definition.   │
266
267       slot -clear
268              This sets the slot definition to the empty list.                 │
269
270       slot -set ?member ...?
271              This  replaces  the  slot  definition with the given member ele‐ │
272              ments.                                                           │
273
274       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
279   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 │
282variable”  slot, this is forwarded to “my -append”), and these methods │
283       which provide the implementation interface:
284
285       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
290       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
295       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

EXAMPLES

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
308              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
327       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
330              oo::object create inst
331              inst m1               error "unknown method m1"
332              inst m2               error "unknown method m2"
333
334              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
345              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

SEE ALSO

357       next(n), oo::class(n), oo::object(n)
358

KEYWORDS

360       class, definition, method, object, slot
361
362
363
364TclOO                                 0.3                            define(n)
Impressum