Re: I need simpler examples (was: RE: Enhancement request: enabling Variant in C parsers)

[Akim Demaille]

> Le 6 déc. 2018 à 23:07, Askar Safin <address@hidden> a écrit :
> 
> Hi, Akim.

Hi Askar!

>> I did look at it - this example scared me off c++ parsers :-(
> I completely agree.
> I will talk about Bison 3.2.2 manual.
> If the user looks in manual and tries to find some C++ example, then he finds 
> either too simple example ("10.1.1 A Simple C++ Example", which doesn't use 
> Flex), either mammoth big example ("10.1.7 A Complete C++ Example"), which 
> will definitely scary user away.
> Moreover, Bison is normally used with Flex. And unfortunately, Bison manual 
> gives only one Flex+Bison example, and this example is already mentioned big 
> scary "10.1.7 A Complete C++ Example".

This is the Bison manual, and we don't try to compete with the "flex & bison" 
book.  The purpose of this documentation is to document Bison.  We made efforts 
to give more examples to make things easier, but I don't plan to turn this 
documentation into an O'Reilly book.

> Okey, what to do? Well, we usually use Bison with Flex,

This is an overstatement.

Flex is often *advertised* in the context of Bison, but most of the real world 
examples I know do not use flex.  Most of the time, the scanner is written by 
hand.  I do not want to give the impression that Flex is needed in any way to 
use Bison, nor that it makes things easier.


> so manual should contain:
> 1. At least one example which shows how to use Bison parser in C language 
> with Flex. It should be as simple as possible.

There are already plenty of tutorials about that.  I don't see what it would 
bring to add one in Bison's documentation.  Besides, there are things that I 
don't want to show at all.  For instance, it's bad design to use non pure 
parsers, and the only reason we still have them is for compatibility with POSIX 
Yacc.  So if I were to add an example, I would be with a pure parser.  
Migrating from one model to the other is painful, let's show right from the 
beginning the right approach.

Besides, locations are also a key feature.  Since out there there are many 
examples that don't show how to track locations, and since it's a fundamental 
feature for any user-facing parser, we _have_ to show how it works.


> No location tracking, no everything. Bison should generate C code, and Flex 
> too. It will be used as starting point for C users.

Again, there are plenty of this on the Internet.

That being said, I can add a Flex+Bison example in examples/c.  That's where I 
think people should look at working examples.  But I certainly will not show 
impure parsers/scanners.

> 2. The same, but for C++. Bison will generate C++ code, and Flex too.

We are quite a few here to have some experience with Flex in C++, and it's not 
pretty.  Again, this is Bison's documentation, I don't plan to spend time and 
pages on documenting Flex.

> When I tried to understand Flex and Bison, I spent a lot of time trying to 
> figure everything out.
> 
> I just described bare minimum. Now I will describe my dream.
> 
> Ideally there should be many examples, which are different in this aspects:
> * Whether we use C or C++

What about Java?  And now D.

What about the semantic value storage?  %union?  Or api.value.type=union, or 
variant?

With, or without generated headers?

What about the *.output, *.xml, and *.dot output?

> * Whether we use Bison+Flex or just Bison

Why Flex only?  There is also POSIX Lex.

> * What build system we use (plain Make, Cmake or Autotools)

What about scons and the others?  At my previous job, we were also using 
"drake".

> * Other aspects, which require consistent changes to both Bison and Flex 
> files and thus can be hard to get right for beginners. Possible candidates: 
> whether we use location tracking, whether we use reentrant Bison parser etc
> 
> So far we got at least 2 * 2 * 3 * 2 * 2 = 48 examples and possibly more.
> 
> Ideally this should be public Web service, where a user configures his 
> example using some checkboxes, radiobuttons etc and then presses "Generate". 
> And the service generates the example for him. Personally I think that such 
> service will be *very* useful for users. This would be very cool if it would 
> be available when I tried to understand all this. I would run such Web 
> service if I would have free time.
> 
> If anybody here agree, please say "Yes, I need such service!" in the answer. 
> I hope that there will be a lot of us.

I'm not sure there's really a need for such a templating system, but once it 
exists, I will be most happy to use it to generate the flex+bison in C to add 
to examples/c, or to point Bison users to it.

Actually half of that generator exists in the Bison test suite: calc.at for 
instance generates many different flavors of the calculator to exercise Bison's 
features.  But you will have to add something similar for lex/flex.


> Also, this could be service which let you to create and edit your .y, .l and 
> .c (or .cpp) files simultaneously online and immediately see results. I. e. 
> something like https://jsfiddle.net/ , but with Bison + Flex + C/C++ instead 
> of HTML + JS + CSS. Of course, this service should come with some already 
> included examples. They should contain already mentioned 2 * 2 * 3 * 2 * 2 
> examples, as well as some more practical examples (toy C-like language, toy 
> Pascal-like language, etc)

A language repository would be a wonderful thing, I agree.  But who will 
maintain it?  Who will host it?

Cheers!