![packages icon](/images/packages-icon.png)
* 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.