ceph/src/boost/libs/spirit/doc/karma/operator.qbk

   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:operator Generator Operators]
  10
  11 Operators are used as a means for object composition and embedding.
  12 Simple generators may be composed to form composites through operator
  13 overloading, crafted to approximate the syntax of __peg__ (PEG). An
  14 expression such as:
  15
  16     a | b
  17
  18 yields a new generator type which is a composite of its operands, `a` and
  19 `b`.
  20
  21 This module includes different generators which get instantiated if one of the
  22 overloaded operators is used with more primitive generator constructs. It
  23 includes sequences (`a << b`), alternatives (`a | b`), Kleene star (unary `*`),
  24 plus (unary `+`), optional (unary `-`), lists (`a % b`), and the two predicates, the
  25 /and/ predicate (unary `&`) and the /not/ predicate (unary `!`).
  26
  27 [heading Module Header]
  28
  29     // forwards to <boost/spirit/home/karma/operator.hpp>
  30     #include <boost/spirit/include/karma_operator.hpp>
  31
  32 Also, see __include_structure__.
  33
  34 [/////////////////////////////////////////////////////////////////////////////]
  35 [section:sequence Sequence Generator (`a << b`)]
  36
  37 [heading Description]
  38
  39 Generator sequences are used to consecutively combine different, more primitive
  40 generators. All generators in a sequence are invoked from left to right as long
  41 as they succeed.
  42
  43 [heading Header]
  44
  45     // forwards to <boost/spirit/home/karma/operator/sequence.hpp>
  46     #include <boost/spirit/include/karma_sequence.hpp>
  47
  48 Also, see __include_structure__.
  49
  50 [heading Model of]
  51
  52 [:__nary_generator_concept__]
  53
  54 [heading Expression Semantics]
  55
  56 Semantics of an expression is defined only where it differs from, or is not
  57 defined in __nary_generator_concept__.
  58
  59 [table
  60     [[Expression]       [Semantics]]
  61     [[`a << b`]         [The generators `a` and `b` are executed sequentially
  62                          from left to right and as long as they succeed. A
  63                          failed generator stops the execution of the entire
  64                          sequence and makes the sequence fail as well.]]
  65 ]
  66
  67 It is important to note, that sequences don't perform any buffering of the
  68 output generated by its elements. That means that any failing sequence might
  69 have already generated some output, which is /not/ rolled back.
  70
  71 [tip    The simplest way to force a sequence to behave as if it did buffering
  72         is to wrap it into a buffering directive (see __karma_buffer__):
  73
  74         ``buffer[a << b << c]``
  75
  76         which will /not/ generate any output in case of a failing sequence.]
  77
  78 [heading Attributes]
  79
  80 See __karma_comp_attr_notation__.
  81
  82 [table
  83     [[Expression]       [Attribute]]
  84     [[`a << b` (sequence)]
  85 [``a: A, b: B --> (a << b): tuple<A, B>
  86 a: A, b: Unused --> (a << b): A
  87 a: Unused, b: B --> (a << b): B
  88 a: Unused, b: Unused --> (a << b): Unused
  89
  90 a: A, b: A --> (a << b): vector<A>
  91 a: vector<A>, b: A --> (a << b): vector<A>
  92 a: A, b: vector<A> --> (a << b): vector<A>
  93 a: vector<A>, b: vector<A> --> (a << b): vector<A>``]]
  94 ]
  95
  96 [important The table above uses `tuple<A, B>` and `vector<A>` as placeholders
  97            only.
  98
  99            The notation `tuple<A, B>` stands for /any fusion sequence of two
 100            elements/, where `A` is the type of its first element and `B` is the
 101            type of its second element.
 102
 103            The notation of `vector<A>` stands for /any STL container/ holding
 104            elements of type `A`.]
 105
 106 The attribute composition and propagation rules as shown in the table above make
 107 sequences somewhat special as they can operate in two modes if all elements have
 108 the same attribute type: consuming fusion sequences and consuming STL
 109 containers. The selected mode depends on the type of the attribute supplied.
 110
 111 [heading Complexity]
 112
 113 [:The overall complexity of the sequence generator is defined by the sum of the
 114   complexities of its elements. The complexity of the sequence itself is O(N),
 115   where N is the number of elements in the sequence.]
 116
 117 [heading Example]
 118
 119 [note The test harness for the example(s) below is presented in the
 120       __karma_basics_examples__ section.]
 121
 122 Some includes:
 123
 124 [reference_karma_includes]
 125
 126 Some using declarations:
 127
 128 [reference_karma_using_declarations_sequence]
 129
 130 Basic usage of a sequence:
 131
 132 [reference_karma_sequence]
 133
 134 [endsect]
 135
 136 [/////////////////////////////////////////////////////////////////////////////]
 137 [section:alternative Alternative Generator (`a | b`)]
 138
 139 [heading Description]
 140
 141 Generator alternatives are used to combine different, more primitive generators
 142 into alternatives. All generators in an alternative are invoked from left to
 143 right until one of them succeeds.
 144
 145 [heading Header]
 146
 147     // forwards to <boost/spirit/home/karma/operator/alternative.hpp>
 148     #include <boost/spirit/include/karma_alternative.hpp>
 149
 150 Also, see __include_structure__.
 151
 152 [heading Model of]
 153
 154 [:__nary_generator_concept__]
 155
 156 [heading Expression Semantics]
 157
 158 Semantics of an expression is defined only where it differs from, or is not
 159 defined in __nary_generator_concept__.
 160
 161 [table
 162     [[Expression]       [Semantics]]
 163     [[`a | b`]          [The generators `a` and `b` are executed sequentially
 164                          from left to right until one of them succeeds. A
 165                          failed generator forces the alternative generator to
 166                          try the next one. The alternative fails as a whole
 167                          only if all elements of the alternative fail. Each
 168                          element of the alternative gets passed the whole
 169                          attribute of the alternative.]]
 170 ]
 171
 172 Alternatives intercept and buffer the output of the currently executed element.
 173 This allows to avoid partial outputs from failing elements as the buffered
 174 content will be forwarded to the actual output only after an element succeeded.
 175
 176 [heading Attributes]
 177
 178 See __karma_comp_attr_notation__.
 179
 180 [table
 181     [[Expression]        [Attribute]]
 182     [[`a | b` (alternative)]
 183 [``a: A, b: B --> (a | b): variant<A, B>
 184 a: A, b: Unused --> (a | b): A
 185 a: Unused, b: B --> (a | b): B
 186 a: Unused, b: Unused --> (a | b): Unused
 187 a: A, b: A --> (a | b): A``]]
 188 ]
 189
 190 [important The table above uses `variant<A, B>` as a placeholder only. The
 191            notation `variant<A, B>` stands for the type `boost::variant<A, B>`.
 192 ]
 193
 194 The attribute handling of Alternatives is special as their behavior is
 195 not completely defined at compile time. First of all the selected alternative
 196 element depends on the actual type of the attribute supplied to the alternative
 197 generator (i.e. what is stored in the variant). The attribute type supplied at
 198 /runtime/ narrows the set of considered alternatives to those being compatible
 199 attribute wise. The remaining alternatives are tried sequentially until the
 200 first of them succeeds. See below for an example of this behavior.
 201
 202 [heading Complexity]
 203
 204 [:The overall complexity of the alternative generator is defined by the sum of
 205   the complexities of its elements. The complexity of the alternative itself is
 206   O(N), where N is the number of elements in the alternative.]
 207
 208 [heading Example]
 209
 210 [note The test harness for the example(s) below is presented in the
 211       __karma_basics_examples__ section.]
 212
 213 Some includes:
 214
 215 [reference_karma_includes]
 216
 217 Some using declarations:
 218
 219 [reference_karma_using_declarations_alternative]
 220
 221 Basic usage of an alternative. While being only the second alternative, the
 222 `double_` generator is chosen for output formatting because the supplied
 223 attribute type is not compatible (i.e. not convertible) to the attribute type
 224 of the `string` alternative.
 225
 226 [reference_karma_alternative1]
 227
 228 The same formatting rules may be used to output a string. This time we supply
 229 the string `"example"`, resulting in the first alternative to be chosen for the
 230 generated output.
 231
 232 [reference_karma_alternative2]
 233
 234 [endsect]
 235
 236 [/////////////////////////////////////////////////////////////////////////////]
 237 [section:kleene Kleene Star Generator (`*a`)]
 238
 239 [heading Description]
 240
 241 Kleene star generators are used to repeat the execution of an embedded generator
 242 zero or more times. Regardless of the success of the embedded generator, the
 243 Kleene star generator always succeeds.
 244
 245 [heading Header]
 246
 247     // forwards to <boost/spirit/home/karma/operator/kleene.hpp>
 248     #include <boost/spirit/include/karma_kleene.hpp>
 249
 250 Also, see __include_structure__.
 251
 252 [heading Model of]
 253
 254 [:__unary_generator_concept__]
 255
 256 [heading Expression Semantics]
 257
 258 Semantics of an expression is defined only where it differs from, or is not
 259 defined in __unary_generator_concept__.
 260
 261 [table
 262     [[Expression]       [Semantics]]
 263     [[`*a`]             [The generator `a` is executed zero or more times
 264                          depending on the availability of an attribute. The
 265                          execution of `a` stops after the attribute values
 266                          passed to the Kleene star generator are exhausted.
 267                          The Kleene star always succeeds (unless the
 268                          underlying output stream reports an error).]]
 269 ]
 270
 271 [note All failing iterations of the embedded generator will consume one element
 272       from the supplied attribute.]
 273
 274 [heading Attributes]
 275
 276 See __karma_comp_attr_notation__.
 277
 278 [table
 279     [[Expression]           [Attribute]]
 280     [[`*a` (Kleene star, unary `*`)]
 281 [``a: A --> *a: vector<A>
 282 a: Unused --> *a: Unused``]]
 283 ]
 284
 285 [important The table above uses `vector<A>` as a placeholder only. The notation
 286            of `vector<A>` stands for /any STL container/ holding elements of
 287            type `A`.]
 288
 289 The Kleene star generator will execute its embedded generator once for each
 290 element in the provided container attribute as long as the embedded
 291 generator succeeds. On each iteration it will pass the next consecutive element
 292 from the container attribute to the embedded generator. Therefore the number of
 293 iterations will not be larger than the number of elements in the container
 294 passed as its attribute. An empty container will make the Kleene star
 295 generate no output at all.
 296
 297 It is important to note, that the Kleene star does not perform any buffering
 298 of the output generated by its embedded elements. That means that any failing
 299 element generator might have already generated some output, which is /not/
 300 rolled back.
 301
 302 [tip    The simplest way to force a Kleene star to behave as if it did
 303         buffering is to wrap it into a buffering directive (see
 304         __karma_buffer__):
 305
 306         ``buffer[*a]``
 307
 308         which will /not/ generate any output in case of a failing generator `*a`.
 309         The expression:
 310
 311         ``*(buffer[a])``
 312
 313         will not generate any partial output from a generator `a` if it fails
 314         generating in the middle of its output. The overall expression will
 315         still generate the output as produced by all successful invocations of
 316         the generator `a`.]
 317
 318 [heading Complexity]
 319
 320 [:The overall complexity of the Kleene star generator is defined by the
 321   complexity of its embedded generator multiplied by the number of executed
 322   iterations. The complexity of the Kleene star itself is O(N), where N is the
 323   number of elements in the container passed as its attribute.]
 324
 325 [heading Example]
 326
 327 [note The test harness for the example(s) below is presented in the
 328       __karma_basics_examples__ section.]
 329
 330 Some includes:
 331
 332 [reference_karma_includes]
 333
 334 Some using declarations:
 335
 336 [reference_karma_using_declarations_kleene]
 337
 338 Basic usage of a Kleene star generator:
 339
 340 [reference_karma_kleene]
 341
 342 [endsect]
 343
 344 [/////////////////////////////////////////////////////////////////////////////]
 345 [section:plus Plus Generator (`+a`)]
 346
 347 [heading Description]
 348
 349 The Plus generator is used to repeat the execution of an embedded generator
 350 one or more times. It succeeds if the embedded generator has been successfully
 351 executed at least once.
 352
 353 [heading Header]
 354
 355     // forwards to <boost/spirit/home/karma/operator/plus.hpp>
 356     #include <boost/spirit/include/karma_plus.hpp>
 357
 358 Also, see __include_structure__.
 359
 360 [heading Model of]
 361
 362 [:__unary_generator_concept__]
 363
 364 [heading Expression Semantics]
 365
 366 Semantics of an expression is defined only where it differs from, or is not
 367 defined in __unary_generator_concept__.
 368
 369 [table
 370     [[Expression]       [Semantics]]
 371     [[`+a`]             [The generator `a` is executed one or more times
 372                          depending on the availability of an attribute. The
 373                          execution of `a` stops after the attribute values
 374                          passed to the plus generator are exhausted.
 375                          The plus generator succeeds as long as its embedded
 376                          generator has been successfully executed at least once
 377                          (unless the underlying output stream reports an
 378                          error).]]
 379 ]
 380
 381 [note All failing iterations of the embedded generator will consume one element
 382       from the supplied attribute. The overall `+a` will succeed as long as at
 383       least one invocation of the embedded generator will succeed (unless the
 384       underlying output stream reports an error).]
 385
 386 [heading Attributes]
 387
 388 See __karma_comp_attr_notation__.
 389
 390 [table
 391     [[Expression]         [Attribute]]
 392     [[`+a` (unary `+`)]
 393 [``a: A --> +a: vector<A>
 394 a: Unused --> +a: Unused``]]
 395 ]
 396
 397 [important The table above uses `vector<A>` as a placeholder only. The notation
 398            of `vector<A>` stands for /any STL container/ holding elements of
 399            type `A`.]
 400
 401 The Plus generator will execute its embedded generator once for each
 402 element in the provided container attribute as long as the embedded
 403 generator succeeds. On each iteration it will pass the next consecutive element
 404 from the container attribute to the embedded generator. Therefore the number of
 405 iterations will not be larger than the number of elements in the container
 406 passed as its attribute. An empty container will make the plus generator fail.
 407
 408 It is important to note, that the plus generator does not perform any buffering
 409 of the output generated by its embedded elements. That means that any failing
 410 element generator might have already generated some output, which is /not/
 411 rolled back.
 412
 413 [tip    The simplest way to force a plus generator to behave as if it did
 414         buffering is to wrap it into a buffering directive (see
 415         __karma_buffer__):
 416
 417         ``buffer[+a]``
 418
 419         which will /not/ generate any output in case of a failing generator `+a`.
 420         The expression:
 421
 422         ``+(buffer[a])``
 423
 424         will not generate any partial output from a generator `a` if it fails
 425         generating in the middle of its output. The overall expression will
 426         still generate the output as produced by all successful invocations of
 427         the generator `a`.]
 428
 429 [heading Complexity]
 430
 431 [:The overall complexity of the plus generator is defined by the
 432   complexity of its embedded generator multiplied by the number of executed
 433   iterations. The complexity of the plus generator itself is O(N), where N is
 434   the number of elements in the container passed as its attribute.]
 435
 436 [heading Example]
 437
 438 [note The test harness for the example(s) below is presented in the
 439       __karma_basics_examples__ section.]
 440
 441 Some includes:
 442
 443 [reference_karma_includes]
 444
 445 Some using declarations:
 446
 447 [reference_karma_using_declarations_plus]
 448
 449 Basic usage of a plus generator:
 450
 451 [reference_karma_plus1]
 452
 453 A more sophisticated use case showing how to leverage the fact that plus is
 454 failing for empty containers passed as its attribute:
 455
 456 [reference_karma_plus2]
 457
 458 [endsect]
 459
 460 [/////////////////////////////////////////////////////////////////////////////]
 461 [section:list List Generator (`a % b`)]
 462
 463 [heading Description]
 464
 465 The list generator is used to repeat the execution of an embedded generator
 466 and intersperse it with the output of another generator one or more times.
 467 It succeeds if the embedded generator has been successfully executed at least
 468 once.
 469
 470 [heading Header]
 471
 472     // forwards to <boost/spirit/home/karma/operator/list.hpp>
 473     #include <boost/spirit/include/karma_list.hpp>
 474
 475 Also, see __include_structure__.
 476
 477 [heading Model of]
 478
 479 [:__binary_generator_concept__]
 480
 481 [heading Expression Semantics]
 482
 483 Semantics of an expression is defined only where it differs from, or is not
 484 defined in __binary_generator_concept__.
 485
 486 [table
 487     [[Expression]       [Semantics]]
 488     [[`a % b`]          [The generator `a` is executed one or more times
 489                          depending on the availability of an attribute. The
 490                          output generated by `a` is interspersed with the output
 491                          generated by `b`. The list generator succeeds if
 492                          its first embedded generator has been
 493                          successfully executed at least once  (unless the
 494                          underlying output stream reports an error).]]
 495 ]
 496
 497 The list expression `a % b` is a shortcut for `a << *(b << a)`. It is almost
 498 semantically equivalent, except for the attribute of `b`, which gets ignored
 499 in the case of the list generator.
 500
 501 [note All failing iterations of the embedded generator will consume one element
 502       from the supplied attribute. The overall `a % b` will succeed as long as at
 503       least one invocation of the embedded generator, `a`, will succeed (unless
 504       the underlying output stream reports an error).]
 505
 506 [heading Attributes]
 507
 508 See __karma_comp_attr_notation__.
 509
 510 [table
 511     [[Expression]         [Attribute]]
 512     [[`a % b` (list)]
 513 [``a: A, b: B --> (a % b): vector<A>
 514 a: Unused, b: B --> (a % b): Unused``]]
 515 ]
 516
 517 [important The table above uses `vector<A>` as a placeholder only. The notation
 518            of `vector<A>` stands for /any STL container/ holding elements of
 519            type `A`.]
 520
 521 The list generator will execute its embedded generator once for each
 522 element in the provided container attribute and as long as the embedded
 523 generator succeeds. The output generated by its first generator will be
 524 interspersed by the output generated by the second generator. On each iteration
 525 it will pass the next consecutive element from the container attribute to the
 526 first embedded generator. The second embedded generator does not get passed
 527 any attributes (it gets invoked using an `unused_type` as its attribute).
 528 Therefore the number of iterations will not be larger than the number of
 529 elements in the container passed as its attribute. An empty container will make
 530 the list generator fail.
 531
 532 [tip    If you want to use the list generator and still allow for an empty
 533         attribute, you can use the optional operator (see __karma_optional__):
 534
 535         ``-(a % b)``
 536
 537         which will succeed even if the provided container attribute does not
 538         contain any elements.
 539 ]
 540
 541 [heading Complexity]
 542
 543 [:The overall complexity of the list generator is defined by the
 544   complexity of its embedded generators multiplied by the number of executed
 545   iterations. The complexity of the list generator itself is O(N), where N is
 546   the number of elements in the container passed as its attribute.]
 547
 548 [heading Example]
 549
 550 [note The test harness for the example(s) below is presented in the
 551       __karma_basics_examples__ section.]
 552
 553 Some includes:
 554
 555 [reference_karma_includes]
 556
 557 Some using declarations:
 558
 559 [reference_karma_using_declarations_list]
 560
 561 Basic usage of a list generator:
 562
 563 [reference_karma_list]
 564
 565 [endsect]
 566
 567 [/////////////////////////////////////////////////////////////////////////////]
 568 [section:optional Optional Generator (`-a`)]
 569
 570 [heading Description]
 571
 572 The optional generator is used to conditionally execute an embedded generator.
 573 It succeeds always.
 574
 575 [heading Header]
 576
 577     // forwards to <boost/spirit/home/karma/operator/optional.hpp>
 578     #include <boost/spirit/include/karma_optional.hpp>
 579
 580 Also, see __include_structure__.
 581
 582 [heading Model of]
 583
 584 [:__unary_generator_concept__]
 585
 586 [heading Expression Semantics]
 587
 588 Semantics of an expression is defined only where it differs from, or is not
 589 defined in __unary_generator_concept__.
 590
 591 [table
 592     [[Expression]       [Semantics]]
 593     [[`-a`]             [The generator `a` is executed depending on the
 594                          availability of an attribute. The optional generator
 595                          succeeds if its embedded generator succeeds
 596                          (unless the underlying output stream reports an
 597                          error).]]
 598 ]
 599
 600 [heading Attributes]
 601
 602 See __karma_comp_attr_notation__.
 603
 604 [table
 605     [[Expression]           [Attribute]]
 606     [[`-a` (optional, unary `-`)]
 607 [``a: A --> -a: optional<A>
 608 a: Unused --> -a: Unused``]]
 609 ]
 610
 611 [important The table above uses `optional<A>` as a placeholder only. The
 612            notation of `optional<A>` stands for the data type
 613            `boost::optional<A>`.]
 614
 615 The optional generator will execute its embedded generator once if the provided
 616 attribute holds a valid value. It forwards the value held in its attribute
 617 to the embedded generator.
 618
 619 It is important to note, that the optional generator does not perform any
 620 buffering of the output generated by its embedded elements. That means that any
 621 failing element might have already generated some output, which is /not/
 622 rolled back.
 623
 624 [tip    The simplest way to force a optional generator to behave as if it did
 625         buffering is to wrap it into a buffering directive (see
 626         __karma_buffer__):
 627
 628         ``buffer[-a]``
 629
 630         which will /not/ generate any output in case of a failing generator `-a`.
 631 ]
 632
 633 [heading Complexity]
 634
 635 [:The overall complexity of the optional generator is defined by the
 636   complexity of its embedded generator. The complexity of the optional
 637   generator itself is O(1).]
 638
 639 [heading Example]
 640
 641 [note The test harness for the example(s) below is presented in the
 642       __karma_basics_examples__ section.]
 643
 644 Some includes:
 645
 646 [reference_karma_includes]
 647
 648 Some using declarations:
 649
 650 [reference_karma_using_declarations_optional]
 651
 652 Basic usage of an optional generator:
 653
 654 [reference_karma_optional1]
 655
 656 Usage and result of an empty optional generator:
 657
 658 [reference_karma_optional2]
 659
 660 [endsect]
 661
 662 [/////////////////////////////////////////////////////////////////////////////]
 663 [section:and_predicate And-Predicate Generator (`&a`)]
 664
 665 [heading Description]
 666
 667 The and-predicate generator is used to test, whether the embedded generator
 668 succeeds without generating any output. It succeeds if the embedded generator
 669 succeeds.
 670
 671 [heading Header]
 672
 673     // forwards to <boost/spirit/home/karma/operator/and_predicate.hpp>
 674     #include <boost/spirit/include/karma_and_predicate.hpp>
 675
 676 Also, see __include_structure__.
 677
 678 [heading Model of]
 679
 680 [:__unary_generator_concept__]
 681
 682 [heading Expression Semantics]
 683
 684 Semantics of an expression is defined only where it differs from, or is not
 685 defined in __unary_generator_concept__.
 686
 687 [table
 688     [[Expression]       [Semantics]]
 689     [[`&a`]             [The generator `a` is executed for the sole purpose of
 690                          testing whether it succeeds. The and-predicate
 691                          generator succeeds if its embedded generator
 692                          succeeds (unless the underlying output stream
 693                          reports an error). The and-predicate never produces
 694                          any output.]]
 695 ]
 696
 697 The and generator is implemented by redirecting all output produced by its
 698 embedded generator into a discarding device.
 699
 700 [heading Attributes]
 701
 702 See __karma_comp_attr_notation__.
 703
 704 [table
 705     [[Expression]                 [Attribute]]
 706     [[`&a` (and-predicate, unary `&`)]  [`a: A --> &a: A`]]
 707 ]
 708
 709 [note The attribute of the and-predicate is not always `unused_type`, which is
 710       different from Qi's and-predicate. This is necessary as the generator the
 711       and predicate is attached to most of the time needs an attribute.
 712 ]
 713
 714 [heading Complexity]
 715
 716 [:The overall complexity of the and-predicate generator is defined by the
 717   complexity of its embedded generator. The complexity of the and-predicate
 718   generator itself is O(1).]
 719
 720 [heading Example]
 721
 722 [note The test harness for the example(s) below is presented in the
 723       __karma_basics_examples__ section.]
 724
 725 Some includes:
 726
 727 [reference_karma_includes]
 728
 729 Some using declarations:
 730
 731 [reference_karma_using_declarations_and_predicate]
 732
 733 Basic usage of an and predicate generator:
 734
 735 [reference_karma_and_predicate]
 736
 737 [endsect]
 738
 739 [/////////////////////////////////////////////////////////////////////////////]
 740 [section:not_predicate Not-Predicate Generator (`!a`)]
 741
 742 [heading Description]
 743
 744 The not-predicate generator is used to test, whether the embedded generator
 745 fails, without generating any output. It succeeds if the embedded generator
 746 fails.
 747
 748 [heading Header]
 749
 750     // forwards to <boost/spirit/home/karma/operator/not_predicate.hpp>
 751     #include <boost/spirit/include/karma_not_predicate.hpp>
 752
 753 Also, see __include_structure__.
 754
 755 [heading Model of]
 756
 757 [:__unary_generator_concept__]
 758
 759 [heading Expression Semantics]
 760
 761 Semantics of an expression is defined only where it differs from, or is not
 762 defined in __unary_generator_concept__.
 763
 764 [table
 765     [[Expression]       [Semantics]]
 766     [[`!a`]             [The generator `a` is executed for the sole purpose of
 767                          testing whether it succeeds. The not-predicate
 768                          generator succeeds if its embedded generator
 769                          fails (unless the underlying output stream
 770                          reports an error). The not-predicate never produces
 771                          any output.]]
 772 ]
 773
 774 The not generator is implemented by redirecting all output produced by its
 775 embedded generator into a discarding device.
 776
 777 [heading Attributes]
 778
 779 See __karma_comp_attr_notation__.
 780
 781 [table
 782     [[Expression]                 [Attribute]]
 783     [[`!a` (not-predicate, unary `!`)]  [`a: A --> !a: A`]]
 784 ]
 785
 786 [note The attribute of the not-predicate is not always `unused_type`, which is
 787       different from Qi's not-predicate. This is necessary as the generator the
 788       and-predicate is attached to most of the time needs an attribute.
 789 ]
 790
 791 [heading Complexity]
 792
 793 [:The overall complexity of the not-predicate generator is defined by the
 794   complexity of its embedded generator. The complexity of the not-predicate
 795   generator itself is O(1).]
 796
 797 [heading Example]
 798
 799 [note The test harness for the example(s) below is presented in the
 800       __karma_basics_examples__ section.]
 801
 802 Some includes:
 803
 804 [reference_karma_includes]
 805
 806 Some using declarations:
 807
 808 [reference_karma_using_declarations_not_predicate]
 809
 810 Basic usage of a not predicate generator:
 811
 812 [reference_karma_not_predicate]
 813
 814 [endsect]
 815
 816 [endsect]