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 11This module includes different generator directives. It includes alignment 12directives (`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 16columns (`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 24Also, see __include_structure__. 25 26[/////////////////////////////////////////////////////////////////////////////] 27[section:alignment Alignment Generator Directives (`left_align[]`, `center[]`, `right_align[]`)] 28 29[heading Description] 30 31The alignment directives allow to left align, right align or center output 32emitted by other generators into columns of a specified width while using 33an arbitrary generator to create the padding. 34 35[heading Header] 36 37For 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 42For 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 47For 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 52Also, 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 78Semantics of an expression is defined only where it differs from, or is not 79defined 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 192See __karma_comp_attr_notation__. 193 194[table 195 [[Expression] [Attribute]] 196 [[`left_align[]`] 197[``a: A --> left_align[a]: A 198a: Unused --> left_align[a]: Unused``]] 199 [[`left_align(width)[]`] 200[``a: A --> left_align(width)[a]: A 201a: Unused --> left_align(width)[a]: Unused``]] 202 [[`left_align(pad)[]`] 203[``a: A, pad: Pad --> left_align(pad)[a]: A 204a: Unused, pad: Pad --> left_align(pad)[a]: Unused``]] 205 [[`left_align(pad, width)[]`] 206[``a: A, pad: Pad --> left_align(pad, width)[a]: A 207a: Unused, pad: Pad --> left_align(pad, width)[a]: Unused``]] 208 209 [[`center[]`] 210[``a: A --> center[a]: A 211a: Unused --> center[a]: Unused``]] 212 [[`center(width)[]`] 213[``a: A --> center(width)[a]: A 214a: Unused --> center(width)[a]: Unused``]] 215 [[`center(pad)[]`] 216[``a: A, pad: Pad --> center(pad)[a]: A 217a: Unused, pad: Pad --> center(pad)[a]: Unused``]] 218 [[`center(pad, width)[]`] 219[``a: A, pad: Pad --> center(pad, width)[a]: A 220a: Unused, pad: Pad --> center(pad, width)[a]: Unused``]] 221 222 [[`right_align[]`] 223[``a: A --> right_align[a]: A 224a: Unused --> right_align[a]: Unused``]] 225 [[`right_align(width)[]`] 226[``a: A --> right_align(width)[a]: A 227a: Unused --> right_align(width)[a]: Unused``]] 228 [[`right_align(pad)[]`] 229[``a: A, pad: Pad --> right_align(pad)[a]: A 230a: Unused, pad: Pad --> right_align(pad)[a]: Unused``]] 231 [[`right_align(pad, width)[]`] 232[``a: A, pad: Pad --> right_align(pad, width)[a]: A 233a: 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 249Some includes: 250 251[reference_karma_includes] 252 253Some using declarations: 254 255[reference_karma_using_declarations_alignment] 256 257Basic 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 268The repetition directive allows to repeat an arbitrary generator expression 269while optionally specifying the lower and upper repetition counts. It provides 270a more powerful and flexible mechanism for repeating a generator. There are 271grammars that are impractical and cumbersome, if not impossible, for the basic 272EBNF iteration syntax ([karma_kleene unary `'*'`] and the [karma_plus unary `'+'`]) 273to 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 284Also, 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 309Semantics of an expression is defined only where it differs from, or is not 310defined 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 357See __karma_comp_attr_notation__. 358 359[table 360 [[Expression] [Attribute]] 361 [[`repeat[a]`] 362[``a: A --> repeat[a]: vector<A> 363a: Unused --> repeat[a]: Unused``]] 364 [[`repeat(num)[a]`] 365[``a: A --> repeat(num)[a]: vector<A> 366a: Unused --> repeat(num)[a]: Unused``]] 367 [[`repeat(num1, num2)[a]`] 368[``a: A --> repeat(num1, num2)[a]: vector<A> 369a: Unused --> repeat(num1, num2)[a]: Unused``]] 370 [[`repeat(num, inf)[a]`] 371[``a: A --> repeat(num, inf)[a]: vector<A> 372a: 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 380It is important to note, that the `repeat[]` directive does not perform any 381buffering of the output generated by its embedded elements. That means that 382any failing element generator might have already generated some output, which 383is /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 412Some includes: 413 414[reference_karma_includes] 415 416Some using declarations: 417 418[reference_karma_using_declarations_repeat] 419 420Basic 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 431The directives `delimit[]`, `no_delimit[]`, and `verbatim[]` can be used to 432control automatic delimiting. The directives `verbatim[]` and `no_delimit[]` 433disable any automatic delimiting, while the directive `delimit[]` (re-)enables 434automatic delimiting. 435 436[heading Header] 437 438For the `verbatim[]` directive: 439 440 // forwards to <boost/spirit/home/karma/directive/verbatim.hpp> 441 #include <boost/spirit/include/karma_verbatim.hpp> 442 443For 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 448For the `delimit[]` directive: 449 450 // forwards to <boost/spirit/home/karma/directive/delimit.hpp> 451 #include <boost/spirit/include/karma_delimit.hpp> 452 453Also, 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 476Semantics of an expression is defined only where it differs from, or is not 477defined 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 513See __karma_comp_attr_notation__. 514 515[table 516 [[Expression] [Attribute]] 517 [[`delimit[a]`] 518[``a: A --> delimit[a]: A 519a: Unused --> delimit[a]: Unused``]] 520 [[`delimit(d)[a]`] 521[``a: A, d: D --> delimit(d)[a]: A 522a: Unused, d: D --> delimit(d)[a]: Unused``]] 523 [[`verbatim[a]`] 524[``a: A --> verbatim[a]: A 525a: Unused --> verbatim[a]: Unused``]] 526 [[`no_delimit[a]`] 527[``a: A --> no_delimit[a]: A 528a: 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 542Some includes: 543 544[reference_karma_includes_simple] 545 546Some using declarations: 547 548[reference_karma_using_declarations_delimit] 549 550Basic 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 561The generator directives `ns::lower[]` and `ns::upper[]` force their embedded 562generators to emit lower case or upper case only characters based on the 563interpretation 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 571Also, see __include_structure__. 572 573[heading Namespace] 574 575[table 576 [[Name]] 577 [[`ns::lower`]] 578 [[`ns::upper`]] 579] 580 581In 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 594The `lower[]` and `upper[]` directives have no special generator semantics. 595They are pure modifier directives. They indirectly influence the way all 596subject generators work. They add information (the `tag::upper` or `tag::lower`) 597to the `Modifier` template parameter used while transforming the `proto::expr` 598into the corresponding generator expression. This is achieved by the 599following 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 646See __karma_comp_attr_notation__. 647 648[table 649 [[Expression] [Attribute]] 650 [[`ns:lower[a]`] 651[``a: A --> ns:lower[a]: A 652a: Unused --> ns:lower[a]: Unused``]] 653 [[`ns:upper[a]`] 654[``a: A --> ns:upper[a]: A 655a: 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 670Some includes: 671 672[reference_karma_includes_simple] 673 674Some using declarations: 675 676[reference_karma_using_declarations_upperlower] 677 678Basic 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 689The `maxwidth[]` directive allows to limit (truncate) the overall length of the 690output 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 697Also, 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 717Semantics of an expression is defined only where it differs from, or is not 718defined 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 755See __karma_comp_attr_notation__. 756 757[table 758 [[Expression] [Attribute]] 759 [[`maxwidth[a]`] 760[``a: A --> maxwidth[a]: A 761a: Unused --> maxwidth[a]: Unused``]] 762 [[`maxwidth(num)[a]`] 763[``a: A --> maxwidth(num)[a]: A 764a: 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 779Some includes: 780 781[reference_karma_includes_simple] 782 783Some using declarations: 784 785[reference_karma_using_declarations_maxwidth] 786 787Basic 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 798All generator components (except the __karma_alternative__ generator) pass 799their generated output directly to the underlying output stream. If a generator 800fails halfway through, the output generated so far is not 'rolled back'. The 801buffering generator directive allows to avoid this unwanted output to be 802generated. It temporarily redirects the output produced by the embedded 803generator into a buffer. This buffer is flushed to the underlying stream only 804after 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 811Also, 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 828Semantics of an expression is defined only where it differs from, or is not 829defined 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 848See __karma_comp_attr_notation__. 849 850[table 851 [[Expression] [Attribute]] 852 [[`buffer[a]`] 853[``a: A --> buffer[a]: A 854a: 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 869Some includes: 870 871[reference_karma_includes] 872 873Some using declarations: 874 875[reference_karma_using_declarations_buffer] 876 877Basic usage of a buffering generator directive. It shows how the partial 878output generated in the first example does not show up in the generated output 879as 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 890The directives `omit[]` and `skip[]` consumes the attribute type of the 891embedded generator without generating any output. The `omit[]` directive 892will still execute the embedded generator while discarding the generated output 893afterwards. The `skip[]` directive will not execute the embedded generator, but 894will 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 901Also, 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 919Semantics of an expression is defined only where it differs from, or is not 920defined 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 936See __karma_comp_attr_notation__. 937 938[table 939 [[Expression] [Attribute]] 940 [[`omit[a]`] 941[``a: A --> omit[a]: A 942a: Unused --> omit[a]: Unused``]] 943 [[`skip[a]`] 944[``a: A --> skip[a]: A 945a: 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 959Some includes: 960 961[reference_karma_includes] 962 963Some using declarations: 964 965[reference_karma_using_declarations_omit] 966 967Basic usage of a `omit` generator directive. It shows how it consumes the first 968element of the provided attribute without generating anything, leaving the 969second element of the attribute to the non-wrapped `double_` generator. 970 971[reference_karma_omit] 972 973Generally, this directive is helpful in situations, where the attribute type 974contains more information (elements) than need to be used to generate the 975required output. Normally in such situations we would resolve to use semantic 976actions to explicitly pass the correct parts of the overall attribute to the 977generators. The `omit` directive helps achieving the same without having to use 978semantic actions. 979 980Consider the attribute type: 981 982 typedef fusion::vector<int, double, std::string> attribute_type; 983 984where 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 995This is error prone and not really readable. The same can be achieved by using 996the `omit` directive: 997 998 r = int_ << omit[double_] << string; 999 1000which is at the same time more readable and more efficient as we don't have to 1001use semantic actions. 1002 1003The semantics of using the `skip[]` directive are identical to the `omit[]` 1004directive, except that it does not actually execute the embedded generator. 1005For this reason it is usually preferable to utilize the `skip[]` directive 1006instead of the `omit[]` directive. On the other hand, the `omit[]` directive 1007is very useful whenever the embedded generator produces side effects (has 1008semantic 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 1017The directive `duplicate[]` duplicates its attribute to all elements of the 1018embedded 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 1025Also, 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 1042Semantics of an expression is defined only where it differs from, or is not 1043defined 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 1056See __karma_comp_attr_notation__. 1057 1058[table 1059 [[Expression] [Attribute]] 1060 [[`duplicate[a]`] 1061[``a: A --> duplicate[a]: A 1062a: tuple<A, A, ...> --> duplicate[a]: A 1063a: Unused --> duplicate[a]: Unused``]] 1064] 1065 1066If the embedded generator of the `duplicate[]` directive is a sequence it is 1067expected that all elements of this sequence expose either the same attribute 1068type, an compatible attribute type, or `unused`. In this case, the 1069`duplicate[]` directive exposes the attribute type of its first element. The 1070behavior of the `duplicate[]` directive is undefined if the elements of an 1071embedded sequence do not expose the same attributes. Most likely, the 1072corresponding 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 1084Some includes: 1085 1086[reference_karma_includes] 1087 1088Some using declarations: 1089 1090[reference_karma_using_declarations_duplicate] 1091 1092Basic 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 1103The `columns[]` directive separates the output emitted by the embedded 1104generator 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 1111Also, 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 1135Semantics of an expression is defined only where it differs from, or is not 1136defined 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 1164See __karma_comp_attr_notation__. 1165 1166[table 1167 [[Expression] [Attribute]] 1168 [[`columns[a]`] 1169[``a: A --> columns[a]: A 1170a: Unused --> columns[a]: Unused``]] 1171 [[`columns(num)[a]`] 1172[``a: A --> columns(num)[a]: A 1173a: Unused --> columns(num)[a]: Unused``]] 1174 [[`columns(g)[a]`] 1175[``a: A --> columns(g)[a]: A 1176a: Unused --> columns(g)[a]: Unused``]] 1177 [[`columns(num, g)[a]`] 1178[``a: A --> columns(num, g)[a]: A 1179a: Unused --> columns(num, g)[a]: Unused``]] 1180] 1181 1182[heading Complexity] 1183 1184[:The overall complexity of the `columns` generator directive depends on the 1185complexity of the embedded generator. The complexity of the `columns` generator 1186directive itself is O(N), where `N` is the number of inserted column 1187separators.] 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 1194Some includes: 1195 1196[reference_karma_includes] 1197 1198Some using declarations: 1199 1200[reference_karma_using_declarations_columns] 1201 1202Basic 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 1213The `as<T>` class forces the atomic extraction of a container type `T` from it's 1214consumed attribute. Usually, repetitive generators (such as __karma_kleene__, 1215etc) or sequences exposing a `vector<A>` will extract elements from the 1216container supplied as their consumed attribute by looping through the 1217containers iterators. In some cases, this may be undesirable. The `as<T>` 1218class 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 1220at generation-time to be valid. __customize_valid_as__ is called by `as<T>` to 1221determine validity; if it returns false, the generator fails. Subsequent 1222extraction is performed by calling __customize_as__. 1223 1224[note `T` is required to be a container type. If __customize_is_container__ 1225does 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 1232Also, 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 1265Semantics of an expression is defined only where it differs from, or is 1266not 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 1279See __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 1289the complexity of the extraction unnamed contianer of type `T` from the 1290attribute `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 1297Some using declarations: 1298 1299[reference_karma_using_declarations_as] 1300 1301Simple usage of `as<T>`, `as_string` and `as_wstring`: 1302 1303[reference_karma_as] 1304 1305[endsect] [/ as] 1306 1307[endsect] [/ directives] 1308