[/============================================================================== Copyright (C) 2001-2011 Joel de Guzman Copyright (C) 2001-2011 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 #include For variadic attributes: // forwards to #include 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 #include 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 inline bool generate( OutputIterator& sink , Expr const& expr); template inline bool generate( OutputIterator& sink , Expr const& expr , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template inline bool generate_delimited( OutputIterator& sink , Expr const& expr , Delimiter const& delimiter , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template inline bool generate_delimited( OutputIterator& sink , Expr const& expr , Delimiter const& delimiter , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template 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); }}} [note Starting with __spirit__ V2.5 (distributed with Boost V1.47) the placeholder `_val` can be used in semantic actions attached to top level generator components. In this case `_val` refers to the supplied attribute as a whole. For API functions taking more than one attribute argument `_val` will refer to a Fusion vector or references to the attributes.] __karma__ generator API functions based on the automatic creation of the matching generator type: namespace boost { namespace spirit { namespace karma { template inline bool generate_delimited( OutputIterator& sink , Attr const& attr , Delimiter const& delimiter , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template 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 #include For variadic attributes: // forwards to #include 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 #include 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 inline format( Expr const& xpr); template inline format( Expr const& xpr , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template inline format_delimited( Expr const& expr , Delimiter const& d , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template inline format_delimited( Expr const& expr , Delimiter const& d , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template inline 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 inline format_delimited( Attr const& attr , Delimiter const& d , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template inline 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 #include 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 inline 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 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]