#include <ConfigManager.h>

Public Member Functions
	ConfigManager ()=default

	ConfigManager (const ConfigManager &)=delete

ConfigManager &	operator= (const ConfigManager &)=delete

std::optional< Error >	loadFile (ConfigCategory category, std::string_view sFileName)

std::optional< Error >	loadFile (std::filesystem::path pathToConfigFile)

template<typename T >
T	getValue (std::string_view sSection, std::string_view sKey, T defaultValue) const

std::vector< std::string >	getAllSections ()

std::variant< std::vector< std::string >, Error >	getAllKeysOfSection (std::string_view sSection) const

template<typename T >
void	setValue (std::string_view sSection, std::string_view sKey, T value, std::string_view sComment="")

std::optional< Error >	saveFile (ConfigCategory category, std::string_view sFileName)

std::optional< Error >	saveFile (std::filesystem::path pathToConfigFile, bool bEnableBackup)

std::filesystem::path	getFilePath () const

Static Public Member Functions
static std::string	getConfigFormatExtension ()

static std::string	getBackupFileExtension ()

static std::set< std::string >	getAllFileNames (ConfigCategory category)

static std::string	getFreeProgressProfileName ()

static std::filesystem::path	getCategoryDirectory (ConfigCategory category)

static std::optional< Error >	removeFile (ConfigCategory category, std::string_view sFileName)

static void	removeFile (std::filesystem::path pathToConfigFile)

Static Private Member Functions
static std::variant< std::filesystem::path, Error >	constructFilePath (ConfigCategory category, std::string_view sFileName)

static std::string	generateFreeFileName (const std::set< std::string > &usedFileNames, const std::string &sFileNamePrefix="")

Private Attributes
toml::value	tomlData

std::filesystem::path	filePath

Static Private Attributes
static const char *	sBackupFileExtension = ".old"

Detailed Description

Allows saving and loading configuration in key-value style.

Constructor & Destructor Documentation

◆ ConfigManager()

ne::ConfigManager::ConfigManager ( )

default

Constructs an empty configuration, use loadFile to read configuration from a file or setValue methods and then saveFile to save a new configuration.

Member Function Documentation

◆ constructFilePath()

std::variant< std::filesystem::path, Error > ne::ConfigManager::constructFilePath	(	ConfigCategory	category,
		std::string_view	sFileName
	)

staticprivate

Constructs a file path from file name.

Parameters

category	Directory in which we will store this file. Use PROGRESS category to save player's game progress and SETTINGS to store player's settings.
sFileName	Name of the file, a predefined directory will be appended to the beginning, the .toml extension will be added if the passed name does not have it.

Returns: Error if something went wrong, valid path otherwise.

◆ generateFreeFileName()

std::string ne::ConfigManager::generateFreeFileName	(	const std::set< std::string > &	usedFileNames,
		const std::string &	sFileNamePrefix = `""`
	)

staticprivate

Generates a free (unused) file name (without extension).

Parameters

usedFileNames	File names (without extension) that cannot be used.
sFileNamePrefix	Prefix for generated file name. Final prefix may be different.

Returns: Generated file name (without extension).

◆ getAllFileNames()

std::set< std::string > ne::ConfigManager::getAllFileNames ( ConfigCategory category )

static

Returns file names (without extension) that this category (directory) contains.

Remarks: Does not include names of backup files.; How backup files are handled: Imagine you had a file player.toml and a backup file (player.toml.old). If for some reason player.toml (the original file) does not exist, but its backup file is there, we will copy the backup file (player.toml.old) as the original file (will copy player.toml.old as player.toml) and return player as a file name.

Parameters

category Category (directory) in which to look for files.

Returns: All files in the specified category (backup files are excluded).

◆ getAllKeysOfSection()

std::variant< std::vector< std::string >, Error > ne::ConfigManager::getAllKeysOfSection ( std::string_view sSection ) const

Returns all keys of the specified section.

Parameters

sSection Name of the section to look for keys, use getAllSections to get names of all sections.

Returns: Error if something went wrong, a vector of keys otherwise.

◆ getAllSections()

std::vector< std::string > ne::ConfigManager::getAllSections ( )

Returns names of all sections.

Returns: Names of all sections.

◆ getBackupFileExtension()

std::string ne::ConfigManager::getBackupFileExtension ( )

static

Returns file extension used to store backup files, for example: ".old".

Returns: File extension used to store backup files.

◆ getCategoryDirectory()

std::filesystem::path ne::ConfigManager::getCategoryDirectory ( ConfigCategory category )

static

