[/============================================================================== Copyright (C) 2001-2011 Hartmut Kaiser Copyright (C) 2001-2011 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 Auxiliary Generators] 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 #include Also, see __include_structure__. [/////////////////////////////////////////////////////////////////////////////] [section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)] [heading Description] The `attr_cast()` 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 #include Also, see __include_structure__. [heading Namespace] [table [[Name]] [[`boost::spirit::attr_cast // alias: boost::spirit::karma::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 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(g) attr_cast(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(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(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(g)`] [`g: A --> attr_cast(g): Exposed`]] [[`attr_cast(g)`] [`g: A --> attr_cast(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 Generator (`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 #include 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 Generator (`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 #include 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 Generator (`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 #include 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 __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 __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]