NCBI C++ ToolKit
ncbi_config.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CORELIB___NCBI_CONFIG__HPP
2 #define CORELIB___NCBI_CONFIG__HPP
3 
4 /* $Id: ncbi_config.hpp 99115 2023-02-15 17:18:08Z vasilche $
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 
39 
40 /** @addtogroup ModuleConfig
41  *
42  * @{
43  */
44 
45 
46 /////////////////////////////////////////////////////////////////////////////
47 ///
48 /// CConfigException --
49 ///
50 /// Exception generated by configuration API
51 
53 {
54 public:
55  enum EErrCode {
56  eParameterMissing, ///< Missing mandatory parameter
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.
66 };
67 
68 
69 
70 class IRegistry;
71 
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  ///
83 
84 public:
85  /// Optionally takes ownership on passed param_tree
86  explicit
87  CConfig(TParamTree* param_tree,
89  NStr::ECase use_case = NStr::eNocase);
90 
91  /// Construct, take no tree ownership
92  explicit
93  CConfig(const TParamTree* param_tree,
94  NStr::ECase use_case = NStr::eNocase);
95 
96  /// Take registry and create a config tree out of it
97  explicit
98  CConfig(const IRegistry& reg,
99  NStr::ECase use_case = NStr::eNocase);
100  ~CConfig();
101 
102  /// Defines how to behave when parameter is missing
103  enum EErrAction {
104  eErr_Throw, ///< Throw an exception on error
105  eErr_NoThrow ///< Return default value on error
106  };
107 
108  /// Utility function to get an element of parameter tree
109  /// Throws an exception when mandatory parameter is missing
110  /// (or returns the default value)
111  ///
112  /// @param driver_name
113  /// Name of the module requesting parameter (used in diagnostics)
114  /// @param params
115  /// Parameters tree
116  /// @param param_name
117  /// Name of the parameter
118  /// @param mandatory
119  /// Error action
120  /// @param default_value
121  /// Default value for missing parameters
122  string GetString(const string& driver_name,
123  const string& param_name,
124  EErrAction on_error,
125  const string& default_value,
126  const list<string>* synonyms = NULL);
127 
128  /// This version always defaults to the empty string so that it
129  /// can safely return a reference. (default_value may be
130  /// temporary in some cases.)
131  const string& GetString(const string& driver_name,
132  const string& param_name,
133  EErrAction on_error,
134  const list<string>* synonyms = NULL);
135 
136  /// Utility function to get an integer element of parameter tree
137  /// Throws an exception when mandatory parameter is missing
138  /// (or returns the default value)
139  ///
140  /// @param driver_name
141  /// Name of the module requesting parameter (used in diagnostics)
142  /// @param params
143  /// Parameters tree
144  /// @param param_name
145  /// Name of the parameter
146  /// @param mandatory
147  /// Error action
148  /// @param default_value
149  /// Default value for missing parameters
150  /// @sa ParamTree_GetString
151  int GetInt(const string& driver_name,
152  const string& param_name,
153  EErrAction on_error,
154  int default_value,
155  const list<string>* synonyms = NULL);
156 
157  /// Utility function to get an integer element of parameter tree
158  /// Throws an exception when mandatory parameter is missing
159  /// (or returns the default value)
160  /// This function understands KB, MB, GB qualifiers at the end of the string
161  ///
162  /// @param driver_name
163  /// Name of the module requesting parameter (used in diagnostics)
164  /// @param params
165  /// Parameters tree
166  /// @param param_name
167  /// Name of the parameter
168  /// @param mandatory
169  /// Error action
170  /// @param default_value
171  /// Default value for missing parameters
172  /// @sa ParamTree_GetString
173  Uint8 GetDataSize(const string& driver_name,
174  const string& param_name,
175  EErrAction on_error,
176  unsigned int default_value,
177  const list<string>* synonyms = NULL);
178 
179  /// Utility function to get an integer element of parameter tree
180  /// Throws an exception when mandatory parameter is missing
181  /// (or returns the default value)
182  ///
183  /// @param driver_name
184  /// Name of the module requesting parameter (used in diagnostics)
185  /// @param params
186  /// Parameters tree
187  /// @param param_name
188  /// Name of the parameter
189  /// @param mandatory
190  /// Error action
191  /// @param default_value
192  /// Default value for missing parameters
193  /// @sa ParamTree_GetString
194  bool GetBool(const string& driver_name,
195  const string& param_name,
196  EErrAction on_error,
197  bool default_value,
198  const list<string>* synonyms = NULL);
199 
200  /// Utility function to get a double element of parameter tree
201  /// Throws an exception when mandatory parameter is missing
202  /// (or returns the default value)
203  ///
204  /// @param driver_name
205  /// Name of the module requesting parameter (used in diagnostics)
206  /// @param params
207  /// Parameters tree
208  /// @param param_name
209  /// Name of the parameter
210  /// @param mandatory
211  /// Error action
212  /// @param default_value
213  /// Default value for missing parameters
214  /// @sa ParamTree_GetString
215  double GetDouble(const string& driver_name,
216  const string& param_name,
217  EErrAction on_error,
218  double default_value,
219  const list<string>* synonyms = NULL);
220 
221  const TParamTree* GetTree() const { return m_ParamTree.get(); }
222 
223  /// Reconstruct param tree from the application registry
224  /// @param reg
225  /// Application registry (loaded from the INI file)
226  /// @return
227  /// Reconstructed tree (caller is responsible for deletion)
228  static TParamTree* ConvertRegToTree(const IRegistry& reg,
229  NStr::ECase use_case = NStr::eNocase);
230 
231  /// Overloading of getters for generic programming
232  string Get(const string& d, const string& p, EErrAction e, const string& v,
233  const list<string>* s = NULL)
234  { return GetString(d, p, e, v, s); }
235 
236  int Get(const string& d, const string& p, EErrAction e, int v,
237  const list<string>* s = NULL)
238  { return GetInt(d, p, e, v, s); }
239 
240  bool Get(const string& d, const string& p, EErrAction e, bool v,
241  const list<string>* s = NULL)
242  { return GetBool(d, p, e, v, s); }
243 
244  double Get(const string& d, const string& p, EErrAction e, double v,
245  const list<string>* s = NULL)
246  { return GetDouble(d, p, e, v, s); }
247 
248 private:
249  CConfig(const CConfig&);
251 
252 protected:
253  const string& x_GetString(const string& driver_name,
254  const string& param_name,
255  EErrAction on_error,
256  const string& default_value,
257  const list<string>* synonyms);
258 
259 protected:
261 };
262 
263 /* @} */
264 
265 
267 
268 #endif /* CORELIB___NCBI_CONFIG__HPP */
AutoPtr –.
Definition: ncbimisc.hpp:401
CConfigException –.
Definition: ncbi_config.hpp:53
CCoreException –.
Definition: ncbiexpt.hpp:1476
definition of a Culling tree
Definition: ncbi_tree.hpp:100
IRegistry –.
Definition: ncbireg.hpp:73
@ eTakeOwnership
An object can take ownership of another.
Definition: ncbi_types.h:136
#define NULL
Definition: ncbistd.hpp:225
virtual const char * GetErrCodeString(void) const override
Translate from the error code value to its string representation.
Definition: ncbiexpt.cpp:757
double Get(const string &d, const string &p, EErrAction e, double v, const list< string > *s=NULL)
NCBI_EXCEPTION_DEFAULT(CConfigException, CCoreException)
const TParamTree * GetTree() const
EErrAction
Defines how to behave when parameter is missing.
string Get(const string &d, const string &p, EErrAction e, const string &v, const list< string > *s=NULL)
Overloading of getters for generic programming.
CTreePair< string, string, PEqualNocase_Conditional > TParamValue
Instantiation parameters tree.
Definition: ncbi_config.hpp:81
TParamValue::TPairTreeNode TParamTree
Definition: ncbi_config.hpp:82
AutoPtr< TParamTree > m_ParamTree
int Get(const string &d, const string &p, EErrAction e, int v, const list< string > *s=NULL)
bool Get(const string &d, const string &p, EErrAction e, bool v, const list< string > *s=NULL)
CConfig & operator=(const CConfig &)
CConfig(const CConfig &)
@ eErr_Throw
Throw an exception on error.
@ eParameterMissing
Missing mandatory parameter.
Definition: ncbi_config.hpp:56
@ eInvalidParameter
Invalid parameter value.
Definition: ncbi_config.hpp:58
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
ECase
Which type of string comparison.
Definition: ncbistr.hpp:1204
@ eNocase
Case insensitive compare.
Definition: ncbistr.hpp:1206
enum ENcbiOwnership EOwnership
Ownership relations between objects.
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
Node data template for id-value trees.
Definition: ncbi_tree.hpp:453
Modified on Fri Jul 19 17:11:44 2024 by modify_doxy.py rev. 669887