]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================== |
2 | Copyright (C) 2001-2011 Joel de Guzman | |
3 | Copyright (C) 2001-2011 Hartmut Kaiser | |
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 | [section:generate_api Generator API] | |
9 | ||
10 | [//////////////////////////////////////////////////////////////////////////////] | |
11 | [section:iterator_api Iterator Based Generator API] | |
12 | ||
13 | [heading Description] | |
14 | ||
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. | |
22 | ||
23 | [heading Header] | |
24 | ||
25 | // forwards to <boost/spirit/home/karma/generate.hpp> | |
26 | #include <boost/spirit/include/karma_generate.hpp> | |
27 | ||
28 | For variadic attributes: | |
29 | ||
30 | // forwards to <boost/spirit/home/karma/generate_attr.hpp> | |
31 | #include <boost/spirit/include/karma_generate_attr.hpp> | |
32 | ||
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. | |
38 | ||
39 | For the API functions deducing the correct (matching) generator type from the | |
40 | supplied attribute type: | |
41 | ||
42 | // forwards to <boost/spirit/home/karma/detail/generate_auto.hpp> | |
43 | #include <boost/spirit/include/karma_generate_auto.hpp> | |
44 | ||
45 | Also, see __include_structure__. | |
46 | ||
47 | [heading Namespace] | |
48 | ||
49 | [table | |
50 | [[Name]] | |
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` ]] | |
55 | ] | |
56 | ||
57 | [heading Synopsis] | |
58 | ||
59 | namespace boost { namespace spirit { namespace karma | |
60 | { | |
61 | template <typename OutputIterator, typename Expr> | |
62 | inline bool | |
63 | generate( | |
64 | OutputIterator& sink | |
65 | , Expr const& expr); | |
66 | ||
67 | template <typename OutputIterator, typename Expr | |
68 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
69 | inline bool | |
70 | generate( | |
71 | OutputIterator& sink | |
72 | , Expr const& expr | |
73 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
74 | ||
75 | template <typename OutputIterator, typename Expr, typename Delimiter> | |
76 | inline bool | |
77 | generate_delimited( | |
78 | OutputIterator& sink | |
79 | , Expr const& expr | |
80 | , Delimiter const& delimiter | |
81 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); | |
82 | ||
83 | template <typename OutputIterator, typename Expr, typename Delimiter | |
84 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
85 | inline bool | |
86 | generate_delimited( | |
87 | OutputIterator& sink | |
88 | , Expr const& expr | |
89 | , Delimiter const& delimiter | |
90 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
91 | ||
92 | template <typename OutputIterator, typename Expr, typename Delimiter | |
93 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
94 | inline bool | |
95 | generate_delimited( | |
96 | OutputIterator& sink | |
97 | , Expr const& expr | |
98 | , Delimiter const& delimiter | |
99 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit | |
100 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
101 | }}} | |
102 | ||
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.] | |
108 | ||
109 | __karma__ generator API functions based on the automatic creation of the | |
110 | matching generator type: | |
111 | ||
112 | namespace boost { namespace spirit { namespace karma | |
113 | { | |
114 | template <typename OutputIterator, typename Attr, typename Delimiter> | |
115 | inline bool | |
116 | generate_delimited( | |
117 | OutputIterator& sink | |
118 | , Attr const& attr | |
119 | , Delimiter const& delimiter | |
120 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); | |
121 | ||
122 | template <typename OutputIterator, typename Attr> | |
123 | inline bool | |
124 | generate( | |
125 | OutputIterator& sink | |
126 | , Attr const& attr); | |
127 | }}} | |
128 | ||
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` | |
132 | as well. | |
133 | ||
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`). | |
137 | ||
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.] | |
142 | ||
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. | |
148 | ||
149 | [heading Template parameters] | |
150 | ||
151 | [table | |
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.]] | |
159 | ] | |
160 | ||
161 | [endsect] [/ Iterator Based Generator API] | |
162 | ||
163 | [//////////////////////////////////////////////////////////////////////////////] | |
164 | [section:stream_api Stream Based Generator API] | |
165 | ||
166 | [heading Description] | |
167 | ||
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. | |
176 | ||
177 | [heading Header] | |
178 | ||
179 | // forwards to <boost/spirit/home/karma/stream/format_manip.hpp> | |
180 | #include <boost/spirit/include/karma_format.hpp> | |
181 | ||
182 | For variadic attributes: | |
183 | ||
184 | // forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp> | |
185 | #include <boost/spirit/include/karma_format_attr.hpp> | |
186 | ||
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. | |
192 | ||
193 | For the API functions deducing the correct (matching) generator type from the | |
194 | supplied attribute type: | |
195 | ||
196 | // forwards to <boost/spirit/home/karma/format_auto.hpp> | |
197 | #include <boost/spirit/include/karma_format_auto.hpp> | |
198 | ||
199 | Also, see __include_structure__. | |
200 | ||
201 | [heading Namespace] | |
202 | ||
203 | [table | |
204 | [[Name]] | |
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` ]] | |
209 | ] | |
210 | ||
211 | [heading Synopsis] | |
212 | ||
213 | namespace boost { namespace spirit { namespace karma | |
214 | { | |
215 | template <typename Expr> | |
216 | inline <unspecified> | |
217 | format( | |
218 | Expr const& xpr); | |
219 | ||
220 | template <typename Expr | |
221 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
222 | inline <unspecified> | |
223 | format( | |
224 | Expr const& xpr | |
225 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
226 | ||
227 | template <typename Expr, typename Delimiter> | |
228 | inline <unspecified> | |
229 | format_delimited( | |
230 | Expr const& expr | |
231 | , Delimiter const& d | |
232 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); | |
233 | ||
234 | template <typename Expr, typename Delimiter | |
235 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
236 | inline <unspecified> | |
237 | format_delimited( | |
238 | Expr const& expr | |
239 | , Delimiter const& d | |
240 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
241 | ||
242 | template <typename Expr, typename Delimiter | |
243 | , typename Attr1, typename Attr2, ..., typename AttrN> | |
244 | inline <unspecified> | |
245 | format_delimited( | |
246 | Expr const& expr | |
247 | , Delimiter const& d | |
248 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit | |
249 | , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); | |
250 | }}} | |
251 | ||
252 | __karma__ generator API functions based on the automatic creation of the | |
253 | matching generator type: | |
254 | ||
255 | namespace boost { namespace spirit { namespace karma | |
256 | { | |
257 | template <typename Attr, typename Delimiter> | |
258 | inline <unspecified> | |
259 | format_delimited( | |
260 | Attr const& attr | |
261 | , Delimiter const& d | |
262 | , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); | |
263 | ||
264 | template <typename Attr> | |
265 | inline <unspecified> | |
266 | format( | |
267 | Attr const& xpr); | |
268 | }}} | |
269 | ||
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). | |
275 | ||
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`). | |
279 | ||
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.] | |
284 | ||
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. | |
290 | ||
291 | [heading Template parameters] | |
292 | ||
293 | [table | |
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.]] | |
300 | ] | |
301 | ||
302 | [endsect] [/ Stream Based Generator API] | |
303 | ||
304 | [//////////////////////////////////////////////////////////////////////////////] | |
305 | [section:create_generator API for Automatic Generator Creation] | |
306 | ||
307 | [heading Description] | |
308 | ||
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. | |
314 | ||
315 | [heading Header] | |
316 | ||
317 | // forwards to <boost/spirit/home/karma/auto.hpp> | |
318 | #include <boost/spirit/include/karma_auto.hpp> | |
319 | ||
320 | Also, see __include_structure__. | |
321 | ||
322 | [heading Namespace] | |
323 | ||
324 | [table | |
325 | [[Name]] | |
326 | [[`boost::spirit::karma::create_generator`]] | |
327 | [[`boost::spirit::traits::create_generator_exists`]] | |
328 | ] | |
329 | ||
330 | [heading Synopsis] | |
331 | ||
332 | namespace boost { namespace spirit { namespace karma | |
333 | { | |
334 | template <typename Attr> | |
335 | inline <unspecified> | |
336 | create_generator(); | |
337 | }}} | |
338 | ||
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 | |
344 | compiling. | |
345 | ||
346 | namespace boost { namespace spirit { namespace traits | |
347 | { | |
348 | template <typename Attr> | |
349 | struct create_generator_exists; | |
350 | }}} | |
351 | ||
352 | The meta function evaluates to `mpl::true_` if `create_generator` would return | |
353 | a valid generator for the given type `Attr`. | |
354 | ||
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. | |
358 | ||
359 | [table | |
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`]] | |
369 | [[`bool`] [`bool_`]] | |
370 | [[Any string (`char const*`, `std::string`, etc.)] | |
371 | [`string`]] | |
372 | [[Any (STL) container] [Kleene Star (unary `'*'`)]] | |
373 | [[Any Fusion sequence] [Sequence operator (`'<<'`)]] | |
374 | [[`boost::optional<>`] [Optional operator (unary `'-'`)]] | |
375 | [[`boost::variant<>`] [Alternative operator (`'|'`)]] | |
376 | ] | |
377 | ||
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).] | |
383 | ||
384 | [heading Template parameters] | |
385 | ||
386 | [table | |
387 | [[Parameter] [Description]] | |
388 | [[`Attr`] [An attribute type utilized to create the corresponding | |
389 | generator type from.]] | |
390 | ] | |
391 | ||
392 | [endsect] [/ API for Automatic Generator Creation] | |
393 | ||
394 | [endsect] |