| [/============================================================================== |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| Copyright (C) 2001-2010 Joel de Guzman |
| |
| 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 generators not fitting into any of the |
| other categories. It includes the `attr_cast`, `eol`, `eps`, and `lazy` |
| generators. |
| |
| [heading Module Header] |
| |
| // forwards to <boost/spirit/home/karma/auxiliary.hpp> |
| #include <boost/spirit/include/karma_auxiliary.hpp> |
| |
| Also, see __include_structure__. |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)] |
| |
| [heading Description] |
| |
| The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator |
| 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/karma/auxiliary/attr_cast.hpp> |
| #include <boost/spirit/include/karma_attr_cast.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::attr_cast // alias: boost::spirit::karma::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 |
| generator `g`.] [__unused_type__]] |
| ] |
| |
| The `attr_cast` is a function template. It is possible to invoke it using the |
| following schemes: |
| |
| attr_cast(g) |
| attr_cast<Exposed>(g) |
| attr_cast<Exposed, Transformed>(g) |
| |
| depending on which of the attribute types can be deduced properly if not |
| explicitly specified. |
| |
| [heading Model of] |
| |
| [:__unary_generator_concept__] |
| |
| [variablelist Notation |
| [[`g`] [A generator object.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __unary_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`attr_cast(g)`] [Create a component invoking the |
| generator `g` while passing an attribute of the type |
| as normally expected by `g`. The type of the supplied |
| attribute will be transformed to the type |
| `g` exposes as its attribute type (by using the |
| attribute customization point __customize_transform_attribute__). |
| This generator does not fail unless `g` fails.]] |
| [[`attr_cast<Exposed>(g)`] [Create a component invoking the |
| generator `g` while passing an attribute of the type |
| as normally expected by `g`. The supplied attribute |
| is expected to be of the type `Exposed`, it will be |
| transformed to the type `g` exposes as its attribute type |
| (using the attribute customization point |
| __customize_transform_attribute__). |
| This generator does not fail unless `g` fails.]] |
| [[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the |
| generator `g` 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__). |
| This generator does not fail unless `g` fails.]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`attr_cast(g)`] [`g: A --> attr_cast(g): A`]] |
| [[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]] |
| [[`attr_cast<Exposed, Transformed>(g)`] |
| [`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]] |
| ] |
| |
| [heading Complexity] |
| |
| [:The complexity of this component is fully defined by the complexity of the |
| embedded generator `g`.] |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_attr_cast] |
| |
| The example references data structure `int_data` which needs a specialization of |
| the customization point __customize_transform_attribute__: |
| |
| [reference_karma_auxiliary_attr_cast_data1] |
| |
| Now we use the `attr_cast` pseudo generator to invoke the attribute |
| transformation: |
| |
| [reference_karma_attr_cast1] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:eol End of Line (`eol`)] |
| |
| [heading Description] |
| |
| The `eol` component generates a single newline character. It is equivalent |
| to `lit('\n')` or simply '\\n' (please see the [karma_char `char_`] generator |
| module for more details). |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/auxiliary/eol.hpp> |
| #include <boost/spirit/include/karma_eol.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::eol // alias: boost::spirit::karma::eol`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_generator_concept__] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`eol`] [Create a component generating a single end of line |
| character in the output. This generator never fails |
| (unless the underlying output stream reports an |
| error).]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`eol`] [__unused__]] |
| ] |
| |
| [heading Complexity] |
| |
| [:O(1)] |
| |
| The complexity is constant as a single character is generated in the output. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_eol] |
| |
| Basic usage of the `eol` generator: |
| |
| [reference_karma_eol] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:eps Epsilon (`eps`)] |
| |
| The family of `eps` components allows to create pseudo generators generating |
| an empty string. This feature is sometimes useful either to force a generator |
| to fail or to succeed or to insert semantic actions into the generation process. |
| |
| [heading Description] |
| |
| The Epsilon (`eps`) is a multi-purpose generator that emits a zero length |
| string. |
| |
| [heading Simple Form] |
| |
| In its simplest form, `eps` creates a component generating an empty string |
| while always succeeding: |
| |
| eps // always emits a zero-length string |
| |
| 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 generate |
| |
| [heading Semantic Predicate] |
| |
| The `eps(b)` component generates an empty string as well, but |
| succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)` |
| is equivalent to `eps(b)` except it evaluates the supplied function `fb` at |
| generate time, while using the return value as the criteria to succeed. |
| |
| Semantic predicates allow you to attach a conditional function anywhere |
| in the grammar. In this role, the epsilon takes a __karma_lazy_argument__ that |
| returns `true` or `false`. The __karma_lazy_argument__ is typically a test |
| that is called to resolve ambiguity in the grammar. A generator failure will |
| be reported when the __karma_lazy_argument__ result evaluates to `false`. |
| Otherwise an empty string will be emitted. The general form is: |
| |
| eps_p(fb) << rest; |
| |
| The __karma_lazy_argument__ `fb` is called to do a semantic test. If the test |
| returns true, `rest` will be evaluated. Otherwise, the production will return |
| early without ever touching rest. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/auxiliary/eps.hpp> |
| #include <boost/spirit/include/karma_eps.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::eps // alias: boost::spirit::karma::eps`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__primitive_generator_concept__] |
| |
| [variablelist Notation |
| [[`b`] [A boolean value.]] |
| [[`fb`] [A __karma_lazy_argument__ that evaluates to a boolean value.]] |
| ] |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __primitive_generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`eps`] [Creates a component generating an empty string. |
| Succeeds always.]] |
| [[`eps(b)`] [Creates a component generating an empty string. |
| Succeeds if `b` is `true` (unless the underlying |
| output stream reports an error).]] |
| [[`eps(fb)`] [Creates a component generating an empty string. |
| Succeeds if `fb` returns `true` at generate time |
| (unless the underlying output stream reports an |
| error).]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`eps`] [__unused__]] |
| [[`eps(b)`] [__unused__]] |
| [[`eps(fb)`] [__unused__]] |
| ] |
| |
| [heading Complexity] |
| |
| [:O(1)] |
| |
| The complexity is constant as no output is generated. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_eps] |
| |
| Basic usage of the `eps` generator: |
| |
| [reference_karma_eps] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:lazy Lazy (`lazy`)] |
| |
| [heading Description] |
| |
| The family of `lazy` components allows to use a dynamically returned generator |
| component for output generation. It calls the provided function or function |
| object at generate time using its return value as the actual generator to |
| produce the output. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp> |
| #include <boost/spirit/include/karma_lazy.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::lazy // alias: boost::spirit::karma::lazy`]] |
| ] |
| |
| [heading Model of] |
| |
| [:__generator_concept__] |
| |
| [variablelist Notation |
| [[`fg`] [A function or function object that evaluates to a generator |
| object (an object exposing the __generator_concept__). This |
| function will be invoked at generate time.]] |
| ] |
| |
| The signature of `fg` is expected to be |
| |
| G f(Unused, Context) |
| |
| where `G`, the function's return value, is the type of the generator to be |
| invoked, and `Context` is the generator's __karma_context__ type (The |
| first argument is __unused__ to make the `Context` the second argument. This |
| is done for uniformity with __karma_actions__). |
| |
| [heading Expression Semantics] |
| |
| Semantics of an expression is defined only where it differs from, or is |
| not defined in __generator_concept__. |
| |
| [table |
| [[Expression] [Semantics]] |
| [[`fg`] [The __boost_phoenix__ function object `fg` will be |
| invoked at generate time. It is expected to return a |
| generator instance. This generator is then invoked |
| in order to generate the output. This generator will |
| succeed as long as the invoked generated succeeds as |
| well (unless the underlying output stream reports |
| an error).]] |
| [[`lazy(fg)`] [The function or function object will be invoked at |
| generate time. It is expected to return a generator |
| instance (note this version of `lazy` does not |
| require `fg` to be a __boost_phoenix__ function |
| object). This generator is then invoked in order to |
| generate the output. This generator will succeed as |
| long as the invoked generated succeeds as well (except |
| if the underlying output stream reports an error).]] |
| ] |
| |
| [heading Attributes] |
| |
| [table |
| [[Expression] [Attribute]] |
| [[`fg`] [The attribute type `G` as exposed by the generator `g` |
| returned from `fg`.]] |
| [[`lazy(fg)`] [The attribute type `G` as exposed by the generator `g` |
| returned from `fg`.]] |
| ] |
| |
| [heading Complexity] |
| |
| The complexity of the `lazy` component is determined by the complexity of the |
| generator returned from `fg`. |
| |
| [heading Example] |
| |
| [note The test harness for the example(s) below is presented in the |
| __karma_basics_examples__ section.] |
| |
| Some includes: |
| |
| [reference_karma_includes] |
| |
| Some using declarations: |
| |
| [reference_karma_using_declarations_lazy] |
| |
| Basic usage of the `lazy` generator: |
| |
| [reference_karma_lazy] |
| |
| [endsect] |
| |
| [endsect] |
