### rbison-0.0.7 README file

    * What is rbison?

    rbison generates a Ruby parser class from a Bison-like specification
    file. rbison uses Bison to do all the hard work (generating state
    tables, transition tables, etc.), then translates the Bison-generated C
    code into a class for use in other Ruby code.

    * Why rbison?

    Because it uses Bison directly, rbison should produce good parsers.
    Bison is stable and robust. Bison produces fast parsers. rbison should
    inherit those attributes, once the code has stabilized a bit. Moreover,
    Bison users will feel at home, since rbison uses a nearly identical
    parser specification format (see below).

    * rbison DEPENDS ON Bison!

    !!! READ ME READ ME READ ME !!!

    rbison uses Bison. This version was developed using GNU Bison version
    1.28. It may work with other versions.

    * Installation and Usage

    Installation is simple:

         cp rbison /usr/local/bin/

    You may have to change the first line of the script to match ruby's
    location on your box (if it's something other than /usr/local/bin/ruby).

    Usage is equally simple:

         rbison <infile> <class> > <outfile>

    where infile is the Bison-like specification file, class is the desired
    name of the parser class, and outfile is where rbison should dump the
    Ruby code. See calc.ry for an example specification file.

    Using the generated parser is easy:

         require "FooParser"
         p = FooParser.new
         p.yyparse(<FooLexer object>)

    The FooLexer object can be of any class, as long as yylex is implemented
    and returns [token, value] pairs at each call. To tell the parser that
    the end of input has been reached, yylex returns [-1, nil]. See
    CalcFileLexer.rb for an example lexer class.

    If you want Bison-like debugging output, simply do:

         require "FooParser"
         p = FooParser.new
         p.yydebug = true	## debug
         p.yyparse(<FooLexer object>)

    * How does rbison differ from Bison?

    rbison uses Bison directly to generate a Ruby parser class. The
    specification file format is nearly identical, but there are three
    important differences:

         1. To use Bison semantic value variables ($$, $1, $2, etc), you
         MUST prepend an underscore (_$$, _$1, _$2, etc).

         2. Rule actions and code declarations (between %{ and %}) contain
         Ruby code, *not* C code.

         3. yyparse takes an object argument. That object must implement
         yylex, which you must write yourself. Each call to yylex returns a
         [token, value] pair. See CalcStringLexer.rb for an lexer class that
         implements yylex. rbison expects yylex to raise the LexError
         exception on error.

    * How do I write a parser?

    See the Bison info pages. Most Bison options and features will work with
    rbison. Remember that you need to use Ruby code in the action, code
    declaration, and additional code sections.

    * This seems a little complicated. Can you give me an example?

    Sure. calc.ry contains a sample Ruby parser specification for an infix
    calculator (lifted from the Bison info pages). To try it out, do:

         rbison calc.ry CalcParser > CalcParser.rb
         ruby calc_test.rb

    * Error notification and recovery.

    rbison supports the Bison parse error recovery mechanism. See the Bison
    info page topic "Error Recovery" for more information. For example
    usage, see calc.ry, as it now contains several error handling rules. An
    irrecoverable parse error throws the exception ParseError.

    Errors can also occur during lexical analysis. rbison expects yylex to
    throw LexError on error.

    * Debugging your parser.

    After creating a parser object p, do:

         p.yydebug = true

    That will give you lots of helpful debugging output on stderr.

    It is possible to shift debugging output to streams other than stderr,
    by setting p.yyerror:

         p.yyerror = $stdout

    That will send all debugging output to stdout instead of the default
    stderr.

    * How to get rbison.

    The latest release of rbison is available at:

         http://www.cs.umass.edu/~aseltine/rbison.html

    * Found a bug?

    Let me know. Please make sure it has nothing to do with your yylex. Send
    the specification file (.ry), lexer, and an input file that exhibits the
    bug to:

           aseltine@cs.umass.edu

    I will also accept fixes for bugs. ;-)

    * Copying

    rbison is copyrighted free software by Jonathan Aseltine
    <aseltine@cs.umass.edu>.  You can redistribute it and/or modify it under
    either the terms of the GPL (see COPYING file), or the conditions below:

      1. You may make and give away verbatim copies of the source form of the
         software without restriction, provided that you duplicate all of the
         original copyright notices and associated disclaimers.

      2. You may modify your copy of the software in any way, provided that
         you do at least ONE of the following:

           a) place your modifications in the Public Domain or otherwise
              make them Freely Available, such as by posting said
    	  modifications to Usenet or an equivalent medium, or by allowing
    	  the author to include your modifications in the software.

           b) use the modified software only within your corporation or
              organization.

           c) rename any non-standard executables so the names do not conflict
    	  with standard executables, which must also be provided.

           d) make other distribution arrangements with the author.

      3. You may distribute the software in object code or executable
         form, provided that you do at least ONE of the following:

           a) distribute the executables and library files of the software,
    	  together with instructions (in the manual page or equivalent)
    	  on where to get the original distribution.

           b) accompany the distribution with the machine-readable source of
    	  the software.

           c) give non-standard executables non-standard names, with
              instructions on where to get the original software distribution.

           d) make other distribution arrangements with the author.

      4. You may modify and include part of the software into any other
         software (possibly commercial).

      5. The scripts and library files supplied as input to or produced as
         output from the software do not automatically fall under the
         copyright of the software, but belong to whomever generated them,
         and may be sold commercially, and may be aggregated with this
         software.

      6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
         IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
         PURPOSE.