1switched(n) Simple Tcl Only Object Oriented Programming switched(n)
2______________________________________________________________________________
6
8 switched - switch/option management.
9
11 package require Tcl 8.3
12 package require switched ?2.2.1?
14 <switched> complete this
16 <switched> options this
18 <switched> set-option this value
20______________________________________________________________________________
22
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 For example:
29 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 Of course, as you might have guessed, the car class is derived from the
38 switched class. Let us see how it works:
39 class car {
42 proc car {this args} switched {$args} {
43 # car specific initialization code here
44 switched::complete $this
45 }
46 ...
47 }
48 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 The switched class members available to the programmer are:
57 <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 <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 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 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 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 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 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 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 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 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 <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 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 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 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 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 new car
195 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 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 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 -option
219 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 ...
230 proc car::options {this} {
231 return {
232 ...
233 {-manufacturer {} {}}
234 ...
235 }
236 }
237 proc car::set-manufacturer {this value} {}
239 proc car::printData {this} {
241 puts "manufacturer: $switched::($this,-manufacturer)"
242 ...
243 }
244 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 complete
251 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 proc car::set-width {this value} {
262 if {$switched::($this,complete)} {
263 error {option -width cannot be set dynamically}
264 }
265 ...
266 }
267
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 When proposing code changes, please provide unified diffs, i.e the out‐
277 put of diff -u.
278 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
285 C++, class, object, object oriented
286
288 Programming tools
289tcllib 2.2.1 switched(n)