395 lines
15 KiB
Plaintext
395 lines
15 KiB
Plaintext
[/==============================================================================
|
|
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 <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);
|
|
}}}
|
|
|
|
[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 <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]
|