clay(n) 0.9 clay "Clay Framework"

Structured Data

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}

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.

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

Class clay::class

Methods

method clay ancestors

Return this class and all ancestors in search order.

method clay dump

Return a complete dump of this object's clay data, but only this object's clay data.

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 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 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.

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 conents 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

Return 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 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 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 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 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 clay dump

Return 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

Return a dictionary describing the method ensembles to be assembled for this object

method clay eval script

Evaluated a script in the namespace of this object

method clay evolve

Trigger 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 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 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 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 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 conents of value with the object's clay storage at path.

method InitializePublic

Instantiate variables. Called on object creation and during clay mixin.