The MRPT project: CConfigFileBase.h Source File

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2010  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 #ifndef  CConfigFileBase_H
00029 #define  CConfigFileBase_H
00030 
00031 #include <mrpt/utils/utils_defs.h>
00032 
00033 #include <mrpt/math/CMatrixTemplate.h>
00034 
00035 /*---------------------------------------------------------------
00036         Class
00037   ---------------------------------------------------------------*/
00038 namespace mrpt
00039 {
00040 namespace utils
00041 {
00042         /** 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...
00043           *   This is a virtual class, use only as a pointer to an implementation of one of the derived classes.
00044           */
00045         class MRPTDLLIMPEXP CConfigFileBase
00046         {
00047         protected:
00048                 /** A virtual method to write a generic string.
00049                   */
00050                 virtual void  writeString(const std::string &section,const std::string &name, const std::string &str) = 0;
00051 
00052                 /** A virtual method to read a generic string.
00053          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00054                  */
00055                 virtual std::string  readString(
00056             const std::string &section,
00057             const std::string &name,
00058             const std::string &defaultStr,
00059             bool failIfNotFound = false) const = 0;
00060 
00061         public:
00062         /** Virtual destructor...
00063          */
00064          virtual ~CConfigFileBase()
00065          {
00066          }
00067 
00068                 /** Returns a list with all the section names.
00069                   */
00070                 virtual void getAllSections( vector_string      &sections ) const = 0 ;
00071                 
00072                 /** Returs a list with all the keys into a section.
00073                   */
00074                 virtual void getAllKeys( const std::string section, vector_string       &keys ) const = 0;
00075 
00076                 /** Checks if a given section exists (name is case insensitive) */
00077                 bool sectionExists( const std::string &section_name) const;
00078 
00079                 /** Save a configuration parameter of type "double"
00080                  */
00081                 void  write(const std::string &section, const std::string &name, double value);
00082 
00083                 /** Save a configuration parameter of type "float"
00084                  */
00085                 void  write(const std::string &section, const std::string &name, float value);
00086 
00087                 /** Save a configuration parameter of type "int"
00088                  */
00089                 void  write(const std::string &section, const std::string &name, int value);
00090 
00091                 /** Save a configuration parameter of type "unsigned int"
00092                  */
00093                 void  write(const std::string &section, const std::string &name, unsigned int value);
00094 
00095                 /** Save a configuration parameter of type "string"
00096                  */
00097                 void  write(const std::string &section, const std::string &name, const std::string &value);
00098 
00099                 /** Save a configuration parameter of type "std::vector<int>"
00100                  */
00101                 void  write(const std::string &section, const std::string &name, const std::vector<int> &value);
00102 
00103                 /** Save a configuration parameter of type "std::vector<unsigned int>"
00104                  */
00105                 void  write(const std::string &section, const std::string &name, const std::vector<unsigned int> &value);
00106 
00107                 /** Save a configuration parameter of type "std::vector<float>"
00108                  */
00109                 void  write(const std::string &section, const std::string &name, const std::vector<float> &value);
00110 
00111                 /** Save a configuration parameter of type "std::vector<double>"
00112                  */
00113                 void  write(const std::string &section, const std::string &name, const std::vector<double> &value);
00114 
00115                 /** Save a configuration parameter of type "std::vector<bool>"
00116                  */
00117                 void  write(const std::string &section, const std::string &name, const std::vector<bool> &value);
00118 
00119                 /** Reads a configuration parameter of type "double"
00120          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00121                  */
00122                 double  read_double(const std::string &section, const std::string &name, double defaultValue, bool failIfNotFound = false) const;
00123 
00124                 /** Reads a configuration parameter of type "float"
00125          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00126                  */
00127                 float  read_float(const std::string &section, const std::string &name, float defaultValue, bool failIfNotFound = false) const;
00128 
00129                 /** Reads a configuration parameter of type "bool", codified as "1"/"0" or "true"/"false" or "yes"/"no" for true/false, repectively.
00130          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00131                  */
00132                 bool  read_bool(const std::string &section, const std::string &name, bool defaultValue, bool failIfNotFound = false) const;
00133 
00134                 /** Reads a configuration parameter of type "int"
00135          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00136                  */
00137                 int  read_int(const std::string &section, const std::string &name, int defaultValue, bool failIfNotFound = false) const;
00138 
00139                 /** 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"
00140          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00141                  */
00142                 uint64_t read_uint64_t(const std::string &section, const std::string &name, uint64_t defaultValue, bool failIfNotFound = false ) const;
00143 
00144                 /** Reads a configuration parameter of type "string"
00145          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00146                  */
00147                 std::string  read_string(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
00148 
00149                 /** 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)
00150          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00151                  */
00152                 std::string  read_string_first_word(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
00153 
00154                 /** Reads a configuration parameter of type "std::vector<unsigned int>"
00155          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00156                  */
00157                 void  read_vector(
00158                         const std::string                                       &section,
00159                         const std::string                                       &name,
00160                         const std::vector<uint32_t>             &defaultValue,
00161                         std::vector<uint32_t>                   &outValues,
00162                         bool failIfNotFound = false) const;
00163 
00164                 /** Reads a configuration parameter of type "std::vector<int>"
00165          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00166                  */
00167                 void  read_vector(
00168                         const std::string                       &section,
00169                         const std::string                       &name,
00170                         const std::vector<int32_t>              &defaultValue,
00171                         std::vector<int32_t>                    &outValues,
00172                         bool failIfNotFound = false) const;
00173 
00174                 /** Reads a configuration parameter of type "std::vector<unsigned int>"
00175          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00176                  */
00177                 void  read_vector(
00178                         const std::string                                       &section,
00179                         const std::string                                       &name,
00180                         const std::vector<uint64_t>             &defaultValue,
00181                         std::vector<uint64_t>                   &outValues,
00182                         bool failIfNotFound = false) const;
00183 
00184                 /** Reads a configuration parameter of type "std::vector<int>"
00185          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00186                  */
00187                 void  read_vector(
00188                         const std::string                       &section,
00189                         const std::string                       &name,
00190                         const std::vector<int64_t>              &defaultValue,
00191                         std::vector<int64_t>                    &outValues,
00192                         bool failIfNotFound = false) const;
00193 
00194 
00195                 /** Reads a configuration parameter of type "std::vector<float>"
00196          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00197                  */
00198                 void  read_vector(
00199                         const std::string                       &section,
00200                         const std::string                       &name,
00201                         const std::vector<float>        &defaultValue,
00202                         std::vector<float>                      &outValues,
00203                         bool failIfNotFound = false) const;
00204 
00205                 /** Reads a configuration parameter of type "std::vector<double>"
00206          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00207                  */
00208                 void  read_vector(
00209                         const std::string                       &section,
00210                         const std::string                       &name,
00211                         const std::vector<double>       &defaultValue,
00212                         std::vector<double>                     &outValues,
00213                         bool failIfNotFound = false ) const;
00214 
00215                 /** Reads a configuration parameter of type "std::vector<bool>"
00216          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00217                  */
00218                 void  read_vector(
00219                         const std::string                       &section,
00220                         const std::string                       &name,
00221                         const std::vector<bool>         &defaultValue,
00222                         std::vector<bool>                       &outValues,
00223                         bool failIfNotFound = false ) const;
00224 
00225                 /** Reads a configuration parameter as a matrix written in a matlab-like format - for example: "[2 3 4 ; 7 8 9]"
00226                  *  This template method can be instantiated for matrices of the types: int, long, unsinged int, unsigned long, float, double, long double
00227          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00228                  */
00229                  template <class T>
00230                  void read_matrix(
00231                         const std::string                       &section,
00232                         const std::string                       &name,
00233                         mrpt::math::CMatrixTemplate<T>  &outMatrix,
00234                         const mrpt::math::CMatrixTemplate<T> &defaultMatrix = mrpt::math::CMatrixTemplate<T>(0,0),
00235                         bool failIfNotFound = false ) const;
00236 
00237 
00238         }; // End of class def.
00239 
00240         /** 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.
00241           *  The variableType must be the suffix of "read_XXX" functions, i.e. int, bool,...
00242           */
00243 #define MRPT_LOAD_CONFIG_VAR(variableName,variableType,configFileObject,sectionNameStr) \
00244         { variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName); }
00245 
00246         /** Loads a float variable, stored as radians but entered in the INI-file as degrees:
00247           */
00248 #define MRPT_LOAD_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
00249         { variableName = DEG2RAD( configFileObject.read_float(sectionNameStr,#variableName, RAD2DEG(variableName)) ); }
00250 
00251 #define MRPT_LOAD_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
00252         { variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName)); }
00253 
00254 
00255 #define MRPT_LOAD_HERE_CONFIG_VAR(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
00256                 targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,false);
00257 
00258 #define MRPT_LOAD_HERE_CONFIG_VAR_NO_DEFAULT(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
00259         { try { \
00260                 targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true); \
00261     } catch (std::exception &) \
00262     { \
00263                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00264         } }\
00265 
00266 
00267 #define MRPT_LOAD_CONFIG_VAR_NO_DEFAULT(variableName,variableType,configFileObject,sectionNameStr) \
00268         { try { \
00269                 variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true); \
00270     } catch (std::exception &) \
00271     { \
00272                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00273         } }\
00274 
00275 #define MRPT_LOAD_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
00276         { try { \
00277                 variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true)); \
00278     } catch (std::exception &) \
00279     { \
00280                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00281         } }\
00282 
00283 
00284 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
00285                 targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable));
00286 
00287 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
00288         { try { \
00289                 targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true)); \
00290     } catch (std::exception &) \
00291     { \
00292                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00293         } }\
00294 
00295 
00296 #define MRPT_SAVE_CONFIG_VAR(variableName,configFileObject,sectionNameStr) \
00297         { configFileObject.write(sectionNameStr,#variableName,variableName); }
00298 
00299 #define MRPT_SAVE_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
00300         { configFileObject.write(sectionNameStr,#variableName, RAD2DEG(variableName)); }
00301 
00302 
00303         } // End of namespace
00304 } // end of namespace
00305 #endif