Debian Codegraph @

www/doc/errorrecovery.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: Error Reporting and Recovery</title>
35 <!-- Changed by: Michael Van De Vanter, 14-Jan-2003 -->
36 </head>
37 <body bgcolor="#FFFFFF" >
38
39 <h1>JavaCC [tm]: Error Reporting and Recovery</h1>
40
41 <p>
42 This document describes the error recovery features introduced in
43 Version 0.7.1. This document also describes how features have changed
44 since Version 0.6.
45 </p>
46 <p>
47 The first change (from 0.6) is that we have two new exceptions:
48 </p>
49 <pre>
50 . ParseException
51 . TokenMgrError
52 </pre>
53 <p>
54 Whenever the token manager detects a problem, it throws the exception
55 TokenMgrError. Previously, it used to print the message:
56 </p>
57 <pre>
58 Lexical Error ...
59 </pre>
60 <p>
61 following which it use to throw the exception ParseError.
62 </p>
63 <p>
64 Whenever the parser detects a problem, it throws the exception
65 ParseException. Previously, it used to print the message:
66 </p>
67 <pre>
68 Encountered ... Was expecting one of ...
69 </pre>
70 <p>
71 following which it use to throw the exception ParseError.
72 </p>
73 <p>
74 In Version 0.7.1, error messages are never printed explicitly,
75 rather this information is stored inside the exception objects that
76 are thrown. Please see the classes ParseException.java and
77 TokenMgrError.java (that get generated by JavaCC [tm] during parser
78 generation) for more details.
79 </p>
80 <p>
81 If the thrown exceptions are never caught, then a standard action is
82 taken by the virtual machine which normally includes printing the
83 stack trace and also the result of the "toString" method in the
84 exception. So if you do not catch the JavaCC exceptions, a message
85 quite similar to the ones in Version 0.6.
86 </p>
87 <p>
88 But if you catch the exception, you must print the message yourself.
89 </p>
90 <p>
91 Exceptions in the Java [tm] programming language are all subclasses of
92 type Throwable. Furthermore, exceptions are divided into two broad
93 categories - ERRORS and other exceptions.
94 </p>
95 <p>
96 Errors are exceptions that one is not expected to recover from -
97 examples of these are ThreadDeath or OutOfMemoryError. Errors are
98 indicated by subclassing the exception "Error". Exceptions subclassed
99 from Error need not be specified in the "throws" clause of method
100 declarations.
101 </p>
102 <p>
103 Exceptions other than errors are typically defined by subclassing the
104 exception "Exception". These exceptions are typically handled by the
105 user program and must be declared in throws clauses of method
106 declarations (if it is possible for the method to throw that
107 exception).
108 </p>
109 <p>
110 The exception TokenMgrError is a subclass of Error, while the
111 exception ParseException is a subclass of Exception. The reasoning
112 here is that the token manager is never expected to throw an exception
113 - you must be careful in defining your token specifications such that
114 you cover all cases. Hence the suffix "Error" in TokenMgrError. You
115 do not have to worry about this exception - if you have designed your
116 tokens well, it should never get thrown. Whereas it is typical to
117 attempt recovery from Parser errors - hence the name "ParseException".
118 (Although if you still want to recover from token manager errors, you
119 can do it - it's just that you are not forced to catch them.)
120 </p>
121 <p>
122 In Version 0.7.1, we have added a syntax to specify additional exceptions
123 that may be thrown by methods corresponding to non-terminals. This
124 syntax is identical to the Java "throws ..." syntax. Here's an
125 example of how you use this:
126 </p>
127 <pre>
128
129 void VariableDeclaration() throws SymbolTableException, IOException :
130 {...}
131 {
132 ...
133 }
134 </pre>
135 <p>
136 Here, VariableDeclaration is defined to throw exceptions
137 SymbolTableException and IOException in addition to ParseException.
138 </p>
139 <h2>Error Reporting</h2>
140 <p>
141 The scheme for error reporting is simpler in Version 0.7.1 (as compared
142 to Version 0.6) - simply modify the file ParseException.java to do
143 what you want it to do. Typically, you would modify the getMessage
144 method to do your own customized error reporting. All information
145 regarding these methods can be obtained from the comments in the
146 generated files ParseException.java and TokenMgrError.java. It will
147 also help to understand the functionality of the class Throwable (read
148 a Java book for this).
149 </p>
150 <p>
151 There is a method in the generated parser called
152 "generateParseException". You can call this method anytime you wish
153 to generate an object of type ParseException. This object will
154 contain all the choices that the parser has attempted since the last
155 successfully consumed token.
156 </p>
157
158 <h2>Error Recovery</h2>
159 <p>
160 JavaCC offers two kinds of error recovery - shallow recovery and deep
161 recovery. Shallow recovery recovers if none of the current choices
162 have succeeded in being selected, while deep recovery is when a choice
163 is selected, but then an error happens sometime during the parsing of
164 this choice.
165 </p>
166 <h3>Shallow Error Recovery</h3>
167 <p>
168 We shall explain shallow error recovery using the following example:
169 </p>
170 <pre>
171 void Stm() :
172 {}
173 {
174 IfStm()
175 |
176 WhileStm()
177 }
178 </pre>
179 <p>
180 Let's assume that IfStm starts with the reserved word "if" and WhileStm
181 starts with the reserved word "while". Suppose you want to recover by
182 skipping all the way to the next semicolon when neither IfStm nor WhileStm
183 can be matched by the next input token (assuming a lookahead of 1). That
184 is the next token is neither "if" nor "while".
185 </p>
186 <p>
187 What you do is write the following:
188 </p>
189 <pre>
190 void Stm() :
191 {}
192 {
193 IfStm()
194 |
195 WhileStm()
196 |
197 error_skipto(SEMICOLON)
198 }
199 </pre>
200 <p>
201 But you have to define "error_skipto" first. So far as JavaCC is concerned,
202 "error_skipto" is just like any other non-terminal. The following is one
203 way to define "error_skipto" (here we use the standard JAVACODE production):
204 </p>
205 <pre>
206 JAVACODE
207 void error_skipto(int kind) {
208 ParseException e = generateParseException(); // generate the exception object.
209 System.out.println(e.toString()); // print the error message
210 Token t;
211 do {
212 t = getNextToken();
213 } while (t.kind != kind);
214 // The above loop consumes tokens all the way up to a token of
215 // "kind". We use a do-while loop rather than a while because the
216 // current token is the one immediately before the erroneous token
217 // (in our case the token immediately before what should have been
218 // "if"/"while".
219 }
220 </pre>
221 <p>
222 That's it for shallow error recovery. In a future version of JavaCC
223 we will have support for modular composition of grammars. When this
224 happens, one can place all these error recovery routines into a
225 separate module that can be "imported" into the main grammar module.
226 We intend to supply a library of useful routines (for error recovery
227 and otherwise) when we implement this capability.
228 </p>
229 <h3>Deep Error Recovery</h3>
230 <p>
231 Let's use the same example that we did for shallow recovery:
232 </p>
233 <pre>
234 void Stm() :
235 {}
236 {
237 IfStm()
238 |
239 WhileStm()
240 }
241 </pre>
242 <p>
243 In this case we wish to recover in the same way. However, we wish to
244 recover even when there is an error deeper into the parse. For
245 example, suppose the next token was "while" - therefore the choice
246 "WhileStm" was taken. But suppose that during the parse of WhileStm
247 some error is encountered - say one has "while (foo { stm; }" - i.e., the
248 closing parentheses has been missed. Shallow recovery will not work
249 for this situation. You need deep recovery to achieve this. For this,
250 we offer a new syntactic entity in JavaCC - the try-catch-finally block.
251 </p>
252 <p>
253 First, let us rewrite the above example for deep error recovery and then
254 explain the try-catch-finally block in more detail:
255 </p>
256 <pre>
257 void Stm() :
258 {}
259 {
260 try {
261 (
262 IfStm()
263 |
264 WhileStm()
265 )
266 catch (ParseException e) {
267 error_skipto(SEMICOLON);
268 }
269 }
270 </pre>
271 <p>
272 That's all you need to do. If there is any unrecovered error during the
273 parse of IfStm or WhileStm, then the catch block takes over. You can
274 have any number of catch blocks and also optionally a finally block
275 (just as with Java errors). What goes into the catch blocks is *Java code*,
276 not JavaCC expansions. For example, the above example could have been
277 rewritten as:
278 </p>
279 <pre>
280 void Stm() :
281 {}
282 {
283 try {
284 (
285 IfStm()
286 |
287 WhileStm()
288 )
289 catch (ParseException e) {
290 System.out.println(e.toString());
291 Token t;
292 do {
293 t = getNextToken();
294 } while (t.kind != SEMICOLON);
295 }
296 }
297 </pre>
298 <p>
299 Our belief is that it's best to avoid placing too much Java code in the
300 catch and finally blocks since it overwhelms the grammar reader. Its best
301 to define methods that you can then call from the catch blocks.
302 </p>
303 <p>
304 Note that in the second writing of the example, we essentially copied
305 the code out of the implementation of error_skipto. But we left out the
306 first statement - the call to generateParseException. That's because in
307 this case, the catch block already provides us with the exception. But
308 even if you did call this method, you will get back an identical object.
309 </p>
310 </body>
311 </html>