This directory contains a dynamically loadable tcl extension which
supports the manipulation of binary data.  This extension defines the
Tcl
commands binary_append for building binary data, binary_scan for
disassembling binary structures, binary_read for reading from files
containing binary data and binary_write for writing binary data to
files.  

The append and scan routines each accept format arguments which
determine what data is expected.  This format argument is a list of
codes which can include:


	b - the data is a single 8 bit byte
	h - the data is a 16 bit integer
	i - the data is a 32 bit integer
	f - the data is a 4 byte floating point number in whatever
	    format is native to the current machine.
	d - the data is an 8 byte floating point number in whatever
	    format is native to the current machine.
	s - the data is a null terminated string

In addition, structures can be read or written using a notation in
which < and > enclose a list of the structure components.  Each
component consists of a name followed by a colon, and then a type
signature for that component.  Components of structures can themselves
be structures or vectors.  When scanning structures, the components
will be stored in a single tcl array which is indexed by the component
names.

Vectors are indicated by a v, an optional count followed by the
element type enclosed in parentheses.  If the count is not given, then
it is assumed that the first 4 bytes of the vector will contain the
count.  When a vector is scanned, the elements are stored in a tcl
array in a manner similar to the way that structures are stored,
except that the indexes are integers.  Vectors are zero-origin, so the
first index is 0.  The number of elements is also stored under the
index count.

When structures and vectors are used recursively, the indices are
concatenated using a comma as a separator.  Thus a structure defined
by <first:i other:v3(d)> would have tcl index values of "first",
"other,0", "other,1", "other,2" and "other,count".

For now, scanning vectors and structures isn't fully supported.

Binary_scan accepts a first argument which is an offset at which
conversion should start and returns an offset where conversion left
off.  This returned offset can be used if successive elements of
binary data should be converted.  This makes it easy to use
binary_scan in (for instance) a loop.

			   Encoding Method

These routines all encode binary data so that Tcl doesn't have trouble
when it encounters null bytes.  The encoding used by all of the
binary_* commands is designed to avoid changing the length of the
encoded string as much as possible.  Since a null is quite common in
most binary data, this goal means that nulls have to be encoded in a
single byte.  This package encodes a null as 0x80, encodes 0x80 as
0x81 0x80, and encodes 0x81 as 0x81 0x81.  This has the virtue of
leaving strings containing ISO-latin, ASCII, EUC, GuoBiao, and Big5
unchanged.  I am unsure what will happen with Unicode encoded as
UTF-8, but 16 bit Unicode data should mostly not expand.


			  Command Arguments


binary_read fileID ?numBytes?
	reads all or part of a file and encodes it for safe
	manipulation by Tcl
	
binary_write fileID string
	writes a string to a file after decoding it.
	
binary_append var format value1 ... valuen
	adds encoded binary representations of the values according to
	the supplied format.  vectors and structures are assumed to be
	stored in Tcl arrays.
	
binary_scan offset format binary_value var1 ... varn
	reads encoded binary values from binary_value starting at
	offset.  the formats for the values are determined by
	examining format.  the places to put the values are determined
	by the variable names var1 through varn.  vectors and
	structures only need a single variable to hold them since they
	will be stored as a Tcl array.  binary_scan returns the offset
	of the first unconverted byte.