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) or the class object
55              itself.
56
57       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
72       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
80       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
89       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
101       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
113       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
120       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
130       self subcommand arg ...
131
132       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
140       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
150       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
159       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
172   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
176       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
182       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
190       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
197       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
207       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
216       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
226       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
232       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
243       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
251       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

SLOTTED DEFINITIONS │

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
271       slot -append ?member ...?
272              This appends the given member elements to the slot definition.   │
273
274       slot -clear
275              This sets the slot definition to the empty list.                 │
276
277       slot -set ?member ...?
278              This replaces the slot definition with  the  given  member  ele‐ │
279              ments.                                                           │
280
281       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
286   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 │
289variable” slot, this is forwarded to “my -append”), and these  methods │
290       which provide the implementation interface:
291
292       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
297       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
302       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

EXAMPLES

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
315              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
334       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
337              oo::object create inst
338              inst m1               error "unknown method m1"
339              inst m2               error "unknown method m2"
340
341              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
352              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

SEE ALSO

364       next(n), oo::class(n), oo::object(n)
365

KEYWORDS

367       class, definition, method, object, slot
368
369
370
371TclOO                                 0.3                            define(n)
Impressum