Project

General

Profile

Fhiclcpp types in detail » History » Version 32

Kyle Knoepfel, 11/17/2015 01:23 PM

1 1 Kyle Knoepfel
h1. @fhiclcpp@ types in detail
2 1 Kyle Knoepfel
3 20 Kyle Knoepfel
* [[Fhiclcpp_types_in_detail#ctors|Parameter constructors]]
4 16 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#ctors_rules|General rules]]
5 14 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#atom|Atom<T>]]
6 14 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#vector|Sequence<T>]]
7 14 Kyle Knoepfel
*** [[Fhiclcpp_types_in_detail#make_empty|make_empty()]]
8 27 Kyle Knoepfel
*** [[Fhiclcpp_types_in_detail#narrowing|Caveat regarding narrowing conversions]]
9 14 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#array|Sequence<T,std::size_t>]]
10 14 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#tuple|Tuple<T...>]]
11 14 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#table|Table<T>]]
12 9 Kyle Knoepfel
* [[Fhiclcpp_types_in_detail#return|Return types]]
13 22 Kyle Knoepfel
* [[Fhiclcpp_types_in_detail#table_func|Additional functions for Table<T>]]
14 22 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#get_pset|get_PSet]]
15 22 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#print|print_allowed_configuration]]
16 23 Kyle Knoepfel
** [[Fhiclcpp_types_in_detail#validate|validate_ParameterSet (*expert*)]]
17 14 Kyle Knoepfel
* [[Fhiclcpp_types_in_detail#common_acc|Common parameter accessors]]
18 1 Kyle Knoepfel
19 9 Kyle Knoepfel
----
20 9 Kyle Knoepfel
21 17 Kyle Knoepfel
h1(#ctors). Parameter constructors
22 1 Kyle Knoepfel
23 18 Kyle Knoepfel
h2(#ctors_rules). %{color:blue}General rules%
24 1 Kyle Knoepfel
25 1 Kyle Knoepfel
For each of the @fhiclcpp@ types, the following rules apply:
26 12 Kyle Knoepfel
* The @Name@ argument is required.
27 12 Kyle Knoepfel
* If there is more than one argument, the @Name@ argument must be first in the list.
28 12 Kyle Knoepfel
* If there are three arguments, the relative order of the @Comment@ argument and default-value argument is not important.
29 12 Kyle Knoepfel
<pre><code class="cpp">
30 12 Kyle Knoepfel
Atom<int> val { Name("val"), Comment("Some parameter"), 9 }; // is equivalent to
31 12 Kyle Knoepfel
Atom<int> val { Name("val"), 9, Comment("Some parameter") };
32 12 Kyle Knoepfel
</code></pre>
33 32 Kyle Knoepfel
* Neither the @Table<T>@ parameter nor any of the @Optional*@ parameters support a default value.
34 1 Kyle Knoepfel
35 18 Kyle Knoepfel
h2(#atom). %{color:blue}@Atom<T>@%
36 7 Kyle Knoepfel
37 1 Kyle Knoepfel
<pre><code class="cpp">
38 1 Kyle Knoepfel
Atom<int> var { Name("var") };
39 1 Kyle Knoepfel
Atom<int> var { Name("var"), 9 };
40 7 Kyle Knoepfel
Atom<int> var { Name("var"), Comment("A parameter description") };
41 1 Kyle Knoepfel
Atom<int> var { Name("var"), Comment("A parameter description"), 9 };
42 1 Kyle Knoepfel
</code></pre>
43 1 Kyle Knoepfel
44 18 Kyle Knoepfel
h2(#vector). %{color:blue}@Sequence<T>@%
45 1 Kyle Knoepfel
46 18 Kyle Knoepfel
This class template is used for unbounded sequences.  See the two caveats below.
47 18 Kyle Knoepfel
48 1 Kyle Knoepfel
<pre><code class="cpp">
49 7 Kyle Knoepfel
Sequence<int> seq { Name("seq") };
50 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence") };
51 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Sequence<int>{ 4, 5, 6, 7 } };
52 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), { 4, 5, 6, 7 } };
53 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence"), Sequence<int>{ 4, 5, 6, 7 } };
54 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6, 7 } };
55 1 Kyle Knoepfel
</code></pre>
56 1 Kyle Knoepfel
57 1 Kyle Knoepfel
h3(#make_empty). @Sequence<T>::make_empty()@
58 1 Kyle Knoepfel
59 8 Kyle Knoepfel
Due to the implementation details of the unbounded sequence, the following:
60 1 Kyle Knoepfel
61 8 Kyle Knoepfel
<pre><code class="cpp">
62 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Sequence<int>{} }; // Don't do this.
63 1 Kyle Knoepfel
</code></pre>
64 1 Kyle Knoepfel
65 18 Kyle Knoepfel
_does not_ represent an empty sequence.  If you would like an empty sequence as a default value, use the following:
66 1 Kyle Knoepfel
67 1 Kyle Knoepfel
<pre><code class="cpp">
68 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Sequence<int>::make_empty() };
69 1 Kyle Knoepfel
</code></pre>
70 1 Kyle Knoepfel
71 18 Kyle Knoepfel
h3(#narrowing). Precaution regarding narrowing conversions and @std::initializer_list@ objects
72 1 Kyle Knoepfel
73 19 Kyle Knoepfel
The following configuration will trigger a compilation warning:
74 19 Kyle Knoepfel
75 19 Kyle Knoepfel
<pre><code class="cpp">
76 19 Kyle Knoepfel
Sequence<int> seq1 { Name("seq1"), Sequence<int>{ 1, 2.4e-4 } };
77 19 Kyle Knoepfel
Sequence<int> seq2 { Name("seq2"), { 1, 2.4e-4 } };
78 19 Kyle Knoepfel
</code></pre>
79 19 Kyle Knoepfel
80 19 Kyle Knoepfel
that looks similar to this:
81 19 Kyle Knoepfel
82 19 Kyle Knoepfel
<pre>
83 19 Kyle Knoepfel
warning: narrowing conversion of ‘2.4000000000000001e-4’ from ‘double’ to ‘int’ inside { } [-Wnarrowing]
84 19 Kyle Knoepfel
</pre>
85 19 Kyle Knoepfel
86 19 Kyle Knoepfel
For build systems that convert compile-time warnings to errors, this will result in a build failure.  The warning results from the nature of an @std::initializer_list@ object, signified by @'{1, 2.4e-4}'@, which is used to initialize the sequence objects.  For @std::initializer_list@ objects, narrowing conversions are not allowed--that is, converting a @double@ to an @int@ is an example of narrowing that results in loss of information.  This is the most likely example of where you may find a narrowing conversion.
87 19 Kyle Knoepfel
88 18 Kyle Knoepfel
h2(#array). %{color:blue}@Sequence<T,std::size_t>@%
89 18 Kyle Knoepfel
90 18 Kyle Knoepfel
This class template is used for sequences of a specific length, known at compile time.
91 18 Kyle Knoepfel
92 1 Kyle Knoepfel
<pre><code class="cpp">
93 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq") };
94 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence") };
95 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Sequence<int,3u>{ 4, 5, 6 } };
96 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), { 4, 5, 6 } };
97 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), Sequence<int,3u>{ 4, 5, 6 } };
98 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6 } };
99 1 Kyle Knoepfel
</code></pre>
100 1 Kyle Knoepfel
101 18 Kyle Knoepfel
The warning regarding narrowing conversions [[Fhiclcpp_types_in_detail#narrowing|above]] applies for bounded sequences as well.
102 17 Kyle Knoepfel
103 18 Kyle Knoepfel
h2(#tuple). %{color:blue}@Tuple<T...>@%
104 18 Kyle Knoepfel
105 1 Kyle Knoepfel
<pre><code class="cpp">
106 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple") };
107 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple") };
108 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Tuple<string,bool>{"explicit?", true} };
109 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), {"compact?", true } };
110 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), Tuple<string,bool>{ "Particle physics is neat.", true } };
111 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), { "This is false", false } };
112 1 Kyle Knoepfel
</code></pre>
113 1 Kyle Knoepfel
114 18 Kyle Knoepfel
h2(#table). %{color:blue}@Table<T>@%
115 1 Kyle Knoepfel
116 1 Kyle Knoepfel
<pre><code class="cpp">
117 1 Kyle Knoepfel
Table<T> config { Name("config") };
118 1 Kyle Knoepfel
Table<T> config { Name("config"), Comment("This describes the table") };
119 1 Kyle Knoepfel
</code></pre>
120 1 Kyle Knoepfel
121 1 Kyle Knoepfel
----
122 1 Kyle Knoepfel
123 17 Kyle Knoepfel
h1(#return). Return types
124 1 Kyle Knoepfel
125 1 Kyle Knoepfel
|{background:#fba}. *@fhiclcpp@ parameter*|{background:#fba}. *Function call*|{background:#fba}. *Return type*|
126 1 Kyle Knoepfel
|\3{background:#ddd}. _Simple @fhiclcpp@ parameters_|
127 1 Kyle Knoepfel
|@Atom<std::string> label@; |@label()@| @std::string const&@|
128 1 Kyle Knoepfel
|/2.@Sequence<int> counts@; | @counts()@ | @std::vector<int>@|
129 1 Kyle Knoepfel
|@counts(1)@ | @int@ |
130 1 Kyle Knoepfel
|/2.@Sequence<double, 3u> point@;| @point()@ | @std::array<double, 3u>@|
131 1 Kyle Knoepfel
|@point(0)@ | @double@ |
132 1 Kyle Knoepfel
|/3.@Tuple<std::string, double> assoc;@|@assoc()@| @std::tuple<std::string, double>@|
133 1 Kyle Knoepfel
|@assoc.get<0>()@|@std::string@|
134 1 Kyle Knoepfel
|@assoc.get<double>()@|@double@|
135 8 Kyle Knoepfel
|@Table<Config> config;@|@config()@|@Config const&@|
136 8 Kyle Knoepfel
|\3{background:#ddd}. _Nested @fhiclcpp@ parameters_|
137 8 Kyle Knoepfel
|/2.@Sequence< Sequence<int> > datasets;@ | @datasets()@ | @std::vector< std::vector<int> >@ |
138 8 Kyle Knoepfel
| @datasets(17)@ | @std::vector<int>@ |
139 8 Kyle Knoepfel
|/2.@Sequence< Sequence<int>, 2u > twoDatasets;@ | @twoDatasets()@ | @std::array< std::vector<int>, 2u >@ |
140 8 Kyle Knoepfel
|@twoDatasets(1)@ | @std::vector<int>@ |
141 8 Kyle Knoepfel
|/2.@Sequence< Sequence<int, 2u> > intPairs;@ | @intPairs()@ | @std::vector< std::array<int, 2u> >@ |
142 8 Kyle Knoepfel
|@intPairs(42)@ | @std::array<int, 2u>@|
143 8 Kyle Knoepfel
|/2.@Sequence< Tuple<std::string, int, bool> > triplets;@ | @triplets()@ | @std::vector< std::tuple<std::string, int, bool> >@ |
144 1 Kyle Knoepfel
|@triplets(3)@ | @std::tuple<std::string, int, bool>@ |
145 1 Kyle Knoepfel
|/2.@Sequence< Table<Config> > manyConfigTables;@ | @manyConfigTables()@ | @std::vector< Config >@ |
146 7 Kyle Knoepfel
|@manyConfigTables(6)@ | @Config const&@ |
147 1 Kyle Knoepfel
|/5.@Tuple< std::string, Table<Config> > configAssoc;@ | @configAssoc()@ | @std::tuple< std::string, Config >@ |
148 7 Kyle Knoepfel
|@configAssoc.get<0>()@ | @std::string@ |
149 10 Kyle Knoepfel
|@configAssoc.get<std::string>()@ | @std::string@ |
150 10 Kyle Knoepfel
|@configAssoc.get<1>()@ | @Config@ |
151 11 Kyle Knoepfel
|@configAssoc.get< Table<Config> >()@ | @Config@ |
152 10 Kyle Knoepfel
|/3.@Tuple< Tuple<std::string,bool>, Sequence<int> > awkward;@ | @awkward()@ | @std::tuple< std::tuple<std::string, bool>, std::vector<int> >@ |
153 10 Kyle Knoepfel
|@awkward.get<0>()@|@std::tuple<std::string,bool>@|
154 14 Kyle Knoepfel
|@awkward.get<1>()@|@std::vector<int>@|
155 14 Kyle Knoepfel
156 14 Kyle Knoepfel
----
157 1 Kyle Knoepfel
158 22 Kyle Knoepfel
h1(#table_func). Additional functions for @Table<T>@
159 21 Kyle Knoepfel
160 21 Kyle Knoepfel
The @Table@ template offers a few extra functions that the user can call: 
161 21 Kyle Knoepfel
162 21 Kyle Knoepfel
<pre><code class="cpp">
163 21 Kyle Knoepfel
fhicl::ParameterSet const& get_PSet() const;
164 21 Kyle Knoepfel
165 21 Kyle Knoepfel
void print_allowed_configuration(std::ostream& os,
166 21 Kyle Knoepfel
                                 std::string const& tab = std::string(3,' ') ) const;
167 21 Kyle Knoepfel
168 21 Kyle Knoepfel
// Expert-level functions
169 21 Kyle Knoepfel
void validate_ParameterSet(fhicl::ParameterSet const& pset,
170 21 Kyle Knoepfel
                           std::set<std::string> const& keysToIgnore = {} );
171 21 Kyle Knoepfel
172 21 Kyle Knoepfel
</code></pre>
173 21 Kyle Knoepfel
174 21 Kyle Knoepfel
h3(#get_pset). @get_PSet@
175 21 Kyle Knoepfel
176 21 Kyle Knoepfel
A call to this function returns a @const@ reference to the @ParameterSet@ object that was used to fill the values of the individual @Table@ members.  This is helpful for users who need to interact with the @ParameterSet@ object itself.
177 21 Kyle Knoepfel
178 21 Kyle Knoepfel
h3(#print). @print_allowed_configuration@
179 21 Kyle Knoepfel
180 21 Kyle Knoepfel
For any @Table<Config>@ object, @print_allowed_configuration@ will fill a user-supplied @std::ostream@ object with the allowed configuration as defined by the @Config@ struct.  The optional second argument specifies the number of spaces per indentation.  The default is 3 spaces but is, of course, user-configurable.
181 21 Kyle Knoepfel
182 24 Kyle Knoepfel
----
183 1 Kyle Knoepfel
184 28 Kyle Knoepfel
%{color:red} _[ *N.B.* The following function should not normally be invoked by users. It is meant to be called only in contexts outside of @art@.  Please consult artists@fnal.gov for guidance.]_%
185 24 Kyle Knoepfel
186 21 Kyle Knoepfel
h3(#validate). @validate_ParameterSet@ (expert)
187 21 Kyle Knoepfel
188 1 Kyle Knoepfel
This function is intended for experts who need to validate the @pset@ object themselves.  The @keysToIgnore@ variable represents a set of keys for which the validation step will ignore.  The validation function will ignore any nested keys as well--i.e. if a user specifies an ignorable key as @table1@, the (e.g.) @table1.someAtom@ key would be ignored in addition to just the @table1@ name.  An indexed parameter (e.g.) @seq[1]@ is considered a nested parameter of its parent @seq@.  Providing or not providing the ignorable key in a configuration will lead to no error upon validation of the @ParameterSet@.
189 21 Kyle Knoepfel
190 24 Kyle Knoepfel
Should the validation step fail, an exception is thrown of type @fhicl::detail::validationException@.  This behavior is not currently configurable.
191 21 Kyle Knoepfel
192 25 Kyle Knoepfel
----
193 25 Kyle Knoepfel
194 17 Kyle Knoepfel
h1(#common_acc). Common parameter accessors
195 14 Kyle Knoepfel
196 14 Kyle Knoepfel
Each of the @fhiclcpp@ types has the following accessors:
197 14 Kyle Knoepfel
<pre><code class="cpp">
198 14 Kyle Knoepfel
std::string key()            const;
199 30 Kyle Knoepfel
std::string name()           const;
200 14 Kyle Knoepfel
std::string comment()        const;
201 14 Kyle Knoepfel
bool        has_default()    const;
202 30 Kyle Knoepfel
bool        is_optional()    const;
203 14 Kyle Knoepfel
par_type    parameter_type() const;
204 14 Kyle Knoepfel
</code></pre>
205 14 Kyle Knoepfel
206 14 Kyle Knoepfel
To call these functions, the difference in syntax is crucial:
207 14 Kyle Knoepfel
208 14 Kyle Knoepfel
<pre><code class="cpp">
209 14 Kyle Knoepfel
Atom<int> val { Name("val") };
210 14 Kyle Knoepfel
211 14 Kyle Knoepfel
auto key1 = val.key();   //   correct
212 14 Kyle Knoepfel
auto key2 = val().key(); // ! compile-time ERROR - 'val()' is an int, which has no accessor called 'key()' 
213 14 Kyle Knoepfel
</code></pre>
214 14 Kyle Knoepfel
215 17 Kyle Knoepfel
h2. @key()@
216 14 Kyle Knoepfel
217 14 Kyle Knoepfel
A call to @key()@ returns the _full_ key, including all enclosing tables.  For example, consider a module that is designed to allow the following configuration:
218 14 Kyle Knoepfel
<pre><code class="ruby">
219 14 Kyle Knoepfel
pset: {
220 14 Kyle Knoepfel
  list: [ { particle: electron },
221 14 Kyle Knoepfel
          { particle: muon } ]
222 14 Kyle Knoepfel
}
223 31 Kyle Knoepfel
</code></pre>For a suitably declared set of @fhiclcpp@ parameters, the returned key corresponding to "muon" would be @pset.list[1].particle@.
224 1 Kyle Knoepfel
225 30 Kyle Knoepfel
h2. @name()@
226 14 Kyle Knoepfel
227 30 Kyle Knoepfel
The name is the most-nested name in the key.  For the above "muon" parameter, a key of @pset.list[1].particle@ has a corresponding name of @particle@.  If the parameter in question were @pset.list[1]@, the name would be[1] @list[1]@.
228 1 Kyle Knoepfel
229 30 Kyle Knoepfel
fn1. Technically, this is inaccurate -- sequence elements do not have names.  However, for the sake of parameter identification, a sequence element has a name whose value is the sequence name with the appropriate sequence element index/indices appended.
230 30 Kyle Knoepfel
231 17 Kyle Knoepfel
h2. @comment()@
232 14 Kyle Knoepfel
233 14 Kyle Knoepfel
Returns the comment supplied as the string literal in (e.g.) @Comment("Here is the comment")@.  If no @Comment@ argument is provided in the @fhiclcpp@ parameter constructor, a call to this function returns an empty string.
234 14 Kyle Knoepfel
235 17 Kyle Knoepfel
h2. @has_default()@
236 14 Kyle Knoepfel
237 1 Kyle Knoepfel
Returns @true@ or @false@ depending on whether the user supplied a default value for the parameter.
238 1 Kyle Knoepfel
239 30 Kyle Knoepfel
h2. @is_optional()@
240 30 Kyle Knoepfel
241 30 Kyle Knoepfel
Returns @true@ or @false@ depending on whether the parameter is of an @Optional*@ @fhiclcpp@ type.
242 30 Kyle Knoepfel
243 1 Kyle Knoepfel
h2. @parameter_type()@
244 1 Kyle Knoepfel
245 1 Kyle Knoepfel
Returns an enumeration value based on the parameter type:
246 1 Kyle Knoepfel
247 14 Kyle Knoepfel
<pre><code class="cpp">
248 14 Kyle Knoepfel
enum class par_type {
249 30 Kyle Knoepfel
  ATOM,        // (Optional)Atom<T>
250 30 Kyle Knoepfel
  TABLE,       // (Optional)Table<T>
251 30 Kyle Knoepfel
  SEQ_VECTOR,  // (Optional)Sequence<T>
252 30 Kyle Knoepfel
  SEQ_ARRAY,   // (Optional)Sequence<T,std::size_t>
253 30 Kyle Knoepfel
  TUPLE,       // (Optional)Tuple<T...>
254 14 Kyle Knoepfel
  NTYPES       // Signifies invalid parameter 
255 14 Kyle Knoepfel
};
256 14 Kyle Knoepfel
</code></pre>