* 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.
