configurable(3tcl)

🎀 configurable(3tcl) — TclOO Commands 🎀

hey bestie! welcome to the configurable(3tcl) manual page, part 1 of 2. this is giving major TclOO energy, and we're gonna break it down so it's actually slay. 💅

✨ NAME ✨

oo::configurable, configure, property — A class that makes configurable classes and objects, and supports making configurable properties 💖

🌸 SYNOPSIS 🌸

package require TclOO

oo::configurable create class ?definitionScript?

oo::define class {
    property propName ?options...? ?propName ?options...?...?
}

oo::objdefine object {
    property propName ?options...? ?propName ?options...?...?
}

objectName configure
objectName configure -prop
objectName configure -prop value ?-prop value...

👑 CLASS HIERARCHY 👑

oo::object
   → oo::class
       → oo::configurable

oo::object
   → oo::class
       → oo::configurablesupport::configurable

💖 DESCRIPTION 💖

Configurable objects are objects that are literally built to be configured with a configure method. Every configurable thing on the object is known as a property of the object. Properties can be defined on classes or instances; when you're configuring an object, any of the properties defined by its classes (direct or indirect) or by the instance itself can be configured. ✨

The oo::configurable metaclass installs basic support for making configurable objects into a class. This means it makes a property definition command available in definition scripts for the class and instances (like from the class's constructor, within oo::define, and within oo::objdefine) and makes a configure method available within the instances. 🫶

🔧 CONFIGURE METHOD 🔧

The behavior of the configure method is modelled after the fconfigure/chan configure command. No cap.

• If you pass no additional arguments, the configure method returns an alphabetically sorted dictionary of all readable and read-write properties and their current values. 💅
• If you pass a single additional argument, that argument to the configure method must be the name of a property to read (or an unambiguous prefix thereof); its value is returned. 👑
• Otherwise, if you pass an even number of arguments, then each pair of arguments specifies a property name (or an unambiguous prefix thereof) and the value to set it to. The properties will be set in the order specified, including duplicates. If the setting of any property fails, the overall configure method fails, the preceding pairs (if any) will continue to have been applied, and the succeeding pairs (if any) will be not applied. On success, the result of the configure method in this mode operation will be an empty string. 😭

🎀 PROPERTY DEFINITIONS 🎀

When a class has been manufactured by the oo::configurable metaclass (or one of its subclasses), it gains an extra definition, property. The property definition defines one or more properties that will be exposed by the class's instances. 🌸

The property command takes the name of a property to define first, without a leading hyphen, followed by a number of option-value pairs that modify the basic behavior of the property. This can then be followed by an arbitrary number of other property definitions. The supported options are:

• -get getterScript — This defines the implementation of how to read from the property; the getterScript will become the body of a method (taking no arguments) defined on the class, if the kind of the property is such that the property can be read from. The method will be named <ReadProp-propertyName>, and will default to being a simple read of the instance variable with the same name as the property (e.g., property xyz will result in a method <ReadProp-xyz> being created). 🔍
• -kind propertyKind — This defines what sort of property is being created. The propertyKind must be exactly one of readable, writable, or readwrite (which is the default) which will make the property read-only, write-only or read-write, respectively. Read-only properties can only ever be read from, write-only properties can only ever be written to, and read-write properties can be both read and written. 💖

Note that write-only properties are not particularly discoverable as they are never reported by the configure method other than by error messages when attempting to write to a property that does not exist. 💀

• -set setterScript — This defines the implementation of how to write to the property; the setterScript will become the body of a method taking a single argument, value, defined on the class, if the kind of the property is such that the property can be written to. The method will be named <WriteProp-propertyName>, and will default to being a simple write of the instance variable with the same name as the property (e.g., property xyz will result in a method <WriteProp-xyz> being created). ✍️

Instances of the class that was created by oo::configurable will also support property definitions; the semantics will be exactly as above except that the properties will be defined on the instance alone. 🦋

Note that the property implementation methods that property defines should not be private, as this makes them inaccessible from the implementation of configure (by design; the property configuration mechanism is intended for use mainly from outside a class, whereas a class may access variables directly). The variables accessed by the default implementations of the properties may be private, if so declared. 🙈

🧚 ADVANCED USAGE 🧚

The configurable class system is comprised of several pieces. The oo::configurable metaclass works by mixing in a class and setting definition namespaces during object creation that provide the other bits and pieces of machinery. The key pieces of the implementation are enumerated here so that they can be used by other code:

• oo::configuresupport::configurable — This is a class that provides the implementation of the configure method (described above in CONFIGURE METHOD). 🔧
• oo::configuresupport::configurableclass — This is a namespace that contains the definition dialect that provides the property declaration for use in classes (i.e., via oo::define, and class constructors under normal circumstances), as described above in PROPERTY DEFINITIONS. It namespace exports its property command so that it may be used easily in user definition dialects. 📦
• oo::configuresupport::configurableobject — This is a namespace that contains the definition dialect that provides the property declaration for use in instance objects (i.e., via oo::objdefine, and the self declaration in oo::define), as described above in PROPERTY DEFINITIONS. It namespace exports its property command so that it may be used easily in user definition dialects. 🎁

The underlying property discovery mechanism relies on four slots (see oo::define for what that implies) that list the properties that can be configured. These slots do not themselves impose any semantics on what the slots mean other than that they have unique names, no important order, can be inherited and discovered on classes and instances. 🗂️

These slots, and their intended semantics, are:

• oo::configuresupport::readableproperties — The set of properties of a class (not including those from its superclasses) that may be read from when configuring an instance of the class. This slot can also be read with the info class properties command. 📖
• oo::configuresupport::writableproperties — The set of properties of a class (not including those from its superclasses) that may be written to when configuring an instance of the class. This slot can also be read with the info class properties command. ✏️
• oo::configuresupport::objreadableproperties — The set of properties of an object instance (not including those from its classes) that may be read from when configuring the object. This slot can also be read with the info object properties command. 🔍
• oo::configuresupport::objwritableproperties — The set of properties of an object instance (not including those from its classes) that may be written to when configuring the object. This slot can also be read with the info object properties command. ✍️

Note that though these are slots, they are not in the standard oo::define or oo::objdefine namespaces; in order to use them inside a definition script, they need to be referred to by full name. This is because they are intended to be building bricks of configurable property system, and not directly used by normal user code. 🧱

💡 IMPLEMENTATION NOTE 💡

The implementation of the configure method uses info object properties with the -all option to discover what properties it may manipulate. 👀

🌸 EXAMPLES 🌸

okay bestie, this is the fun part — let's build a whole configurable class from scratch and watch it cook. 💅

First, a simple configurable class, so you can see how it gets configured:

oo::configurable create Point {
    property x y
    constructor args {
        my configure -x 0 -y 0 {*}$args
    }
    variable x y
    method print {} {
        puts "x=$x, y=$y"
    }
}

set pt [Point new -x 27]
$pt print;   # x=27, y=0
$pt configure -y 42
$pt print;   # x=27, y=42
puts "distance from origin: [expr {
    hypot([$pt configure -x], [$pt configure -y])
}]";         # distance from origin: 49.92995093127971
puts [$pt configure]
             # -x 27 -y 42

