1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
[/==============================================================================
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]
|
