| Home | Libraries | People | FAQ | More

##### Lazy Generator (`lazy`)

###### 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.

###### Header

    // forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp>
    #include <boost/spirit/include/karma_lazy.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::lazy // alias: boost::spirit::karma::lazy`

###### Model of

> `Generator`

Notation

`fg`

  A function or function object that evaluates to a generator object (an object exposing the `Generator`). 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 Context type (The first argument is `unused` to make the `Context` the second argument. This is done for uniformity with Semantic Actions).

###### Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in `Generator`.

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).

###### Attributes

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`.

###### Complexity

The complexity of the `lazy` component is determined by the complexity of the generator returned from `fg`.

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

    #include <boost/spirit/include/karma.hpp>
    #include <boost/spirit/include/support_utree.hpp>
    #include <boost/phoenix/core.hpp>
    #include <boost/phoenix/operator.hpp>
    #include <boost/fusion/include/std_pair.hpp>
    #include <boost/proto/deep_copy.hpp>
    #include <iostream>
    #include <string>

Some using declarations:

    namespace karma = boost::spirit::karma;
    using boost::spirit::karma::_1;
    using boost::spirit::ascii::string;
    using boost::phoenix::val;

Basic usage of the `lazy` generator:

    test_generator_attr("abc", karma::lazy(val(string)), "abc");
    test_generator("abc", karma::lazy(val(string))[_1 = "abc"]);