look at her go 🥹 we made x default to 27 on construction, then slid -y 42 in afterwards, and then — icon behaviour only — read the values back out by just calling configure -x with no value at all. and puts [$pt configure]? that dumps every option. obsessed.

---

Such a configurable class can be extended by subclassing, but heads up 🫶 — the subclass also needs to be created by oo::configurable if it's gonna use the property definition:

oo::configurable create Point3D {
    superclass Point
    property z
    constructor args {
        next -z 0 {*}$args
    }
}

set pt2 [Point3D new -x 2 -y 3 -z 4]
puts [$pt2 configure]
             # -x 2 -y 3 -z 4

so Point3D says superclass Point, adds a property z, and its constructor does next -z 0 {*}$args — meaning it hands off to the parent constructor and passes along a default z of 0 unless you gave it one. then we spawn one with all three coords and print the config. slay. ✨

---

Once you've got a configurable class, you can also add instance properties to it. (fun fact: the backing variables for all properties start out unset — no sneaky defaults hiding in there.) and peep this: below we set a property using an unambiguous prefix of its name. that's supported for all properties 🎀, BUT full names are normally recommended, because that way subclasses won't ever make an unambiguous prefix become ambiguous. iykyk.

oo::objdefine $pt {
    property color
}
$pt configure -c bisque
puts [$pt configure]
             # -color bisque -x 27 -y 42

-c ate and left no crumbs — it found -color no problem. 🍓

---

You can also do derived properties by making them read-only and supplying a script that computes them:

oo::configurable create PointMk2 {
    property x y
    property distance -kind readable -get {
        return [expr {hypot($x, $y)}]
    }
    variable x y
    constructor args {
        my configure -x 0 -y 0 {*}$args
    }
}

set pt3 [PointMk2 new -x 3 -y 4]
puts [$pt3 configure -distance]
             # 5.0
$pt3 configure -distance 10
             # ERROR: bad property "-distance": must be -x or -y

distance is -kind readable with a -get script that runs hypot($x, $y) — so it's calculated, never stored. 💖 and the second it tries to set it? nope, -distance isn't settable, so you get an error telling you it must be -x or -y. it's giving read-only main character energy. 👑

---

Setters are how you validate the type of a property, and honestly they're so satisfying:

oo::configurable create PointMk3 {
    property x -set {
        if {![string is double -strict $value]} {
            error "-x property must be a number"
        }
        set x $value
    }
    property y -set {
        if {![string is double -strict $value]} {
            error "-y property must be a number"
        }
        set y $value
    }
    variable x y
    constructor args {
        my configure -x 0 -y 0 {*}$args
    }
}

set pt4 [PointMk3 new]
puts [$pt4 configure]
             # -x 0 -y 0
$pt4 configure -x 3 -y 4
puts [$pt4 configure]
             # -x 3 -y 4
$pt4 configure -x "obviously not a number"
             # ERROR: -x property must be a number

each -set script checks [string is double -strict $value] and, if it fails, throws error with a lil message — otherwise it stores the value with set x $value / set y $value. so -x 3 -y 4? cute, accepted. -x "obviously not a number"? absolutely not, blocked at the door with ERROR: -x property must be a number. no cap, that's the whole point of a setter. 💀🙈

---

💜 SEE ALSO 💜

• info(3tcl), oo::class(3tcl), oo::define(3tcl)

🌈 KEYWORDS 🌈

• class, object, properties, configuration

---

and that's a wrap, babe 🫶 this lil page comes from the TclOO docs, version 0.4, and it's the configurable(3tcl) man page — the date slot in this copy was left blank, so just picture me tapping my lil watch ✨ keep it configurable, keep it cunty, periodt. 💅🎀