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

[heading Description]

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

[heading Header]

    // forwards to <boost/spirit/home/qi/auto.hpp>
    #include <boost/spirit/include/qi_auto.hpp>

Also, see __include_structure__.

[heading Namespace]

[table
    [[Name]]
    [[`boost::spirit::auto_  // alias: boost::spirit::qi::auto_`]]
]

[heading Model of]

[:__primitive_parser_concept__]

[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 parser instance compatible with the 
                             supplied attribute type and use it for input
                             matching.]]
]

[heading Additional Requirements]

The `auto_` parsers can be used to match input for any data type for which 
a mapping to a parser type is defined (the meta function 
`traits::create_parser_exists` returns `mpl::true_`). 
The following table outlines the predefined mapping rules from the attribute 
type to the parser type. These rules are applied recursively to create the parser
type which can be used to match input for the given attribute type.

[table 
    [[Attribute type]   [Parser 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`]]
    [[`long long`, `unsigned long long`]
                              [`long_long`, `ulong_long`]]
    [[`bool`]                 [`bool_`]]
    [[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_parser__. This
customization can be used also to redefined any of the predefined mappings.

[heading Attributes]

[table
    [[Expression]           [Attribute]]
    [[`auto_`]              [`hold_any`]]
]

[important The attribute type `hold_any` exposed by the `auto_`
           parser 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__.
]

[heading Complexity]

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

[heading Example]

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

Some includes:

[reference_includes]

Some using declarations:

[reference_qi_using_declarations_auto]

And a class definition used in the examples:

[reference_qi_complex]
[reference_qi_auto_complex]

Some usage examples of `auto_` parsers:

[reference_qi_auto]

[endsect]