]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Joel de Guzman | |
3 | Copyright (C) 2001-2011 Hartmut Kaiser | |
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 | [section:parse_api Parser API] | |
9 | ||
10 | [//////////////////////////////////////////////////////////////////////////////] | |
11 | [section:iterator_api Iterator Based Parser API] | |
12 | ||
13 | [heading Description] | |
14 | ||
15 | The library provides a couple of free functions to make parsing a snap. | |
16 | These parser functions have two forms. The first form `parse` works on | |
17 | the character level. The second `phrase_parse` works on the phrase level | |
18 | and requires skip parser. Both versions can take in attributes by | |
19 | reference that will hold the parsed values on a successful parse. | |
20 | ||
21 | [heading Header] | |
22 | ||
23 | // forwards to <boost/spirit/home/qi/parse.hpp> | |
24 | #include <boost/spirit/include/qi_parse.hpp> | |
25 | ||
26 | For variadic attributes: | |
27 | ||
28 | // forwards to <boost/spirit/home/qi/parse_attr.hpp> | |
29 | #include <boost/spirit/include/qi_parse_attr.hpp> | |
30 | ||
31 | The variadic attributes version of the API allows one or more | |
32 | attributes to be passed into the parse functions. The functions taking two | |
33 | or more are usable when the parser expression is a __qi_sequence__ only. | |
34 | In this case each of the attributes passed have to match the corresponding | |
35 | part of the sequence. | |
36 | ||
37 | For the API functions deducing the correct (matching) parser type from the | |
38 | supplied attribute type: | |
39 | ||
40 | // forwards to <boost/spirit/home/qi/detail/parse_auto.hpp> | |
41 | #include <boost/spirit/include/qi_parse_auto.hpp> | |
42 | ||
43 | Also, see __include_structure__. | |
44 | ||
45 | [heading Namespace] | |
46 | ||
47 | [table | |
48 | [[Name]] | |
49 | [[`boost::spirit::qi::parse` ]] | |
50 | [[`boost::spirit::qi::phrase_parse` ]] | |
51 | [[`boost::spirit::qi::skip_flag::postskip` ]] | |
52 | [[`boost::spirit::qi::skip_flag::dont_postskip` ]] | |
53 | ] | |
54 | ||
55 | [heading Synopsis] | |
56 | ||
57 | namespace boost { namespace spirit { namespace qi | |
58 | { | |
59 | template <typename Iterator, typename Expr> | |
60 | inline bool | |
61 | parse( | |
62 | Iterator& first | |
63 | , Iterator last | |
64 | , Expr const& expr); | |
65 | ||
66 | template <typename Iterator, typename Expr | |
67 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
68 | inline bool | |
69 | parse( | |
70 | Iterator& first | |
71 | , Iterator last | |
72 | , Expr const& expr | |
73 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
74 | ||
75 | template <typename Iterator, typename Expr, typename Skipper> | |
76 | inline bool | |
77 | phrase_parse( | |
78 | Iterator& first | |
79 | , Iterator last | |
80 | , Expr const& expr | |
81 | , Skipper const& skipper | |
82 | , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip); | |
83 | ||
84 | template <typename Iterator, typename Expr, typename Skipper | |
85 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
86 | inline bool | |
87 | phrase_parse( | |
88 | Iterator& first | |
89 | , Iterator last | |
90 | , Expr const& expr | |
91 | , Skipper const& skipper | |
92 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
93 | ||
94 | template <typename Iterator, typename Expr, typename Skipper | |
95 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
96 | inline bool | |
97 | phrase_parse( | |
98 | Iterator& first | |
99 | , Iterator last | |
100 | , Expr const& expr | |
101 | , Skipper const& skipper | |
102 | , BOOST_SCOPED_ENUM(skip_flag) post_skip | |
103 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
104 | }}} | |
105 | ||
106 | [note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the | |
107 | placeholder `_val` can be used in semantic actions attached to top level | |
108 | parser components. In this case `_val` refers to the supplied attribute | |
109 | as a whole. For API functions taking more than one attribute argument | |
110 | `_val` will refer to a Fusion vector or references to the attributes.] | |
111 | ||
112 | __qi__ parser API functions based on the automatic creation of the matching | |
113 | parser type: | |
114 | ||
115 | namespace boost { namespace spirit { namespace qi | |
116 | { | |
117 | template <typename Iterator, typename Attr> | |
118 | inline bool | |
119 | parse( | |
120 | Iterator& first | |
121 | , Iterator last | |
122 | , Attr& attr); | |
123 | ||
124 | ||
125 | template <typename Iterator, typename Attr, typename Skipper> | |
126 | inline bool | |
127 | phrase_parse( | |
128 | Iterator& first | |
129 | , Iterator last | |
130 | , Attr& attr | |
131 | , Skipper const& skipper | |
132 | , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip); | |
133 | }}} | |
134 | ||
135 | All functions above return `true` if none of the involved parser components | |
136 | failed, and `false` otherwise. | |
137 | ||
138 | The maximum number of supported arguments is limited by the preprocessor | |
139 | constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined | |
140 | by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). | |
141 | ||
142 | [note The variadic functions with two or more attributes internally combine | |
143 | references to all passed attributes into a `fusion::vector` and forward | |
144 | this as a combined attribute to the corresponding one attribute function.] | |
145 | ||
146 | The `phrase_parse` functions not taking an explicit `skip_flag` as one of their | |
147 | arguments invoke the passed skipper after a successful match of the parser | |
148 | expression. This can be inhibited by using the other versions of that function | |
149 | while passing `skip_flag::dont_postskip` to the corresponding argument. | |
150 | ||
151 | [table | |
152 | [[Parameter] [Description]] | |
153 | [[`Iterator`] [__fwditer__ pointing to the source to parse.]] | |
154 | [[`Expr`] [An expression that can be converted to a Qi parser.]] | |
155 | [[`Skipper`] [Parser used to skip white spaces.]] | |
156 | [[`Attr`] [An attribute type utilized to create the corresponding | |
157 | parser type from.]] | |
158 | [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]] | |
159 | ] | |
160 | ||
161 | [endsect] [/ Iterator Based Parser API] | |
162 | ||
163 | [//////////////////////////////////////////////////////////////////////////////] | |
164 | [section:stream_api Stream Based Parser API] | |
165 | ||
166 | [heading Description] | |
167 | ||
168 | The library provides a couple of Standard IO __iomanip__ allowing to integrate | |
169 | __qi__ input parsing facilities with Standard input streams. | |
170 | These parser manipulators have two forms. The first form, `match`, works on | |
171 | the character level. The second `phrase_match` works on the phrase level | |
172 | and requires a skip parser. Both versions can take in attributes by reference | |
173 | that will hold the parsed values on a successful parse. | |
174 | ||
175 | [heading Header] | |
176 | ||
177 | // forwards to <boost/spirit/home/qi/stream/match_manip.hpp> | |
178 | #include <boost/spirit/include/qi_match.hpp> | |
179 | ||
180 | For variadic attributes: | |
181 | ||
182 | // forwards to <boost/spirit/home/qi/stream/match_manip_attr.hpp> | |
183 | #include <boost/spirit/include/qi_match_attr.hpp> | |
184 | ||
185 | The variadic attributes version of the API allows one or more | |
186 | attributes to be passed into the parse manipulators. The manipulators taking | |
187 | two or more attributes are usable when the parser expression is a | |
188 | __qi_sequence__ only. In this case each of the attributes passed have to | |
189 | match the corresponding part of the sequence. | |
190 | ||
191 | For the API functions deducing the correct (matching) parser type from the | |
192 | supplied attribute type: | |
193 | ||
194 | // forwards to <boost/spirit/home/qi/match_auto.hpp> | |
195 | #include <boost/spirit/include/qi_match_auto.hpp> | |
196 | ||
197 | Also, see __include_structure__. | |
198 | ||
199 | [heading Namespace] | |
200 | ||
201 | [table | |
202 | [[Name]] | |
203 | [[`boost::spirit::qi::match` ]] | |
204 | [[`boost::spirit::qi::phrase_match` ]] | |
205 | [[`boost::spirit::qi::skip_flag::postskip` ]] | |
206 | [[`boost::spirit::qi::skip_flag::dont_postskip` ]] | |
207 | ] | |
208 | ||
209 | [heading Synopsis] | |
210 | ||
211 | namespace boost { namespace spirit { namespace qi | |
212 | { | |
213 | template <typename Expr> | |
214 | inline <unspecified> | |
215 | match( | |
216 | Expr const& xpr); | |
217 | ||
218 | template <typename Expr | |
219 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
220 | inline <unspecified> | |
221 | match( | |
222 | Expr const& xpr | |
223 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
224 | ||
225 | template <typename Expr, typename Skipper> | |
226 | inline <unspecified> | |
227 | phrase_match( | |
228 | Expr const& expr | |
229 | , Skipper const& s | |
230 | , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip); | |
231 | ||
232 | template <typename Expr, typename Skipper | |
233 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
234 | inline <unspecified> | |
235 | phrase_match( | |
236 | Expr const& expr | |
237 | , Skipper const& s | |
238 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
239 | ||
240 | template <typename Expr, typename Skipper | |
241 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
242 | inline <unspecified> | |
243 | phrase_match( | |
244 | Expr const& expr | |
245 | , Skipper const& s | |
246 | , BOOST_SCOPED_ENUM(skip_flag) post_skip | |
247 | , Attr1& attr1, Attr2& attr2, ..., AttrN& attrN); | |
248 | }}} | |
249 | ||
250 | __qi__ parser API functions based on the automatic creation of the matching | |
251 | parser type: | |
252 | ||
253 | namespace boost { namespace spirit { namespace qi | |
254 | { | |
255 | template <typename Attr> | |
256 | inline <unspecified> | |
257 | match( | |
258 | Attr& attr); | |
259 | ||
260 | template <typename Attr, typename Skipper> | |
261 | inline <unspecified> | |
262 | phrase_match( | |
263 | Attr& attr | |
264 | , Skipper const& s | |
265 | , BOOST_SCOPED_ENUM(skip_flag) post_skip = skip_flag::postskip); | |
266 | }}} | |
267 | ||
268 | All functions above return a standard IO stream manipulator instance (see | |
269 | __iomanip__), which when streamed from an input stream will result in parsing | |
270 | the input using the embedded __qi__ parser expression. Any error (or failed | |
271 | parse) occurring during the invocation of the __qi__ parsers will be reflected | |
272 | in the streams status flag (`std::ios_base::failbit` will be set). | |
273 | ||
274 | The maximum number of supported arguments is limited by the preprocessor | |
275 | constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined | |
276 | by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). | |
277 | ||
278 | [note The variadic manipulators with two or more attributes internally combine | |
279 | references to all passed attributes into a `fusion::vector` | |
280 | and forward this as a combined attribute to the corresponding manipulator | |
281 | taking one attribute.] | |
282 | ||
283 | The `phrase_match` manipulators not taking an explicit `skip_flag` as one of their | |
284 | arguments invoke the passed skipper after a successful match of the parser | |
285 | expression. This can be inhibited by using the other versions of that manipulator | |
286 | while passing `skip_flag::dont_postskip` to the corresponding argument. | |
287 | ||
288 | [heading Template parameters] | |
289 | ||
290 | [table | |
291 | [[Parameter] [Description]] | |
292 | [[`Expr`] [An expression that can be converted to a Qi parser.]] | |
293 | [[`Skipper`] [Parser used to skip white spaces.]] | |
294 | [[`Attr`] [An attribute type utilized to create the corresponding | |
295 | parser type from.]] | |
296 | [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]] | |
297 | ] | |
298 | ||
299 | [endsect] [/ Stream Based Parser API] | |
300 | ||
301 | [//////////////////////////////////////////////////////////////////////////////] | |
302 | [section:create_parser API for Automatic Parser Creation] | |
303 | ||
304 | [heading Description] | |
305 | ||
306 | The library implements a special API returning a parser instance for a | |
307 | supplied attribute type. This function finds the best matching parser type | |
308 | for the attribute based on a set of simple matching rules (as outlined in the | |
309 | table below) applied recursively to the attribute type. The returned parser | |
310 | can be utilized to match input for the provided attribute. | |
311 | ||
312 | [heading Header] | |
313 | ||
314 | // forwards to <boost/spirit/home/qi/auto.hpp> | |
315 | #include <boost/spirit/include/qi_auto.hpp> | |
316 | ||
317 | Also, see __include_structure__. | |
318 | ||
319 | [heading Namespace] | |
320 | ||
321 | [table | |
322 | [[Name]] | |
323 | [[`boost::spirit::qi::create_parser`]] | |
324 | [[`boost::spirit::traits::create_parser_exists`]] | |
325 | ] | |
326 | ||
327 | [heading Synopsis] | |
328 | ||
329 | namespace boost { namespace spirit { namespace qi | |
330 | { | |
331 | template <typename Attr> | |
332 | inline <unspecified> | |
333 | create_parser(); | |
334 | }}} | |
335 | ||
336 | The returned instance can be directly passed as the parser (or the skipping | |
337 | parser) to any of the __qi__ API functions. Additionally it | |
338 | can be assigned to a rule as the rules right hand side expression. This | |
339 | function will return a valid parser type only if the meta function | |
340 | `traits::create_parser_exists` returns `mpl::true_`. Otherwise it will fail | |
341 | compiling. | |
342 | ||
343 | namespace boost { namespace spirit { namespace traits | |
344 | { | |
345 | template <typename Attr> | |
346 | struct create_parser_exists; | |
347 | }}} | |
348 | ||
349 | The meta function evaluates to `mpl::true_` if `create_parser` would return | |
350 | a valid parser for the given type `Attr`. | |
351 | ||
352 | The following table outlines the mapping rules from the attribute type to the | |
353 | parser type. These rules are applied recursively to create the parser | |
354 | type which can be used to match input for the given attribute type. | |
355 | ||
356 | [table | |
357 | [[Attribute type] [Generator type]] | |
358 | [[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]] | |
359 | [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] | |
360 | [[`unsigned short`, `unsigned int`, `unsigned long`] | |
361 | [`ushort_`, `uint_`, `ulong_`]] | |
362 | [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]] | |
363 | [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] | |
364 | [[`long long`, `unsigned long long`] | |
365 | [`long_long`, `ulong_long`]] | |
366 | [[`bool`] [`bool_`]] | |
367 | [[Any (STL) container] [Kleene Star (unary `'*'`)]] | |
368 | [[Any Fusion sequence] [Sequence operator (`'<<'`)]] | |
369 | [[`boost::optional<>`] [Optional operator (unary `'-'`)]] | |
370 | [[`boost::variant<>`] [Alternative operator (`'|'`)]] | |
371 | ] | |
372 | ||
373 | [important The mapping for the parsers `long_long` and `ulong_long` are only | |
374 | available on platforms where the preprocessor constant | |
375 | `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native | |
376 | support for `long long` and `unsigned long long` (64 bit) signed and | |
377 | unsigned integer types).] | |
378 | ||
379 | [heading Template parameters] | |
380 | ||
381 | [table | |
382 | [[Parameter] [Description]] | |
383 | [[`Attr`] [An attribute type utilized to create the corresponding | |
384 | parser type from.]] | |
385 | ] | |
386 | ||
387 | [endsect] [/ API for Automatic Parser Creation] | |
388 | ||
389 | [endsect] |