Returns path to the directory used to store specific category of files. Path will be created if not existed before.

Parameters

category Category for which to return path.

Returns: Path to the directory of the specified category.

◆ getConfigFormatExtension()

std::string ne::ConfigManager::getConfigFormatExtension ( )

static

Returns file format extension used to store config files.

Returns: File extension that starts with a dot, for example: ".toml".

◆ getFilePath()

std::filesystem::path ne::ConfigManager::getFilePath ( ) const

Returns full path to the file if it was loaded using loadFile or saved using saveFile.

Returns: Full path to the file.

◆ getFreeProgressProfileName()

std::string ne::ConfigManager::getFreeProgressProfileName ( )

static

Goes through all existing (on disk) config files used for storing user's progress (PROGRESS category, see getAllFileNames) and returns the name of the file that is not used (free) by existing progress config files.

Remarks: This function is useful for getting the name of the new player profile (that will not conflict with existing profiles).

Returns: Name of the progress config file without extension.

◆ getValue()

template<typename T >

T ne::ConfigManager::getValue	(	std::string_view	sSection,
		std::string_view	sKey,
		T	defaultValue
	)		const

Reads a value from the loaded file (see loadFile).

Possible value types:

integer types (underlying type for integer is std::int64_t),
float/double,
bool,
strings,
date/time,
array containers (vector, list, deque, etc.),
map containers (std::unordered_map<std::string, T>, etc.) (key should be std::string).

In order to use custom user types include ConfigManager and see our ShaderDescription class or: https://github.com/ToruNiina/toml11#conversion-between-toml-value-and-arbitrary-types

Example:

// sample.toml:
// pi      = 3.14
// numbers = [1,2,3]
// time    = 1979-05-27T07:32:00Z
// [server]
// port    = 12312
using std::chrono::system_clock;
double pi = manager.getValue<double>("", "pi", 0.0);
std::vector<int> = manager.getValue<std::vector<int>>("", "numbers", std::vector<int>{});
system_clock::time_point time = manager.getValue<time_point>("", "time", system_clock::now());
int port = manager.getValue<int>("server", "port", 0);

Parameters

sSection	Name of the section (can be empty if the key has no section).
sKey	Name of the key.
defaultValue	Value that will be returned if the specified key was not found.

Returns: Default value if the specified section/key was not found, otherwise value from file.

◆ loadFile() [1/2]

std::optional< Error > ne::ConfigManager::loadFile	(	ConfigCategory	category,
		std::string_view	sFileName
	)

Loads data from TOML file. File should exist, otherwise an error will be returned (you can use getAllFileNames or getCategoryDirectory to see if files exist). If you used saveFile before and enabled a backup file (see saveFile), if usual file does not exist this function will look for a backup file and if found, will copy this backup file with a name of the usual file.

Parameters

category	Directory in which we will store this file. Use PROGRESS category to save player's game progress and SETTINGS to store player's settings.
sFileName	Name of the file to load. We will load it from a predefined directory that we also use in saveFile (use getFilePath to see full path), the .toml extension will be added if the passed name does not have it.

Returns: Error if something went wrong.

◆ loadFile() [2/2]

std::optional< Error > ne::ConfigManager::loadFile ( std::filesystem::path pathToConfigFile )

Loads data from file.

Prefer to use the other overload (loadFile) that uses a category instead of a path.

If you used saveFile before with PROGRESS category, if the usual (original) file does not exist this function will look for a backup file and if found, will copy this backup file with a name of the usual (original) file (so this function will restore the original file if it was deleted).

Parameters

pathToConfigFile Path to the file to load (should exist). The .toml extension will be added if the passed path does not have it.

Returns: Error if something went wrong.

◆ removeFile() [1/2]

std::optional< Error > ne::ConfigManager::removeFile	(	ConfigCategory	category,
		std::string_view	sFileName
	)

static

Removes a file.

Remarks: This function will also remove the backup file of this file (if exists).

Parameters

category	Directory in which we will search for this file. Use PROGRESS category to search for player's game progress and SETTINGS to search for player's settings.
sFileName	Name of the file to remove. We will search it in a predefined directory that we also use in saveFile (use getFilePath to see full path), the .toml extension will be added if the passed name does not have it.

Returns: Error if something went wrong. No error will be returned if the file does not exist.

◆ removeFile() [2/2]

void ne::ConfigManager::removeFile ( std::filesystem::path pathToConfigFile )

static

Removes a file.

Remarks: This function will also remove the backup file of this file (if exists).

Parameters

pathToConfigFile Path to the file to remove. The .toml extension will be added if the passed path does not have it.

