The MRPT project: CConfigFileBase.h Source 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 BASE_IMPEXP 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 #if MRPT_WORD_SIZE>32
00096                 /** Save a configuration parameter of type "size_t"
00097                  */
00098                 void  write(const std::string &section, const std::string &name, size_t value);
00099 #endif          
00100 
00101                 /** Save a configuration parameter of type "string"
00102                  */
00103                 void  write(const std::string &section, const std::string &name, const std::string &value);
00104 
00105                 /** Save a configuration parameter of type "std::vector<int>"
00106                  */
00107                 void  write(const std::string &section, const std::string &name, const std::vector<int> &value);
00108 
00109                 /** Save a configuration parameter of type "std::vector<unsigned int>"
00110                  */
00111                 void  write(const std::string &section, const std::string &name, const std::vector<unsigned int> &value);
00112 
00113                 /** Save a configuration parameter of type "std::vector<float>"
00114                  */
00115                 void  write(const std::string &section, const std::string &name, const std::vector<float> &value);
00116 
00117                 /** Save a configuration parameter of type "std::vector<double>"
00118                  */
00119                 void  write(const std::string &section, const std::string &name, const std::vector<double> &value);
00120 
00121                 /** Save a configuration parameter of type "std::vector<bool>"
00122                  */
00123                 void  write(const std::string &section, const std::string &name, const std::vector<bool> &value);
00124 
00125                 /** Reads a configuration parameter of type "double"
00126          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00127                  */
00128                 double  read_double(const std::string &section, const std::string &name, double defaultValue, bool failIfNotFound = false) const;
00129 
00130                 /** Reads a configuration parameter of type "float"
00131          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00132                  */
00133                 float  read_float(const std::string &section, const std::string &name, float defaultValue, bool failIfNotFound = false) const;
00134 
00135                 /** Reads a configuration parameter of type "bool", codified as "1"/"0" or "true"/"false" or "yes"/"no" for true/false, repectively.
00136          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00137                  */
00138                 bool  read_bool(const std::string &section, const std::string &name, bool defaultValue, bool failIfNotFound = false) const;
00139 
00140                 /** Reads a configuration parameter of type "int"
00141          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00142                  */
00143                 int  read_int(const std::string &section, const std::string &name, int defaultValue, bool failIfNotFound = false) const;
00144 
00145                 /** 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"
00146          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00147                  */
00148                 uint64_t read_uint64_t(const std::string &section, const std::string &name, uint64_t defaultValue, bool failIfNotFound = false ) const;
00149 
00150                 /** Reads a configuration parameter of type "string"
00151          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00152                  */
00153                 std::string  read_string(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
00154 
00155                 /** 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)
00156          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00157                  */
00158                 std::string  read_string_first_word(const std::string &section, const std::string &name, const std::string &defaultValue, bool failIfNotFound = false) const;
00159 
00160                 /** Reads a configuration parameter of type "std::vector<unsigned int>"
00161          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00162                  */
00163                 void  read_vector(
00164                         const std::string                                       &section,
00165                         const std::string                                       &name,
00166                         const std::vector<uint32_t>             &defaultValue,
00167                         std::vector<uint32_t>                   &outValues,
00168                         bool failIfNotFound = false) const;
00169 
00170                 /** Reads a configuration parameter of type "std::vector<int>"
00171          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00172                  */
00173                 void  read_vector(
00174                         const std::string                       &section,
00175                         const std::string                       &name,
00176                         const std::vector<int32_t>              &defaultValue,
00177                         std::vector<int32_t>                    &outValues,
00178                         bool failIfNotFound = false) const;
00179 
00180                 /** Reads a configuration parameter of type "std::vector<unsigned int>"
00181          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00182                  */
00183                 void  read_vector(
00184                         const std::string                                       &section,
00185                         const std::string                                       &name,
00186                         const std::vector<uint64_t>             &defaultValue,
00187                         std::vector<uint64_t>                   &outValues,
00188                         bool failIfNotFound = false) const;
00189 
00190                 /** Reads a configuration parameter of type "std::vector<int>"
00191          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00192                  */
00193                 void  read_vector(
00194                         const std::string                       &section,
00195                         const std::string                       &name,
00196                         const std::vector<int64_t>              &defaultValue,
00197                         std::vector<int64_t>                    &outValues,
00198                         bool failIfNotFound = false) const;
00199 
00200 
00201                 /** Reads a configuration parameter of type "std::vector<float>"
00202          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00203                  */
00204                 void  read_vector(
00205                         const std::string                       &section,
00206                         const std::string                       &name,
00207                         const std::vector<float>        &defaultValue,
00208                         std::vector<float>                      &outValues,
00209                         bool failIfNotFound = false) const;
00210 
00211                 /** Reads a configuration parameter of type "std::vector<double>"
00212          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00213                  */
00214                 void  read_vector(
00215                         const std::string                       &section,
00216                         const std::string                       &name,
00217                         const std::vector<double>       &defaultValue,
00218                         std::vector<double>                     &outValues,
00219                         bool failIfNotFound = false ) const;
00220 
00221                 /** Reads a configuration parameter of type "std::vector<bool>"
00222          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00223                  */
00224                 void  read_vector(
00225                         const std::string                       &section,
00226                         const std::string                       &name,
00227                         const std::vector<bool>         &defaultValue,
00228                         std::vector<bool>                       &outValues,
00229                         bool failIfNotFound = false ) const;
00230 
00231                 /** Reads a configuration parameter as a matrix written in a matlab-like format - for example: "[2 3 4 ; 7 8 9]"
00232                  *  This template method can be instantiated for matrices of the types: int, long, unsinged int, unsigned long, float, double, long double
00233          * \exception std::exception If the key name is not found and "failIfNotFound" is true. Otherwise the "defaultValue" is returned.
00234                  */
00235                  template <class T>
00236                  void read_matrix(
00237                         const std::string                       &section,
00238                         const std::string                       &name,
00239                         mrpt::math::CMatrixTemplate<T>  &outMatrix,
00240                         const mrpt::math::CMatrixTemplate<T> &defaultMatrix = mrpt::math::CMatrixTemplate<T>(0,0),
00241                         bool failIfNotFound = false ) const;
00242 
00243 
00244         }; // End of class def.
00245 
00246         /** 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.
00247           *  The variableType must be the suffix of "read_XXX" functions, i.e. int, bool,...
00248           */
00249 #define MRPT_LOAD_CONFIG_VAR(variableName,variableType,configFileObject,sectionNameStr) \
00250         { variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName); }
00251 
00252         /** Loads a float variable, stored as radians but entered in the INI-file as degrees:
00253           */
00254 #define MRPT_LOAD_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
00255         { variableName = DEG2RAD( configFileObject.read_float(sectionNameStr,#variableName, RAD2DEG(variableName)) ); }
00256 
00257 #define MRPT_LOAD_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
00258         { variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName)); }
00259 
00260 
00261 #define MRPT_LOAD_HERE_CONFIG_VAR(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
00262                 targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,false);
00263 
00264 #define MRPT_LOAD_HERE_CONFIG_VAR_NO_DEFAULT(variableName,variableType,targetVariable,configFileObject,sectionNameStr) \
00265         { try { \
00266                 targetVariable = configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true); \
00267     } catch (std::exception &) \
00268     { \
00269                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00270         } }\
00271 
00272 
00273 #define MRPT_LOAD_CONFIG_VAR_NO_DEFAULT(variableName,variableType,configFileObject,sectionNameStr) \
00274         { try { \
00275                 variableName = configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true); \
00276     } catch (std::exception &) \
00277     { \
00278                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00279         } }\
00280 
00281 #define MRPT_LOAD_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,configFileObject,sectionNameStr) \
00282         { try { \
00283                 variableName = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,variableName,true)); \
00284     } catch (std::exception &) \
00285     { \
00286                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00287         } }\
00288 
00289 
00290 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
00291                 targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable));
00292 
00293 #define MRPT_LOAD_HERE_CONFIG_VAR_CAST_NO_DEFAULT(variableName,variableType,variableTypeCast,targetVariable,configFileObject,sectionNameStr) \
00294         { try { \
00295                 targetVariable = static_cast<variableTypeCast>(configFileObject.read_##variableType(sectionNameStr,#variableName,targetVariable,true)); \
00296     } catch (std::exception &) \
00297     { \
00298                 THROW_EXCEPTION( format( "Value for '%s' not found in config file", static_cast<const char*>(#variableName ) )); \
00299         } }\
00300 
00301 
00302 #define MRPT_SAVE_CONFIG_VAR(variableName,configFileObject,sectionNameStr) \
00303         { configFileObject.write(sectionNameStr,#variableName,variableName); }
00304 
00305 #define MRPT_SAVE_CONFIG_VAR_DEGREES(variableName,configFileObject,sectionNameStr) \
00306         { configFileObject.write(sectionNameStr,#variableName, RAD2DEG(variableName)); }
00307 
00308 
00309         } // End of namespace
00310 } // end of namespace
00311 #endif