1switched(n)       Simple Tcl Only Object Oriented Programming      switched(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       switched - switch/option management.
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require switched  ?2.2.1?
14
15       <switched> complete this
16
17       <switched> options this
18
19       <switched> set-option this value
20
21______________________________________________________________________________
22

DESCRIPTION

24       The  switched class serves as base class for user classes with switch /
25       option configuration procedures. It provides  facilities  for  managing
26       options through a simple interface.
27
28       For example:
29
30
31              set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
32              puts "my car was running on [switched::cget $vehicle -fuel]"
33              switched::configure $vehicle -power 40 -fuel electricity
34              puts "but is now running on clean [switched::cget $vehicle -fuel]"
35
36
37       Of course, as you might have guessed, the car class is derived from the
38       switched class. Let us see how it works:
39
40
41              class car {
42                  proc car {this args} switched {$args} {
43                      # car specific initialization code here
44                      switched::complete $this
45                  }
46                  ...
47              }
48
49
50       The switched class constructor takes the optional configuration  option
51       /  value pairs as parameters.  The switched class layer then completely
52       manages the switched options: it checks their  validity,  stores  their
53       values  and  provides a clean interface to the user layer configuration
54       setting procedures.
55
56       The switched class members available to the programmer are:
57
58       <switched> complete this
59              This procedure is used to tell the switched layer that  the  de‐
60              rived  class object (a car in the examples) is completely built.
61              At that time, the initial configuration of the  switched  object
62              occurs,  using  default  option  values  (see procedure options)
63              eventually overridden by construction time values, passed at the
64              time  of  the  new  operator invocation.  This procedure must be
65              called only once, usually around or at the end  of  the  derived
66              class  constructor.   (Note: Also check the complete data member
67              later in this chapter).
68
69       <switched> options this
70              This procedure must return the configuration description for all
71              options that the switched object will accept.  It is a pure vir‐
72              tual member procedure and therefore its implementation is manda‐
73              tory  in  the  derived class layer.  The procedure must return a
74              list of lists.  Each list pertains to a  single  option  and  is
75              composed  of  the  switch name, the default value for the option
76              and an optional initial value.  For example:
77
78
79
80              class car {
81                  ...
82                  proc options {this} {
83                      return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
84                  }
85                  proc set-fuel {this value} {
86                      ...
87                  }
88                  ...
89              }
90
91
92       In this case, 4 options are specified: fuel, length, power  and  width.
93       The  default  and  initial values for the fuel option are identical and
94       set to petrol.  For the other options, values are all empty.
95
96       For each option, there must be a corresponding set-option procedure de‐
97       fined in the derived class layer.  For example, since we defined a fuel
98       option, there is a set-fuel procedure in the car class.  The parameters
99       always are the object identifier (since this is not a static procedure,
100       but rather a dynamically defined virtual  one),  followed  by  the  new
101       value  for  the  option.  A set-option procedure is only invoked if the
102       new value differs from the current one (a caching scheme for  improving
103       performance), or if there is no initial value set in the options proce‐
104       dure for that option.
105
106       In this procedure, if the initial value differs from the default  value
107       or is omitted, then initial configuration is forced and the correspond‐
108       ing set-option procedure is invoked by the switched complete  procedure
109       located at the end of the derived class constructor.  For example:
110
111
112              class car {
113                  ...
114                  proc options {this} {
115                      return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
116                  }
117                  ...
118              }
119
120
121              In  this case, configuration is forced on the fuel and power op‐
122              tions, that is the corresponding set-option procedures  will  be
123              invoked  when the switched object is constructed (see set-option
124              procedures documentation below).
125
126              For the fuel option, since there is no initial value,  the  set-
127              fuel  procedure is called with the default value (petrol) as ar‐
128              gument.  For the power option, since the initial  value  differs
129              from  the  default value, the set-power procedure is called with
130              the initial value as argument (50).
131
132              For the other options, since the initial values  (last  elements
133              of  the option lists) are identical to their default values, the
134              corresponding set-option procedures will not be invoked.  It  is
135              the  programmer's  responsibility to insure that the initial op‐
136              tion values are correct.
137
138       <switched> set-option this value
139              These procedures may be viewed  as  dynamic  virtual  functions.
140              There  must  be  one implementation per supported option, as re‐
141              turned by the options procedure.  For example:
142
143
144              class car {
145                  ...
146                  proc options {this} {
147                      return [list ...
148                          [list -width {} {}] ]
149                  }
150                  ...
151                  proc set-width {this value} {
152                      ...
153                  }
154                  ...
155              }
156
157
158              Since the -width option was listed in the options  procedure,  a
159              set-width  procedure implementation is provided, which of course
160              would proceed to set the width of the car (and would modify  the
161              looks of a graphical representation, for example).
162
163              As  you  add  a supported option in the list returned by the op‐
164              tions procedure, the corresponding set-option procedure  may  be
165              called  as soon as the switched object is complete, which occurs
166              when the switched level complete procedure is invoked.  For  ex‐
167              ample:
168
169
170
171              class car {
172                  proc car {this args} switched {args} {
173                      ...
174                      switched::complete $this
175                 }
176                  ...
177                  proc options {this} {
178                      return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
179                  }
180                  proc set-fuel {this value} {
181                      ...
182                  }
183                  proc set-length {this value} {
184                      ...
185                  }
186                  proc set-power {this value} {
187                      ...
188                  }
189                  proc set-width {this value} {
190                      ...
191                  }
192              }
193
194              new car
195
196
197       In  this  case,  a new car is created with no options, which causes the
198       car constructor to be called, which in turns calls the  switched  level
199       complete  procedure  after  the car object layer is completely initial‐
200       ized.  At this point, since there are no initial values in  any  option
201       list  in  the  options procedure, the set-fuel procedure is called with
202       its default value of petrol as parameter, followed  by  the  set-length
203       call  with  4.5  value,  set-power with 350 value and finally with set-
204       width with 1.8 as parameter.  This is a good way to test the set-option
205       procedures  when debugging, and when done, just fill-in the initial op‐
206       tion values.
207
208       The switched layer checks that an option is valid (that is,  listed  in
209       the options procedure) but obviously does not check the validity of the
210       value passed to the set-option procedure, which should throw  an  error
211       (for example by using the Tcl error command) if the value is invalid.
212
213       The  switched  layer also keeps track of the options current values, so
214       that a set-option procedure is called only when the  corresponding  op‐
215       tion value passed as parameter is different from the current value (see
216       -option data members description).
217
218       -option
219
220              The -option data member is an options current value.   There  is
221              one  for  each  option  listed in the options procedure. It is a
222              read-only value which the switched layer checks against when  an
223              option  is changed.  It is rarely used at the layer derived from
224              switched, except in the few cases, such as in the following  ex‐
225              ample:
226
227
228
229              ...
230              proc car::options {this} {
231                  return {
232                      ...
233                      {-manufacturer {} {}}
234                      ...
235                  }
236              }
237
238              proc car::set-manufacturer {this value} {}
239
240              proc car::printData {this} {
241                  puts "manufacturer: $switched::($this,-manufacturer)"
242                  ...
243              }
244
245
246       In  this  case, the manufacturer's name is stored at the switched layer
247       level (this is why the set-manufacturer procedure has  nothing  to  do)
248       and later retrieved in the printData procedure.
249
250       complete
251
252              The  complete  data member (not to be confused with the complete
253              procedure) is a boolean.  Its initial value is false and  it  is
254              set  to true at the very end of the switched complete procedure.
255              It becomes useful when some options should be set  at  construc‐
256              tion  time  only  and  not dynamically, as the following example
257              shows:
258
259
260
261              proc car::set-width {this value} {
262                  if {$switched::($this,complete)} {
263                      error {option -width cannot be set dynamically}
264                  }
265                  ...
266              }
267
268

BUGS, IDEAS, FEEDBACK

270       This document, and the package it describes, will  undoubtedly  contain
271       bugs  and other problems.  Please report such in the category stooop of
272       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
273       also  report any ideas for enhancements you may have for either package
274       and/or documentation.
275
276       When proposing code changes, please provide unified diffs, i.e the out‐
277       put of diff -u.
278
279       Note  further  that  attachments  are  strongly  preferred over inlined
280       patches. Attachments can be made by going  to  the  Edit  form  of  the
281       ticket  immediately  after  its  creation, and then using the left-most
282       button in the secondary navigation bar.
283

KEYWORDS

285       C++, class, object, object oriented
286

CATEGORY

288       Programming tools
289
290
291
292tcllib                               2.2.1                         switched(n)
Impressum