edelib
2.1.0
|
Resource loader and saver. More...
#include <edelib/Resource.h>
Public Member Functions | |
Resource () | |
~Resource () | |
bool | load (const char *domain, const char *prefix="ede") |
bool | save (const char *domain, const char *prefix="ede") |
void | clear (void) |
operator bool (void) const | |
bool | get (const char *section, const char *key, char *ret, unsigned int size, ResourceType rt=RES_USER_FIRST) |
bool | get_localized (const char *section, const char *key, char *ret, unsigned int size, ResourceType rt=RES_USER_FIRST) |
bool | get_allocated (const char *section, const char *key, char **ret, unsigned int &retsize, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, int &ret, int dfl=0, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, bool &ret, bool dfl=false, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, float &ret, float dfl=0, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, long &ret, long dfl=0, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, double &ret, double dfl=0, ResourceType rt=RES_USER_FIRST) |
bool | get (const char *section, const char *key, char &ret, char dfl=0, ResourceType rt=RES_USER_FIRST) |
void | set (const char *section, const char *key, char *val) |
void | set (const char *section, const char *key, const char *val) |
void | set_localized (const char *section, const char *key, char *val) |
void | set_localized (const char *section, const char *key, const char *val) |
void | set (const char *section, const char *key, bool val) |
void | set (const char *section, const char *key, int val) |
void | set (const char *section, const char *key, long val) |
void | set (const char *section, const char *key, float val) |
void | set (const char *section, const char *key, double val) |
Static Public Member Functions | |
static String | find_config (const char *name, ResourceType rt=RES_USER_FIRST, const char *prefix="ede") |
static String | find_in_config_dir (const char *name, ResourceType rt=RES_USER_FIRST, const char *prefix="ede") |
static String | find_data (const char *name, ResourceType rt=RES_USER_FIRST, const char *prefix="ede") |
Resource loader and saver.
Resource class representing the way of loading and storing application settings and retrieving paths for application data. Application settings are read and saved (by default) in config files, handled by Config class (for format of config files, see documentation for Config class).
When you want to load application settings from it's specific config file, you load it by domain. Domain can be any name and prefered way is to use the same name as the name of application. Then Resource will append .conf suffix and try to find or save that as file name. With this way, Resource can be instructed to use another backend for storage (e.g. database).
How it will lookup for files? Resource uses XDG Base Directory Specification (see user_config_dir(), system_config_dirs(), user_data_dir(), system_data_dirs() and user_cache_dir()) for finding proper locations.
Resource class will also merge settings from config files, depending on ResourceType parameter for any of get() members. Merging can be described as overriding certain system settings, but keeping those that are not overridden (huh ;)). Here is simple example:
You can also limit what key/values user can override or not using ResourceType parameter. A short sample:
When you want to save settings, you do it with save(domain). Resource will save this file in $XDG_CONFIG_HOME appending .conf suffix. All user modifications will be preserved.
So, to sum things up, here is the complete example of loading and storing settings for some application:
Resource | ( | ) |
Empty constructor
~Resource | ( | ) |
Clears internals
void clear | ( | void | ) |
Clears all loaded data. Calls to any get() member after this will return false.
|
static |
Locate path of config filename searching XDG_CONFIG_HOME and XDG_CONFIG_DIRS paths. It is meant for locting config files. Config filename must not have an extension, example:
Returned value is tested for accessibility via access() function, so you can be sure that returned value exists.
name | is config filename without extension |
rt | is ResourceType variable |
prefix | same as from load() |
|
static |
Locate data in XDG_DATA_HOME and XDG_DATA_DIRS paths. Data can be anything, like file, directory, link, etc.
name | is data name |
rt | is ResourceType variable |
prefix | same as from load() |
|
static |
Locate data in XDG_CONFIG_HOME and XDG_CONFIG_DIRS paths. The difference between this function and find_config() is that find_config() will search only configuration files in this directories. find_in_config_dir() will try to search anything, like subdirectories or links.
name | is data name |
rt | is ResourceType variable |
prefix | same as from load() |
bool get | ( | const char * | section, |
const char * | key, | ||
char * | ret, | ||
unsigned int | size, | ||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get char* value from named section.
section | name of target section |
key | name of target key |
ret | buffer to copy returned value |
size | size of buffer |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
int & | ret, | ||
int | dfl = 0 , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get int value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
bool & | ret, | ||
bool | dfl = false , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get bool value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
float & | ret, | ||
float | dfl = 0 , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get float value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
long & | ret, | ||
long | dfl = 0 , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get long value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
double & | ret, | ||
double | dfl = 0 , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get double value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get | ( | const char * | section, |
const char * | key, | ||
char & | ret, | ||
char | dfl = 0 , |
||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get char value from named section.
section | name of target section |
key | name of target key |
ret | where to place returned value |
dfl | default value, in case real value not found |
rt | is ResourceType variable |
bool get_allocated | ( | const char * | section, |
const char * | key, | ||
char ** | ret, | ||
unsigned int & | retsize, | ||
ResourceType | rt = RES_USER_FIRST |
||
) |
This function is the same as get() with char*, except returned data is allocated. Use must call delete[] on returned data. If this function returns false, returned data will not be allocated and retsize will be 0.
section | name of target section |
key | name of target key |
ret | is allocated by this function ad returned value will be copied in it |
retsize | size of buffer |
rt | is ResourceType variable |
bool get_localized | ( | const char * | section, |
const char * | key, | ||
char * | ret, | ||
unsigned int | size, | ||
ResourceType | rt = RES_USER_FIRST |
||
) |
Get localized character data. Check get_localized() from Config for the details.
section | name of target section |
key | name of target key |
ret | buffer to copy returned value |
size | size of buffer |
rt | is ResourceType variable |
bool load | ( | const char * | domain, |
const char * | prefix = "ede" |
||
) |
Load resource settings file. Internals will be cleared.
domain | is application specific settings file; by default it will search for domain.conf file |
prefix | is added at the beggining of domain (e.g. "prefix/domain") and is used to setup default reading directory, so all config files can be stored in one place, like: * Resource r;
* // load foo.conf from XDG config dirs and 'ede' as subdirectory
* // e.g. if XDG_CONFIG_DIRS is "/etc/xdg:/opt/etc", directories "/etc/xdg/ede"
* // and "/opt/etc/ede" will be searched
* r.load("foo");
*
* // or load straight from /etc/xdg and /opt/etc directories
* r.load("foo", "");
*
* When prefix is NULL, it will not be appended to domain name.
*
|
|
inline |
With this, you can use:
bool save | ( | const char * | domain, |
const char * | prefix = "ede" |
||
) |
Save content to the file.
domain | is application specific settings file; by default it will be domain.conf and will be stored in $XDG_CONFIG_HOME directory |
prefix | same as from load() |
void set | ( | const char * | section, |
const char * | key, | ||
char * | val | ||
) |
Set char* value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
const char * | val | ||
) |
Set const char* value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
bool | val | ||
) |
Set bool value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
int | val | ||
) |
Set int value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
long | val | ||
) |
Set long value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
float | val | ||
) |
Set float value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set | ( | const char * | section, |
const char * | key, | ||
double | val | ||
) |
Set double value in named section. If section, or key does not exists, they will be created.
section | name of target section |
key | name of target key |
val | value to store within key |
void set_localized | ( | const char * | section, |
const char * | key, | ||
char * | val | ||
) |
Set char* value for localized named section. Description for get_localized() applies here too.
section | name of target section |
key | name of target key |
val | value to store within key |
void set_localized | ( | const char * | section, |
const char * | key, | ||
const char * | val | ||
) |
Set const char* value for localized named section. Description for get_localized() applies here too.
section | name of target section |
key | name of target key |
val | value to store within key |