clay(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

🎀 clay(n) — the Clay Framework 🎀

okay bestie, pull up a chair, we're reading a manual page together and honestly? it's giving main character energy. 💅

✨ NAME ✨

clay — a minimalist framework for large scale OO Projects 🫶

🌸 SYNOPSIS 🌸

package require Tcl 8.6 9

package require uuid

package require oo::dialect

proc clay::PROC name arglist body ?ninja ?

proc clay::_ancestors resultvar class

proc clay::ancestors ?args?

proc clay::args_to_dict ?args?

proc clay::args_to_options ?args?

proc clay::dynamic_arguments ensemble method arglist ?args?

proc clay::dynamic_wrongargs_message arglist

proc clay::is_dict d

proc clay::is_null value

proc clay::leaf ?args?

proc clay::K a b

proc clay::noop ?args?

proc clay::cleanup

proc clay::object_create objname ?class ?

proc clay::object_rename object newname

proc clay::object_destroy ?args?

proc clay::path ?args?

proc clay::putb ?map? text

proc clay::script_path

proc clay::NSNormalize qualname

proc clay::uuid_generate ?args?

proc clay::uuid::generate_tcl_machinfo

proc clay::uuid::tostring uuid

proc clay::uuid::fromstring uuid

proc clay::uuid::equal left right

proc clay::uuid cmd ?args?

proc clay::tree::sanitize dict

proc clay::tree::_sanitizeb path varname dict

proc clay::tree::storage rawpath

proc clay::tree::dictset varname ?args?

proc clay::tree::dictmerge varname ?args?

proc clay::tree::merge ?args?

proc dictargs::proc name argspec body

proc dictargs::method name argspec body

proc clay::dialect::Push class

proc clay::dialect::Peek

proc clay::dialect::Pop

proc clay::dialect::create name ?parent ?

proc clay::dialect::NSNormalize namespace qualname

proc clay::dialect::DefineThunk target ?args?

proc clay::dialect::Canonical namespace NSpace class

proc clay::dialect::Define namespace class ?args?

proc clay::dialect::Aliases namespace ?args?

proc clay::dialect::SuperClass namespace ?args?

proc clay::dynamic_methods class

proc clay::dynamic_methods_class thisclass

proc clay::define::Array name ?values ?

proc clay::define::Delegate name info

proc clay::define::constructor arglist rawbody

proc clay::define::Class_Method name arglist body

proc clay::define::class_method name arglist body

proc clay::define::clay ?args?

proc clay::define::destructor rawbody

proc clay::define::Dict name ?values ?

proc clay::define::Option name ?args?

proc clay::define::Method name argstyle argspec body

proc clay::define::Option_Class name ?args?

proc clay::define::Variable name ?default ?

proc clay::ensemble_methodbody ensemble einfo

proc clay::define::Ensemble rawmethod ?args?

proc clay::event::cancel self ?task *?

proc clay::event::generate self event ?args?

proc clay::event::nextid

proc clay::event::Notification_list self event ?stackvar ?

proc clay::event::notify rcpt sender event eventinfo

proc clay::event::process self handle script

proc clay::event::schedule self handle interval script

proc clay::event::subscribe self who event

proc clay::event::unsubscribe self ?args?

proc clay::singleton name script

method clay ancestors

method clay dump

method clay find path ?path...?

method clay get path ?path...?

method clay GET path ?path...?

method clay merge dict ?dict...?

method clay replace dictionary

method clay search path ?path...?

method clay set path ?path...? value

method clay ancestors

method clay cache path value

method clay cget field

method clay delegate ?stub? ?object?

method clay dump

method clay ensemble_map

method clay eval script

method clay evolve

method clay exists path ?path...?

method clay flush

method clay forward method object

method clay get path ?path...?

method clay leaf path ?path...?

method clay merge dict ?dict...?

method clay mixin class ?class...?

method clay mixinmap ?stub? ?classes?

method clay provenance path ?path...?

method clay replace dictionary

method clay search path valuevar isleafvar

method clay source filename

method clay set path ?path...? value

method InitializePublic

ngl that's a lot of entry points and every single one of them is getting covered, no skipping, periodt. 💀

💖 DESCRIPTION 💖

So here's the vibe. Clay introduces a method ensemble to both oo::class and oo::object, and that ensemble is called clay. It handles literally all of the high level interactions inside the framework. Clay stores structured data. Clan manages method delegation. Clay has facilities to manage the complex interactions that come about with mixins. (yes, Clan said hi, that's its whole cameo, moving on 🦋)

