ceph/src/boost/libs/spirit/doc/qi/auxiliary.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
   9 [section:auxiliary Auxiliary Parsers]
  10
  11 This module includes different auxiliary parsers not fitting into any of the
  12 other categories. This module includes the `attr`, `attr_cast`, `eoi`, `eol`,
  13 `eps`, and `lazy` parsers.
  14
  15 [heading Module Header]
  16
  17     // forwards to <boost/spirit/home/qi/auxiliary.hpp>
  18     #include <boost/spirit/include/qi_auxiliary.hpp>
  19
  20 Also, see __include_structure__.
  21
  22 [/------------------------------------------------------------------------------]
  23 [section:attr Attribute Parser (`attr`)]
  24
  25 [heading Description]
  26
  27 The Attribute parser does not consume any input, for this reason it
  28 always matches an empty string and always succeeds. It's purpose is to
  29 expose its specified parameter as an attribute.
  30
  31 [heading Header]
  32
  33     // forwards to <boost/spirit/home/qi/auxiliary/attr.hpp>
  34     #include <boost/spirit/include/qi_attr.hpp>
  35
  36 Also, see __include_structure__.
  37
  38 [heading Namespace]
  39
  40 [table
  41     [[Name]]
  42     [[`boost::spirit::attr // alias: boost::spirit::qi::attr`]]
  43 ]
  44
  45 [heading Model of]
  46
  47 [:__primitive_parser_concept__]
  48
  49 [variablelist Notation
  50     [[`a`]          [A arbitrary typed constant value, e.g. 0.0, "Hello", or a
  51                     variable of arbitrary type or a __qi_lazy_argument__ that evaluates
  52                     to an arbitrary type.]]
  53     [[`A`]          [The type of `a` or if it is a __qi_lazy_argument__, its
  54                     return type.]]
  55 ]
  56
  57 [heading Expression Semantics]
  58
  59 Semantics of an expression is defined only where it differs from, or is
  60 not defined in __primitive_parser_concept__.
  61
  62 [table
  63     [[Expression]       [Semantics]]
  64     [[`attr(a)`]        [Create a pseudo parser exposing the current value of
  65                         `a` as its attribute without consuming any input
  66                         at parse time.]]
  67 ]
  68
  69 [heading Attributes]
  70
  71 [table
  72     [[Expression]       [Attribute]]
  73     [[`attr(a)`]        [`A`]]
  74 ]
  75
  76
  77 [heading Complexity]
  78
  79 [:O(1)]
  80
  81 The complexity is constant as no input is consumed and no matching is done.
  82
  83 [heading Example]
  84
  85 [note The test harness for the example(s) below is presented in the
  86 __qi_basics_examples__ section.]
  87
  88 Some using declarations:
  89
  90 [reference_using_declarations_attr]
  91
  92 Using `attr` with literals:
  93
  94 [reference_attr]
  95
  96 Using `attr` with __phoenix__ function objects:
  97
  98 [reference_attr_phoenix]
  99
 100 [endsect] [/ attr]
 101
 102 [/------------------------------------------------------------------------------]
 103 [section:attr_cast Attribute Transformation Pseudo Parser (`attr_cast`)]
 104
 105 [heading Description]
 106
 107 The `attr_cast<Exposed, Transformed>()` component invokes the embedded parser
 108 while supplying an attribute of type `Transformed`. The supplied attribute gets created
 109 from the original attribute (of type `Exposed`) passed to this component using the
 110 customization point __customize_transform_attribute__.
 111
 112 [heading Header]
 113
 114     // forwards to <boost/spirit/home/qi/auxiliary/attr_cast.hpp>
 115     #include <boost/spirit/include/qi_attr_cast.hpp>
 116
 117 Also, see __include_structure__.
 118
 119 [heading Namespace]
 120
 121 [table
 122     [[Name]]
 123     [[`boost::spirit::attr_cast // alias: boost::spirit::qi::attr_cast`]]
 124 ]
 125
 126 [heading Synopsis]
 127
 128     template <Exposed, Transformed>
 129     <unspecified> attr_cast(<unspecified>);
 130
 131 [heading Template parameters]
 132
 133 [table
 134     [[Parameter]    [Description]                       [Default]]
 135     [[`Exposed`]    [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]]
 136     [[`Transformed`][The type of the attribute expected by the embedded
 137                      parser `p`.]                    [__unused_type__]]
 138 ]
 139
 140 The `attr_cast` is a function template. It is possible to invoke it using the
 141 following schemes:
 142
 143     attr_cast(p)
 144     attr_cast<Exposed>(p)
 145     attr_cast<Exposed, Transformed>(p)
 146
 147 depending on which of the attribute types can be deduced properly if not
 148 explicitly specified.
 149
 150 [heading Model of]
 151
 152 [:__unary_parser_concept__]
 153
 154 [variablelist Notation
 155     [[`p`]          [A parser object.]]
 156 ]
 157
 158 [heading Expression Semantics]
 159
 160 Semantics of an expression is defined only where it differs from, or is
 161 not defined in __unary_parser_concept__.
 162
 163 [table
 164     [[Expression]             [Semantics]]
 165     [[`attr_cast(p)`]         [Create a component invoking the
 166                               parser `p` while passing an attribute of the type
 167                               as normally expected by `p`. The type of the supplied
 168                               attribute will be transformed to the type
 169                               `p` exposes as its attribute type (by using the
 170                               attribute customization point __customize_transform_attribute__).]]
 171     [[`attr_cast<Exposed>(p)`] [Create a component invoking the
 172                               parser `p` while passing an attribute of the type
 173                               as normally expected by `p`. The supplied attribute
 174                               is expected to be of the type `Exposed`, it will be
 175                               transformed to the type `p` exposes as its attribute type
 176                               (using the attribute customization point
 177                               __customize_transform_attribute__).]]
 178     [[`attr_cast<Exposed, Transformed>(p)`] [Create a component invoking the
 179                               parser `p` while passing an attribute of type
 180                               `Transformed`. The supplied attribute is expected
 181                               to be of the type `Exposed`, it will be transformed
 182                               to the type `Transformed` (using the attribute
 183                               customization point __customize_transform_attribute__).]]
 184 ]
 185
 186 [heading Attributes]
 187
 188 [table
 189     [[Expression]                             [Attribute]]
 190     [[`attr_cast(p)`]                         [`p: A --> attr_cast(p): A`]]
 191     [[`attr_cast<Exposed>(p)`] [`p: A --> attr_cast<Exposed>(p): Exposed`]]
 192     [[`attr_cast<Exposed, Transformed>(p)`]
 193                   [`p: A --> attr_cast<Exposed, Transformed>(p): Exposed`]]
 194 ]
 195
 196 [heading Complexity]
 197
 198 [:The complexity of this component is fully defined by the complexity of the
 199   embedded parser `p`.]
 200
 201 [heading Example]
 202
 203 [note The test harness for the example(s) below is presented in the
 204       __qi_basics_examples__ section.]
 205
 206 Some using declarations:
 207
 208 [reference_qi_using_declarations_attr_cast]
 209
 210 The example references data structure `int_data` which needs a specialization of
 211 the customization point __customize_transform_attribute__:
 212
 213 [reference_qi_auxiliary_attr_cast_data1]
 214
 215 Now we use the `attr_cast` pseudo parser to invoke the attribute
 216 transformation:
 217
 218 [reference_qi_attr_cast1]
 219
 220 [endsect]
 221
 222
 223 [/------------------------------------------------------------------------------]
 224 [section:eol End of Line Parser (`eol`)]
 225
 226 [heading Description]
 227
 228 The `eol` parser matches the end of line (CR/LF and combinations
 229 thereof).
 230
 231 [heading Header]
 232
 233     // forwards to <boost/spirit/home/qi/auxiliary/eol.hpp>
 234     #include <boost/spirit/include/qi_eol.hpp>
 235
 236 Also, see __include_structure__.
 237
 238 [heading Namespace]
 239
 240 [table
 241     [[Name]]
 242     [[`boost::spirit::eol // alias: boost::spirit::qi::eol`]]
 243 ]
 244
 245 [heading Model of]
 246
 247 [:__primitive_parser_concept__]
 248
 249 [heading Expression Semantics]
 250
 251 Semantics of an expression is defined only where it differs from, or is
 252 not defined in __primitive_parser_concept__.
 253
 254 [table
 255     [[Expression]       [Semantics]]
 256     [[`eol`]            [Create a parser that matches the end of line.]]
 257 ]
 258
 259 [heading Attributes]
 260
 261 [table
 262     [[Expression]       [Attribute]]
 263     [[`eol`]            [__unused__]]
 264 ]
 265
 266 [heading Complexity]
 267
 268 [:O(1)]
 269
 270 [heading Example]
 271
 272 [note The test harness for the example(s) below is presented in the
 273 __qi_basics_examples__ section.]
 274
 275 Some using declarations:
 276
 277 [reference_using_declarations_eol]
 278
 279 Using `eol`:
 280
 281 [reference_eol]
 282
 283 [endsect] [/ End of Line]
 284
 285 [/------------------------------------------------------------------------------]
 286 [section:eoi End of Input Parser (`eoi`)]
 287
 288 [heading Description]
 289
 290 The `eoi` parser matches the end of input (returns a successful match
 291 with 0 length when the input is exhausted)
 292
 293 [heading Header]
 294
 295     // forwards to <boost/spirit/home/qi/auxiliary/eoi.hpp>
 296     #include <boost/spirit/include/qi_eoi.hpp>
 297
 298 Also, see __include_structure__.
 299
 300 [heading Namespace]
 301
 302 [table
 303     [[Name]]
 304     [[`boost::spirit::eoi // alias: boost::spirit::qi::eoi`]]
 305 ]
 306
 307 [heading Model of]
 308
 309 [:__primitive_parser_concept__]
 310
 311 [heading Expression Semantics]
 312
 313 Semantics of an expression is defined only where it differs from, or is
 314 not defined in __primitive_parser_concept__.
 315
 316 [table
 317     [[Expression]       [Semantics]]
 318     [[`eoi`]            [Create a parser that matches the end of input.]]
 319 ]
 320
 321 [heading Attributes]
 322
 323 [table
 324     [[Expression]       [Attribute]]
 325     [[`eoi`]            [__unused__]]
 326 ]
 327
 328 [heading Complexity]
 329
 330 [:O(1)]
 331
 332 [heading Example]
 333
 334 [note The test harness for the example(s) below is presented in the
 335 __qi_basics_examples__ section.]
 336
 337 Some using declarations:
 338
 339 [reference_using_declarations_eoi]
 340
 341 Using `eoi`:
 342
 343 [reference_eoi]
 344
 345 [endsect] [/ End of Input]
 346
 347 [/------------------------------------------------------------------------------]
 348 [section:eps Epsilon Parser (`eps`)]
 349
 350 [heading Description]
 351
 352 The Epsilon (`eps`) is a multi-purpose parser that returns a zero length
 353 match.
 354
 355 [heading Simple Form]
 356
 357 In its simplest form, `eps` matches the null string and always returns a
 358 match of zero length:
 359
 360     eps // always returns a zero-length match
 361
 362 This form is usually used to trigger a semantic action unconditionally.
 363 For example, it is useful in triggering error messages when a set of
 364 alternatives fail:
 365
 366     r = a | b | c | eps[error()]; // Call error if a, b, and c fail to match
 367
 368 [heading Semantic Predicate]
 369
 370 Semantic predicates allow you to attach a conditional function anywhere
 371 in the grammar. In this role, the epsilon takes a __qi_lazy_argument__ that
 372 returns `true` or `false`. The __qi_lazy_argument__ is typically a test
 373 that is called to resolve ambiguity in the grammar. A parse failure will
 374 be reported when the __qi_lazy_argument__ result evaluates to `false`.
 375 Otherwise an empty match will be reported. The general form is:
 376
 377     eps(f) >> rest;
 378
 379 The __qi_lazy_argument__ `f` is called to do a semantic test (say, checking
 380 if a symbol is in the symbol table). If test returns true, `rest` will
 381 be evaluated. Otherwise, the production will return early with a
 382 no-match without ever touching rest.
 383
 384 [heading Header]
 385
 386     // forwards to <boost/spirit/home/qi/auxiliary/eps.hpp>
 387     #include <boost/spirit/include/qi_eps.hpp>
 388
 389 Also, see __include_structure__.
 390
 391 [heading Namespace]
 392
 393 [table
 394     [[Name]]
 395     [[`boost::spirit::eps // alias: boost::spirit::qi::eps`]]
 396 ]
 397
 398 [heading Model of]
 399
 400 [:__primitive_parser_concept__]
 401
 402 [variablelist Notation
 403     [[`f`]    [A __qi_lazy_argument__ that evaluates `bool`.]]
 404 ]
 405
 406 [heading Expression Semantics]
 407
 408 Semantics of an expression is defined only where it differs from, or is
 409 not defined in __primitive_parser_concept__.
 410
 411 [table
 412     [[Expression]       [Semantics]]
 413     [[`eps`]            [Match an empty string (always matches).]]
 414     [[`eps(f)`]         [If `f` evaluates to `true`, return a zero length match.]]
 415 ]
 416
 417 [heading Attributes]
 418
 419 [table
 420     [[Expression]       [Attribute]]
 421     [[`eps`]            [__unused__]]
 422 ]
 423
 424 [heading Complexity]
 425
 426 [:For plain (`eps`) the complexity is O(1). For Semantic predicates
 427 (`eps(f)`) the complexity is defined by the function `f`.]
 428
 429 [heading Example]
 430
 431 [note The test harness for the example(s) below is presented in the
 432 __qi_basics_examples__ section.]
 433
 434 Some using declarations:
 435
 436 [reference_using_declarations_eps]
 437
 438 [reference_eps]
 439
 440 [reference_eps_if]
 441
 442 [reference_eps_while]
 443
 444 [endsect] [/Epsilon]
 445
 446 [/------------------------------------------------------------------------------]
 447 [section:lazy Lazy Parser (`lazy`)]
 448
 449 [heading Description]
 450
 451 The `lazy` parser, as its name suggests, invokes a lazy __phoenix__
 452 function that returns a parser at parse time. This parser will be
 453 used once it is created to continue the parse.
 454
 455 [heading Header]
 456
 457     // forwards to <boost/spirit/home/qi/auxiliary/lazy.hpp>
 458     #include <boost/spirit/include/qi_lazy.hpp>
 459
 460 Also, see __include_structure__.
 461
 462 [heading Namespace]
 463
 464 [table
 465     [[Name]]
 466     [[`boost::spirit::lazy // alias: boost::spirit::qi::lazy`]]
 467 ]
 468
 469 [heading Model of]
 470
 471 [:__parser_concept__]
 472
 473 [variablelist Notation
 474     [[`fp`]     [A __qi_lazy_argument__ that evaluates to a
 475                 __parser_concept__.]]
 476 ]
 477
 478 [heading Expression Semantics]
 479
 480 Semantics of an expression is defined only where it differs from, or is
 481 not defined in __parser_concept__.
 482
 483 [table
 484     [[Expression]       [Semantics]]
 485     [[`fp`]             [Create a lazy-parser from a __qi_lazy_argument__, `fp`.
 486                         `fp` will be invoked at parse time. `fp` is expected to
 487                         return a __parser_concept__ object. This parser is then
 488                         invoked in order to parse the input.]]
 489     [[`lazy(fp)`]       [Create a lazy-parser from a __qi_lazy_argument__, `fp`.
 490                         `fp` will be invoked at parse time. `fp` is expected to
 491                         return a __parser_concept__ object. This parser is then
 492                         invoked in order to parse the input.]]
 493 ]
 494
 495 [heading Attributes]
 496
 497 [table
 498     [[Expression]       [Attribute]]
 499     [[`fp`]             [The attribute type of the return type of `fp`.]]
 500     [[`lazy(fp)`]       [The attribute type of the return type of `fp`.]]
 501 ]
 502
 503 [heading Complexity]
 504
 505 The complexity of the `lazy` parser is determined by the complexity of
 506 the parser returned from `fp`.
 507
 508 [heading Example]
 509
 510 [note The test harness for the example(s) below is presented in the
 511 __qi_basics_examples__ section.]
 512
 513 Some using declarations:
 514
 515 [reference_using_declarations_lazy]
 516
 517 Using `lazy`:
 518
 519 [reference_lazy]
 520
 521 [endsect] [/ Lazy]
 522
 523 [endsect] [/ Auxiliary]