1[/============================================================================== 2 Copyright (C) 2001-2011 Joel de Guzman 3 Copyright (C) 2001-2011 Hartmut Kaiser 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section:auto Auto Generator] 10 11[heading Description] 12 13This module includes the description of the `auto_` generator. This generator 14can be used to automatically create a generator based on the supplied attribute 15type. 16 17[heading Header] 18 19 // forwards to <boost/spirit/home/karma/auto.hpp> 20 #include <boost/spirit/include/karma_auto.hpp> 21 22Also, see __include_structure__. 23 24[heading Namespace] 25 26[table 27 [[Name]] 28 [[`boost::spirit::auto_ // alias: boost::spirit::karma::auto_`]] 29] 30 31[heading Model of] 32 33[:__primitive_generator_concept__] 34 35[variablelist Notation 36 [[`s`] [A variable instance of any type for which a mapping to a 37 generator type is defined (the meta function 38 `traits::create_generator_exists` returns `mpl::true_`) or a 39 __karma_lazy_argument__ that evaluates to any type for which 40 a mapping to a generator type is defined (the meta function 41 `traits::create_generator_exists` returns `mpl::true_`).]] 42] 43 44[heading Expression Semantics] 45 46Semantics of an expression is defined only where it differs from, or is 47not defined in __primitive_generator_concept__. 48 49[table 50 [[Expression] [Description]] 51 [[`auto_`] [Create a generator instance compatible with the 52 supplied attribute type and use it for output 53 generation. This generator never fails 54 (unless the underlying output stream reports an 55 error).]] 56 [[`auto_(s)`] [Create a generator instance compatible with the 57 supplied literal value. This generator never fails 58 (unless the underlying output stream reports an 59 error).]] 60] 61 62[heading Additional Requirements] 63 64The `auto_` generators can be used to emit output for any data type for which 65a mapping to a generator type is defined (the meta function 66`traits::create_generator_exists` returns `mpl::true_`). 67The following table outlines the predefined mapping rules from the attribute type 68to the generator type. These rules are applied recursively to create the generator 69type which can be used to generate output from the given attribute type. 70 71[table 72 [[Attribute type] [Generator type]] 73 [[`char`, `wchar_t`] [`standard::char_`, `standard_wide::char_`]] 74 [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] 75 [[`unsigned short`, `unsigned int`, `unsigned long`] 76 [`ushort_`, `uint_`, `ulong_`]] 77 [[`float`, `double`, `long double`] [`float_`, `double_`, `long_double`]] 78 [[`short`, `int`, `long`] [`short_`, `int_`, `long_`]] 79 [[`long long`, `unsigned long long`] 80 [`long_long`, `ulong_long`]] 81 [[`bool`] [`bool_`]] 82 [[Any string (`char const*`, `std::string`, etc.)] 83 [`string`]] 84 [[Any (STL) container] [Kleene Star (unary `'*'`)]] 85 [[Any Fusion sequence] [Sequence operator (`'<<'`)]] 86 [[`boost::optional<>`] [Optional operator (unary `'-'`)]] 87 [[`boost::variant<>`] [Alternative operator (`'|'`)]] 88] 89 90It is possible to add support for any custom data type by implementing a 91specialization of the customization point __customize_create_generator__. This 92customization can be used also to redefined any of the predefined mappings. 93 94[heading Attributes] 95 96[table 97 [[Expression] [Attribute]] 98 [[`auto_`] [`hold_any`, attribute is mandatory (otherwise 99 compilation will fail)]] 100 [[`auto_(s)`] [__unused__]] 101] 102 103[important The attribute type `hold_any` exposed by some of the `auto_` 104 generators is semantically and syntactically equivalent to 105 the type implemented by __boost_any__. It has been added to /Spirit/ 106 as it has better a performance and a smaller footprint if compared to 107 __boost_any__. 108] 109 110[note In addition to their usual attribute of type `Attrib` all listed generators 111 accept an instance of a `boost::optional<Attrib>` as well. If the 112 `boost::optional<>` is initialized (holds a value) the generators behave 113 as if their attribute was an instance of `Attrib` and emit the value stored 114 in the `boost::optional<>`. Otherwise the generators will fail.] 115 116[heading Complexity] 117 118[:The complexity of the `auto_` generator depends on the attribute type. Each 119 attribute type results in a different generator type to be instantiated which 120 defines the overall complexity.] 121 122[heading Example] 123 124[note The test harness for the example(s) below is presented in the 125 __karma_basics_examples__ section.] 126 127Some includes: 128 129[reference_karma_includes] 130 131Some using declarations: 132 133[reference_karma_using_declarations_auto] 134 135And a class definition used in the examples: 136 137[reference_karma_complex] 138[reference_karma_auto_complex] 139 140Some usage examples of `auto_` generators: 141 142[reference_karma_auto] 143 144[endsect] 145 146