1<html> 2<head> 3<title>Error Handling</title> 4<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<link rel="stylesheet" href="theme/style.css" type="text/css"> 6</head> 7 8<body> 9<table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2"> 10 <tr> 11 <td width="10"> 12 </td> 13 <td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Error 14 Handling </b></font></td> 15 <td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" width="112" height="48" align="right" border="0"></a></td> 16 </tr> 17</table> 18<br> 19<table border="0"> 20 <tr> 21 <td width="10"></td> 22 <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> 23 <td width="30"><a href="debugging.html"><img src="theme/l_arr.gif" border="0"></a></td> 24 <td width="30"><a href="quickref.html"><img src="theme/r_arr.gif" border="0"></a></td> 25 </tr> 26</table> 27<p>C++'s exception handling mechanism is a perfect match for error handling in 28 the framework. Imagine a complete parser as a maze. At each branch, the input 29 dictates where we will turn. Given an erroneous input, we may reach a dead end. 30 If we ever reach one, it would be a waste of time to backtrack from where we 31 came from. Instead, we supply guards in strategic points. Beyond a certain point, 32 we put put parser assertions in places where one is not allowed to go. </p> 33<p>The assertions are like springs that catapult us back to the guard. If we ever 34 reach a brick wall given a specific input pattern, everything unwinds quickly 35 and we are thrown right back to the guard. This can be a very effective optimization 36 when used wisely. Right back at the guard, we have a chance to correct the situation, 37 if possible. The following illustration depicts the scenario.</p> 38<table border="0" align="center"> 39 <tr> 40 <td><img src="theme/error_handling.png" width="313" height="238"></td> 41 </tr> 42</table> 43<a name="the_parser_exception"></a> 44<h2>Parser Errors</h2> 45<p> The <tt>parser_error</tt> class is the generic parser exception class used 46 by Spirit. This is the base class for all parser exceptions.</p> 47<pre> <code><span class=keyword>template </span><span class=special><</span><span class=keyword>typename </span><span class=identifier>ErrorDescrT</span><span class=special>, </span><span class=keyword>typename </span><span class=identifier>IteratorT </span><span class=special>= </span><span class=keyword>char </span><span class=keyword>const</span><span class=special>*> 48 </span><span class=keyword>class </span><span class=identifier>parser_error </span><span class=special> 49 { 50 </span><span class=keyword>public</span><span class=special>: 51 </span><span class=identifier>parser_error</span><span class=special>(</span><span class=identifier>IteratorT </span><span class=identifier>where</span><span class=special>, </span><span class=identifier>ErrorDescrT </span><span class=identifier>descriptor</span><span class=special>); 52 </span><span class=identifier>IteratorT </span><span class=identifier>where</span><span class=special>; 53 </span><span class=identifier>ErrorDescrT</span><span class=identifier> descriptor</span><span class=special>; 54 </span><span class=special>}; 55</span></code></pre> 56<p> The exception holds the iterator position where the error was encountered 57 in its <tt>where</tt> member variable. In addition to the iterator, <tt>parser_error</tt> 58 also holds information regarding the error (error descriptor) in its <tt>descriptor 59 </tt> member variable.</p> 60<p> Semantic actions are free to throw parser exceptions when necessary. A utility 61 function <tt>throw_</tt> may be called. This function creates and throws a <tt>parser_error</tt> 62 given an iterator and an error descriptor:</p> 63<pre> 64 <code><span class=keyword>template </span><span class=special><</span><span class=keyword>typename </span><span class=identifier>ErrorDescrT</span><span class=special>, </span><span class=keyword>typename </span><span class=identifier>IteratorT</span><span class=special>> 65 </span><span class=keyword>void </span><span class=identifier>throw_</span><span class=special>(</span><span class=identifier>IteratorT where</span><span class=special>, </span><span class=identifier>ErrorDescrT descriptor</span><span class=special>); 66</span></code></pre> 67<a name="the_parser_assertion"></a> 68<h2>Parser Assertions</h2> 69<p> Assertions may be put in places where we don't have any other option other 70 than expect parsing to succeed. If parsing fails, a specific type of exception 71 is thrown.</p> 72<p> Before declaring the grammar, we declare some assertion objects. <tt>assertion</tt> 73 is a template class parameterized by the type of error that will be thrown once 74 the assertion fails. The following assertions are parameterized by a user defined 75 Error enumeration.</p> 76<a name="examples"></a> 77<h3>Examples</h3> 78<pre> 79 <code><span class=keyword>enum </span><span class=identifier>Errors 80 </span><span class=special>{ 81 </span><span class=identifier>program_expected</span><span class=special>, 82 </span><span class=identifier>begin_expected</span><span class=special>, 83 </span><span class=identifier>end_expected 84 </span><span class=special>}; 85 86 </span><span class=identifier>assertion</span><span class=special><</span><span class=identifier>Errors</span><span class=special>> </span><span class=identifier>expect_program</span><span class=special>(</span><span class=identifier>program_expected</span><span class=special>); 87 </span><span class=identifier>assertion</span><span class=special><</span><span class=identifier>Errors</span><span class=special>> </span><span class=identifier>expect_begin</span><span class=special>(</span><span class=identifier>begin_expected</span><span class=special>); 88 </span><span class=identifier>assertion</span><span class=special><</span><span class=identifier>Errors</span><span class=special>> </span><span class=identifier>expect_end</span><span class=special>(</span><span class=identifier>end_expected</span><span class=special>); 89</span></code></pre> 90<p> The example above uses enums to hold the information regarding the error, 91 we are free to use other types such as integers and strings. For example, <tt>assertion<string></tt> 92 accepts a string as its info. It is advisable to use light-weight objects though, 93 after all, error descriptors are usually static. Enums are convenient for error 94 handlers to detect and easily catch since C++ treats enums as unique types.</p> 95<table width="80%" border="0" align="center"> 96 <tr> 97 <td class="note_box"> <b><img src="theme/lens.gif" width="15" height="16"> 98 The assertive_parser</b><br> 99 <br> 100 Actually, the expression <tt>expect_end(str_p("end"))</tt>creates 101 an assertive_parser object. An assertive_parser is a parser that throws 102 an exception in response to a parsing failure. The assertive_parser throws 103 a parser_error exception rather than returning an unsuccessful match to 104 signal that the parser failed to match the input. During parsing, parsers 105 are given an iterator of type <tt>IteratorT</tt>. This is combined with 106 the error descriptor type <tt>ErrorDescrT</tt> of the assertion (in this 107 case enum <tt>Errors</tt>). Both are used to create a <tt>parser_error<Errors, 108 IteratorT></tt> which is then thrown to signal the exception. </td> 109 </tr> 110</table> 111<p> The predeclared <tt>expect_end</tt> assertion object may now be used in the 112 grammar as wrappers around parsers. For example:</p> 113<pre> 114 <code><span class=identifier>expect_end</span><span class=special>(</span><span class=identifier>str_p</span><span class=special>(</span><span class=string>"end"</span><span class=special>)) 115</span></code></pre> 116<p> This will throw an exception if it fails to see "end" from the input.</p> 117<a name="the_guard"></a> 118<h2>The Guard</h2> 119<p> The <tt>guard</tt> is used to catch a specific type of <tt>parser_error</tt>. 120 guards are typically predeclared just like assertions. Extending our previous 121 example:</p> 122<pre> 123 <code><span class=identifier>guard</span><span class=special><</span><span class=identifier>Errors</span><span class=special>> </span><span class=identifier>my_guard</span><span class=special>; 124</span></code></pre> 125<p> <tt>Errors</tt>, in this example is the error descriptor type we want to detect. 126 This is the same enum as above. <tt>my_guard</tt> may now be used in a grammar 127 declaration:</p> 128<pre> <code><span class=identifier>my_guard</span><span class=special>(</span><span class=identifier>p</span><span class=special>)[</span><span class=identifier>error_handler</span><span class=special>]</span></code></pre> 129<p> where <tt>p</tt> is an expression that evaluates to a parser. Somewhere inside 130 <tt>p</tt>, a parser may throw a parser exception. <tt>error_handler</tt> is 131 the error handler which may be a function or functor compatible with the interface:</p> 132<pre> <code>error_status<span class=special><</span>T<span class=special>></span><span class=identifier> 133 f</span><span class=special>(</span>ScannerT const& scan, ErrorT error<span class=special>); 134</span></code></pre> 135<p> Where scan points to the scanner state prior to parsing and error is the error 136 that arose. The handler is allowed to move the scanner position as it sees fit, 137 possibly in an attempt to perform error correction. The handler must then return 138 an <tt>error_status<T></tt> object. </p> 139<table width="80%" border="0" align="center"> 140 <tr> 141 <td class="note_box"> <b><img src="theme/lens.gif" width="15" height="16"> 142 The fallback_parser </b><br> 143 <br> 144 The expression <tt>my_guard(expr, error_handler)</tt>creates a fallback_parser 145 object. The fallback_parser handles parser_error exceptions of a specific 146 type. Since <tt>my_guard</tt> is declared as <tt>guard<Errors></tt>, 147 the fallback_parser catches <tt>Errors</tt> specific parser errors: <tt>parser_error<Errors, 148 IteratorT></tt>. The class sets up a try block. When an exception is 149 caught, the catch block then calls the error_handler. </td> 150 </tr> 151</table> 152<h2>error_status<T></h2> 153<pre> 154 <code><span class=keyword>template </span><span class=special><</span><span class=keyword>typename </span><span class=identifier>T </span><span class=special>= </span><span class=identifier>nil_t</span><span class=special>> 155 </span><span class=keyword>struct </span><span class=identifier>error_status 156 </span><span class=special>{ 157 </span><span class=keyword>enum </span><span class=identifier>result_t </span><span class=special>{ </span><span class=identifier>fail</span><span class=special>, </span><span class=identifier>retry</span><span class=special>, </span><span class=identifier>accept</span><span class=special>, </span><span class=identifier>rethrow </span><span class=special>}; 158 159 </span><span class=identifier>error_status</span><span class=special>(</span><span class=identifier> 160 result_t result </span><span class=special>= </span><span class=identifier>fail</span><span class=special>, 161 </span><span class=keyword>int </span><span class=identifier>length </span><span class=special>= -</span><span class=number>1</span><span class=special>, 162 </span><span class=identifier>T </span><span class=keyword>const</span><span class=special>& </span><span class=identifier>value </span><span class=special>= </span><span class=identifier>T</span><span class=special>()); 163</span> 164 <span class=identifier>result_t result</span><span class=special>; 165 </span><span class=keyword>int </span><span class=identifier>length</span><span class=special>; 166 </span><span class=identifier>T value</span><span class=special>; 167 };</span></code></pre> 168<p>Where <tt>T</tt> is an attribute type compatible with the match attribute of 169 the <tt>fallback_parser</tt>'s subject (defaults to <tt>nil_t</tt>). The class 170 <tt>error_status</tt> reports the result of an error handler. This result can 171 be one of: </p> 172<table width="90%" border="0" align="center"> 173 <tr> 174 <td class="table_title" colspan="8"> error_status result </td> 175 </tr> 176 <tr> 177 <tr> 178 <td class="table_cells"><b>fail</b></td> 179 <td class="table_cells">quit and fail. Return a <tt>no_match</tt></td> 180 </tr> 181 <td class="table_cells"><b>retry</b></td> 182 <td class="table_cells">attempt error recovery, possibly moving the scanner</td> 183 </tr> 184 <td class="table_cells"><b>accept</b></td> 185 <td class="table_cells">force success returning a matching length, moving the 186 scanner appropriately and returning an attribute value</td> 187 </tr> 188 <td class="table_cells"><b>rethrow</b></td> 189 <td class="table_cells">rethrows the error</td> 190 </tr> 191</table> 192<p><img src="theme/lens.gif" width="15" height="16"> See <a href="../example/fundamental/error_handling.cpp">error_handling.cpp</a> for a compilable example. This is part of the Spirit distribution.</p> 193<table width="80%" border="0" align="center"> 194</table> 195<table border="0"> 196 <tr> 197 <td width="10"></td> 198 <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td> 199 <td width="30"><a href="debugging.html"><img src="theme/l_arr.gif" border="0"></a></td> 200 <td width="30"><a href="quickref.html"><img src="theme/r_arr.gif" border="0"></a></td> 201 </tr> 202</table> 203<br> 204<hr size="1"> 205<p class="copyright">Copyright © 1998-2003 Joel de Guzman<br> 206 <br> 207<font size="2">Use, modification and distribution is subject to the Boost Software 208 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 209 http://www.boost.org/LICENSE_1_0.txt)</font></p> 210<p class="copyright"> </p> 211</body> 212</html> 213
