1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
|
[/==============================================================================
Copyright (C) 2001-2011 Joel de Guzman
Copyright (C) 2001-2011 Hartmut Kaiser
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:generate_api Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:iterator_api Iterator Based Generator API]
[heading Description]
The library provides a couple of free functions to make generating a snap.
These generator functions have two forms. The first form, `generate`,
concatenates the output generated by the involved components without inserting
any output in between. The second `generate_delimited` intersperses the output
generated by the involved components using the given delimiter generator.
Both versions can take in attributes by (constant) reference that hold the
attribute values to output.
[heading Header]
// forwards to <boost/spirit/home/karma/generate.hpp>
#include <boost/spirit/include/karma_generate.hpp>
For variadic attributes:
// forwards to <boost/spirit/home/karma/generate_attr.hpp>
#include <boost/spirit/include/karma_generate_attr.hpp>
The variadic attributes version of the API allows one or more
attributes to be passed into the `generate` functions. The functions taking two
or more attributes are usable when the generator expression is a
__karma_sequence__ only. In this case each of the
attributes passed have to match the corresponding part of the sequence.
For the API functions deducing the correct (matching) generator type from the
supplied attribute type:
// forwards to <boost/spirit/home/karma/detail/generate_auto.hpp>
#include <boost/spirit/include/karma_generate_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::generate` ]]
[[`boost::spirit::karma::generate_delimited` ]]
[[`boost::spirit::karma::delimit_flag::predelimit` ]]
[[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename OutputIterator, typename Expr>
inline bool
generate(
OutputIterator& sink
, Expr const& expr);
template <typename OutputIterator, typename Expr
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate(
OutputIterator& sink
, Expr const& expr
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename OutputIterator, typename Expr, typename Delimiter>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename OutputIterator, typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename OutputIterator, typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline bool
generate_delimited(
OutputIterator& sink
, Expr const& expr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
}}}
[note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the
placeholder `_val` can be used in semantic actions attached to top level
generator components. In this case `_val` refers to the supplied attribute
as a whole. For API functions taking more than one attribute argument
`_val` will refer to a Fusion vector or references to the attributes.]
__karma__ generator API functions based on the automatic creation of the
matching generator type:
namespace boost { namespace spirit { namespace karma
{
template <typename OutputIterator, typename Attr, typename Delimiter>
inline bool
generate_delimited(
OutputIterator& sink
, Attr const& attr
, Delimiter const& delimiter
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename OutputIterator, typename Attr>
inline bool
generate(
OutputIterator& sink
, Attr const& attr);
}}}
All functions above return `true` if none of the involved generator components
failed, and `false` otherwise. If during the process of the output generation
the underlying output stream reports an error, the return value will be `false`
as well.
The maximum number of supported arguments is limited by the preprocessor
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
[note The variadic functions with two or more attributes internally combine
(constant) references to all passed attributes into a `fusion::vector`
and forward this as a combined attribute to the corresponding function
taking one attribute.]
The `generate_delimited` functions not taking an explicit `delimit_flag` as one
of their arguments don't invoke the passed delimiter before starting to generate
output from the generator expression. This can be enabled by using the other
version of that function while passing `delimit_flag::predelimit` to the
corresponding argument.
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`OutputIterator`] [__outputiter__ receiving the generated output.]]
[[`Expr`] [An expression that can be converted to a Karma generator.]]
[[`Delimiter`] [Generator used to delimit the output of the expression components.]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
[[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]
[endsect] [/ Iterator Based Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:stream_api Stream Based Generator API]
[heading Description]
The library provides a couple of Standard IO __iomanip__ allowing to integrate
__karma__ output generation facilities with Standard output streams.
These generator manipulators have two forms. The first form, `format`,
concatenates the output generated by the involved components without inserting
any output in between. The second, `format_delimited`, intersperses the output
generated by the involved components using the given delimiter generator.
Both versions can take in attributes by (constant) reference that hold the
attribute values to output.
[heading Header]
// forwards to <boost/spirit/home/karma/stream/format_manip.hpp>
#include <boost/spirit/include/karma_format.hpp>
For variadic attributes:
// forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp>
#include <boost/spirit/include/karma_format_attr.hpp>
The variadic attributes version of the API allows one or more
attributes to be passed into the `format` manipulators. The manipulators taking
two or more attributes are usable when the generator expression is a
__karma_sequence__ only. In this case each of the attributes passed have to
match the corresponding part of the sequence.
For the API functions deducing the correct (matching) generator type from the
supplied attribute type:
// forwards to <boost/spirit/home/karma/format_auto.hpp>
#include <boost/spirit/include/karma_format_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::format` ]]
[[`boost::spirit::karma::format_delimited` ]]
[[`boost::spirit::karma::delimit_flag::predelimit` ]]
[[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename Expr>
inline <unspecified>
format(
Expr const& xpr);
template <typename Expr
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format(
Expr const& xpr
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename Expr, typename Delimiter>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
template <typename Expr, typename Delimiter
, typename Attr1, typename Attr2, ..., typename AttrN>
inline <unspecified>
format_delimited(
Expr const& expr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
, Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
}}}
__karma__ generator API functions based on the automatic creation of the
matching generator type:
namespace boost { namespace spirit { namespace karma
{
template <typename Attr, typename Delimiter>
inline <unspecified>
format_delimited(
Attr const& attr
, Delimiter const& d
, BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
template <typename Attr>
inline <unspecified>
format(
Attr const& xpr);
}}}
All functions above return a standard IO stream manipulator instance (see
__iomanip__), which when streamed to an output stream will result in generating
the output as emitted by the embedded __karma__ generator expression. Any error
occurring during the invocation of the __karma__ generators will be reflected
in the streams status flag (`std::ios_base::failbit` will be set).
The maximum number of supported arguments is limited by the preprocessor
constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
[note The variadic manipulators with two or more attributes internally combine
(constant) references to all passed attributes into a `fusion::vector`
and forward this as a combined attribute to the corresponding manipulator
taking one attribute.]
The `format_delimited` manipulators not taking an explicit `delimit_flag` as one
of their arguments don't invoke the passed delimiter before starting to generate
output from the generator expression. This can be enabled by using the other
version of that manipulator while passing `delimit_flag::predelimit` to the
corresponding argument.
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`Expr`] [An expression that can be converted to a Karma generator.]]
[[`Delimiter`] [Generator used to delimit the output of the expression components.]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
[[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
]
[endsect] [/ Stream Based Generator API]
[//////////////////////////////////////////////////////////////////////////////]
[section:create_generator API for Automatic Generator Creation]
[heading Description]
The library implements a special API returning a generator instance for a
supplied attribute type. This function finds the best matching generator type
for the attribute based on a set of simple matching rules (as outlined in the
table below) applied recursively to the attribute type. The returned generator
can be utilized to emit output for the provided attribute.
[heading Header]
// forwards to <boost/spirit/home/karma/auto.hpp>
#include <boost/spirit/include/karma_auto.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::karma::create_generator`]]
[[`boost::spirit::traits::create_generator_exists`]]
]
[heading Synopsis]
namespace boost { namespace spirit { namespace karma
{
template <typename Attr>
inline <unspecified>
create_generator();
}}}
The returned instance can be directly passed as the generator (or the
delimiting generator) to any of the __karma__ API functions. Additionally it
can be assigned to a rule as the rules right hand side expression. This
function will return a valid generator type only if the meta function
`traits::create_generator_exists` returns `mpl::true_`. Otherwise it will fail
compiling.
namespace boost { namespace spirit { namespace traits
{
template <typename Attr>
struct create_generator_exists;
}}}
The meta function evaluates to `mpl::true_` if `create_generator` would return
a valid generator for the given type `Attr`.
The following table outlines the mapping rules from the attribute type to the
generator type. These rules are applied recursively to create the generator
type which can be used to generate output from the given attribute type.
[table
[[Attribute type] [Generator type]]
[[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`unsigned short`, `unsigned int`, `unsigned long`]
[`ushort_`, `uint_`, `ulong_`]]
[[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
[[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
[[`long long`, `unsigned long long`]
[`long_long`, `ulong_long`]]
[[`bool`] [`bool_`]]
[[Any string (`char const*`, `std::string`, etc.)]
[`string`]]
[[Any (STL) container] [Kleene Star (unary `'*'`)]]
[[Any Fusion sequence] [Sequence operator (`'<<'`)]]
[[`boost::optional<>`] [Optional operator (unary `'-'`)]]
[[`boost::variant<>`] [Alternative operator (`'|'`)]]
]
[important The mapping for the generators `long_long` and `ulong_long` are only
available on platforms where the preprocessor constant
`BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native
support for `long long` and `unsigned long long` (64 bit) signed and
unsigned integer types).]
[heading Template parameters]
[table
[[Parameter] [Description]]
[[`Attr`] [An attribute type utilized to create the corresponding
generator type from.]]
]
[endsect] [/ API for Automatic Generator Creation]
[endsect]
|
