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