grayz.zip contains the following files

grayz.fth - the common file, equivalent to gray5.fs without any generating code
graygen.fth - contains the generating code from Gray5
              i.e. grayz.fth + graygen.fth (+ sets.fth) is functionally
              equivalent to gray5.fs
forthgen.fth - contains the generating code for a parser in Forth. It must be
              compiled after grayz.fth instead of graygen.fth

Various library files:
   - ansify.fth
   - files.fth
   - lexscanner.fth
   - list.fth
   - sections.fth
   - sets.fth   (this was originally extracted from gray4.fs)
   - xmini_oof.fth

The example is taken from mini.fs that came with gray4 originally. There are
three loader files:

1)  minigray.fth that includes and runs grayz + graygen
2)  minifgen.fth that includes and runs grayz + forthgen to generate a
                 mini parser
3)  minigo.fth that runs the mini parser with the same test file as 1)

Directory mini holds various files for mini, including the generated
miniparser.fth (not included in the zip file)

To run the programs with GForth:

1) Unzip the files into a directory called, say, grayz under Gforth
2) Run Gforth and type:
            s" grayz\minigray.fth" included
   to compile and run mini
3) Run Gforth again and type:
            s" grayz\minifgen.fth" included
   to generate miniparser.fth in the mini directory
4) Run Gforth again and type:
            s" grayz\minigo.fth" included
   to run the generated mini parser/compiler

The user interface
~~~~~~~~~~~~~~~~~~

When generating the parser the user must (e.g. see minidefs.fth):

1)  Call max-member to establish the set size
2)  Name the word to be called to check the current symbol and get
    the next symbol. This is done by a call to terminal e.g.
         25 singleton s" ?nextsym" 0 terminal
    i.e. calling terminal with a string and zero xt. This needs to
    be done for every terminal.
3)  Provide equivalents to copyToPad and genForth as given in minidefs.fth

(Note to self - best to put copyToPad and genForth into forthgen.fth??)

When running the parser the user needs to provide four values which are set
by the generated parser:

      bytes/set
      bits/cell
      first-set
      parser-name

Also the following words must be defined:
      test-token testsym?
and whatever the user has defined as the name to check and get the next symbol
e.g.  ?nextsym

Example definitions for these are: (assumes variable sym holds the token value
for the current symbol)

: test-token  ( n -- f )  sym @ = ;

\ This version of testsym? written for multi-cell sets. It can be slightly
\ simplified for sets occupying 1 cell

: testsym?  ( set-index -- f )
   bytes/set * first-set + >r          ( -- )     ( R:  -- ad )
   sym @ bits/cell /mod cells r> + @   ( -- bit vec )
   1 rot lshift and                    ( -- f )
;

: ?nextsym  ( f -- )    \ Used for check&next in Gray terminals
   0= abort"  Syntax error"
   get-next-symbol \ Call lexical scanner to get the next symbol/token
   sym !
;
