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

[Akim Demaille]

> Le 8 déc. 2018 à 17:06, Askar Safin <address@hidden> a écrit :
> 
> Hi, Akim.

Hi Askar!

>> This is the Bison manual, and we don't try to compete with the "flex & 
>> bison" book.

> I tried to websearch this book and found it in Google Books. Google Books 
> showed me preview and suggested to buy full copy. Also I found some free 
> online full copy, but I wonder whether it is legal. So, it seems this book is 
> not free (I mean free as free beer). And also it seems it is not free as in 
> freedom. So, it seems that if user has problems with understanding how Flex 
> and Bison work (they are both free software), you suggest them go read 
> non-free book. You said you don't try to complete. Well, you should do 
> exactly this: complete with non-free documentation. What Stallman would say?

Since he is one of primary authors of the book, I'm not sure his opinion would 
differ from mine :)

Askar, please note that this is the *documentation* of Bison.  We already make 
effort to also be a tutorial, but that's not the point of documentation.  
You'll have a hard time learning C reading GCC's documentation.

We do make efforts to make things more readable and nicer to read, but don't 
expect a documentation written by someone who is spending his free time to 
maintain free software to compete with books that make money.


> Even if you don't agree with me, well, at least, please, insert a link to the 
> manual pointing to that book.

I'm not sure Richard would agree on this.


>> 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.
> I still think that the manual should give at least one C+Flex+Bison example 
> without locations and at least one "C++"+Flex+Bison example without locations.

I will not agree for two, but if you keep on insisting, then I guess the 
example in C will be without locations, ok.

> Just because the user should have something simple to begin with.

That's not so obvious.

Bison+Flex require way too much boilerplate, granted.  But in my experience, 
it's easier in the long run to start from a fully featured full example rather 
than starting with something smaller, and have to retrofit things like 
locations.

So I still believe the documentation, with rpcalc and mfcalc are the simple 
examples you are asking for, and then the flex example (in examples/c, not in 
the documentation) should be good starting points, with locations.


> Okey, I agree, that this examples should be pure. If you add them to 
> /examples/, then, please, link them from the manual.

You are right.  I have to find where exactly.  Suggestions welcome.

> Even if you will not add examples, please, insert a link to some external web 
> page, where users can view them.

This is tricky.  The idea is good, but I'm not sure how to do it.  However, the 
real value is when you go there and run the examples.


>> Again, there are plenty of this on the Internet.
> No. When I first decided to write Flex+Bison+"C++" parser, I didn't find 
> anything useful in internet.

Ok, I really thought you were referring to C, not C++.  Yet I'm amazed by the 
number of pages you managed to compile.


> Right now I repeated my websearch and didn't find anything useful again. What 
> I want is "C++"+Flex+Bison example, which contains nothing on top of 
> "C++"+Flex+Bison. In particular it should not contain any "driver classes", 
> nor it should contain any other code, which is not needed for example.

Unfortunately I'm not sure we can have a real world example that works without. 
 Flex's interface requires that we have a means to open/close the streams.  We 
need to share the error handling (syntax_error does help here though).

A simpler example would "paint the user in the corner".


> This is first 6 links in Google search "c++ bison flex example" from my 
> computer:

Thanks for this.  I'll have a look at them, time permitting.

> You may say that driver is useful. Well, yes, probably. But I still think 
> that a user should see example without any driver just to understand how the 
> example works.

Let him read the C examples then.

> Also, it is possible the user have already working parser written in C. And 
> he wants to know what exactly he should change to turn it into C++ parser 
> (also let's assume he wants to use C++ semantic values with non-trivial 
> destructors etc, so just processing Bison output with C++ compiler is not 
> enough).

I agree paving the path of C to C++ would be nice.  But I still disagree on the 
relevance of such an example _in Bison's documentation_.  You are most welcome 
to add your own tutorial on the Web, with what you think is the right approach.


> Well, I am not trying to say that I am too stupid to understand driver class. 
> I just want to say that first I want to see example without driver class, and 
> only after that example with driver class.

I wish there was no driver at all.  I just don't see, currently, how to do that 
cleanly.  If the user was able to push methods into the parser, we could 
probably do that.  But so far I'm the only one to contribute code, and my 
throughput is limited.


> Here is how I would write C++ example: 
> https://paste.gg/p/anonymous/ad450c26fd6d443b900fbc36f4eb599e . It is 
> possible I did something wrong. Well, my example just to show you what size 
> C++ example should have. I don't claim the example to be perfect. I tested 
> it, and it works.

You didn't specify %require "3.2", so you still have stack.hh.  What's the 
point of lex.yy.hh?


> * As you can see, this is bare minimum. There is only two files, not counting 
> Makefile!
> * My example seems to be pure parser

It is.

> * I warned the user that Flex processes C++ code, but is run in C mode, and 
> thus thinks that it processes C code (your example does the same, but you 
> didn't warned user about this)
> * I give exact command lines to run my example, you don't

It's an ongoing effort.  If you look the history of the examples you'll see 
that they are getting Makefiles and READMEs.  In particular calc++ has its 
Makefile, so your comment is quite inaccurate.


>> Why Flex only?  There is also POSIX Lex
> Is there any lex implementation in use today not counting flex?

I mean POSIX Lex, the specification, just like POSIX YACC.  There is no 
implementation which is strictly about POSIX Yacc, as far as I can tell (I 
believe byacc and bison are the only ones in this game), yet to some people it 
matters to stick to POSIX.

When I was younger, yes, there were several lexes, for the instance Solaris'.  
I don't know if it is still running.