[antlr-interest] A postmortem of my use of antler

[Kay Röpke]

Hi!

On Mar 10, 2008, at 9:29 PM, Benjamin Shropshire wrote:

> I don't want to be a troll so plese understand I'm trying to be  
> helpful with these comments, not antagonistic.

Thank you very much for taking the time to write this email, rather  
than just walking away! It _is_ helpful, indeed.

> The concept of ANTLR is a really good idea.
>
> The execution is fairly good (It could be better in a few places but  
> it's not worth complaining about.

Could you expand on the places you feel are sub-standard? It would be  
good to know so we can improve that, if possible.

> The documentation is abysmal.

I'm afraid you are right in some way. Not that I think it is really  
bad, because there is help available. The public documentation  
unfortunately is pretty sparse and is more or a reference.

> In my experience, ANTLR doesn't so much have a learning curve as a  
> learning step function. The documentation seems to assume a degree  
> of understanding of what antlr is that, IMHO, is unreasonable to  
> assume of a new user. In attempting to learn antler I was playing  
> with it, reading what docs I could find, looking for and reading  
> example code and looking at the output code.

Yes, the parsing has a rather ugly learning function, I agree. Though  
I think the approach you took is probably the best for any programmer:  
Start doing something and learn by making mistakes. Unfortunately,  
sometimes you can hit rather severe roadblocks when doing this with a  
grammar. It might simply choke on what you gave it and fixing that  
requires a fair amount of understanding of how it works internally.

> In all that, it took me over 2 weeks to even notice that the  
> expected mode of operation is to lex, AST, work with AST. I saw  
> mentions of AST and assumed that this was antlr's turm for the type  
> of output that yacc and bison typically are sued to generate. This  
> is just one example of a cases where the antlr docs seemed to assume  
> a understanding of things that I didn't have. And I'm not talking  
> general ignorance. I'm referring to ignorance of the specifics of  
> antlr. The best I can do to describe my frustration is this: "the  
> antlr doc's are not good enough to let a new user figure out what  
> questions to ask." I'm not so dumb that I can't figure antlr out  
> (theres nothing complicated with any part of it that I've used) I  
> just wasn't asking the right questions and had no way to find that  
> out.

What kinds questions are these? What cannot be figured out by reading/ 
searching the ANTLR wiki and/or posting to this mailing list? The  
archives generally turn up pretty good explanations, too, and are  
searchable via google.
But, with all due respect, the "expected mode" of a parser generator  
like ANTLR is to lex, parse, and do something with the resulting  
tree(s). Any kind of reading about the subject matter introduces the  
concept. Even for someone not having had the benefit of classes in  
university the wikipedia pages should provide enough information to  
figure that out. 2 weeks sounds excessive and exaggerated to me.

> Now I will confess that I have yet to read the manual cover to  
> cover, but I think I've hit all of the intro material in it and in  
> the web pages. If that material doesn't give the user something to  
> hold onto, I fear that many users a just going to give up on antlr  
> after only a few minutes to an hour. In retrospect that is what I / 
> should/ have done. My bosses opinion is that antlr is not giving us  
> much enough value over writing the parser by hand. I'm a bit  
> embarrassed to say, I think he's correct and I could have/should  
> have made that call a lot sooner.

I hereby question the boss' and colleague's opinions. For a very  
simple, one-time recognizers there might be truth in it, but if you  
expect to have to maintain the recognizers in the future, it's madness  
to not use some kind of generator. After all, writing correct  
recognizers is tricky, especially if the language isn't trivial.

> Now for some rhetorical questions:
>
> --What is ANTLR? Is it an academic research project? A source of  
> work for grad students? A FOSS utility intended for the general  
> community? A toy?

Warning: Rhetorical answers ahead!
It's
  a) A research project.
  b) Provides grad students with a tool they can use to learn about  
parsing.
  c) Provides grad students with a tool they can use to do more  
advanced work and not spend the entire class on implementing  
recognizers, so they can move on to implement languages/compilers/ 
whatever once they grokked parsing enough to understand the value of  
_not_ writing recognizers by hand.
  d) A FOSS utility intended for the general community, lowering the  
bar to write recognizers. Ever used and maintained a 15000 line yacc  
grammar?
  e) A high-quality tool widely used in the industry and open source  
community.

>
> --Who is the intended user base? It's own developers? Language/ 
> grammar theory people? Professional programming gurus? The  
> programming world at large?

Yes, yes, yes, yes ;)

> I don't need answers to those, I'd be interested but it's academic  
> at this point. If ANTLR is supposed to be what I think it's supposed  
> to be, I think that ANTLR would benefit by the consideration of  
> those questions.

I agree there's a need to lower the bar of entry even further, but I  
think no tool has lowered it to the level ANTLR has. At least not yet.

> My suggestion is that someone go over the docs with an eye to how  
> well they present material to a brand new users. Does it quickly  
> present the user with the information needed to (correctly) grasp  
> the big picture? What IS the big picture? Does it give the user the  
> information they need to find the information thy /really/ need?  
> This would be no trivial task and I understand that. What wold do  
> the most good would be to have about 1 or 2 dozen new users (a  
> compilers class?) be thrown at antlr with nothing but the current  
> docs to work from. let them play with it for about a day or two and  
> then start asking them what they found interesting/useful/confusing.  
> Then start answering there questions and /recording/ what they  
> asked, what they wanted to known (when these are different that is  
> valuable info). Also take notes on what kind of assumptions, correct  
> and incorrect they made. This info would be of huge value to the  
> ANTLR project.
>
> OK I understand that that project has about zero chance of  
> happening, but one can dream...

I don't think anything like that will happen, either. To use tools you  
need at least a basic understanding of the concepts. Don't need to be  
an expert, but understanding helps a lot. If someone does not  
understand the basics of parsing, it's kinda hard to write parsers,  
with tools or without.

> I hope this is of some use.

I hope so, too.

> p.s. I might get to use ANTLR on another project (only, oddly  
> enough, because the default rendering of AST looks like lisp)

Yeah, it's odd ;)

> p.p.s. Another guy on that last project (with a much different  
> personality than me) also took a look at antlr and more or less  
> agreed with me on the deficiencies of the antlr docs.

What is the background of those people? Is it just the docs? Is it the  
tool?

cheers,
-k
-- 
Kay Röpke
http://classdump.org/