From 9e5bd370c444d587e6fa1b2a3123d91c6effe0aa Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Thu, 18 Jul 2024 09:28:10 +0800 Subject: [PATCH] doc: add documentation for ConfigManager --- doc/src/config_manager.dox | 115 +++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/doc/src/config_manager.dox b/doc/src/config_manager.dox index a9abf30..e0253a2 100644 --- a/doc/src/config_manager.dox +++ b/doc/src/config_manager.dox @@ -2,4 +2,119 @@ \page config_manager Universal Config Manager +Universal config manager give programmer an universal way to manage its program settings. +There is an example about how to use universal config manager. +In following content, we will describe it in detail. + +\code +class TestConfigManager { +public: + enum class TestEnum : int8_t { + Test1, Test2, Test3 + }; + + TestConfigManager() : + m_IntSetting(YYCC_U8("int-setting"), INT32_C(0)), + m_StringSetting(YYCC_U8("string-setting"), YYCC_U8("")), + m_FloatSetting(YYCC_U8("float-setting"), 0.0f, YYCC::ConfigManager::ConstraintPresets::GetNumberRangeConstraint(-1.0f, 1.0f)), + m_EnumSetting(YYCC_U8("enum-setting"), TestEnum::Test1), + m_CoreManager(YYCC_U8("test.cfg"), UINT64_C(0), { + &m_IntSetting, &m_StringSetting, &m_FloatSetting, &m_EnumSetting + }) + {} + ~TestConfigManager() {} + + YYCC::ConfigManager::NumberSetting m_IntSetting; + YYCC::ConfigManager::StringSetting m_StringSetting; + YYCC::ConfigManager::NumberSetting m_FloatSetting; + YYCC::ConfigManager::NumberSetting m_EnumSetting; + + YYCC::ConfigManager::CoreManager m_CoreManager; +}; + +// init cfg manager +TestConfigManager test; +// load string +test.m_CoreManager.Load() +// get string value +auto val = test.m_StringSetting.Get(); +\endcode + +\section config_manager__setting Setting + +Setting can be seen as the leaf of the config tree. +Each setting describe a single configuration entry. + +\subsection config_manager__setting__presets Setting Presets + +We currently provide 2 setting preset classes which you can directly use. + +\li YYCC::ConfigManager::NumberSetting: The setting storing a number inside. +It is a template class. Support all arithmetic and enum types (integral, floating point, bool, enum). +\li YYCC::ConfigManager::StringSetting: The setting storing a string inside. + +When constructing these settings, +you need to provide its unique name which will be used when saving to file or reading from file. +Also you need to provide a default value for it. +It will be used when fail to read file or initializing itself. +Optionally, you can assign a constraint to it which we will introduce in following section. + +\subsection config_manager__setting__custom Custom Setting + +In most cases, the combination use of setting presets and constraints introduced in following is enough. +However, if you still are urge to create your personal setting, +please inherit YYCC::ConfigManager::AbstractSetting and implement essential class functions. +For the class functions you need to implement, +please refer to our setting presets, YYCC::ConfigManager::NumberSetting and YYCC::ConfigManager::StringSetting. + +\section config_manager__constraint Constraint + +Constraint can be applied to specific setting instance, +and limit its value to specific values, +such as minimum maximum value, specific string format and etc. + +\subsection config_manager__constraint__presets Constraint Presets + +YYCC::ConfigManager provide some constraint presets in YYCC::ConfigManager::Constraints namespace. +All functions inside this namespace will return a YYCC::ConfigManager::Constraint instance, +and you can directly assign it to the constructor of setting. +Currently there is only one constraint preset: + +\li YYCC::ConfigManager::Constraints::GetNumberRangeConstraint: Constrain the number value in minimum maximum value range (inclusive). + +\subsection config_manager__constraint__custom Custom Constraint + +For creating your personal constraint, +you need to create YYCC::ConfigManager::Constraint instance manually. + +First you need decide the template argument of YYCC::ConfigManager::Constraint. +The type you assigned to template argument always is +the same type which is accepted by the setting this constraint will be applied to. + +Second, you need assign class member of YYCC::ConfigManager::Constraint. +Currently there is only one class member. +It is a function pointer called when correcting value. +See our constraint presets for more infomation about how to write it. + +\section config_manager__core_manager Core Manager + +YYCC::ConfigManager::CoreManager manage a collection of settings. +And have responsibility to reading and writing config file. + +We highly suggest that you create a personal config manager class like example does. +Then put essential settings and core manager inside it. +Please note you must place core manager after all settings. +Because the order of C++ initializing its class member is the order you declared them. +The constructor of core manager need the pointer to all it managed settings, +so it must be initialized after initializing all settings. + +When initializing core manager, you need assign config file path first. +Then you need specify a version number. +Version number will be used when reading config file. +If the version of config file is higher than your given number, +core manager will assume you are trying to read a config file created by a higher version program. +Core manager will reject reading and use default value for all settings. +Otherwise, core manager will try to read config file and do proper migration if possible. +The last argument is an initializer list which contain the \b pointer to all settings this manager managed. + */ \ No newline at end of file