ceph/src/boost/libs/spirit/doc/karma/auxiliary.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:auxiliary Auxiliary Generators]
  10
  11 This module includes different auxiliary generators not fitting into any of the
  12 other categories. It includes the `attr_cast`, `eol`, `eps`, and `lazy`
  13 generators.
  14
  15 [heading Module Header]
  16
  17     // forwards to <boost/spirit/home/karma/auxiliary.hpp>
  18     #include <boost/spirit/include/karma_auxiliary.hpp>
  19
  20 Also, see __include_structure__.
  21
  22 [/////////////////////////////////////////////////////////////////////////////]
  23 [section:attr_cast Attribute Transformation Pseudo Generator (`attr_cast`)]
  24
  25 [heading Description]
  26
  27 The `attr_cast<Exposed, Transformed>()` component invokes the embedded generator
  28 while supplying an attribute of type `Transformed`. The supplied attribute gets created
  29 from the original attribute (of type `Exposed`) passed to this component using the
  30 customization point __customize_transform_attribute__.
  31
  32
  33 [heading Header]
  34
  35     // forwards to <boost/spirit/home/karma/auxiliary/attr_cast.hpp>
  36     #include <boost/spirit/include/karma_attr_cast.hpp>
  37
  38 Also, see __include_structure__.
  39
  40 [heading Namespace]
  41
  42 [table
  43     [[Name]]
  44     [[`boost::spirit::attr_cast // alias: boost::spirit::karma::attr_cast`]]
  45 ]
  46
  47 [heading Synopsis]
  48
  49     template <Exposed, Transformed>
  50     <unspecified> attr_cast(<unspecified>);
  51
  52 [heading Template parameters]
  53
  54 [table
  55     [[Parameter]    [Description]                       [Default]]
  56     [[`Exposed`]    [The type of the attribute supplied to the `attr_cast`.] [__unused_type__]]
  57     [[`Transformed`][The type of the attribute expected by the embedded
  58                      generator `g`.]                    [__unused_type__]]
  59 ]
  60
  61 The `attr_cast` is a function template. It is possible to invoke it using the
  62 following schemes:
  63
  64     attr_cast(g)
  65     attr_cast<Exposed>(g)
  66     attr_cast<Exposed, Transformed>(g)
  67
  68 depending on which of the attribute types can be deduced properly if not
  69 explicitly specified.
  70
  71 [heading Model of]
  72
  73 [:__unary_generator_concept__]
  74
  75 [variablelist Notation
  76     [[`g`]          [A generator object.]]
  77 ]
  78
  79 [heading Expression Semantics]
  80
  81 Semantics of an expression is defined only where it differs from, or is
  82 not defined in __unary_generator_concept__.
  83
  84 [table
  85     [[Expression]             [Semantics]]
  86     [[`attr_cast(g)`]         [Create a component invoking the
  87                               generator `g` while passing an attribute of the type
  88                               as normally expected by `g`. The type of the supplied
  89                               attribute will be transformed to the type
  90                               `g` exposes as its attribute type (by using the
  91                               attribute customization point __customize_transform_attribute__).
  92                               This generator does not fail unless `g` fails.]]
  93     [[`attr_cast<Exposed>(g)`] [Create a component invoking the
  94                               generator `g` while passing an attribute of the type
  95                               as normally expected by `g`. The supplied attribute
  96                               is expected to be of the type `Exposed`, it will be
  97                               transformed to the type `g` exposes as its attribute type
  98                               (using the attribute customization point
  99                               __customize_transform_attribute__).
 100                               This generator does not fail unless `g` fails.]]
 101     [[`attr_cast<Exposed, Transformed>(g)`] [Create a component invoking the
 102                               generator `g` while passing an attribute of type
 103                               `Transformed`. The supplied attribute is expected
 104                               to be of the type `Exposed`, it will be transformed
 105                               to the type `Transformed` (using the attribute
 106                               customization point __customize_transform_attribute__).
 107                               This generator does not fail unless `g` fails.]]
 108 ]
 109
 110 [heading Attributes]
 111
 112 [table
 113     [[Expression]                             [Attribute]]
 114     [[`attr_cast(g)`]                         [`g: A --> attr_cast(g): A`]]
 115     [[`attr_cast<Exposed>(g)`] [`g: A --> attr_cast<Exposed>(g): Exposed`]]
 116     [[`attr_cast<Exposed, Transformed>(g)`]
 117                   [`g: A --> attr_cast<Exposed, Transformed>(g): Exposed`]]
 118 ]
 119
 120 [heading Complexity]
 121
 122 [:The complexity of this component is fully defined by the complexity of the
 123   embedded generator `g`.]
 124
 125 [heading Example]
 126
 127 [note The test harness for the example(s) below is presented in the
 128       __karma_basics_examples__ section.]
 129
 130 Some includes:
 131
 132 [reference_karma_includes]
 133
 134 Some using declarations:
 135
 136 [reference_karma_using_declarations_attr_cast]
 137
 138 The example references data structure `int_data` which needs a specialization of
 139 the customization point __customize_transform_attribute__:
 140
 141 [reference_karma_auxiliary_attr_cast_data1]
 142
 143 Now we use the `attr_cast` pseudo generator to invoke the attribute
 144 transformation:
 145
 146 [reference_karma_attr_cast1]
 147
 148 [endsect]
 149
 150 [/////////////////////////////////////////////////////////////////////////////]
 151 [section:eol End of Line Generator (`eol`)]
 152
 153 [heading Description]
 154
 155 The `eol` component generates a single newline character. It is equivalent
 156 to `lit('\n')` or simply '\\n' (please see the [karma_char `char_`] generator
 157 module for more details).
 158
 159 [heading Header]
 160
 161     // forwards to <boost/spirit/home/karma/auxiliary/eol.hpp>
 162     #include <boost/spirit/include/karma_eol.hpp>
 163
 164 Also, see __include_structure__.
 165
 166 [heading Namespace]
 167
 168 [table
 169     [[Name]]
 170     [[`boost::spirit::eol // alias: boost::spirit::karma::eol`]]
 171 ]
 172
 173 [heading Model of]
 174
 175 [:__primitive_generator_concept__]
 176
 177 [heading Expression Semantics]
 178
 179 Semantics of an expression is defined only where it differs from, or is
 180 not defined in __primitive_generator_concept__.
 181
 182 [table
 183     [[Expression]       [Semantics]]
 184     [[`eol`]            [Create a component generating a single end of line
 185                          character in the output. This generator never fails
 186                          (unless the underlying output stream reports an
 187                          error).]]
 188 ]
 189
 190 [heading Attributes]
 191
 192 [table
 193     [[Expression]       [Attribute]]
 194     [[`eol`]            [__unused__]]
 195 ]
 196
 197 [heading Complexity]
 198
 199 [:O(1)]
 200
 201 The complexity is constant as a single character is generated in the output.
 202
 203 [heading Example]
 204
 205 [note The test harness for the example(s) below is presented in the
 206       __karma_basics_examples__ section.]
 207
 208 Some includes:
 209
 210 [reference_karma_includes]
 211
 212 Some using declarations:
 213
 214 [reference_karma_using_declarations_eol]
 215
 216 Basic usage of the `eol` generator:
 217
 218 [reference_karma_eol]
 219
 220 [endsect]
 221
 222 [/////////////////////////////////////////////////////////////////////////////]
 223 [section:eps Epsilon Generator (`eps`)]
 224
 225 The family of `eps` components allows to create pseudo generators generating
 226 an empty string. This feature is sometimes useful either to force a generator
 227 to fail or to succeed or to insert semantic actions into the generation process.
 228
 229 [heading Description]
 230
 231 The Epsilon (`eps`) is a multi-purpose generator that emits a zero length
 232 string.
 233
 234 [heading Simple Form]
 235
 236 In its simplest form, `eps` creates a component generating an empty string
 237 while always succeeding:
 238
 239     eps       // always emits a zero-length string
 240
 241 This form is usually used to trigger a semantic action unconditionally.
 242 For example, it is useful in triggering error messages when a set of
 243 alternatives fail:
 244
 245     r = a | b | c | eps[error()]; // Call error if a, b, and c fail to generate
 246
 247 [heading Semantic Predicate]
 248
 249 The `eps(b)` component generates an empty string as well, but
 250 succeeds only if `b` is `true` and fails otherwise. It's lazy variant `eps(fb)`
 251 is equivalent to `eps(b)` except it evaluates the supplied function `fb` at
 252 generate time, while using the return value as the criteria to succeed.
 253
 254 Semantic predicates allow you to attach a conditional function anywhere
 255 in the grammar. In this role, the epsilon takes a __karma_lazy_argument__ that
 256 returns `true` or `false`. The __karma_lazy_argument__ is typically a test
 257 that is called to resolve ambiguity in the grammar. A generator failure will
 258 be reported when the __karma_lazy_argument__ result evaluates to `false`.
 259 Otherwise an empty string will be emitted. The general form is:
 260
 261     eps_p(fb) << rest;
 262
 263 The __karma_lazy_argument__ `fb` is called to do a semantic test. If the test
 264 returns true, `rest` will be evaluated. Otherwise, the production will return
 265 early without ever touching rest.
 266
 267 [heading Header]
 268
 269     // forwards to <boost/spirit/home/karma/auxiliary/eps.hpp>
 270     #include <boost/spirit/include/karma_eps.hpp>
 271
 272 Also, see __include_structure__.
 273
 274 [heading Namespace]
 275
 276 [table
 277     [[Name]]
 278     [[`boost::spirit::eps // alias: boost::spirit::karma::eps`]]
 279 ]
 280
 281 [heading Model of]
 282
 283 [:__primitive_generator_concept__]
 284
 285 [variablelist Notation
 286     [[`b`]      [A boolean value.]]
 287     [[`fb`]     [A __karma_lazy_argument__ that evaluates to a boolean value.]]
 288 ]
 289
 290 [heading Expression Semantics]
 291
 292 Semantics of an expression is defined only where it differs from, or is
 293 not defined in __primitive_generator_concept__.
 294
 295 [table
 296     [[Expression]       [Semantics]]
 297     [[`eps`]            [Creates a component generating an empty string.
 298                          Succeeds always.]]
 299     [[`eps(b)`]         [Creates a component generating an empty string.
 300                          Succeeds if `b` is `true` (unless the underlying
 301                          output stream reports an error).]]
 302     [[`eps(fb)`]        [Creates a component generating an empty string.
 303                          Succeeds if `fb` returns `true` at generate time
 304                          (unless the underlying output stream reports an
 305                          error).]]
 306 ]
 307
 308 [heading Attributes]
 309
 310 [table
 311     [[Expression]       [Attribute]]
 312     [[`eps`]            [__unused__]]
 313     [[`eps(b)`]         [__unused__]]
 314     [[`eps(fb)`]        [__unused__]]
 315 ]
 316
 317 [heading Complexity]
 318
 319 [:O(1)]
 320
 321 The complexity is constant as no output is generated.
 322
 323 [heading Example]
 324
 325 [note The test harness for the example(s) below is presented in the
 326       __karma_basics_examples__ section.]
 327
 328 Some includes:
 329
 330 [reference_karma_includes]
 331
 332 Some using declarations:
 333
 334 [reference_karma_using_declarations_eps]
 335
 336 Basic usage of the `eps` generator:
 337
 338 [reference_karma_eps]
 339
 340 [endsect]
 341
 342 [/////////////////////////////////////////////////////////////////////////////]
 343 [section:lazy Lazy Generator (`lazy`)]
 344
 345 [heading Description]
 346
 347 The family of `lazy` components allows to use a dynamically returned generator
 348 component for output generation. It calls the provided function or function
 349 object at generate time using its return value as the actual generator to
 350 produce the output.
 351
 352 [heading Header]
 353
 354     // forwards to <boost/spirit/home/karma/auxiliary/lazy.hpp>
 355     #include <boost/spirit/include/karma_lazy.hpp>
 356
 357 Also, see __include_structure__.
 358
 359 [heading Namespace]
 360
 361 [table
 362     [[Name]]
 363     [[`boost::spirit::lazy // alias: boost::spirit::karma::lazy`]]
 364 ]
 365
 366 [heading Model of]
 367
 368 [:__generator_concept__]
 369
 370 [variablelist Notation
 371     [[`fg`]       [A function or function object that evaluates to a generator
 372                    object (an object exposing the __generator_concept__). This
 373                    function will be invoked at generate time.]]
 374 ]
 375
 376 The signature of `fg` is expected to be
 377
 378     G f(Unused, Context)
 379
 380 where `G`, the function's return value, is the type of the generator to be
 381 invoked, and `Context` is the generator's __karma_context__ type (The
 382 first argument is __unused__ to make the `Context` the second argument. This
 383 is done for uniformity with __karma_actions__).
 384
 385 [heading Expression Semantics]
 386
 387 Semantics of an expression is defined only where it differs from, or is
 388 not defined in __generator_concept__.
 389
 390 [table
 391     [[Expression]       [Semantics]]
 392     [[`fg`]             [The __boost_phoenix__ function object `fg` will be
 393                          invoked at generate time. It is expected to return a
 394                          generator instance. This generator is then invoked
 395                          in order to generate the output. This generator will
 396                          succeed as long as the invoked generated succeeds as
 397                          well (unless the underlying output stream reports
 398                          an error).]]
 399     [[`lazy(fg)`]       [The function or function object will be invoked at
 400                          generate time. It is expected to return a generator
 401                          instance  (note this version of `lazy` does not
 402                          require `fg` to be a __boost_phoenix__ function
 403                          object). This generator is then invoked in order to
 404                          generate the output. This generator will succeed as
 405                          long as the invoked generated succeeds as well (except
 406                          if the underlying output stream reports an error).]]
 407 ]
 408
 409 [heading Attributes]
 410
 411 [table
 412     [[Expression]       [Attribute]]
 413     [[`fg`]             [The attribute type `G` as exposed by the generator `g`
 414                          returned from `fg`.]]
 415     [[`lazy(fg)`]       [The attribute type `G` as exposed by the generator `g`
 416                          returned from `fg`.]]
 417 ]
 418
 419 [heading Complexity]
 420
 421 The complexity of the `lazy` component is determined by the complexity of the
 422 generator returned from `fg`.
 423
 424 [heading Example]
 425
 426 [note The test harness for the example(s) below is presented in the
 427       __karma_basics_examples__ section.]
 428
 429 Some includes:
 430
 431 [reference_karma_includes]
 432
 433 Some using declarations:
 434
 435 [reference_karma_using_declarations_lazy]
 436
 437 Basic usage of the `lazy` generator:
 438
 439 [reference_karma_lazy]
 440
 441 [endsect]
 442
 443 [endsect]