# $Id: README,v 1.2 1998/04/29 06:34:46 jake Exp $ 

                       Perl 5 Byacc Patches 0.6
                       ------------------------

This is a set of patches to perl-byacc1.8.2 which cause it to generate a Perl 5 class implementing a parser (instead of a file full of global data and procedures). It's nice if you want to be squeaky clean, and very nice if you have a need for multiple parsers or multiple instances of a parser in one program.

How to install it

  1. Get perl-byacc1.8.2 and unpack it. See

http://www.perl.com/CPAN/src/misc/perl-byacc1.8.2.tar.gz

2. Patch byacc with 

     cd perl-byacc1.8.2
     patch < ../perl5-byacc-patches-0.6/patch

3. Compile perl-byacc1.8.2 as usual.

How to use it

You invoke byacc a little differently:

  1. -P now takes a package name argument, and the output file is written as {package name}.pm.
  2. You can pass a -5 argument to get a somewhat faster parser under Perl 5.005 (using 'my Dog $spot' and 'use fields'). By the way, parsers generated with these patches are thread-safe (all package variables are static data), although of course you will break that if you do something non-thread-safe in your lexer or actions.

You must write your parser a little differently:

  1. Your &yylex and &yyerror procedures can (optionally) take an extra argument, which is passed from &yyparse (see below).
  2. Your &yylex procedure no longer side-effects $yylval; instead, it must return a list containing the token and the value.
  3. Your top-level rule can assign a value to $$, and this value will be returned as the value of &yyparse (see below).

And you must write the code that uses the parser differently too:

  1. Use 'use Parser' (or whatever package you put in -P) instead of 'require "y.tab.pl"'.
  2. Create a new parser object with

    $p = Parser->new($yylex, $yyerror, $yydebug);

    The first two arguments are references to your &yylex and &yyerror procedures, respectively. The third is true or false to enable or disable debugging output.

    Although you may wind up sticking your &yylex and &yyerror in the parser package in most cases, this is more composable if you want to do something weird.

  3. Start a parse by calling

    $val = $p->yyparse($s);

    Here $s is an optional "stream" argument which represents the state of the text you're scanning. Depending on what you want to do, this could be a filehandle reference, a string, some object you cooked up, or whatever.

    The argument is passed down to &yylex and &yyerror. &yylex should use it to get characters, and &yyerror should examine it to generate a meaningful message.

  4. $p->yyparse returns the value that your top-level rule assigned to $$, instead of true or false to indicate success or failure. This obviates the need to side-effect global variables to return values from the parser. You should use exceptions to handle error conditions.

Example

I've include two examples: an ultra-simple calculator and a random text generator. Type 'make' to build the parsers.

Copying

This code is in the public domain--use it and redistribute it as you like. I would appreciate acknowledgement of some kind (or at the very least an email) if you use it in something that is widely used or distributed.

Bugs and feedback

Send them to Jake Donham (donham@linex.com). I'd love to hear from you if you find these patches useful.