ceph/src/boost/libs/spirit/doc/qi/parse_api.qbk

   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]