| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| ===============================================================================/] |
| [section:generate_api Generator API] |
| |
| [//////////////////////////////////////////////////////////////////////////////] |
| [section:iterator_api Iterator Based Generator API] |
| |
| [heading Description] |
| |
| The library provides a couple of free functions to make generating a snap. |
| These generator functions have two forms. The first form, `generate`, |
| concatenates the output generated by the involved components without inserting |
| any output in between. The second `generate_delimited` intersperses the output |
| generated by the involved components using the given delimiter generator. |
| Both versions can take in attributes by (constant) reference that hold the |
| attribute values to output. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/generate.hpp> |
| #include <boost/spirit/include/karma_generate.hpp> |
| |
| For variadic attributes: |
| |
| // forwards to <boost/spirit/home/karma/generate_attr.hpp> |
| #include <boost/spirit/include/karma_generate_attr.hpp> |
| |
| The variadic attributes version of the API allows one or more |
| attributes to be passed into the `generate` functions. The functions taking two |
| or more attributes are usable when the generator expression is a |
| __karma_sequence__ only. In this case each of the |
| attributes passed have to match the corresponding part of the sequence. |
| |
| For the API functions deducing the correct (matching) generator type from the |
| supplied attribute type: |
| |
| // forwards to <boost/spirit/home/karma/detail/generate_auto.hpp> |
| #include <boost/spirit/include/karma_generate_auto.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::karma::generate` ]] |
| [[`boost::spirit::karma::generate_delimited` ]] |
| [[`boost::spirit::karma::delimit_flag::predelimit` ]] |
| [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]] |
| ] |
| |
| [heading Synopsis] |
| |
| namespace boost { namespace spirit { namespace karma |
| { |
| template <typename OutputIterator, typename Expr> |
| inline bool |
| generate( |
| OutputIterator& sink |
| , Expr const& expr); |
| |
| template <typename OutputIterator, typename Expr |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline bool |
| generate( |
| OutputIterator& sink |
| , Expr const& expr |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| |
| template <typename OutputIterator, typename Expr, typename Delimiter> |
| inline bool |
| generate_delimited( |
| OutputIterator& sink |
| , Expr const& expr |
| , Delimiter const& delimiter |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); |
| |
| template <typename OutputIterator, typename Expr, typename Delimiter |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline bool |
| generate_delimited( |
| OutputIterator& sink |
| , Expr const& expr |
| , Delimiter const& delimiter |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| |
| template <typename OutputIterator, typename Expr, typename Delimiter |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline bool |
| generate_delimited( |
| OutputIterator& sink |
| , Expr const& expr |
| , Delimiter const& delimiter |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| }}} |
| |
| __karma__ generator API functions based on the automatic creation of the |
| matching generator type: |
| |
| namespace boost { namespace spirit { namespace karma |
| { |
| template <typename OutputIterator, typename Attr, typename Delimiter> |
| inline bool |
| generate_delimited( |
| OutputIterator& sink |
| , Attr const& attr |
| , Delimiter const& delimiter |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); |
| |
| template <typename OutputIterator, typename Attr> |
| inline bool |
| generate( |
| OutputIterator& sink |
| , Attr const& attr); |
| }}} |
| |
| All functions above return `true` if none of the involved generator components |
| failed, and `false` otherwise. If during the process of the output generation |
| the underlying output stream reports an error, the return value will be `false` |
| as well. |
| |
| The maximum number of supported arguments is limited by the preprocessor |
| constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined |
| by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). |
| |
| [note The variadic functions with two or more attributes internally combine |
| (constant) references to all passed attributes into a `fusion::vector` |
| and forward this as a combined attribute to the corresponding function |
| taking one attribute.] |
| |
| The `generate_delimited` functions not taking an explicit `delimit_flag` as one |
| of their arguments don't invoke the passed delimiter before starting to generate |
| output from the generator expression. This can be enabled by using the other |
| version of that function while passing `delimit_flag::predelimit` to the |
| corresponding argument. |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description]] |
| [[`OutputIterator`] [__outputiter__ receiving the generated output.]] |
| [[`Expr`] [An expression that can be converted to a Karma generator.]] |
| [[`Delimiter`] [Generator used to delimit the output of the expression components.]] |
| [[`Attr`] [An attribute type utilized to create the corresponding |
| generator type from.]] |
| [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]] |
| ] |
| |
| [endsect] [/ Iterator Based Generator API] |
| |
| [//////////////////////////////////////////////////////////////////////////////] |
| [section:stream_api Stream Based Generator API] |
| |
| [heading Description] |
| |
| The library provides a couple of Standard IO __iomanip__ allowing to integrate |
| __karma__ output generation facilities with Standard output streams. |
| These generator manipulators have two forms. The first form, `format`, |
| concatenates the output generated by the involved components without inserting |
| any output in between. The second, `format_delimited`, intersperses the output |
| generated by the involved components using the given delimiter generator. |
| Both versions can take in attributes by (constant) reference that hold the |
| attribute values to output. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/stream/format_manip.hpp> |
| #include <boost/spirit/include/karma_format.hpp> |
| |
| For variadic attributes: |
| |
| // forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp> |
| #include <boost/spirit/include/karma_format_attr.hpp> |
| |
| The variadic attributes version of the API allows one or more |
| attributes to be passed into the `format` manipulators. The manipulators taking |
| two or more attributes are usable when the generator expression is a |
| __karma_sequence__ only. In this case each of the attributes passed have to |
| match the corresponding part of the sequence. |
| |
| For the API functions deducing the correct (matching) generator type from the |
| supplied attribute type: |
| |
| // forwards to <boost/spirit/home/karma/format_auto.hpp> |
| #include <boost/spirit/include/karma_format_auto.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::karma::format` ]] |
| [[`boost::spirit::karma::format_delimited` ]] |
| [[`boost::spirit::karma::delimit_flag::predelimit` ]] |
| [[`boost::spirit::karma::delimit_flag::dont_predelimit` ]] |
| ] |
| |
| [heading Synopsis] |
| |
| namespace boost { namespace spirit { namespace karma |
| { |
| template <typename Expr> |
| inline <unspecified> |
| format( |
| Expr const& xpr); |
| |
| template <typename Expr |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline <unspecified> |
| format( |
| Expr const& xpr |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| |
| template <typename Expr, typename Delimiter> |
| inline <unspecified> |
| format_delimited( |
| Expr const& expr |
| , Delimiter const& d |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); |
| |
| template <typename Expr, typename Delimiter |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline <unspecified> |
| format_delimited( |
| Expr const& expr |
| , Delimiter const& d |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| |
| template <typename Expr, typename Delimiter |
| , typename Attr1, typename Attr2, ..., typename AttrN> |
| inline <unspecified> |
| format_delimited( |
| Expr const& expr |
| , Delimiter const& d |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit |
| , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); |
| }}} |
| |
| __karma__ generator API functions based on the automatic creation of the |
| matching generator type: |
| |
| namespace boost { namespace spirit { namespace karma |
| { |
| template <typename Attr, typename Delimiter> |
| inline <unspecified> |
| format_delimited( |
| Attr const& attr |
| , Delimiter const& d |
| , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); |
| |
| template <typename Attr> |
| inline <unspecified> |
| format( |
| Attr const& xpr); |
| }}} |
| |
| All functions above return a standard IO stream manipulator instance (see |
| __iomanip__), which when streamed to an output stream will result in generating |
| the output as emitted by the embedded __karma__ generator expression. Any error |
| occurring during the invocation of the __karma__ generators will be reflected |
| in the streams status flag (`std::ios_base::failbit` will be set). |
| |
| The maximum number of supported arguments is limited by the preprocessor |
| constant `SPIRIT_ARGUMENTS_LIMIT`. This constant defaults to the value defined |
| by the preprocessor constant `PHOENIX_LIMIT` (which in turn defaults to `10`). |
| |
| [note The variadic manipulators with two or more attributes internally combine |
| (constant) references to all passed attributes into a `fusion::vector` |
| and forward this as a combined attribute to the corresponding manipulator |
| taking one attribute.] |
| |
| The `format_delimited` manipulators not taking an explicit `delimit_flag` as one |
| of their arguments don't invoke the passed delimiter before starting to generate |
| output from the generator expression. This can be enabled by using the other |
| version of that manipulator while passing `delimit_flag::predelimit` to the |
| corresponding argument. |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description]] |
| [[`Expr`] [An expression that can be converted to a Karma generator.]] |
| [[`Delimiter`] [Generator used to delimit the output of the expression components.]] |
| [[`Attr`] [An attribute type utilized to create the corresponding |
| generator type from.]] |
| [[`Attr1`, `Attr2`, ..., `AttrN`][One or more attributes.]] |
| ] |
| |
| [endsect] [/ Stream Based Generator API] |
| |
| [//////////////////////////////////////////////////////////////////////////////] |
| [section:create_generator API for Automatic Generator Creation] |
| |
| [heading Description] |
| |
| The library implements a special API returning a generator instance for a |
| supplied attribute type. This function finds the best matching generator type |
| for the attribute based on a set of simple matching rules (as outlined in the |
| table below) applied recursively to the attribute type. The returned generator |
| can be utilized to emit output for the provided attribute. |
| |
| [heading Header] |
| |
| // forwards to <boost/spirit/home/karma/auto.hpp> |
| #include <boost/spirit/include/karma_auto.hpp> |
| |
| Also, see __include_structure__. |
| |
| [heading Namespace] |
| |
| [table |
| [[Name]] |
| [[`boost::spirit::karma::create_generator`]] |
| [[`boost::spirit::traits::create_generator_exists`]] |
| ] |
| |
| [heading Synopsis] |
| |
| namespace boost { namespace spirit { namespace karma |
| { |
| template <typename Attr> |
| inline <unspecified> |
| create_generator(); |
| }}} |
| |
| The returned instance can be directly passed as the generator (or the |
| delimiting generator) to any of the __karma__ API functions. Additionally it |
| can be assigned to a rule as the rules right hand side expression. This |
| function will return a valid generator type only if the meta function |
| `traits::create_generator_exists` returns `mpl::true_`. Otherwise it will fail |
| compiling. |
| |
| namespace boost { namespace spirit { namespace traits |
| { |
| template <typename Attr> |
| struct create_generator_exists; |
| }}} |
| |
| The meta function evaluates to `mpl::true_` if `create_generator` would return |
| a valid generator for the given type `Attr`. |
| |
| The following table outlines the mapping rules from the attribute type to the |
| generator type. These rules are applied recursively to create the generator |
| type which can be used to generate output from the given attribute type. |
| |
| [table |
| [[Attribute type] [Generator type]] |
| [[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]] |
| [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] |
| [[`unsigned short`, `unsigned int`, `unsigned long`] |
| [`ushort_`, `uint_`, `ulong_`]] |
| [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]] |
| [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] |
| [[`long long`, `unsigned long long`] |
| [`long_long`, `ulong_long`]] |
| [[`bool`] [`bool_`]] |
| [[Any string (`char const*`, `std::string`, etc.)] |
| [`string`]] |
| [[Any (STL) container] [Kleene Star (unary `'*'`)]] |
| [[Any Fusion sequence] [Sequence operator (`'<<'`)]] |
| [[`boost::optional<>`] [Optional operator (unary `'-'`)]] |
| [[`boost::variant<>`] [Alternative operator (`'|'`)]] |
| ] |
| |
| [important The mapping for the generators `long_long` and `ulong_long` are only |
| available on platforms where the preprocessor constant |
| `BOOST_HAS_LONG_LONG` is defined (i.e. on platforms having native |
| support for `long long` and `unsigned long long` (64 bit) signed and |
| unsigned integer types).] |
| |
| [heading Template parameters] |
| |
| [table |
| [[Parameter] [Description]] |
| [[`Attr`] [An attribute type utilized to create the corresponding |
| generator type from.]] |
| ] |
| |
| [endsect] [/ API for Automatic Generator Creation] |
| |
| [endsect] |