The central concept — the icon, the moment, the whole point — is that inside of every object and class (and bestie, classes are actually objects too, they're objects the whole time) there's a dict called clay. What you put in that dict? Left to your imagination, honestly. But because that dict is exposed via a public method, we can share structured data between object, classes, and mixins. slay. 💅

🌈 STRUCTURED DATA 🌈

Clay uses a standardized set of method interactions and introspection that TclOO already provides to do on-the-fly searches. On-the-fly searches mean the data is never stale, and we dodge soooo many of the sorts of collisions that would pop up when objects start mixing in other classes during operation. no cap.

The clay methods for both classes and objects have a get and a set method. For objects, get will search through the local clay dict. If the requested leaf is not found, or the query is for a branch, the system will then begin to poll the clay methods of all of the class that implements the object, all of that classes’ ancestors, as well as all of the classes that have been mixed into this object, and all of their ancestors. it's giving thorough.

Intended branches on a tree end with a directory slash (/). Intended leaves are left unadorned. This is a guide for the tool that builds the search results to know what parts of a dict are intended to be branches and which are intended to be leaves. For simple cases, branch marking can be ignored:

::oo::class create ::foo { }
::foo clay set property/ color blue
::foo clay set property/ shape round

set A [::foo new]
$A clay get property/
{color blue shape round}

$A clay set property/ shape square
$A clay get property/
{color blue shape square}

cute, right? but the second you start storing blocks of text, guessing what field is a dict and what isn’t gets messy:

::foo clay set description {A generic thing of designated color and shape}

$A clay get description
{A generic thing of designated color and shape}

Without a convention for discerning branches for leaves what should have been a value can be accidentally parsed as a dictionary, and merged with all of the other values that were never intended to be merge. Here is an example of it all going wrong:

::oo::class create ::foo { }
# Add description as a leaf
::foo clay set description  {A generic thing of designated color and shape}
# Add description as a branch
::foo clay set description/  {A generic thing of designated color and shape}

::oo::class create ::bar {
  superclass foo
}
# Add description as a leaf
::bar clay set description  {A drinking establishment of designated color and shape and size}
# Add description as a branch
::bar clay set description/  {A drinking establishment of designated color and shape and size}

set B [::bar new]
# As a leaf we get the value verbatim from he nearest ancestor
$B clay get description
  {A drinking establishment of designated color and shape and size}
# As a branch we get a recursive merge
$B clay get description/
{A drinking establishment of designated color and size thing of}

see that last line? that is the crime scene 😭 the merge ate the sentence and left confetti. mark your branches, bestie, that's the whole moral of the story.

🦋 CLAY DIALECT 🦋

Clay is built using the oo::dialect module from Tcllib. oo::dialect allows you to either add keywords directly to clay, or to create your own metaclass and keyword set using Clay as a foundation. For details on the keywords and what they do, consult the functions in the ::clay::define namespace. iykyk 👑

🎀 METHOD DELEGATION 🎀

Method Delegation. It is sometimes useful to have an external object that can be invoked as if it were a method of the object. Clay provides a delegate ensemble method to perform that delegation, as well as introspect which methods are delegated in that manner. All delegated methods are marked with html-like tag markings (< >) around them.

::clay::define counter {
  Variable counter 0
  method incr {{howmuch 1}} {
    my variable counter
    incr counter $howmuch
  }
  method value {} {
    my variable counter
    return $counter
  }
  method reset {} {
    my variable counter
    set counter 0
  }
}
::clay::define example {
  variable buffer
  constructor {} {
    # Build a counter object
    set obj [namespace current]::counter
    ::counter create $obj
    # Delegate the counter
    my delegate <counter> $obj
  }
  method line {text} {
    my <counter> incr
    append buffer $text
  }
}

set A [example new]
$A line {Who’s line is it anyway?}
$A <counter> value
1

the <counter> angle brackets are literally the vibe check that says "hey, this one's not mine, it's borrowed and it's iconic for it". 🫶

✨ COMMANDS ✨

proc clay::PROC name arglist body ?ninja ? — okay so bestie, because many features in this package might get added as commands to future tcl cores, or be provided in binary form by packages, she needs a declarative way of saying “create this command if there isn’t one already”. The ninja argument? That’s a script to execute if the command is created by this mechanism. 💅
proc clay::_ancestors resultvar class — no description in the original, she’s keeping it mysterious ✨
proc clay::ancestors ?args? — no description, just vibes 🦋
proc clay::args_to_dict ?args? — no description, lowkey iconic 🎀
proc clay::args_to_options ?args? — no description, she’s shy 🙈
proc clay::dynamic_arguments ensemble method arglist ?args? — no description, main character energy 👑
proc clay::dynamic_wrongargs_message arglist — no description, periodt 💅
proc clay::is_dict d — no description, fr fr 💖
proc clay::is_null value — no description, ngl 🌸
proc clay::leaf ?args? — no description, it’s giving mystery 🧚
proc clay::K a b — no description, iykyk 💜
proc clay::noop ?args? — Perform a noop. Super useful in prototyping for commenting out blocks of code without actually having to comment them out. It also makes a handy default for method delegation if a delegate hasn’t been assigned yet. 💅
proc clay::cleanup — Process the queue of objects to be destroyed. 🗑️
proc clay::object_create objname ?class ? — no description, she’s a mystery ✨
proc clay::object_rename object newname — no description, lowkey 🔥
proc clay::object_destroy ?args? — Mark an object for destruction on the next cleanup. 💀
proc clay::path ?args? — no description, iconic 🦋
proc clay::putb ?map? text — Append a line of text to a variable. Optionally apply a string mapping. 🌈
proc clay::script_path — no description, she’s quiet 🎀
proc clay::NSNormalize qualname — no description, periodt 💅
proc clay::uuid_generate ?args? — no description, fr fr 💖
proc clay::uuid::generate_tcl_machinfo — no description, ngl 🌸
proc clay::uuid::tostring uuid — no description, it’s giving ✨
proc clay::uuid::fromstring uuid — Convert a string representation of a uuid into its binary format. 🔄
proc clay::uuid::equal left right — Compare two uuids for equality. 💖
proc clay::uuid cmd ?args? — uuid generate -> string rep of a new uuid uuid equal uuid1 uuid2 — that’s the whole description, bestie 😭
proc clay::tree::sanitize dict — Output a dictionary removing any . entries added by clay::tree::merge. 🧹
proc clay::tree::_sanitizeb path varname dict — Helper function for ::clay::tree::sanitize. Formats the string representation for a dictionary element within a human readable stream of lines, and determines if it needs to call itself with further indentation to express a sub-branch. 🌳
proc clay::tree::storage rawpath — Return the path as a storage path for clay::tree with all branch terminators removed. This command will also break arguments up if they contain /.

Example:

> clay::tree::storage {foo bar baz bang}
foo bar baz bang
> clay::tree::storage {foo bar baz bang/}
foo bar baz bang
> clay::tree::storage {foo bar baz bang:}
foo bar baz bang:
> clay::tree::storage {foo/bar/baz bang:}
foo bar baz bang:
> clay::tree::storage {foo/bar/baz/bang}
foo bar baz bang

proc clay::tree::dictset varname ?args? — Set an element with a recursive dictionary, marking all branches on the way down to the final element. If the value does not exist in the nested dictionary it is added as a leaf. If the value already exists as a branch the value given is merged if the value is a valid dict. If the incoming value is not a valid dict, the value overrides the value stored, and the value is treated as a leaf from then on.

Example:

> set r {}
> ::clay::tree::dictset r option color default Green
. {} option {. {} color {. {} default Green}}
> ::clay::tree::dictset r option {Something not dictlike}
. {} option {Something not dictlike}
# Note that if the value is not a dict, and you try to force it to be
# an error with be thrown on the merge
> ::clay::tree::dictset r option color default Blue
missing value to go with key

proc clay::tree::dictmerge varname ?args? — A recursive form of dict merge, intended for modifying variables in place.

Example:

> set mydict {sub/ {sub/ {description {a block of text}}}}
> ::clay::tree::dictmerge mydict {sub/ {sub/ {field {another block of text}}}}]
> clay::tree::print $mydict
sub/ {
  sub/ {
    description {a block of text}
    field {another block of text}
  }
}

