Debian Codegraph @

doc/jtb_doc.html

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