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 15The library provides a couple of free functions to make parsing a snap. 16These parser functions have two forms. The first form `parse` works on 17the character level. The second `phrase_parse` works on the phrase level 18and requires skip parser. Both versions can take in attributes by 19reference 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 26For variadic attributes: 27 28 // forwards to <boost/spirit/home/qi/parse_attr.hpp> 29 #include <boost/spirit/include/qi_parse_attr.hpp> 30 31The variadic attributes version of the API allows one or more 32attributes to be passed into the parse functions. The functions taking two 33or more are usable when the parser expression is a __qi_sequence__ only. 34In this case each of the attributes passed have to match the corresponding 35part of the sequence. 36 37For the API functions deducing the correct (matching) parser type from the 38supplied attribute type: 39 40 // forwards to <boost/spirit/home/qi/detail/parse_auto.hpp> 41 #include <boost/spirit/include/qi_parse_auto.hpp> 42 43Also, 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 113parser 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 135All functions above return `true` if none of the involved parser components 136failed, and `false` otherwise. 137 138The maximum number of supported arguments is limited by the preprocessor 139constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined 140by 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 146The `phrase_parse` functions not taking an explicit `skip_flag` as one of their 147arguments invoke the passed skipper after a successful match of the parser 148expression. This can be inhibited by using the other versions of that function 149while 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 168The library provides a couple of Standard IO __iomanip__ allowing to integrate 169__qi__ input parsing facilities with Standard input streams. 170These parser manipulators have two forms. The first form, `match`, works on 171the character level. The second `phrase_match` works on the phrase level 172and requires a skip parser. Both versions can take in attributes by reference 173that 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 180For 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 185The variadic attributes version of the API allows one or more 186attributes to be passed into the parse manipulators. The manipulators taking 187two 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 189match the corresponding part of the sequence. 190 191For the API functions deducing the correct (matching) parser type from the 192supplied attribute type: 193 194 // forwards to <boost/spirit/home/qi/match_auto.hpp> 195 #include <boost/spirit/include/qi_match_auto.hpp> 196 197Also, 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 251parser 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 268All functions above return a standard IO stream manipulator instance (see 269__iomanip__), which when streamed from an input stream will result in parsing 270the input using the embedded __qi__ parser expression. Any error (or failed 271parse) occurring during the invocation of the __qi__ parsers will be reflected 272in the streams status flag (`std::ios_base::failbit` will be set). 273 274The maximum number of supported arguments is limited by the preprocessor 275constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined 276by 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 283The `phrase_match` manipulators not taking an explicit `skip_flag` as one of their 284arguments invoke the passed skipper after a successful match of the parser 285expression. This can be inhibited by using the other versions of that manipulator 286while 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 306The library implements a special API returning a parser instance for a 307supplied attribute type. This function finds the best matching parser type 308for the attribute based on a set of simple matching rules (as outlined in the 309table below) applied recursively to the attribute type. The returned parser 310can 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 317Also, 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 336The returned instance can be directly passed as the parser (or the skipping 337parser) to any of the __qi__ API functions. Additionally it 338can be assigned to a rule as the rules right hand side expression. This 339function will return a valid parser type only if the meta function 340`traits::create_parser_exists` returns `mpl::true_`. Otherwise it will fail 341compiling. 342 343 namespace boost { namespace spirit { namespace traits 344 { 345 template <typename Attr> 346 struct create_parser_exists; 347 }}} 348 349The meta function evaluates to `mpl::true_` if `create_parser` would return 350a valid parser for the given type `Attr`. 351 352The following table outlines the mapping rules from the attribute type to the 353parser type. These rules are applied recursively to create the parser 354type 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] 390