THIS FILE WAS NOT WRITTEN NOR ENDORSED BY THE AUTHORS OF BISON. IT IS
WHOLLY THE PERSONAL OPINIONS AND OBSERVATIONS OF STEVE A FINK
<sfink@cs.berkeley.edu>, THE AUTHOR OF THE PERL-RELATED
MODIFICATIONS. ALL INACCURACIES AND MISCONCEPTIONS ARE HIS
RESPONSIBILITY ALONE.

One of the most frequent activities of a programmer appears to be
reinventing wheels. We all know that we should be building on top of
other people's code, but it seems easier or at least more gratifying
to charge ahead and do it all again. At the same time, most of us
think that everyone *else* should be using our code instead of
rewriting it from scratch. Besides, reusing code can be quite
difficult -- it may be written in a different style, poorly
encapsulated, or just applicable to a slightly different problem.

Since programmers cannot be cured, this file is intended to make the
accompanying code easier to reuse. Bowing to the inevitable, I will
not force the user to reuse all my code or none of it; instead, this
file is an attempt to point out the pieces which might be easier or
harder to break out from the whole and salvage.

----------------------------------------------------------------------

This file is for perl-bison, based on bison v1.25 with minor
modifications to generate perl parsing code. I have attempted to
describe the bison portions as well as the perl modifications, but I'm
actually writing this over a year after I wrote my modifications, so
my memory is quite vague.

Fragments:

LALR parser building -- The code is quite dense and requires detailed
study to figure out what the heck is going on. Lots of densely packed
C structures and things. You'll probably need the dragon book to make
any sense of what's going on. (Ug, I don't have my copy with me right
now, but hopefully you know what I mean.) If you stare at the code for
long enough, you may end up admiring the efficiency and terseness as I
did -- but it's still a pain to interpret, modify, or extract.

Yacc file parser -- Unfortunately, the .y file parser is not written
in yacc (or bison). Instead, it appears to be completely
handcoded. See comments above.

Generated parser -- The main body of a generated parser is in the file
bison.simple (bison.simple.perl for the perl parser). bison.hairy
contains a more capable parser, but it appears to use some features
which are not yet implemented. The parsers are a mass of embedded
gotos and inline compressed table lookups, but are still fairly
understandable. I once attempted to expand bison.simple into goto-free
code, but it seemed to quickly get rather ugly. Maybe state machines
really should be implemented with gotos, even if they make my flesh
crawl.

Perl additions -- All other perl-related modifications are tightly
tangled up in the C-related code. Eventually, I hope to split the C
and perl code parsing and generation fragments into independent
modules (thereby making it much easier to add further languages), but
don't hold your breath.

Sorry I couldn't be more helpful, but I promised myself I'd at least
include a SALVAGE file with everything I release publicly. Good luck,
and happy hacking!

		-- Steve A Fink <sfink@cs.berkeley.edu>, 16 Mar 1998
