iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ParameterDef.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_MODEL_PARAMETERDEF_H
37 #define INCLUDE_NRT_CORE_MODEL_PARAMETERDEF_H
38 
40 #include <memory>
41 
42 namespace nrt
43 {
44  template <class T> class ParameterCore;
45 
46  // ######################################################################
47  //! A category to which multiple ParameterDefs can belong
48  /*! ParameterDefs which belong to the same category will show up next to each other when the user requests --help on
49  the command line.
50  \ingroup parameter */
52  {
53  //! Constructor
54  /*! \param name_ The name of this category.
55  \param description_ An optional short description of the category */
56  ParameterCategory(std::string const & name_ = "General Use Options", std::string const & description_ = "");
57 
58  std::string name; //!< The name of the category
59  std::string description; //!< An optional short description of the category
60  };
61 
62  // ######################################################################
63  //! Definitions of parameter flags
64  /*! \ingroup parameter */
65  enum class ParameterFlags
66  {
67  None = 0, //!< No flags
68  NoOnlineChanges = 1 //!< This parameter does not allow online changes
69  // Programmer note: use only single bits as we combine flags by or'ing
70  };
71 
72  //! Operator to OR parameter flags
73  /*! \relates ParameterFlags */
74  constexpr ParameterFlags operator|(ParameterFlags f, ParameterFlags g);
75 
76  //! Operator to AND parameter flags
77  /*! \relates ParameterFlags */
78  constexpr ParameterFlags operator&(ParameterFlags f, ParameterFlags g);
79 
80  // ######################################################################
81  //! Base class for a Paramater definition
82  /*! This exposes the string-based interface to the definition while derived class templates will expose the
83  value-based interface. Users should never directly create a ParameterDefBase, but should instead create a properly
84  templated ParemeterDef<T>
85  \ingroup parameter */
87  {
88  public:
89  //! Construct a ParameterDefBase
90  ParameterDefBase(std::string const & name, std::string const & description,
92  ParameterFlags const pflags = ParameterFlags::None);
93 
94  //! Destructor
95  virtual ~ParameterDefBase();
96 
97  //! The parameter name (without the leading "--")
98  std::string const & name() const;
99 
100  //! Description of what the parameter does
101  std::string const & description() const;
102 
103  //! The Parameter category
104  ParameterCategory const & category() const;
105 
106  //! Default value in string representation
107  virtual std::string const defaultValueString() const = 0;
108 
109  //! Valid values in string representation
110  virtual std::string const validValuesString() const = 0;
111 
112  //! The Parameter Flags
113  ParameterFlags flags() const;
114 
115  protected:
116  std::string itsName;
117  std::string itsDescription;
118  ParameterCategory itsCategory;
119  ParameterFlags itsFlags;
120  };
121 
122  // ######################################################################
123  //! A Parameter Definition
124  /*! ParameterDef is used to specify the name, description, default value, category, and optionally valid values for a
125  Parameter.
126 
127  \see nrt/Core/Typing/ValidValuesSpec.H for definitions of specifications for valid values.
128 
129  \ingroup parameter */
130  template <class T>
132  {
133  public:
134  //! Construct a ParameterDef with no given valid values, valid values are whatever T can take
135  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
137  ParameterFlags const pflags = ParameterFlags::None);
138 
139  //! Create a Parameter definition with specified valid values from a ValidValueSpec
140  template <template <typename> class ValidValuesSpec>
141  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
142  ValidValuesSpec<T> const & validValuesSpec,
144  ParameterFlags const pflags = ParameterFlags::None);
145 
146  //! Shorthand to create a Parameter definition with specified valid values from a list
147  /*! If your Parameter can only be set to a finite list of values, you can use this convenience constructor
148  to specify them.
149 
150  For example, if you want to create a Parameter for some kernel convolution for which you only have
151  kernels of sizes 3, 5, 7 and 9 you could create a ParameterDef as follows:
152  @code
153  ParameterDef<uint> KernelSizeDef("kernel-size", "The size of the convolution kernel", 3, {3,5,7,9});
154  @endcode
155 
156  Parameters created with this kind of list definition will show up as a drop-down box in nrtDesigner, allowing
157  users to select only from your specified list of values. */
158  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
159  std::vector<T> const & validvalues, ParameterCategory const & category = ParameterCategory(),
160  ParameterFlags const pflags = ParameterFlags::None);
161 
162  //! Shorthand to create a Parameter definition with specified valid values from a range (bounds inclusive)
163  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
164  nrt::Range<T> const & validrange, ParameterCategory const & category = ParameterCategory(),
165  ParameterFlags const pflags = ParameterFlags::None);
166 
167  //! Shorthand to create a Parameter definition with specified valid values in a regex
168  /*! This allows for highly flexible valid values definitions. For example, say you want an int parameter to be in
169  range [0..59] but it could also have value 72, your regex would be:
170 
171  \verbatim
172  ^(([0-5]?[0-9])|72)$
173  \endverbatim */
174  ParameterDef(std::string const & name, std::string const & description, T const & defaultValue,
175  boost::regex const & validregex, ParameterCategory const & category = ParameterCategory(),
176  ParameterFlags const pflags = ParameterFlags::None);
177 
178  //! Get the default value that was specified for this Parameter definition
179  T const defaultValue() const;
180 
181  //! Default value in string representation
182  virtual std::string const defaultValueString() const;
183 
184  //! Valid values in string representation
185  virtual std::string const validValuesString() const;
186 
187  private:
188  friend class ParameterCore<T>;
189  T itsDefaultValue;
190  std::shared_ptr<ValidValuesSpecBase<T> > itsValidValuesSpec;
191  void checkDefaultValue();
192  };
193 
194 } // namespace nrt
195 
196 // Include inlined implementation details that are of no interest to the end user
198 
199 #endif // INCLUDE_NRT_CORE_MODEL_PARAMETERDEF_H
200