[/==============================================================================
    Copyright (C) 2001-2010 Hartmut Kaiser
    Copyright (C) 2001-2010 Joel de Guzman

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]

[section:flush_multi_pass Qi flush_multi_pass parser]

[heading Description]

The __qi__ `flush_multi_pass` parser is a primitive (pseudo) parser component 
allowing to clear the internal buffer of a `multi_pass` iterator. Clearing the 
buffer of a `multi_pass` might be beneficial for grammars where it is clear
that no backtracking can occur.
The general syntax for using the `flush_multi_pass` is:

    flush_multi_pass

which will call the `clear_queue()` member function if the current iterators
are of the type `multi_pass`. This will cause any buffered data to be erased. 
This also will invalidate all other copies of multi_pass and they should not 
be used. If they are, an `boost::illegal_backtracking` exception will be 
thrown. For all other iterator types this is a no-op. The `flush_multi_pass` 
generates a parser component which always succeeds and which does not consume 
any input (very much like `eps`).

[heading Header]

    // forwards to <boost/spirit/repository/home/qi/primitive/flush_multi_pass.hpp>
    #include <boost/spirit/repository/include/qi_flush_multi_pass.hpp>

[heading Synopsis]

    flush_multi_pass

[heading Parameters]

The `flush_multi_pass` does not require any parameters.

[heading Attribute]

The `flush_multi_pass` component exposes no attribute (the exposed attribute 
type is `unused_type`):

    flush_multi_pass --> unused

[heading Example]

The following example shows a simple use case of the `flush_multi_pass` parser. 

We will illustrate its usage by generating different comment styles and a 
function prototype (for the full example code see here: 
[@../../example/qi/flush_multi_pass.cpp flush_multi_pass.cpp])

[import ../example/qi/flush_multi_pass.cpp]

[heading Prerequisites]

In addition to the main header file needed to include the core components 
implemented in __qi__ we add the header file needed for the new 
`flush_multi_pass` parser.

[qi_flush_multi_pass_includes]

To make all the code below more readable we introduce the following namespaces.

[qi_flush_multi_pass_namespace]

[heading Clearing the internal buffer]

The example grammar recognizes the (simplified) preprocessor commands `#define` 
and `#undef` both of which are constraint to a single line. This makes it 
possible to delete all internal iterator buffers on each detected line break.
This is safe as no backtracking will occur after any line end. The following 
code snippet shows the usage of `flush_multi_pass` for this purpose.

[qi_flush_multi_pass_clear_buffer]

[note Using the `flush_multi_pass` parser component with iterators other than 
      `multi_pass` is safe as it has no effect on the parsing.]

[endsect]