Debian Codegraph @

www/doc/jjtreereleasenotes.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml">
3 <!--
4
5 Copyright (c) 2006, Sun Microsystems, Inc.
6 All rights reserved.
7
8 Redistribution and use in source and binary forms, with or without
9 modification, are permitted provided that the following conditions are met:
10
11 * Redistributions of source code must retain the above copyright notice,
12 this list of conditions and the following disclaimer.
13 * Redistributions in binary form must reproduce the above copyright
14 notice, this list of conditions and the following disclaimer in the
15 documentation and/or other materials provided with the distribution.
16 * Neither the name of the Sun Microsystems, Inc. nor the names of its
17 contributors may be used to endorse or promote products derived from
18 this software without specific prior written permission.
19
20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
24 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
30 THE POSSIBILITY OF SUCH DAMAGE.
31
32 -->
33 <head>
34 <title>JavaCC: JJTree Release Notes</title>
35 <!-- Changed by: Michael Van De Vanter, 14-Jan-2003 -->
36 </head>
37 <body bgcolor="#FFFFFF" >
38
39 <h1>JavaCC [tm]: JJTree Release Notes</h1>
40
41 <pre>
42
43 ======================================
44 Changes in 4.2
45 ======================================
46 Release 4.2 is a maintenance release, incorporating a number of bug
47 fixes and enhancements. For a complete list, please see the
48 issue tracker:
49
50 https://javacc.dev.java.net/issues/buglist.cgi?component=javacc&field0-0-0=target_milestone&type0-0-0=equals&value0-0-0=4.2
51
52 ======================================
53 Changes in 4.1
54 ======================================
55 Release 4.1 is a maintenance release, incorporating a number of bug
56 fixes and enhancements. For a complete list, please see the
57 issue tracker:
58
59 https://javacc.dev.java.net/issues/buglist.cgi?component=javacc&field0-0-0=target_milestone&type0-0-0=equals&value0-0-0=4.1
60
61 ======================================
62 Changes in 4.0
63 ======================================
64 New option NODE_EXTENDS to specify a classname that
65 SimpleNode extends so that boiler plate code can be put
66 in that class. See the examples/Interpreter for an example
67 usage.
68
69 ======================================
70 Changes from JJTree 0.3pre5 to 0.3pre6
71 ======================================
72
73 ----------------------------------------------------------------
74
75 Fixed bug where Writers were not being closed correctly.
76
77 ----------------------------------------------------------------
78
79 ======================================
80 Changes from JJTree 0.3pre4 to 0.3pre5
81 ======================================
82
83 ----------------------------------------------------------------
84
85 Fixed a bug where a node annotation #P() caused a null pointer error.
86
87 ----------------------------------------------------------------
88
89 Only generate the jjtCreate() methods if the NODE_FACTORY option is
90 set.
91
92 ----------------------------------------------------------------
93
94 Fixed a bug where the name of the JJTree state file was being used in
95 the declaration of the field.
96
97 ----------------------------------------------------------------
98
99 ======================================
100 Changes from JJTree 0.3pre3 to 0.3pre4
101 ======================================
102
103 ----------------------------------------------------------------
104
105 Made the constructors of nodes public. Also made the node identifier
106 constants and the associated strings public.
107
108 ----------------------------------------------------------------
109
110 Fixed a misleading error message that was produced when the output
111 file couldn't be generated for some reason.
112
113 ----------------------------------------------------------------
114
115 Brought the HTML documentation up to date.
116
117 ----------------------------------------------------------------
118
119 Fixed a bug where the file containing the JJTree state class was
120 ignoring the OUTPUT_DIRECTORY option.
121
122 ----------------------------------------------------------------
123
124 Fixed a bug where a construction like this:
125
126 a=foo() #Foo
127
128 was being incorrectly handled and generating bad Java code.
129
130 ----------------------------------------------------------------
131
132 Changed the visitor support from a void function to one which takes a
133 parameter and returns a result. This is a non-compatible change, so
134 you will have to update your code if it uses the visitor support.
135
136
137 [Also, if the string option VISITOR_EXCEPTION is set, its value is
138 also used in the signatures of the various methods in the pattern.
139
140 Please note: this exception support is very provisional and will be
141 replaced in a following version by a more general solution. It's only
142 here because I needed it for one of my own projects and thought it
143 might be useful to someone else too. Don't use it unless you're
144 prepared to change your code again later. Rob.]
145
146 ----------------------------------------------------------------
147
148 ======================================
149 Changes from JJTree 0.3pre2 to 0.3pre3
150 ======================================
151
152 ----------------------------------------------------------------
153
154 JJTree now uses the same grammar as JavaCC. This means that Java code
155 in parser actions is parsed.
156
157 ----------------------------------------------------------------
158
159 Added support for the Visitor design pattern. If the VISITOR option
160 is true, JJTree adds an accept method to the node classes that it
161 generates, and also generates a visitor interface. This interface is
162 regenerated every time that JJTree is run, so that new nodes will
163 cause compilation errors in concrete visitors that have not been
164 updated for them.
165
166 ----------------------------------------------------------------
167
168 Added a couple of examples to illustrate the Visitor support.
169 JJTreeExamples/eg4.jjt is yet another version of the expression tree
170 builder which uses a visitor to dump the expression tree; and
171 VTransformer is a variation of the Java source code transformer.
172
173 VTransformer is also possibly directly useful as a tool that inserts
174 visitor accept methods into class files that were generated with
175 earlier versions of JJTree.
176
177 ----------------------------------------------------------------
178
179 Added the BUILD_NODE_FILES option, with a default value of true. If
180 set to false, it prevents JJTree from generating SimpleNode.java and
181 nodes that are usually built in MULTI mode. Node.java is still
182 generated, as are the various tree constants, etc.
183
184 ----------------------------------------------------------------
185
186 Code that is inserted into the grammar is now enclosed in the standard
187 @bgen/@egen pair.
188
189 ----------------------------------------------------------------
190
191 The JJTree state object is now generated into its own file if it
192 doesn't already exist. This is to make it easier to modify.
193
194 ----------------------------------------------------------------
195
196 Fixed a couple of bugs in the HTML example grammar where the closing
197 tags didn't match the opening tags.
198
199 ----------------------------------------------------------------
200
201 Fixed a bug where JJTree was trying to clear the node scope while
202 handling an exception, even when the node had been closed successfully.
203
204 ----------------------------------------------------------------
205
206 NODE_FACTORY no longer implies NODE_USES_PARSER.
207
208 If you have been using NODE_FACTORY, then now you'll also need
209 NODE_USES_PARSER. Unless, of course, you were never using the parser
210 in your node factories.
211
212 ----------------------------------------------------------------
213
214 Removed not very useful debugging stuff from the JJTree state object.
215 It was causing problems with parsers running in security environments
216 where access to arbitrary properties is disallowed.
217
218 ----------------------------------------------------------------
219
220 ======================================
221 Changes from JJTree 0.3pre1 to 0.3pre2
222 ======================================
223
224 ----------------------------------------------------------------
225
226 The state that JJTree inserts into the parser class is now guarded by
227 the formal comments.
228
229 ----------------------------------------------------------------
230
231 The JJTree syntax has been changed so that the node descriptor now
232 comes after the throws clause, rather than before it.
233
234 ----------------------------------------------------------------
235
236 Fixed a bug where string-valued options did not have their quotes
237 stripped.
238
239 ----------------------------------------------------------------
240
241 Fixed a bug where nodes were being closed early for actions within
242 ZeroOrMore etc., expansion units.
243
244 ----------------------------------------------------------------
245
246 The special identifier `jjtThis' was not being translated in parameter
247 lists or in the BNF declaration section. Fixed it.
248
249 ----------------------------------------------------------------
250
251 Added the OUTPUT_DIRECTORY option. The default value is "".
252
253 ----------------------------------------------------------------
254
255 Reinstated node factory methods. They are enabled by setting the
256 NODE_FACTORY option to true. Unlike the original node factory methods
257 they take two arguments: the node identifier constant and a reference
258 to the parser. The reference is null for static parsers.
259
260 ----------------------------------------------------------------
261
262 Added the NODE_USES_PARSER option with a default value of false. When
263 set to true, JJTree will call the node constructor with a reference to
264 the parser object as an extra parameter. This reference is null for
265 static parsers.
266
267 ----------------------------------------------------------------
268
269 ====================================
270 Changes from JJTree 0.2.6 to 0.3pre1
271 ====================================
272
273 ----------------------------------------------------------------
274
275 JJTree 0.3pre1 has been bootstrapped with JJTree 0.2.6.
276
277 Some aspects of JJTree 0.3pre1 are not backwards-compatible with
278 0.2.6. Some users will need to modify their parsers in
279 straightforward ways in order to work with the new version. See the
280 file JJTREE-FIX to find out if you need to change anything, and for
281 detailed instructions on what to change.
282
283 ----------------------------------------------------------------
284
285 JJTree works with the JavaCC exception handling code. Any unhandled
286 exceptions within a node scope are caught, the node stack is cleaned
287 up a bit, and then the exception is rethrown.
288
289 ----------------------------------------------------------------
290
291 Indefinite and Greater-Than nodes have been generalized into
292 conditional nodes.
293
294 Definite nodes now take any integer expression to indicate now many
295 children they take. Conditional nodes take any boolean expression to
296 indicate whether the node is closed and pushed on to the node stack.
297
298 ----------------------------------------------------------------
299
300 The life cycle of a node is now defined.
301
302 ----------------------------------------------------------------
303
304 User-defined parser methods can be called when a node scope is entered
305 and exited.
306
307 ----------------------------------------------------------------
308
309 The NODE_STACK_SIZE and CHECK_DEFINITE_NODE options are now ignored.
310
311 The NODE_SCOPE_HOOK option has been added. This boolean option
312 determines whether calls to certain user-defined parser methods are
313 generated at the beginning and end of each node scope. The default
314 value for this option is false.
315
316 ----------------------------------------------------------------
317
318 The special identifier jjtThis can now be used in the declarations
319 section of a production, as well as on the left hand side of call to a
320 nonterminal.
321
322 ----------------------------------------------------------------
323
324 A new method arity() has been added to the JJTree state. It returns
325 the number of nodes that have been pushed so far in the current node
326 scope.
327
328 ----------------------------------------------------------------
329
330 The Node interface has changed. The method jjtAddChild() now takes an
331 argument to indicate the index of the child it is adding.
332
333 ----------------------------------------------------------------
334
335 The node factory methods are no longer used. You can remove all your
336 jjtCreate() methods.
337
338 The node constructor now takes an int parameter instead of a String.
339 You will have to modify your node implementations to use the new
340 signature. The protected field `identifier' no longer exists: you can
341 use the jjtNodeName[] array to map from the new parameter to the old
342 String.
343
344 ----------------------------------------------------------------
345
346 The implementation of SimpleNode has changed significantly. It now
347 uses an array to hold any child nodes instead of a Vector. It no
348 longer implements a node factory, its constructor takes an int instead
349 of a String, and it uses the jjtNodeName[] mechanism for dumping. The
350 setInfo() and getInfo() methods have been removed.
351
352 ----------------------------------------------------------------
353
354 The implementation of the state that JJTree keeps in the parser has
355 changed. It is now considerably more lightweight: the auxiliary
356 classes JJTreeNodeStack and JJTreeNodeStackEnum have been abolished.
357
358 ----------------------------------------------------------------
359
360 The JJTree state method currentNode() has been removed. Any calls to
361 the method in an action within a node scope are automatically replaced
362 by references to the special identifier jjtThis.
363
364 ----------------------------------------------------------------
365
366 ==================================
367 Changes from JJTree 0.2.5 to 0.2.6
368 ==================================
369
370 ----------------------------------------------------------------
371
372 Made appropriate internal modifications for the JavaCC 0.7 parse error
373 exceptions.
374
375 ----------------------------------------------------------------
376
377 ==================================
378 Changes from JJTree 0.2.4 to 0.2.5
379 ==================================
380
381 ----------------------------------------------------------------
382
383 Fixed a bug where the current node was not being updated in the right
384 place for final user actions.
385
386 ----------------------------------------------------------------
387
388 ==================================
389 Changes from JJTree 0.2.3 to 0.2.4
390 ==================================
391
392 ----------------------------------------------------------------
393
394 Fixed a bug where bad code was generated for void nodes in MULTI mode.
395
396 ----------------------------------------------------------------
397
398 Fixed a bug where a node decoration directly on an action generated
399 bad code. For example,
400
401 {} #MyNode
402
403 ----------------------------------------------------------------
404
405 ==================================
406 Changes from JJTree 0.2.2 to 0.2.3
407 ==================================
408
409 ----------------------------------------------------------------
410
411 Added toString() and toString(String) methods to SimpleNode and
412 modified the dumping code to use them. Now you can easily customize
413 how a node appears in the tree dump, without having to reproduce the
414 tree walking machinery. See SimpleNode.java for details.
415
416 ----------------------------------------------------------------
417
418 Clarified the concept of node scope. currentNode() now refers to the
419 node currently being built for the current scope. It used to be
420 incorrectly implemented as referring to the most recently created
421 node, and was synonymous with peekNode().
422
423 This change may break some existing programs. Those programs should
424 be changed to use peekNode() where they currently use currentNode().
425
426 Added jjtThis to every user action. It refers to the same node that
427 currentNode() does, but is already cast to the appropriate node type.
428
429 The final user action in a node scope is different from all the
430 others. When it is executed the node has been fully created, had its
431 children added, and has been pushed on the node stack. By contrast,
432 other user actions within the scope are called when the children are
433 still on the stack, and the current node is not.
434
435 Added the nodeCreated() method so that final actions within greater
436 than nodes can tell whether the node was created or not.
437
438 ----------------------------------------------------------------
439
440 Fixed several stupid bugs in the Macintosh main class.
441
442 ----------------------------------------------------------------
443
444 Fixed names of internally used JJTree classes so that they use the JJT
445 prefix and the name of the parser. This is to avoid naming conflicts
446 where there is more than one JJTree parser in the same package.
447
448 ----------------------------------------------------------------
449
450 ================================
451 Changes from JJTree 0.2 to 0.2.2
452 ================================
453
454 The main change between Beanstalk 0.2 and JJTree 0.2.2 is the removal
455 of the factory classes. Their function is now performed by a static
456 method in the node classes themselves.
457
458 The state maintained in the parser class has been changed from bs to
459 jjtree. The prefix on the Node class methods has been changed from bs
460 to jjt.
461
462 A new node method jjtGetNumChildren() returns the number of children
463 the node has. You can use this in conjunction with jjtGetChild() to
464 iterate over the children.
465
466 Two new options have been added: OUTPUT_FILE and NODE_DEFAULT_VOID.
467
468 ----------------------------------------------------------------
469 </pre>
470
471 </body>
472 </html>