1[/============================================================================== 2 Copyright (C) 2001-2011 Hartmut Kaiser 3 Copyright (C) 2001-2011 Joel de Guzman 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section:flush_multi_pass Qi flush_multi_pass parser] 10 11[heading Description] 12 13The __qi__ `flush_multi_pass` parser is a primitive (pseudo) parser component 14allowing to clear the internal buffer of a `multi_pass` iterator. Clearing the 15buffer of a `multi_pass` might be beneficial for grammars where it is clear 16that no backtracking can occur. 17The general syntax for using the `flush_multi_pass` is: 18 19 flush_multi_pass 20 21which will call the `clear_queue()` member function if the current iterators 22are of the type `multi_pass`. This will cause any buffered data to be erased. 23This also will invalidate all other copies of multi_pass and they should not 24be used. If they are, an `boost::illegal_backtracking` exception will be 25thrown. For all other iterator types this is a no-op. The `flush_multi_pass` 26generates a parser component which always succeeds and which does not consume 27any input (very much like `eps`). 28 29[heading Header] 30 31 // forwards to <boost/spirit/repository/home/qi/primitive/flush_multi_pass.hpp> 32 #include <boost/spirit/repository/include/qi_flush_multi_pass.hpp> 33 34[heading Synopsis] 35 36 flush_multi_pass 37 38[heading Parameters] 39 40The `flush_multi_pass` does not require any parameters. 41 42[heading Attribute] 43 44The `flush_multi_pass` component exposes no attribute (the exposed attribute 45type is `unused_type`): 46 47 flush_multi_pass --> unused 48 49[heading Example] 50 51The following example shows a simple use case of the `flush_multi_pass` parser. 52 53We will illustrate its usage by generating different comment styles and a 54function prototype (for the full example code see here: 55[@../../example/qi/flush_multi_pass.cpp flush_multi_pass.cpp]) 56 57[import ../../example/qi/flush_multi_pass.cpp] 58 59[heading Prerequisites] 60 61In addition to the main header file needed to include the core components 62implemented in __qi__ we add the header file needed for the new 63`flush_multi_pass` parser. 64 65[qi_flush_multi_pass_includes] 66 67To make all the code below more readable we introduce the following namespaces. 68 69[qi_flush_multi_pass_namespace] 70 71[heading Clearing the internal buffer] 72 73The example grammar recognizes the (simplified) preprocessor commands `#define` 74and `#undef` both of which are constraint to a single line. This makes it 75possible to delete all internal iterator buffers on each detected line break. 76This is safe as no backtracking will occur after any line end. The following 77code snippet shows the usage of `flush_multi_pass` for this purpose. 78 79[qi_flush_multi_pass_clear_buffer] 80 81[note Using the `flush_multi_pass` parser component with iterators other than 82 `multi_pass` is safe as it has no effect on the parsing.] 83 84[endsect] 85