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.
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.
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.
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.
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.
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