qxLib
layered_configs_manager.h
Go to the documentation of this file.
1 /**
2 
3  @file layered_configs_manager.h
4  @author Khrapov
5  @date 12.05.2026
6  @copyright © Nick Khrapov, 2026. All right reserved.
7 
8 **/
9 #pragma once
10 
11 #include <qx/algo/contains.h>
12 #include <qx/algo/sort.h>
14 #include <qx/logger/logger.h>
15 #include <qx/patterns/singleton.h>
16 
17 #include <any>
18 #include <expected>
19 #include <functional>
20 #include <unordered_map>
21 
22 namespace qx
23 {
24 
25 namespace details
26 {
27 
29 {
30  string_view svEnvName;
31  string_view svFullCommandLineName;
32  string_view svShortCommandLineName;
33 
34  string_view svGroupName;
35  string_view svDescription;
36  bool bRequired = false;
37 
38  std::optional<std::any> (*pStringToT)(string_view svData) = nullptr;
39  string (*pTToString)(const std::any& data) = nullptr;
40  string_view svTypeName;
41 };
42 
43 } // namespace details
44 
45 /**
46  @brief Public variable metadata for enumeration and help; views refer to registered static names.
47 **/
49 {
50  string_view svName;
51  string_view svDescription;
52  string_view svTypeName;
53  string_view svGroupName;
54 };
55 
56 /**
57 
58  @class layered_configs_manager
59  @brief A singleton that manages layered configuration variables
60  @details Doesn't support multithreading
61  @author Khrapov
62  @date 17.05.2026
63 
64 **/
65 class layered_configs_manager final : public singleton<layered_configs_manager>
66 {
67  template<class T>
69 
70 public:
71  /**
72  @brief Errors returned when reading a registered variable.
73  **/
74  enum class get_error
75  {
76  unknown_variable,
77  type_mismatch
78  };
79 
80  /**
81  @brief Errors returned when writing a variable; failed writes preserve the current value.
82  **/
83  enum class set_error
84  {
85  unknown_variable,
86  type_mismatch,
87  invalid_value
88  };
89 
90 public:
91  /**
92  @brief Set app description. It will be shown in help message.
93  @param sAppDescription - app description
94  **/
95  void set_app_description(string sAppDescription) noexcept;
96 
97  /**
98  @brief Copy command line arguments, converting narrow input with to_string().
99  @details Should be called once at the beginning of the app before the first parse().
100  Non-positive argc or null argv clears the command line arguments.
101  @param argc - number of command line arguments
102  @param argv - array of command line arguments
103  **/
104  void set_args(int argc, char* argv[]) noexcept;
105 
106  /**
107  @brief Show help message if "--help" or "-h" argument is present in command line arguments.
108  @details Should be called after set_args().
109  @return - true if help message was shown. usually the app should exit after that
110  **/
111  bool show_help() const noexcept;
112 
113  /**
114  @brief Parse command line arguments, environment variables, and default values.
115  @details Should be called after set_args() and before get()/set() of any variable.
116  You can call it multiple times during the app lifetime, for example, to load variables from different DLLs.
117  @return - true all required variables are present and have valid values
118  **/
119  bool parse() noexcept;
120 
121  /**
122  @brief Get variable value by runtime name.
123  @tparam T - type of variable
124  @param svRuntimeName - runtime name of variable
125  @return - value, or unknown_variable / type_mismatch error
126  **/
127  template<class T>
128  std::expected<T, get_error> get(string_view svRuntimeName) const noexcept;
129 
130  /**
131  @brief Set variable value by runtime name. Only set if the variable type matches.
132  @tparam T - type of variable
133  @param svRuntimeName - runtime name of variable
134  @param value - new variable value
135  @return - success, or unknown_variable / type_mismatch error
136  **/
137  template<class T>
138  std::expected<void, set_error> set(string_view svRuntimeName, T value) noexcept;
139 
140  /**
141  @brief Read the current value without knowing its C++ type.
142  @details The reference is valid until the stored value is removed or the manager is reset.
143  Setting or parsing values may change which value is current.
144  @param svRuntimeName - registered runtime name, matched exactly
145  @return - reference to the stored value, or unknown_variable error
146  **/
147  std::expected<std::reference_wrapper<const std::any>, get_error> get(string_view svRuntimeName) const noexcept;
148 
149  /**
150  @brief Set a type-erased value using the variable's exact registered C++ type.
151  @param svRuntimeName - registered runtime name
152  @param value - owned value; a mismatched type leaves the variable unchanged
153  @return - success, or unknown_variable / type_mismatch error
154  **/
155  std::expected<void, set_error> set(string_view svRuntimeName, std::any value) noexcept;
156 
157  /**
158  @brief Read a value through its registered string formatter without knowing its C++ type.
159  @param svRuntimeName - registered runtime name, matched exactly
160  @return - owned string for the current value or default, or unknown_variable error
161  **/
162  std::expected<string, get_error> get_string(string_view svRuntimeName) const noexcept;
163 
164  /**
165  @brief Set a variable from text using its existing registered parser.
166  @details Every registered variable is writable. Conversion rules match environment and command-line
167  parsing. On success this uses the same runtime storage as set<T>(); no file is written.
168  Failure leaves the previous value unchanged. Call only on the manager's owning thread.
169  @param svRuntimeName - registered runtime name, matched exactly
170  @param svValue - text to convert to the variable's declared type
171  @return - success, or unknown_variable / invalid_value error
172  **/
173  std::expected<void, set_error> set_string(string_view svRuntimeName, string_view svValue) noexcept;
174 
175  /**
176  @brief Enumerate registered variables without exposing converters or stored values.
177  @return - metadata sorted by runtime name; views retain the registered names' and descriptions' lifetime
178  **/
179  std::vector<layered_config_variable_info> get_variables() const noexcept;
180 
181  /**
182  @brief Clear all variables and command line arguments. You should call parse() after that to set variables again.
183  **/
184  void reset() noexcept;
185 
186 private:
187  /**
188  @brief Add a variable to the manager. Called from variable builders
189  @tparam T - type of variable
190  @param svRuntimeName - runtime name of variable
191  @param data - information about variable
192  @param defaultValue - default variable value
193  **/
194  template<class T>
195  void add_variable(
196  string_view svRuntimeName,
197  const details::layered_config_variable_data& data,
198  T defaultValue) noexcept;
199 
200 private:
201  string m_sAppDescription;
202  std::vector<string> m_Args;
203 
204  std::unordered_map<string_view, details::layered_config_variable_data> m_VariableData;
205  std::unordered_map<string_view, std::any> m_DefaultVariables;
206  std::unordered_map<string_view, std::any> m_Variables;
207 };
208 
209 } // namespace qx
210 
211 #include <qx/layered_config/layered_configs_manager.inl>
A builder for creating layered_config_variable instances.
A singleton that manages layered configuration variables.
std::expected< void, set_error > set_string(string_view svRuntimeName, string_view svValue) noexcept
Set a variable from text using its existing registered parser.
void set_app_description(string sAppDescription) noexcept
Set app description. It will be shown in help message.
get_error
Errors returned when reading a registered variable.
std::vector< layered_config_variable_info > get_variables() const noexcept
Enumerate registered variables without exposing converters or stored values.
std::expected< void, set_error > set(string_view svRuntimeName, T value) noexcept
Set variable value by runtime name. Only set if the variable type matches.
void reset() noexcept
Clear all variables and command line arguments. You should call parse() after that to set variables a...
std::expected< string, get_error > get_string(string_view svRuntimeName) const noexcept
Read a value through its registered string formatter without knowing its C++ type.
set_error
Errors returned when writing a variable; failed writes preserve the current value.
std::expected< T, get_error > get(string_view svRuntimeName) const noexcept
Get variable value by runtime name.
bool parse() noexcept
Parse command line arguments, environment variables, and default values.
bool show_help() const noexcept
Show help message if "--help" or "-h" argument is present in command line arguments.
void set_args(int argc, char *argv[]) noexcept
Copy command line arguments, converting narrow input with to_string().
Inherit the necessary singleton class from this.
Public variable metadata for enumeration and help; views refer to registered static names.