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 11This module includes different auxiliary parsers not fitting into any of the 12other 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 20Also, see __include_structure__. 21 22[/------------------------------------------------------------------------------] 23[section:attr Attribute Parser (`attr`)] 24 25[heading Description] 26 27The Attribute parser does not consume any input, for this reason it 28always matches an empty string and always succeeds. It's purpose is to 29expose 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 36Also, 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 59Semantics of an expression is defined only where it differs from, or is 60not 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 81The 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 88Some using declarations: 89 90[reference_using_declarations_attr] 91 92Using `attr` with literals: 93 94[reference_attr] 95 96Using `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 107The `attr_cast<Exposed, Transformed>()` component invokes the embedded parser 108while supplying an attribute of type `Transformed`. The supplied attribute gets created 109from the original attribute (of type `Exposed`) passed to this component using the 110customization 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 117Also, 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 140The `attr_cast` is a function template. It is possible to invoke it using the 141following schemes: 142 143 attr_cast(p) 144 attr_cast<Exposed>(p) 145 attr_cast<Exposed, Transformed>(p) 146 147depending on which of the attribute types can be deduced properly if not 148explicitly 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 160Semantics of an expression is defined only where it differs from, or is 161not 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 206Some using declarations: 207 208[reference_qi_using_declarations_attr_cast] 209 210The example references data structure `int_data` which needs a specialization of 211the customization point __customize_transform_attribute__: 212 213[reference_qi_auxiliary_attr_cast_data1] 214 215Now we use the `attr_cast` pseudo parser to invoke the attribute 216transformation: 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 228The `eol` parser matches the end of line (CR/LF and combinations 229thereof). 230 231[heading Header] 232 233 // forwards to <boost/spirit/home/qi/auxiliary/eol.hpp> 234 #include <boost/spirit/include/qi_eol.hpp> 235 236Also, 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 251Semantics of an expression is defined only where it differs from, or is 252not 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 275Some using declarations: 276 277[reference_using_declarations_eol] 278 279Using `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 290The `eoi` parser matches the end of input (returns a successful match 291with 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 298Also, 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 313Semantics of an expression is defined only where it differs from, or is 314not 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 337Some using declarations: 338 339[reference_using_declarations_eoi] 340 341Using `eoi`: 342 343[reference_eoi] 344 345[endsect] [/ End of Input] 346 347[/------------------------------------------------------------------------------] 348[section:eps Epsilon Parser (`eps`)] 349 350[heading Description] 351 352The Epsilon (`eps`) is a multi-purpose parser that returns a zero length 353match. 354 355[heading Simple Form] 356 357In its simplest form, `eps` matches the null string and always returns a 358match of zero length: 359 360 eps // always returns a zero-length match 361 362This form is usually used to trigger a semantic action unconditionally. 363For example, it is useful in triggering error messages when a set of 364alternatives 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 370Semantic predicates allow you to attach a conditional function anywhere 371in the grammar. In this role, the epsilon takes a __qi_lazy_argument__ that 372returns `true` or `false`. The __qi_lazy_argument__ is typically a test 373that is called to resolve ambiguity in the grammar. A parse failure will 374be reported when the __qi_lazy_argument__ result evaluates to `false`. 375Otherwise an empty match will be reported. The general form is: 376 377 eps(f) >> rest; 378 379The __qi_lazy_argument__ `f` is called to do a semantic test (say, checking 380if a symbol is in the symbol table). If test returns true, `rest` will 381be evaluated. Otherwise, the production will return early with a 382no-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 389Also, 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 408Semantics of an expression is defined only where it differs from, or is 409not 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 434Some 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 451The `lazy` parser, as its name suggests, invokes a lazy __phoenix__ 452function that returns a parser at parse time. This parser will be 453used 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 460Also, 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 480Semantics of an expression is defined only where it differs from, or is 481not 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 505The complexity of the `lazy` parser is determined by the complexity of 506the 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 513Some using declarations: 514 515[reference_using_declarations_lazy] 516 517Using `lazy`: 518 519[reference_lazy] 520 521[endsect] [/ Lazy] 522 523[endsect] [/ Auxiliary] 524