1 #ifndef CORELIB___NCBI_CONFIG__HPP 2 #define CORELIB___NCBI_CONFIG__HPP 3 4 /* $Id: ncbi_config.hpp 574926 2018-11-20 20:23:54Z ucko $ 5 * =========================================================================== 6 * 7 * PUBLIC DOMAIN NOTICE 8 * National Center for Biotechnology Information 9 * 10 * This software/database is a "United States Government Work" under the 11 * terms of the United States Copyright Act. It was written as part of 12 * the author's official duties as a United States Government employee and 13 * thus cannot be copyrighted. This software/database is freely available 14 * to the public for use. The National Library of Medicine and the U.S. 15 * Government have not placed any restriction on its use or reproduction. 16 * 17 * Although all reasonable efforts have been taken to ensure the accuracy 18 * and reliability of the software and data, the NLM and the U.S. 19 * Government do not and cannot warrant the performance or results that 20 * may be obtained by using this software or data. The NLM and the U.S. 21 * Government disclaim all warranties, express or implied, including 22 * warranties of performance, merchantability or fitness for any particular 23 * purpose. 24 * 25 * Please cite the author in any work or product based on this material. 26 * 27 * =========================================================================== 28 * 29 * Authors: Anatoliy Kuznetsov 30 * 31 */ 32 33 /// @file ncbi_config.hpp 34 /// Parameters initialization model 35 36 #include <corelib/ncbi_tree.hpp> 37 38 BEGIN_NCBI_SCOPE 39 40 /** @addtogroup ModuleConfig 41 * 42 * @{ 43 */ 44 45 46 ///////////////////////////////////////////////////////////////////////////// 47 /// 48 /// CConfigException -- 49 /// 50 /// Exception generated by configuration API 51 52 class NCBI_XNCBI_EXPORT CConfigException : public CCoreException 53 { 54 public: 55 enum EErrCode { 56 eParameterMissing, ///< Missing mandatory parameter 57 eSynonymDuplicate, 58 eInvalidParameter, ///< Invalid parameter value 59 }; 60 61 /// Translate from the error code value to its string representation. 62 virtual const char* GetErrCodeString(void) const override; 63 64 // Standard exception boilerplate code. 65 NCBI_EXCEPTION_DEFAULT(CConfigException, CCoreException); 66 }; 67 68 69 70 class IRegistry; 71 72 class NCBI_XNCBI_EXPORT CConfig 73 { 74 public: 75 /// Instantiation parameters tree. 76 /// 77 /// Plug-in instantiation model is based on class factories. 78 /// Recursive class factory calls are modeled as tree, where specific 79 /// subtree is responsible for CF parameters 80 /// 81 typedef CTreePair<string, string> TParamValue; 82 typedef TParamValue::TPairTreeNode TParamTree; 83 84 public: 85 /// Optionally takes ownership on passed param_tree 86 CConfig(TParamTree* param_tree, EOwnership own = eTakeOwnership); 87 88 /// Construct, take no tree ownership 89 CConfig(const TParamTree* param_tree); 90 91 /// Take registry and create a config tree out of it 92 CConfig(const IRegistry& reg); 93 ~CConfig(); 94 95 /// Defines how to behave when parameter is missing 96 enum EErrAction { 97 eErr_Throw, ///< Throw an exception on error 98 eErr_NoThrow ///< Return default value on error 99 }; 100 101 /// Utility function to get an element of parameter tree 102 /// Throws an exception when mandatory parameter is missing 103 /// (or returns the default value) 104 /// 105 /// @param driver_name 106 /// Name of the module requesting parameter (used in diagnostics) 107 /// @param params 108 /// Parameters tree 109 /// @param param_name 110 /// Name of the parameter 111 /// @param mandatory 112 /// Error action 113 /// @param default_value 114 /// Default value for missing parameters 115 string GetString(const string& driver_name, 116 const string& param_name, 117 EErrAction on_error, 118 const string& default_value, 119 const list<string>* synonyms = NULL); 120 121 /// This version always defaults to the empty string so that it 122 /// can safely return a reference. (default_value may be 123 /// temporary in some cases.) 124 const string& GetString(const string& driver_name, 125 const string& param_name, 126 EErrAction on_error, 127 const list<string>* synonyms = NULL); 128 129 /// Utility function to get an integer element of parameter tree 130 /// Throws an exception when mandatory parameter is missing 131 /// (or returns the default value) 132 /// 133 /// @param driver_name 134 /// Name of the module requesting parameter (used in diagnostics) 135 /// @param params 136 /// Parameters tree 137 /// @param param_name 138 /// Name of the parameter 139 /// @param mandatory 140 /// Error action 141 /// @param default_value 142 /// Default value for missing parameters 143 /// @sa ParamTree_GetString 144 int GetInt(const string& driver_name, 145 const string& param_name, 146 EErrAction on_error, 147 int default_value, 148 const list<string>* synonyms = NULL); 149 150 /// Utility function to get an integer element of parameter tree 151 /// Throws an exception when mandatory parameter is missing 152 /// (or returns the default value) 153 /// This function understands KB, MB, GB qualifiers at the end of the string 154 /// 155 /// @param driver_name 156 /// Name of the module requesting parameter (used in diagnostics) 157 /// @param params 158 /// Parameters tree 159 /// @param param_name 160 /// Name of the parameter 161 /// @param mandatory 162 /// Error action 163 /// @param default_value 164 /// Default value for missing parameters 165 /// @sa ParamTree_GetString 166 Uint8 GetDataSize(const string& driver_name, 167 const string& param_name, 168 EErrAction on_error, 169 unsigned int default_value, 170 const list<string>* synonyms = NULL); 171 172 /// Utility function to get an integer element of parameter tree 173 /// Throws an exception when mandatory parameter is missing 174 /// (or returns the default value) 175 /// 176 /// @param driver_name 177 /// Name of the module requesting parameter (used in diagnostics) 178 /// @param params 179 /// Parameters tree 180 /// @param param_name 181 /// Name of the parameter 182 /// @param mandatory 183 /// Error action 184 /// @param default_value 185 /// Default value for missing parameters 186 /// @sa ParamTree_GetString 187 bool GetBool(const string& driver_name, 188 const string& param_name, 189 EErrAction on_error, 190 bool default_value, 191 const list<string>* synonyms = NULL); 192 193 /// Utility function to get a double element of parameter tree 194 /// Throws an exception when mandatory parameter is missing 195 /// (or returns the default value) 196 /// 197 /// @param driver_name 198 /// Name of the module requesting parameter (used in diagnostics) 199 /// @param params 200 /// Parameters tree 201 /// @param param_name 202 /// Name of the parameter 203 /// @param mandatory 204 /// Error action 205 /// @param default_value 206 /// Default value for missing parameters 207 /// @sa ParamTree_GetString 208 double GetDouble(const string& driver_name, 209 const string& param_name, 210 EErrAction on_error, 211 double default_value, 212 const list<string>* synonyms = NULL); 213 GetTree() const214 const TParamTree* GetTree() const { return m_ParamTree.get(); } 215 216 /// Reconstruct param tree from the application registry 217 /// @param reg 218 /// Application registry (loaded from the INI file) 219 /// @return 220 /// Reconstructed tree (caller is responsible for deletion) 221 static TParamTree* ConvertRegToTree(const IRegistry& reg); 222 223 /// Overloading of getters for generic programming Get(const string & d,const string & p,EErrAction e,const string & v,const list<string> * s=NULL)224 string Get(const string& d, const string& p, EErrAction e, const string& v, 225 const list<string>* s = NULL) 226 { return GetString(d, p, e, v, s); } 227 Get(const string & d,const string & p,EErrAction e,int v,const list<string> * s=NULL)228 int Get(const string& d, const string& p, EErrAction e, int v, 229 const list<string>* s = NULL) 230 { return GetInt(d, p, e, v, s); } 231 Get(const string & d,const string & p,EErrAction e,bool v,const list<string> * s=NULL)232 bool Get(const string& d, const string& p, EErrAction e, bool v, 233 const list<string>* s = NULL) 234 { return GetBool(d, p, e, v, s); } 235 Get(const string & d,const string & p,EErrAction e,double v,const list<string> * s=NULL)236 double Get(const string& d, const string& p, EErrAction e, double v, 237 const list<string>* s = NULL) 238 { return GetDouble(d, p, e, v, s); } 239 240 private: 241 CConfig(const CConfig&); 242 CConfig& operator=(const CConfig&); 243 244 protected: 245 const string& x_GetString(const string& driver_name, 246 const string& param_name, 247 EErrAction on_error, 248 const string& default_value, 249 const list<string>* synonyms); 250 251 protected: 252 AutoPtr<TParamTree> m_ParamTree; 253 }; 254 255 /* @} */ 256 257 258 END_NCBI_SCOPE 259 260 #endif /* CORELIB___NCBI_CONFIG__HPP */ 261