Project

General

Profile

Fhiclcpp types in detail » History » Version 48

Kyle Knoepfel, 12/16/2015 09:41 AM

1 1 Kyle Knoepfel
h1. @fhiclcpp@ types in detail
2 1 Kyle Knoepfel
3 34 Kyle Knoepfel
{{toc}}
4 1 Kyle Knoepfel
5 9 Kyle Knoepfel
----
6 9 Kyle Knoepfel
7 17 Kyle Knoepfel
h1(#ctors). Parameter constructors
8 1 Kyle Knoepfel
9 18 Kyle Knoepfel
h2(#ctors_rules). %{color:blue}General rules%
10 1 Kyle Knoepfel
11 1 Kyle Knoepfel
For each of the @fhiclcpp@ types, the following rules apply:
12 12 Kyle Knoepfel
* The @Name@ argument is required.
13 32 Kyle Knoepfel
* Neither the @Table<T>@ parameter nor any of the @Optional*@ parameters support a default value.
14 1 Kyle Knoepfel
15 39 Kyle Knoepfel
h3(#opt_comment). Note about optional parameters
16 39 Kyle Knoepfel
17 39 Kyle Knoepfel
In addition to @Optional*@ parameters not supporting default values, they also cannot be used as template arguments to *any* @fhiclcpp@ types:
18 39 Kyle Knoepfel
19 39 Kyle Knoepfel
<pre><code class="cpp">
20 39 Kyle Knoepfel
Sequence< OptionalSequence<int> >     e1 { ... };  // error
21 39 Kyle Knoepfel
Sequence< OptionalSequence<int,2u> >  e2 { ... };  // error
22 39 Kyle Knoepfel
Sequence< OptionalTuple<int,double> > e3 { ... };  // error
23 40 Kyle Knoepfel
OptionalSequence< Sequence<int> >     ok { ... };  // ok
24 39 Kyle Knoepfel
</code></pre>
25 39 Kyle Knoepfel
26 18 Kyle Knoepfel
h2(#atom). %{color:blue}@Atom<T>@%
27 7 Kyle Knoepfel
28 46 Kyle Knoepfel
h3. Allowed constructors
29 46 Kyle Knoepfel
30 1 Kyle Knoepfel
<pre><code class="cpp">
31 46 Kyle Knoepfel
explicit Atom(Name&&);
32 46 Kyle Knoepfel
explicit Atom(Name&&, Comment&&);
33 46 Kyle Knoepfel
explicit Atom(Name&&, Comment&&, std::function<bool()> maybeUse);
34 46 Kyle Knoepfel
35 46 Kyle Knoepfel
// c'tors supporting default values
36 46 Kyle Knoepfel
explicit Atom(Name&&, T const& t);
37 46 Kyle Knoepfel
explicit Atom(Name&&, Comment&&, T const& t);
38 46 Kyle Knoepfel
explicit Atom(Name&&, Comment&&, std::function<bool()> maybeUse, T const& t);
39 46 Kyle Knoepfel
</code></pre>
40 46 Kyle Knoepfel
41 46 Kyle Knoepfel
h3. Examples
42 46 Kyle Knoepfel
43 46 Kyle Knoepfel
<pre><code class="cpp">
44 1 Kyle Knoepfel
Atom<int> var { Name("var") };
45 1 Kyle Knoepfel
Atom<int> var { Name("var"), 9 };
46 7 Kyle Knoepfel
Atom<int> var { Name("var"), Comment("A parameter description") };
47 1 Kyle Knoepfel
Atom<int> var { Name("var"), Comment("A parameter description"), 9 };
48 1 Kyle Knoepfel
</code></pre>
49 33 Kyle Knoepfel
50 39 Kyle Knoepfel
51 33 Kyle Knoepfel
h2(#opt_atom). %{color:blue}@OptionalAtom<T>@%
52 33 Kyle Knoepfel
53 46 Kyle Knoepfel
h3. Allowed constructors
54 46 Kyle Knoepfel
55 33 Kyle Knoepfel
<pre><code class="cpp">
56 46 Kyle Knoepfel
explicit OptionalAtom(Name&&);
57 46 Kyle Knoepfel
explicit OptionalAtom(Name&&, Comment&&);
58 46 Kyle Knoepfel
explicit OptionalAtom(Name&&, Comment&&, std::function<bool()> maybeUse);
59 46 Kyle Knoepfel
</code></pre>
60 46 Kyle Knoepfel
61 46 Kyle Knoepfel
h3. Examples
62 46 Kyle Knoepfel
63 46 Kyle Knoepfel
<pre><code class="cpp">
64 33 Kyle Knoepfel
OptionalAtom<int> var { Name("var") };
65 33 Kyle Knoepfel
OptionalAtom<int> var { Name("var"), Comment("A parameter description") };
66 33 Kyle Knoepfel
</code></pre>
67 33 Kyle Knoepfel
68 33 Kyle Knoepfel
h2(#opt_vector). %{color:blue}@OptionalSequence<T>@%
69 1 Kyle Knoepfel
70 39 Kyle Knoepfel
This class template is used for unbounded sequences.
71 33 Kyle Knoepfel
72 46 Kyle Knoepfel
h3. Allowed constructors
73 46 Kyle Knoepfel
74 33 Kyle Knoepfel
<pre><code class="cpp">
75 46 Kyle Knoepfel
explicit OptionalSequence(Name&&);
76 46 Kyle Knoepfel
explicit OptionalSequence(Name&&, Comment&&);
77 46 Kyle Knoepfel
explicit OptionalSequence(Name&&, Comment&&, std::function<bool()> maybeUse);
78 46 Kyle Knoepfel
</code></pre>
79 46 Kyle Knoepfel
80 46 Kyle Knoepfel
h3. Examples
81 46 Kyle Knoepfel
82 46 Kyle Knoepfel
<pre><code class="cpp">
83 33 Kyle Knoepfel
OptionalSequence<int> seq { Name("seq") };
84 33 Kyle Knoepfel
OptionalSequence<int> seq { Name("seq"), Comment("A sequence") };
85 33 Kyle Knoepfel
</code></pre>
86 33 Kyle Knoepfel
87 33 Kyle Knoepfel
h2(#opt_array). %{color:blue}@OptionalSequence<T,std::size_t>@%
88 33 Kyle Knoepfel
89 33 Kyle Knoepfel
This class template is used for sequences of a specific length, known at compile time.
90 33 Kyle Knoepfel
91 46 Kyle Knoepfel
h3. Allowed constructors
92 46 Kyle Knoepfel
93 33 Kyle Knoepfel
<pre><code class="cpp">
94 46 Kyle Knoepfel
explicit OptionalSequence(Name&&);
95 46 Kyle Knoepfel
explicit OptionalSequence(Name&&, Comment&&);
96 46 Kyle Knoepfel
explicit OptionalSequence(Name&&, Comment&&, std::function<bool()> maybeUse);
97 46 Kyle Knoepfel
</code></pre>
98 46 Kyle Knoepfel
99 46 Kyle Knoepfel
h3. Examples
100 46 Kyle Knoepfel
101 46 Kyle Knoepfel
<pre><code class="cpp">
102 33 Kyle Knoepfel
OptionalSequence<int,3u> seq { Name("seq") };
103 33 Kyle Knoepfel
OptionalSequence<int,3u> seq { Name("seq"), Comment("A sequence") };
104 33 Kyle Knoepfel
</code></pre>
105 33 Kyle Knoepfel
106 33 Kyle Knoepfel
h2(#opt_table). %{color:blue}@OptionalTable<T>@%
107 33 Kyle Knoepfel
108 46 Kyle Knoepfel
h3. Allowed constructors
109 46 Kyle Knoepfel
110 33 Kyle Knoepfel
<pre><code class="cpp">
111 46 Kyle Knoepfel
explicit OptionalTable(Name&&);
112 46 Kyle Knoepfel
explicit OptionalTable(Name&&, Comment&&);
113 46 Kyle Knoepfel
explicit OptionalTable(Name&&, Comment&&, std::function<bool()> maybeUse);
114 46 Kyle Knoepfel
</code></pre>
115 46 Kyle Knoepfel
116 46 Kyle Knoepfel
h3. Examples
117 46 Kyle Knoepfel
118 46 Kyle Knoepfel
<pre><code class="cpp">
119 33 Kyle Knoepfel
OptionalTable<T> config { Name("config") };
120 33 Kyle Knoepfel
OptionalTable<T> config { Name("config"), Comment("This describes the table") };
121 33 Kyle Knoepfel
</code></pre>
122 33 Kyle Knoepfel
123 33 Kyle Knoepfel
h2(#opt_tuple). %{color:blue}@OptionalTuple<T...>@%
124 33 Kyle Knoepfel
125 46 Kyle Knoepfel
h3. Allowed constructors
126 46 Kyle Knoepfel
127 33 Kyle Knoepfel
<pre><code class="cpp">
128 46 Kyle Knoepfel
explicit OptionalTuple(Name&&);
129 46 Kyle Knoepfel
explicit OptionalTuple(Name&&, Comment&&);
130 46 Kyle Knoepfel
explicit OptionalTuple(Name&&, Comment&&, std::function<bool()> maybeUse);
131 46 Kyle Knoepfel
</code></pre>
132 46 Kyle Knoepfel
133 46 Kyle Knoepfel
h3. Examples
134 46 Kyle Knoepfel
135 46 Kyle Knoepfel
<pre><code class="cpp">
136 33 Kyle Knoepfel
OptionalTuple<string,bool> tuple { Name("tuple") };
137 33 Kyle Knoepfel
OptionalTuple<string,bool> tuple { Name("tuple"), Comment("A tuple") };
138 33 Kyle Knoepfel
</code></pre>
139 18 Kyle Knoepfel
140 1 Kyle Knoepfel
h2(#vector). %{color:blue}@Sequence<T>@%
141 1 Kyle Knoepfel
142 46 Kyle Knoepfel
This class template is used for unbounded sequences.  See the caveat below regarding narrowing conversions.
143 1 Kyle Knoepfel
144 46 Kyle Knoepfel
h3. Allowed constructors
145 46 Kyle Knoepfel
146 1 Kyle Knoepfel
<pre><code class="cpp">
147 46 Kyle Knoepfel
explicit Sequence(Name&&);
148 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&);
149 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, std::function<bool()> maybeUse);
150 46 Kyle Knoepfel
151 46 Kyle Knoepfel
// c'tors supporting default values
152 46 Kyle Knoepfel
explicit Sequence(Name&&, std::vector<T> const& t);
153 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, std::vector<T> const& t);
154 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, std::function<bool()> maybeUse, std::vector<T> const& t);
155 46 Kyle Knoepfel
</code></pre>
156 46 Kyle Knoepfel
157 46 Kyle Knoepfel
h3. Examples
158 46 Kyle Knoepfel
159 46 Kyle Knoepfel
<pre><code class="cpp">
160 7 Kyle Knoepfel
Sequence<int> seq { Name("seq") };
161 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence") };
162 42 Kyle Knoepfel
Sequence<int> seq { Name("seq"), std::vector<int>{ 4, 5, 6, 7 } };
163 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), { 4, 5, 6, 7 } };
164 42 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence"), std::vector<int>{ 4, 5, 6, 7 } };
165 1 Kyle Knoepfel
Sequence<int> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6, 7 } };
166 1 Kyle Knoepfel
</code></pre>
167 1 Kyle Knoepfel
168 1 Kyle Knoepfel
h3(#narrowing). Precaution regarding narrowing conversions and @std::initializer_list@ objects
169 1 Kyle Knoepfel
170 18 Kyle Knoepfel
The following configuration will trigger a compilation warning:
171 19 Kyle Knoepfel
172 19 Kyle Knoepfel
<pre><code class="cpp">
173 42 Kyle Knoepfel
Sequence<int> seq1 { Name("seq1"), std::vector<int>{ 1, 2.4e-4 } };
174 19 Kyle Knoepfel
Sequence<int> seq2 { Name("seq2"), { 1, 2.4e-4 } };
175 19 Kyle Knoepfel
</code></pre>
176 19 Kyle Knoepfel
177 19 Kyle Knoepfel
that looks similar to this:
178 19 Kyle Knoepfel
179 18 Kyle Knoepfel
<pre>
180 18 Kyle Knoepfel
warning: narrowing conversion of ‘2.4000000000000001e-4’ from ‘double’ to ‘int’ inside { } [-Wnarrowing]
181 18 Kyle Knoepfel
</pre>
182 1 Kyle Knoepfel
183 42 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 (also referred to as a brace-enclosed initializer), 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.
184 1 Kyle Knoepfel
185 1 Kyle Knoepfel
h2(#array). %{color:blue}@Sequence<T,std::size_t>@%
186 1 Kyle Knoepfel
187 1 Kyle Knoepfel
This class template is used for sequences of a specific length, known at compile time.
188 1 Kyle Knoepfel
189 46 Kyle Knoepfel
h3. Allowed constructors
190 46 Kyle Knoepfel
191 47 Kyle Knoepfel
_The @dtype@ is a type alias that allows users to specify as a default argument either an @std::array<T,N>@ object or a brace-enclosed @std::initializer_list<T>@ object.  It is preferred that users provide an @std::array@ object as a default value since the size of the supplied array is checked against the expected size at compile time._
192 47 Kyle Knoepfel
193 1 Kyle Knoepfel
<pre><code class="cpp">
194 46 Kyle Knoepfel
explicit Sequence(Name&&);
195 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&);
196 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, std::function<bool()> maybeUse);
197 46 Kyle Knoepfel
198 46 Kyle Knoepfel
// c'tors supporting default values
199 46 Kyle Knoepfel
explicit Sequence(Name&&, dtype const& t);
200 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, dtype const& t);
201 46 Kyle Knoepfel
explicit Sequence(Name&&, Comment&&, std::function<bool()> maybeUse, dtype const& t);
202 46 Kyle Knoepfel
</code></pre>
203 46 Kyle Knoepfel
204 46 Kyle Knoepfel
h3. Examples
205 46 Kyle Knoepfel
206 46 Kyle Knoepfel
<pre><code class="cpp">
207 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq") };
208 18 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence") };
209 43 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), std::array<int,3u>{ 4, 5, 6 } };
210 18 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), { 4, 5, 6 } };
211 43 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), std::array<int,3u>{ 4, 5, 6 } };
212 1 Kyle Knoepfel
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6 } };
213 1 Kyle Knoepfel
</code></pre>
214 1 Kyle Knoepfel
215 1 Kyle Knoepfel
The warning regarding narrowing conversions [[Fhiclcpp_types_in_detail#narrowing|above]] applies for bounded sequences as well.
216 1 Kyle Knoepfel
217 33 Kyle Knoepfel
h2(#table). %{color:blue}@Table<T>@%
218 1 Kyle Knoepfel
219 46 Kyle Knoepfel
h3. Allowed constructors
220 46 Kyle Knoepfel
221 1 Kyle Knoepfel
<pre><code class="cpp">
222 46 Kyle Knoepfel
explicit Table(Name&&);
223 46 Kyle Knoepfel
explicit Table(Name&&, Comment&&);
224 46 Kyle Knoepfel
explicit Table(Name&&, Comment&&, std::function<bool()> maybeUse);
225 46 Kyle Knoepfel
</code></pre>
226 46 Kyle Knoepfel
227 46 Kyle Knoepfel
h3. Examples
228 46 Kyle Knoepfel
229 46 Kyle Knoepfel
<pre><code class="cpp">
230 33 Kyle Knoepfel
Table<T> config { Name("config") };
231 33 Kyle Knoepfel
Table<T> config { Name("config"), Comment("This describes the table") };
232 33 Kyle Knoepfel
</code></pre>
233 33 Kyle Knoepfel
234 1 Kyle Knoepfel
h2(#tuple). %{color:blue}@Tuple<T...>@%
235 46 Kyle Knoepfel
236 46 Kyle Knoepfel
h3. Allowed constructors
237 46 Kyle Knoepfel
238 48 Kyle Knoepfel
_The @dtype@ is a type alias that allows users to specify as a default argument either an @std::tuple<T...>@ object or a brace-enclosed initializer, which, in this case, is *not* an @std::initializer@ object._
239 48 Kyle Knoepfel
240 46 Kyle Knoepfel
<pre><code class="cpp">
241 46 Kyle Knoepfel
explicit Tuple(Name&&);
242 46 Kyle Knoepfel
explicit Tuple(Name&&, Comment&&);
243 46 Kyle Knoepfel
explicit Tuple(Name&&, Comment&&, std::function<bool()> maybeUse);
244 46 Kyle Knoepfel
245 46 Kyle Knoepfel
// c'tors supporting default values
246 46 Kyle Knoepfel
explicit Tuple(Name&&, dtype const& t);
247 46 Kyle Knoepfel
explicit Tuple(Name&&, Comment&&, dtype const& t);
248 46 Kyle Knoepfel
explicit Tuple(Name&&, Comment&&, std::function<bool()> maybeUse, dtype const& t);
249 46 Kyle Knoepfel
</code></pre>
250 46 Kyle Knoepfel
251 46 Kyle Knoepfel
h3. Examples
252 1 Kyle Knoepfel
253 1 Kyle Knoepfel
<pre><code class="cpp">
254 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple") };
255 18 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple") };
256 44 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), std::tuple<string,bool>{"explicit?", true} };
257 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), {"compact?", true } };
258 44 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), std::tuple<string,bool>{ "Particle physics is neat.", true } };
259 1 Kyle Knoepfel
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), { "This is false", false } };
260 1 Kyle Knoepfel
</code></pre>
261 1 Kyle Knoepfel
262 1 Kyle Knoepfel
----
263 1 Kyle Knoepfel
264 35 Kyle Knoepfel
h1(#return). Standard parameters - return types
265 35 Kyle Knoepfel
266 38 Kyle Knoepfel
_[ In what follows, @array@, @string@, @tuple@, and @vector@ should each be prefaced with the appropriate namespace resolution: '@std::@'. ]_
267 37 Kyle Knoepfel
268 1 Kyle Knoepfel
|{background:#fba}. *@fhiclcpp@ parameter*|{background:#fba}. *Function call*|{background:#fba}. *Return type*|
269 1 Kyle Knoepfel
|\3{background:#ddd}. _Simple @fhiclcpp@ parameters_|
270 37 Kyle Knoepfel
|@Atom<string> label@; |@label()@| @string const&@|
271 37 Kyle Knoepfel
|/2.@Sequence<int> counts@; | @counts()@ | @vector<int>@|
272 35 Kyle Knoepfel
|@counts(1)@ | @int@ |
273 37 Kyle Knoepfel
|/2.@Sequence<double, 3u> point@;| @point()@ | @array<double, 3u>@|
274 1 Kyle Knoepfel
|@point(0)@ | @double@ |
275 37 Kyle Knoepfel
|/3.@Tuple<string, double> assoc;@|@assoc()@| @tuple<string, double>@|
276 37 Kyle Knoepfel
|@assoc.get<0>()@|@string@|
277 35 Kyle Knoepfel
|@assoc.get<double>()@|@double@|
278 35 Kyle Knoepfel
|@Table<Config> config;@|@config()@|@Config const&@|
279 35 Kyle Knoepfel
|\3{background:#ddd}. _Nested @fhiclcpp@ parameters_|
280 37 Kyle Knoepfel
|/2.@Sequence< Sequence<int> > datasets;@ | @datasets()@ | @vector< vector<int> >@ |
281 37 Kyle Knoepfel
| @datasets(17)@ | @vector<int>@ |
282 37 Kyle Knoepfel
|/2.@Sequence< Sequence<int>, 2u > twoDatasets;@ | @twoDatasets()@ | @array< vector<int>, 2u >@ |
283 37 Kyle Knoepfel
|@twoDatasets(1)@ | @vector<int>@ |
284 37 Kyle Knoepfel
|/2.@Sequence< Sequence<int, 2u> > intPairs;@ | @intPairs()@ | @vector< array<int, 2u> >@ |
285 37 Kyle Knoepfel
|@intPairs(42)@ | @array<int, 2u>@|
286 37 Kyle Knoepfel
|/2.@Sequence< Tuple<string, int, bool> > triplets;@ | @triplets()@ | @vector< tuple<string, int, bool> >@ |
287 37 Kyle Knoepfel
|@triplets(3)@ | @tuple<string, int, bool>@ |
288 37 Kyle Knoepfel
|/2.@Sequence< Table<Config> > manyConfigTables;@ | @manyConfigTables()@ | @vector< Config >@ |
289 35 Kyle Knoepfel
|@manyConfigTables(6)@ | @Config const&@ |
290 37 Kyle Knoepfel
|/3.@Tuple< string, Table<Config> > configAssoc;@ | @configAssoc()@ | @tuple< string, Config >@ |
291 37 Kyle Knoepfel
|@configAssoc.get<0>()@ | @string@ |
292 35 Kyle Knoepfel
|@configAssoc.get<1>()@ | @Config@ |
293 37 Kyle Knoepfel
|/3.@Tuple< Tuple<string,bool>, Sequence<int> > awkward;@ | @awkward()@ | @tuple< tuple<string, bool>, vector<int> >@ |
294 37 Kyle Knoepfel
|@awkward.get<0>()@|@tuple<string,bool>@|
295 37 Kyle Knoepfel
|@awkward.get<1>()@|@vector<int>@|
296 1 Kyle Knoepfel
297 36 Kyle Knoepfel
h1(#opt_arg). @Optional@ parameters - argument types
298 1 Kyle Knoepfel
299 38 Kyle Knoepfel
The usage pattern for @Optional@ @fhiclcpp@ parameters is:
300 38 Kyle Knoepfel
301 38 Kyle Knoepfel
<pre><code class="cpp">
302 38 Kyle Knoepfel
OptionalAtom<string> message { Name("message") };
303 38 Kyle Knoepfel
304 38 Kyle Knoepfel
string filled_msg; // passed argument
305 38 Kyle Knoepfel
306 38 Kyle Knoepfel
if ( message(filled_msg) ) {
307 38 Kyle Knoepfel
   // use 'filled_msg'
308 38 Kyle Knoepfel
}
309 38 Kyle Knoepfel
</code></pre>
310 38 Kyle Knoepfel
311 38 Kyle Knoepfel
The following table gives the required passed-argument types for a given @Optional@ parameter.
312 38 Kyle Knoepfel
313 38 Kyle Knoepfel
_[ In what follows, @array@, @string@, @tuple@, and @vector@ should each be prefaced with the appropriate namespace resolution: '@std::@'. ]_
314 38 Kyle Knoepfel
315 1 Kyle Knoepfel
|{background:#fba}. *@fhiclcpp@ parameter*|{background:#fba}. *Passed argument*|{background:#fba}. *Function call*|
316 1 Kyle Knoepfel
|\3{background:#ddd}. _Simple @fhiclcpp@ parameters_|
317 38 Kyle Knoepfel
|@OptionalAtom<string> label@; |@string l;@| @bool exists = label(l);@|
318 38 Kyle Knoepfel
|@OptionalSequence<int> counts@; | @vector<int> v;@|@bool exists = counts(v);@ |
319 38 Kyle Knoepfel
|@OptionalSequence<double, 3u> point@;| @array<double, 3u> p;@| @bool exists = point(p);@ |
320 38 Kyle Knoepfel
|@OptionalTuple<string, double> assoc;@|@tuple<string, double> t;@| @bool exists = assoc(t);@|
321 36 Kyle Knoepfel
|@OptionalTable<Config> config;@|@Config c;@|@bool exists = config(c);@|
322 14 Kyle Knoepfel
|\3{background:#ddd}. _Nested @fhiclcpp@ parameters_|
323 38 Kyle Knoepfel
|@OptionalSequence< Sequence<int> > datasets;@ |  @vector< vector<int> > sets;@ |@bool exists = datasets(sets);@ |
324 38 Kyle Knoepfel
|@OptionalSequence< Sequence<int>, 2u > twoDatasets;@ |  @array< vector<int>, 2u >@ sets; |@bool exists = twoDatasets(sets);@ |
325 38 Kyle Knoepfel
|@OptionalSequence< Sequence<int, 2u> > intPairs;@ | @vector< array<int, 2u> >@ prs; |@bool exists = intPairs(prs);@ |
326 38 Kyle Knoepfel
|@OptionalSequence< Tuple<string, int, bool> > triplets;@ |  @vector< tuple<string, int, bool> > trps;@ |@bool exists = triplets(trps);@ |
327 38 Kyle Knoepfel
|@OptionalSequence< Table<Config> > manyConfigTables;@ | @vector< Config > tbls;@ |@bool exists = manyConfigTables(tbls);@ |
328 38 Kyle Knoepfel
|@OptionalTuple< string, Table<Config> > configAssoc;@ | @tuple< string, Config > assoc;@ |@bool exists = configAssoc(assoc);@ |
329 38 Kyle Knoepfel
|@OptionalTuple< Tuple<string,bool>, Sequence<int> > awkward;@ | @tuple< tuple<string, bool>, vector<int> > wow;@ |@bool exists = awkward(wow);@ |
330 38 Kyle Knoepfel
331 21 Kyle Knoepfel
332 21 Kyle Knoepfel
----
333 21 Kyle Knoepfel
334 21 Kyle Knoepfel
h1(#table_func). Additional functions for @Table<T>@
335 21 Kyle Knoepfel
336 21 Kyle Knoepfel
The @Table@ template offers a few extra functions that the user can call: 
337 21 Kyle Knoepfel
338 21 Kyle Knoepfel
<pre><code class="cpp">
339 21 Kyle Knoepfel
fhicl::ParameterSet const& get_PSet() const;
340 21 Kyle Knoepfel
341 21 Kyle Knoepfel
void print_allowed_configuration(std::ostream& os,
342 21 Kyle Knoepfel
                                 std::string const& tab = std::string(3,' ') ) const;
343 21 Kyle Knoepfel
344 21 Kyle Knoepfel
// Expert-level functions
345 21 Kyle Knoepfel
void validate_ParameterSet(fhicl::ParameterSet const& pset,
346 21 Kyle Knoepfel
                           std::set<std::string> const& keysToIgnore = {} );
347 21 Kyle Knoepfel
348 21 Kyle Knoepfel
</code></pre>
349 24 Kyle Knoepfel
350 1 Kyle Knoepfel
h3(#get_pset). @get_PSet@
351 28 Kyle Knoepfel
352 24 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.
353 21 Kyle Knoepfel
354 21 Kyle Knoepfel
h3(#print). @print_allowed_configuration@
355 1 Kyle Knoepfel
356 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.
357 24 Kyle Knoepfel
358 21 Kyle Knoepfel
----
359 25 Kyle Knoepfel
360 25 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.]_%
361 17 Kyle Knoepfel
362 14 Kyle Knoepfel
h3(#validate). @validate_ParameterSet@ (expert)
363 14 Kyle Knoepfel
364 14 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@.
365 14 Kyle Knoepfel
366 30 Kyle Knoepfel
Should the validation step fail, an exception is thrown of type @fhicl::detail::validationException@.  This behavior is not currently configurable.
367 14 Kyle Knoepfel
368 14 Kyle Knoepfel
----
369 30 Kyle Knoepfel
370 14 Kyle Knoepfel
h1(#common_acc). Common parameter accessors
371 14 Kyle Knoepfel
372 14 Kyle Knoepfel
Each of the @fhiclcpp@ types has the following accessors:
373 14 Kyle Knoepfel
<pre><code class="cpp">
374 14 Kyle Knoepfel
std::string key()            const;
375 14 Kyle Knoepfel
std::string name()           const;
376 14 Kyle Knoepfel
std::string comment()        const;
377 14 Kyle Knoepfel
bool        has_default()    const;
378 14 Kyle Knoepfel
bool        is_optional()    const;
379 45 Kyle Knoepfel
bool        is_conditional() const;
380 14 Kyle Knoepfel
par_type    parameter_type() const;
381 45 Kyle Knoepfel
bool        should_use()     const;
382 14 Kyle Knoepfel
</code></pre>
383 14 Kyle Knoepfel
384 17 Kyle Knoepfel
To call these functions, the difference in syntax is crucial:
385 14 Kyle Knoepfel
386 14 Kyle Knoepfel
<pre><code class="cpp">
387 14 Kyle Knoepfel
Atom<int> val { Name("val") };
388 14 Kyle Knoepfel
389 14 Kyle Knoepfel
auto key1 = val.key();   //   correct
390 14 Kyle Knoepfel
auto key2 = val().key(); // ! compile-time ERROR - 'val()' is an int, which has no accessor called 'key()' 
391 14 Kyle Knoepfel
</code></pre>
392 31 Kyle Knoepfel
393 1 Kyle Knoepfel
h2. @key()@
394 30 Kyle Knoepfel
395 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:
396 30 Kyle Knoepfel
<pre><code class="ruby">
397 1 Kyle Knoepfel
pset: {
398 30 Kyle Knoepfel
  list: [ { particle: electron },
399 30 Kyle Knoepfel
          { particle: muon } ]
400 17 Kyle Knoepfel
}
401 14 Kyle Knoepfel
</code></pre>For a suitably declared set of @fhiclcpp@ parameters, the returned key corresponding to "muon" would be @pset.list[1].particle@.
402 14 Kyle Knoepfel
403 14 Kyle Knoepfel
h2. @name()@
404 17 Kyle Knoepfel
405 14 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]@.
406 1 Kyle Knoepfel
407 1 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.
408 30 Kyle Knoepfel
409 30 Kyle Knoepfel
h2. @comment()@
410 30 Kyle Knoepfel
411 30 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.
412 1 Kyle Knoepfel
413 1 Kyle Knoepfel
h2. @has_default()@
414 1 Kyle Knoepfel
415 1 Kyle Knoepfel
Returns @true@ or @false@ depending on whether the user supplied a default value for the parameter.
416 14 Kyle Knoepfel
417 30 Kyle Knoepfel
h2. @is_optional()@
418 1 Kyle Knoepfel
419 45 Kyle Knoepfel
Returns @true@ if the parameter is an @Optional*@ @fhiclcpp@ type; @false@ otherwise.
420 1 Kyle Knoepfel
421 45 Kyle Knoepfel
h2. @is_conditional()@
422 45 Kyle Knoepfel
423 45 Kyle Knoepfel
Returns @true@ if a configuration predicate (either through @fhicl::use_if@, @fhicl::use_unless@, or some supplied lambda function) has been provided by the user; @false@ otherwise.
424 45 Kyle Knoepfel
425 30 Kyle Knoepfel
h2. @parameter_type()@
426 30 Kyle Knoepfel
427 14 Kyle Knoepfel
Returns an enumeration value based on the parameter type:
428 14 Kyle Knoepfel
429 14 Kyle Knoepfel
<pre><code class="cpp">
430 1 Kyle Knoepfel
enum class par_type {
431 1 Kyle Knoepfel
  ATOM,        // (Optional)Atom<T>
432 1 Kyle Knoepfel
  TABLE,       // (Optional)Table<T>
433 1 Kyle Knoepfel
  SEQ_VECTOR,  // (Optional)Sequence<T>
434 1 Kyle Knoepfel
  SEQ_ARRAY,   // (Optional)Sequence<T,std::size_t>
435 1 Kyle Knoepfel
  TUPLE,       // (Optional)Tuple<T...>
436 1 Kyle Knoepfel
  NTYPES       // Signifies invalid parameter 
437 1 Kyle Knoepfel
};
438 1 Kyle Knoepfel
</code></pre>
439 45 Kyle Knoepfel
440 45 Kyle Knoepfel
h2. @should_use()@
441 45 Kyle Knoepfel
442 45 Kyle Knoepfel
Returns @true@ unless a user-provided configuration predicate returns @false@.