]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
13 | This module includes the description of the `auto_` generator. This generator | |
14 | can be used to automatically create a generator based on the supplied attribute | |
15 | type. | |
16 | ||
17 | [heading Header] | |
18 | ||
19 | // forwards to <boost/spirit/home/karma/auto.hpp> | |
20 | #include <boost/spirit/include/karma_auto.hpp> | |
21 | ||
22 | Also, 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 | ||
46 | Semantics of an expression is defined only where it differs from, or is | |
47 | not 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 | ||
64 | The `auto_` generators can be used to emit output for any data type for which | |
65 | a mapping to a generator type is defined (the meta function | |
66 | `traits::create_generator_exists` returns `mpl::true_`). | |
67 | The following table outlines the predefined mapping rules from the attribute type | |
68 | to the generator type. These rules are applied recursively to create the generator | |
69 | type 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 | ||
90 | It is possible to add support for any custom data type by implementing a | |
91 | specialization of the customization point __customize_create_generator__. This | |
92 | customization 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 | ||
127 | Some includes: | |
128 | ||
129 | [reference_karma_includes] | |
130 | ||
131 | Some using declarations: | |
132 | ||
133 | [reference_karma_using_declarations_auto] | |
134 | ||
135 | And a class definition used in the examples: | |
136 | ||
137 | [reference_karma_complex] | |
138 | [reference_karma_auto_complex] | |
139 | ||
140 | Some usage examples of `auto_` generators: | |
141 | ||
142 | [reference_karma_auto] | |
143 | ||
144 | [endsect] | |
145 |