proc clay::tree::merge ?args? — A recursive form of dict merge.

A routine to recursively dig through dicts and merge adapted from http://stevehavelka.com/tcl-dict-operation-nested-merge/.

Example:

> set mydict {sub/ {sub/ {description {a block of text}}}}
> set odict [clay::tree::merge $mydict {sub/ {sub/ {field {another block of text}}}}]
> clay::tree::print $odict
sub/ {
  sub/ {
    description {a block of text}
    field {another block of text}
  }
}

proc dictargs::proc name argspec body — Named Procedures as new command. ✨
proc dictargs::method name argspec body — no description, just vibes 🦋
proc clay::dialect::Push class — no description, she’s keeping it lowkey 🙈
proc clay::dialect::Peek — no description, iconic 🎀
proc clay::dialect::Pop — no description, periodt 💅
proc clay::dialect::create name ?parent ? — This proc will generate a namespace, a “mother of all classes”, and a rudimentary set of policies for this dialect. 👑
proc clay::dialect::NSNormalize namespace qualname — Support commands; not intended to be called directly. 🙈
proc clay::dialect::DefineThunk target ?args? — no description, fr fr 💖
proc clay::dialect::Canonical namespace NSpace class — no description, ngl 🌸
proc clay::dialect::Define namespace class ?args? — Implementation of the language’s define command. 💅
proc clay::dialect::Aliases namespace ?args? — no description, it’s giving mystery 🧚
proc clay::dialect::SuperClass namespace ?args? — no description, iykyk 💜
proc clay::dynamic_methods class — no description, main character energy 👑
proc clay::dynamic_methods_class thisclass — no description, lowkey 🔥
proc clay::define::Array name ?values ? — New OO Keywords for clay. 🌈
proc clay::define::Delegate name info — An annotation that objects of this class interact with delegated methods. The annotation is intended to be a dictionary, and the only reserved key is description, a human readable description. 🦋
proc clay::define::constructor arglist rawbody — no description, she’s shy 🎀
proc clay::define::Class_Method name arglist body — Specify a method for the class object itself, instead of for objects of the class. 💅
proc clay::define::class_method name arglist body — An alias to the new Class_Method keyword. ✨
proc clay::define::clay ?args? — no description, periodt 💅
proc clay::define::destructor rawbody — no description, fr fr 💖
proc clay::define::Dict name ?values ? — no description, ngl 🌸
proc clay::define::Option name ?args? — Define an option for the class. 🎀
proc clay::define::Method name argstyle argspec body — no description, it’s giving ✨
proc clay::define::Option_Class name ?args? — Define a class of options. All field / value pairs will be inherited by an option that specifies name as its class field. 👑
proc clay::define::Variable name ?default ? — This keyword can also be expressed: property variable NAME {default DEFAULT}.

