Project

General

Profile

Fhiclcpp types in detail » History » Version 17

Version 16 (Kyle Knoepfel, 09/02/2015 02:03 PM) → Version 17/56 (Kyle Knoepfel, 09/02/2015 02:05 PM)

h1. @fhiclcpp@ types in detail

* [[Fhiclcpp_types_in_detail#ctors|Constructors]]
** [[Fhiclcpp_types_in_detail#ctors_rules|General rules]]
** [[Fhiclcpp_types_in_detail#atom|Atom<T>]]
** [[Fhiclcpp_types_in_detail#vector|Sequence<T>]]
*** [[Fhiclcpp_types_in_detail#make_empty|make_empty()]]
** [[Fhiclcpp_types_in_detail#array|Sequence<T,std::size_t>]]
** [[Fhiclcpp_types_in_detail#tuple|Tuple<T...>]]
** [[Fhiclcpp_types_in_detail#table|Table<T>]]
* [[Fhiclcpp_types_in_detail#return|Return types]]
* [[Fhiclcpp_types_in_detail#common_acc|Common parameter accessors]]

----

h1(#ctors). h2(#ctors). Parameter constructors

h2(#ctors_rules). h3(#ctors_rules). General rules

For each of the @fhiclcpp@ types, the following rules apply:
* The @Name@ argument is required.
* If there is more than one argument, the @Name@ argument must be first in the list.
* If there are three arguments, the relative order of the @Comment@ argument and default-value argument is not important.
<pre><code class="cpp">
Atom<int> val { Name("val"), Comment("Some parameter"), 9 }; // is equivalent to
Atom<int> val { Name("val"), 9, Comment("Some parameter") };
</code></pre>
* The @Table<T>@ parameter does not support a default value.

h2(#atom). h3(#atom). @Atom<T>@

<pre><code class="cpp">
Atom<int> var { Name("var") };
Atom<int> var { Name("var"), 9 };
Atom<int> var { Name("var"), Comment("A parameter description") };
Atom<int> var { Name("var"), Comment("A parameter description"), 9 };
</code></pre>

h2(#vector). h3(#vector). @Sequence<T>@

<pre><code class="cpp">
Sequence<int> seq { Name("seq") };
Sequence<int> seq { Name("seq"), Comment("A sequence") };
Sequence<int> seq { Name("seq"), Sequence<int>{ 4, 5, 6, 7 } };
Sequence<int> seq { Name("seq"), { 4, 5, 6, 7 } };
Sequence<int> seq { Name("seq"), Comment("A sequence"), Sequence<int>{ 4, 5, 6, 7 } };
Sequence<int> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6, 7 } };
</code></pre>

h3(#make_empty). @Sequence<T>::make_empty()@

Due to the implementation details of the unbounded sequence, the following:

<pre><code class="cpp">
Sequence<int> seq { Name("seq"), Sequence<int>{} }; // Don't do this.
</code></pre>

_*does not*_ represent an empty sequence. If you would like an empty sequence as a default value, use the following:

<pre><code class="cpp">
Sequence<int> seq { Name("seq"), Sequence<int>::make_empty() };
</code></pre>

h2(#array). h3(#array). @Sequence<T,std::size_t>@

<pre><code class="cpp">
Sequence<int,3u> seq { Name("seq") };
Sequence<int,3u> seq { Name("seq"), Comment("A sequence") };
Sequence<int,3u> seq { Name("seq"), Sequence<int,3u>{ 4, 5, 6 } };
Sequence<int,3u> seq { Name("seq"), { 4, 5, 6 } };
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), Sequence<int,3u>{ 4, 5, 6 } };
Sequence<int,3u> seq { Name("seq"), Comment("A sequence"), { 4, 5, 6 } };
</code></pre>

h2(#tuple). h3(#tuple). @Tuple<T...>@

<pre><code class="cpp">
Tuple<string,bool> tuple { Name("tuple") };
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple") };
Tuple<string,bool> tuple { Name("tuple"), Tuple<string,bool>{"explicit?", true} };
Tuple<string,bool> tuple { Name("tuple"), {"compact?", true } };
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), Tuple<string,bool>{ "Particle physics is neat.", true } };
Tuple<string,bool> tuple { Name("tuple"), Comment("A tuple"), { "This is false", false } };
</code></pre>

h2(#table). h3(#table). @Table<T>@

<pre><code class="cpp">
Table<T> config { Name("config") };
Table<T> config { Name("config"), Comment("This describes the table") };
</code></pre>

----

h1(#return). h2(#return). Return types

|{background:#fba}. *@fhiclcpp@ parameter*|{background:#fba}. *Function call*|{background:#fba}. *Return type*|
|\3{background:#ddd}. _Simple @fhiclcpp@ parameters_|
|@Atom<std::string> label@; |@label()@| @std::string const&@|
|/2.@Sequence<int> counts@; | @counts()@ | @std::vector<int>@|
|@counts(1)@ | @int@ |
|/2.@Sequence<double, 3u> point@;| @point()@ | @std::array<double, 3u>@|
|@point(0)@ | @double@ |
|/3.@Tuple<std::string, double> assoc;@|@assoc()@| @std::tuple<std::string, double>@|
|@assoc.get<0>()@|@std::string@|
|@assoc.get<double>()@|@double@|
|@Table<Config> config;@|@config()@|@Config const&@|
|\3{background:#ddd}. _Nested @fhiclcpp@ parameters_|
|/2.@Sequence< Sequence<int> > datasets;@ | @datasets()@ | @std::vector< std::vector<int> >@ |
| @datasets(17)@ | @std::vector<int>@ |
|/2.@Sequence< Sequence<int>, 2u > twoDatasets;@ | @twoDatasets()@ | @std::array< std::vector<int>, 2u >@ |
|@twoDatasets(1)@ | @std::vector<int>@ |
|/2.@Sequence< Sequence<int, 2u> > intPairs;@ | @intPairs()@ | @std::vector< std::array<int, 2u> >@ |
|@intPairs(42)@ | @std::array<int, 2u>@|
|/2.@Sequence< Tuple<std::string, int, bool> > triplets;@ | @triplets()@ | @std::vector< std::tuple<std::string, int, bool> >@ |
|@triplets(3)@ | @std::tuple<std::string, int, bool>@ |
|/2.@Sequence< Table<Config> > manyConfigTables;@ | @manyConfigTables()@ | @std::vector< Config >@ |
|@manyConfigTables(6)@ | @Config const&@ |
|/5.@Tuple< std::string, Table<Config> > configAssoc;@ | @configAssoc()@ | @std::tuple< std::string, Config >@ |
|@configAssoc.get<0>()@ | @std::string@ |
|@configAssoc.get<std::string>()@ | @std::string@ |
|@configAssoc.get<1>()@ | @Config@ |
|@configAssoc.get< Table<Config> >()@ | @Config@ |
|/3.@Tuple< Tuple<std::string,bool>, Sequence<int> > awkward;@ | @awkward()@ | @std::tuple< std::tuple<std::string, bool>, std::vector<int> >@ |
|@awkward.get<0>()@|@std::tuple<std::string,bool>@|
|@awkward.get<1>()@|@std::vector<int>@|

----

h1(#common_acc). h2(#common_acc). Common parameter accessors

Each of the @fhiclcpp@ types has the following accessors:
<pre><code class="cpp">
std::string key() const;
std::string comment() const;
bool has_default() const;
par_type parameter_type() const;
</code></pre>

To call these functions, the difference in syntax is crucial:

<pre><code class="cpp">
Atom<int> val { Name("val") };

auto key1 = val.key(); // correct
auto key2 = val().key(); // ! compile-time ERROR - 'val()' is an int, which has no accessor called 'key()'
</code></pre>

h2. h3. @key()@

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:
<pre><code class="ruby">
pset: {
list: [ { particle: electron },
{ particle: muon } ]
}
</code></pre>For a suitably declared set of @fhiclcpp@ parameters, the returned key corresponding to "muon" would be @pset.list[1].particle@.

%{color:red} *N.B.*% The returned value is different than the _relative_ name that is supplied in the @Name("val")@ argument to the @fhiclcpp@ parameter constructor.

_[ The following three functions are used primarily by the validation/description system. Although they are not likely to be directly helpful for the user, the user is still permitted to call them. ]_

h2. h3. @comment()@

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.

h2. h3. @has_default()@

Returns @true@ or @false@ depending on whether the user supplied a default value for the parameter.

h2. h3. @parameter_type()@

Returns an enumeration value based on the parameter type:

<pre><code class="cpp">
enum class par_type {
ATOM, // Atom<T>
TABLE, // Table<T>
SEQ_VECTOR, // Sequence<T>
SEQ_ARRAY, // Sequence<T,std::size_t>
TUPLE, // Tuple<T...>
NTYPES // Signifies invalid parameter
};
</code></pre>