| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| ===============================================================================/] |
| |
| [section Auxiliary] |
| |
| This module includes different auxiliary parsers not fitting into any of the |
| other categories. This module includes the `attr`, `attr_cast`, `eoi`, `eol`, |
| `eps`, and `lazy` parsers. |
| |
| [heading Module Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary.hpp> |
| #include <boost/spirit/include/qi_auxiliary.hpp> |
| |
| Also, see __include_structure__. |
| |
| [/------------------------------------------------------------------------------] |
| [section:attr Attribute (`attr`)] |
| |
| [heading Description] |
| |
| The Attribute parser does not consume any input, for this reason it |
| always matches an empty string and always succeeds. It's purpose is to |
| expose its specified parameter as an attribute. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/attr.hpp> |
| #include <boost/spirit/include/qi_attr.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::attr // alias: boost::spirit::qi::attr`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [variablelist Notation |
| [[`a`] [A arbitrary typed constant value, e.g. 0.0, "Hello", or a |
| variable of arbitrary type or a __qi_lazy_argument__ that evaluates |
| to an arbitrary type.]] |
| [[`A`] [The type of `a` or if it is a __qi_lazy_argument__, its |
| return type.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`attr(a)`] [Create a pseudo parser exposing the current value of |
| `a` as its attribute without consuming any input |
| at parse time.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`attr(a)`] [`A`]] |
| ] |
| |
| |
| [heading Complexity] |
| |
| [:O(1)] |
| |
| The complexity is constant as no input is consumed and no matching is done. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_attr] |
| |
| Using `attr` with literals: |
| |
| [reference_attr] |
| |
| Using `attr` with __phoenix__ function objects: |
| |
| [reference_attr_phoenix] |
| |
| [endsect] [/ attr] |
| |
| [/------------------------------------------------------------------------------] |
| [section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)] |
| |
| [heading Description] |
| |
| The `attr_cast<Exposed, Transformed>()` component invokes the embedded parser |
| while supplying an attribute of type `Transformed`. The supplied attribute gets created |
| from the original attribute (of type `Exposed`) passed to this component using the |
| customization point __customize_transform_attribute__. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/attr_cast.hpp> |
| #include <boost/spirit/include/qi_attr_cast.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::attr_cast // alias: boost::spirit::qi::attr_cast`]] |
| ] |
| |
| [heading Synopsis] |
| |
| template <Exposed, Transformed> |
| <unspecified> attr_cast(<unspecified>); |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description] [Default]] |
| [[`Exposed`] [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]] |
| [[`Transformed`][The type of the attribute expected by the embedded |
| parser `p`.] [__unused_type__]] |
| ] |
| |
| The `attr_cast` is a function template. It is possible to invoke it using the |
| following schemes: |
| |
| attr_cast(p) |
| attr_cast<Exposed>(p) |
| attr_cast<Exposed, Transformed>(p) |
| |
| depending on which of the attribute types can be deduced properly if not |
| explicitly specified. |
| |
| [heading Model of] |
| |
| [:__unary_parser_concept__] |
| |
| [variablelist Notation |
| [[`p`] [A parser object.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __unary_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`attr_cast(p)`] [Create a component invoking the |
| parser `p` while passing an attribute of the type |
| as normally expected by `p`. The type of the supplied |
| attribute will be transformed to the type |
| `p` exposes as its attribute type (by using the |
| attribute customization point __customize_transform_attribute__).]] |
| [[`attr_cast<Exposed>(p)`] [Create a component invoking the |
| parser `p` while passing an attribute of the type |
| as normally expected by `p`. The supplied attribute |
| is expected to be of the type `Exposed`, it will be |
| transformed to the type `p` exposes as its attribute type |
| (using the attribute customization point |
| __customize_transform_attribute__).]] |
| [[`attr_cast<Exposed, Transformed>(p)`] [Create a component invoking the |
| parser `p` while passing an attribute of type |
| `Transformed`. The supplied attribute is expected |
| to be of the type `Exposed`, it will be transformed |
| to the type `Transformed` (using the attribute |
| customization point __customize_transform_attribute__).]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`attr_cast(p)`] [`p: A --> attr_cast(p): A`]] |
| [[`attr_cast<Exposed>(p)`] [`p: A --> attr_cast<Exposed>(p): Exposed`]] |
| [[`attr_cast<Exposed, Transformed>(p)`] |
| [`p: A --> attr_cast<Exposed, Transformed>(p): Exposed`]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The complexity of this component is fully defined by the complexity of the |
| embedded parser `p`.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_qi_using_declarations_attr_cast] |
| |
| The example references data structure `int_data` which needs a specialization of |
| the customization point __customize_transform_attribute__: |
| |
| [reference_qi_auxiliary_attr_cast_data1] |
| |
| Now we use the `attr_cast` pseudo parser to invoke the attribute |
| transformation: |
| |
| [reference_qi_attr_cast1] |
| |
| [endsect] |
| |
| |
| [/------------------------------------------------------------------------------] |
| [section:eol End of Line (`eol`)] |
| |
| [heading Description] |
| |
| The `eol` parser matches the end of line (CR/LF and combinations |
| thereof). |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/eol.hpp> |
| #include <boost/spirit/include/qi_eol.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::eol // alias: boost::spirit::qi::eol`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`eol`] [Create a parser that matches the end of line.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`eol`] [__unused__]] |
| ] |
| |
| [heading Complexity] |
| |
| [:O(1)] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_eol] |
| |
| Using `eol`: |
| |
| [reference_eol] |
| |
| [endsect] [/ End of Line] |
| |
| [/------------------------------------------------------------------------------] |
| [section:eoi End of Input (`eoi`)] |
| |
| [heading Description] |
| |
| The `eoi` parser matches the end of input (returns a successful match |
| with 0 length when the input is exhausted) |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/eoi.hpp> |
| #include <boost/spirit/include/qi_eoi.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::eoi // alias: boost::spirit::qi::eoi`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`eoi`] [Create a parser that matches the end of input.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`eoi`] [__unused__]] |
| ] |
| |
| [heading Complexity] |
| |
| [:O(1)] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_eoi] |
| |
| Using `eoi`: |
| |
| [reference_eoi] |
| |
| [endsect] [/ End of Input] |
| |
| [/------------------------------------------------------------------------------] |
| [section:eps Epsilon (`eps`)] |
| |
| [heading Description] |
| |
| The Epsilon (`eps`) is a multi-purpose parser that returns a zero length |
| match. |
| |
| [heading Simple Form] |
| |
| In its simplest form, `eps` matches the null string and always returns a |
| match of zero length: |
| |
| eps // always returns a zero-length match |
| |
| This form is usually used to trigger a semantic action unconditionally. |
| For example, it is useful in triggering error messages when a set of |
| alternatives fail: |
| |
| r = a | b | c | eps[error()]; // Call error if a, b, and c fail to match |
| |
| [heading Semantic Predicate] |
| |
| Semantic predicates allow you to attach a conditional function anywhere |
| in the grammar. In this role, the epsilon takes a __qi_lazy_argument__ that |
| returns `true` or `false`. The __qi_lazy_argument__ is typically a test |
| that is called to resolve ambiguity in the grammar. A parse failure will |
| be reported when the __qi_lazy_argument__ result evaluates to `false`. |
| Otherwise an empty match will be reported. The general form is: |
| |
| eps(f) >> rest; |
| |
| The __qi_lazy_argument__ `f` is called to do a semantic test (say, checking |
| if a symbol is in the symbol table). If test returns true, `rest` will |
| be evaluated. Otherwise, the production will return early with a |
| no-match without ever touching rest. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/eps.hpp> |
| #include <boost/spirit/include/qi_eps.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::eps // alias: boost::spirit::qi::eps`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_parser_concept__] |
| |
| [variablelist Notation |
| [[`f`] [A __qi_lazy_argument__ that evaluates `bool`.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`eps`] [Match an empty string (always matches).]] |
| [[`eps(f)`] [If `f` evaluates to `true`, return a zero length match.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`eps`] [__unused__]] |
| ] |
| |
| [heading Complexity] |
| |
| [:For plain (`eps`) the complexity is O(1). For Semantic predicates |
| (`eps(f)`) the complexity is defined by the function `f`.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_eps] |
| |
| [reference_eps] |
| |
| [reference_eps_if] |
| |
| [reference_eps_while] |
| |
| [endsect] [/Epsilon] |
| |
| [/------------------------------------------------------------------------------] |
| [section:lazy Lazy (`lazy`)] |
| |
| [heading Description] |
| |
| The `lazy` parser, as its name suggests, invokes a lazy __phoenix__ |
| function that returns a parser at parse time. This parser will be |
| used once it is created to continue the parse. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/qi/auxiliary/lazy.hpp> |
| #include <boost/spirit/include/qi_lazy.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::lazy // alias: boost::spirit::qi::lazy`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__parser_concept__] |
| |
| [variablelist Notation |
| [[`fp`] [A __qi_lazy_argument__ that evaluates to a |
| __parser_concept__.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __parser_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`fp`] [Create a lazy-parser from a __qi_lazy_argument__, `fp`. |
| `fp` will be invoked at parse time. `fp` is expected to |
| return a __parser_concept__ object. This parser is then |
| invoked in order to parse the input.]] |
| [[`lazy(fp)`] [Create a lazy-parser from a __qi_lazy_argument__, `fp`. |
| `fp` will be invoked at parse time. `fp` is expected to |
| return a __parser_concept__ object. This parser is then |
| invoked in order to parse the input.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`fp`] [The attribute type of the return type of `fp`.]] |
| [[`lazy(fp)`] [The attribute type of the return type of `fp`.]] |
| ] |
| |
| [heading Complexity] |
| |
| The complexity of the `lazy` parser is determined by the complexity of |
| the parser returned from `fp`. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __qi_basics_examples__ section.] |
| |
| Some using declarations: |
| |
| [reference_using_declarations_lazy] |
| |
| Using `lazy`: |
| |
| [reference_lazy] |
| |
| [endsect] [/ Lazy] |
| |
| [endsect] [/ Auxiliary] |