1[/==============================================================================
2    Copyright (C) 2001-2011 Hartmut Kaiser
3    Copyright (C) 2001-2011 Joel de Guzman
4
5    Distributed under the Boost Software License, Version 1.0. (See accompanying
6    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7===============================================================================/]
8
9[section:stream Stream Generators]
10
11This module includes the description of the different variants of the `stream`
12generator. It can be used to utilize existing streaming operators
13(`operator<<(std::ostream&, ...)`) for output generation.
14
15[heading Header]
16
17    // forwards to <boost/spirit/home/karma/stream.hpp>
18    #include <boost/spirit/include/karma_stream.hpp>
19
20Also, see __include_structure__.
21
22[section:stream Stream Generators (`stream`, `wstream`, etc.)]
23
24[heading Description]
25
26The `stream_generator` is a primitive which allows to use pre-existing standard
27streaming operators for output generation integrated with __karma__. It
28provides a wrapper generator dispatching the value to output to the stream
29operator of the corresponding type. Any value `a` to be formatted using the
30`stream_generator` will result in invoking the standard streaming operator
31for its type `A`, for instance:
32
33    std::ostream& operator<< (std::ostream&, A const&);
34
35[heading Header]
36
37    // forwards to <boost/spirit/home/karma/stream.hpp>
38    #include <boost/spirit/include/karma_stream.hpp>
39
40Also, see __include_structure__.
41
42[heading Namespace]
43
44[table
45    [[Name]]
46    [[`boost::spirit::stream  // alias: boost::spirit::karma::stream`]]
47    [[`boost::spirit::wstream // alias: boost::spirit::karma::wstream`]]
48]
49
50[heading Synopsis]
51
52    template <typename Char>
53    struct stream_generator;
54
55[heading Template parameters]
56
57[table
58    [[Parameter]    [Description]                       [Default]]
59    [[`Char`]   [The character type to use to generate
60                 the output. This type will be used while
61                 assigning the generated characters to the
62                 underlying output iterator.]           [`char`]]
63]
64
65[heading Model of]
66
67[:__primitive_generator_concept__]
68
69[variablelist Notation
70    [[`s`]      [A variable instance of any type with a defined matching
71                 streaming `operator<<()` or a __karma_lazy_argument__ that
72                 evaluates to any type with a defined matching streaming
73                 `operator<<()`.]]
74]
75
76[heading Expression Semantics]
77
78Semantics of an expression is defined only where it differs from, or is
79not defined in __primitive_generator_concept__.
80
81[table
82    [[Expression]           [Description]]
83    [[`stream`]             [Call the streaming `operator<<()` for the type
84                             of the mandatory attribute. The output emitted
85                             by this operator will be the result of the
86                             `stream` generator. This generator never fails
87                             (unless the underlying output stream reports an
88                             error). The character type of the I/O ostream
89                             is assumed to be `char`.]]
90    [[`stream(s)`]          [Call the streaming `operator<<()` for the type
91                             of the immediate value `s`. The output emitted
92                             by this operator will be the result of the
93                             `stream` generator. This generator never fails
94                             (unless the underlying output stream reports an
95                             error). The character type of the I/O ostream
96                             is assumed to be `char`.]]
97    [[`wstream`]            [Call the streaming `operator<<()` for the type
98                             of the mandatory attribute. The output emitted
99                             by this operator will be the result of the
100                             `stream` generator. This generator never fails
101                             (unless the underlying output stream reports an
102                             error). The character type of the I/O ostream
103                             is assumed to be `wchar_t`.]]
104    [[`wstream(s)`]         [Call the streaming `operator<<()` for the type
105                             of the immediate value `s`. The output emitted
106                             by this operator will be the result of the
107                             `stream` generator. This generator never fails
108                             (unless the underlying output stream reports an
109                             error). The character type of the I/O ostream
110                             is assumed to be `wchar_t`.]]
111]
112
113All generators listed in the table above are predefined specializations of the
114`stream_generator<Char>` basic stream generator type described below. It is
115possible to directly use this type to create stream generators using an
116arbitrary underlying character type.
117
118[table
119    [[Expression]       [Semantics]]
120    [
121[``stream_generator<
122    Char
123>()``]                      [Call the streaming `operator<<()` for the type
124                             of the mandatory attribute. The output emitted
125                             by this operator will be the result of the
126                             `stream` generator. This generator never fails
127                             (unless the underlying output stream reports an
128                             error). The character type of the I/O ostream
129                             is assumed to be `Char`]]
130    [
131[``stream_generator<
132    Char
133>()(s)``]                   [Call the streaming `operator<<()` for the type
134                             of the immediate value `s`. The output emitted
135                             by this operator will be the result of the
136                             `stream` generator. This generator never fails
137                             (unless the underlying output stream reports an
138                             error). The character type of the I/O ostream
139                             is assumed to be `Char`.]]
140]
141
142[heading Additional Requirements]
143
144All of the stream generators listed above require the type of the value to
145generate output for (either the immediate value or the associated attribute) to
146implement a streaming operator conforming to the usual I/O streams conventions
147(where `attribute_type` is the type of the value to generate output for):
148
149    template <typename Ostream>
150    Ostream& operator<< (Ostream& os, attribute_type const& attr)
151    {
152        // type specific output generation
153        return os;
154    }
155
156This operator will be called by the stream generators to gather the output for
157the attribute of type `attribute_type`. All data streamed into the given
158`Ostream` will end up being generated by the corresponding stream generator
159instance.
160
161[note   If the `stream` generator is invoked inside a [karma_format `format`]
162        (or [karma_format `format_delimited`]) stream manipulator the `Ostream`
163        passed to the `operator<<()` will have registered (imbued) the same
164        standard locale instance as the stream the [karma_format `format`] (or
165        [karma_format `format_delimited`]) manipulator has been used with.
166        This ensures all facets registered (imbued) with the original I/O
167        stream object are used during output generation.
168]
169
170[heading Attributes]
171
172[table
173    [[Expression]           [Attribute]]
174    [[`stream`]             [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
175    [[`stream(s)`]          [__unused__]]
176    [[`wstream`]            [`whold_any`, attribute is mandatory (otherwise compilation will fail)]]
177    [[`wstream(s)`]         [__unused__]]
178    [[`stream_generator<Char>()`]    [`basic_hold_any<Char>`, attribute is mandatory (otherwise compilation will fail)]]
179    [[`stream_generator<Char>()(s)`] [__unused__]]
180]
181
182[important The attribute type `hold_any` exposed by some of the stream
183           generators is semantically and syntactically equivalent to
184           the type implemented by __boost_any__. It has been added to /Spirit/
185           as it has better a performance and a smaller footprint if compared to
186           __boost_any__.
187]
188
189[note  In addition to their usual attribute of type `Attrib` all listed generators
190       accept an instance of a `boost::optional<Attrib>` as well. If the
191       `boost::optional<>` is initialized (holds a value) the generators behave
192       as if their attribute was an instance of `Attrib` and emit the value stored
193       in the `boost::optional<>`. Otherwise the generators will fail.]
194
195[heading Complexity]
196
197[:O(N), where N is the number of characters emitted by the stream generator]
198
199[heading Example]
200
201[note The test harness for the example(s) below is presented in the
202      __karma_basics_examples__ section.]
203
204Some includes:
205
206[reference_karma_includes]
207
208Some using declarations:
209
210[reference_karma_using_declarations_stream]
211
212And a class definition used in the examples:
213
214[reference_karma_complex]
215[reference_karma_stream_complex]
216
217Basic usage of `stream` generators:
218
219[reference_karma_stream]
220
221[endsect]
222
223[endsect]
224