]> git.proxmox.com Git - ceph.git/blob - ceph/src/boost/libs/spirit/repository/doc/qi/flush_multi_pass.qbk
add subtree-ish sources for 12.0.3
[ceph.git] / ceph / src / boost / libs / spirit / repository / doc / qi / flush_multi_pass.qbk
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
13 The __qi__ `flush_multi_pass` parser is a primitive (pseudo) parser component
14 allowing to clear the internal buffer of a `multi_pass` iterator. Clearing the
15 buffer of a `multi_pass` might be beneficial for grammars where it is clear
16 that no backtracking can occur.
17 The general syntax for using the `flush_multi_pass` is:
18
19 flush_multi_pass
20
21 which will call the `clear_queue()` member function if the current iterators
22 are of the type `multi_pass`. This will cause any buffered data to be erased.
23 This also will invalidate all other copies of multi_pass and they should not
24 be used. If they are, an `boost::illegal_backtracking` exception will be
25 thrown. For all other iterator types this is a no-op. The `flush_multi_pass`
26 generates a parser component which always succeeds and which does not consume
27 any 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
40 The `flush_multi_pass` does not require any parameters.
41
42 [heading Attribute]
43
44 The `flush_multi_pass` component exposes no attribute (the exposed attribute
45 type is `unused_type`):
46
47 flush_multi_pass --> unused
48
49 [heading Example]
50
51 The following example shows a simple use case of the `flush_multi_pass` parser.
52
53 We will illustrate its usage by generating different comment styles and a
54 function 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
61 In addition to the main header file needed to include the core components
62 implemented in __qi__ we add the header file needed for the new
63 `flush_multi_pass` parser.
64
65 [qi_flush_multi_pass_includes]
66
67 To 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
73 The example grammar recognizes the (simplified) preprocessor commands `#define`
74 and `#undef` both of which are constraint to a single line. This makes it
75 possible to delete all internal iterator buffers on each detected line break.
76 This is safe as no backtracking will occur after any line end. The following
77 code 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]