edelib 1.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Hierarchy
- Class Members

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;
Resource r;
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
// ...
Resource r;
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

  name | is config filename without extension
  rt | is ResourceType variable
  prefix | same 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

  name | is data name
  rt | is ResourceType variable
  prefix | same 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

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if value exists

Parameters

  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.

Returns
  true if value exist

Parameters

  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.

Returns
  true if was able to find either user or system file

Parameters

  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.

operator bool | ( | void |  | ) | const

inline

With this, you can use:

Resource r;
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

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  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.

Parameters

  section | name of target section
  key | name of target key
  val | value to store within key

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

- edelib/Resource.h