FreeCC Parser Generator 0.9.3, released 13 January 2009

This is the fourth publicly announced release of FreeCC, labelled as version 0.9.3. Version 0.9 was released on 2 October 2008, Version 0.9.1 on 22 October 2008 Version 0.9.2 on 19 November 2008.

Version numbers are quite arbitrary, of course. This one is somewhat misleading as regards the maturity of the tool. FreeCC is based on forking the JavaCC codebase in April of this year, which is basically the same code that was released soon afterwards as JavaCC version 4.1.

Hence, FreeCC version 0.9.x is a more advanced version of the JavaCC tool which is labelled 4.x. In fact, if this work had been done as part of the JavaCC project, it would be a preview release of JavaCC 5.0.

Changes since the last release

Perhaps the most noticeable aspect of this release is that various out of the box defaults have been changed. Now tree building is on by default. If you do not want tree building to be enabled, you have to disable it explicitly by setting TREE_BUILDING_ENABLED=false. Also, MULTI and TOKENS_ARE_NODES are set to true by default. Note also, that with the MULTI setting as true (the default) subclasses of Token are generated for the various different types of Token. Also, since TOKENS_ARE_NODES is true by default, these Token subclasses are inserted in the generated AST.

A very major bug has been fixed. In earlier FreeCC releases, IGNORE_CASE did not work. This was due to a silly typo in the template that generated the lexer code that was only hit when the lexer did case-insensitive matching.

The Node API has been reworked significantly. Also, a Nodes class is now generated that is a holder for various static utility routines, mostly related to traversing trees of Nodes.

Some start has been made on the documentation front. See the docs directory. It is extremely incomplete. Really, all there is right now, is an early draft of a "Getting Started" Tutorial. Still, it is better than nothing, and should help many people to get their feet wet. I am eager to get any feedback I can on this.

Getting Started

How you would best go about getting started will, I think, depend greatly on your level of prior experience using JavaCC specifically, and/or other similar sorts of tools. Besides that, it depends on your learning style.

If you are new to JavaCC...

Personally, I began using JavaCC at some point in 2001. At the time, I had basically zero experience using this kind of tool. Nonetheless, if memory serves, I got going with it fairly quickly. Even though the documentation was extremely sparse (and still is) it was fairly easy to get going with it simply by mucking about with the simple examples that came with the tool. See the Simple1.freecc, Simple2.freecc, and Simple3.freecc that are in the examples/SimpleExamples directory. I found that by simply experimenting using these trivial examples as a starting point, I was able to expand my knowledge and gain some sense of comfort fairly quickly. Oddly enough, even though JavaCC's main competitor, ANTLR, has much more documentation, I found that it presented a much steeper learning curve.

I believe that the best materials available online for familiarizing yourself with JavaCC would be the FAQ and tutorial by Theodore Norvell.

If you are an experienced user of JavaCC...

People who are already comfortable using JavaCC should have little trouble getting started with FreeCC. In this case, you will be most interested in seeing what features FreeCC offers beyond what is in JavaCC. A good starting point is this Wiki page. You should certainly have a look at the page on code injection as well as the page that describes tree building enhancements in FreeCC.

Some of the examples have been reworked to show how these new features such as code injection can be put to good use. The simplest example to examine would be examples/TreeBuildingExamples/eg2.freecc, an example that is included with JavaCC, but here, has been rewritten to use code injection. You can then move on and look at eg3.freecc and eg4.freecc to see some other, still quite simple, examples of how the INJECT instruction can be used.

A much more involved example of the use of new FreeCC features is in the src/grammars directory. This contains a modified version of the Java 1.5 grammar included with JavaCC.

Also, you would do well to take a look at the FreeMarker example under examples/freemarker. This contains a new FreeMarker grammar which will supplant the existing one in the FreeMarker 2.4.x release cycle.

Please Join the Community

While there is no obligation, of course, FreeCC users are strongly encouraged to subscribe to the freecc-devel mailing list. You can do so here. I am very interested in receiving user feedback on this work.

Jonathan Revusky
Palma de Mallorca, Spain
January 2009