Tcl Library Source Code

Check-in [147792792a]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Pulling changes from trunk
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | hypnotoad
Files: files | file ages | folders
SHA3-256: 147792792a48afba1429fa8cfb0ec44d8a8c4c96fd5ffc9e9d8adbede5acfb16
User & Date: hypnotoad 2019-06-05 13:30:59.891
Context
2019-06-08
00:22
Fixed an error with Clay's uuid generator when running with Tcllib's md5 implementation SCGI servers now read the doc_root setting and expose that as the DOCUMENT_ROOT header to scgi application code check-in: 2b1fd1d488 user: hypnotoad tags: hypnotoad
2019-06-05
13:30
Pulling changes from trunk check-in: 147792792a user: hypnotoad tags: hypnotoad
06:31
Integrated last of hypnotoad branch check-in: 8ec2d6ea79 user: aku tags: trunk
05:02
Integrated testsuite fixups Merged latest work from trunk Regenerated documentation. - Fixed outdated references to feedback.inc Use `modules/common-text/feedback.inc` now. check-in: e3ae2af3f4 user: aku tags: hypnotoad
Changes
Unified Diff Ignore Whitespace Patch
Added embedded/md/tcllib/files/modules/clay/clay.md.


















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777

[//000000001]: # (clay \- Clay Framework)
[//000000002]: # (Generated from file 'clay\.man' by tcllib/doctools with format 'markdown')
[//000000003]: # (Copyright &copy; 2018 Sean Woods <yoda@etoyoc\.com>)
[//000000004]: # (clay\(n\) 0\.8 tcllib "Clay Framework")

<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
href="../../../toc.md">Table Of Contents</a> &#124; <a
href="../../../../index.md">Keyword Index</a> &#124; <a
href="../../../../toc0.md">Categories</a> &#124; <a
href="../../../../toc1.md">Modules</a> &#124; <a
href="../../../../toc2.md">Applications</a> ] <hr>

# NAME

clay \- A minimalist framework for large scale OO Projects

# <a name='toc'></a>Table Of Contents

  - [Table Of Contents](#toc)

  - [Synopsis](#synopsis)

  - [Description](#section1)

      - [Structured Data](#subsection1)

      - [Clay Dialect](#subsection2)

      - [Method Delegation](#subsection3)

  - [Commands](#section2)

  - [Classes](#section3)

      - [Class clay::class](#subsection4)

      - [Class clay::object](#subsection5)

  - [AUTHORS](#section4)

  - [Bugs, Ideas, Feedback](#section5)

  - [Keywords](#keywords)

  - [Category](#category)

  - [Copyright](#copyright)

# <a name='synopsis'></a>SYNOPSIS

package require Tcl 8\.6  
package require uuid  
package require oo::dialect  

[proc __clay::PROC__ *name* *arglist* *body* ?*ninja* ____?](#1)  
[proc __clay::\_ancestors__ *resultvar* *class*](#2)  
[proc __clay::ancestors__ ?*args*?](#3)  
[proc __clay::args\_to\_dict__ ?*args*?](#4)  
[proc __clay::args\_to\_options__ ?*args*?](#5)  
[proc __clay::dynamic\_arguments__ *ensemble* *method* *arglist* ?*args*?](#6)  
[proc __clay::dynamic\_wrongargs\_message__ *arglist*](#7)  
[proc __clay::is\_dict__ *d*](#8)  
[proc __clay::is\_null__ *value*](#9)  
[proc __clay::leaf__ ?*args*?](#10)  
[proc __clay::K__ *a* *b*](#11)  
[proc __clay::noop__ ?*args*?](#12)  
[proc __clay::path__ ?*args*?](#13)  
[proc __clay::putb__ ?*map*? *text*](#14)  
[proc __clay::script\_path__](#15)  
[proc __clay::NSNormalize__ *qualname*](#16)  
[proc __clay::uuid\_generate__ ?*args*?](#17)  
[proc __clay::uuid::generate\_tcl\_machinfo__](#18)  
[proc __clay::uuid::tostring__ *uuid*](#19)  
[proc __clay::uuid::fromstring__ *uuid*](#20)  
[proc __clay::uuid::equal__ *left* *right*](#21)  
[proc __clay::uuid__ *cmd* ?*args*?](#22)  
[proc __clay::tree::sanitize__ *dict*](#23)  
[proc __clay::tree::\_sanitizeb__ *path* *varname* *dict*](#24)  
[proc __clay::tree::storage__ *rawpath*](#25)  
[proc __clay::tree::dictset__ *varname* ?*args*?](#26)  
[proc __clay::tree::dictmerge__ *varname* ?*args*?](#27)  
[proc __clay::tree::merge__ ?*args*?](#28)  
[proc __dictargs::proc__ *name* *argspec* *body*](#29)  
[proc __dictargs::method__ *name* *argspec* *body*](#30)  
[proc __clay::dialect::Push__ *class*](#31)  
[proc __clay::dialect::Peek__](#32)  
[proc __clay::dialect::Pop__](#33)  
[proc __clay::dialect::create__ *name* ?*parent* ____?](#34)  
[proc __clay::dialect::NSNormalize__ *namespace* *qualname*](#35)  
[proc __clay::dialect::DefineThunk__ *target* ?*args*?](#36)  
[proc __clay::dialect::Canonical__ *namespace* *NSpace* *class*](#37)  
[proc __clay::dialect::Define__ *namespace* *class* ?*args*?](#38)  
[proc __clay::dialect::Aliases__ *namespace* ?*args*?](#39)  
[proc __clay::dialect::SuperClass__ *namespace* ?*args*?](#40)  
[proc __clay::dynamic\_methods__ *class*](#41)  
[proc __clay::dynamic\_methods\_class__ *thisclass*](#42)  
[proc __clay::define::Array__ *name* ?*values* ____?](#43)  
[proc __clay::define::Delegate__ *name* *info*](#44)  
[proc __clay::define::constructor__ *arglist* *rawbody*](#45)  
[proc __clay::define::Class\_Method__ *name* *arglist* *body*](#46)  
[proc __clay::define::class\_method__ *name* *arglist* *body*](#47)  
[proc __clay::define::clay__ ?*args*?](#48)  
[proc __clay::define::destructor__ *rawbody*](#49)  
[proc __clay::define::Dict__ *name* ?*values* ____?](#50)  
[proc __clay::define::Option__ *name* ?*args*?](#51)  
[proc __clay::define::Method__ *name* *argstyle* *argspec* *body*](#52)  
[proc __clay::define::Option\_Class__ *name* ?*args*?](#53)  
[proc __clay::define::Variable__ *name* ?*default* ____?](#54)  
[proc __clay::ensemble\_methodbody__ *ensemble* *einfo*](#55)  
[proc __clay::define::Ensemble__ *rawmethod* ?*args*?](#56)  
[proc __clay::cleanup__](#57)  
[proc __clay::object\_create__ *objname* ?*class* ____?](#58)  
[proc __clay::object\_rename__ *object* *newname*](#59)  
[proc __clay::object\_destroy__ ?*args*?](#60)  
[proc __clay::event::cancel__ *self* ?*task* __\*__?](#61)  
[proc __clay::event::generate__ *self* *event* ?*args*?](#62)  
[proc __clay::event::nextid__](#63)  
[proc __clay::event::Notification\_list__ *self* *event* ?*stackvar* ____?](#64)  
[proc __clay::event::notify__ *rcpt* *sender* *event* *eventinfo*](#65)  
[proc __clay::event::process__ *self* *handle* *script*](#66)  
[proc __clay::event::schedule__ *self* *handle* *interval* *script*](#67)  
[proc __clay::event::subscribe__ *self* *who* *event*](#68)  
[proc __clay::event::unsubscribe__ *self* ?*args*?](#69)  
[method __clay ancestors__](#70)  
[method __clay dump__](#71)  
[method __clay find__ *path* ?__path\.\.\.__?](#72)  
[method __clay get__ *path* ?__path\.\.\.__?](#73)  
[method __clay GET__ *path* ?__path\.\.\.__?](#74)  
[method __clay merge__ *dict* ?__dict\.\.\.__?](#75)  
[method __clay replace__ *dictionary*](#76)  
[method __clay search__ *path* ?__path\.\.\.__?](#77)  
[method __clay set__ *path* ?__path\.\.\.__? *value*](#78)  
[method __clay ancestors__](#79)  
[method __clay cget__ *field*](#80)  
[method __clay delegate__ ?*stub*? ?*object*?](#81)  
[method __clay dump__](#82)  
[method __clay ensemble\_map__](#83)  
[method __clay eval__ *script*](#84)  
[method __clay evolve__](#85)  
[method __clay exists__ *path* ?__path\.\.\.__?](#86)  
[method __clay flush__](#87)  
[method __clay forward__ *method* *object*](#88)  
[method __clay get__ *path* ?__path\.\.\.__?](#89)  
[method __clay leaf__ *path* ?__path\.\.\.__?](#90)  
[method __clay merge__ *dict* ?__dict\.\.\.__?](#91)  
[method __clay mixin__ *class* ?__class\.\.\.__?](#92)  
[method __clay mixinmap__ ?*stub*? ?*classes*?](#93)  
[method __clay provenance__ *path* ?__path\.\.\.__?](#94)  
[method __clay replace__ *dictionary*](#95)  
[method __clay source__ *filename*](#96)  
[method __clay set__ *path* ?__path\.\.\.__? *value*](#97)  
[method __InitializePublic__](#98)  

# <a name='description'></a>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\.

## <a name='subsection1'></a>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}

## <a name='subsection2'></a>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\.

## <a name='subsection3'></a>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

# <a name='section2'></a>Commands

  - <a name='1'></a>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\.

  - <a name='2'></a>proc __clay::\_ancestors__ *resultvar* *class*

  - <a name='3'></a>proc __clay::ancestors__ ?*args*?

  - <a name='4'></a>proc __clay::args\_to\_dict__ ?*args*?

  - <a name='5'></a>proc __clay::args\_to\_options__ ?*args*?

  - <a name='6'></a>proc __clay::dynamic\_arguments__ *ensemble* *method* *arglist* ?*args*?

  - <a name='7'></a>proc __clay::dynamic\_wrongargs\_message__ *arglist*

  - <a name='8'></a>proc __clay::is\_dict__ *d*

  - <a name='9'></a>proc __clay::is\_null__ *value*

  - <a name='10'></a>proc __clay::leaf__ ?*args*?

  - <a name='11'></a>proc __clay::K__ *a* *b*

  - <a name='12'></a>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\.

  - <a name='13'></a>proc __clay::path__ ?*args*?

  - <a name='14'></a>proc __clay::putb__ ?*map*? *text*

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

  - <a name='15'></a>proc __clay::script\_path__

  - <a name='16'></a>proc __clay::NSNormalize__ *qualname*

  - <a name='17'></a>proc __clay::uuid\_generate__ ?*args*?

  - <a name='18'></a>proc __clay::uuid::generate\_tcl\_machinfo__

  - <a name='19'></a>proc __clay::uuid::tostring__ *uuid*

  - <a name='20'></a>proc __clay::uuid::fromstring__ *uuid*

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

  - <a name='21'></a>proc __clay::uuid::equal__ *left* *right*

    Compare two uuids for equality\.

  - <a name='22'></a>proc __clay::uuid__ *cmd* ?*args*?

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

  - <a name='23'></a>proc __clay::tree::sanitize__ *dict*

    Output a dictionary removing any \. entries added by
    __clay::tree::merge__

  - <a name='24'></a>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

  - <a name='25'></a>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

  - <a name='26'></a>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 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 name='27'></a>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}
      }
    }

  - <a name='28'></a>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}
      }
    }

  - <a name='29'></a>proc __dictargs::proc__ *name* *argspec* *body*

    Named Procedures as new command

  - <a name='30'></a>proc __dictargs::method__ *name* *argspec* *body*

  - <a name='31'></a>proc __clay::dialect::Push__ *class*

  - <a name='32'></a>proc __clay::dialect::Peek__

  - <a name='33'></a>proc __clay::dialect::Pop__

  - <a name='34'></a>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\.

  - <a name='35'></a>proc __clay::dialect::NSNormalize__ *namespace* *qualname*

    Support commands; not intended to be called directly\.

  - <a name='36'></a>proc __clay::dialect::DefineThunk__ *target* ?*args*?

  - <a name='37'></a>proc __clay::dialect::Canonical__ *namespace* *NSpace* *class*

  - <a name='38'></a>proc __clay::dialect::Define__ *namespace* *class* ?*args*?

    Implementation of the languages' define command

  - <a name='39'></a>proc __clay::dialect::Aliases__ *namespace* ?*args*?

  - <a name='40'></a>proc __clay::dialect::SuperClass__ *namespace* ?*args*?

  - <a name='41'></a>proc __clay::dynamic\_methods__ *class*

  - <a name='42'></a>proc __clay::dynamic\_methods\_class__ *thisclass*

  - <a name='43'></a>proc __clay::define::Array__ *name* ?*values* ____?

    New OO Keywords for clay

  - <a name='44'></a>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\.

  - <a name='45'></a>proc __clay::define::constructor__ *arglist* *rawbody*

  - <a name='46'></a>proc __clay::define::Class\_Method__ *name* *arglist* *body*

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

  - <a name='47'></a>proc __clay::define::class\_method__ *name* *arglist* *body*

    And alias to the new Class\_Method keyword

  - <a name='48'></a>proc __clay::define::clay__ ?*args*?

  - <a name='49'></a>proc __clay::define::destructor__ *rawbody*

  - <a name='50'></a>proc __clay::define::Dict__ *name* ?*values* ____?

  - <a name='51'></a>proc __clay::define::Option__ *name* ?*args*?

    Define an option for the class

  - <a name='52'></a>proc __clay::define::Method__ *name* *argstyle* *argspec* *body*

  - <a name='53'></a>proc __clay::define::Option\_Class__ *name* ?*args*?

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

  - <a name='54'></a>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\.

  - <a name='55'></a>proc __clay::ensemble\_methodbody__ *ensemble* *einfo*

  - <a name='56'></a>proc __clay::define::Ensemble__ *rawmethod* ?*args*?

  - <a name='57'></a>proc __clay::cleanup__

    Process the queue of objects to be destroyed

  - <a name='58'></a>proc __clay::object\_create__ *objname* ?*class* ____?

  - <a name='59'></a>proc __clay::object\_rename__ *object* *newname*

  - <a name='60'></a>proc __clay::object\_destroy__ ?*args*?

    Mark an objects for destruction on the next cleanup

  - <a name='61'></a>proc __clay::event::cancel__ *self* ?*task* __\*__?

    Cancel a scheduled event

  - <a name='62'></a>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

  - <a name='63'></a>proc __clay::event::nextid__

  - <a name='64'></a>proc __clay::event::Notification\_list__ *self* *event* ?*stackvar* ____?

    Called recursively to produce a list of who recieves notifications

  - <a name='65'></a>proc __clay::event::notify__ *rcpt* *sender* *event* *eventinfo*

    Final delivery to intended recipient object

  - <a name='66'></a>proc __clay::event::process__ *self* *handle* *script*

    Evaluate an event script in the global namespace

  - <a name='67'></a>proc __clay::event::schedule__ *self* *handle* *interval* *script*

    Schedule an event to occur later

  - <a name='68'></a>proc __clay::event::subscribe__ *self* *who* *event*

    Subscribe an object to an event pattern

  - <a name='69'></a>proc __clay::event::unsubscribe__ *self* ?*args*?

    Unsubscribe an object from an event pattern

# <a name='section3'></a>Classes

## <a name='subsection4'></a>Class  clay::class

__Methods__

  - <a name='70'></a>method __clay ancestors__

    Return this class and all ancestors in search order\.

  - <a name='71'></a>method __clay dump__

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

  - <a name='72'></a>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\.

  - <a name='73'></a>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\.

  - <a name='74'></a>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\.

  - <a name='75'></a>method __clay merge__ *dict* ?__dict\.\.\.__?

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

  - <a name='76'></a>method __clay replace__ *dictionary*

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

  - <a name='77'></a>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

  - <a name='78'></a>method __clay set__ *path* ?__path\.\.\.__? *value*

    Merge the conents of __value__ with the object's clay storage at
    __path__\.

## <a name='subsection5'></a>Class  clay::object

clay::object This class is inherited by all classes that have options\.

__Methods__

  - <a name='79'></a>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\.

  - <a name='80'></a>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__

  - <a name='81'></a>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*\.

  - <a name='82'></a>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\.

  - <a name='83'></a>method __clay ensemble\_map__

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

  - <a name='84'></a>method __clay eval__ *script*

    Evaluated a script in the namespace of this object

  - <a name='85'></a>method __clay evolve__

    Trigger the __InitializePublic__ private method

  - <a name='86'></a>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\.

  - <a name='87'></a>method __clay flush__

    Wipe any caches built by the clay implementation

  - <a name='88'></a>method __clay forward__ *method* *object*

    A convenience wrapper for

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

  - <a name='89'></a>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\.

  - <a name='90'></a>method __clay leaf__ *path* ?__path\.\.\.__?

    A modified get which is tailored to pull only leaf elements

  - <a name='91'></a>method __clay merge__ *dict* ?__dict\.\.\.__?

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

  - <a name='92'></a>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\.\)

  - <a name='93'></a>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\.

  - <a name='94'></a>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\.

  - <a name='95'></a>method __clay replace__ *dictionary*

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

  - <a name='96'></a>method __clay source__ *filename*

    Source the given filename within the object's namespace

  - <a name='97'></a>method __clay set__ *path* ?__path\.\.\.__? *value*

    Merge the conents of __value__ with the object's clay storage at
    __path__\.

  - <a name='98'></a>method __InitializePublic__

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

# <a name='section4'></a>AUTHORS

Sean Woods

[mailto:<yoda@etoyoc\.com>](mailto:<yoda@etoyoc\.com>)

# <a name='section5'></a>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\.

# <a name='keywords'></a>KEYWORDS

[TclOO](\.\./\.\./\.\./\.\./index\.md\#tcloo), [oo](\.\./\.\./\.\./\.\./index\.md\#oo)

# <a name='category'></a>CATEGORY

Programming tools

# <a name='copyright'></a>COPYRIGHT

Copyright &copy; 2018 Sean Woods <yoda@etoyoc\.com>
Added idoc/man/files/modules/clay/clay.n.




























































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
'\"
'\" Generated from file 'clay\&.man' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2018 Sean Woods <yoda@etoyoc\&.com>
'\"
.TH "clay" n 0\&.8 tcllib "Clay Framework"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
clay \- A minimalist framework for large scale OO Projects
.SH SYNOPSIS
package require \fBTcl  8\&.6\fR
.sp
package require \fBuuid \fR
.sp
package require \fBoo::dialect \fR
.sp
proc \fBclay::PROC\fR \fIname\fR \fIarglist\fR \fIbody\fR ?\fIninja\fR \fB\fR?
.sp
proc \fBclay::_ancestors\fR \fIresultvar\fR \fIclass\fR
.sp
proc \fBclay::ancestors\fR ?\fIargs\fR?
.sp
proc \fBclay::args_to_dict\fR ?\fIargs\fR?
.sp
proc \fBclay::args_to_options\fR ?\fIargs\fR?
.sp
proc \fBclay::dynamic_arguments\fR \fIensemble\fR \fImethod\fR \fIarglist\fR ?\fIargs\fR?
.sp
proc \fBclay::dynamic_wrongargs_message\fR \fIarglist\fR
.sp
proc \fBclay::is_dict\fR \fId\fR
.sp
proc \fBclay::is_null\fR \fIvalue\fR
.sp
proc \fBclay::leaf\fR ?\fIargs\fR?
.sp
proc \fBclay::K\fR \fIa\fR \fIb\fR
.sp
proc \fBclay::noop\fR ?\fIargs\fR?
.sp
proc \fBclay::path\fR ?\fIargs\fR?
.sp
proc \fBclay::putb\fR ?\fImap\fR? \fItext\fR
.sp
proc \fBclay::script_path\fR
.sp
proc \fBclay::NSNormalize\fR \fIqualname\fR
.sp
proc \fBclay::uuid_generate\fR ?\fIargs\fR?
.sp
proc \fBclay::uuid::generate_tcl_machinfo\fR
.sp
proc \fBclay::uuid::tostring\fR \fIuuid\fR
.sp
proc \fBclay::uuid::fromstring\fR \fIuuid\fR
.sp
proc \fBclay::uuid::equal\fR \fIleft\fR \fIright\fR
.sp
proc \fBclay::uuid\fR \fIcmd\fR ?\fIargs\fR?
.sp
proc \fBclay::tree::sanitize\fR \fIdict\fR
.sp
proc \fBclay::tree::_sanitizeb\fR \fIpath\fR \fIvarname\fR \fIdict\fR
.sp
proc \fBclay::tree::storage\fR \fIrawpath\fR
.sp
proc \fBclay::tree::dictset\fR \fIvarname\fR ?\fIargs\fR?
.sp
proc \fBclay::tree::dictmerge\fR \fIvarname\fR ?\fIargs\fR?
.sp
proc \fBclay::tree::merge\fR ?\fIargs\fR?
.sp
proc \fBdictargs::proc\fR \fIname\fR \fIargspec\fR \fIbody\fR
.sp
proc \fBdictargs::method\fR \fIname\fR \fIargspec\fR \fIbody\fR
.sp
proc \fBclay::dialect::Push\fR \fIclass\fR
.sp
proc \fBclay::dialect::Peek\fR
.sp
proc \fBclay::dialect::Pop\fR
.sp
proc \fBclay::dialect::create\fR \fIname\fR ?\fIparent\fR \fB\fR?
.sp
proc \fBclay::dialect::NSNormalize\fR \fInamespace\fR \fIqualname\fR
.sp
proc \fBclay::dialect::DefineThunk\fR \fItarget\fR ?\fIargs\fR?
.sp
proc \fBclay::dialect::Canonical\fR \fInamespace\fR \fINSpace\fR \fIclass\fR
.sp
proc \fBclay::dialect::Define\fR \fInamespace\fR \fIclass\fR ?\fIargs\fR?
.sp
proc \fBclay::dialect::Aliases\fR \fInamespace\fR ?\fIargs\fR?
.sp
proc \fBclay::dialect::SuperClass\fR \fInamespace\fR ?\fIargs\fR?
.sp
proc \fBclay::dynamic_methods\fR \fIclass\fR
.sp
proc \fBclay::dynamic_methods_class\fR \fIthisclass\fR
.sp
proc \fBclay::define::Array\fR \fIname\fR ?\fIvalues\fR \fB\fR?
.sp
proc \fBclay::define::Delegate\fR \fIname\fR \fIinfo\fR
.sp
proc \fBclay::define::constructor\fR \fIarglist\fR \fIrawbody\fR
.sp
proc \fBclay::define::Class_Method\fR \fIname\fR \fIarglist\fR \fIbody\fR
.sp
proc \fBclay::define::class_method\fR \fIname\fR \fIarglist\fR \fIbody\fR
.sp
proc \fBclay::define::clay\fR ?\fIargs\fR?
.sp
proc \fBclay::define::destructor\fR \fIrawbody\fR
.sp
proc \fBclay::define::Dict\fR \fIname\fR ?\fIvalues\fR \fB\fR?
.sp
proc \fBclay::define::Option\fR \fIname\fR ?\fIargs\fR?
.sp
proc \fBclay::define::Method\fR \fIname\fR \fIargstyle\fR \fIargspec\fR \fIbody\fR
.sp
proc \fBclay::define::Option_Class\fR \fIname\fR ?\fIargs\fR?
.sp
proc \fBclay::define::Variable\fR \fIname\fR ?\fIdefault\fR \fB\fR?
.sp
proc \fBclay::ensemble_methodbody\fR \fIensemble\fR \fIeinfo\fR
.sp
proc \fBclay::define::Ensemble\fR \fIrawmethod\fR ?\fIargs\fR?
.sp
proc \fBclay::cleanup\fR
.sp
proc \fBclay::object_create\fR \fIobjname\fR ?\fIclass\fR \fB\fR?
.sp
proc \fBclay::object_rename\fR \fIobject\fR \fInewname\fR
.sp
proc \fBclay::object_destroy\fR ?\fIargs\fR?
.sp
proc \fBclay::event::cancel\fR \fIself\fR ?\fItask\fR \fB*\fR?
.sp
proc \fBclay::event::generate\fR \fIself\fR \fIevent\fR ?\fIargs\fR?
.sp
proc \fBclay::event::nextid\fR
.sp
proc \fBclay::event::Notification_list\fR \fIself\fR \fIevent\fR ?\fIstackvar\fR \fB\fR?
.sp
proc \fBclay::event::notify\fR \fIrcpt\fR \fIsender\fR \fIevent\fR \fIeventinfo\fR
.sp
proc \fBclay::event::process\fR \fIself\fR \fIhandle\fR \fIscript\fR
.sp
proc \fBclay::event::schedule\fR \fIself\fR \fIhandle\fR \fIinterval\fR \fIscript\fR
.sp
proc \fBclay::event::subscribe\fR \fIself\fR \fIwho\fR \fIevent\fR
.sp
proc \fBclay::event::unsubscribe\fR \fIself\fR ?\fIargs\fR?
.sp
method \fBclay ancestors\fR
.sp
method \fBclay dump\fR
.sp
method \fBclay find\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay GET\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR?
.sp
method \fBclay replace\fR \fIdictionary\fR
.sp
method \fBclay search\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR
.sp
method \fBclay ancestors\fR
.sp
method \fBclay cget\fR \fIfield\fR
.sp
method \fBclay delegate\fR ?\fIstub\fR? ?\fIobject\fR?
.sp
method \fBclay dump\fR
.sp
method \fBclay ensemble_map\fR
.sp
method \fBclay eval\fR \fIscript\fR
.sp
method \fBclay evolve\fR
.sp
method \fBclay exists\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay flush\fR
.sp
method \fBclay forward\fR \fImethod\fR \fIobject\fR
.sp
method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay leaf\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR?
.sp
method \fBclay mixin\fR \fIclass\fR ?\fBclass\&.\&.\&.\fR?
.sp
method \fBclay mixinmap\fR ?\fIstub\fR? ?\fIclasses\fR?
.sp
method \fBclay provenance\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
.sp
method \fBclay replace\fR \fIdictionary\fR
.sp
method \fBclay source\fR \fIfilename\fR
.sp
method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR
.sp
method \fBInitializePublic\fR
.sp
.BE
.SH DESCRIPTION
Clay introduces a method ensemble to both \fBoo::class\fR and \fBoo::object\fR 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\&.
.PP
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\&.
.PP
.SS "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\&.
.PP
The \fBclay\fR 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\&.
.PP
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:
.CS


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

.CE
.PP
But when you start storing blocks of text, guessing what field is a dict and what isn’t gets messy:
.CS


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

.CE
.SS "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\&.
.SS "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\&.
.CS


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

.CE
.SH COMMANDS
.TP
proc \fBclay::PROC\fR \fIname\fR \fIarglist\fR \fIbody\fR ?\fIninja\fR \fB\fR?
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
\fICreate this command if there isn't one already\fR\&.
The \fIninja\fR argument is a script to execute if the
command is created by this mechanism\&.
.TP
proc \fBclay::_ancestors\fR \fIresultvar\fR \fIclass\fR
.TP
proc \fBclay::ancestors\fR ?\fIargs\fR?
.TP
proc \fBclay::args_to_dict\fR ?\fIargs\fR?
.TP
proc \fBclay::args_to_options\fR ?\fIargs\fR?
.TP
proc \fBclay::dynamic_arguments\fR \fIensemble\fR \fImethod\fR \fIarglist\fR ?\fIargs\fR?
.TP
proc \fBclay::dynamic_wrongargs_message\fR \fIarglist\fR
.TP
proc \fBclay::is_dict\fR \fId\fR
.TP
proc \fBclay::is_null\fR \fIvalue\fR
.TP
proc \fBclay::leaf\fR ?\fIargs\fR?
.TP
proc \fBclay::K\fR \fIa\fR \fIb\fR
.TP
proc \fBclay::noop\fR ?\fIargs\fR?
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\&.
.TP
proc \fBclay::path\fR ?\fIargs\fR?
.TP
proc \fBclay::putb\fR ?\fImap\fR? \fItext\fR
Append a line of text to a variable\&. Optionally apply a string mapping\&.
.TP
proc \fBclay::script_path\fR
.TP
proc \fBclay::NSNormalize\fR \fIqualname\fR
.TP
proc \fBclay::uuid_generate\fR ?\fIargs\fR?
.TP
proc \fBclay::uuid::generate_tcl_machinfo\fR
.TP
proc \fBclay::uuid::tostring\fR \fIuuid\fR
.TP
proc \fBclay::uuid::fromstring\fR \fIuuid\fR
Convert a string representation of a uuid into its binary format\&.
.TP
proc \fBclay::uuid::equal\fR \fIleft\fR \fIright\fR
Compare two uuids for equality\&.
.TP
proc \fBclay::uuid\fR \fIcmd\fR ?\fIargs\fR?
uuid generate -> string rep of a new uuid
uuid equal uuid1 uuid2
.TP
proc \fBclay::tree::sanitize\fR \fIdict\fR
Output a dictionary removing any \&. entries added by \fBclay::tree::merge\fR
.TP
proc \fBclay::tree::_sanitizeb\fR \fIpath\fR \fIvarname\fR \fIdict\fR
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
.TP
proc \fBclay::tree::storage\fR \fIrawpath\fR
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 /\&.
.sp
Example:
.CS

 > 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



.CE
.TP
proc \fBclay::tree::dictset\fR \fIvarname\fR ?\fIargs\fR?
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\&.
.sp
Example:
.CS

 > 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



.CE
.TP
proc \fBclay::tree::dictmerge\fR \fIvarname\fR ?\fIargs\fR?
A recursive form of dict merge, intended for modifying variables in place\&.
.sp
Example:
.CS

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



.CE
.TP
proc \fBclay::tree::merge\fR ?\fIargs\fR?
A recursive form of dict merge
.sp
A routine to recursively dig through dicts and merge
adapted from http://stevehavelka\&.com/tcl-dict-operation-nested-merge/
.sp
Example:
.CS

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



.CE
.TP
proc \fBdictargs::proc\fR \fIname\fR \fIargspec\fR \fIbody\fR
Named Procedures as new command
.TP
proc \fBdictargs::method\fR \fIname\fR \fIargspec\fR \fIbody\fR
.TP
proc \fBclay::dialect::Push\fR \fIclass\fR
.TP
proc \fBclay::dialect::Peek\fR
.TP
proc \fBclay::dialect::Pop\fR
.TP
proc \fBclay::dialect::create\fR \fIname\fR ?\fIparent\fR \fB\fR?
This proc will generate a namespace, a "mother of all classes", and a
rudimentary set of policies for this dialect\&.
.TP
proc \fBclay::dialect::NSNormalize\fR \fInamespace\fR \fIqualname\fR
Support commands; not intended to be called directly\&.
.TP
proc \fBclay::dialect::DefineThunk\fR \fItarget\fR ?\fIargs\fR?
.TP
proc \fBclay::dialect::Canonical\fR \fInamespace\fR \fINSpace\fR \fIclass\fR
.TP
proc \fBclay::dialect::Define\fR \fInamespace\fR \fIclass\fR ?\fIargs\fR?
Implementation of the languages' define command
.TP
proc \fBclay::dialect::Aliases\fR \fInamespace\fR ?\fIargs\fR?
.TP
proc \fBclay::dialect::SuperClass\fR \fInamespace\fR ?\fIargs\fR?
.TP
proc \fBclay::dynamic_methods\fR \fIclass\fR
.TP
proc \fBclay::dynamic_methods_class\fR \fIthisclass\fR
.TP
proc \fBclay::define::Array\fR \fIname\fR ?\fIvalues\fR \fB\fR?
New OO Keywords for clay
.TP
proc \fBclay::define::Delegate\fR \fIname\fR \fIinfo\fR
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 \fIdescription\fR, a human readable description\&.
.TP
proc \fBclay::define::constructor\fR \fIarglist\fR \fIrawbody\fR
.TP
proc \fBclay::define::Class_Method\fR \fIname\fR \fIarglist\fR \fIbody\fR
Specify the a method for the class object itself, instead of for objects of the class
.TP
proc \fBclay::define::class_method\fR \fIname\fR \fIarglist\fR \fIbody\fR
And alias to the new Class_Method keyword
.TP
proc \fBclay::define::clay\fR ?\fIargs\fR?
.TP
proc \fBclay::define::destructor\fR \fIrawbody\fR
.TP
proc \fBclay::define::Dict\fR \fIname\fR ?\fIvalues\fR \fB\fR?
.TP
proc \fBclay::define::Option\fR \fIname\fR ?\fIargs\fR?
Define an option for the class
.TP
proc \fBclay::define::Method\fR \fIname\fR \fIargstyle\fR \fIargspec\fR \fIbody\fR
.TP
proc \fBclay::define::Option_Class\fR \fIname\fR ?\fIargs\fR?
Define a class of options
All field / value pairs will be be inherited by an option that
specify \fIname\fR as it class field\&.
.TP
proc \fBclay::define::Variable\fR \fIname\fR ?\fIdefault\fR \fB\fR?
This keyword can also be expressed:
.CS

property variable NAME {default DEFAULT}
.CE
.sp
Variables registered in the variable property are also initialized
(if missing) when the object changes class via the \fImorph\fR method\&.
.TP
proc \fBclay::ensemble_methodbody\fR \fIensemble\fR \fIeinfo\fR
.TP
proc \fBclay::define::Ensemble\fR \fIrawmethod\fR ?\fIargs\fR?
.TP
proc \fBclay::cleanup\fR
Process the queue of objects to be destroyed
.TP
proc \fBclay::object_create\fR \fIobjname\fR ?\fIclass\fR \fB\fR?
.TP
proc \fBclay::object_rename\fR \fIobject\fR \fInewname\fR
.TP
proc \fBclay::object_destroy\fR ?\fIargs\fR?
Mark an objects for destruction on the next cleanup
.TP
proc \fBclay::event::cancel\fR \fIself\fR ?\fItask\fR \fB*\fR?
Cancel a scheduled event
.TP
proc \fBclay::event::generate\fR \fIself\fR \fIevent\fR ?\fIargs\fR?
Generate an event
Adds a subscription mechanism for objects
to see who has recieved this event and prevent
spamming or infinite recursion
.TP
proc \fBclay::event::nextid\fR
.TP
proc \fBclay::event::Notification_list\fR \fIself\fR \fIevent\fR ?\fIstackvar\fR \fB\fR?
Called recursively to produce a list of
who recieves notifications
.TP
proc \fBclay::event::notify\fR \fIrcpt\fR \fIsender\fR \fIevent\fR \fIeventinfo\fR
Final delivery to intended recipient object
.TP
proc \fBclay::event::process\fR \fIself\fR \fIhandle\fR \fIscript\fR
Evaluate an event script in the global namespace
.TP
proc \fBclay::event::schedule\fR \fIself\fR \fIhandle\fR \fIinterval\fR \fIscript\fR
Schedule an event to occur later
.TP
proc \fBclay::event::subscribe\fR \fIself\fR \fIwho\fR \fIevent\fR
Subscribe an object to an event pattern
.TP
proc \fBclay::event::unsubscribe\fR \fIself\fR ?\fIargs\fR?
Unsubscribe an object from an event pattern
.PP
.SH CLASSES
.SS "CLASS  CLAY::CLASS"
.PP
\fBMethods\fR
.TP
method \fBclay ancestors\fR
Return this class and all ancestors in search order\&.
.TP
method \fBclay dump\fR
Return a complete dump of this object's clay data, but only this object's clay data\&.
.TP
method \fBclay find\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Pull a chunk of data from the clay system\&. If the last element of \fIpath\fR 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\&.
.TP
method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
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\&.
.TP
method \fBclay GET\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Pull a chunk of data from the class's clay system\&.
If no value is found, returns an empty string\&.
.TP
method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR?
Recursively merge the dictionaries given into the object's local clay storage\&.
.TP
method \fBclay replace\fR \fIdictionary\fR
Replace the contents of the internal clay storage with the dictionary given\&.
.TP
method \fBclay search\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Return the first matching value for the path in either this class's clay data or one of its ancestors
.TP
method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR
Merge the conents of \fBvalue\fR with the object's clay storage at \fBpath\fR\&.
.PP
.PP
.SS "CLASS  CLAY::OBJECT"
clay::object
This class is inherited by all classes that have options\&.
.PP
\fBMethods\fR
.TP
method \fBclay ancestors\fR
Return the class this object belongs to, all classes mixed into this object, and all ancestors of those classes in search order\&.
.TP
method \fBclay cget\fR \fIfield\fR
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:
.sp
1\&. The as a value in local dict variable config
.sp
2\&. The as a value in local dict variable clay
.sp
3\&. As a leaf in any ancestor as a root of the clay tree
.sp
4\&. As a leaf in any ancestor as \fBconst\fR \fIfield\fR
.sp
5\&. As a leaf in any ancestor as \fBoption\fR \fIfield\fR \fBdefault\fR
.TP
method \fBclay delegate\fR ?\fIstub\fR? ?\fIobject\fR?
Introspect or control method delegation\&. With no arguments, the method will return a
key/value list of stubs and objects\&. With just the \fIstub\fR argument, the method will
return the object (if any) attached to the stub\&. With a \fIstub\fR and an \fIobject\fR
this command will forward all calls to the method \fIstub\fR to the \fIobject\fR\&.
.TP
method \fBclay dump\fR
Return a complete dump of this object's clay data, as well as the data from all constituent classes recursively blended in\&.
.TP
method \fBclay ensemble_map\fR
Return a dictionary describing the method ensembles to be assembled for this object
.TP
method \fBclay eval\fR \fIscript\fR
Evaluated a script in the namespace of this object
.TP
method \fBclay evolve\fR
Trigger the \fBInitializePublic\fR private method
.TP
method \fBclay exists\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Returns 1 if \fIpath\fR 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\&.
.TP
method \fBclay flush\fR
Wipe any caches built by the clay implementation
.TP
method \fBclay forward\fR \fImethod\fR \fIobject\fR
A convenience wrapper for
.CS

oo::objdefine [self] forward {*}$args
.CE
.TP
method \fBclay get\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Pull a chunk of data from the clay system\&. If the last element of \fIpath\fR 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\&.
.TP
method \fBclay leaf\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
A modified get which is tailored to pull only leaf elements
.TP
method \fBclay merge\fR \fIdict\fR ?\fBdict\&.\&.\&.\fR?
Recursively merge the dictionaries given into the object's local clay storage\&.
.TP
method \fBclay mixin\fR \fIclass\fR ?\fBclass\&.\&.\&.\fR?
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\&.)
.TP
method \fBclay mixinmap\fR ?\fIstub\fR? ?\fIclasses\fR?
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\&.
.TP
method \fBclay provenance\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR?
Return either \fBself\fR if that path exists in the current object, or return the first class (if any) along the clay search path which contains that element\&.
.TP
method \fBclay replace\fR \fIdictionary\fR
Replace the contents of the internal clay storage with the dictionary given\&.
.TP
method \fBclay source\fR \fIfilename\fR
Source the given filename within the object's namespace
.TP
method \fBclay set\fR \fIpath\fR ?\fBpath\&.\&.\&.\fR? \fIvalue\fR
Merge the conents of \fBvalue\fR with the object's clay storage at \fBpath\fR\&.
.TP
method \fBInitializePublic\fR
Instantiate variables\&. Called on object creation and during clay mixin\&.
.PP
.PP
.SH AUTHORS
Sean Woods \fImailto:<yoda@etoyoc\&.com>\fR
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIoo\fR of the
\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.PP
When proposing code changes, please provide \fIunified diffs\fR,
i\&.e the output of \fBdiff -u\fR\&.
.PP
Note further that \fIattachments\fR are strongly preferred over
inlined patches\&. Attachments can be made by going to the \fBEdit\fR
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar\&.
.SH KEYWORDS
TclOO, oo
.SH CATEGORY
Programming tools
.SH COPYRIGHT
.nf
Copyright (c) 2018 Sean Woods <yoda@etoyoc\&.com>

.fi
Added idoc/www/tcllib/files/modules/clay/clay.html.




















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
<!DOCTYPE html><html><head>
<title>clay - Clay Framework</title>
<style type="text/css"><!--
    HTML {
	background: 	#FFFFFF;
	color: 		black;
    }
    BODY {
	background: 	#FFFFFF;
	color:	 	black;
    }
    DIV.doctools {
	margin-left:	10%;
	margin-right:	10%;
    }
    DIV.doctools H1,DIV.doctools H2 {
	margin-left:	-5%;
    }
    H1, H2, H3, H4 {
	margin-top: 	1em;
	font-family:	sans-serif;
	font-size:	large;
	color:		#005A9C;
	background: 	transparent;
	text-align:		left;
    }
    H1.doctools_title {
	text-align: center;
    }
    UL,OL {
	margin-right: 0em;
	margin-top: 3pt;
	margin-bottom: 3pt;
    }
    UL LI {
	list-style: disc;
    }
    OL LI {
	list-style: decimal;
    }
    DT {
	padding-top: 	1ex;
    }
    UL.doctools_toc,UL.doctools_toc UL, UL.doctools_toc UL UL {
	font:		normal 12pt/14pt sans-serif;
	list-style:	none;
    }
    LI.doctools_section, LI.doctools_subsection {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding: 	0em;
    }
    PRE {
	display: 	block;
	font-family:	monospace;
	white-space:	pre;
	margin:		0%;
	padding-top:	0.5ex;
	padding-bottom:	0.5ex;
	padding-left:	1ex;
	padding-right:	1ex;
	width:		100%;
    }
    PRE.doctools_example {
	color: 		black;
	background: 	#f5dcb3;
	border:		1px solid black;
    }
    UL.doctools_requirements LI, UL.doctools_syntax LI {
	list-style: 	none;
	margin-left: 	0em;
	text-indent:	0em;
	padding:	0em;
    }
    DIV.doctools_synopsis {
	color: 		black;
	background: 	#80ffff;
	border:		1px solid black;
	font-family:	serif;
	margin-top: 	1em;
	margin-bottom: 	1em;
    }
    UL.doctools_syntax {
	margin-top: 	1em;
	border-top:	1px solid black;
    }
    UL.doctools_requirements {
	margin-bottom: 	1em;
	border-bottom:	1px solid black;
    }
--></style>
</head>
<!-- Generated from file 'clay.man' by tcllib/doctools with format 'html'
   -->
<!-- Copyright &amp;copy; 2018 Sean Woods &amp;lt;[email protected]&amp;gt;
   -->
<!-- clay.n
   -->
<body><hr> [
   <a href="../../../../../../../../home">Tcllib Home</a>
&#124; <a href="../../../../toc.html">Main Table Of Contents</a>
&#124; <a href="../../../toc.html">Table Of Contents</a>
&#124; <a href="../../../../index.html">Keyword Index</a>
&#124; <a href="../../../../toc0.html">Categories</a>
&#124; <a href="../../../../toc1.html">Modules</a>
&#124; <a href="../../../../toc2.html">Applications</a>
 ] <hr>
<div class="doctools">
<h1 class="doctools_title">clay(n) 0.8 tcllib &quot;Clay Framework&quot;</h1>
<div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
<p>clay - A minimalist framework for large scale OO Projects</p>
</div>
<div id="toc" class="doctools_section"><h2><a name="toc">Table Of Contents</a></h2>
<ul class="doctools_toc">
<li class="doctools_section"><a href="#toc">Table Of Contents</a></li>
<li class="doctools_section"><a href="#synopsis">Synopsis</a></li>
<li class="doctools_section"><a href="#section1">Description</a>
<ul>
<li class="doctools_subsection"><a href="#subsection1">Structured Data</a></li>
<li class="doctools_subsection"><a href="#subsection2">Clay Dialect</a></li>
<li class="doctools_subsection"><a href="#subsection3">Method Delegation</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section2">Commands</a></li>
<li class="doctools_section"><a href="#section3">Classes</a>
<ul>
<li class="doctools_subsection"><a href="#subsection4">Class  clay::class</a></li>
<li class="doctools_subsection"><a href="#subsection5">Class  clay::object</a></li>
</ul>
</li>
<li class="doctools_section"><a href="#section4">AUTHORS</a></li>
<li class="doctools_section"><a href="#section5">Bugs, Ideas, Feedback</a></li>
<li class="doctools_section"><a href="#keywords">Keywords</a></li>
<li class="doctools_section"><a href="#category">Category</a></li>
<li class="doctools_section"><a href="#copyright">Copyright</a></li>
</ul>
</div>
<div id="synopsis" class="doctools_section"><h2><a name="synopsis">Synopsis</a></h2>
<div class="doctools_synopsis">
<ul class="doctools_requirements">
<li>package require <b class="pkgname">Tcl 8.6</b></li>
<li>package require <b class="pkgname">uuid</b></li>
<li>package require <b class="pkgname">oo::dialect</b></li>
</ul>
<ul class="doctools_syntax">
<li><a href="#1">proc <b class="cmd">clay::PROC</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i> <span class="opt">?<i class="arg">ninja</i> <b class="const"></b>?</span></a></li>
<li><a href="#2">proc <b class="cmd">clay::_ancestors</b> <i class="arg">resultvar</i> <i class="arg">class</i></a></li>
<li><a href="#3">proc <b class="cmd">clay::ancestors</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#4">proc <b class="cmd">clay::args_to_dict</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#5">proc <b class="cmd">clay::args_to_options</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#6">proc <b class="cmd">clay::dynamic_arguments</b> <i class="arg">ensemble</i> <i class="arg">method</i> <i class="arg">arglist</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#7">proc <b class="cmd">clay::dynamic_wrongargs_message</b> <i class="arg">arglist</i></a></li>
<li><a href="#8">proc <b class="cmd">clay::is_dict</b> <i class="arg">d</i></a></li>
<li><a href="#9">proc <b class="cmd">clay::is_null</b> <i class="arg">value</i></a></li>
<li><a href="#10">proc <b class="cmd">clay::leaf</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#11">proc <b class="cmd">clay::K</b> <i class="arg">a</i> <i class="arg">b</i></a></li>
<li><a href="#12">proc <b class="cmd">clay::noop</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#13">proc <b class="cmd">clay::path</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#14">proc <b class="cmd">clay::putb</b> <span class="opt">?<i class="arg">map</i>?</span> <i class="arg">text</i></a></li>
<li><a href="#15">proc <b class="cmd">clay::script_path</b></a></li>
<li><a href="#16">proc <b class="cmd">clay::NSNormalize</b> <i class="arg">qualname</i></a></li>
<li><a href="#17">proc <b class="cmd">clay::uuid_generate</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#18">proc <b class="cmd">clay::uuid::generate_tcl_machinfo</b></a></li>
<li><a href="#19">proc <b class="cmd">clay::uuid::tostring</b> <i class="arg">uuid</i></a></li>
<li><a href="#20">proc <b class="cmd">clay::uuid::fromstring</b> <i class="arg">uuid</i></a></li>
<li><a href="#21">proc <b class="cmd">clay::uuid::equal</b> <i class="arg">left</i> <i class="arg">right</i></a></li>
<li><a href="#22">proc <b class="cmd">clay::uuid</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#23">proc <b class="cmd">clay::tree::sanitize</b> <i class="arg">dict</i></a></li>
<li><a href="#24">proc <b class="cmd">clay::tree::_sanitizeb</b> <i class="arg">path</i> <i class="arg">varname</i> <i class="arg">dict</i></a></li>
<li><a href="#25">proc <b class="cmd">clay::tree::storage</b> <i class="arg">rawpath</i></a></li>
<li><a href="#26">proc <b class="cmd">clay::tree::dictset</b> <i class="arg">varname</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#27">proc <b class="cmd">clay::tree::dictmerge</b> <i class="arg">varname</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#28">proc <b class="cmd">clay::tree::merge</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#29">proc <b class="cmd">dictargs::proc</b> <i class="arg">name</i> <i class="arg">argspec</i> <i class="arg">body</i></a></li>
<li><a href="#30">proc <b class="cmd">dictargs::method</b> <i class="arg">name</i> <i class="arg">argspec</i> <i class="arg">body</i></a></li>
<li><a href="#31">proc <b class="cmd">clay::dialect::Push</b> <i class="arg">class</i></a></li>
<li><a href="#32">proc <b class="cmd">clay::dialect::Peek</b></a></li>
<li><a href="#33">proc <b class="cmd">clay::dialect::Pop</b></a></li>
<li><a href="#34">proc <b class="cmd">clay::dialect::create</b> <i class="arg">name</i> <span class="opt">?<i class="arg">parent</i> <b class="const"></b>?</span></a></li>
<li><a href="#35">proc <b class="cmd">clay::dialect::NSNormalize</b> <i class="arg">namespace</i> <i class="arg">qualname</i></a></li>
<li><a href="#36">proc <b class="cmd">clay::dialect::DefineThunk</b> <i class="arg">target</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#37">proc <b class="cmd">clay::dialect::Canonical</b> <i class="arg">namespace</i> <i class="arg">NSpace</i> <i class="arg">class</i></a></li>
<li><a href="#38">proc <b class="cmd">clay::dialect::Define</b> <i class="arg">namespace</i> <i class="arg">class</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#39">proc <b class="cmd">clay::dialect::Aliases</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#40">proc <b class="cmd">clay::dialect::SuperClass</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#41">proc <b class="cmd">clay::dynamic_methods</b> <i class="arg">class</i></a></li>
<li><a href="#42">proc <b class="cmd">clay::dynamic_methods_class</b> <i class="arg">thisclass</i></a></li>
<li><a href="#43">proc <b class="cmd">clay::define::Array</b> <i class="arg">name</i> <span class="opt">?<i class="arg">values</i> <b class="const"></b>?</span></a></li>
<li><a href="#44">proc <b class="cmd">clay::define::Delegate</b> <i class="arg">name</i> <i class="arg">info</i></a></li>
<li><a href="#45">proc <b class="cmd">clay::define::constructor</b> <i class="arg">arglist</i> <i class="arg">rawbody</i></a></li>
<li><a href="#46">proc <b class="cmd">clay::define::Class_Method</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#47">proc <b class="cmd">clay::define::class_method</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></li>
<li><a href="#48">proc <b class="cmd">clay::define::clay</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#49">proc <b class="cmd">clay::define::destructor</b> <i class="arg">rawbody</i></a></li>
<li><a href="#50">proc <b class="cmd">clay::define::Dict</b> <i class="arg">name</i> <span class="opt">?<i class="arg">values</i> <b class="const"></b>?</span></a></li>
<li><a href="#51">proc <b class="cmd">clay::define::Option</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#52">proc <b class="cmd">clay::define::Method</b> <i class="arg">name</i> <i class="arg">argstyle</i> <i class="arg">argspec</i> <i class="arg">body</i></a></li>
<li><a href="#53">proc <b class="cmd">clay::define::Option_Class</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#54">proc <b class="cmd">clay::define::Variable</b> <i class="arg">name</i> <span class="opt">?<i class="arg">default</i> <b class="const"></b>?</span></a></li>
<li><a href="#55">proc <b class="cmd">clay::ensemble_methodbody</b> <i class="arg">ensemble</i> <i class="arg">einfo</i></a></li>
<li><a href="#56">proc <b class="cmd">clay::define::Ensemble</b> <i class="arg">rawmethod</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#57">proc <b class="cmd">clay::cleanup</b></a></li>
<li><a href="#58">proc <b class="cmd">clay::object_create</b> <i class="arg">objname</i> <span class="opt">?<i class="arg">class</i> <b class="const"></b>?</span></a></li>
<li><a href="#59">proc <b class="cmd">clay::object_rename</b> <i class="arg">object</i> <i class="arg">newname</i></a></li>
<li><a href="#60">proc <b class="cmd">clay::object_destroy</b> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#61">proc <b class="cmd">clay::event::cancel</b> <i class="arg">self</i> <span class="opt">?<i class="arg">task</i> <b class="const">*</b>?</span></a></li>
<li><a href="#62">proc <b class="cmd">clay::event::generate</b> <i class="arg">self</i> <i class="arg">event</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#63">proc <b class="cmd">clay::event::nextid</b></a></li>
<li><a href="#64">proc <b class="cmd">clay::event::Notification_list</b> <i class="arg">self</i> <i class="arg">event</i> <span class="opt">?<i class="arg">stackvar</i> <b class="const"></b>?</span></a></li>
<li><a href="#65">proc <b class="cmd">clay::event::notify</b> <i class="arg">rcpt</i> <i class="arg">sender</i> <i class="arg">event</i> <i class="arg">eventinfo</i></a></li>
<li><a href="#66">proc <b class="cmd">clay::event::process</b> <i class="arg">self</i> <i class="arg">handle</i> <i class="arg">script</i></a></li>
<li><a href="#67">proc <b class="cmd">clay::event::schedule</b> <i class="arg">self</i> <i class="arg">handle</i> <i class="arg">interval</i> <i class="arg">script</i></a></li>
<li><a href="#68">proc <b class="cmd">clay::event::subscribe</b> <i class="arg">self</i> <i class="arg">who</i> <i class="arg">event</i></a></li>
<li><a href="#69">proc <b class="cmd">clay::event::unsubscribe</b> <i class="arg">self</i> <span class="opt">?<i class="arg">args</i>?</span></a></li>
<li><a href="#70">method <b class="cmd">clay ancestors</b></a></li>
<li><a href="#71">method <b class="cmd">clay dump</b></a></li>
<li><a href="#72">method <b class="cmd">clay find</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#73">method <b class="cmd">clay get</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#74">method <b class="cmd">clay GET</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#75">method <b class="cmd">clay merge</b> <i class="arg">dict</i> <span class="opt">?<b class="option">dict...</b>?</span></a></li>
<li><a href="#76">method <b class="cmd">clay replace</b> <i class="arg">dictionary</i></a></li>
<li><a href="#77">method <b class="cmd">clay search</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#78">method <b class="cmd">clay set</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span> <i class="arg">value</i></a></li>
<li><a href="#79">method <b class="cmd">clay ancestors</b></a></li>
<li><a href="#80">method <b class="cmd">clay cget</b> <i class="arg">field</i></a></li>
<li><a href="#81">method <b class="cmd">clay delegate</b> <span class="opt">?<i class="arg">stub</i>?</span> <span class="opt">?<i class="arg">object</i>?</span></a></li>
<li><a href="#82">method <b class="cmd">clay dump</b></a></li>
<li><a href="#83">method <b class="cmd">clay ensemble_map</b></a></li>
<li><a href="#84">method <b class="cmd">clay eval</b> <i class="arg">script</i></a></li>
<li><a href="#85">method <b class="cmd">clay evolve</b></a></li>
<li><a href="#86">method <b class="cmd">clay exists</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#87">method <b class="cmd">clay flush</b></a></li>
<li><a href="#88">method <b class="cmd">clay forward</b> <i class="arg">method</i> <i class="arg">object</i></a></li>
<li><a href="#89">method <b class="cmd">clay get</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#90">method <b class="cmd">clay leaf</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#91">method <b class="cmd">clay merge</b> <i class="arg">dict</i> <span class="opt">?<b class="option">dict...</b>?</span></a></li>
<li><a href="#92">method <b class="cmd">clay mixin</b> <i class="arg">class</i> <span class="opt">?<b class="option">class...</b>?</span></a></li>
<li><a href="#93">method <b class="cmd">clay mixinmap</b> <span class="opt">?<i class="arg">stub</i>?</span> <span class="opt">?<i class="arg">classes</i>?</span></a></li>
<li><a href="#94">method <b class="cmd">clay provenance</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></li>
<li><a href="#95">method <b class="cmd">clay replace</b> <i class="arg">dictionary</i></a></li>
<li><a href="#96">method <b class="cmd">clay source</b> <i class="arg">filename</i></a></li>
<li><a href="#97">method <b class="cmd">clay set</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span> <i class="arg">value</i></a></li>
<li><a href="#98">method <b class="cmd">InitializePublic</b></a></li>
</ul>
</div>
</div>
<div id="section1" class="doctools_section"><h2><a name="section1">Description</a></h2>
<p>Clay introduces a method ensemble to both <b class="class">oo::class</b> and <b class="class">oo::object</b> 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.</p>
<p>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.</p>
<div id="subsection1" class="doctools_subsection"><h3><a name="subsection1">Structured Data</a></h3>
<p>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.</p>
<p>The <b class="method">clay</b> 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.</p>
<p>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:</p>
<pre class="doctools_example">
::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}
</pre>
<p>But when you start storing blocks of text, guessing what field is a dict and what isn’t gets messy:</p>
<pre class="doctools_example">
::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}
</pre>
</div>
<div id="subsection2" class="doctools_subsection"><h3><a name="subsection2">Clay Dialect</a></h3>
<p>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.</p>
</div>
<div id="subsection3" class="doctools_subsection"><h3><a name="subsection3">Method Delegation</a></h3>
<p>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 (&lt; &gt;) around them.</p>
<pre class="doctools_example">
::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 &lt;counter&gt; $obj
  }
  method line {text} {
    my &lt;counter&gt; incr
    append buffer $text
  }
}
set A [example new]
$A line {Who’s line is it anyway?}
$A &lt;counter&gt; value
1
</pre>
</div>
</div>
<div id="section2" class="doctools_section"><h2><a name="section2">Commands</a></h2>
<dl class="doctools_definitions">
<dt><a name="1">proc <b class="cmd">clay::PROC</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i> <span class="opt">?<i class="arg">ninja</i> <b class="const"></b>?</span></a></dt>
<dd><p>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
 <em>Create this command if there isn't one already</em>.
 The <em>ninja</em> argument is a script to execute if the
 command is created by this mechanism.</p></dd>
<dt><a name="2">proc <b class="cmd">clay::_ancestors</b> <i class="arg">resultvar</i> <i class="arg">class</i></a></dt>
<dd></dd>
<dt><a name="3">proc <b class="cmd">clay::ancestors</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="4">proc <b class="cmd">clay::args_to_dict</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="5">proc <b class="cmd">clay::args_to_options</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="6">proc <b class="cmd">clay::dynamic_arguments</b> <i class="arg">ensemble</i> <i class="arg">method</i> <i class="arg">arglist</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="7">proc <b class="cmd">clay::dynamic_wrongargs_message</b> <i class="arg">arglist</i></a></dt>
<dd></dd>
<dt><a name="8">proc <b class="cmd">clay::is_dict</b> <i class="arg">d</i></a></dt>
<dd></dd>
<dt><a name="9">proc <b class="cmd">clay::is_null</b> <i class="arg">value</i></a></dt>
<dd></dd>
<dt><a name="10">proc <b class="cmd">clay::leaf</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="11">proc <b class="cmd">clay::K</b> <i class="arg">a</i> <i class="arg">b</i></a></dt>
<dd></dd>
<dt><a name="12">proc <b class="cmd">clay::noop</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="13">proc <b class="cmd">clay::path</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="14">proc <b class="cmd">clay::putb</b> <span class="opt">?<i class="arg">map</i>?</span> <i class="arg">text</i></a></dt>
<dd><p>Append a line of text to a variable. Optionally apply a string mapping.</p></dd>
<dt><a name="15">proc <b class="cmd">clay::script_path</b></a></dt>
<dd></dd>
<dt><a name="16">proc <b class="cmd">clay::NSNormalize</b> <i class="arg">qualname</i></a></dt>
<dd></dd>
<dt><a name="17">proc <b class="cmd">clay::uuid_generate</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="18">proc <b class="cmd">clay::uuid::generate_tcl_machinfo</b></a></dt>
<dd></dd>
<dt><a name="19">proc <b class="cmd">clay::uuid::tostring</b> <i class="arg">uuid</i></a></dt>
<dd></dd>
<dt><a name="20">proc <b class="cmd">clay::uuid::fromstring</b> <i class="arg">uuid</i></a></dt>
<dd><p>Convert a string representation of a uuid into its binary format.</p></dd>
<dt><a name="21">proc <b class="cmd">clay::uuid::equal</b> <i class="arg">left</i> <i class="arg">right</i></a></dt>
<dd><p>Compare two uuids for equality.</p></dd>
<dt><a name="22">proc <b class="cmd">clay::uuid</b> <i class="arg">cmd</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>uuid generate -&gt; string rep of a new uuid
 uuid equal uuid1 uuid2</p></dd>
<dt><a name="23">proc <b class="cmd">clay::tree::sanitize</b> <i class="arg">dict</i></a></dt>
<dd><p>Output a dictionary removing any . entries added by <b class="function">clay::tree::merge</b></p></dd>
<dt><a name="24">proc <b class="cmd">clay::tree::_sanitizeb</b> <i class="arg">path</i> <i class="arg">varname</i> <i class="arg">dict</i></a></dt>
<dd><p>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</p></dd>
<dt><a name="25">proc <b class="cmd">clay::tree::storage</b> <i class="arg">rawpath</i></a></dt>
<dd><p>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 /.</p>
<p>Example:</p>
<pre class="doctools_example"> &gt; clay::tree::storage {foo bar baz bang}
 foo bar baz bang
 &gt; clay::tree::storage {foo bar baz bang/}
 foo bar baz bang
 &gt; clay::tree::storage {foo bar baz bang:}
 foo bar baz bang:
 &gt; clay::tree::storage {foo/bar/baz bang:}
 foo bar baz bang:
 &gt; clay::tree::storage {foo/bar/baz/bang}
 foo bar baz bang
</pre>
</dd>
<dt><a name="26">proc <b class="cmd">clay::tree::dictset</b> <i class="arg">varname</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>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.</p>
<p>Example:</p>
<pre class="doctools_example"> &gt; set r {}
 &gt; ::clay::tree::dictset r option color default Green
 . {} option {. {} color {. {} default Green}}
 &gt; ::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
 &gt; ::clay::tree::dictset r option color default Blue
 missing value to go with key
</pre>
</dd>
<dt><a name="27">proc <b class="cmd">clay::tree::dictmerge</b> <i class="arg">varname</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>A recursive form of dict merge, intended for modifying variables in place.</p>
<p>Example:</p>
<pre class="doctools_example"> &gt; set mydict {sub/ {sub/ {description {a block of text}}}}
 &gt; ::clay::tree::dictmerge mydict {sub/ {sub/ {field {another block of text}}}}]
 &gt; clay::tree::print $mydict
 sub/ {
   sub/ {
     description {a block of text}
     field {another block of text}
   }
 }
</pre>
</dd>
<dt><a name="28">proc <b class="cmd">clay::tree::merge</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>A recursive form of dict merge</p>
<p>A routine to recursively dig through dicts and merge
 adapted from http://stevehavelka.com/tcl-dict-operation-nested-merge/</p>
<p>Example:</p>
<pre class="doctools_example"> &gt; set mydict {sub/ {sub/ {description {a block of text}}}}
 &gt; set odict [clay::tree::merge $mydict {sub/ {sub/ {field {another block of text}}}}]
 &gt; clay::tree::print $odict
 sub/ {
   sub/ {
     description {a block of text}
     field {another block of text}
   }
 }
</pre>
</dd>
<dt><a name="29">proc <b class="cmd">dictargs::proc</b> <i class="arg">name</i> <i class="arg">argspec</i> <i class="arg">body</i></a></dt>
<dd><p>Named Procedures as new command</p></dd>
<dt><a name="30">proc <b class="cmd">dictargs::method</b> <i class="arg">name</i> <i class="arg">argspec</i> <i class="arg">body</i></a></dt>
<dd></dd>
<dt><a name="31">proc <b class="cmd">clay::dialect::Push</b> <i class="arg">class</i></a></dt>
<dd></dd>
<dt><a name="32">proc <b class="cmd">clay::dialect::Peek</b></a></dt>
<dd></dd>
<dt><a name="33">proc <b class="cmd">clay::dialect::Pop</b></a></dt>
<dd></dd>
<dt><a name="34">proc <b class="cmd">clay::dialect::create</b> <i class="arg">name</i> <span class="opt">?<i class="arg">parent</i> <b class="const"></b>?</span></a></dt>
<dd><p>This proc will generate a namespace, a &quot;mother of all classes&quot;, and a
 rudimentary set of policies for this dialect.</p></dd>
<dt><a name="35">proc <b class="cmd">clay::dialect::NSNormalize</b> <i class="arg">namespace</i> <i class="arg">qualname</i></a></dt>
<dd><p>Support commands; not intended to be called directly.</p></dd>
<dt><a name="36">proc <b class="cmd">clay::dialect::DefineThunk</b> <i class="arg">target</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="37">proc <b class="cmd">clay::dialect::Canonical</b> <i class="arg">namespace</i> <i class="arg">NSpace</i> <i class="arg">class</i></a></dt>
<dd></dd>
<dt><a name="38">proc <b class="cmd">clay::dialect::Define</b> <i class="arg">namespace</i> <i class="arg">class</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Implementation of the languages' define command</p></dd>
<dt><a name="39">proc <b class="cmd">clay::dialect::Aliases</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="40">proc <b class="cmd">clay::dialect::SuperClass</b> <i class="arg">namespace</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="41">proc <b class="cmd">clay::dynamic_methods</b> <i class="arg">class</i></a></dt>
<dd></dd>
<dt><a name="42">proc <b class="cmd">clay::dynamic_methods_class</b> <i class="arg">thisclass</i></a></dt>
<dd></dd>
<dt><a name="43">proc <b class="cmd">clay::define::Array</b> <i class="arg">name</i> <span class="opt">?<i class="arg">values</i> <b class="const"></b>?</span></a></dt>
<dd><p>New OO Keywords for clay</p></dd>
<dt><a name="44">proc <b class="cmd">clay::define::Delegate</b> <i class="arg">name</i> <i class="arg">info</i></a></dt>
<dd><p>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 <em>description</em>, a human readable description.</p></dd>
<dt><a name="45">proc <b class="cmd">clay::define::constructor</b> <i class="arg">arglist</i> <i class="arg">rawbody</i></a></dt>
<dd></dd>
<dt><a name="46">proc <b class="cmd">clay::define::Class_Method</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>Specify the a method for the class object itself, instead of for objects of the class</p></dd>
<dt><a name="47">proc <b class="cmd">clay::define::class_method</b> <i class="arg">name</i> <i class="arg">arglist</i> <i class="arg">body</i></a></dt>
<dd><p>And alias to the new Class_Method keyword</p></dd>
<dt><a name="48">proc <b class="cmd">clay::define::clay</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="49">proc <b class="cmd">clay::define::destructor</b> <i class="arg">rawbody</i></a></dt>
<dd></dd>
<dt><a name="50">proc <b class="cmd">clay::define::Dict</b> <i class="arg">name</i> <span class="opt">?<i class="arg">values</i> <b class="const"></b>?</span></a></dt>
<dd></dd>
<dt><a name="51">proc <b class="cmd">clay::define::Option</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Define an option for the class</p></dd>
<dt><a name="52">proc <b class="cmd">clay::define::Method</b> <i class="arg">name</i> <i class="arg">argstyle</i> <i class="arg">argspec</i> <i class="arg">body</i></a></dt>
<dd></dd>
<dt><a name="53">proc <b class="cmd">clay::define::Option_Class</b> <i class="arg">name</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Define a class of options
 All field / value pairs will be be inherited by an option that
 specify <em>name</em> as it class field.</p></dd>
<dt><a name="54">proc <b class="cmd">clay::define::Variable</b> <i class="arg">name</i> <span class="opt">?<i class="arg">default</i> <b class="const"></b>?</span></a></dt>
<dd><p>This keyword can also be expressed:</p>
<pre class="doctools_example">property variable NAME {default DEFAULT}</pre>
<p>Variables registered in the variable property are also initialized
    (if missing) when the object changes class via the <em>morph</em> method.</p></dd>
<dt><a name="55">proc <b class="cmd">clay::ensemble_methodbody</b> <i class="arg">ensemble</i> <i class="arg">einfo</i></a></dt>
<dd></dd>
<dt><a name="56">proc <b class="cmd">clay::define::Ensemble</b> <i class="arg">rawmethod</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd></dd>
<dt><a name="57">proc <b class="cmd">clay::cleanup</b></a></dt>
<dd><p>Process the queue of objects to be destroyed</p></dd>
<dt><a name="58">proc <b class="cmd">clay::object_create</b> <i class="arg">objname</i> <span class="opt">?<i class="arg">class</i> <b class="const"></b>?</span></a></dt>
<dd></dd>
<dt><a name="59">proc <b class="cmd">clay::object_rename</b> <i class="arg">object</i> <i class="arg">newname</i></a></dt>
<dd></dd>
<dt><a name="60">proc <b class="cmd">clay::object_destroy</b> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Mark an objects for destruction on the next cleanup</p></dd>
<dt><a name="61">proc <b class="cmd">clay::event::cancel</b> <i class="arg">self</i> <span class="opt">?<i class="arg">task</i> <b class="const">*</b>?</span></a></dt>
<dd><p>Cancel a scheduled event</p></dd>
<dt><a name="62">proc <b class="cmd">clay::event::generate</b> <i class="arg">self</i> <i class="arg">event</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Generate an event
    Adds a subscription mechanism for objects
    to see who has recieved this event and prevent
    spamming or infinite recursion</p></dd>
<dt><a name="63">proc <b class="cmd">clay::event::nextid</b></a></dt>
<dd></dd>
<dt><a name="64">proc <b class="cmd">clay::event::Notification_list</b> <i class="arg">self</i> <i class="arg">event</i> <span class="opt">?<i class="arg">stackvar</i> <b class="const"></b>?</span></a></dt>
<dd><p>Called recursively to produce a list of
    who recieves notifications</p></dd>
<dt><a name="65">proc <b class="cmd">clay::event::notify</b> <i class="arg">rcpt</i> <i class="arg">sender</i> <i class="arg">event</i> <i class="arg">eventinfo</i></a></dt>
<dd><p>Final delivery to intended recipient object</p></dd>
<dt><a name="66">proc <b class="cmd">clay::event::process</b> <i class="arg">self</i> <i class="arg">handle</i> <i class="arg">script</i></a></dt>
<dd><p>Evaluate an event script in the global namespace</p></dd>
<dt><a name="67">proc <b class="cmd">clay::event::schedule</b> <i class="arg">self</i> <i class="arg">handle</i> <i class="arg">interval</i> <i class="arg">script</i></a></dt>
<dd><p>Schedule an event to occur later</p></dd>
<dt><a name="68">proc <b class="cmd">clay::event::subscribe</b> <i class="arg">self</i> <i class="arg">who</i> <i class="arg">event</i></a></dt>
<dd><p>Subscribe an object to an event pattern</p></dd>
<dt><a name="69">proc <b class="cmd">clay::event::unsubscribe</b> <i class="arg">self</i> <span class="opt">?<i class="arg">args</i>?</span></a></dt>
<dd><p>Unsubscribe an object from an event pattern</p></dd>
</dl>
</div>
<div id="section3" class="doctools_section"><h2><a name="section3">Classes</a></h2>
<div id="subsection4" class="doctools_subsection"><h3><a name="subsection4">Class  clay::class</a></h3>
<p><b class="class">Methods</b></p>
<dl class="doctools_definitions">
<dt><a name="70">method <b class="cmd">clay ancestors</b></a></dt>
<dd><p>Return this class and all ancestors in search order.</p></dd>
<dt><a name="71">method <b class="cmd">clay dump</b></a></dt>
<dd><p>Return a complete dump of this object's clay data, but only this object's clay data.</p></dd>
<dt><a name="72">method <b class="cmd">clay find</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Pull a chunk of data from the clay system. If the last element of <em>path</em> 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.</p></dd>
<dt><a name="73">method <b class="cmd">clay get</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="74">method <b class="cmd">clay GET</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Pull a chunk of data from the class's clay system.
     If no value is found, returns an empty string.</p></dd>
<dt><a name="75">method <b class="cmd">clay merge</b> <i class="arg">dict</i> <span class="opt">?<b class="option">dict...</b>?</span></a></dt>
<dd><p>Recursively merge the dictionaries given into the object's local clay storage.</p></dd>
<dt><a name="76">method <b class="cmd">clay replace</b> <i class="arg">dictionary</i></a></dt>
<dd><p>Replace the contents of the internal clay storage with the dictionary given.</p></dd>
<dt><a name="77">method <b class="cmd">clay search</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Return the first matching value for the path in either this class's clay data or one of its ancestors</p></dd>
<dt><a name="78">method <b class="cmd">clay set</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span> <i class="arg">value</i></a></dt>
<dd><p>Merge the conents of <b class="const">value</b> with the object's clay storage at <b class="const">path</b>.</p></dd>
</dl>
</div>
<div id="subsection5" class="doctools_subsection"><h3><a name="subsection5">Class  clay::object</a></h3>
<p>clay::object
 This class is inherited by all classes that have options.</p>
<p><b class="class">Methods</b></p>
<dl class="doctools_definitions">
<dt><a name="79">method <b class="cmd">clay ancestors</b></a></dt>
<dd><p>Return the class this object belongs to, all classes mixed into this object, and all ancestors of those classes in search order.</p></dd>
<dt><a name="80">method <b class="cmd">clay cget</b> <i class="arg">field</i></a></dt>
<dd><p>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:</p>
<p>1. The as a value in local dict variable config</p>
<p>2. The as a value in local dict variable clay</p>
<p>3. As a leaf in any ancestor as a root of the clay tree</p>
<p>4. As a leaf in any ancestor as <b class="const">const</b> <em>field</em></p>
<p>5. As a leaf in any ancestor as <b class="const">option</b> <em>field</em> <b class="const">default</b></p></dd>
<dt><a name="81">method <b class="cmd">clay delegate</b> <span class="opt">?<i class="arg">stub</i>?</span> <span class="opt">?<i class="arg">object</i>?</span></a></dt>
<dd><p>Introspect or control method delegation. With no arguments, the method will return a
 key/value list of stubs and objects. With just the <i class="arg">stub</i> argument, the method will
 return the object (if any) attached to the stub. With a <i class="arg">stub</i> and an <i class="arg">object</i>
 this command will forward all calls to the method <i class="arg">stub</i> to the <i class="arg">object</i>.</p></dd>
<dt><a name="82">method <b class="cmd">clay dump</b></a></dt>
<dd><p>Return a complete dump of this object's clay data, as well as the data from all constituent classes recursively blended in.</p></dd>
<dt><a name="83">method <b class="cmd">clay ensemble_map</b></a></dt>
<dd><p>Return a dictionary describing the method ensembles to be assembled for this object</p></dd>
<dt><a name="84">method <b class="cmd">clay eval</b> <i class="arg">script</i></a></dt>
<dd><p>Evaluated a script in the namespace of this object</p></dd>
<dt><a name="85">method <b class="cmd">clay evolve</b></a></dt>
<dd><p>Trigger the <b class="method">InitializePublic</b> private method</p></dd>
<dt><a name="86">method <b class="cmd">clay exists</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Returns 1 if <em>path</em> 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.</p></dd>
<dt><a name="87">method <b class="cmd">clay flush</b></a></dt>
<dd><p>Wipe any caches built by the clay implementation</p></dd>
<dt><a name="88">method <b class="cmd">clay forward</b> <i class="arg">method</i> <i class="arg">object</i></a></dt>
<dd><p>A convenience wrapper for</p>
<pre class="doctools_example">oo::objdefine [self] forward {*}$args</pre>
</dd>
<dt><a name="89">method <b class="cmd">clay get</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Pull a chunk of data from the clay system. If the last element of <em>path</em> 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.</p></dd>
<dt><a name="90">method <b class="cmd">clay leaf</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>A modified get which is tailored to pull only leaf elements</p></dd>
<dt><a name="91">method <b class="cmd">clay merge</b> <i class="arg">dict</i> <span class="opt">?<b class="option">dict...</b>?</span></a></dt>
<dd><p>Recursively merge the dictionaries given into the object's local clay storage.</p></dd>
<dt><a name="92">method <b class="cmd">clay mixin</b> <i class="arg">class</i> <span class="opt">?<b class="option">class...</b>?</span></a></dt>
<dd><p>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.)</p></dd>
<dt><a name="93">method <b class="cmd">clay mixinmap</b> <span class="opt">?<i class="arg">stub</i>?</span> <span class="opt">?<i class="arg">classes</i>?</span></a></dt>
<dd><p>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.</p></dd>
<dt><a name="94">method <b class="cmd">clay provenance</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span></a></dt>
<dd><p>Return either <b class="const">self</b> if that path exists in the current object, or return the first class (if any) along the clay search path which contains that element.</p></dd>
<dt><a name="95">method <b class="cmd">clay replace</b> <i class="arg">dictionary</i></a></dt>
<dd><p>Replace the contents of the internal clay storage with the dictionary given.</p></dd>
<dt><a name="96">method <b class="cmd">clay source</b> <i class="arg">filename</i></a></dt>
<dd><p>Source the given filename within the object's namespace</p></dd>
<dt><a name="97">method <b class="cmd">clay set</b> <i class="arg">path</i> <span class="opt">?<b class="option">path...</b>?</span> <i class="arg">value</i></a></dt>
<dd><p>Merge the conents of <b class="const">value</b> with the object's clay storage at <b class="const">path</b>.</p></dd>
<dt><a name="98">method <b class="cmd">InitializePublic</b></a></dt>
<dd><p>Instantiate variables. Called on object creation and during clay mixin.</p></dd>
</dl>
</div>
</div>
<div id="section4" class="doctools_section"><h2><a name="section4">AUTHORS</a></h2>
<p>Sean Woods <a href="mailto:<[email protected]>">mailto:&lt;[email protected]&gt;</a></p>
</div>
<div id="section5" class="doctools_section"><h2><a name="section5">Bugs, Ideas, Feedback</a></h2>
<p>This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category <em>oo</em> of the
<a href="http://core.tcl.tk/tcllib/reportlist">Tcllib Trackers</a>.
Please also report any ideas for enhancements you may have for either
package and/or documentation.</p>
<p>When proposing code changes, please provide <em>unified diffs</em>,
i.e the output of <b class="const">diff -u</b>.</p>
<p>Note further that <em>attachments</em> are strongly preferred over
inlined patches. Attachments can be made by going to the <b class="const">Edit</b>
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar.</p>
</div>
<div id="keywords" class="doctools_section"><h2><a name="keywords">Keywords</a></h2>
<p><a href="../../../../index.html#tcloo">TclOO</a>, <a href="../../../../index.html#oo">oo</a></p>
</div>
<div id="category" class="doctools_section"><h2><a name="category">Category</a></h2>
<p>Programming tools</p>
</div>
<div id="copyright" class="doctools_section"><h2><a name="copyright">Copyright</a></h2>
<p>Copyright &copy; 2018 Sean Woods &lt;[email protected]&gt;</p>
</div>
</div></body></html>