Variables registered in the variable property are also initialized (if missing) when the object changes class via the morph method. 🌱

proc clay::ensemble_methodbody ensemble einfo — Produce the body of an ensemble’s public dispatch method. ensemble is the name of the ensemble. einfo is a dictionary of methods for the ensemble, and each value is a script to execute on dispatch.

Example:

::clay::ensemble_methodbody foo {
  bar {tailcall my Foo_bar {*}$args}
  baz {tailcall my Foo_baz {*}$args}
  clock {return [clock seconds]}
  default {puts "You gave me $method"}
}

proc clay::define::Ensemble rawmethod ?args? — no description, lowkey 🔥
proc clay::event::cancel self ?task *? — Cancel a scheduled event. ❌
proc clay::event::generate self event ?args? — Generate an event. Adds a subscription mechanism for objects to see who has received this event and prevent spamming or infinite recursion. 🔔
proc clay::event::nextid — no description, she’s mysterious ✨
proc clay::event::Notification_list self event ?stackvar ? — Called recursively to produce a list of who receives notifications. 📋
proc clay::event::notify rcpt sender event eventinfo — Final delivery to intended recipient object. 📬
proc clay::event::process self handle script — Evaluate an event script in the global namespace. 🌍
proc clay::event::schedule self handle interval script — Schedule an event to occur later. ⏰
proc clay::event::subscribe self who event — Subscribe an object to an event pattern. 💖
proc clay::event::unsubscribe self ?args? — Unsubscribe an object from an event pattern. 💔
proc clay::singleton name script — An object which is intended to be its own class. 👑

