libs/spirit/doc/qi/auto.qbk
[/==============================================================================
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]
