tool(n)

💖 tool(n) 💖

okay bestie, so this is the manual page for tool — the TclOO Library (TOOL) Framework, living in section n of the manual. no cap, it's a whole vibe. let's get into it ✨

---

🦋 SYNOPSIS 🦋

package require Tcl 8.6 9

package require sha1

package require dicttool

package require oo::meta

package require oo::dialect

tool::define class_method arglist body

tool::define array name contents

tool::define array_ensemble methodname varname ?cases?

tool::define dict_ensemble methodname varname ?cases?

tool::define method methodname arglist body

tool::define option name dictopts

tool::define property ?branch? field value

tool::define variable name value

object cget option

object configure ?keyvaluelist?

object configure field value ?field? ?value? ?...?

object configurelist ?keyvaluelist?

object forward stub forward

object graft stub forward

object InitializePublic

object Eval_Script ?script?

object Option_Default field

---

🌸 DESCRIPTION 🌸

So this module is literally the whole Tcl Object Oriented Library framework, aka TOOL. It's giving general purpose framework energy — you can use it all on its own, and it's super easy to extend. main character behaviour fr fr 💅

TOOL defines a metaclass that hands a bunch of extra keywords to the TclOO description language, plus default behaviors for the objects that make it up, plus top-down integration with everything the oo::meta package brings to the table.

The TOOL metaclass was built with the oo::dialect package, so bestie, you can use it as the base for even more metaclasses. As a metaclass, TOOL has its own "class" class, "object" class, and define namespace. iconic.

package require tool

# tool::class workds just like oo::class
tool::class create myclass {
}

# tool::define works just like oo::define
tool::define myclass method noop {} {}

# tool::define and tool::class understand additional keywords
tool::define myclass array_ensemble mysettings mysettings {}

# And tool interoperates with oo::define
oo::define myclass method do_something {} { return something }

# TOOL and TclOO objects are interchangeable
oo::class create myooclass {
  superclass myclass
}

There are several manual pages that go way deeper on specific keywords and methods, so go read those too 🫶

• tool::array_ensemble
• tool::dict_ensemble
• tool::method_ensemble
• tool::object
• tool::option_handling

---

👑 KEYWORDS 👑

TOOL adds new keywords (and also modifies some existing ones) that you use when defining classes. BUT — huge caveat — these new keywords are only available through calls to tool::class create or tool::define. no shortcuts, bestie.

• tool::define class_method arglist body — Defines a method for the class object itself. This method gets passed on down to descendents of the class, which is not how self method behaves. different vibe entirely.
• tool::define array name contents — Declares a variable name that gets initialized as an array, populated with contents, for objects of this class and for any objects of classes that descend from this class. the family tree eats 💖
• tool::define array_ensemble methodname varname ?cases? — Declares a method ensemble methodname that controls access to variable varname. The cases are a key/value list of method names and bodies that get overlaid on top of the standard template. Peep tool::array_ensemble for more.

One method name is reserved: initialize. initialize declares the initial values to be populated in the array, as a key/value list, and it will not be expressed as a method for the ensemble.

• tool::define dict_ensemble methodname varname ?cases? — Declares a method ensemble methodname that controls access to variable varname. The cases are a key/value list of method names and bodies that get overlaid on top of the standard template. Peep tool::dict_ensemble for more.

One method name is reserved: initialize. initialize declares the initial values to be populated in the array, as a key/value list, and it will not be expressed as a method for the ensemble.

• tool::define method methodname arglist body — If methodname contains ::, the method is treated as part of a method ensemble. See tool::method_ensembles. Otherwise this command behaves exactly like the standard oo::define method command. literally identical.
• tool::define option name dictopts — Declares an option. dictopts is a key/value list defining the parameters for the option. See tool::option_handling.

tool::class create myclass {
  option color {
    post-command: {puts [list %self%'s %field% is now %value%]}
    default: green
  }
}
myclass create foo
foo configure color purple
> foo's color is now purple

• tool::define property ?branch? field value — Defines a new leaf in the class metadata tree 🌳. With no branch, the leaf shows up in the const section, reachable either by the object's property method, or via oo::meta::info class get const field.
• tool::define variable name value — Declares a variable name that gets initialized with the value value for objects of this class, and for any objects of classes that descend from this class. 💫

---

✨ PUBLIC OBJECT METHODS ✨

The TOOL object mother of all classes defines several methods to enforce consistent behavior all throughout the framework. she's the blueprint, the moment, the standard 💅

• object cget option — Returns the value of this object's option option. If the property options_strict is true for this class, calling an option that was not declared by the option keyword will throw an error 💀. In all other cases, if the value is present in the object's options array, that value is returned. If it doesn't exist, the object will try to retrieve a property of the same name.
• object configure ?keyvaluelist?
• object configure field value ?field? ?value? ?...? — This command injects new values into the object's options array, following the rules laid out by the option descriptions. See tool::option_handling for the details. configure will strip leading -'s off of field names, which lets it act in a quasi-backward compatible way to tk options. retro but make it cute 🎀
• object configurelist ?keyvaluelist? — This command injects new values into the object's options array, following the rules laid out by the option descriptions. This one performs validation and alternate storage rules. It will not invoke trigger rules. See tool::option_handling for the details.
• object forward stub forward — A passthrough to oo:objdefine [self] forward.
• object graft stub forward — Delegates the <stub> method to the object or command designated by forward.

tool::object create A
tool::object create B
A graft buddy B
A configure color red
B configure color blue
A cget color
> red
A <buddy> cget color
> blue

---

🙈 PRIVATE OBJECT METHODS 🙈

• object InitializePublic — Consults the metadata for the class to make sure every array, option, and variable that's been declared but not initialized gets initialized with the default value. This method is called by the constructor and the morph method. It's safe to invoke multiple times. no side effects, we love that 🫶
• object Eval_Script ?script? — Executes a block of text inside the namespace of the object. Lines that begin with a # are ignored as comments. Commands that begin with :: are interpreted as calling a global command. All other Tcl commands that lack a "my" prefix are given one, so the script can exercise internal methods. This method is meant for configuration scripts, where the object's methods are interpreting a domain specific language.

tool::class myclass {
  constructor script {
    my Eval_Script $script
  }
  method node {nodename info} {
    my variable node
    dict set node $nodename $info
  }
  method get {args} {
    my variable node
    return [dict get $node $args]
  }
}
myclass create movies {
  # This block of code is executed by the object
  node {The Day the Earth Stood Still} {
    date: 1952
    characters: {GORT Klatoo}
  }
}
movies get {The Day the Earth Stood Still} date:
> 1952

• object Option_Default field — Computes the default value for an option. See tool::option_handling.

---

🌈 AUTHORS 🌈

Sean Woods

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. Please report them in the category tcloo of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. Also please report any ideas for enhancements you might have for either the package and/or the documentation. we listen, bestie 🫶

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

Also note: attachments are strongly preferred over inlined patches. You can make attachments by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. iykyk.

---

⭐ KEYWORDS ⭐

TOOL, TclOO, framework

---

🎀 CATEGORY 🎀

TclOO

---

💜 COPYRIGHT 💜

Copyright (c) 2015 Sean Woods <yoda@etoyoc.com>

---

okay and that's the whole thing, periodt 💅 this was tcllib version 0.8, the tool(n) page — thanks for reading the whole thing bestie, you ate that 🍓✨