💖 CLASSES 💖

Okay bestie, this is where the clay system gets its classy little structure. Let’s go. ✨

🌸 CLASS `CLAY::CLASS` 🌸

✨ Methods ✨

method clay ancestors — Returns this class and all ancestors in search order. 💫
method clay dump — Returns a complete dump of this object's clay data, but only this object's clay data. No ancestor spillover, periodt. 🫶
method clay find path ?path...? — Pull a chunk of data from the clay system. If the last element of path is a branch, returns a recursive merge of all data from this object and its constituent classes of the data in that branch. If the last element is a leaf, search this object for a matching leaf, or search all constituent classes for a matching leaf and return the first value found. If no value is found, returns an empty string. If a branch is returned the topmost . entry is omitted. 🍃
method clay get path ?path...? — Pull a chunk of data from the class's clay system. If no value is found, returns an empty string. If a branch is returned the topmost . entry is omitted. 🌿
method clay GET path ?path...? — Pull a chunk of data from the class's clay system. If no value is found, returns an empty string. (Yes, uppercase GET — she’s different.) 💅
method clay merge dict ?dict...? — Recursively merge the dictionaries given into the object's local clay storage. 🧬
method clay replace dictionary — Replace the contents of the internal clay storage with the dictionary given. ♻️
method clay search path ?path...? — Return the first matching value for the path in either this class's clay data or one of its ancestors. 🕵️
method clay set path ?path...? value — Merge the contents of value with the object's clay storage at path. 🧩

🦋 CLASS `CLAY::OBJECT` 🦋

clay::object — this class is inherited by all classes that have options. 👑

✨ Methods ✨

method clay ancestors — Returns the class this object belongs to, all classes mixed into this object, and all ancestors of those classes in search order. 🌈
method clay cache path value — Store VALUE in such a way that a request in SEARCH for PATH will always return it until the cache is flushed. 🧊
method clay cget field — Pull a value from either the object's clay structure or one of its constituent classes that matches the field name. The order of search is:
1. The as a value in local dict variable config
2. The as a value in local dict variable clay
3. As a leaf in any ancestor as a root of the clay tree
4. As a leaf in any ancestor as const field
5. As a leaf in any ancestor as option field default
method clay delegate ?stub? ?object? — Introspect or control method delegation. With no arguments, the method returns a key/value list of stubs and objects. With just the stub argument, it returns the object (if any) attached to the stub. With a stub and an object, this command forwards all calls to the method stub to the object. 🎯
method clay dump — Returns a complete dump of this object's clay data, as well as the data from all constituent classes recursively blended in. 🌀
method clay ensemble_map — Returns a dictionary describing the method ensembles to be assembled for this object. 🗺️
method clay eval script — Evaluates a script in the namespace of this object. 📜
method clay evolve — Triggers the InitializePublic private method. 🚀
method clay exists path ?path...? — Returns 1 if path exists in either the object's clay data. Values greater than one indicate the element exists in one of the object's constituent classes. A value of zero indicates the path could not be found. 🔍
method clay flush — Wipe any caches built by the clay implementation. 🧹
method clay forward method object — A convenience wrapper for:

