Project

General

Profile

Wiki » History » Version 48

Kyle Knoepfel, 12/08/2015 01:34 PM

1 1 Walter E Brown
h1. Wiki
2 1 Walter E Brown
3 14 Walter E Brown
4 1 Walter E Brown
h2. Contents
5 2 Walter E Brown
6 14 Walter E Brown
* [[Wiki#Library overview|Library overview]]
7 14 Walter E Brown
* [[Wiki#The ParameterSet interface|The ParameterSet interface]]
8 26 Walter E Brown
** [[Wiki#Names, keys, and values|Names, keys, and values]]
9 26 Walter E Brown
** [[Wiki#Relationship to ParameterSetID|Relationship to ParameterSetID]]
10 26 Walter E Brown
** [[Wiki#Immutability|Immutability]]
11 26 Walter E Brown
** [[Wiki#Compiler-generated functions|Compiler-generated functions]]
12 26 Walter E Brown
** [[Wiki#Observers|Observers]]
13 26 Walter E Brown
** [[Wiki#Retrievers|Retrievers]]
14 26 Walter E Brown
** [[Wiki#Inserters|Inserters]]
15 26 Walter E Brown
** [[Wiki#Deleters|Deleters]]
16 26 Walter E Brown
** [[Wiki#Comparators|Comparators]]
17 26 Walter E Brown
** [[Wiki#Interface technical summary|Interface technical summary]]
18 1 Walter E Brown
* [[ParameterSet Creation]] (Separate page)
19 39 Kyle Knoepfel
* [[Configuration validation and fhiclcpp types]] (Separate page)
20 40 Kyle Knoepfel
* [[Helper applications]]
21 28 Walter E Brown
* [[Release Notes]] (Separate page)
22 12 Walter E Brown
23 5 Walter E Brown
h2. Library overview
24 1 Walter E Brown
25 42 Kyle Knoepfel
The @fhiclcpp@ library provides types and functions that constitute a _binding_ of the FHiCL specification to C++.  The current version of @fhicl-cpp@ corresponds to FHiCL 3 (see fhicl:document:"FHiCL 3 Quick Start Guide").
26 1 Walter E Brown
27 14 Walter E Brown
The following types are provided, each declared in the @fhicl@ namespace:
28 14 Walter E Brown
29 14 Walter E Brown
* @ParameterSet@, corresponding to a user-specified _configuration_ (a "collection of named values accessible to a user’s program while it is running");
30 48 Kyle Knoepfel
* Any of the @fhiclcpp@ parameter types as described [[Configuration_validation_and_fhiclcpp_types|here]].
31 4 Walter E Brown
* @ParameterSetID@, uniquely identifying a specific value of a @ParameterSet@ instance;
32 7 Walter E Brown
* @ParameterSetRegistry@, automatically registering each @ParameterSet@ instance (or sub-instance) with its corresponding @ParameterSetID@;
33 7 Walter E Brown
* @intermediate_table@, serving as an internal ("raw" or "working") representation of a FHiCL document;
34 4 Walter E Brown
* @extended_value@, representing a FHiCL value within an @intermediate_table@;
35 1 Walter E Brown
* @value_tag@, classifying an @extended_value@ instance; and
36 1 Walter E Brown
* @exception@, describing a circumstance from which the library can't recover.
37 16 Walter E Brown
38 1 Walter E Brown
In addition, the library provides public member functions and (also in the @fhicl@ namespace) free functions to construct, observe, and transform values of these types.
39 1 Walter E Brown
40 1 Walter E Brown
The next section details the interface of the @ParameterSet@ type, likely of greatest interest to most users of this library.  (A separate [[ParameterSet Creation|page]] describes those remaining types and functions that are typically used only while initially producing @ParameterSet@ instances by combining information obtained from a @fhicl@ document with additional information from such sources as a command line and application-specific defaults.)
41 21 Walter E Brown
42 1 Walter E Brown
h2.  The ParameterSet interface
43 1 Walter E Brown
44 26 Walter E Brown
h3. Names, keys, and values
45 21 Walter E Brown
46 26 Walter E Brown
* In the descriptions below, parameters and arguments denoted @name@ are always of type of type @std::string@; each corresponds to FHiCL's notion of a _name_.
47 26 Walter E Brown
* In the descriptions below, parameters and arguments denoted @key@ are always of type of type @std::string@; each also corresponds to FHiCL's notion of a _name_, but when one @ParameterSet@ is nested within another @ParameterSet@, a key may employ the FHiCL _member notation_.
48 20 Walter E Brown
* Each @ParameterSet@ object consists of some number of  keys, each associated with a value of some C++ type.  Such an association is termed a _key-value pair_.  When the key is a simple name, the association is equivalently termed a _name-value pair_.
49 19 Walter E Brown
* A value can be retrieved from a @ParameterSet@ by presenting its corresponding key.  Similarly, a value can be inserted into a @ParameterSet@ by presenting both the value and its desired corresponding key.  
50 41 Kyle Knoepfel
* A @ParameterSet@ contains values of C++ types closely corresponding to FHiCL values as described in the below table.  We define a _FHiCL type_ as any C++ type for which a conversion from the corresponding FHiCL value to that type is supported.
51 41 Kyle Knoepfel
52 41 Kyle Knoepfel
table{margin-left:4em}.
53 41 Kyle Knoepfel
|{background:#fba}. *FHiCL type (C++ type)*|{background:#fba}. *FHiCL value*|{background:#fba}. *FHiCL category*|
54 41 Kyle Knoepfel
|@bool@| boolean |/4. atom |
55 41 Kyle Knoepfel
|(un)signed integer types &
56 41 Kyle Knoepfel
 floating-point types | numeric|
57 41 Kyle Knoepfel
|@std::string@| string |
58 41 Kyle Knoepfel
|@std::complex@| complex |
59 41 Kyle Knoepfel
|@std::array@|/4. sequence |/4. sequence |
60 41 Kyle Knoepfel
|@std::pair@|
61 41 Kyle Knoepfel
|@std::tuple@|
62 41 Kyle Knoepfel
|@std::array@|
63 41 Kyle Knoepfel
|@fhicl::ParameterSet@| table | table |
64 41 Kyle Knoepfel
65 41 Kyle Knoepfel
* Note that a processed FHiCL _document_ also yields a @ParameterSet@.
66 41 Kyle Knoepfel
* A @nil@ value is an atom by definition.
67 1 Walter E Brown
* As an extension to the functionality required of a FHiCL binding, a @ParameterSet@ can contain values of arbitrary user-defined C++ types. The library processes such values via user-supplied functions that convert to the user-defined type.  (In practice, this has been a rarely-used @fhiclcpp@ library feature.)
68 1 Walter E Brown
69 26 Walter E Brown
h3. Relationship to ParameterSetID
70 1 Walter E Brown
71 1 Walter E Brown
* A @ParameterSetID@ is automatically generated from (and thus corresponds to) the value of a @ParameterSet@ object.
72 17 Walter E Brown
* If the value of a @ParameterSet@ object @ps@ is modified in any way (whether by inserting, deleting, or updating any key-value pair), a new @ParameterSetID@ value is generated to correspond to the updated value of @ps@.
73 18 Walter E Brown
74 26 Walter E Brown
h3. Immutability
75 18 Walter E Brown
76 18 Walter E Brown
In practice, most @ParameterSet@ objects, once constructed, are treated as immutable. While such practice is not required, it is preferable because of the relationship of a @ParameterSet@ to a @ParameterSetID@, described above.
77 10 Walter E Brown
78 10 Walter E Brown
h3. Compiler-generated functions
79 10 Walter E Brown
80 10 Walter E Brown
* A default-constructed @ParameterSet@ object is  _empty_; that is, it consists of no key-value pairs.
81 10 Walter E Brown
* A copy-constructed @ParameterSet@ object has the same key-value pairs as did the @ParameterSet@ object from which it was copied.
82 10 Walter E Brown
* A newly assigned-to @ParameterSet@ object has the same key-value pairs as did the @ParameterSet@ object from which it was copied.
83 10 Walter E Brown
84 10 Walter E Brown
h3. Observers
85 1 Walter E Brown
86 43 Kyle Knoepfel
* A call of the form *@ps.is_empty()@* returns @true@ if @ps@ is empty, and returns @false@ otherwise.
87 43 Kyle Knoepfel
* A call of the form *@ps.id()@* returns the @ParameterSetID@ value corresponding to the current value of @ps@.
88 43 Kyle Knoepfel
* A call of the form *@ps.to_string()@* returns a @std::string@ representation of the current value of @ps@.
89 43 Kyle Knoepfel
* A call of the form *@ps.to_compact_string()@* returns a compact @std::string@ representation of the current value of @ps@, including the collapsing of non-trivial nested parameter sets to @@id::<hash>@.
90 43 Kyle Knoepfel
* String-rendered representations of the parameter set can be obtain by any of the calls:
91 43 Kyle Knoepfel
## *@ps.to_indented_string()@* returns an expanded and easier-to-read @std::string@ representation of the current value of @ps@.
92 43 Kyle Knoepfel
## *@ps.to_indented_string(initial_indent_level)@* -- same as 1, but with an optional indent level (@unsigned int@) to increase the left-side margin.
93 43 Kyle Knoepfel
## *@ps.to_indented_string(initial_indent_level, annotate)@* -- same as 2 but additionally annotated (when @annotate == true@) with the filename and line number where the key was defined or overridden.  
94 43 Kyle Knoepfel
## *@ps.to_indented_string(initial_indent_level, print_mode)@* -- same as 3, but allows additional printing formats (as defined in source:fhiclcpp/detail/print_mode.h).
95 43 Kyle Knoepfel
* A call of the form *@ps.get_names()@* returns, as a @std::vector<std::string>@, a list of all names in @ps@.
96 1 Walter E Brown
* A call of the form *@ps.get_pset_names()@* returns, as a @std::vector<std::string>@, a list of all names in @ps@ whose corresponding values are of @ParameterSet@ type.
97 1 Walter E Brown
* A call of the form *@ps.get_src_info(key)@* returns a @std::string@ with the filename and line number (delimited by @':'@) corresponding to where the key was defined or overridden.
98 44 Kyle Knoepfel
* *@ps.has_key(key)@*  returns @true@ if @ps@ contains a pair with a matching name as key (nested keys allowed), @false@ otherwise.
99 44 Kyle Knoepfel
* *@ps.is_key_to_atom(key)@* returns @true@ if @ps@ contains a pair with a matching name as key (no dot notation allowed), and a value which is an atom (@@nil@ is an atom by definition).
100 44 Kyle Knoepfel
* *@ps.is_key_to_sequence(key)@* returns @true@ if @ps@ contains a pair with a matching name as key (no dot notation allowed), and a value which is a sequence.
101 44 Kyle Knoepfel
* *@ps.is_key_to_table(key)@* returns @true@ if @ps@ contains a pair with a matching name as key (no dot notation allowed), and a value which is a table (nested @ParameterSet@).
102 1 Walter E Brown
103 1 Walter E Brown
h3. Retrievers
104 1 Walter E Brown
105 31 Christopher Green
Keys specified as arguments to retrievers may be nested (dot-delimited).
106 31 Christopher Green
107 45 Kyle Knoepfel
* A call of the form *@ps.get<T>(key)@* (or of the variant form @ps.get<T>(key, convert)@) will return the value of type @T@ associated with the key. 
108 20 Walter E Brown
** Either call will throw an exception if:
109 20 Walter E Brown
*** @ps@ contains no pair with a matching key, or 
110 20 Walter E Brown
*** @ps@ does contain a pair with a matching key, but the corresponding value can't be returned as a value of type @T@.
111 20 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
112 20 Walter E Brown
** The variant form is used when @T@ is an arbitrary user-defined type. The @convert@ argument is a user-provided function that converts a given FHiCL value to a value of type @T@.
113 45 Kyle Knoepfel
* A call of the form *@ps.get(key,default_value)@* (or of the variant form @ps.get<T>(key, default_value, convert)@) will return the value of type @T@ associated with the key.
114 20 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
115 20 Walter E Brown
** The variant form is used when @T@ is an arbitrary user-defined type. The @convert@ argument is a user-provided function that converts a given FHiCL value to a value of type @T@.
116 20 Walter E Brown
** Either call will return the supplied @default_value@ (which must be of type @T@) if:
117 20 Walter E Brown
*** @ps@ contains no pair with a matching key, or 
118 20 Walter E Brown
*** @ps@ does contain a pair with a matching key, but the corresponding value can't be returned as a value of type @T@.
119 45 Kyle Knoepfel
* A call of the form *@get_if_present(key, result)@* (or of the variant form @get_if_present(key, result, convert)@) has the following behavior:
120 20 Walter E Brown
** If the supplied key is an empty string, throw an exception.
121 20 Walter E Brown
** If @ps@ contains no pair with a matching key, return @false@.
122 1 Walter E Brown
** If @ps@ does contain a pair with a matching key, but the corresponding value isn't of type @T@, throw an exception.
123 1 Walter E Brown
** Otherwise, set the supplied @result@ (which must be an lvalue expression) to the corresponding value and return @true@.
124 22 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
125 22 Walter E Brown
** The variant form is used when @T@ is an arbitrary user-defined type. The @convert@ argument is a user-provided function that converts a given FHiCL value to a value of type @T@.
126 22 Walter E Brown
127 1 Walter E Brown
h3. Inserters
128 1 Walter E Brown
129 31 Christopher Green
Note that all @key@ arguments to inserters must be names: it is an error to specify a nested (dot-delimited) key.
130 31 Christopher Green
131 46 Kyle Knoepfel
* A call of the form *@ps.put(name, value)@* will insert into @ps@ a name-value pair composed of the given name and the given value.
132 31 Christopher Green
** If @ps@ already contains a pair with the given name, a @cant_insert@ exception is thrown.
133 1 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
134 31 Christopher Green
** The type of the supplied value must either be a [[Wiki#FHiCL_type|FHiCL type]], or the user must define a function @encode(X const & x)@ in the same namespace as @X@ which returns the result of calling @fhicl::encode()@ on one of the aforementioned types. As a fallback, a @boost::lexical_cast()@ will be attempted to decode @x@.
135 46 Kyle Knoepfel
* A call of the form *@ps.put(name)@* will insert into @ps@ a name-value pair composed of the given name and the library's equivalent of a FHiCL @nil@ value.
136 31 Christopher Green
** If @ps@ already contains a pair with the given name, a @cant_insert@ exception is thrown.
137 31 Christopher Green
** Otherwise, a new pair is constructed and inserted into @ps@.
138 46 Kyle Knoepfel
* A call of the form *@ps.put_or_replace(name, value)@* will insert into @ps@ a name-value pair composed of the given name and the given value.
139 1 Walter E Brown
** If @ps@ already contains a pair with the given name, that pair's value component is replaced.
140 1 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
141 46 Kyle Knoepfel
* A call of the form *@ps.put(name)@* will insert into @ps@ a name-value pair composed of the given name and the library's equivalent of a FHiCL @nil@ value.
142 24 Walter E Brown
** If @ps@ already contains a pair with the given name, that pair's value component is replaced.
143 24 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
144 46 Kyle Knoepfel
* A call of the form *@ps.put_or_replace_compatible(name, value)@* will insert into @ps@ a name-value pair composed of the given name and the given value.
145 31 Christopher Green
** If @ps@ already contains a pair with the given name, that pair's value component is replaced if and only if it is of a compatible [[Wiki#FHiCL_categories|FHiCL category]]. A @nil@ value is compatible with all classifications. If the replacement value is not compatible with the existing value, a @cant_insert@ exception is thrown.
146 31 Christopher Green
** Otherwise, a new pair is constructed and inserted into @ps@.
147 10 Walter E Brown
148 11 Walter E Brown
h3. Deleters
149 21 Walter E Brown
150 47 Kyle Knoepfel
A call of the form *@ps.erase(name)@* will attempt to remove from @ps@ the name-value pair with matching name and will return @true@ if successful and @false@ otherwise (_i.e._, if @ps@ contains no pair with the specified name).
151 10 Walter E Brown
152 10 Walter E Brown
h3. Comparators
153 14 Walter E Brown
154 10 Walter E Brown
Two @ParameterSet@ objects may be compared for equality or inequality via the corresponding conventional operator notations.  The objects are considered equal if and only if their respective @ParameterSetID@ values are equal.
155 10 Walter E Brown
156 10 Walter E Brown
h3. Interface technical summary
157 10 Walter E Brown
158 30 Christopher Green
See source:fhiclcpp/ParameterSet.h.
159 10 Walter E Brown
160 1 Walter E Brown
</code></pre>