nx_metadata_sdk  1.0
Metadata SDK
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
nx::kit::IniConfig Class Reference

#include <ini_config.h>

Inheritance diagram for nx::kit::IniConfig:
nx::vms_server_plugins::analytics::stub::Ini SavedIni TestIni

Classes

class  Impl
 

Public Member Functions

 IniConfig (const char *iniFile)
 
 IniConfig (const IniConfig &)=delete
 
 IniConfig (IniConfig &&)=delete
 
IniConfigoperator= (const IniConfig &)=delete
 
IniConfigoperator= (IniConfig &&)=delete
 
const char * iniFile () const
 
const char * iniFilePath () const
 
void reload ()
 
 Tweaks ()
 
 Tweaks (const Tweaks &)=delete
 
 Tweaks (Tweaks &&)=delete
 
Tweaks & operator= (const Tweaks &)=delete
 
Tweaks & operator= (Tweaks &&)=delete
 
template<typename T >
void set (const T *field, T newValue)
 

Static Public Member Functions

static bool isEnabled ()
 
static void setEnabled (bool value)
 
static void setOutput (std::ostream *output)
 
static const char * iniFilesDir ()
 
static void setIniFilesDir (const char *iniFilesDir)
 

Protected Member Functions

bool regBoolParam (const bool *pValue, bool defaultValue, const char *paramName, const char *description)
 
int regIntParam (const int *pValue, int defaultValue, const char *paramName, const char *description)
 
const char * regStringParam (const char *const *pValue, const char *defaultValue, const char *paramName, const char *description)
 
float regFloatParam (const float *pValue, float defaultValue, const char *paramName, const char *description)
 
double regDoubleParam (const double *pValue, double defaultValue, const char *paramName, const char *description)
 

Detailed Description

Mechanism for configuration variables that can alter the behavior of the code for the purpose of debugging and experimenting, with very little performance overhead. The default (initial) values are defined in the code and lead to the nominal behavior, which can be overridden by creating .ini files (with name=value lines) in the directory determined by the platform:

This unit can be compiled in the context of any C++ project.

Each derived class represents a dedicated .ini file. If, on attempt to load a file, it is found empty, the file is filled with default values and descriptions. The names of .ini files and their values are printed to stderr (configurable), overridden values marked with "*".

Usage example:

    struct Ini: nx::kit::IniConfig
    {
        // NOTE: Omit `reload();` if load-on-start is not needed.
        Ini(): IniConfig("my_module.ini") { reload(); }
        NX_INI_FLAG(0, myFlag, "Here 0 stands for 'false' as the default value.");
        NX_INI_INT(7, myInt, "Here 7 is the default value.");
        NX_INI_STRING("Default value", myStr, "Description.");
        NX_INI_FLOAT(1.0, myFloat, "Here 1.0 is the default value.");
        NX_INI_DOUBLE(1.0, myDouble, "Here 1.0 is the default value.");
    };
    inline Ini& ini()
    {
        static Ini ini;
        return ini;
    }

In the code, use ini().<param-name> to access the values. Call ini().reload() when needed, e.g. when certain activity starts or at regular intervals.

ATTENTION: Inline functions with static variables are safe to use only when the header is local to a single dynamic library or executable. Otherwise (if the header is included into more than one dynamic library or executable), due to compiler/linker limitations, such variables may have duplicate instances, thus, the function definition must be moved to a .cpp.

Allows to tweak IniConfig values for the duration defined by this object life time. Re-reading the values is disabled while at least one Tweaks instance exists. Intended for tests.

Usage:

{
IniConfig::Tweaks tweaks;
tweaks.set(&ini().parameter, value);
// The value will be altered up to the end of this scope.
}

Constructor & Destructor Documentation

◆ IniConfig()

nx::kit::IniConfig::IniConfig ( const char *  iniFile)
explicit
Parameters
iniFileName of .ini file without a path but including ".ini" suffix.

Member Function Documentation

◆ iniFile()

const char * nx::kit::IniConfig::iniFile ( ) const
Returns
Stored copy of the string supplied to the ctor.

◆ iniFilePath()

const char * nx::kit::IniConfig::iniFilePath ( ) const

◆ iniFilesDir()

const char * nx::kit::IniConfig::iniFilesDir ( )
static
Returns
Currently used path to .ini files, including the trailing slash or backslash.

◆ isEnabled()

bool nx::kit::IniConfig::isEnabled ( )
static
Returns
Whether reading .ini files is enabled. If disabled, the values are frozen at defaults. Enabled by default, can be disabled by setEnabled(false) or by defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DISABLED to minimize performance overhead.

◆ reload()

void nx::kit::IniConfig::reload ( )

Reload values from .ini file, logging the values first time, or if changed.

◆ setIniFilesDir()

void nx::kit::IniConfig::setIniFilesDir ( const char *  iniFilesDir)
static

Use the specified directory for .ini files. If iniFilesDir is null or empty, and also before this call, a platform-dependent directory is used (described in this class comment), which can be changed defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DEFAULT_INI_FILES_DIR=<enquoted-path-with-trailing-slash-or-backslash>

Parameters
iniFilesDirShould include the trailing slash or backslash.

◆ setOutput()

void nx::kit::IniConfig::setOutput ( std::ostream *  output)
static

Change the output stream, affecting all instances, null means silent. Before this call, all output goes to std::cerr, which can be changed defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DEFAULT_OUTPUT=<stream-address>, where <stream-address> can be e.g. '&std::cout', or 'nullptr' for no output.


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