◆ saveFile() [1/2]

std::optional< Error > ne::ConfigManager::saveFile	(	ConfigCategory	category,
		std::string_view	sFileName
	)

Saves the current configuration to a file with a UTF-8 encoding.

Remarks: There is no need to save render settings as some parts of the engine save their own configs, for example, renderer will save last applied settings and restore them on start so you don't need to save them manually.; Note that you don't need to save player input settings here, use InputManager for this task, InputManager has save/load functions, for SETTINGS category save settings that InputManager can't handle, for example: mouse sensitivity.

Parameters

category Directory in which we will store this file. Use PROGRESS category to save player's game progress and SETTINGS to store player's settings. The difference is that for PROGRESS category we will use backup files, so that if user's progress was deleted we can use a backup file to restore it. SETTINGS category does not use backup files. Backup files handling is used internally so you don't need to worry about it.

sFileName Name of the file to save, prefer to have only ASCII characters in the file name. We will save it to a predefined directory that we also use in loadFile (use getFilePath to see full path), the .toml extension will be added if the passed name does not have it.

Returns: Error if something went wrong.

◆ saveFile() [2/2]

std::optional< Error > ne::ConfigManager::saveFile	(	std::filesystem::path	pathToConfigFile,
		bool	bEnableBackup
	)

Saves the current configuration to a file with a UTF-8 encoding.

Prefer to use the other overload (saveFile) that uses a category instead of a path.

Parameters

pathToConfigFile	Path to the file to save (if file does not exist, it will be created). The .toml extension will be added if the passed name does not have it.
bEnableBackup	If 'true' will also use a backup (copy) file. loadFile can use backup file if a usual configuration file does not exist. Generally you want to use a backup file if you are saving important information, such as player progress, other cases such as player game settings and etc. usually do not need a backup but you can use it if you want.

Returns: Error if something went wrong.

◆ setValue()

template<typename T >

void ne::ConfigManager::setValue	(	std::string_view	sSection,
		std::string_view	sKey,
		T	value,
		std::string_view	sComment = `""`
	)

Sets a value. This value will not be written to file until saveFile is called.

If the specified key was already set before (in the specified section), this call will overwrite it with the new value (that can have a different type).

Different sections can have keys with the same name (uniqueness per section). Example:

// sample.toml:
[section1]
test = test1
[section2]
test = test2

Possible value types:

integer types (underlying type for integer is std::int64_t),
float/double,
bool,
strings,
date/time,
array containers (vector, list, deque, etc.),
map containers (unordered_map, etc.).

In order to use custom user types include ConfigManager and see our ShaderDescription class or: https://github.com/ToruNiina/toml11#conversion-between-toml-value-and-arbitrary-types

Example:

// in order to create this sample.toml:
// pi      = 3.14
// numbers = [1,2,3]
// time    = 1979-05-27T07:32:00Z
// [server]
// port    = 12312
using std::chrono::system_clock;
manager.setValue<double>("", "pi", 3.14);
manager.setValue<std::vector<int>>("", "numbers", std::vector<int>{1, 2, 3});
manager.setValue<time_point>("", "time", system_clock::now());
manager.setValue<int>("server", "port", 12312);

Parameters

sSection	Name of the section (can be empty if the key has no section).
sKey	Name of the key.
value	Value to set.
sComment	Comment to add to this value.

Member Data Documentation

◆ filePath

std::filesystem::path ne::ConfigManager::filePath

private

Full path to file.

◆ sBackupFileExtension

const char* ne::ConfigManager::sBackupFileExtension = ".old"

inlinestaticprivate

File extension used for backup files.

◆ tomlData

toml::value ne::ConfigManager::tomlData

private

Config file structure

The documentation for this class was generated from the following files:

src/engine_lib/public/io/ConfigManager.h
src/engine_lib/private/io/ConfigManager.cpp

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ConfigManager()

Member Function Documentation

◆ constructFilePath()

◆ generateFreeFileName()

◆ getAllFileNames()

◆ getAllKeysOfSection()

◆ getAllSections()

◆ getBackupFileExtension()

◆ getCategoryDirectory()

◆ getConfigFormatExtension()

◆ getFilePath()

◆ getFreeProgressProfileName()

◆ getValue()

◆ loadFile() [1/2]

◆ loadFile() [2/2]

◆ removeFile() [1/2]

◆ removeFile() [2/2]

◆ saveFile() [1/2]

◆ saveFile() [2/2]

◆ setValue()

Member Data Documentation

◆ filePath

◆ sBackupFileExtension

◆ tomlData