[/============================================================================== Copyright (C) 2001-2011 Joel de Guzman Copyright (C) 2001-2011 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 Auxiliary Parsers] 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 #include Also, see __include_structure__. [/------------------------------------------------------------------------------] [section:attr Attribute Parser (`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 #include 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 Parser (`attr_cast`)] [heading Description] The `attr_cast()` 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 #include Also, see __include_structure__. [heading Namespace] [table [[Name]] [[`boost::spirit::attr_cast // alias: boost::spirit::qi::attr_cast`]] ] [heading Synopsis] template attr_cast(); [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(p) attr_cast(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(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(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(p)`] [`p: A --> attr_cast(p): Exposed`]] [[`attr_cast(p)`] [`p: A --> attr_cast(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 Parser (`eol`)] [heading Description] The `eol` parser matches the end of line (CR/LF and combinations thereof). [heading Header] // forwards to #include 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 Parser (`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 #include 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 Parser (`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 #include 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 Parser (`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 #include 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]