The Tcl Hash Extension
		----------------------

Description
-----------
The Tcl "hash" extension creates commands that access Tcl's
hash table functions; it provides functionality that is similar
to Tcl arrays, except that the interface is via Tcl functions,
in a manner similar to the way Tk widget commands provide access
to window operations. Hash tables also have a number of features
not shared with Tcl arrays: they can provide a default value when
undefined table entries are accessed, and they can be made to have
a fixed set of entries. (This latter property makes them useful for
simulating C structs. See the "Examples" section below to get
a better idea of what the hash extension might be useful for.)


Installation
------------
The Tcl hash extension is TEA compliant, or very close to it.
Installation is via the usual sequence of:

	$ ./configure
	$ make
	$ make test
	$ su
	# make install

This will create an object file that can be loaded via the Tcl "load"
command; if properly installed, "package require Hash" will
load it automatically.

So far, I've only built and installed this extension on Linux
(RedHat 6.2) with Tcl8.4a1. Reports regarding installation on
other systems are appreciated; if you have problems with installation,
please let me know, especially if you have a fix for the problem. 

Licensing
---------
The license for the hash extension is essentially the same as the
license for Tcl itself; see the file "license.terms" for details.
In a nutshell, you can do anything you want with the code except
say that you wrote it, and I'm not responsible if it causes any
problems for you.

Examples
--------

To use hash tables as structs:

	% hash::create someStruct
	% someStruct contents {a 1 b 2 c 3}
	% someStruct configure -allowchanges false

The hash table "someStruct" will have three entries, "a", "b",
and "c"; the "-allowchanges false" configuration option prevents
the creation of new entries in the hash table, or the deletion
of the current entries, although the values for the current entries
may change. You may reference entries in the hash table with a
C-like notation if you wish:

	% someStruct -> a
	1
	% someStruct -> a = 1000
	1000
	% someStruct -> z = 10
	hash table is not modifiable
	% someStruct unset a
	Hash table is not modifiable

Note that the "z" entry can't be set and the "a" entry can't be
unset, since the hash table is not modifiable.

By setting the "-deleteproc" option, you can name a "destructor"
proc that will do any necessary clean up when the hash table
is deleted. For example, if we create a "struct" that in turn
contains a "substruct", we can have the substruct deleted when
the struct is deleted:

	% proc destructor {table} {
	    # Delete substructure so we don't leak memory
	    rename [$table -> sub] {}
	}
	% hash::create struct -deleteproc destructor
	% hash::create substruct
	% struct -> sub = substruct
	substruct
	%  hash::exists struct
	1
	% hash::exists substruct
	1
	% rename struct {}
	% hash::exists substruct
	0


To use a hash table as a lookup table with a default value, set the
"-missingentryproc" option:

	% proc missingVal {tabName entName} {
	     return $entName
	}
	%
	% hash::create almostIdentity -missingentryproc missingVal
	% almostIdentity set 1 100
	100
	% almostIdentity set -1 -100
	-100

The "almostIdentity" hash table will return the table index
for all undefined entries. In this case, we would have:

	% almostIdentity set 5
	5
	% almostIdentity set z
	z
	% almostIdentity set 1
	100
	%


Author
------
The hash extension was written by Neil McKay.


Reporting Problems
------------------
Report any bugs/problems to Neil McKay at:

	mckay@gmr.com, or
	mckay@eecs.umich.edu

I'll also consider enhancement requests, although I may not do
anything about them unless you submit the code for the enhancement.
(Actually, I may not do anything about them even if you DO submit
code, but if I don't do anything with your mods, I'll at least try
to give you a reason why I didn't.)


Bugs/Deficiencies
-----------------

The current version of the code does not have makefiles for Visual C++
or for Borland C. Since I don't have a machine running Windows,
I would appreciate it if some kind soul contributed these items.