When is on_error supposed to be called?  Will on_error be called when
the error rule is triggered?

After reading the lex/yacc book, it seems as though the error rule is
supposed to eat up tokens until it can find a pivot token.  But is
on_error supposed to be called?  I did a couple experiments and found
that on_error is not called if the error rule matches only one token,
but if it matches many tokens on_error is called.

Consider the following grammar:

  class Tester
  
    token A LBRACE
  
  rule
    a_a_lbrace
      : A A LBRACE { puts val }
      | A error LBRACE { puts "recovered"; puts val }
      ;
  
  end

and the following script:

  class Foo < Tester
    def initialize
      @tokens = [
        [ :A, 'a' ],
        [ :b, 'b' ],
        [ :LBRACE, '{' ],
        [ false, false ],
      ]
    end
  
    def parse; do_parse; end
  
    def next_token; @tokens.shift; end
  
    def on_error(*args)
      puts "on_error called"
    end
  end
  
  Foo.new.parse

on_error does not get called, but the recovery rule matches.  However,
change the tokens to this:

      @tokens = [
        [ :A, 'a' ],
        [ :b, 'b' ],
        [ :b, 'b' ],
        [ :b, 'b' ],
        [ :LBRACE, '{' ],
        [ false, false ],
      ]

on_error gets called *and* the recover rule matches.  It seems on_error
gets called if the error rule matches >  1 token.  Is that expected
behavior?  Am I using the error rule correctly?

Any help would be greatly appreciated.  Thanks!

-- 
Aaron Patterson
http://tenderlovemaking.com/