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

This module includes the description of the different variants of the `stream` 
generator. It can be used to utilize existing streaming operators 
(`operator<<(std::ostream&, ...)`) for output generation.

[heading Header]

    // forwards to <boost/spirit/home/karma/stream.hpp>
    #include <boost/spirit/include/karma_stream.hpp>

Also, see __include_structure__.

[section:stream Stream (`stream`, `wstream`, etc.)]

[heading Description]

The `stream_generator` is a primitive which allows to use pre-existing standard
streaming operators for output generation integrated with __karma__. It 
provides a wrapper generator dispatching the value to output to the stream 
operator of the corresponding type. Any value `a` to be formatted using the
`stream_generator` will result in invoking the standard streaming operator
for its type `A`, for instance:

    std::ostream& operator<< (std::ostream&, A const&);

[heading Header]

    // forwards to <boost/spirit/home/karma/stream.hpp>
    #include <boost/spirit/include/karma_stream.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::stream  // alias: boost::spirit::karma::stream`]]
    [[`boost::spirit::wstream // alias: boost::spirit::karma::wstream`]]
]

[heading Synopsis]

    template <typename Char>
    struct stream_generator;

[heading Template parameters]

[table
    [[Parameter]    [Description]                       [Default]]
    [[`Char`]   [The character type to use to generate 
                 the output. This type will be used while 
                 assigning the generated characters to the 
                 underlying output iterator.]           [`char`]]
]

[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`s`]      [A variable instance of any type with a defined matching 
                 streaming `operator<<()` or a __karma_lazy_argument__ that 
                 evaluates to any type with a defined matching streaming 
                 `operator<<()`.]]
]

[heading Expression Semantics]

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

[table
    [[Expression]           [Description]]
    [[`stream`]             [Call the streaming `operator<<()` for the type
                             of the mandatory attribute. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `char`.]]
    [[`stream(s)`]          [Call the streaming `operator<<()` for the type
                             of the immediate value `s`. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `char`.]]
    [[`wstream`]            [Call the streaming `operator<<()` for the type
                             of the mandatory attribute. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `wchar_t`.]]
    [[`wstream(s)`]         [Call the streaming `operator<<()` for the type
                             of the immediate value `s`. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `wchar_t`.]]
]

All generators listed in the table above are predefined specializations of the 
`stream_generator<Char>` basic stream generator type described below. It is 
possible to directly use this type to create stream generators using an 
arbitrary underlying character type.

[table
    [[Expression]       [Semantics]]
    [
[``stream_generator<
    Char
>()``]                      [Call the streaming `operator<<()` for the type
                             of the mandatory attribute. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `Char`]]
    [
[``stream_generator<
    Char
>()(s)``]                   [Call the streaming `operator<<()` for the type
                             of the immediate value `s`. The output emitted 
                             by this operator will be the result of the 
                             `stream` generator. This generator never fails 
                             (unless the underlying output stream reports an 
                             error). The character type of the I/O ostream
                             is assumed to be `Char`.]]
]

[heading Additional Requirements]

All of the stream generators listed above require the type of the value to 
generate output for (either the immediate value or the associated attribute) to 
implement a streaming operator conforming to the usual I/O streams conventions
(where `attribute_type` is the type of the value to generate output for):

    template <typename Ostream>
    Ostream& operator<< (Ostream& os, attribute_type const& attr)
    {
        // type specific output generation
        return os;
    }

This operator will be called by the stream generators to gather the output for
the attribute of type `attribute_type`. All data streamed into the given 
`Ostream` will end up being generated by the corresponding stream generator 
instance.

[note   If the `stream` generator is invoked inside a [karma_format `format`] 
        (or [karma_format `format_delimited`]) stream manipulator the `Ostream` 
        passed to the `operator<<()` will have registered (imbued) the same 
        standard locale instance as the stream the [karma_format `format`] (or 
        [karma_format `format_delimited`]) manipulator has been used with. 
        This ensures all facets registered (imbued) with the original I/O 
        stream object are used during output generation.
]

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`stream`]             [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
    [[`stream(s)`]          [__unused__]]
    [[`wstream`]            [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
    [[`wstream(s)`]         [__unused__]]
    [[`stream_generator<Char>()`]    [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
    [[`stream_generator<Char>()(s)`] [__unused__]]
]

[important The attribute type `hold_any` exposed by some of the stream 
           generators is semantically and syntactically equivalent to 
           the type implemented by __boost_any__. It has been added to /Spirit/ 
           as it has better a performance and a smaller footprint if compared to 
           __boost_any__.
]

[note  In addition to their usual attribute of type `Attrib` all listed generators 
       accept an instance of a `boost::optional<Attrib>` as well. If the 
       `boost::optional<>` is initialized (holds a value) the generators behave 
       as if their attribute was an instance of `Attrib` and emit the value stored
       in the `boost::optional<>`. Otherwise the generators will fail.]

[heading Complexity]

[:O(N), where N is the number of characters emitted by the stream generator]

[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_stream]

And a class definition used in the examples:

[reference_karma_complex]
[reference_karma_stream_complex]

Basic usage of `stream` generators:

[reference_karma_stream]

[endsect]

[endsect]