123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394 |
- [/==============================================================================
- 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]
|