oo::objdefine [self] forward {*}$args

method clay get path ?path...? — Pull a chunk of data from the clay system. If the last element of path is a branch (ends in a slash /), returns a recursive merge of all data from this object and its constituent classes of the data in that branch. If the last element is a leaf, search this object for a matching leaf, or search all constituent classes for a matching leaf and return the first value found. If no value is found, returns an empty string. 🍃
method clay leaf path ?path...? — A modified get which is tailored to pull only leaf elements. 🍂
method clay merge dict ?dict...? — Recursively merge the dictionaries given into the object's local clay storage. 🧬
method clay mixin class ?class...? — Perform [oo::objdefine [self] mixin] on this object, with a few additional rules: Prior to the call, for any class previously mixed in, but not in the new result, execute the script registered to mixin/ unmap-script (if given.) For all new classes that were not present prior to this call, after the native TclOO mixin is invoked, execute the script registered to mixin/ map-script (if given.) Fall all classes that are now present and “mixed in”, execute the script registered to mixin/ react-script (if given.) 🎭
method clay mixinmap ?stub? ?classes? — With no arguments returns the map of stubs and classes mixed into the current object. When only stub is given, returns the classes mixed in on that stub. When stub and classlist given, replace the classes currently on that stub with the given classes and invoke clay mixin on the new matrix of mixed in classes. 🗺️
method clay provenance path ?path...? — Return either self if that path exists in the current object, or return the first class (if any) along the clay search path which contains that element. 🕵️
method clay replace dictionary — Replace the contents of the internal clay storage with the dictionary given. ♻️
method clay search path valuevar isleafvar — Return true, and set valuevar to the value and isleafar to true for false if PATH was found in the cache. 🎯
method clay source filename — Source the given filename within the object's namespace. 📜
method clay set path ?path...? value — Merge the contents of value with the object's clay storage at path. 🧩
method InitializePublic — Instantiate variables. Called on object creation and during clay mixin. 🌱

💌 AUTHORS 💌

Sean Woods — mailto:<yoda@etoyoc.com> 🫶

🐛 BUGS, IDEAS, FEEDBACK 🐛

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category oo of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. 🙈

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

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 🔑

TclOO, oo 👑

🏷️ CATEGORY 🏷️

Programming tools 🛠️

That's the tea from tcllib 0.8.8, clay(n) 💅✨

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

clay(n)

🎀 clay(n) — the Clay Framework 🎀

✨ NAME ✨

🌸 SYNOPSIS 🌸

💖 DESCRIPTION 💖

🌈 STRUCTURED DATA 🌈

🦋 CLAY DIALECT 🦋

🎀 METHOD DELEGATION 🎀

✨ COMMANDS ✨

💖 CLASSES 💖

🌸 CLASS CLAY::CLASS 🌸

✨ Methods ✨

🦋 CLASS CLAY::OBJECT 🦋

✨ Methods ✨

💌 AUTHORS 💌

🐛 BUGS, IDEAS, FEEDBACK 🐛

🔑 KEYWORDS 🔑

🏷️ CATEGORY 🏷️

©️ COPYRIGHT ©️

🌸 CLASS `CLAY::CLASS` 🌸

🦋 CLASS `CLAY::OBJECT` 🦋