switched(n)

💖 NAME 💖

okay so bestie, welcome to switched(n) — the page for switched, and it's literally all about switch/option management. that's it, that's the vibe. 💅

---

🎀 SYNOPSIS 🎀

package require Tcl 8.5 9

package require switched ?2.2.2?

<switched> complete this

<switched> options this

<switched> set-option this value

---

🦋 DESCRIPTION 🦋

so the switched class is the base class you inherit from when your own classes need switch / option configuration procedures. it hands you a whole set of facilities for managing options through one simple little interface, no cap. 🫶

like, for example:

set vehicle [new car -length 4.5 -width 2 -power 100 -fuel diesel]
puts "my car was running on [switched::cget $vehicle -fuel]"
switched::configure $vehicle -power 40 -fuel electricity
puts "but is now running on clean [switched::cget $vehicle -fuel]"

and yeah, you probably already guessed it — the car class is derived from the switched class. so let's see how that actually works:

class car {
    proc car {this args} switched {$args} {
        # car specific initialization code here
        switched::complete $this
    }
    ...
}

the switched class constructor takes the optional configuration option / value pairs as its parameters. then the switched class layer does all the heavy lifting on the switched options: it checks that they're valid, it stores their values, and it gives the user layer configuration setting procedures a clean interface to work with. iconic behavior honestly. ✨

the switched class members you (the programmer) get to play with are:

🌸 <switched> complete this 🌸

this procedure is how you tell the switched layer that the derived class object (a car in the examples) is completely built. once you do that, the initial configuration of the switched object happens — using the default option values (peep the options procedure) which may have been overridden by construction time values that got passed when the new operator was invoked.

⚠️ this procedure must be called only once, usually around or at the end of the derived class constructor.

(also note: check out the complete data member further down this chapter, bestie, it's a whole different thing 👀)

🧚 <switched> options this 🧚

this procedure must return the configuration description for every option that the switched object will accept. it's a pure virtual member procedure, so implementing it in your derived class layer is mandatory — no skipping, periodt.

the procedure has to return a list of lists. each little list is about a single option, and it's made of the switch name, the default value for that option, and an optional initial value. like so:

class car {
    ...
    proc options {this} {
        return [list [list -fuel petrol petrol] [list -length {} {}] [list -power {} {}] [list -width {} {}] ]
    }
    proc set-fuel {this value} {
        ...
    }
    ...
}

in this case, 4 options are specified: fuel, length, power and width. the default and initial values for the fuel option are identical and set to petrol. for the other options, the values are all empty.

for each option there must be a corresponding set-option procedure defined in the derived class layer. like, since we defined a fuel option, there's a set-fuel procedure in the car class. the parameters are always the object identifier first (because this isn't a static procedure, it's a dynamically defined virtual one 💫), followed by the new value for the option.

a set-option procedure only gets invoked if the new value differs from the current one (it's a caching scheme, for improving performance ✨), or if there's no initial value set in the options procedure for that option.

inside this procedure: if the initial value differs from the default value, or it's omitted entirely, then initial configuration is forced and the corresponding set-option procedure gets invoked by the switched complete procedure sitting at the end of the derived class constructor. for example:

class car {
    ...
    proc options {this} {
        return [list [list -fuel petrol] [list -length {} {}] [list -power 100 50] [list -width {} {}] ]
    }
    ...
}

in this case, configuration is forced on the fuel and power options — meaning the corresponding set-option procedures will be invoked when the switched object is constructed (check the set-option procedures documentation below for that).

for the fuel option, since there's no initial value, the set-fuel procedure is called with the default value (petrol) as its argument. for the power option, since the initial value differs from the default value, the set-power procedure is called with the initial value as its argument (50).

for the other options, since their initial values (the last elements of the option lists) are identical to their default values, the corresponding set-option procedures will not be invoked. and it's the programmer's responsibility to insure that the initial option values are correct, so like... no pressure bestie 😭

💜 <switched> set-option this value 💜

these procedures can be thought of as dynamic virtual functions. there must be one implementation per supported option, as returned by the options procedure. for example:

class car {
    ...
    proc options {this} {
        return [list ...
            [list -width {} {}] ]
    }
    ...
    proc set-width {this value} {
        ...
    }
    ...
}

since the -width option was listed in the options procedure, a set-width procedure implementation is provided, which of course would proceed to set the width of the car (and would modify the looks of a graphical representation, for example 🎨).

as you add a supported option in the list returned by the options procedure, the corresponding set-option procedure may be called as soon as the switched object is complete — which happens when the switched level complete procedure is invoked. for example:

class car {
    proc car {this args} switched {args} {
        ...
        switched::complete $this
   }
    ...
    proc options {this} {
        return [list [list -fuel petrol] [list -length 4.5] [list -power 350] [list -width 1.8] ]
    }
    proc set-fuel {this value} {
        ...
    }
    proc set-length {this value} {
        ...
    }
    proc set-power {this value} {
        ...
    }
    proc set-width {this value} {
        ...
    }
}

new car

in this case, a new car is created with no options, which causes the car constructor to be called, which in turn calls the switched level complete procedure after the car object layer is completely initialized. at that point, since there are no initial values in any option list in the options procedure, the set-fuel procedure is called with its default value of petrol as parameter, followed by the set-length call with 4.5 value, set-power with 350 value and finally set-width with 1.8 as parameter. this is a great way to test the set-option procedures when debugging — and once you're done, just fill in the initial option values. 💅

the switched layer checks that an option is valid (meaning: listed in the options procedure) but obviously it does not check the validity of the value passed to the set-option procedure. that one should throw an error if the value is invalid (for example by using the Tcl error command).

the switched layer also keeps track of the options' current values, so a set-option procedure is called only when the corresponding option value passed as parameter differs from the current value (peep the -option data members description below 👇).

🍓 -option 🍓

the -option data member is an option's current value. there's one of these for each option listed in the options procedure. it's a read-only value which the switched layer checks against when an option is changed. it's rarely used at the layer derived from switched, except in a few cases, like in the following example:

...
proc car::options {this} {
    return {
        ...
        {-manufacturer {} {}}
        ...
    }
}

proc car::set-manufacturer {this value} {}

proc car::printData {this} {
    puts "manufacturer: $switched::($this,-manufacturer)"
    ...
}

in this case, the manufacturer's name is stored at the switched layer level (which is why the set-manufacturer procedure has nothing to do 😌) and later retrieved in the printData procedure.

⭐ complete ⭐

the complete data member (not to be confused with the complete procedure, bestie, they're different things) is a boolean. its initial value is false and it gets set to true at the very end of the switched complete procedure. it becomes useful when some options should be set at construction time only and not dynamically, as this example shows:

proc car::set-width {this value} {
    if {$switched::($this,complete)} {
        error {option -width cannot be set dynamically}
    }
    ...
}

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. 😭 please report such things in the category stooop of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also report any ideas for enhancements you may have for either the package and/or the documentation — they want to hear it fr fr.

when proposing code changes, please provide unified diffs, i.e the output of diff -u.

also note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. 🫶

---

🔥 KEYWORDS 🔥

• C++
• class
• object
• object oriented

---

👑 CATEGORY 👑

Programming tools

---

okay that's the whole page bestie, you ate that 🎀 this was switched(n) from tcllib, version 2.2.2 — go forth and configure some options, mwah 💅✨