So today I am looking at this thing called ANTLR. It's an LL parser generator, at first glance it seemed to be a bison/flex alternative with a more modern toolset. I look at it a bit more and am actually very impressed-- it appears to offer significantly less nonsense than some other compiler compilers, it supports more than one language within a single toolset*, and it
comes with this super fancy IDE for writing grammars. I'm happy. I write a grammar.
Then I start trying to integrate the C target into my program.
I almost immediately discover that the C target documentation CONSISTS ENTIRELY OF LIES. There's a main document which is on the website and included with the source as a .doxy; almost every line of this document refers to at least one function that doesn't exist. Ancillary documentation on the website apologizes for its own state of disrepair, then refers you to the examples. It doesn't
link the examples, but with some hunting they turn out to exist on github; they don't compile. A wiki exists, but appears to be years out of date and contains many statements like "when the C++ target is completed in late 2008...".
What I
think happened, judging from some things I accidentally stumbled across on the mailing list, is that at some point whoever maintains the Antlr C target refactored all the code, overhauled the API, and renamed everything, but then didn't change any of the documentation to reflect their changes. If this is the case, this seems to indicate that I can avoid these problems if I simply downgrade to whichever version of Antlr is accurately described by the documentation; unfortunately, I'm given little clue
which version that might be.
* At first I thought this was the coolest thing about the tool, in retrospect it probably should have been a red flag. "Supports more than one language target" probably necessarily means "some language targets are better supported than others". This at least seems to be the case here, it appears the Java target is the "main" one and most of the others just scramble to keep up using contributions from random volunteers.