clay(3)



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

______________________________________________________________________________

NAME
       clay - A minimalist framework for large scale OO Projects

SYNOPSIS
       package require Tcl  8.6

       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 sys-
       tem 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 al-
       lows 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::de-
       fine 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  in-
       trospect  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
       proc clay::PROC name arglist body ?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 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.

       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?
              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_create objname ?class ?

       proc clay::object_rename object newname

       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::NSNormalize qualname

       proc clay::uuid_generate ?args?

       proc clay::uuid::generate_tcl_machinfo

       proc clay::uuid::tostring uuid

       proc clay::uuid::fromstring uuid
              Convert a string representation of a uuid into its  binary  for-
              mat.

       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

       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 ex-
              ists  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

       proc clay::dialect::Push class

       proc clay::dialect::Peek

       proc clay::dialect::Pop

       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?

       proc clay::dialect::Canonical namespace NSpace class

       proc clay::dialect::Define namespace class ?args?
              Implementation of the languages' define command

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

       proc clay::define::Class_Method name arglist body
              Specify the a method for the class object itself, instead of for
              objects of the class

       proc clay::define::class_method name arglist body
              And alias to the new Class_Method keyword

       proc clay::define::clay ?args?

       proc clay::define::destructor rawbody

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

       proc clay::define::Option name ?args?
              Define an option for the class

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

       proc clay::define::Option_Class name ?args?
              Define a class of options All field / value pairs will be be in-
              herited by an option that specify name as it 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 ensem-
              ble 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::Ensemble rawmethod ?args?

       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 recieved this event and prevent spamming or infinite
              recursion

       proc clay::event::nextid

       proc clay::event::Notification_list self event ?stackvar ?
              Called recursively to produce a list of who  recieves  notifica-
              tions

       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 it's own class.

CLASSES
   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 dic-
              tionary 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 com-
              mand 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 assem-
              bled 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.  Val-
              ues  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  con-
              stituent 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 previ-
              ously 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 na-
              tive  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 dic-
              tionary 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.

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 out-
       put 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>

tcllib                               0.8.6                          clay(3tcl)

Man(1) output converted with man2html
list of all man pages