			tclStruct
	A Tcl extension to provide access to 'C' data structures
		by Matthew.Costello@SanDiegoCA.ATTGIS.COM

This file provides a quick introduction to the tclStruct package,
a Tcl extension for accessing complex data structures.  tclStruct
is known to work with Tcl7.4 and Tcl7.5.  With Tcl7.5 it is a
loadable extension and so may be used with the tclsh shell as well
as any enhanced Tcl shells.

tclStruct provides for the definition and layout of 'C' or or
other binary structures, the allocation and deallocation of
memory objects, the construction and use of typed pointers,
and access to binary data using Tcl's associative arrays.


Commands
--------
tclStruct provides the following built-in commands:

  struct_typedef	Define a type.
  struct_untypedef	Remove an unused type definition.
  struct_new		Allocate an object.
  struct_info		Retrieve information about types and objects.
  struct_copy		Binary (fast) copy of objects.
  struct_read		Binary read of an object from a file.
  struct_write		Binary write of an object to a file.

It also provides the following commands written in Tcl.
  struct_hexdump	Hexadecimal and ASCII dump of an object.
  struct_show		Print the contents of any object.


Example
-------
The following example gives a small sample of what tclStruct
can be used for.
 
  struct qu {
    int index;
    struct spez {
       char name [20];
       char text[20];
       int kind;
    } spez[10],
      klass[10];
  }

The declaration for the above structure is created using
the struct_typedef command:

  struct_typedef spez {struct
    {char*20 name}
    {char*20 text}
    {int kind}
  }
  struct_typedef qu {struct
    {int index}
    {spez*10 spez}
    {spez*10 klass}
  }

To create the structure the struct_new command is used.  It optionally
takes a pointer to an existing C structure.

  struct_new frob qu

Access to members of the structure are done using Tcl arrays.
  set frob(index) 1
  set frob(spez.0.kind) 2
  set frob(spez.4.name.0) 'K'

Access to aggregate members is also possible.
  set frob(spez.4.name) 'The Name'
  set frob(spez.4) { bird "has wings" 6 }

Typecasts are also possible.  For debugging the content of structures
it always possible to typecast the whole structure to an array of hex
characters ...

  puts $frob(_hex_)


The Package
-----------
The tclStruct package includes complete manual pages and examples.
It also includes a test suite.  tclStruct uses the GNU autoconf package.

The tclStruct package is freely available under the same licensing
terms as Tcl.

