524 lines
14 KiB
Plaintext
524 lines
14 KiB
Plaintext
[/==============================================================================
|
|
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]
|