Project

General

Profile

Wiki » History » Version 24

Walter E Brown, 03/05/2012 12:06 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 1 Walter E Brown
* [[Release Notes]] (Separate page)
9 12 Walter E Brown
10 14 Walter E Brown
11 5 Walter E Brown
h2. Library overview
12 1 Walter E Brown
13 14 Walter E Brown
The @fhiclcpp@ library provides types and functions that constitute a _binding_ of the FHiCL specification to C++.  (See https://cdcvs.fnal.gov/redmine/attachments/5348/quick_start.pdf for an introduction to FHiCL nomenclature and concepts.)
14 1 Walter E Brown
15 14 Walter E Brown
The following types are provided, each declared in the @fhicl@ namespace:
16 14 Walter E Brown
17 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");
18 4 Walter E Brown
* @ParameterSetID@, uniquely identifying a specific value of a @ParameterSet@ instance;
19 7 Walter E Brown
* @ParameterSetRegistry@, automatically registering each @ParameterSet@ instance (or sub-instance) with its corresponding @ParameterSetID@;
20 7 Walter E Brown
* @intermediate_table@, serving as an internal ("raw" or "working") representation of a FHiCL document;
21 4 Walter E Brown
* @extended_value@, representing a FHiCL value within an @intermediate_table@;
22 1 Walter E Brown
* @value_tag@, classifying an @extended_value@ instance; and
23 1 Walter E Brown
* @exception@, describing a circumstance from which the library can't recover.
24 5 Walter E Brown
25 14 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.
26 1 Walter E Brown
27 16 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 page will describe 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.)
28 1 Walter E Brown
29 1 Walter E Brown
30 14 Walter E Brown
h2.  The ParameterSet interface
31 1 Walter E Brown
32 21 Walter E Brown
h3. @ParameterSet@ names, keys, and values
33 1 Walter E Brown
34 21 Walter E Brown
* In the descriptions below, parameters and arguments denoted @name@ are always of type of type @std::string@; a name corresponds to FHiCL's notion of a _name_.
35 21 Walter E Brown
* In the descriptions below, parameters and arguments denoted @key@ are always of type of type @std::string@; a key 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_.
36 21 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_.
37 16 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.  
38 20 Walter E Brown
* A @ParameterSet@ contains values of C++ types closely corresponding to FHiCL values.  We refer to the C++ types in the following list as _FHiCL types_.
39 19 Walter E Brown
** The C++ standard @bool@ type corresponds to FHiCL's notion of a _boolean value_.
40 19 Walter E Brown
** The C++ standard signed and unsigned integer types, as well as the C++ standard floating-point types, correspond to FHiCL's notion of a _numeric value_.
41 1 Walter E Brown
** The C++ @std::complex<>@ types correspond to FHiCL's notion of a _complex value_.
42 19 Walter E Brown
** The C++ @std::string@ type corresponds to FHiCL's notion of a _string value_.
43 19 Walter E Brown
** The C++ @std::vector@ types correspond to FHiCL's notion of a _sequence value_.  Only homogeneous sequences are supported in this binding.
44 20 Walter E Brown
** The @fhicl::ParameterSet@ type corresponds to FHiCL's notion of a _table value_. Note that a processed FHiCL _document_ also yields a @ParameterSet@.
45 21 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.)
46 9 Walter E Brown
47 1 Walter E Brown
h3. Relating @ParameterSetID@ to @ParameterSet@
48 1 Walter E Brown
49 1 Walter E Brown
* A @ParameterSetID@ is automatically generated from (and thus corresponds to) the value of a @ParameterSet@ object.
50 1 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@.
51 17 Walter E Brown
52 18 Walter E Brown
h3. @ParameterSet@ immutability
53 18 Walter E Brown
54 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.
55 18 Walter E Brown
56 10 Walter E Brown
h3. Compiler-generated functions
57 10 Walter E Brown
58 10 Walter E Brown
* A default-constructed @ParameterSet@ object is  _empty_; that is, it consists of no key-value pairs.
59 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.
60 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.
61 10 Walter E Brown
62 10 Walter E Brown
h3. Observers
63 10 Walter E Brown
64 10 Walter E Brown
* A call of the form @ps.is_empty()@ returns @true@ if @ps@ is empty, and returns @false@ otherwise.
65 10 Walter E Brown
* A call of the form @ps.id()@ returns the @ParameterSetID@ value corresponding to the current value of @ps@.
66 10 Walter E Brown
* A call of the form @ps.tostring()@ returns a compact @std::string@ representation of the current value of @ps@.
67 15 Walter E Brown
* A call of the form @ps.to_indented_string()@ returns an expanded and easier-to-read @std::string@ representation of the current value of @ps@.
68 22 Walter E Brown
* A call of the form @ps.get_keys()@ returns, as a @std::vector<std::string>@, a list of all names in @ps@.
69 22 Walter E Brown
* A call of the form @ps.get_pset_keys()@ returns, as a @std::vector<std::string>@, a list of all names in @ps@ whose corresponding values are of @ParameterSet@ type.
70 1 Walter E Brown
71 1 Walter E Brown
h3. Retrievers
72 1 Walter E Brown
73 20 Walter E Brown
* 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. 
74 20 Walter E Brown
** Either call will throw an exception if:
75 20 Walter E Brown
*** @ps@ contains no pair with a matching key, or 
76 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@.
77 20 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
78 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@.
79 20 Walter E Brown
* 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.
80 20 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
81 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@.
82 20 Walter E Brown
** Either call will return the supplied @default_value@ (which must be of type @T@) if:
83 20 Walter E Brown
*** @ps@ contains no pair with a matching key, or 
84 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@.
85 20 Walter E Brown
* 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:
86 20 Walter E Brown
** If the supplied key is an empty string, throw an exception.
87 20 Walter E Brown
** If @ps@ contains no pair with a matching key, return @false@.
88 20 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.
89 20 Walter E Brown
** Otherwise, set the supplied @result@ (which must be an lvalue expression) to the corresponding value and return @true@.
90 20 Walter E Brown
** The first form is used when the type @T@ is corresponds to a FHiCL value.
91 1 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@.
92 1 Walter E Brown
93 1 Walter E Brown
h3. Inserters
94 1 Walter E Brown
95 22 Walter E Brown
* 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.
96 22 Walter E Brown
** If @ps@ already contains a pair with the given name, that pair's value component is replaced by the value provided in the call.
97 22 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
98 22 Walter E Brown
** The type of the supplied value must be a FHiCL type.  If it is not, either the code will fail to compile or else the compiled code will throw an exception.
99 24 Walter E Brown
* 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.
100 24 Walter E Brown
** If @ps@ already contains a pair with the given name, that pair's value component is replaced.
101 1 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
102 24 Walter E Brown
* A call of the form @ps.insert(name, value)@ will insert into @ps@ a name-value pair composed of the given name and the given value.
103 24 Walter E Brown
** If @ps@ already contains a pair with the given name, that pair's value component is replaced.
104 24 Walter E Brown
** Otherwise, a new pair is constructed and inserted into @ps@.
105 24 Walter E Brown
** The supplied value may be of any C++ type and will be inserted as-is (_i.e._, will be treated strictly as a user-defined type).  It is therefore recommended that this call not be used with values of any FHiCL type.
106 21 Walter E Brown
107 10 Walter E Brown
h3. Deleters
108 11 Walter E Brown
109 21 Walter E Brown
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).
110 10 Walter E Brown
111 10 Walter E Brown
h3. Comparators
112 10 Walter E Brown
113 14 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.
114 10 Walter E Brown
115 10 Walter E Brown
h3. Interface technical summary
116 10 Walter E Brown
117 10 Walter E Brown
<pre><code class="cplusplus">
118 4 Walter E Brown
class ParameterSet
119 4 Walter E Brown
{
120 4 Walter E Brown
public:
121 4 Walter E Brown
  // use compiler-generated default c'tor, d'tor, and copy functions
122 4 Walter E Brown
123 4 Walter E Brown
  // observers:
124 4 Walter E Brown
  bool                      is_empty          ( ) const;
125 4 Walter E Brown
  ParameterSetID            id                ( ) const;
126 4 Walter E Brown
  std::string               to_string         ( ) const;
127 4 Walter E Brown
  std::string               to_indented_string( ) const;
128 4 Walter E Brown
  std::vector<std::string>  get_keys          ( ) const;
129 4 Walter E Brown
  std::vector<std::string>  get_pset_keys     ( ) const;
130 4 Walter E Brown
131 4 Walter E Brown
  // retrievers:
132 4 Walter E Brown
  template< class T >
133 4 Walter E Brown
    bool get_if_present( std::string const & key, T & value ) const;
134 4 Walter E Brown
  template< class T, class Via >
135 4 Walter E Brown
    bool get_if_present( std::string const & key, T & value, T convert(Via const &) ) const;
136 1 Walter E Brown
  template< class T >
137 4 Walter E Brown
    T  get( std::string const & key ) const;
138 4 Walter E Brown
  template< class T, class Via >
139 1 Walter E Brown
    T  get( std::string const & key, T convert(Via const &) ) const;
140 1 Walter E Brown
  template< class T >
141 1 Walter E Brown
    T  get( std::string const & key, T const & default_value ) const;
142 4 Walter E Brown
  template< class T, class Via >
143 1 Walter E Brown
    T  get( std::string const & key, T const & default_value, T convert(Via const &) ) const;
144 1 Walter E Brown
145 8 Walter E Brown
  // inserters:
146 21 Walter E Brown
  void  insert( std::string const & name, boost::any const & value );
147 21 Walter E Brown
  void  put( std::string const & name );  // implicit nil value
148 8 Walter E Brown
  template< class T >
149 21 Walter E Brown
    void  put( std::string const & name, T const & value );
150 8 Walter E Brown
151 8 Walter E Brown
  // deleters:
152 21 Walter E Brown
  bool  erase( std::string const & name );
153 4 Walter E Brown
154 4 Walter E Brown
  // comparators:
155 4 Walter E Brown
  bool  operator == ( ParameterSet const & other ) const;
156 4 Walter E Brown
  bool  operator != ( ParameterSet const & other ) const;
157 4 Walter E Brown
158 4 Walter E Brown
};  // ParameterSet
159 10 Walter E Brown
</code></pre>