ceph/src/boost/libs/spirit/doc/karma/directive.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: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]