Project

General

Profile

Fhiclcpp types in detail » History » Version 56

Kyle Knoepfel, 09/09/2016 01:56 PM

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