iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ValidValuesSpec.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
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_TYPING_VALIDVALUESSPEC_H
37 #define INCLUDE_NRT_CORE_TYPING_VALIDVALUESSPEC_H
38 
39 #include <vector>
40 #include <string>
41 #include <nrt/Core/Typing/Range.H>
42 #include <boost/regex.hpp>
43 
44 namespace nrt
45 {
46  /*! \defgroup validvalues Specification of valid values
47 
48  This is used by ParameterDef to specify valid values as unrestricted, from a given list, in a range, matching a
49  regex, etc
50 
51  \ingroup typing */
52 
53  /*! @{ */ // **********************************************************************
54 
55  //! Base class for specifying a set of valid values for a type
56  /*! Note when defining new derived valid values specs: make sure you define operator<<() and also that the copy
57  constructor works as intended (which means that you may have to define it explicitly if your data members are
58  complicated). */
59  template <class T>
61  {
62  public:
63  //! Construct, for the base class this is a no-op
64  /*! Note that we make the constructor explicit otherwise we get false hits against strings and what not in our
65  operator<< defined on various ValidValueSpec derivatives. */
66  explicit ValidValuesSpecBase();
67 
68  //! Destructor
69  virtual ~ValidValuesSpecBase();
70 
71  //! Check whether a proposed value is valid, here always returns true
72  virtual bool checkValueValidity(T const & val) const = 0;
73 
74  //! Convert to a readable string
75  /*! Caution, the GUI may wish to parse this string so keep the format tight. Typically,
76  type:[valuesdescription], e.g., see derived classes for None:[], List:[A|B|C], etc. */
77  virtual std::string const str() const = 0;
78  };
79 
80  // ######################################################################
81  //! Open/None valid values spec, anything that T can take is valid
82  template <class T>
84  {
85  public:
86  //! Construct with no specification, any value that T can take goes
87  explicit ValidValuesSpecNone();
88 
89  //! Destructor
90  virtual ~ValidValuesSpecNone();
91 
92  //! Check whether a proposed value is valid, here always returns true
93  virtual bool checkValueValidity(T const & val) const;
94 
95  //! Convert to a readable string
96  /*! Returns None:[] */
97  virtual std::string const str() const;
98  };
99 
100  // ######################################################################
101  //! Finite list valid values spec, everything listed at construction is valid, anything else is not
102  /*! \ingroup typingmisc */
103  template <class T>
105  {
106  public:
107  //! No default constructor, always need to provide a list
108  ValidValuesSpecList() = delete;
109 
110  //! Construct from a given list of valid values in a vector
111  explicit ValidValuesSpecList(std::vector<T> const & valid_list);
112 
113  //! Destructor
114  virtual ~ValidValuesSpecList();
115 
116  //! Check whether a proposed value is valid, returns true iff value is in our list
117  virtual bool checkValueValidity(T const & val) const;
118 
119  //! Convert to a readable string
120  /*! Returns List:[A|B|C] where A, B, C are replaced by the actual elements. */
121  virtual std::string const str() const;
122 
123  protected:
124  std::vector<T> const itsValidList;
125  };
126 
127  // ######################################################################
128  //! Range-based valid values spec, bounds are included
129  /*! \ingroup typingmisc */
130  template <class T>
132  {
133  public:
134  //! No default constructor, always need to provide a range
135  ValidValuesSpecRange() = delete;
136 
137  //! Construct from an nrt::Range of valid values (convention: bounds are inclusive)
138  explicit ValidValuesSpecRange(nrt::Range<T> const & valid_range);
139 
140  //! Destructor
141  virtual ~ValidValuesSpecRange();
142 
143  //! Check whether a proposed value is valid, returns true iff value is in our range (bounds included)
144  virtual bool checkValueValidity(T const & val) const;
145 
146  //! Convert to a readable string
147  /*! Returns Range:[MIN-MAX] where MIN and MAX are replaced by the actual range bounds. */
148  virtual std::string const str() const;
149 
150  protected:
151  nrt::Range<T> const itsValidRange;
152  };
153 
154  // ######################################################################
155  //! Regex-based valid values spec, everything that is a match to the regex is considered valid
156  /*! Uses boost::regex internally (because std::regex is not fully supported by g++ yet). This allows for highly
157  flexible valid values definitions. For example, say you want an int parameter to be in range [0..59] but it could
158  also have value 72, your regex would be:
159 
160  \verbatim
161  ^(([0-5]?[0-9])|72)$
162  \endverbatim
163 
164  You can find on the web regex examples to match things like a valid filename, a valid URL, a valid credit card
165  number, etc. Just make sure your regex is in the syntax expected by boost::regex since several syntaxes are
166  floating around for regular expressions.
167 
168  \ingroup typingmisc */
169  template <class T>
171  {
172  public:
173  //! No default constructor, always need to provide a regex
174  ValidValuesSpecRegex() = delete;
175 
176  //! Construct from a given regex that specifies valid values
177  explicit ValidValuesSpecRegex(boost::regex const & valid_regex);
178 
179  //! Destructor
180  virtual ~ValidValuesSpecRegex();
181 
182  //! Check whether a proposed value is valid, returns true iff value is a match against our regex
183  virtual bool checkValueValidity(T const & val) const;
184 
185  //! Convert to a readable string
186  /*! Returns Regex:[expression] where expression is replaced by the actual regex. */
187  virtual std::string const str() const;
188 
189  protected:
190  boost::regex const itsValidRegex;
191  };
192 
193  /*! @} */ // **********************************************************************
194 
195 } // namespace nrt
196 
197 // Include inlined implementation details that are of no interest to the end user
199 
200 #endif // INCLUDE_NRT_CORE_TYPING_VALIDVALUESSPEC_H
201