YYCCommonplace/doc/src/config_manager.dox

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 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.

*/
}