123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523 |
- [/==============================================================================
- 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]
|