[George Peter Staplin]: Mar 20, 2005 - The megapkg structure extension provides rich structures, and capabilities beyond dict, and arrays.  It's available under a BSD-like license.

Tarballs are available from:
http://www.xmission.com/~georgeps/implementation/software/megapkg/

----
'''Structure creation:'''

 set s [structure]

Alternatively named structures can be created.  This is useful for widgets, and object systems.

 structure name


'''Structure keys:''''

Any characters can be used as keys for a structure (even binary).  A custom hash table is used, so the NUL character is valid in keys.


'''Setting keys in a Structure:'''

Here are some examples of setting keys:

 $s -foo bar
 $s -key value -anotherkey value

Usage of a named structure is like this:

 structure foo
 foo -key value


'''Getting key values from a structure:'''

 set s [structure]
 $s -key value
 # This prints value
 puts [$s -key]
 

'''Locking:'''

The structure extension supports locking of keys, key creation, and structures as a whole.


'''Global locking'''

This makes it so that no keys can be created or set, but key values may be retrieved as stated above.

 lock.structure $s

 unlock.structure $s


'''Locking keys to prevent modification'''

 lock.structure.keys $s -key1 -key2 ...

 unlock.structure.keys $s -key1 -key2 ...


'''Locking key creation'''

It can be useful for the construction of structures that are made available in a public API, to only allow certain keys to be set.  By locking key creation new keys will not be created.  This helps avoid errors.  For example if the user ran the following:

 $s -backgrnd 

instead of:

 $s -background

The unfortunate result would be that -backgrnd is set instead of -background.  Locking key creation prevents this error from occuring.

The usage is:
 lock.structure.creation $s

 unlock.structure.creation $s


'''Key traces'''

It's possible to setup the evalution of a callback script, whenever a key is modified.  If an error occurs in the callback it will be thrown as a background error.

 set s [structure]

 $s -text Hello

 proc text.modified s { puts "You changed -text." }

 trace.structure.key $s -text [list text.modified $s]

It's allowable to free a structure while in a callback.  The reference count of a structure is increased before the execution of any callback, and it will be freed upon the return of a callback, if free.structure was called in the callback.


'''Freeing a structure'''

After some experiments it was decided that having reference-counted collection of a structure would be difficult to achieve with a custom Tcl_ObjType, and the performance might suffer.  It's expected that structures will generally be retained for longer than the scope of a procedure.  In cases of a procedure that requires a structure to have limited scope, an array can be used.


The patterns to free structures are:
 set s [structure]
 free.structure $s 

 structure foo
 free.structure foo

''By George Peter Staplin''
-----

'''Comments:'''

----
[Category Package] [Category Data Structures]