[/==============================================================================
    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:auto Auto Generator]

[heading Description]

This module includes the description of the `auto_` generator. This generator 
can be used to automatically create a generator based on the supplied attribute 
type.

[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::auto_  // alias: boost::spirit::karma::auto_`]]
]

[heading Model of]

[:__primitive_generator_concept__]

[variablelist Notation
    [[`s`]      [A variable instance of any type for which a mapping to a 
                 generator type is defined (the meta function 
                 `traits::create_generator_exists` returns `mpl::true_`) or a 
                 __karma_lazy_argument__ that evaluates to any type for which 
                 a mapping to a generator type is defined (the meta function 
                 `traits::create_generator_exists` returns `mpl::true_`).]]
]

[heading Expression Semantics]

Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.

[table
    [[Expression]           [Description]]
    [[`auto_`]              [Create a generator instance compatible with the 
                             supplied attribute type and use it for output 
                             generation. This generator never fails 
                             (unless the underlying output stream reports an 
                             error).]]
    [[`auto_(s)`]           [Create a generator instance compatible with the
                             supplied literal value. This generator never fails 
                             (unless the underlying output stream reports an 
                             error).]]
]

[heading Additional Requirements]

The `auto_` generators can be used to emit output for any data type for which 
a mapping to a generator type is defined (the meta function 
`traits::create_generator_exists` returns `mpl::true_`). 
The following table outlines the predefined 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 (`'|'`)]]
]

It is possible to add support for any custom data type by implementing a 
specialization of the customization point __customize_create_generator__. This
customization can be used also to redefined any of the predefined mappings.

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`auto_`]              [`hold_any`, attribute is mandatory (otherwise 
                             compilation will fail)]]
    [[`auto_(s)`]           [__unused__]]
]

[important The attribute type `hold_any` exposed by some of the `auto_`
           generators is semantically and syntactically equivalent to 
           the type implemented by __boost_any__. It has been added to /Spirit/ 
           as it has better a performance and a smaller footprint if compared to 
           __boost_any__.
]

[note  In addition to their usual attribute of type `Attrib` all listed generators 
       accept an instance of a `boost::optional<Attrib>` as well. If the 
       `boost::optional<>` is initialized (holds a value) the generators behave 
       as if their attribute was an instance of `Attrib` and emit the value stored
       in the `boost::optional<>`. Otherwise the generators will fail.]

[heading Complexity]

[:The complexity of the `auto_` generator depends on the attribute type. Each 
 attribute type results in a different generator type to be instantiated which 
 defines the overall complexity.]

[heading Example]

[note The test harness for the example(s) below is presented in the
      __karma_basics_examples__ section.]

Some includes:

[reference_karma_includes]

Some using declarations:

[reference_karma_using_declarations_auto]

And a class definition used in the examples:

[reference_karma_complex]
[reference_karma_auto_complex]

Some usage examples of `auto_` generators:

[reference_karma_auto]

[endsect]