]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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:directive Generator Directives] | |
10 | ||
11 | This module includes different generator directives. It includes alignment | |
12 | directives (`left_align[]`, `center[]`, and `right_align[]`), repetition | |
13 | (`repeat[]`), directives controlling automatic delimiting (`verbatim[]`, | |
14 | `no_delimit[]`, and `delimit[]`), controlling case sensitivity (`upper[]` and | |
15 | `lower[]`), field width (`maxwidth[]`), buffering (`buffer[]`), splitting into | |
16 | columns (`columns[]`) and attribute handling (`duplicate[]`, `omit[]`, and | |
17 | `skip[]`). | |
18 | ||
19 | [heading Module Header] | |
20 | ||
21 | // forwards to <boost/spirit/home/karma/directive.hpp> | |
22 | #include <boost/spirit/include/karma_directive.hpp> | |
23 | ||
24 | Also, see __include_structure__. | |
25 | ||
26 | [/////////////////////////////////////////////////////////////////////////////] | |
27 | [section:alignment Alignment Generator Directives (`left_align[]`, `center[]`, `right_align[]`)] | |
28 | ||
29 | [heading Description] | |
30 | ||
31 | The alignment directives allow to left align, right align or center output | |
32 | emitted by other generators into columns of a specified width while using | |
33 | an arbitrary generator to create the padding. | |
34 | ||
35 | [heading Header] | |
36 | ||
37 | For the `left_align[]` directive: | |
38 | ||
39 | // forwards to <boost/spirit/home/karma/directive/left_alignment.hpp> | |
40 | #include <boost/spirit/include/karma_left_alignment.hpp> | |
41 | ||
42 | For the `center[]` directive: | |
43 | ||
44 | // forwards to <boost/spirit/home/karma/directive/center_alignment.hpp> | |
45 | #include <boost/spirit/include/karma_center_alignment.hpp> | |
46 | ||
47 | For the `right_align[]` directive: | |
48 | ||
49 | // forwards to <boost/spirit/home/karma/directive/right_alignment.hpp> | |
50 | #include <boost/spirit/include/karma_right_alignment.hpp> | |
51 | ||
52 | Also, see __include_structure__. | |
53 | ||
54 | [heading Namespace] | |
55 | ||
56 | [table | |
57 | [[Name]] | |
58 | [[`boost::spirit::left_align // alias: boost::spirit::karma::left_align` ]] | |
59 | [[`boost::spirit::center // alias: boost::spirit::karma::center` ]] | |
60 | [[`boost::spirit::right_align // alias: boost::spirit::karma::right_align` ]] | |
61 | ] | |
62 | ||
63 | [heading Model of] | |
64 | ||
65 | [:__unary_generator_concept__] | |
66 | ||
67 | [variablelist Notation | |
68 | [[`a`] [A generator object]] | |
69 | [[`pad`] [A generator object, or a __karma_lazy_argument__ that | |
70 | evaluates to a generator object]] | |
71 | [[`A`, `Pad`] [Attribute types of the generators `a` and `pad`]] | |
72 | [[`width`] [Numeric literal, any unsigned integer value, or | |
73 | a __karma_lazy_argument__ that evaluates to an unsigned | |
74 | integer value]]] | |
75 | ||
76 | [heading Expression Semantics] | |
77 | ||
78 | Semantics of an expression is defined only where it differs from, or is not | |
79 | defined in __unary_generator_concept__. | |
80 | ||
81 | [table | |
82 | [[Expression] [Semantics]] | |
83 | [[`left_align[a]`] [Generate `a` left aligned in a column of | |
84 | width as defined by the preprocessor constant | |
85 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
86 | (default: 10), while using `space` to emit | |
87 | the necessary padding. This generator succeeds as | |
88 | long as its embedded generator `a` does not | |
89 | fail (unless the underlying output stream | |
90 | reports an error).]] | |
91 | [[`left_align(width)[a]`] [Generate `a` left aligned in a column of | |
92 | the given `width`, while using `space` to emit | |
93 | the necessary padding. This generator succeeds as | |
94 | long as its embedded generator `a` does not | |
95 | fail (unless the underlying output stream | |
96 | reports an error).]] | |
97 | [[`left_align(pad)[a]`] [Generate `a` left aligned in a column of | |
98 | width as defined by the preprocessor constant | |
99 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
100 | (default: 10), while using the generator `pad` | |
101 | to emit the necessary padding. This generator | |
102 | succeeds as long as its embedded and padding | |
103 | generators `a` and `pad` do not fail (except | |
104 | if the underlying output stream reports an | |
105 | error).]] | |
106 | [[`left_align(width, pad)[a]`] [Generate `a` left aligned in a column of | |
107 | the given `width`, while using the generator | |
108 | `pad` to emit the necessary padding. This | |
109 | generator succeeds as long as its embedded | |
110 | and padding generators `a` and `pad` do not | |
111 | fail (unless the underlying output stream | |
112 | reports an error).]] | |
113 | ||
114 | [[`center[a]`] [Generate `a` centered in a column of | |
115 | width as defined by the preprocessor constant | |
116 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
117 | (default: 10), while using `space` to emit | |
118 | the necessary padding. This generator succeeds as | |
119 | long as its embedded generator `a` does not | |
120 | fail (unless the underlying output stream | |
121 | reports an error).]] | |
122 | [[`center(width)[a]`] [Generate `a` centered in a column of | |
123 | the given `width`, while using `space` to emit | |
124 | the necessary padding. This generator succeeds as | |
125 | long as its embedded generator `a` does not | |
126 | fail (unless the underlying output stream | |
127 | reports an error).]] | |
128 | [[`center(pad)[a]`] [Generate `a` centered in a column of | |
129 | width as defined by the preprocessor constant | |
130 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
131 | (default: 10), while using the generator `pad` | |
132 | to emit the necessary padding. This generator | |
133 | succeeds as long as its embedded and padding | |
134 | generators `a` and `pad` do not fail (except | |
135 | if the underlying output stream reports an | |
136 | error).]] | |
137 | [[`center(width, pad)[a]`] [Generate `a` centered in a column of | |
138 | the given `width`, while using the generator | |
139 | `pad` to emit the necessary padding. This | |
140 | generator succeeds as long as its embedded | |
141 | and padding generators `a` and `pad` do not | |
142 | fail (unless the underlying output stream | |
143 | reports an error).]] | |
144 | ||
145 | [[`right_align[a]`] [Generate `a` right aligned in a column of | |
146 | width as defined by the preprocessor constant | |
147 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
148 | (default: 10), while using `space` to emit | |
149 | the necessary padding. This generator succeeds as | |
150 | long as its embedded generator `a` does not | |
151 | fail (unless the underlying output stream | |
152 | reports an error).]] | |
153 | [[`right_align(width)[a]`] [Generate `a` right aligned in a column of | |
154 | the given `width`, while using `space` to emit | |
155 | the necessary padding. This generator succeeds as | |
156 | long as its embedded generator `a` does not | |
157 | fail (unless the underlying output stream | |
158 | reports an error).]] | |
159 | [[`right_align(pad)[a]`] [Generate `a` right aligned in a column of | |
160 | width as defined by the preprocessor constant | |
161 | `BOOST_KARMA_DEFAULT_FIELD_LENGTH` | |
162 | (default: 10), while using the generator `pad` | |
163 | to emit the necessary padding. This generator | |
164 | succeeds as long as its embedded and padding | |
165 | generators `a` and `pad` do not fail (except | |
166 | if the underlying output stream reports an | |
167 | error).]] | |
168 | [[`right_align(width, pad)[a]`] [Generate `a` right aligned in a column of | |
169 | the given `width`, while using the generator | |
170 | `pad` to emit the necessary padding. This | |
171 | generator succeeds as long as its embedded | |
172 | and padding generators `a` and `pad` do not | |
173 | fail (unless the underlying output stream | |
174 | reports an error).]] | |
175 | ] | |
176 | ||
177 | [note None of the generator directives listed above limits the emitted output | |
178 | to the respective column width. If the emitted output is longer than | |
179 | the specified (or implied) column width, the generated output overruns | |
180 | the column to the right. | |
181 | ||
182 | If the output needs to be limited to a specified column width, use the | |
183 | `maxwidth[]` directive, for instance: | |
184 | `` | |
185 | maxwidth(8)[right_align(12)["1234567890"]] | |
186 | `` | |
187 | which will output (without the quotes): ``" 123456"`` | |
188 | ] | |
189 | ||
190 | [heading Attributes] | |
191 | ||
192 | See __karma_comp_attr_notation__. | |
193 | ||
194 | [table | |
195 | [[Expression] [Attribute]] | |
196 | [[`left_align[]`] | |
197 | [``a: A --> left_align[a]: A | |
198 | a: Unused --> left_align[a]: Unused``]] | |
199 | [[`left_align(width)[]`] | |
200 | [``a: A --> left_align(width)[a]: A | |
201 | a: Unused --> left_align(width)[a]: Unused``]] | |
202 | [[`left_align(pad)[]`] | |
203 | [``a: A, pad: Pad --> left_align(pad)[a]: A | |
204 | a: Unused, pad: Pad --> left_align(pad)[a]: Unused``]] | |
205 | [[`left_align(pad, width)[]`] | |
206 | [``a: A, pad: Pad --> left_align(pad, width)[a]: A | |
207 | a: Unused, pad: Pad --> left_align(pad, width)[a]: Unused``]] | |
208 | ||
209 | [[`center[]`] | |
210 | [``a: A --> center[a]: A | |
211 | a: Unused --> center[a]: Unused``]] | |
212 | [[`center(width)[]`] | |
213 | [``a: A --> center(width)[a]: A | |
214 | a: Unused --> center(width)[a]: Unused``]] | |
215 | [[`center(pad)[]`] | |
216 | [``a: A, pad: Pad --> center(pad)[a]: A | |
217 | a: Unused, pad: Pad --> center(pad)[a]: Unused``]] | |
218 | [[`center(pad, width)[]`] | |
219 | [``a: A, pad: Pad --> center(pad, width)[a]: A | |
220 | a: Unused, pad: Pad --> center(pad, width)[a]: Unused``]] | |
221 | ||
222 | [[`right_align[]`] | |
223 | [``a: A --> right_align[a]: A | |
224 | a: Unused --> right_align[a]: Unused``]] | |
225 | [[`right_align(width)[]`] | |
226 | [``a: A --> right_align(width)[a]: A | |
227 | a: Unused --> right_align(width)[a]: Unused``]] | |
228 | [[`right_align(pad)[]`] | |
229 | [``a: A, pad: Pad --> right_align(pad)[a]: A | |
230 | a: Unused, pad: Pad --> right_align(pad)[a]: Unused``]] | |
231 | [[`right_align(pad, width)[]`] | |
232 | [``a: A, pad: Pad --> right_align(pad, width)[a]: A | |
233 | a: Unused, pad: Pad --> right_align(pad, width)[a]: Unused``]] | |
234 | ] | |
235 | ||
236 | [heading Complexity] | |
237 | ||
238 | [:The overall complexity of an alignment generator directive is defined by | |
239 | the complexity of its embedded and padding generator. The complexity of the | |
240 | left alignment directive generator itself is O(1). The complexity of the | |
241 | center and right alignment directive generators is O(N), where `N` is the | |
242 | number of characters emitted by the embedded and padding generators.] | |
243 | ||
244 | [heading Example] | |
245 | ||
246 | [note The test harness for the example(s) below is presented in the | |
247 | __karma_basics_examples__ section.] | |
248 | ||
249 | Some includes: | |
250 | ||
251 | [reference_karma_includes] | |
252 | ||
253 | Some using declarations: | |
254 | ||
255 | [reference_karma_using_declarations_alignment] | |
256 | ||
257 | Basic usage of the alignment generators: | |
258 | ||
259 | [reference_karma_alignment] | |
260 | ||
261 | [endsect] [/ alignment] | |
262 | ||
263 | [/////////////////////////////////////////////////////////////////////////////] | |
264 | [section:repeat Repetition Generator Directive (`repeat[]`)] | |
265 | ||
266 | [heading Description] | |
267 | ||
268 | The repetition directive allows to repeat an arbitrary generator expression | |
269 | while optionally specifying the lower and upper repetition counts. It provides | |
270 | a more powerful and flexible mechanism for repeating a generator. There are | |
271 | grammars that are impractical and cumbersome, if not impossible, for the basic | |
272 | EBNF iteration syntax ([karma_kleene unary `'*'`] and the [karma_plus unary `'+'`]) | |
273 | to specify. Examples: | |
274 | ||
275 | * A file name may have a maximum of 255 characters only. | |
276 | * A specific bitmap file format has exactly 4096 RGB color information. | |
277 | * A 256 bit binary string (1..256 1s or 0s). | |
278 | ||
279 | [heading Header] | |
280 | ||
281 | // forwards to <boost/spirit/home/karma/directive/repeat.hpp> | |
282 | #include <boost/spirit/include/karma_repeat.hpp> | |
283 | ||
284 | Also, see __include_structure__. | |
285 | ||
286 | [heading Namespace] | |
287 | ||
288 | [table | |
289 | [[Name]] | |
290 | [[`boost::spirit::repeat // alias: boost::spirit::karma::repeat` ]] | |
291 | [[`boost::spirit::inf // alias: boost::spirit::karma::inf` ]] | |
292 | ] | |
293 | ||
294 | [heading Model of] | |
295 | ||
296 | [:__unary_generator_concept__] | |
297 | ||
298 | [variablelist Notation | |
299 | [[`a`] [A generator object]] | |
300 | [[`num, num1, num2`][Numeric literals, any unsigned integer value, or | |
301 | a __karma_lazy_argument__ that evaluates to an | |
302 | unsigned integer value]] | |
303 | [[`inf`] [Placeholder expression standing for 'no upper repeat | |
304 | limit']] | |
305 | ] | |
306 | ||
307 | [heading Expression Semantics] | |
308 | ||
309 | Semantics of an expression is defined only where it differs from, or is not | |
310 | defined in __unary_generator_concept__. | |
311 | ||
312 | [table | |
313 | [[Expression] [Semantics]] | |
314 | [[`repeat[a]`] [Repeat the generator `a` zero or more times. | |
315 | This generator succeeds as long as its | |
316 | embedded generator `a` does not fail (except | |
317 | if the underlying output stream reports an | |
318 | error). This variant of `repeat[]` is | |
319 | semantically equivalent to the | |
320 | [karma_kleene Kleene Star operator `*a`]]] | |
321 | [[`repeat(num)[a]`] [Repeat the generator `a` exactly `num` | |
322 | times. This generator succeeds as long as its | |
323 | embedded generator `a` does not fail and | |
324 | as long as the associated attribute | |
325 | (container) contains at least `num` elements | |
326 | (unless the underlying output stream | |
327 | reports an error).]] | |
328 | [[`repeat(num1, num2)[a]`] [Repeat the generator `a` at least `num1` | |
329 | times but not more than `num2` times. This | |
330 | generator succeeds as long as its | |
331 | embedded generator `a` does not fail and | |
332 | as long as the associated attribute | |
333 | (container) contains at least `num1` elements | |
334 | (unless the underlying output stream | |
335 | reports an error). If the associated | |
336 | attribute (container) does contain more | |
337 | than `num2` elements, this directive | |
338 | limits the repeat count to `num2`. ]] | |
339 | [[`repeat(num, inf)[a]`] [Repeat the generator `a` at least `num1` | |
340 | times. No upper limit for the repeat count | |
341 | is set. This generator succeeds as long as | |
342 | its embedded generator `a` does not fail | |
343 | and as long as the associated attribute | |
344 | (container) contains at least `num` elements | |
345 | (unless the underlying output stream | |
346 | reports an error).]] | |
347 | ] | |
348 | ||
349 | [note All failing iterations of the embedded generator will consume one element | |
350 | from the supplied attribute. The overall `repeat[a]` will succeed as long | |
351 | as the iteration criteria (number of successful invocations of the | |
352 | embedded generator) is fulfilled (unless the underlying output stream | |
353 | reports an error).] | |
354 | ||
355 | [heading Attributes] | |
356 | ||
357 | See __karma_comp_attr_notation__. | |
358 | ||
359 | [table | |
360 | [[Expression] [Attribute]] | |
361 | [[`repeat[a]`] | |
362 | [``a: A --> repeat[a]: vector<A> | |
363 | a: Unused --> repeat[a]: Unused``]] | |
364 | [[`repeat(num)[a]`] | |
365 | [``a: A --> repeat(num)[a]: vector<A> | |
366 | a: Unused --> repeat(num)[a]: Unused``]] | |
367 | [[`repeat(num1, num2)[a]`] | |
368 | [``a: A --> repeat(num1, num2)[a]: vector<A> | |
369 | a: Unused --> repeat(num1, num2)[a]: Unused``]] | |
370 | [[`repeat(num, inf)[a]`] | |
371 | [``a: A --> repeat(num, inf)[a]: vector<A> | |
372 | a: Unused --> repeat(num, inf)[a]: Unused``]] | |
373 | ] | |
374 | ||
375 | [important The table above uses `vector<A>` as placeholders only. | |
376 | ||
377 | The notation of `vector<A>` stands for /any STL container/ holding | |
378 | elements of type `A`.] | |
379 | ||
380 | It is important to note, that the `repeat[]` directive does not perform any | |
381 | buffering of the output generated by its embedded elements. That means that | |
382 | any failing element generator might have already generated some output, which | |
383 | is /not/ rolled back. | |
384 | ||
385 | [tip The simplest way to force a `repeat[]` directive to behave as if it did | |
386 | buffering is to wrap it into a buffering directive (see | |
387 | __karma_buffer__): | |
388 | ||
389 | ``buffer[repeat[a]]`` | |
390 | ||
391 | which will /not/ generate any output in case of a failing generator | |
392 | `repeat[a]`. The expression: | |
393 | ||
394 | ``repeat[buffer[a]]`` | |
395 | ||
396 | will not generate any partial output from a generator `a` if it fails | |
397 | generating in the middle of its output. The overall expression will | |
398 | still generate the output as produced by all succeeded invocations of | |
399 | the generator `a`.] | |
400 | ||
401 | [heading Complexity] | |
402 | ||
403 | [:The overall complexity of the repetition generator is defined by the | |
404 | complexity of its embedded generator. The complexity of the repeat itself is | |
405 | O(N), where N is the number of repetitions to execute.] | |
406 | ||
407 | [heading Example] | |
408 | ||
409 | [note The test harness for the example(s) below is presented in the | |
410 | __karma_basics_examples__ section.] | |
411 | ||
412 | Some includes: | |
413 | ||
414 | [reference_karma_includes] | |
415 | ||
416 | Some using declarations: | |
417 | ||
418 | [reference_karma_using_declarations_repeat] | |
419 | ||
420 | Basic usage of `repeat` generator directive: | |
421 | ||
422 | [reference_karma_repeat] | |
423 | ||
424 | [endsect] [/ repeat] | |
425 | ||
426 | [/////////////////////////////////////////////////////////////////////////////] | |
427 | [section:delimit Generator Directives Controlling Automatic Delimiting (`verbatim[]`, `no_delimit[]`, `delimit[]`)] | |
428 | ||
429 | [heading Description] | |
430 | ||
431 | The directives `delimit[]`, `no_delimit[]`, and `verbatim[]` can be used to | |
432 | control automatic delimiting. The directives `verbatim[]` and `no_delimit[]` | |
433 | disable any automatic delimiting, while the directive `delimit[]` (re-)enables | |
434 | automatic delimiting. | |
435 | ||
436 | [heading Header] | |
437 | ||
438 | For the `verbatim[]` directive: | |
439 | ||
440 | // forwards to <boost/spirit/home/karma/directive/verbatim.hpp> | |
441 | #include <boost/spirit/include/karma_verbatim.hpp> | |
442 | ||
443 | For the `no_delimit[]` directive: | |
444 | ||
445 | // forwards to <boost/spirit/home/karma/directive/no_delimit.hpp> | |
446 | #include <boost/spirit/include/karma_no_delimit.hpp> | |
447 | ||
448 | For the `delimit[]` directive: | |
449 | ||
450 | // forwards to <boost/spirit/home/karma/directive/delimit.hpp> | |
451 | #include <boost/spirit/include/karma_delimit.hpp> | |
452 | ||
453 | Also, see __include_structure__. | |
454 | ||
455 | [heading Namespace] | |
456 | ||
457 | [table | |
458 | [[Name]] | |
459 | [[`boost::spirit::verbatim // alias: boost::spirit::karma::verbatim` ]] | |
460 | [[`boost::spirit::no_delimit // alias: boost::spirit::karma::no_delimit` ]] | |
461 | [[`boost::spirit::delimit // alias: boost::spirit::karma::delimit` ]] | |
462 | ] | |
463 | ||
464 | [heading Model of] | |
465 | ||
466 | [:__unary_generator_concept__] | |
467 | ||
468 | [variablelist Notation | |
469 | [[`a`] [A generator object]] | |
470 | [[`d`] [A generator object, or a __karma_lazy_argument__ that | |
471 | evaluates to a generator object]] | |
472 | [[`A`, `D`] [Attribute types of the generators `a` and `d`]]] | |
473 | ||
474 | [heading Expression Semantics] | |
475 | ||
476 | Semantics of an expression is defined only where it differs from, or is not | |
477 | defined in __unary_generator_concept__. | |
478 | ||
479 | [table | |
480 | [[Expression] [Semantics]] | |
481 | [[`delimit[a]`] [Enable automatic delimiting for the embedded generator | |
482 | `a` while using the `space` generator as the | |
483 | delimiting generator. If used inside a `verbatim[]` | |
484 | directive it re-enables the delimiter generator as used | |
485 | outside of this `verbatim[]` instead. The directive succeeds | |
486 | as long as the embedded generator succeeded (unless | |
487 | the underlying output stream reports an error).]] | |
488 | [[`delimit(d)[a]`] [Enable automatic delimiting for the embedded generator | |
489 | `a` while using the generator `d` as the | |
490 | delimiting generator. The directive succeeds | |
491 | as long as the embedded generator succeeded (unless | |
492 | the underlying output stream reports an error).]] | |
493 | [[`verbatim[a]`] [Disable automatic delimiting for the embedded generator | |
494 | `a`. The directive succeeds | |
495 | as long as the embedded generator succeeded (unless | |
496 | the underlying output stream reports an error). This | |
497 | directive it has no effect if it is used when no | |
498 | delimiting is active. When delimiting is active this | |
499 | directive performs a post-delimit step (which is | |
500 | different from the behavior of `no_delimit[]`).]] | |
501 | [[`no_delimit[a]`] [Disable automatic delimiting for the embedded generator | |
502 | `a`. The directive succeeds | |
503 | as long as the embedded generator succeeded (unless | |
504 | the underlying output stream reports an error). This | |
505 | directive it has no effect if it is used when no | |
506 | delimiting is active. When delimiting is active this | |
507 | directive does not perform a post-delimit step (which is | |
508 | different from the behavior of `verbatim[]`.]] | |
509 | ] | |
510 | ||
511 | [heading Attributes] | |
512 | ||
513 | See __karma_comp_attr_notation__. | |
514 | ||
515 | [table | |
516 | [[Expression] [Attribute]] | |
517 | [[`delimit[a]`] | |
518 | [``a: A --> delimit[a]: A | |
519 | a: Unused --> delimit[a]: Unused``]] | |
520 | [[`delimit(d)[a]`] | |
521 | [``a: A, d: D --> delimit(d)[a]: A | |
522 | a: Unused, d: D --> delimit(d)[a]: Unused``]] | |
523 | [[`verbatim[a]`] | |
524 | [``a: A --> verbatim[a]: A | |
525 | a: Unused --> verbatim[a]: Unused``]] | |
526 | [[`no_delimit[a]`] | |
527 | [``a: A --> no_delimit[a]: A | |
528 | a: Unused --> no_delimit[a]: Unused``]] | |
529 | ] | |
530 | ||
531 | [heading Complexity] | |
532 | ||
533 | [:The overall complexity of the generator directives `delimit[]`, `verbatim[]`, | |
534 | and `no_delimit[]` is defined by the complexity of its embedded generators. | |
535 | The complexity of the directives themselves is O(1).] | |
536 | ||
537 | [heading Example] | |
538 | ||
539 | [note The test harness for the example(s) below is presented in the | |
540 | __karma_basics_examples__ section.] | |
541 | ||
542 | Some includes: | |
543 | ||
544 | [reference_karma_includes_simple] | |
545 | ||
546 | Some using declarations: | |
547 | ||
548 | [reference_karma_using_declarations_delimit] | |
549 | ||
550 | Basic usage of `delimit` generator directive: | |
551 | ||
552 | [reference_karma_delimit] | |
553 | ||
554 | [endsect] [/ verbatim/delimit/no_delimit] | |
555 | ||
556 | [/////////////////////////////////////////////////////////////////////////////] | |
557 | [section:upperlower Generator Directives Controlling Case Sensitivity (`upper[]`, `lower[]`)] | |
558 | ||
559 | [heading Description] | |
560 | ||
561 | The generator directives `ns::lower[]` and `ns::upper[]` force their embedded | |
562 | generators to emit lower case or upper case only characters based on the | |
563 | interpretation of the generated characters in the character set defined by | |
564 | `ns` (see __karma_char_encoding_namespace__). | |
565 | ||
566 | [heading Header] | |
567 | ||
568 | // forwards to <boost/spirit/home/karma/directive/upper_lower_case.hpp> | |
569 | #include <boost/spirit/include/karma_upper_lower_case.hpp> | |
570 | ||
571 | Also, see __include_structure__. | |
572 | ||
573 | [heading Namespace] | |
574 | ||
575 | [table | |
576 | [[Name]] | |
577 | [[`ns::lower`]] | |
578 | [[`ns::upper`]] | |
579 | ] | |
580 | ||
581 | In the table above, `ns` represents a __karma_char_encoding_namespace__. | |
582 | ||
583 | [heading Model of] | |
584 | ||
585 | [:The model of `lower[]` and `upper[]` is the model of its subject generator.] | |
586 | ||
587 | [variablelist Notation | |
588 | [[`a`] [A generator object]] | |
589 | [[`A`] [Attribute type of the generator `a`]] | |
590 | [[`ns`] [A __karma_char_encoding_namespace__.]]] | |
591 | ||
592 | [heading Expression Semantics] | |
593 | ||
594 | The `lower[]` and `upper[]` directives have no special generator semantics. | |
595 | They are pure modifier directives. They indirectly influence the way all | |
596 | subject generators work. They add information (the `tag::upper` or `tag::lower`) | |
597 | to the `Modifier` template parameter used while transforming the `proto::expr` | |
598 | into the corresponding generator expression. This is achieved by the | |
599 | following specializations: | |
600 | ||
601 | namespace boost { namespace spirit | |
602 | { | |
603 | template <typename CharEncoding> | |
604 | struct is_modifier_directive< | |
605 | karma::domain | |
606 | , tag::char_code<tag::lower, CharEncoding> > | |
607 | : mpl::true_ | |
608 | {}; | |
609 | ||
610 | template <typename CharEncoding> | |
611 | struct is_modifier_directive< | |
612 | karma::domain | |
613 | , tag::char_code<tag::upper, CharEncoding> > | |
614 | : mpl::true_ | |
615 | }} | |
616 | ||
617 | (for more details see the section describing the compilation process of the | |
618 | __boost_proto__ expression into the corresponding generator expressions). | |
619 | ||
620 | [table | |
621 | [[Expression] [Semantics]] | |
622 | [[`ns::lower[a]`] [Generate `a` as lower case, interpreted in the | |
623 | character set defined by `ns`. The directive succeeds | |
624 | as long as the embedded generator succeeded (unless | |
625 | the underlying output stream reports an error).]] | |
626 | [[`ns::upper[a]`] [Generate `a` as upper case, interpreted in the | |
627 | character set defined by `ns`. The directive succeeds | |
628 | as long as the embedded generator succeeded (unless | |
629 | the underlying output stream reports an error).]] | |
630 | ] | |
631 | ||
632 | [note If both directives are 'active' with regard to a generator, the | |
633 | innermost of those directives takes precedence. For instance: | |
634 | `` | |
635 | generate(sink, ascii::lower['A' << ascii::upper['b']]) | |
636 | `` | |
637 | will generate `"aB"` (without the quotes). | |
638 | ||
639 | Further, the directives will have no effect on generators emitting | |
640 | characters not having an upper case or lower case equivalent in the | |
641 | character set defined by `ns`. | |
642 | ] | |
643 | ||
644 | [heading Attributes] | |
645 | ||
646 | See __karma_comp_attr_notation__. | |
647 | ||
648 | [table | |
649 | [[Expression] [Attribute]] | |
650 | [[`ns:lower[a]`] | |
651 | [``a: A --> ns:lower[a]: A | |
652 | a: Unused --> ns:lower[a]: Unused``]] | |
653 | [[`ns:upper[a]`] | |
654 | [``a: A --> ns:upper[a]: A | |
655 | a: Unused --> ns:upper[a]: Unused``]] | |
656 | ] | |
657 | ||
658 | [heading Complexity] | |
659 | ||
660 | [:The overall complexity of the generator directives `ns::lower[]` and `ns::upper[]` | |
661 | is defined by the complexity of its embedded generators. The directives | |
662 | themselves are compile time only directives, having no impact on runtime | |
663 | performance.] | |
664 | ||
665 | [heading Example] | |
666 | ||
667 | [note The test harness for the example(s) below is presented in the | |
668 | __karma_basics_examples__ section.] | |
669 | ||
670 | Some includes: | |
671 | ||
672 | [reference_karma_includes_simple] | |
673 | ||
674 | Some using declarations: | |
675 | ||
676 | [reference_karma_using_declarations_upperlower] | |
677 | ||
678 | Basic usage of the `upper` and `lower` generator directives: | |
679 | ||
680 | [reference_karma_upperlower] | |
681 | ||
682 | [endsect] [/ upper/lower] | |
683 | ||
684 | [/////////////////////////////////////////////////////////////////////////////] | |
685 | [section:maxwidth Generator Directives Controlling the Maximum Field Width (`maxwidth[]`)] | |
686 | ||
687 | [heading Description] | |
688 | ||
689 | The `maxwidth[]` directive allows to limit (truncate) the overall length of the | |
690 | output generated by the embedded generator. | |
691 | ||
692 | [heading Header] | |
693 | ||
694 | // forwards to <boost/spirit/home/karma/directive/maxwidth.hpp> | |
695 | #include <boost/spirit/include/karma_maxwidth.hpp> | |
696 | ||
697 | Also, see __include_structure__. | |
698 | ||
699 | [table | |
700 | [[Name]] | |
701 | [[`boost::spirit::maxwidth // alias: boost::spirit::karma::maxwidth` ]] | |
702 | ] | |
703 | ||
704 | [heading Model of] | |
705 | ||
706 | [:__unary_generator_concept__] | |
707 | ||
708 | [variablelist Notation | |
709 | [[`a`] [A generator object]] | |
710 | [[`A`] [Attribute type of the generator `a`]] | |
711 | [[`num`] [Numeric literal, any unsigned integer value, or | |
712 | a __karma_lazy_argument__ that evaluates to an unsigned | |
713 | integer value]]] | |
714 | ||
715 | [heading Expression Semantics] | |
716 | ||
717 | Semantics of an expression is defined only where it differs from, or is not | |
718 | defined in __unary_generator_concept__. | |
719 | ||
720 | [table | |
721 | [[Expression] [Semantics]] | |
722 | [[`maxwidth[a]`] [Limit the overall length of the emitted output of | |
723 | the embedded generator (including characters | |
724 | generated by automatic delimiting) to the number | |
725 | of characters as defined by the preprocessor constant | |
726 | `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`. Any additional | |
727 | output is truncated. The directive succeeds as long | |
728 | as the embedded generator succeeded (unless | |
729 | the underlying output stream reports an error).]] | |
730 | [[`maxwidth(num)[a]`] [Limit the overall length of the emitted output of | |
731 | the embedded generator (including characters | |
732 | generated by automatic delimiting) to the number | |
733 | of characters as defined by `num`. Any additional | |
734 | output is truncated. The directive succeeds as long | |
735 | as the embedded generator succeeded (unless the | |
736 | underlying output stream reports an error).]] | |
737 | ] | |
738 | ||
739 | [note The `maxwidth[]` generator directive does not pad the generated output | |
740 | to fill the specified column width. If the emitted output is shorter | |
741 | than the specified (or implied) column width, the generated output will | |
742 | be more narrow than the column width. | |
743 | ||
744 | If the output needs to always be equal to a specified column width, use | |
745 | one of the alignment directives `left-align[]`, `center[]`, or | |
746 | `right_align[]`, for instance: | |
747 | `` | |
748 | maxwidth(8)[left_align(8)["1234"]] | |
749 | `` | |
750 | which will output: `"1234 "` (without the quotes). | |
751 | ] | |
752 | ||
753 | [heading Attributes] | |
754 | ||
755 | See __karma_comp_attr_notation__. | |
756 | ||
757 | [table | |
758 | [[Expression] [Attribute]] | |
759 | [[`maxwidth[a]`] | |
760 | [``a: A --> maxwidth[a]: A | |
761 | a: Unused --> maxwidth[a]: Unused``]] | |
762 | [[`maxwidth(num)[a]`] | |
763 | [``a: A --> maxwidth(num)[a]: A | |
764 | a: Unused --> maxwidth(num)[a]: Unused``]] | |
765 | ] | |
766 | ||
767 | [heading Complexity] | |
768 | ||
769 | [:The overall complexity of the generator directive `maxwidth[]` | |
770 | is defined by the complexity of its embedded generator. The complexity of the | |
771 | directive itself is O(N), where `N` is the number of characters generated | |
772 | by the maxwidth directive.] | |
773 | ||
774 | [heading Example] | |
775 | ||
776 | [note The test harness for the example(s) below is presented in the | |
777 | __karma_basics_examples__ section.] | |
778 | ||
779 | Some includes: | |
780 | ||
781 | [reference_karma_includes_simple] | |
782 | ||
783 | Some using declarations: | |
784 | ||
785 | [reference_karma_using_declarations_maxwidth] | |
786 | ||
787 | Basic usage of `maxwidth` generator directive: | |
788 | ||
789 | [reference_karma_maxwidth] | |
790 | ||
791 | [endsect] [/ maxwidth] | |
792 | ||
793 | [/////////////////////////////////////////////////////////////////////////////] | |
794 | [section:buffer Generator Directive for Temporary Output Buffering (`buffer[]`)] | |
795 | ||
796 | [heading Description] | |
797 | ||
798 | All generator components (except the __karma_alternative__ generator) pass | |
799 | their generated output directly to the underlying output stream. If a generator | |
800 | fails halfway through, the output generated so far is not 'rolled back'. The | |
801 | buffering generator directive allows to avoid this unwanted output to be | |
802 | generated. It temporarily redirects the output produced by the embedded | |
803 | generator into a buffer. This buffer is flushed to the underlying stream only | |
804 | after the embedded generator succeeded, but is discarded otherwise. | |
805 | ||
806 | [heading Header] | |
807 | ||
808 | // forwards to <boost/spirit/home/karma/directive/buffer.hpp> | |
809 | #include <boost/spirit/include/karma_buffer.hpp> | |
810 | ||
811 | Also, see __include_structure__. | |
812 | ||
813 | [table | |
814 | [[Name]] | |
815 | [[`boost::spirit::buffer // alias: boost::spirit::karma::buffer` ]] | |
816 | ] | |
817 | ||
818 | [heading Model of] | |
819 | ||
820 | [:__unary_generator_concept__] | |
821 | ||
822 | [variablelist Notation | |
823 | [[`a`] [A generator object]] | |
824 | [[`A`] [Attribute type of generator `a`]]] | |
825 | ||
826 | [heading Expression Semantics] | |
827 | ||
828 | Semantics of an expression is defined only where it differs from, or is not | |
829 | defined in __unary_generator_concept__. | |
830 | ||
831 | [table | |
832 | [[Expression] [Semantics]] | |
833 | [[`buffer[a]`] [The embedded generator `a` is invoked but its output | |
834 | is temporarily intercepted and stored in an internal | |
835 | buffer. If `a` succeeds the buffer content is flushed | |
836 | to the underlying output stream, otherwise the buffer | |
837 | content is discarded. The buffer directive succeeds | |
838 | as long as the embedded generator succeeded (unless | |
839 | the underlying output stream reports an error).]] | |
840 | ] | |
841 | ||
842 | [tip If you want to make the buffered generator succeed regardless of the | |
843 | outcome of the embedded generator, simply wrap the `buffer[a]` into an | |
844 | additional optional: `-buffer[a]` (see __karma_optional__).] | |
845 | ||
846 | [heading Attributes] | |
847 | ||
848 | See __karma_comp_attr_notation__. | |
849 | ||
850 | [table | |
851 | [[Expression] [Attribute]] | |
852 | [[`buffer[a]`] | |
853 | [``a: A --> buffer[a]: A | |
854 | a: Unused --> buffer[a]: Unused``]] | |
855 | ] | |
856 | ||
857 | [heading Complexity] | |
858 | ||
859 | [:The overall complexity of the buffering generator directive is defined by the | |
860 | complexity of its embedded generator. The complexity of the buffering | |
861 | directive generator itself is O(N), where N is the number of characters | |
862 | buffered.] | |
863 | ||
864 | [heading Example] | |
865 | ||
866 | [note The test harness for the example(s) below is presented in the | |
867 | __karma_basics_examples__ section.] | |
868 | ||
869 | Some includes: | |
870 | ||
871 | [reference_karma_includes] | |
872 | ||
873 | Some using declarations: | |
874 | ||
875 | [reference_karma_using_declarations_buffer] | |
876 | ||
877 | Basic usage of a buffering generator directive. It shows how the partial | |
878 | output generated in the first example does not show up in the generated output | |
879 | as the plus generator fails (no data is available, see __karma_plus__). | |
880 | ||
881 | [reference_karma_buffer] | |
882 | ||
883 | [endsect] [/ buffer] | |
884 | ||
885 | [/////////////////////////////////////////////////////////////////////////////] | |
886 | [section:omit Generator Directives Consuming Attributes (`omit[]` and `skip[]`)] | |
887 | ||
888 | [heading Description] | |
889 | ||
890 | The directives `omit[]` and `skip[]` consumes the attribute type of the | |
891 | embedded generator without generating any output. The `omit[]` directive | |
892 | will still execute the embedded generator while discarding the generated output | |
893 | afterwards. The `skip[]` directive will not execute the embedded generator, but | |
894 | will use it only to extract the exposed attribute type. | |
895 | ||
896 | [heading Header] | |
897 | ||
898 | // forwards to <boost/spirit/home/karma/directive/omit.hpp> | |
899 | #include <boost/spirit/include/karma_omit.hpp> | |
900 | ||
901 | Also, see __include_structure__. | |
902 | ||
903 | [table | |
904 | [[Name]] | |
905 | [[`boost::spirit::omit // alias: boost::spirit::karma::omit` ]] | |
906 | [[`boost::spirit::skip // alias: boost::spirit::karma::skip` ]] | |
907 | ] | |
908 | ||
909 | [heading Model of] | |
910 | ||
911 | [:__unary_generator_concept__] | |
912 | ||
913 | [variablelist Notation | |
914 | [[`a`] [A generator object]] | |
915 | [[`A`] [Attribute type of generator `a`]]] | |
916 | ||
917 | [heading Expression Semantics] | |
918 | ||
919 | Semantics of an expression is defined only where it differs from, or is not | |
920 | defined in __unary_generator_concept__. | |
921 | ||
922 | [table | |
923 | [[Expression] [Semantics]] | |
924 | [[`omit[a]`] [The `omit` directive consumes the attribute type of the | |
925 | embedded generator `A` without generating any output. | |
926 | It succeeds always. The embedded generator is executed | |
927 | and any generated output is discarded.]] | |
928 | [[`skip[a]`] [The `skip` directive consumes the attribute type of the | |
929 | embedded generator `A` without generating any output. | |
930 | It succeeds always. The embedded generator is not | |
931 | executed.]] | |
932 | ] | |
933 | ||
934 | [heading Attributes] | |
935 | ||
936 | See __karma_comp_attr_notation__. | |
937 | ||
938 | [table | |
939 | [[Expression] [Attribute]] | |
940 | [[`omit[a]`] | |
941 | [``a: A --> omit[a]: A | |
942 | a: Unused --> omit[a]: Unused``]] | |
943 | [[`skip[a]`] | |
944 | [``a: A --> skip[a]: A | |
945 | a: Unused --> skip[a]: Unused``]] | |
946 | ] | |
947 | ||
948 | [heading Complexity] | |
949 | ||
950 | [:The overall complexity of the `omit[]` directive depends on the complexity | |
951 | of the embedded generator. The overall complexity of the `skip[]` generator | |
952 | directive is O(1) as it does not generate any output.] | |
953 | ||
954 | [heading Example] | |
955 | ||
956 | [note The test harness for the example(s) below is presented in the | |
957 | __karma_basics_examples__ section.] | |
958 | ||
959 | Some includes: | |
960 | ||
961 | [reference_karma_includes] | |
962 | ||
963 | Some using declarations: | |
964 | ||
965 | [reference_karma_using_declarations_omit] | |
966 | ||
967 | Basic usage of a `omit` generator directive. It shows how it consumes the first | |
968 | element of the provided attribute without generating anything, leaving the | |
969 | second element of the attribute to the non-wrapped `double_` generator. | |
970 | ||
971 | [reference_karma_omit] | |
972 | ||
973 | Generally, this directive is helpful in situations, where the attribute type | |
974 | contains more information (elements) than need to be used to generate the | |
975 | required output. Normally in such situations we would resolve to use semantic | |
976 | actions to explicitly pass the correct parts of the overall attribute to the | |
977 | generators. The `omit` directive helps achieving the same without having to use | |
978 | semantic actions. | |
979 | ||
980 | Consider the attribute type: | |
981 | ||
982 | typedef fusion::vector<int, double, std::string> attribute_type; | |
983 | ||
984 | where we need to generate output only from the first and last element: | |
985 | ||
986 | typedef std::back_insert:iterator<std::string> iterator_type; | |
987 | ||
988 | karma::rule<iterator_type, attribute_type()> r; | |
989 | r = int_[_1 = phoenix::at_c<0>(_val)] << string[_1 = phoenix::at_c<2>(_val)]; | |
990 | ||
991 | std::string str; | |
992 | iterator_type sink(str); | |
993 | generate(sink, r, attribute_type(1, 2.0, "example")); // will generate: '1example' | |
994 | ||
995 | This is error prone and not really readable. The same can be achieved by using | |
996 | the `omit` directive: | |
997 | ||
998 | r = int_ << omit[double_] << string; | |
999 | ||
1000 | which is at the same time more readable and more efficient as we don't have to | |
1001 | use semantic actions. | |
1002 | ||
1003 | The semantics of using the `skip[]` directive are identical to the `omit[]` | |
1004 | directive, except that it does not actually execute the embedded generator. | |
1005 | For this reason it is usually preferable to utilize the `skip[]` directive | |
1006 | instead of the `omit[]` directive. On the other hand, the `omit[]` directive | |
1007 | is very useful whenever the embedded generator produces side effects (has | |
1008 | semantic actions which need to be executed). | |
1009 | ||
1010 | [endsect] [/ omit] | |
1011 | ||
1012 | [/////////////////////////////////////////////////////////////////////////////] | |
1013 | [section:duplicate Generator Directive Duplicating Attributes (`duplicate[]`)] | |
1014 | ||
1015 | [heading Description] | |
1016 | ||
1017 | The directive `duplicate[]` duplicates its attribute to all elements of the | |
1018 | embedded generator if this is a sequence generator. Otherwise it does nothing. | |
1019 | ||
1020 | [heading Header] | |
1021 | ||
1022 | // forwards to <boost/spirit/home/karma/directive/duplicate.hpp> | |
1023 | #include <boost/spirit/include/karma_duplicate.hpp> | |
1024 | ||
1025 | Also, see __include_structure__. | |
1026 | ||
1027 | [table | |
1028 | [[Name]] | |
1029 | [[`boost::spirit::duplicate // alias: boost::spirit::karma::duplicate` ]] | |
1030 | ] | |
1031 | ||
1032 | [heading Model of] | |
1033 | ||
1034 | [:__unary_generator_concept__] | |
1035 | ||
1036 | [variablelist Notation | |
1037 | [[`a`] [A generator object]] | |
1038 | [[`A`] [Attribute type of generator `a`]]] | |
1039 | ||
1040 | [heading Expression Semantics] | |
1041 | ||
1042 | Semantics of an expression is defined only where it differs from, or is not | |
1043 | defined in __unary_generator_concept__. | |
1044 | ||
1045 | [table | |
1046 | [[Expression] [Semantics]] | |
1047 | [[`duplicate[a]`] [The `duplicate` directive duplicates the supplied | |
1048 | attribute for all elements of a embedded sequence | |
1049 | generator. For all other types of embedded generators | |
1050 | it has no effect. It succeeds as long as its embedded | |
1051 | generator does not fail.]] | |
1052 | ] | |
1053 | ||
1054 | [heading Attributes] | |
1055 | ||
1056 | See __karma_comp_attr_notation__. | |
1057 | ||
1058 | [table | |
1059 | [[Expression] [Attribute]] | |
1060 | [[`duplicate[a]`] | |
1061 | [``a: A --> duplicate[a]: A | |
1062 | a: tuple<A, A, ...> --> duplicate[a]: A | |
1063 | a: Unused --> duplicate[a]: Unused``]] | |
1064 | ] | |
1065 | ||
1066 | If the embedded generator of the `duplicate[]` directive is a sequence it is | |
1067 | expected that all elements of this sequence expose either the same attribute | |
1068 | type, an compatible attribute type, or `unused`. In this case, the | |
1069 | `duplicate[]` directive exposes the attribute type of its first element. The | |
1070 | behavior of the `duplicate[]` directive is undefined if the elements of an | |
1071 | embedded sequence do not expose the same attributes. Most likely, the | |
1072 | corresponding expression will not compile. | |
1073 | ||
1074 | [heading Complexity] | |
1075 | ||
1076 | [:The overall complexity of the `duplicate[]` directive depends on the complexity | |
1077 | of the embedded generator.] | |
1078 | ||
1079 | [heading Example] | |
1080 | ||
1081 | [note The test harness for the example(s) below is presented in the | |
1082 | __karma_basics_examples__ section.] | |
1083 | ||
1084 | Some includes: | |
1085 | ||
1086 | [reference_karma_includes] | |
1087 | ||
1088 | Some using declarations: | |
1089 | ||
1090 | [reference_karma_using_declarations_duplicate] | |
1091 | ||
1092 | Basic usage of the `duplicate` generators: | |
1093 | ||
1094 | [reference_karma_duplicate] | |
1095 | ||
1096 | [endsect] [/ duplicate] | |
1097 | ||
1098 | [/////////////////////////////////////////////////////////////////////////////] | |
1099 | [section:columns Generator Directive Separating Output Into Columns (`columns[]`)] | |
1100 | ||
1101 | [heading Description] | |
1102 | ||
1103 | The `columns[]` directive separates the output emitted by the embedded | |
1104 | generator by inserting special column separators. | |
1105 | ||
1106 | [heading Header] | |
1107 | ||
1108 | // forwards to <boost/spirit/home/karma/directive/columns.hpp> | |
1109 | #include <boost/spirit/include/karma_columns.hpp> | |
1110 | ||
1111 | Also, see __include_structure__. | |
1112 | ||
1113 | [table | |
1114 | [[Name]] | |
1115 | [[`boost::spirit::columns // alias: boost::spirit::karma::columns` ]] | |
1116 | ] | |
1117 | ||
1118 | [heading Model of] | |
1119 | ||
1120 | [:__unary_generator_concept__] | |
1121 | ||
1122 | [variablelist Notation | |
1123 | [[`a`] [A generator object]] | |
1124 | [[`g`] [A generator object, or a __karma_lazy_argument__ that | |
1125 | evaluates to a generator object, will be used to emit column | |
1126 | separators]] | |
1127 | [[`A`] [Attribute type of generator `a`] | |
1128 | [[`num`] [Numeric literal, any unsigned integer value, or | |
1129 | a __karma_lazy_argument__ that evaluates to an unsigned | |
1130 | integer value defining the number of items to emit in between | |
1131 | the column separators]]] | |
1132 | ||
1133 | [heading Expression Semantics] | |
1134 | ||
1135 | Semantics of an expression is defined only where it differs from, or is not | |
1136 | defined in __unary_generator_concept__. | |
1137 | ||
1138 | [table | |
1139 | [[Expression] [Semantics]] | |
1140 | [[`columns[a]`] [The `columns` directive invokes a generator after | |
1141 | each N-th element of the embedded generator has been | |
1142 | emitted. The number of columns is defined by the | |
1143 | preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. | |
1144 | The column separator used will be `karma::eol`.]] | |
1145 | [[`columns(num)[a]`][The `columns` directive invokes a generator after | |
1146 | each N-th element of the embedded generator has been | |
1147 | emitted. The number of columns is defined by the | |
1148 | argument to the directive `num`. | |
1149 | The column separator used will be `karma::eol`.]] | |
1150 | [[`columns(g)[a]`] [The `columns` directive invokes a generator after | |
1151 | each N-th element of the embedded generator has been | |
1152 | emitted. The number of columns is defined by the | |
1153 | preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. | |
1154 | The column separator used will be `g`.]] | |
1155 | [[`columns(num, g)[a]`] [The `columns` directive invokes a generator after | |
1156 | each N-th element of the embedded generator has been | |
1157 | emitted. The number of columns is defined by the | |
1158 | argument to the directive `num`. | |
1159 | The column separator used will be `g`.]] | |
1160 | ] | |
1161 | ||
1162 | [heading Attributes] | |
1163 | ||
1164 | See __karma_comp_attr_notation__. | |
1165 | ||
1166 | [table | |
1167 | [[Expression] [Attribute]] | |
1168 | [[`columns[a]`] | |
1169 | [``a: A --> columns[a]: A | |
1170 | a: Unused --> columns[a]: Unused``]] | |
1171 | [[`columns(num)[a]`] | |
1172 | [``a: A --> columns(num)[a]: A | |
1173 | a: Unused --> columns(num)[a]: Unused``]] | |
1174 | [[`columns(g)[a]`] | |
1175 | [``a: A --> columns(g)[a]: A | |
1176 | a: Unused --> columns(g)[a]: Unused``]] | |
1177 | [[`columns(num, g)[a]`] | |
1178 | [``a: A --> columns(num, g)[a]: A | |
1179 | a: Unused --> columns(num, g)[a]: Unused``]] | |
1180 | ] | |
1181 | ||
1182 | [heading Complexity] | |
1183 | ||
1184 | [:The overall complexity of the `columns` generator directive depends on the | |
1185 | complexity of the embedded generator. The complexity of the `columns` generator | |
1186 | directive itself is O(N), where `N` is the number of inserted column | |
1187 | separators.] | |
1188 | ||
1189 | [heading Example] | |
1190 | ||
1191 | [note The test harness for the example(s) below is presented in the | |
1192 | __karma_basics_examples__ section.] | |
1193 | ||
1194 | Some includes: | |
1195 | ||
1196 | [reference_karma_includes] | |
1197 | ||
1198 | Some using declarations: | |
1199 | ||
1200 | [reference_karma_using_declarations_columns] | |
1201 | ||
1202 | Basic usage of the `columns` generators: | |
1203 | ||
1204 | [reference_karma_columns] | |
1205 | ||
1206 | [endsect] [/ columns] | |
1207 | ||
1208 | [/////////////////////////////////////////////////////////////////////////////] | |
1209 | [section:as Generator Directives Forcing Atomic Extraction (`as<T>, as_string[], as_wstring[]`)] | |
1210 | ||
1211 | [heading Description] | |
1212 | ||
1213 | The `as<T>` class forces the atomic extraction of a container type `T` from it's | |
1214 | consumed attribute. Usually, repetitive generators (such as __karma_kleene__, | |
1215 | etc) or sequences exposing a `vector<A>` will extract elements from the | |
1216 | container supplied as their consumed attribute by looping through the | |
1217 | containers iterators. In some cases, this may be undesirable. The `as<T>` | |
1218 | class creates a directive that will pass an unnamed temporary object of type | |
1219 | `T` to it's subject, if extracting `T` from it's consumed attribute determined | |
1220 | at generation-time to be valid. __customize_valid_as__ is called by `as<T>` to | |
1221 | determine validity; if it returns false, the generator fails. Subsequent | |
1222 | extraction is performed by calling __customize_as__. | |
1223 | ||
1224 | [note `T` is required to be a container type. If __customize_is_container__ | |
1225 | does not return true for `T`, a compile-time error will occur.] | |
1226 | ||
1227 | [heading Header] | |
1228 | ||
1229 | // forwards to <boost/spirit/home/karma/directive/as.hpp> | |
1230 | #include <boost/spirit/include/karma_as.hpp> | |
1231 | ||
1232 | Also, see __include_structure__. | |
1233 | ||
1234 | [heading Namespace] | |
1235 | ||
1236 | [table | |
1237 | [[Name]] | |
1238 | [[`boost::spirit::as_string // alias: boost::spirit::karma::as_string` ]] | |
1239 | [[`boost::spirit::as_wstring // alias: boost::spirit::karma::as_wstring` ]] | |
1240 | ] | |
1241 | ||
1242 | [heading Synopsis] | |
1243 | ||
1244 | template <typename T> | |
1245 | struct as; | |
1246 | ||
1247 | [heading Template parameters] | |
1248 | ||
1249 | [table | |
1250 | [[Parameter] [Description] [Default]] | |
1251 | [[`T`] [A container type.] [none]] | |
1252 | ] | |
1253 | ||
1254 | [heading Model of] | |
1255 | ||
1256 | [:__unary_generator_concept__] | |
1257 | ||
1258 | [variablelist Notation | |
1259 | [[`a`] [A __generator_concept__.]] | |
1260 | [[`attr`] [The attribute supplied to the directive.]] | |
1261 | ] | |
1262 | ||
1263 | [heading Expression Semantics] | |
1264 | ||
1265 | Semantics of an expression is defined only where it differs from, or is | |
1266 | not defined in __unary_generator_concept__. | |
1267 | ||
1268 | [table | |
1269 | [[Expression] [Semantics]] | |
1270 | [[`as<T>()[a]`] [Extract an instance of `T` from `attr`, and | |
1271 | invoke the subject generator `a`, supplying | |
1272 | the unnamed temporary as it's attribute.]] | |
1273 | [[`as_string[a]`] [Equivalent to `as<std::string>()[a]`]] | |
1274 | [[`as_wstring[a]`] [Equivalent to `as<std::wstring>()[a]`]] | |
1275 | ] | |
1276 | ||
1277 | [heading Attributes] | |
1278 | ||
1279 | See __karma_comp_attr_notation__. | |
1280 | ||
1281 | [table | |
1282 | [[Expression] [Attribute]] | |
1283 | [[`as<T>()[a]`] [`a: A --> as<T>()[a]: T`]] | |
1284 | ] | |
1285 | ||
1286 | [heading Complexity] | |
1287 | ||
1288 | [:The complexity is defined by the complexity of the subject generator, `a`, and | |
1289 | the complexity of the extraction unnamed contianer of type `T` from the | |
1290 | attribute `attr`.] | |
1291 | ||
1292 | [heading Example] | |
1293 | ||
1294 | [note The test harness for the example(s) below is presented in the | |
1295 | __karma_basics_examples__ section.] | |
1296 | ||
1297 | Some using declarations: | |
1298 | ||
1299 | [reference_karma_using_declarations_as] | |
1300 | ||
1301 | Simple usage of `as<T>`, `as_string` and `as_wstring`: | |
1302 | ||
1303 | [reference_karma_as] | |
1304 | ||
1305 | [endsect] [/ as] | |
1306 | ||
1307 | [endsect] [/ directives] |