1 [/==============================================================================
2 Copyright (C) 2001-2011 Joel de Guzman
3 Copyright (C) 2001-2011 Hartmut Kaiser
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 [section:generate_api Generator API]
10 [//////////////////////////////////////////////////////////////////////////////]
11 [section:iterator_api Iterator Based Generator API]
15 The library provides a couple of free functions to make generating a snap.
16 These generator functions have two forms. The first form, `generate`,
17 concatenates the output generated by the involved components without inserting
18 any output in between. The second `generate_delimited` intersperses the output
19 generated by the involved components using the given delimiter generator.
20 Both versions can take in attributes by (constant) reference that hold the
21 attribute values to output.
25 // forwards to <boost/spirit/home/karma/generate.hpp>
26 #include <boost/spirit/include/karma_generate.hpp>
28 For variadic attributes:
30 // forwards to <boost/spirit/home/karma/generate_attr.hpp>
31 #include <boost/spirit/include/karma_generate_attr.hpp>
33 The variadic attributes version of the API allows one or more
34 attributes to be passed into the `generate` functions. The functions taking two
35 or more attributes are usable when the generator expression is a
36 __karma_sequence__ only. In this case each of the
37 attributes passed have to match the corresponding part of the sequence.
39 For the API functions deducing the correct (matching) generator type from the
40 supplied attribute type:
42 // forwards to <boost/spirit/home/karma/detail/generate_auto.hpp>
43 #include <boost/spirit/include/karma_generate_auto.hpp>
45 Also, see __include_structure__.
51 [[`boost::spirit::karma::generate` ]]
52 [[`boost::spirit::karma::generate_delimited` ]]
53 [[`boost::spirit::karma::delimit_flag::predelimit` ]]
54 [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
59 namespace boost { namespace spirit { namespace karma
61 template <typename OutputIterator, typename Expr>
67 template <typename OutputIterator, typename Expr
68 , typename Attr1, typename Attr2, ..., typename AttrN>
73 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
75 template <typename OutputIterator, typename Expr, typename Delimiter>
80 , Delimiter const& delimiter
81 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
83 template <typename OutputIterator, typename Expr, typename Delimiter
84 , typename Attr1, typename Attr2, ..., typename AttrN>
89 , Delimiter const& delimiter
90 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
92 template <typename OutputIterator, typename Expr, typename Delimiter
93 , typename Attr1, typename Attr2, ..., typename AttrN>
98 , Delimiter const& delimiter
99 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
100 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
103 [note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the
104 placeholder `_val` can be used in semantic actions attached to top level
105 generator components. In this case `_val` refers to the supplied attribute
106 as a whole. For API functions taking more than one attribute argument
107 `_val` will refer to a Fusion vector or references to the attributes.]
109 __karma__ generator API functions based on the automatic creation of the
110 matching generator type:
112 namespace boost { namespace spirit { namespace karma
114 template <typename OutputIterator, typename Attr, typename Delimiter>
119 , Delimiter const& delimiter
120 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
122 template <typename OutputIterator, typename Attr>
129 All functions above return `true` if none of the involved generator components
130 failed, and `false` otherwise. If during the process of the output generation
131 the underlying output stream reports an error, the return value will be `false`
134 The maximum number of supported arguments is limited by the preprocessor
135 constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
136 by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
138 [note The variadic functions with two or more attributes internally combine
139 (constant) references to all passed attributes into a `fusion::vector`
140 and forward this as a combined attribute to the corresponding function
141 taking one attribute.]
143 The `generate_delimited` functions not taking an explicit `delimit_flag` as one
144 of their arguments don't invoke the passed delimiter before starting to generate
145 output from the generator expression. This can be enabled by using the other
146 version of that function while passing `delimit_flag::predelimit` to the
147 corresponding argument.
149 [heading Template parameters]
152 [[Parameter] [Description]]
153 [[`OutputIterator`] [__outputiter__ receiving the generated output.]]
154 [[`Expr`] [An expression that can be converted to a Karma generator.]]
155 [[`Delimiter`] [Generator used to delimit the output of the expression components.]]
156 [[`Attr`] [An attribute type utilized to create the corresponding
157 generator type from.]]
158 [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
161 [endsect] [/ Iterator Based Generator API]
163 [//////////////////////////////////////////////////////////////////////////////]
164 [section:stream_api Stream Based Generator API]
166 [heading Description]
168 The library provides a couple of Standard IO __iomanip__ allowing to integrate
169 __karma__ output generation facilities with Standard output streams.
170 These generator manipulators have two forms. The first form, `format`,
171 concatenates the output generated by the involved components without inserting
172 any output in between. The second, `format_delimited`, intersperses the output
173 generated by the involved components using the given delimiter generator.
174 Both versions can take in attributes by (constant) reference that hold the
175 attribute values to output.
179 // forwards to <boost/spirit/home/karma/stream/format_manip.hpp>
180 #include <boost/spirit/include/karma_format.hpp>
182 For variadic attributes:
184 // forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp>
185 #include <boost/spirit/include/karma_format_attr.hpp>
187 The variadic attributes version of the API allows one or more
188 attributes to be passed into the `format` manipulators. The manipulators taking
189 two or more attributes are usable when the generator expression is a
190 __karma_sequence__ only. In this case each of the attributes passed have to
191 match the corresponding part of the sequence.
193 For the API functions deducing the correct (matching) generator type from the
194 supplied attribute type:
196 // forwards to <boost/spirit/home/karma/format_auto.hpp>
197 #include <boost/spirit/include/karma_format_auto.hpp>
199 Also, see __include_structure__.
205 [[`boost::spirit::karma::format` ]]
206 [[`boost::spirit::karma::format_delimited` ]]
207 [[`boost::spirit::karma::delimit_flag::predelimit` ]]
208 [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
213 namespace boost { namespace spirit { namespace karma
215 template <typename Expr>
220 template <typename Expr
221 , typename Attr1, typename Attr2, ..., typename AttrN>
225 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
227 template <typename Expr, typename Delimiter>
232 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
234 template <typename Expr, typename Delimiter
235 , typename Attr1, typename Attr2, ..., typename AttrN>
240 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
242 template <typename Expr, typename Delimiter
243 , typename Attr1, typename Attr2, ..., typename AttrN>
248 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
249 , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
252 __karma__ generator API functions based on the automatic creation of the
253 matching generator type:
255 namespace boost { namespace spirit { namespace karma
257 template <typename Attr, typename Delimiter>
262 , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
264 template <typename Attr>
270 All functions above return a standard IO stream manipulator instance (see
271 __iomanip__), which when streamed to an output stream will result in generating
272 the output as emitted by the embedded __karma__ generator expression. Any error
273 occurring during the invocation of the __karma__ generators will be reflected
274 in the streams status flag (`std::ios_base::failbit` will be set).
276 The maximum number of supported arguments is limited by the preprocessor
277 constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
278 by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
280 [note The variadic manipulators with two or more attributes internally combine
281 (constant) references to all passed attributes into a `fusion::vector`
282 and forward this as a combined attribute to the corresponding manipulator
283 taking one attribute.]
285 The `format_delimited` manipulators not taking an explicit `delimit_flag` as one
286 of their arguments don't invoke the passed delimiter before starting to generate
287 output from the generator expression. This can be enabled by using the other
288 version of that manipulator while passing `delimit_flag::predelimit` to the
289 corresponding argument.
291 [heading Template parameters]
294 [[Parameter] [Description]]
295 [[`Expr`] [An expression that can be converted to a Karma generator.]]
296 [[`Delimiter`] [Generator used to delimit the output of the expression components.]]
297 [[`Attr`] [An attribute type utilized to create the corresponding
298 generator type from.]]
299 [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
302 [endsect] [/ Stream Based Generator API]
304 [//////////////////////////////////////////////////////////////////////////////]
305 [section:create_generator API for Automatic Generator Creation]
307 [heading Description]
309 The library implements a special API returning a generator instance for a
310 supplied attribute type. This function finds the best matching generator type
311 for the attribute based on a set of simple matching rules (as outlined in the
312 table below) applied recursively to the attribute type. The returned generator
313 can be utilized to emit output for the provided attribute.
317 // forwards to <boost/spirit/home/karma/auto.hpp>
318 #include <boost/spirit/include/karma_auto.hpp>
320 Also, see __include_structure__.
326 [[`boost::spirit::karma::create_generator`]]
327 [[`boost::spirit::traits::create_generator_exists`]]
332 namespace boost { namespace spirit { namespace karma
334 template <typename Attr>
339 The returned instance can be directly passed as the generator (or the
340 delimiting generator) to any of the __karma__ API functions. Additionally it
341 can be assigned to a rule as the rules right hand side expression. This
342 function will return a valid generator type only if the meta function
343 `traits::create_generator_exists` returns `mpl::true_`. Otherwise it will fail
346 namespace boost { namespace spirit { namespace traits
348 template <typename Attr>
349 struct create_generator_exists;
352 The meta function evaluates to `mpl::true_` if `create_generator` would return
353 a valid generator for the given type `Attr`.
355 The following table outlines the mapping rules from the attribute type to the
356 generator type. These rules are applied recursively to create the generator
357 type which can be used to generate output from the given attribute type.
360 [[Attribute type] [Generator type]]
361 [[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]]
362 [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
363 [[`unsigned short`, `unsigned int`, `unsigned long`]
364 [`ushort_`, `uint_`, `ulong_`]]
365 [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
366 [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
367 [[`long long`, `unsigned long long`]
368 [`long_long`, `ulong_long`]]
370 [[Any string (`char const*`, `std::string`, etc.)]
372 [[Any (STL) container] [Kleene Star (unary `'*'`)]]
373 [[Any Fusion sequence] [Sequence operator (`'<<'`)]]
374 [[`boost::optional<>`] [Optional operator (unary `'-'`)]]
375 [[`boost::variant<>`] [Alternative operator (`'|'`)]]
378 [important The mapping for the generators `long_long` and `ulong_long` are only
379 available on platforms where the preprocessor constant
380 `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native
381 support for `long long` and `unsigned long long` (64 bit) signed and
382 unsigned integer types).]
384 [heading Template parameters]
387 [[Parameter] [Description]]
388 [[`Attr`] [An attribute type utilized to create the corresponding
389 generator type from.]]
392 [endsect] [/ API for Automatic Generator Creation]