151 lines
5.8 KiB
Plaintext
151 lines
5.8 KiB
Plaintext
namespace YYCC::ConfigManager {
|
|
/**
|
|
|
|
\page config_manager Universal Config Manager
|
|
|
|
YYCC::ConfigManager 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::Constraints::GetNumberRangeConstraint<float>(-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<int32_t> m_IntSetting;
|
|
YYCC::ConfigManager::StringSetting m_StringSetting;
|
|
YYCC::ConfigManager::NumberSetting<float> m_FloatSetting;
|
|
YYCC::ConfigManager::NumberSetting<TestEnum> m_EnumSetting;
|
|
|
|
YYCC::ConfigManager::CoreManager m_CoreManager;
|
|
};
|
|
|
|
// Initialize config manager
|
|
TestConfigManager test;
|
|
// Load settings.
|
|
test.m_CoreManager.Load()
|
|
// Get string setting 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 NumberSetting: The setting storing a number inside.
|
|
It is a template class. Support all arithmetic and enum types (integral, floating point, bool, enum).
|
|
\li 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 also can provide a constraint to setting.
|
|
Constraint is the struct instructing library to limit value in specified range.
|
|
It usually is used for making sure the setting stored value is valid.
|
|
See \ref constraints chapters to know how we provide constraints.
|
|
|
|
\subsection config_manager__setting__custom Custom Setting
|
|
|
|
In most cases, the combination use of setting presets and constraints is enough.
|
|
However, if you still are urge to create your personal setting,
|
|
please inherit AbstractSetting and implement essential class functions.
|
|
For the class functions you need to implement,
|
|
please refer to our setting presets, NumberSetting and StringSetting.
|
|
|
|
\section config_manager__core_manager Core Manager
|
|
|
|
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 is important.
|
|
It will be used when reading config file and only can be increased if needed (version can not downgrade).
|
|
The last argument is an initializer list which contain the \b pointer to all settings this manager managed.
|
|
|
|
When executing YYCC::ConfigManager::CoreManager::Load to load configs, it will perform following steps one by one:
|
|
|
|
<UL>
|
|
<LI>
|
|
Open given config file.
|
|
<UL>
|
|
<LI>
|
|
If given file is not existing, loading function will simply return and all configs will be reset to its default value.
|
|
</LI>
|
|
<LI>
|
|
Success to open file, go to next step.
|
|
</LI>
|
|
</UL>
|
|
</LI>
|
|
|
|
<LI>
|
|
Fetch version number from file.
|
|
<UL>
|
|
<LI>
|
|
If fail to read version number from file, loading function will simply return and all configs will be reset to its default value.
|
|
</LI>
|
|
<LI>
|
|
If the version of config file is higher than your specified version number when constructing this class,
|
|
core manager will assume you are trying to read a config file created by a higher version program,
|
|
and will reject reading and use default value for all settings.
|
|
</LI>
|
|
<LI>
|
|
If the version of config file is lower than your specified version number,
|
|
core manager will try to read config file and do proper migration (set default value for configs which do not existing) if possible.
|
|
</LI>
|
|
<LI>
|
|
If the version of config file is equal than your specified version number,
|
|
core manager will read config file normally.
|
|
</LI>
|
|
</UL>
|
|
</LI>
|
|
|
|
<LI>
|
|
Read config file body.
|
|
<UL>
|
|
<LI>
|
|
If any IO error occurs when reading, loading function will simply return.
|
|
All read config will keep their read value and all configs which has not been read will keep their default value.
|
|
</LI>
|
|
<LI>
|
|
If some config can not parse binary data to its type,
|
|
this config will be skipped and core manager will process next config.
|
|
This config will keep its default value.
|
|
</LI>
|
|
</UL>
|
|
</LI>
|
|
</UL>
|
|
|
|
All of these scenarios can be found by the return value of loading function.
|
|
The return type of loading function, ConfigLoadResult is a flag enum.
|
|
You can find whether loading process happend specified issue by using bitwise operation on it.
|
|
|
|
*/
|
|
} |