tool(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💅 NAME 💅

tool — the TclOO Library (TOOL) Framework ✨

okay so first things first, bestie: this is page tool(3tcl) from the tcllib crew, and it's about to change your whole object-oriented life 🫶

🌸 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 the Tcl Object Oriented Library framework, aka TOOL. It's giving general purpose framework energy — usable all on its own, and super easily extensible. no cap 💖

TOOL defines a metaclass that hands you a bunch of extra keywords for the TclOO description language, default behaviors for its constituent objects, and top-down integration with everything the oo::meta package brings to the table. it's giving ✨full stack✨

The TOOL metaclass was built with the oo::dialect package, which means it can be the basis for even more metaclasses. iconic behavior honestly 👑 As a metaclass, TOOL has its own "class" class, "object" class, and define namespace.

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
}

Several manual pages go way deeper on specific keywords and methods, so go read these if you're obsessed like me:

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

🔑 KEYWORDS 🔑

TOOL adds new keywords (and modifies some existing ones) that you use when you're defining classes. BUT — and this is the important bit, bestie — the new keywords are only available through calls to tool::class create or tool::define. that's the vibe check right there 🚨

  • 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 what happens with self method. slay 💅
  • 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. spreading the love fr fr 🌈
  • tool::define array_ensemble methodname varname ?cases? — Declares a method ensemble methodname that will control access to the variable varname. cases is a key/value list of method names and bodies that get overlaid on top of the standard template. See tool::array_ensemble.

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. so don't try it 💀

  • tool::define dict_ensemble methodname varname ?cases? — Declares a method ensemble methodname that will control access to the variable varname. cases is a key/value list of method names and bodies that get overlaid on top of the standard template. See tool::dict_ensemble.

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. same rule, no exceptions 🎀

  • tool::define method methodname arglist body — If methodname contains ::, the method is considered to be part of a method ensemble. See tool::method_ensembles. Otherwise this command behaves exactly like the standard oo::define method command. literally identical, periodt ✨
  • tool::define option name dictopts — Declares an option. dictopts is a key/value list defining parameters for the option. See tool::option_handling. check it:
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

see how it just works?? 🍓

  • 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, accessible by either 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, as well as for any objects of classes that descend from this class. inherited, as it should be 💜

👑 PUBLIC OBJECT METHODS 👑

The TOOL object — mother of all classes — defines several methods to enforce consistent behavior all throughout the framework. she's the main character, obviously 💅

  • object cget option — Return 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 attempt to retrieve a property of the same name. sneaky little fallback, we love her 🦋
  • object configure ?keyvaluelist?
  • object configure field value ?field? ?value? ?...? — This command injects new values into the object's options array, following the rules set forth by the option descriptions. See tool::option_handling for the details. configure will strip leading -s off of field names, which lets it behave in a quasi-backward compatible manner with tk options. throwback energy ngl 🙈
  • object configurelist ?keyvaluelist? — This command injects new values into the object's options array, following the rules set forth by the option descriptions. This command will perform validation and alternate storage rules. It will not invoke trigger rules. See tool::option_handling. so close yet so different, iykyk 😭
  • object forward stub forward — A passthrough to oo:objdefine [self] forward. low effort, high reward ✨
  • object graft stub forward — Delegates the <stub> method to the object or command designated by forward. watch this:
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

bestie-fication of objects. a whole buddy system 🔥

🙈 PRIVATE OBJECT METHODS 🙈

these are the behind-the-scenes girlies. don't touch unless you know what you're doing, fr fr 💀

  • 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 is safe to invoke multiple times. no double-init drama here 🎀
  • 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 intended for configuration scripts, where the object's methods are interpreting a domain specific language. it's giving DSL glow-up 💅
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

cinema. literally cinema. 🎬✨

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

💖 AUTHORS 💖

Sean Woods — legend behavior, honestly 👑

🚨 BUGS, IDEAS, FEEDBACK 🚨

This document, and the package it describes, will undoubtedly contain bugs and other problems. (real. they said it, not me 😭) Please report such in the category tcloo of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either the package and/or the documentation — they actually want your ideas bestie 🫶

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the love language of maintainers fr fr

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. do it that way, save everyone a headache 💖

🔑 KEYWORDS 🔑

TOOL, TclOO, framework

🌈 CATEGORY 🌈

TclOO

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

okay that's the whole page bestie, go build something iconic with it 💅✨

this was page tool(3tcl) from tcllib, version 0.8 — mwah, sending you off with all the TOOL energy 🎀🦋💖

📦 where this page comes from