Re: push parser documentation

[Bob Rossi]

On Sat, Aug 11, 2007 at 07:05:29PM -0400, Joel E. Denny wrote:
> On Sat, 4 Aug 2007, Bob Rossi wrote:
> 
> > +A push parser is typically useful when the parser is part of a 
> > +main event loop in the clients application.  Especially when
> > +the event loop needs to be triggered within a certain time period.  
> > +This is often the case with a GUI application.
> 
> "clients" -> "client's"

OK.

> The sentence starting with "Especially" is a sentence fragment.

OK.

> > +a pure parser (@pxref{Pure Decl, ,A Pure (Reentrant) Parser}).  The only
> > +time you should create an impure push parser is to have backwards 
> > +compatibility with the Yacc pull mode interface.  Unless you know
> 
> Let's say "with the impure Yacc pull mode interface".

OK.

> > address@hidden
> > +int yystatus;
> > +yypstate *yyps = yypstate_new ();
> > +do @{
> > +  yystatus = yypush_parse (yyps, yylex ());
> > address@hidden while (yystatus == YYPUSH_MORE);
> > +yypstate_delete (yyps);
> > address@hidden example
> 
> In this and your other examples, symbols named by users (yystatus, yyps) 
> should not start with yy.  The yy namespace is reserved for Bison symbols.  
> (I'll correct this in the test suite.)

OK.

> Also, the pure examples will not compile because they don't pass a 
> semantic value to yypush_parse.  Please test each of your examples.

Oops, you are right, ok, I compiled these.

> > +stream.  It is possible to yypush_parse tokens to select a subgrammar and 
> > +then yypull_parse the rest of the input stream.  If you would like to 
> > +switch back and forth between between parsing styles, you would have to 
> > write 
> > +your own yypull_parse function that knows when to quit looking for input.
> > +An example of using the yypull_parse function would look like this:
> 
> @code around the function names.

OK.

> > address@hidden {Function} yypstate_delete
> > +The function to delete a parser instance, produced by Bison in push mode; 
> > +call this function to delete the memory associate with a parser.
> 
> "associated".

OK.

> Please post an updated patch and then commit it.  Don't forget to update 
> the date in the ChangeLog entry.  Also, I believe the entry was wider than 
> 80 columns.  If you could reformat, that would be best.

OK, great! I've done all that. I don't have commit priviledges, so
here's the patch, please commit it.

> Thanks for all your hard work, Bob.

Well, I really appreciate all your work. I'm thinking this wouldn't have
gotten done otherwise!

What is next? I could provide an example for the manual if it's
necessary. What I'm really interested is getting push.c moved to yacc.c.
I'm not really interested in using this feature until I know it'll get
into the next version of bison.

Thanks,
Bob Rossi

2007-08-12  Bob Rossi  <address@hidden>

        * doc/bison.texinfo (Push Decl): Document the push parser.
        (Table of Symbols): Ditto.
        (Pure Decl): Ditto.
        (Decl Summary): Ditto.
        (Multiple Parsers, Push Parser Function, Pull Parser Function, 
        Parser Create Function, Parser Delete Function):
        Add new push parser symbols.
        (Table of Symbols): Document push-parser, push-pull-parser, 
yypush_parse,
        yypull_parse, yypstate_new and yypstate_delete.

bison_doc.diff
Description: Text Data