| 1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<html> |
| 3 |
<head> |
| 4 |
<title>JTB 1.4.11</title> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| 6 |
<style>@import url("web/site.css");</style> |
| 7 |
<STYLE type="text/css"> |
| 8 |
BODY { font-family:Arial,Helvetica,sans-serif; font-size:10pt; color:#006666; } |
| 9 |
h1 { font-size:14pt; } |
| 10 |
h2 { font-size:12pt; } |
| 11 |
table { font-size:10pt; } |
| 12 |
</STYLE> |
| 13 |
</head> |
| 14 |
<body> |
| 15 |
<h1><font color="red">Java Tree Builder (JTB) 1.4.11</font></h1> |
| 16 |
|
| 17 |
<h2>Last update : apr xxth, 2016 - version <font color="red">1.4.11</font></h2> |
| 18 |
|
| 19 |
<h2>Overview</h2> |
| 20 |
<font color="red">JTB</font> (Java Tree Builder) is a syntax tree builder and visitors generator to be used |
| 21 |
in front of <a href="http://javacc.dev.java.net">JavaCC (Java Compiler Compiler)</a>.<br> |
| 22 |
|
| 23 |
It takes a JavaCC grammar file as input (you just have to change the extension from |
| 24 |
"<font color="red">.jj</font>" to "<font color="red">.jtb</font>" and add a few options) and it automatically |
| 25 |
generates the following: |
| 26 |
<ul> |
| 27 |
<li>a set of syntax tree classes based on the productions in the grammar, |
| 28 |
utilizing the Visitor design pattern;</li> |
| 29 |
<li>four interfaces: <font color="red">IVoidVisitor</font>, <font color="red">IVoidArguVisitor</font>, |
| 30 |
<font color="red">IRetVisitor</font>, <font color="red">IRetArguVisitor</font>;</li> |
| 31 |
<li>four depth-first visitors: <font color="red">DepthFirstVoidVisitor</font>, |
| 32 |
<font color="red">DepthFirstVoidArguVisitor</font>, |
| 33 |
<font color="red">DepthFirstRetVisitor</font>, <font color="red">DepthFirstRetArguVisitor</font>, |
| 34 |
whose default methods simply visit the children of the current node;</li> |
| 35 |
<li>a JavaCC grammar "<font color="red">.jj</font>" file (<font color="red">jtb.out.jj</font> by default), |
| 36 |
with the proper annotations to build the syntax tree during parsing (which then must be compiled with JavaCC).</li> |
| 37 |
</ul> |
| 38 |
|
| 39 |
New visitors, which subclass any generated one, can then override the default methods and perform various |
| 40 |
operations on and manipulate the generated syntax tree.<p> |
| 41 |
|
| 42 |
JTB can be compared to JJTree in the following way:<ul> |
| 43 |
<li>in JJTree you explicitly define the nodes you want to build; in JTB it builds by default all of them |
| 44 |
(but you can tell not to build some of them),</li> |
| 45 |
<li>JJTree generates only interfaces for visitors and you have to code the visitors, so you "fill" them; |
| 46 |
JTB generates interfaces and "full" visitors (i.e. with all the code to visit the tree), so you just |
| 47 |
"modify" them, sometimes just "reducing" them (for not visiting branches), so in a sense it is faster to |
| 48 |
develop on an already generated - bullet proof - code,</li> |
| 49 |
<li>in JJTree, you are tempted to tune the tree, i.e. define only the nodes you need, but if you want to |
| 50 |
develop different visitors, you have to think about all the nodes you want to traverse for the different |
| 51 |
purposes and so you may find yourself sometimes having to enrich the grammar and defeat what you have |
| 52 |
previously done; in JTB you have all the tree right from the beginning so adding a new visitor is not |
| 53 |
disruptive,</li> |
| 54 |
<li>JTB can "inline" the accept methods, i.e. it generates for a node the code to work directly on its |
| 55 |
children, which is usually the right place to take decisions and to reduce the control logic (otherwise |
| 56 |
you usually have to access the fathers and check their types),</li> |
| 57 |
<li>JJTree may be more adequate when only small trees and few visitors are needed; JTB may be more adequate |
| 58 |
when you have to work on the entire tree and build many visitors.</li> |
| 59 |
</ul> |
| 60 |
|
| 61 |
<h2>History</h2> |
| 62 |
04/2016 - 1.4.11 : fixed (added) spaces between the '<' and '>' and the token labels in the generated javadoc comments; |
| 63 |
fixed the conditions on displaying the "warning: Empty choice : a NodeChoice with a 'null' choice member ..."; |
| 64 |
fixed column numbers in messages<p> |
| 65 |
11/2015 - 1.4.10 : added JTB.do_main() returning an int return code<p> |
| 66 |
08/2015 - 1.4.9 : same as 1.4.8.fix_a<p> |
| 67 |
01/2015 - 1.4.8.fix_a : fixed regression in jtb.out.jj generation<p> |
| 68 |
10/2012-12/2014 - 1.4.8 : added generation of JavaCodeProductions ('%' syntax); fixed bug #3164860; fixed |
| 69 |
some messages; fixed some problems (null choice for an empty choice, prefix / suffix management in |
| 70 |
lookahead); checked duplicated Javacode production names; fixed the Java grammar |
| 71 |
(in ExplicitConstructorInvocation & ClassOrInterfaceBodyDeclaration); added annotations in the generated |
| 72 |
classes; fixed some cases and improved printing specials (comments); improved short names generation for |
| 73 |
generated intermediate variables; modified the warning message on ignored LOOKAHEAD (as it can actually be |
| 74 |
not ignored); fixed java blocs generation; some internals improvements |
| 75 |
<p> |
| 76 |
09/2012 - 1.4.7 : added sub comments in the generated visitors java code; did some optimizations; fixed |
| 77 |
bugs JTB-1 & JTB-2; fixed some generation errors; added a check when 'n = prod()' and 'void prod()'; |
| 78 |
added the '!' syntax for not generating a node creation (in a BNFProduction, RegExprSpec and ExpansionUnit) |
| 79 |
; fixed some Java grammar issues and did some refactoring; added column numbers in messages; performed |
| 80 |
tests on more limit cases; fixed missing <EOF> in JavaCCInput() and missing parentheses in Annotation()<p> |
| 81 |
01/2011 - 1.4.6 : JTB hosted at http://java.net/projects/jtb; new contributor (Francis Andre Kampbell); |
| 82 |
added -va and -npfx and -nsfx options<p> |
| 83 |
12/2010 - 1.4.5 : Convert nodes and visitors output directories to absolute paths<p> |
| 84 |
7/2010 - 1.4.4 : Fixed missing space after throws issue in visiting MethodDeclaration & ConstructorDeclaration |
| 85 |
of JavaPrinter; Fixed index issue in visiting TypeArguments of JavaPrinter<p> |
| 86 |
04/2010 - 1.4.3.2 : bug #2991455<p> |
| 87 |
04/2010 - 1.4.3.1 : bugs #2990962 and #2989497<p> |
| 88 |
03/2010 - 1.4.3 : Fixed wrong conditionals generation and TreeFormatter generation issues; |
| 89 |
added node declarations initialization<p> |
| 90 |
02/2010 - 1.4.2 : Fixed missing java.util package in generated JTBToolkit class, |
| 91 |
fixed accept inlining issue in visiting ExpansionChoices<p> |
| 92 |
02/2010 - 1.4.1 : Fixed wrong conditionals generation and missing static modifier for generated return types |
| 93 |
issues (bug 2945965), fixed hard error in semantic checker, fixed command line options overwrite issue<p> |
| 94 |
11/2009 - 1.4.0 : New version delivered / integrated under the |
| 95 |
<a href="http://sourceforge.net/projects/eclipse-javacc">JavaCC Eclipse Plug-in</a><p> |
| 96 |
xx/2005 - 1.3.2 : Last (known) version from UCLA Compilers Group |
| 97 |
: see <a href="http://compilers.cs.ucla.edu/jtb/">JTB 1.3.2 home page</a><p> |
| 98 |
|
| 99 |
<h2>New Features in version 1.4.0+ / 1.4.7</h2> |
| 100 |
Here are the following enhancements that have been added to JTB 1.3.2: |
| 101 |
<ul> |
| 102 |
<li>Internal code</li> |
| 103 |
<ul> |
| 104 |
<li>Internal Java code extensively refactored (performances, namings, JDK 1.5 syntax, numerous fixes, ...)</li> |
| 105 |
<li>Internal Java code Javadoc fully revised</li> |
| 106 |
<li>Internal parser upgraded to version 4.2 of JavaCC, with performance enhancements</li> |
| 107 |
<li>Added Ant build files</li> |
| 108 |
</ul> |
| 109 |
<li>Generated code</li> |
| 110 |
<ul> |
| 111 |
<li>Renamed syntax tree and visitors interfaces and classes</li> |
| 112 |
<li>Generated Java code extensively refactored (performances, namings, JDK 1.5 syntax, numerous fixes, ...)</li> |
| 113 |
<li>Generated Java code Javadoc fully revised, specially with more detailed fields comments</li> |
| 114 |
<li>Special tokens fully printed in the output file (with the -tk option)</li> |
| 115 |
</ul> |
| 116 |
<li>User enhancements</li> |
| 117 |
<ul> |
| 118 |
<li>Removed "only void BNFProduction result type" limitation</li> |
| 119 |
<li>Removed "only non void JavaCodeProduction" limitation</li> |
| 120 |
<li>Added proper handling of "PrimaryExpression() = Identifier() ... | RegularExpression() ..." syntax</li> |
| 121 |
<li>Added a <font color="red">-ia</font> option for inlining visitor accept methods on base nodes</li> |
| 122 |
<li>Changed behavior of option <font color="red">-jd</font>: now turns on printing classes, |
| 123 |
methods and fields javadoc comments</li> |
| 124 |
<li>Added a <font color="red">-dl</font> option for depth level management generation</li> |
| 125 |
<li>Added <font color="red">-d</font>, <font color="red">-nd</font> & <font color="red">-vd</font> options, |
| 126 |
modified <font color="red">-p</font>, <font color="red">-pd</font> & <font color="red">-vp</font> options |
| 127 |
(to separate directories from packages)</li> |
| 128 |
<li>Added input file options "<font color="red">JTB_XX</font>" (in the "options" section of the |
| 129 |
"<font color="red">.jtb</font> grammar file) |
| 130 |
corresponding to the command line options "<font color="red">-xx</font>"<br> |
| 131 |
i.e: <font color="red">JTB_O = "myout.jj"</font> <-> <font color="red">-o myout.jj</font>, |
| 132 |
<font color="red">JTB_TK = true</font> <-> <font color="red">-tk</font> |
| 133 |
</li> |
| 134 |
<li>(1.4.7) Added ability to not generate a (JTB) node creation, with the '!' special character:<ul> |
| 135 |
<li>either in the BNFProduction declaration : e.g. : |
| 136 |
void MyProd() <font color="red">!</font> : { ... }</li> |
| 137 |
<li>or in the RegExprSpec declaration : e.g. : |
| 138 |
TOKEN : { < MyToken : "foo" > <font color="red">!</font> ... }</li> |
| 139 |
<li>or in ExpansionUnits where a BNFProduction or a RegExprSpec is used : e.g. : |
| 140 |
void MyProd() : { ... MyProd() <font color="red">!</font> ... < MyToken> <font color="red">!</font> ...}</li> |
| 141 |
</ul> |
| 142 |
</li> |
| 143 |
</ul> |
| 144 |
</ul> |
| 145 |
<p> |
| 146 |
|
| 147 |
<h2>How to use</h2> |
| 148 |
Environment:<p> |
| 149 |
JTB 1.4.7 is meant to be used as a front end for JavaCC 5.0, with a 1.6.0 JDK, and so is command line by nature.<br> |
| 150 |
But it has been integrated within the <a href="index.html">JavaCC Eclipse Plugin<a>, which embeds the latest |
| 151 |
JTB version each time is is released, and avoids running the tool on the command line.<p> |
| 152 |
|
| 153 |
On the command line:<p> |
| 154 |
<font color="red"><code>java -jar jtb-1.4.x.jar -h</code></font> : to view all available options<br> |
| 155 |
<font color="red"><code>java -jar jtb-1.4.x.jar [CL_Option] -si</code></font> : to use system.in as the input file<br> |
| 156 |
<font color="red"><code>java -jar jtb-1.4.x.jar [CL_Option] [input-file]</code></font> : to use input-file as the input file<br> |
| 157 |
<br> |
| 158 |
In the input file options section:<p> |
| 159 |
<font color="red"><code>options {(JTB_BOOL_OPT=(true|false); | JTB_STR_OPT="str";)*}</code></font><br> |
| 160 |
<br> |
| 161 |
Options are the following:<p> |
| 162 |
<table> |
| 163 |
<tr><td><font color="red">CL_Option</font></td><td><font color="red">JTB_Option</font></td><td><font color="red">Description</font></td></tr> |
| 164 |
<tr><td>-cl </td><td>JTB_CL=(true|false)</td><td>Print a list of the classes generated to standard out</td></tr> |
| 165 |
<tr><td>-d dir </td><td>JTB_D="dir" </td><td>Short for (and overwrites) "-nd dir/syntaxtree -vd dir/visitor"</td></tr> |
| 166 |
<tr><td>-dl </td><td>JTB_DL=(true|false)</td><td>Generate depth level info</td></tr> |
| 167 |
<tr><td>-e </td><td>JTB_E=(true|false) </td><td>Suppress JTB semantic error checking</td></tr> |
| 168 |
<tr><td>-f </td><td>JTB_F=(true|false) </td><td>Use descriptive node class field names</td></tr> |
| 169 |
<tr><td>-h </td><td>N/A </td><td>Display this help message and quit</td></tr> |
| 170 |
<tr><td>-ia </td><td>JTB_IA=(true|false)</td><td>Inline visitors accept methods on base classes</td></tr> |
| 171 |
<tr><td>-jd </td><td>JTB_JD=(true|false)</td><td>Generate JavaDoc-friendly comments in the nodes and visitor</td></tr> |
| 172 |
<tr><td>-nd dir </td><td>JTB_ND="dir" </td><td>Use dir as the package for the syntax tree nodes</td></tr> |
| 173 |
<tr><td>-np pkg </td><td>JTB_NP="pkg" </td><td>Use pkg as the package for the syntax tree nodes</td></tr> |
| 174 |
<tr><td>-ns class</td><td>JTB_NS="class" </td><td>Use class as the class which all node classes will extend</td></tr> |
| 175 |
<tr><td>-o file </td><td>JTB_o="file" </td><td>Use file as the filename for the annotated output grammar</td></tr> |
| 176 |
<tr><td>-p pkg </td><td>JTB_P="pkg" </td><td>Short for (and overwrites) "-np pkg.syntaxtree -vp pkg.visitor"</td></tr> |
| 177 |
<tr><td>-pp </td><td>JTB_PP=(true|false)</td><td>Generate parent pointers in all node classes</td></tr> |
| 178 |
<tr><td>-printer </td><td>JTB_PRINTER </td><td>Generate a syntax tree dumping visitor</td></tr> |
| 179 |
<tr><td>-si </td><td>N/A </td><td>Read from standard input rather than a file</td></tr> |
| 180 |
<tr><td>-scheme </td><td>JTB_SCHEME </td><td>Generate Scheme records representing the grammar and a Scheme tree building visitor</td></tr> |
| 181 |
<tr><td>-tk </td><td>JTB_TK=(true|false)</td><td>Generate special tokens into the tree</td></tr> |
| 182 |
<tr><td>-vd dir </td><td>JTB_VD="dir" </td><td>Use dir as the package for the default visitor classes</td></tr> |
| 183 |
<tr><td>-vp pkg </td><td>JTB_VP="pkg" </td><td>Use pkg as the package for the default visitor classes</td></tr> |
| 184 |
<tr><td>-w </td><td>JTB_W=(true|false )</td><td>Do not overwrite existing files</td></tr> |
| 185 |
</table> |
| 186 |
|
| 187 |
<h2>Support</h2> |
| 188 |
Feel free to report any bug or suggest enhancement at the |
| 189 |
<a href="http://sourceforge.net/tracker/?group_id=56876">JavaCC Eclipse Plug-in Sourceforge site</a>.<p> |
| 190 |
|
| 191 |
<h2>Download</h2> |
| 192 |
<a href="https://java.net/projects/jtb/downloads">JTB download page</a>.<p> |
| 193 |
|
| 194 |
|
| 195 |
<h2>License</h2> |
| 196 |
JTB 1.3.2 is licensed under the <a href="http://compilers.cs.ucla.edu/jtb/license.html">BSD license</a>.<br> |
| 197 |
JTB 1.4.x adds the <a href="http://www.gnu.org/licenses/gpl.html">GPL license</a> and the <a href="http://www.cecill.info/">CECILL license</a>. |
| 198 |
|
| 199 |
</body> |
| 200 |
</html> |