libs/spirit/doc/qi/auxiliary.qbk
[/==============================================================================
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 <boost/spirit/home/qi/auxiliary.hpp>
#include <boost/spirit/include/qi_auxiliary.hpp>
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 <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 Parser (`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 Parser (`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 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 <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 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 <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 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 <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]
