Main MRPT website > C++ reference for MRPT 1.4.0
CConfigFileBase.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2016, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 #ifndef CConfigFileBase_H
10 #define CConfigFileBase_H
11 
12 #include <mrpt/utils/utils_defs.h>
14 
15 /*---------------------------------------------------------------
16  Class
17  ---------------------------------------------------------------*/
18 namespace mrpt
19 {
20 namespace utils
21 {
22  // Frwd. decl:
23  template <typename ENUMTYPE> struct TEnumType;
24  class CConfigFilePrefixer;
25 
26  /** This class allows loading and storing values and vectors of different types from a configuration text, which can be implemented as a ".ini" file, a memory-stored string, etc...
27  * This is a virtual class, use only as a pointer to an implementation of one of the derived classes.
28  * \ingroup mrpt_base_grp
29  */
31  {
32  friend class CConfigFilePrefixer;
33  protected:
34  /** A virtual method to write a generic string.
35  */
36  virtual void writeString(const std::string &section,const std::string &name, const std::string &str) = 0;
37 
38  /** Write a generic string with optional padding and a comment field ("// ...") at the end of the line. */
39  void writeString(const std::string &section,const std::string &name, const std::string &str, const int name_padding_width, const int value_padding_width, const std::string &comment);
40 
41  /** A virtual method to read a generic string.
42  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
43  */
44  virtual std::string readString(
45  const std::string &section,
46  const std::string &name,
47  const std::string &defaultStr,
48  bool failIfNotFound = false) const = 0;
49 
50  public:
51  /** Virtual destructor...
52  */
53  virtual ~CConfigFileBase()
54  {
55  }
56 
57  /** Returns a list with all the section names.
58  */
59  virtual void getAllSections( vector_string &sections ) const = 0 ;
60 
61  /** Returs a list with all the keys into a section.
62  */
63  virtual void getAllKeys( const std::string &section, vector_string &keys ) const = 0;
64 
65  /** Checks if a given section exists (name is case insensitive) */
66  bool sectionExists( const std::string &section_name) const;
67 
68  /** @name Save a configuration parameter. Optionally pads with spaces up to the desired width in number of characters (-1: no fill), and add a final comment field at the end of the line (a "// " prefix is automatically inserted).
69  * @{ */
70  void write(const std::string &section, const std::string &name, double value, const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
71  void write(const std::string &section, const std::string &name, float value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
72  void write(const std::string &section, const std::string &name, int value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
73  void write(const std::string &section, const std::string &name, uint32_t value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
74  void write(const std::string &section, const std::string &name, uint64_t value, const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
75  void write(const std::string &section, const std::string &name, const std::string &value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
76  void write(const std::string &section, const std::string &name, const std::vector<int> &value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
77  void write(const std::string &section, const std::string &name, const std::vector<unsigned int> &value, const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
78  void write(const std::string &section, const std::string &name, const std::vector<float> &value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
79  void write(const std::string &section, const std::string &name, const std::vector<double> &value, const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
80  void write(const std::string &section, const std::string &name, const std::vector<bool> &value , const int name_padding_width=-1, const int value_padding_width=-1, const std::string &comment = std::string() );
81  /** @} */
82 
83  /** Reads a configuration parameter of type "double"
84  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
85  */
86  double read_double(const std::string &section, const std::string &name, double defaultValue, bool failIfNotFound = false) const;
87 
88  /** Reads a configuration parameter of type "float"
89  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
90  */
91  float read_float(const std::string &section, const std::string &name, float defaultValue, bool failIfNotFound = false) const;
92 
93  /** Reads a configuration parameter of type "bool", codified as "1"/"0" or "true"/"false" or "yes"/"no" for true/false, repectively.
94  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
95  */
96  bool read_bool(const std::string &section, const std::string &name, bool defaultValue, bool failIfNotFound = false) const;
97 
98  /** Reads a configuration parameter of type "int"
99  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
100  */
101  int read_int(const std::string &section, const std::string &name, int defaultValue, bool failIfNotFound = false) const;
102 
103  /** Reads a configuration parameter of type "uint64_t": As in all other methods, the numeric value can be in decimal or hexadecimal with the prefix "0x"
104  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
105  */
106  uint64_t read_uint64_t(const std::string &section, const std::string &name, uint64_t defaultValue, bool failIfNotFound = false ) const;
107 
108  /** Reads a configuration parameter of type "string"
109  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
110  */
111  std::string read_string(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
112 
113  /** Reads a configuration parameter of type "string", and keeps only the first word (this can be used to eliminate possible comments at the end of the line)
114  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
115  */
116  std::string read_string_first_word(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
117 
118  /** Reads a configuration parameter of type vector, stored in the file as a string: "[v1 v2 v3 ... ]", where spaces could also be commas.
119  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
120  */
121  template <class VECTOR_TYPE>
123  const std::string & section,
124  const std::string & name,
125  const VECTOR_TYPE & defaultValue,
126  VECTOR_TYPE & outValues,
127  bool failIfNotFound = false) const
128  {
129  std::string aux ( readString(section, name, "",failIfNotFound ) );
130  // Parse the text into a vector:
131  std::vector<std::string> tokens;
132  mrpt::system::tokenize( aux,"[], \t",tokens);
133 
134  if (tokens.size()==0)
135  {
136  outValues = defaultValue;
137  }
138  else
139  {
140  // Parse to numeric type:
141  const size_t N = tokens.size();
142  outValues.resize( N );
143  for (size_t i=0;i<N;i++)
144  {
145  std::stringstream ss(tokens[i]);
146  ss >> outValues[i];
147  }
148  }
149  }
150 
151 
152  /** Reads a configuration parameter as a matrix written in a matlab-like format - for example: "[2 3 4 ; 7 8 9]"
153  * This template method can be instantiated for matrices of the types: int, long, unsinged int, unsigned long, float, double, long double
154  * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
155  */
156  template <class MATRIX_TYPE>
158  const std::string &section,
159  const std::string &name,
160  MATRIX_TYPE &outMatrix,
161  const MATRIX_TYPE &defaultMatrix = MATRIX_TYPE(),
162  bool failIfNotFound = false ) const
163  {
164  std::string aux = readString(section, name, "",failIfNotFound );
165  if (aux.empty())
166  outMatrix = defaultMatrix;
167  else
168  {
169  // Parse the text into a vector:
170  if (!outMatrix.fromMatlabStringFormat(aux))
171  THROW_EXCEPTION_CUSTOM_MSG1("Error parsing matrix: '%s'",aux.c_str())
172  }
173  }
174 
175  /** Reads an "enum" value, where the value in the config file can be either a numerical value or the symbolic name, for example:
176  * In the code:
177  * \code
178  * enum my_type_t { type_foo=0, type_bar };
179  * \endcode
180  * In the config file:
181  * \code
182  * [section]
183  * type = type_bar // Use the symbolic name, or
184  * type = 1 // use the numerical value (both lines will be equivalent)
185  * \endcode
186  * Which can be loaded with:
187  * \code
188  * cfgfile.read_enum<my_type_t>("section","type", type_foo );
189  * \endcode
190  *
191  * \note For an enum type to work with this template it is required that it defines a specialization of mrpt::utils::TEnumType
192  */
193  template <typename ENUMTYPE>
194  ENUMTYPE read_enum(const std::string &section, const std::string &name, const ENUMTYPE &defaultValue, bool failIfNotFound = false) const
195  {
196  MRPT_START
197  const std::string sVal = read_string_first_word(section,name,"",failIfNotFound);
198  if (sVal.empty()) return defaultValue;
199  // Text or numeric value?
200  if (::isdigit(sVal[0]))
201  { // Seems a number:
202  return static_cast<ENUMTYPE>(::atoi(&sVal[0]));
203  }
204  else
205  { // Name look-up:
206  try {
208  } catch (std::exception &)
209  {
210  THROW_EXCEPTION(format("Invalid value '%s' for enum type while reading key='%s'.",sVal.c_str(),name.c_str()))
211  }
212  }
213  MRPT_END
214  }
215 
216 
217  }; // End of class def.
218 
219  /** An useful macro for loading variables stored in a INI-like file under a key with the same name that the variable, and assigning the variable the current value if not found in the config file.
220  * The variableType must be the suffix of "read_XXX" functions, i.e. int, bool,...
221  */
222 #define MRPT_LOAD_CONFIG_VAR(variableName,variableType,configFileObject,sectionNameStr) \
223  { variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName); }
224 
225  /** Loads a float variable, stored as radians but entered in the INI-file as degrees:
226  */
227 #define MRPT_LOAD_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
228  { variableName = DEG2RAD( configFileObject.read_float(sectionNameStr,#variableName, RAD2DEG(variableName)) ); }
229 
230 #define MRPT_LOAD_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
231  { variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName)); }
232 
233 
234 #define MRPT_LOAD_HERE_CONFIG_VAR(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
235  targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,false);
236 
237 #define MRPT_LOAD_HERE_CONFIG_VAR_NO_DEFAULT(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
238  { try { \
239  targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true); \
240  } catch (std::exception &) \
241  { \
242  THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
243  } }\
244 
245 
246 #define MRPT_LOAD_CONFIG_VAR_NO_DEFAULT(variableName,variableType,configFileObject,sectionNameStr) \
247  { try { \
248  variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true); \
249  } catch (std::exception &) \
250  { \
251  THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
252  } }\
253 
254 #define MRPT_LOAD_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
255  { try { \
256  variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true)); \
257  } catch (std::exception &) \
258  { \
259  THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
260  } }\
261 
262 
263 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
264  targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable));
265 
266 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
267  { try { \
268  targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true)); \
269  } catch (std::exception &) \
270  { \
271  THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
272  } }\
273 
274 
275 #define MRPT_SAVE_CONFIG_VAR(variableName,configFileObject,sectionNameStr) \
276  { configFileObject.write(sectionNameStr,#variableName,variableName); }
277 
278 #define MRPT_SAVE_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
279  { configFileObject.write(sectionNameStr,#variableName, RAD2DEG(variableName)); }
280 
281 
282  } // End of namespace
283 } // end of namespace
284 #endif
static ENUMTYPE name2value(const std::string &name)
Gives the numerical name for a given enum text name on unknown enum name.
Definition: TEnumType.h:35
A wrapper for other CConfigFileBase-based objects that prefixes a given token to every key and/or sec...
ENUMTYPE read_enum(const std::string &section, const std::string &name, const ENUMTYPE &defaultValue, bool failIfNotFound=false) const
Reads an "enum" value, where the value in the config file can be either a numerical value or the symb...
std::string BASE_IMPEXP format(const char *fmt,...) MRPT_printf_format_check(1
A std::string version of C sprintf.
#define THROW_EXCEPTION(msg)
void read_vector(const std::string &section, const std::string &name, const VECTOR_TYPE &defaultValue, VECTOR_TYPE &outValues, bool failIfNotFound=false) const
Reads a configuration parameter of type vector, stored in the file as a string: "[v1 v2 v3 ...
void BASE_IMPEXP tokenize(const std::string &inString, const std::string &inDelimiters, std::deque< std::string > &outTokens, bool skipBlankTokens=true) MRPT_NO_THROWS
Tokenizes a string according to a set of delimiting characters.
This class allows loading and storing values and vectors of different types from a configuration text...
virtual ~CConfigFileBase()
Virtual destructor...
std::vector< std::string > vector_string
A type for passing a vector of strings.
Definition: types_simple.h:30
#define MRPT_END
A helper class that can convert an enum value into its textual representation, and viceversa...
#define MRPT_START
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
#define THROW_EXCEPTION_CUSTOM_MSG1(msg, param1)
void read_matrix(const std::string &section, const std::string &name, MATRIX_TYPE &outMatrix, const MATRIX_TYPE &defaultMatrix=MATRIX_TYPE(), bool failIfNotFound=false) const
Reads a configuration parameter as a matrix written in a matlab-like format - for example: "[2 3 4 ; ...



Page generated by Doxygen 1.8.11 for MRPT 1.4.0 SVN: at Mon Aug 15 11:50:21 UTC 2016