Install Now
clay - A minimalist framework for large scale OO Projects
Contents
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 TcllibTrackers [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 unifieddiffs, 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.
Category
Programming tools
Classes
CLASSCLAY::CLASSMethods
method clayancestors
Return this class and all ancestors in search order.
method claydump
Return a complete dump of this object's clay data, but only this object's clay data.
method clayfindpath ?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 it's 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 claygetpath ?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 clayGETpath ?path...?
Pull a chunk of data from the class's clay system. If no value is found, returns an empty string.
method claymergedict ?dict...?
Recursively merge the dictionaries given into the object's local clay storage.
method clayreplacedictionary
Replace the contents of the internal clay storage with the dictionary given.
method claysearchpath ?path...?
Return the first matching value for the path in either this class's clay data or one of its
ancestors
method claysetpath ?path...? value
Merge the conents of value with the object's clay storage at path.
CLASSCLAY::OBJECT
clay::object This class is inherited by all classes that have options.
Methods
method clayancestors
Return the class this object belongs to, all classes mixed into this object, and all ancestors of
those classes in search order.
method claycachepathvalue
Store VALUE in such a way that request in SEARCH for PATH will always return it until the cache is
flushed
method claycgetfield
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 us:
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 constfield
5. As a leaf in any ancestor as optionfielddefault
method claydelegate ?stub? ?object?
Introspect or control method delegation. With no arguments, the method will return a key/value
list of stubs and objects. With just the stub argument, the method will return the object (if any)
attached to the stub. With a stub and an object this command will forward all calls to the method
stub to the object.
method claydump
Return a complete dump of this object's clay data, as well as the data from all constituent
classes recursively blended in.
method clayensemble_map
Return a dictionary describing the method ensembles to be assembled for this object
method clayevalscript
Evaluated a script in the namespace of this object
method clayevolve
Trigger the InitializePublic private method
method clayexistspath ?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 clayflush
Wipe any caches built by the clay implementation
method clayforwardmethodobject
A convenience wrapper for
oo::objdefine [self] forward {*}$args
method claygetpath ?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 it's 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 clayleafpath ?path...?
A modified get which is tailored to pull only leaf elements
method claymergedict ?dict...?
Recursively merge the dictionaries given into the object's local clay storage.
method claymixinclass ?class...?
Perform [oo::objdefine [self] mixin] on this object, with a few additional rules: Prior to the
call, for any class was 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 claymixinmap ?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 clayprovenancepath ?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 clayreplacedictionary
Replace the contents of the internal clay storage with the dictionary given.
method claysearchpathvaluevarisleafvar
Return true, and set valuevar to the value and isleafar to true for false if PATH was found in the
cache.
method claysourcefilename
Source the given filename within the object's namespace
method claysetpath ?path...? value
Merge the conents of value with the object's clay storage at path.
method InitializePublic
Instantiate variables. Called on object creation and during clay mixin.
Commands
proc clay::PROCnamearglistbody ?ninja ?
Because many features in this package may be added as commands to future tcl cores, or be provided
in binary form by packages, I need a declaritive way of saying Createthiscommandifthereisn'tonealready. The ninja argument is a script to execute if the command is created by this
mechanism.
proc clay::_ancestorsresultvarclass
proc clay::ancestors ?args?
proc clay::args_to_dict ?args?
proc clay::args_to_options ?args?
proc clay::dynamic_argumentsensemblemethodarglist ?args?
proc clay::dynamic_wrongargs_messagearglist
proc clay::is_dictd
proc clay::is_nullvalue
proc clay::leaf ?args?
proc clay::Kab
proc clay::noop ?args?
Perform a noop. 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 has not been
assigned yet.
proc clay::cleanup
Process the queue of objects to be destroyed
proc clay::object_createobjname ?class ?
proc clay::object_renameobjectnewname
proc clay::object_destroy ?args?
Mark an objects for destruction on the next cleanup
proc clay::path ?args?
proc clay::putb ?map? text
Append a line of text to a variable. Optionally apply a string mapping.
proc clay::script_path
proc clay::NSNormalizequalname
proc clay::uuid_generate ?args?
proc clay::uuid::generate_tcl_machinfo
proc clay::uuid::tostringuuid
proc clay::uuid::fromstringuuid
Convert a string representation of a uuid into its binary format.
proc clay::uuid::equalleftright
Compare two uuids for equality.
proc clay::uuidcmd ?args?
uuid generate -> string rep of a new uuid uuid equal uuid1 uuid2
proc clay::tree::sanitizedict
Output a dictionary removing any . entries added by clay::tree::merge
proc clay::tree::_sanitizebpathvarnamedict
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::storagerawpath
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::dictsetvarname ?args?
Set an element with a recursive dictionary, marking all branches on the way down to the final
element. If the value does not exists 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::dictmergevarname ?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::procnameargspecbody
Named Procedures as new command
proc dictargs::methodnameargspecbody
proc clay::dialect::Pushclass
proc clay::dialect::Peek
proc clay::dialect::Pop
proc clay::dialect::createname ?parent ?
This proc will generate a namespace, a "mother of all classes", and a rudimentary set of policies
for this dialect.
proc clay::dialect::NSNormalizenamespacequalname
Support commands; not intended to be called directly.
proc clay::dialect::DefineThunktarget ?args?
proc clay::dialect::CanonicalnamespaceNSpaceclass
proc clay::dialect::Definenamespaceclass ?args?
Implementation of the languages' define command
proc clay::dialect::Aliasesnamespace ?args?
proc clay::dialect::SuperClassnamespace ?args?
proc clay::dynamic_methodsclass
proc clay::dynamic_methods_classthisclass
proc clay::define::Arrayname ?values ?
New OO Keywords for clay
proc clay::define::Delegatenameinfo
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::constructorarglistrawbody
proc clay::define::Class_Methodnamearglistbody
Specify the a method for the class object itself, instead of for objects of the class
proc clay::define::class_methodnamearglistbody
And alias to the new Class_Method keyword
proc clay::define::clay ?args?
proc clay::define::destructorrawbody
proc clay::define::Dictname ?values ?
proc clay::define::Optionname ?args?
Define an option for the class
proc clay::define::Methodnameargstyleargspecbody
proc clay::define::Option_Classname ?args?
Define a class of options All field / value pairs will be be inherited by an option that specify
name as it class field.
proc clay::define::Variablename ?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_methodbodyensembleeinfo
Produce the body of an ensemble's public dispatch method ensemble is the name of the 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::Ensemblerawmethod ?args?
proc clay::event::cancelself ?task*?
Cancel a scheduled event
proc clay::event::generateselfevent ?args?
Generate an event Adds a subscription mechanism for objects to see who has recieved this event and
prevent spamming or infinite recursion
proc clay::event::nextid
proc clay::event::Notification_listselfevent ?stackvar ?
Called recursively to produce a list of who recieves notifications
proc clay::event::notifyrcptsendereventeventinfo
Final delivery to intended recipient object
proc clay::event::processselfhandlescript
Evaluate an event script in the global namespace
proc clay::event::scheduleselfhandleintervalscript
Schedule an event to occur later
proc clay::event::subscribeselfwhoevent
Subscribe an object to an event pattern
proc clay::event::unsubscribeself ?args?
Unsubscribe an object from an event pattern
proc clay::singletonnamescript
An object which is intended to be it's own class.
Copyright
Copyright (c) 2018 Sean Woods <yoda@etoyoc.com>
tcllib 0.8.8 clay(3tcl)
Description
Clay introduces a method ensemble to both oo::class and oo::object called clay. This ensemble handles all
of the high level interactions within the framework. Clay stores structured data. Clan manages method
delegation. Clay has facilities to manage the complex interactions that come about with mixins.
The central concept is that inside of every object and class (which are actually objects too) is a dict
called clay. What is stored in that dict is left to the imagination. But because this dict is exposed via
a public method, we can share structured data between object, classes, and mixins.
STRUCTUREDDATA
Clay uses a standardized set of method interactions and introspection that TclOO already provides to
perform on-the-fly searches. On-the-fly searches mean that the data is never stale, and we avoid many of
the sorts of collisions that would arise when objects start mixing in other classes during operation.
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.
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}
But when 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}
CLAYDIALECT
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.
METHODDELEGATION
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
Keywords
TclOO, oo
Name
clay - A minimalist framework for large scale OO Projects
Synopsis
package require Tcl8.69
package require uuid
package require oo::dialect
proc clay::PROCnamearglistbody ?ninja ?
proc clay::_ancestorsresultvarclass
proc clay::ancestors ?args?
proc clay::args_to_dict ?args?
proc clay::args_to_options ?args?
proc clay::dynamic_argumentsensemblemethodarglist ?args?
proc clay::dynamic_wrongargs_messagearglist
proc clay::is_dictd
proc clay::is_nullvalue
proc clay::leaf ?args?
proc clay::Kab
proc clay::noop ?args?
proc clay::cleanup
proc clay::object_createobjname ?class ?
proc clay::object_renameobjectnewname
proc clay::object_destroy ?args?
proc clay::path ?args?
proc clay::putb ?map? text
proc clay::script_path
proc clay::NSNormalizequalname
proc clay::uuid_generate ?args?
proc clay::uuid::generate_tcl_machinfo
proc clay::uuid::tostringuuid
proc clay::uuid::fromstringuuid
proc clay::uuid::equalleftright
proc clay::uuidcmd ?args?
proc clay::tree::sanitizedict
proc clay::tree::_sanitizebpathvarnamedict
proc clay::tree::storagerawpath
proc clay::tree::dictsetvarname ?args?
proc clay::tree::dictmergevarname ?args?
proc clay::tree::merge ?args?
proc dictargs::procnameargspecbody
proc dictargs::methodnameargspecbody
proc clay::dialect::Pushclass
proc clay::dialect::Peek
proc clay::dialect::Pop
proc clay::dialect::createname ?parent ?
proc clay::dialect::NSNormalizenamespacequalname
proc clay::dialect::DefineThunktarget ?args?
proc clay::dialect::CanonicalnamespaceNSpaceclass
proc clay::dialect::Definenamespaceclass ?args?
proc clay::dialect::Aliasesnamespace ?args?
proc clay::dialect::SuperClassnamespace ?args?
proc clay::dynamic_methodsclass
proc clay::dynamic_methods_classthisclass
proc clay::define::Arrayname ?values ?
proc clay::define::Delegatenameinfo
proc clay::define::constructorarglistrawbody
proc clay::define::Class_Methodnamearglistbody
proc clay::define::class_methodnamearglistbody
proc clay::define::clay ?args?
proc clay::define::destructorrawbody
proc clay::define::Dictname ?values ?
proc clay::define::Optionname ?args?
proc clay::define::Methodnameargstyleargspecbody
proc clay::define::Option_Classname ?args?
proc clay::define::Variablename ?default ?
proc clay::ensemble_methodbodyensembleeinfo
proc clay::define::Ensemblerawmethod ?args?
proc clay::event::cancelself ?task*?
proc clay::event::generateselfevent ?args?
proc clay::event::nextid
proc clay::event::Notification_listselfevent ?stackvar ?
proc clay::event::notifyrcptsendereventeventinfo
proc clay::event::processselfhandlescript
proc clay::event::scheduleselfhandleintervalscript
proc clay::event::subscribeselfwhoevent
proc clay::event::unsubscribeself ?args?
proc clay::singletonnamescript
method clayancestors
method claydump
method clayfindpath ?path...?
method claygetpath ?path...?
method clayGETpath ?path...?
method claymergedict ?dict...?
method clayreplacedictionary
method claysearchpath ?path...?
method claysetpath ?path...? value
method clayancestors
method claycachepathvalue
method claycgetfield
method claydelegate ?stub? ?object?
method claydump
method clayensemble_map
method clayevalscript
method clayevolve
method clayexistspath ?path...?
method clayflush
method clayforwardmethodobject
method claygetpath ?path...?
method clayleafpath ?path...?
method claymergedict ?dict...?
method claymixinclass ?class...?
method claymixinmap ?stub? ?classes?
method clayprovenancepath ?path...?
method clayreplacedictionary
method claysearchpathvaluevarisleafvar
method claysourcefilename
method claysetpath ?path...? value
method InitializePublic
________________________________________________________________________________________________________________
PNG Icons
