COMPATIBLE STRUCTURES 1.0.1--README

This distribution is a revision of our earlier "Compatible
Structures in ANS Forth" distribution dating from July, 1995. 
The revision grew out of a general uneasiness with the
complexity of that work.  There is essentially no change in the
code itself, just a reorganization.

Complexity is inevitable in a project which aims for
compatibility with C/POSIX structure layouts, both because of
the richness of the standard C specification, and because of the
system dependence in its implementations.

On the other hand, the core of our code is based on an
implementation of structures in Pocket Forth by Randolph M.
Peters, which is elegant and fairly simple.  In our opinion,
Peters' code satisfies the Forth simplicity imperative, although
there are even simpler implementations [e.g., Ertls, Hayes?] 
that are well-suited to many Forth contexts.

Beyond the Peters core, we describe the sources of complication
in our code as follows:

1.  More kinds of structure fields.  With the exception of
bit-fields, and to a lesser extent arrays, this involves no new
ideas, and is mostly straightforward and easily elaborated by
the user for special situations.

2.  Alignments.  Serious functionality when it is needed, but
complicates the code very little.

3.  System interface.  Related to both of the above, this also
complicates the code very little.

4.  Arrays.  As usual in Forth, a real but small complication
with only a little code.

5.  Bit-fields.  A serious complication, and in our opinion not
that useful.

6.  Unions.  Very little marginal impact on the code.

7.  Bracketed field references.  This automates variable numbers
of arguments for data references in nested substructures,
including incomplete chains.  Very little cost in code.

8.  Early binding.  Straightforward, just uses a little code
space.

9.  Both left and right field reference syntax.  The right field
syntax is more awkward for us, but still doesn't cost a lot of
code.

10.  Design documentation.  This is the major complication,
because the layout of C structures is a complicated subject. 
It's not rocket science, but the simple collection of
information is already a big task.  Although the final design is
not that complicated, it still takes some description.

The upshot is that complication in the code, with the exception
of bit-fields, is mainly an accumulation of small complications,
which are commensurate with added functionality.  The most
complicated part is documentation of the design.  The syntax for
using the words is pretty normal.

To deal with this, we have separated the general design and
usage documentation from the code, and we have organized the
code into sections that can be conditionally compiled, depending
on what features are needed. Documentation of implementation
details is included with the code.

I make no claim that the source code represents the best Forth
style.  It contains at least one outrageous thing (see the word
FLIP-PARMS).

Here is the list of files in the main distribution directory:

cstruct.fs      ANS implementation of C-compatible structures.
machine.fs      System interface for GNU CC with Motorola 680x0 cpus.
examples.fs     Peters' structure examples in our language, including
                  early binding.
shotype.fs      A structure/union type browser with examples 
                  including bit-fields.
README          This file.
cstruct.pdf     PDF version of the design documentation, configured
                  for screen viewing, with links.
cstructpr.pdf   PDF version of the above configured for double-sided 
                  printing.
COPYING.LIB     LGPL version 2.1.
POLITENESS      A request about licensing modifications.

LaTeX source files for the PDF's are in the docsrc subdirectory. 

David N. Williams
July 16, 2000