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

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   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 [section:generate_api Generator API]
   9
  10 [//////////////////////////////////////////////////////////////////////////////]
  11 [section:iterator_api Iterator Based Generator API]
  12
  13 [heading Description]
  14
  15 The library provides a couple of free functions to make generating a snap.
  16 These generator functions have two forms. The first form, `generate`,
  17 concatenates the output generated by the involved components without inserting
  18 any output in between. The second `generate_delimited` intersperses the output
  19 generated by the involved components using the given delimiter generator.
  20 Both versions can take in attributes by (constant) reference that hold the
  21 attribute values to output.
  22
  23 [heading Header]
  24
  25     // forwards to <boost/spirit/home/karma/generate.hpp>
  26     #include <boost/spirit/include/karma_generate.hpp>
  27
  28 For variadic attributes:
  29
  30     // forwards to <boost/spirit/home/karma/generate_attr.hpp>
  31     #include <boost/spirit/include/karma_generate_attr.hpp>
  32
  33 The variadic attributes version of the API allows one or more
  34 attributes to be passed into the `generate` functions. The functions taking two
  35 or more attributes are usable when the generator expression is a
  36 __karma_sequence__ only. In this case each of the
  37 attributes passed have to match the corresponding part of the sequence.
  38
  39 For the API functions deducing the correct (matching) generator type from the
  40 supplied attribute type:
  41
  42     // forwards to <boost/spirit/home/karma/detail/generate_auto.hpp>
  43     #include <boost/spirit/include/karma_generate_auto.hpp>
  44
  45 Also, see __include_structure__.
  46
  47 [heading Namespace]
  48
  49 [table
  50     [[Name]]
  51     [[`boost::spirit::karma::generate` ]]
  52     [[`boost::spirit::karma::generate_delimited` ]]
  53     [[`boost::spirit::karma::delimit_flag::predelimit` ]]
  54     [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
  55 ]
  56
  57 [heading Synopsis]
  58
  59     namespace boost { namespace spirit { namespace karma
  60     {
  61         template <typename OutputIterator, typename Expr>
  62         inline bool
  63         generate(
  64             OutputIterator& sink
  65           , Expr const& expr);
  66
  67         template <typename OutputIterator, typename Expr
  68           , typename Attr1, typename Attr2, ..., typename AttrN>
  69         inline bool
  70         generate(
  71             OutputIterator& sink
  72           , Expr const& expr
  73           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
  74
  75         template <typename OutputIterator, typename Expr, typename Delimiter>
  76         inline bool
  77         generate_delimited(
  78             OutputIterator& sink
  79           , Expr const& expr
  80           , Delimiter const& delimiter
  81           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
  82
  83         template <typename OutputIterator, typename Expr, typename Delimiter
  84           , typename Attr1, typename Attr2, ..., typename AttrN>
  85         inline bool
  86         generate_delimited(
  87             OutputIterator& sink
  88           , Expr const& expr
  89           , Delimiter const& delimiter
  90           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
  91
  92         template <typename OutputIterator, typename Expr, typename Delimiter
  93           , typename Attr1, typename Attr2, ..., typename AttrN>
  94         inline bool
  95         generate_delimited(
  96             OutputIterator& sink
  97           , Expr const& expr
  98           , Delimiter const& delimiter
  99           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
 100           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
 101     }}}
 102
 103 [note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the
 104       placeholder `_val` can be used in semantic actions attached to top level
 105       generator components. In this case `_val` refers to the supplied attribute
 106       as a whole. For API functions taking more than one attribute argument
 107       `_val` will refer to a Fusion vector or references to the attributes.]
 108
 109 __karma__ generator API functions based on the automatic creation of the
 110 matching generator type:
 111
 112     namespace boost { namespace spirit { namespace karma
 113     {
 114         template <typename OutputIterator, typename Attr, typename Delimiter>
 115         inline bool
 116         generate_delimited(
 117             OutputIterator& sink
 118           , Attr const& attr
 119           , Delimiter const& delimiter
 120           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
 121
 122         template <typename OutputIterator, typename Attr>
 123         inline bool
 124         generate(
 125             OutputIterator& sink
 126           , Attr const& attr);
 127     }}}
 128
 129 All functions above return `true` if none of the involved generator components
 130 failed, and `false` otherwise. If during the process of the output generation
 131 the underlying output stream reports an error, the return value will be `false`
 132 as well.
 133
 134 The maximum number of supported arguments is limited by the preprocessor
 135 constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
 136 by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
 137
 138 [note The variadic functions with two or more attributes internally combine
 139       (constant) references to all passed attributes into a `fusion::vector`
 140       and forward this as a combined attribute to the corresponding function
 141       taking one attribute.]
 142
 143 The `generate_delimited` functions not taking an explicit `delimit_flag` as one
 144 of their arguments don't invoke the passed delimiter before starting to generate
 145 output from the generator expression. This can be enabled by using the other
 146 version of that function while passing `delimit_flag::predelimit` to the
 147 corresponding argument.
 148
 149 [heading Template parameters]
 150
 151 [table
 152     [[Parameter]                    [Description]]
 153     [[`OutputIterator`]             [__outputiter__ receiving the generated output.]]
 154     [[`Expr`]                       [An expression that can be converted to a Karma generator.]]
 155     [[`Delimiter`]                  [Generator used to delimit the output of the expression components.]]
 156     [[`Attr`]                       [An attribute type utilized to create the corresponding
 157                                      generator type from.]]
 158     [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
 159 ]
 160
 161 [endsect] [/ Iterator Based Generator API]
 162
 163 [//////////////////////////////////////////////////////////////////////////////]
 164 [section:stream_api Stream Based Generator API]
 165
 166 [heading Description]
 167
 168 The library provides a couple of Standard IO __iomanip__ allowing to integrate
 169 __karma__ output generation facilities with Standard output streams.
 170 These generator manipulators have two forms. The first form, `format`,
 171 concatenates the output generated by the involved components without inserting
 172 any output in between. The second, `format_delimited`, intersperses the output
 173 generated by the involved components using the given delimiter generator.
 174 Both versions can take in attributes by (constant) reference that hold the
 175 attribute values to output.
 176
 177 [heading Header]
 178
 179     // forwards to <boost/spirit/home/karma/stream/format_manip.hpp>
 180     #include <boost/spirit/include/karma_format.hpp>
 181
 182 For variadic attributes:
 183
 184     // forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp>
 185     #include <boost/spirit/include/karma_format_attr.hpp>
 186
 187 The variadic attributes version of the API allows one or more
 188 attributes to be passed into the `format` manipulators. The manipulators taking
 189 two or more attributes are usable when the generator expression is a
 190 __karma_sequence__ only. In this case each of the attributes passed have to
 191 match the corresponding part of the sequence.
 192
 193 For the API functions deducing the correct (matching) generator type from the
 194 supplied attribute type:
 195
 196     // forwards to <boost/spirit/home/karma/format_auto.hpp>
 197     #include <boost/spirit/include/karma_format_auto.hpp>
 198
 199 Also, see __include_structure__.
 200
 201 [heading Namespace]
 202
 203 [table
 204     [[Name]]
 205     [[`boost::spirit::karma::format` ]]
 206     [[`boost::spirit::karma::format_delimited` ]]
 207     [[`boost::spirit::karma::delimit_flag::predelimit` ]]
 208     [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]]
 209 ]
 210
 211 [heading Synopsis]
 212
 213     namespace boost { namespace spirit { namespace karma
 214     {
 215         template <typename Expr>
 216         inline <unspecified>
 217         format(
 218             Expr const& xpr);
 219
 220         template <typename Expr
 221           , typename Attr1, typename Attr2, ..., typename AttrN>
 222         inline <unspecified>
 223         format(
 224             Expr const& xpr
 225           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
 226
 227         template <typename Expr, typename Delimiter>
 228         inline <unspecified>
 229         format_delimited(
 230             Expr const& expr
 231           , Delimiter const& d
 232           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
 233
 234         template <typename Expr, typename Delimiter
 235           , typename Attr1, typename Attr2, ..., typename AttrN>
 236         inline <unspecified>
 237         format_delimited(
 238             Expr const& expr
 239           , Delimiter const& d
 240           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
 241
 242         template <typename Expr, typename Delimiter
 243           , typename Attr1, typename Attr2, ..., typename AttrN>
 244         inline <unspecified>
 245         format_delimited(
 246             Expr const& expr
 247           , Delimiter const& d
 248           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
 249           , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);
 250     }}}
 251
 252 __karma__ generator API functions based on the automatic creation of the
 253 matching generator type:
 254
 255     namespace boost { namespace spirit { namespace karma
 256     {
 257         template <typename Attr, typename Delimiter>
 258         inline <unspecified>
 259         format_delimited(
 260             Attr const& attr
 261           , Delimiter const& d
 262           , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);
 263
 264         template <typename Attr>
 265         inline <unspecified>
 266         format(
 267             Attr const& xpr);
 268     }}}
 269
 270 All functions above return a standard IO stream manipulator instance (see
 271 __iomanip__), which when streamed to an output stream will result in generating
 272 the output as emitted by the embedded __karma__ generator expression. Any error
 273 occurring during the invocation of the __karma__ generators will be reflected
 274 in the streams status flag (`std::ios_base::failbit` will be set).
 275
 276 The maximum number of supported arguments is limited by the preprocessor
 277 constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined
 278 by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`).
 279
 280 [note The variadic manipulators with two or more attributes internally combine
 281       (constant) references to all passed attributes into a `fusion::vector`
 282       and forward this as a combined attribute to the corresponding manipulator
 283       taking one attribute.]
 284
 285 The `format_delimited` manipulators not taking an explicit `delimit_flag` as one
 286 of their arguments don't invoke the passed delimiter before starting to generate
 287 output from the generator expression. This can be enabled by using the other
 288 version of that manipulator while passing `delimit_flag::predelimit` to the
 289 corresponding argument.
 290
 291 [heading Template parameters]
 292
 293 [table
 294     [[Parameter]                    [Description]]
 295     [[`Expr`]                       [An expression that can be converted to a Karma generator.]]
 296     [[`Delimiter`]                  [Generator used to delimit the output of the expression components.]]
 297     [[`Attr`]                       [An attribute type utilized to create the corresponding
 298                                      generator type from.]]
 299     [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]]
 300 ]
 301
 302 [endsect] [/ Stream Based Generator API]
 303
 304 [//////////////////////////////////////////////////////////////////////////////]
 305 [section:create_generator API for Automatic Generator Creation]
 306
 307 [heading Description]
 308
 309 The library implements a special API returning a generator instance for a
 310 supplied attribute type. This function finds the best matching generator type
 311 for the attribute based on a set of simple matching rules (as outlined in the
 312 table below) applied recursively to the attribute type. The returned generator
 313 can be utilized to emit output for the provided attribute.
 314
 315 [heading Header]
 316
 317     // forwards to <boost/spirit/home/karma/auto.hpp>
 318     #include <boost/spirit/include/karma_auto.hpp>
 319
 320 Also, see __include_structure__.
 321
 322 [heading Namespace]
 323
 324 [table
 325     [[Name]]
 326     [[`boost::spirit::karma::create_generator`]]
 327     [[`boost::spirit::traits::create_generator_exists`]]
 328 ]
 329
 330 [heading Synopsis]
 331
 332     namespace boost { namespace spirit { namespace karma
 333     {
 334         template <typename Attr>
 335         inline <unspecified>
 336         create_generator();
 337     }}}
 338
 339 The returned instance can be directly passed as the generator (or the
 340 delimiting generator) to any of the __karma__ API functions. Additionally it
 341 can be assigned to a rule as the rules right hand side expression. This
 342 function will return a valid generator type only if the meta function
 343 `traits::create_generator_exists` returns `mpl::true_`. Otherwise it will fail
 344 compiling.
 345
 346     namespace boost { namespace spirit { namespace traits
 347     {
 348         template <typename Attr>
 349         struct create_generator_exists;
 350     }}}
 351
 352 The meta function evaluates to `mpl::true_` if `create_generator` would return
 353 a valid generator for the given type `Attr`.
 354
 355 The following table outlines the mapping rules from the attribute type to the
 356 generator type. These rules are applied recursively to create the generator
 357 type which can be used to generate output from the given attribute type.
 358
 359 [table
 360     [[Attribute type]   [Generator type]]
 361     [[`char`, `wchar_t`]      [`standard::char_`, `standard_wide::char_`]]
 362     [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
 363     [[`unsigned short`, `unsigned int`, `unsigned long`]
 364                               [`ushort_`, `uint_`, `ulong_`]]
 365     [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]]
 366     [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]]
 367     [[`long long`, `unsigned long long`]
 368                               [`long_long`, `ulong_long`]]
 369     [[`bool`]                 [`bool_`]]
 370     [[Any string (`char const*`, `std::string`, etc.)]
 371                               [`string`]]
 372     [[Any (STL) container]    [Kleene Star (unary `'*'`)]]
 373     [[Any Fusion sequence]    [Sequence operator (`'<<'`)]]
 374     [[`boost::optional<>`]    [Optional operator (unary `'-'`)]]
 375     [[`boost::variant<>`]     [Alternative operator (`'|'`)]]
 376 ]
 377
 378 [important The mapping for the generators `long_long` and `ulong_long` are only
 379         available on platforms where the preprocessor constant
 380         `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native
 381         support for `long long` and `unsigned long long` (64 bit) signed and
 382         unsigned integer types).]
 383
 384 [heading Template parameters]
 385
 386 [table
 387     [[Parameter]                    [Description]]
 388     [[`Attr`]                       [An attribute type utilized to create the corresponding
 389                                      generator type from.]]
 390 ]
 391
 392 [endsect] [/ API for Automatic Generator Creation]
 393
 394 [endsect]