edelib  2.1.0
Public Member Functions | Static Public Member Functions | List of all members
Resource Class Reference

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")
 

Detailed Description

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:

* # Let say you have foo.conf installed in $XDG_CONFIG_DIRS/foo.conf
* # with this content
* [globals]
* first_value = 1
* second_value = 2
*
* # Then if user want to override only first_value, but not copy the whole foo.conf
* # in $XDG_CONFIG_HOME/foo.conf, it will create $XDG_CONFIG_HOME/foo.conf with
* # this content
* [globals]
* first_value = 34
*
* # And application will get 34 for first_value and 2 for second_value.
*

You can also limit what key/values user can override or not using ResourceType parameter. A short sample:

* // You have foo.conf in $XDG_CONFIG_DIRS with this content:
* // [prefs]
* // value_one = 1
* // value_two = 2
* //
* // and you don't want user override value_two in any chance by placing
* // foo.conf in $XDG_CONFIG_HOME directory; overriding value_one is ok.
* // You will do this:
*
* int fetched;
* if(!r.load("foo"))
* // bail
*
* r.get("prefs", "value_one", fetched, 0);
* // this can't be overriden, unless you do it in $XDG_CONFIG_DIRS/foo.conf
* r.get("prefs", "value_two", fetched, 0, RES_SYS_ONLY);
*

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:

* // Application will load myapp.conf and user can tune some
* // settings and some settings only administrator (or one who have access to
* // $XDG_CONFIG_DIRS/myapp.conf). This is the content of myapp.conf:
* // [settings]
* // debug_print = true
* // show_titlebar = true
* // show_in_tray = true
*
* // ...
* if(!r.load("myapp"))
* // bail
*
* bool dprint, titlebar, in_tray;
* r.get("settings", "debug_print", dprint, false);
* r.get("settings", "show_titlebar", titlebar, false);
*
* // user can't override this one
* r.get("settings", "show_in_tray", in_tray, false, RES_SYS_ONLY);
*
* // ...
*
* // storing
* r.set("settings", "debug_print", dprint);
* r.set("settings", "show_titlebar", titlebar);
*
* // since file will be saved in user $XDG_CONFIG_HOME directory, where user can
* // change it, this item will be ignored, so watch for this things !
* r.set("settings", "show_in_tray", in_tray);
*
* // and save it using only domain name
* r.save("myapp");
*

Constructor & Destructor Documentation

Resource ( )

Empty constructor

~Resource ( )

Clears internals

Member Function Documentation

void clear ( void  )

Clears all loaded data. Calls to any get() member after this will return false.

static String find_config ( const char *  name,
ResourceType  rt = RES_USER_FIRST,
const char *  prefix = "ede" 
)
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:

* String path = Resource::find_config("myconfig", RES_USER_FIRST);
*

Returned value is tested for accessibility via access() function, so you can be sure that returned value exists.

Returns
path if filename was found or empty string if failed
Parameters
nameis config filename without extension
rtis ResourceType variable
prefixsame as from load()
static String find_data ( const char *  name,
ResourceType  rt = RES_USER_FIRST,
const char *  prefix = "ede" 
)
static

Locate data in XDG_DATA_HOME and XDG_DATA_DIRS paths. Data can be anything, like file, directory, link, etc.

Returns
path if directory was found or empty string if failed
Parameters
nameis data name
rtis ResourceType variable
prefixsame as from load()
static String find_in_config_dir ( const char *  name,
ResourceType  rt = RES_USER_FIRST,
const char *  prefix = "ede" 
)
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.

Returns
path if data was found or empty string if failed
Parameters
nameis data name
rtis ResourceType variable
prefixsame 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retbuffer to copy returned value
sizesize of buffer
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retwhere to place returned value
dfldefault value, in case real value not found
rtis 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.

Returns
true if value exists
Parameters
sectionname of target section
keyname of target key
retis allocated by this function ad returned value will be copied in it
retsizesize of buffer
rtis 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.

Returns
true if value exist
Parameters
sectionname of target section
keyname of target key
retbuffer to copy returned value
sizesize of buffer
rtis ResourceType variable
bool load ( const char *  domain,
const char *  prefix = "ede" 
)

Load resource settings file. Internals will be cleared.

Returns
true if was able to find either user or system file
Parameters
domainis application specific settings file; by default it will search for domain.conf file
prefixis 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:
* // 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.
*
operator bool ( void  ) const
inline

With this, you can use:

* r.load(...);
* if(!r)
* ...
*
bool save ( const char *  domain,
const char *  prefix = "ede" 
)

Save content to the file.

Returns
true if file saving was ok, otherwise false.
Parameters
domainis application specific settings file; by default it will be domain.conf and will be stored in $XDG_CONFIG_HOME directory
prefixsame 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue 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.

Parameters
sectionname of target section
keyname of target key
valvalue to store within key

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