Scroll to navigation

clay(3tcl) Clay Framework clay(3tcl) 





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










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.




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











COMMANDS



  

  
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 Create this command if there isn't one already. The
      ninja argument is a script to execute if the command is created by
      this mechanism.

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  

  
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.

  

  
Process the queue of objects to be destroyed

  

  

  

  

  

  
Mark an objects for destruction on the next cleanup

  

  

  

  
Append a line of text to a variable. Optionally apply a string
    mapping.

  

  

  

  

  

  

  

  

  

  

  

  
Convert a string representation of a uuid into its binary format.

  

  
Compare two uuids for equality.

  

  
uuid generate -> string rep of a new uuid uuid equal uuid1 uuid2

  

  
Output a dictionary removing any . entries added by
      clay::tree::merge

  

  
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

  

  
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






  

  
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






  

  
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}


   }


 }






  

  
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}


   }


 }






  

  
Named Procedures as new command

  

  

  

  

  

  

  

  

  

  
This proc will generate a namespace, a "mother of all classes",
      and a rudimentary set of policies for this dialect.

  

  
Support commands; not intended to be called directly.

  

  

  

  

  

  
Implementation of the languages' define command

  

  

  

  

  

  

  

  

  

  
New OO Keywords for clay

  

  
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.

  

  

  

  
Specify the a method for the class object itself, instead of for objects
      of the class

  

  
And alias to the new Class_Method keyword

  

  

  

  

  

  

  

  
Define an option for the class

  

  

  

  
Define a class of options All field / value pairs will be be inherited by
      an option that specify name as it class field.

  

  
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.



  

  
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"}


 }






  

  

  

  
Cancel a scheduled event

  

  
Generate an event Adds a subscription mechanism for objects to see who has
      recieved this event and prevent spamming or infinite recursion

  

  

  

  
Called recursively to produce a list of who recieves notifications

  

  
Final delivery to intended recipient object

  

  
Evaluate an event script in the global namespace

  

  
Schedule an event to occur later

  

  
Subscribe an object to an event pattern

  

  
Unsubscribe an object from an event pattern

  

  
An object which is intended to be it's own class.








CLASSES




CLASS CLAY::CLASS


Methods



  

  
Return this class and all ancestors in search order.

  

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

  

  
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.

  

  
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.

  

  
Pull a chunk of data from the class's clay system. If no value is found,
      returns an empty string.

  

  
Recursively merge the dictionaries given into the object's local clay
      storage.

  

  
Replace the contents of the internal clay storage with the dictionary
      given.

  

  
Return the first matching value for the path in either this class's clay
      data or one of its ancestors

  

  
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



  

  
Return the class this object belongs to, all classes mixed into this
      object, and all ancestors of those classes in search order.

  

  
Store VALUE in such a way that request in SEARCH for PATH will always
      return it until the cache is flushed

  

  
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

  

  

  
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.

  

  
Return a complete dump of this object's clay data, as well as the data
      from all constituent classes recursively blended in.

  

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

  

  
Evaluated a script in the namespace of this object

  

  
Trigger the InitializePublic private method

  

  
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.

  

  
Wipe any caches built by the clay implementation

  

  
A convenience wrapper for






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





  

  
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.

  

  
A modified get which is tailored to pull only leaf elements

  

  
Recursively merge the dictionaries given into the object's local clay
      storage.

  

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

  

  
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.

  

  
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.

  

  
Replace the contents of the internal clay storage with the dictionary
      given.

  

  
Return true, and set valuevar to the value and isleafar to true for false
      if PATH was found in the cache.

  

  
Source the given filename within the object's namespace

  

  
Merge the conents of value with the object's clay storage at
      path.

  

  
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






COPYRIGHT


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








  

    0.8.8
    tcllib