Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Public Member Functions
Xfc::G::KeyFile Class Reference

A C++ wrapper interface for the GKeyFile configuration file parser. More...

#include <xfc/glib/keyfile.hh>

Inheritance diagram for Xfc::G::KeyFile:
Xfc::Object Xfc::Trackable

List of all members.

Public Member Functions

Constructors

Detailed Description

A C++ wrapper interface for the GKeyFile configuration file parser.

KeyFile lets you parse, edit or create files containing groups of key-value pairs, which we call key files for lack of a better name. Several freedesktop.org specifications use key files now, e.g the Desktop Entry Specification and the Icon Theme Specification.

The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key files consists of groups of key-value pairs, interspersed with comments.

 # this is just an example
 # there can be comments before the first group
 
 [First Group]
 
 Name=Key File Example\tthis value shows\nescaping
 
 # localized strings are stored in multiple key-value pairs
 Welcome=Hello
 Welcome[de]=Hallo
 Welcome[fr]=Bonjour
 Welcome[it]=Ciao
 
 [Another Group]
 
 Numbers=2;20;-200;0
 
 Booleans=true;false;true;true

Lines beginning with a '#' and blank lines are considered comments.

Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group.

Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form key[locale]=value. Space before and after the '=' character are ignored. Newline, tab, carriage return and backslash characters are escaped as \n, \t, \r, and \\, respectively. To preserve initial and final spaces, these can also be escaped as \s.

Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, typically ';' or ','. To use the list separator character in a value in a list, it has to be escaped by prefixing it with a backslash.

This syntax is obviously inspired by the ini files commonly met on Windows, but there are some important differences:

  1. ini files use the ';' character to begin comments, key files use the '#' character.
  2. Key files allow only comments before the first group.
  3. Key files are always encoded in UTF-8.

Member Function Documentation

bool Xfc::G::KeyFile::get_boolean ( const String group_name,
const String key,
Error error 
) const

Gets the value associated with key under group_name as a bool value.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error.
Returns:
The value associated with the key as a bool.

If group_name is null, the start group is used. If key cannot be found then the return value is undefined and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated with key cannot be interpreted as a bool then the return value is also undefined and error is set to G::KEY_FILE_ERROR_INVALID_VALUE.

std::vector<bool> Xfc::G::KeyFile::get_boolean_list ( const String group_name,
const String key,
Error error 
) const

Gets the values associated with key under group_name as bools.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error, or null.
Returns:
A vector of bool holding the values associated with key as bools.

If group_name is null, the start_group is used. If key cannot be found then an empty vector is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated with key cannot be interpreted as bools then an empty vector is returned and error is set to G::KEY_FILE_ERROR_INVALID_VALUE.

String Xfc::G::KeyFile::get_comment ( const String group_name,
const String key,
Error error 
) const

Retreives a comment above key from group name group_name.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error, or null.
Returns:
The comment string.

If key is null then comment will be read from above group_name. If both key and group_name are null, then comment will be read from above the first group in the file.

String Xfc::G::KeyFile::get_comment ( const String group_name,
Error error 
) const

Retreives a comment from above group name group_name.

Parameters:
group_nameA group name.
errorThe return location for a G::Error, or null.
Returns:
The group comment string.

If group_name is null, then comment will be read from above the first group in the file.

std::vector<String> Xfc::G::KeyFile::get_groups ( ) const

Gets all groups in the key file.

Returns:
A vector of String holding all the group names in the key file.

If there are no group names in the key file the returned vector will be empty.

int Xfc::G::KeyFile::get_integer ( const String group_name,
const String key,
Error error 
) const

Gets the value associated with key under group_name as an integer.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error.
Returns:
The value associated with the key as an integer.

If group_name is null, the start_group is used. If key cannot be found then the return value is undefined and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated with key cannot be interpreted as an integer then the return value is also undefined and error is set to G::KEY_FILE_ERROR_INVALID_VALUE.

std::vector<int> Xfc::G::KeyFile::get_integer_list ( const String group_name,
const String key,
Error error 
) const

Gets the values associated with key under group_name as integers.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error, or null.
Returns:
A vector of int holding the values associated with key as integers.

If group_name is null, the start_group is used. If key cannot be found then an empty vector is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated with key cannot be interpreted as integers then an empty vector is returned and error is set to G::KEY_FILE_ERROR_INVALID_VALUE.

std::vector<String> Xfc::G::KeyFile::get_keys ( const String group_name,
Error error 
) const

Gets all keys for the group name group_name.

Parameters:
group_nameThe group name to get the keys for.
errorThe return location for a G::Error, or null.
Returns:
A vector of String holding all the keys for group_name in the key file.

In the event that the group_name cannot be found, the returned vector will be empty and error is set to G::KEY_FILE_ERROR_GROUP_NOT_FOUND.

Gets the name of the start group of the file.

Returns:
The start group of the key file.
String Xfc::G::KeyFile::get_string ( const String group_name,
const String key,
Error error 
) const

Gets the value associated with key under group_name.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error, or null.
Returns:
A String.

In the event the key cannot be found, a null string is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, a null string is returned and error is set to G::KEY_FILE_ERROR_GROUP_NOT_FOUND.

String Xfc::G::KeyFile::get_string ( const String group_name,
const String key,
const String locale,
Error error 
) const

Gets the value associated with key under group_name translated in the given locale if available.

Parameters:
group_nameA group name.
keyA key.
localeA locale, or null.
errorThe return location for a G::Error, or null.
Returns:
A String.

If locale is null then the current locale is assumed. If key cannot be found then a null string is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated with key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.

std::vector<String> Xfc::G::KeyFile::get_string_list ( const String group_name,
const String key,
Error error 
) const

Gets the string values associated with key under group_name.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error, or null.
Returns:
A vector of String holding the values associated with key.

In the event the key cannot be found, an empty vector is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, an empty vector is returned and error is set to G::KEY_FILE_ERROR_GROUP_NOT_FOUND.

std::vector<String> Xfc::G::KeyFile::get_string_list ( const String group_name,
const String key,
const String locale,
Error error 
) const

Gets the values associated with key under group_name translated in the given locale if available.

Parameters:
group_nameA group name.
keyA key.
localeA locale, such as "de", "fr", or "it".
errorThe return location for a G::Error, or null.
Returns:
A vector of String holding the values associated with key.

If locale is null then the current locale is assumed. If group_name is null, then the start group is used. If key cannot be found then an empty vector is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated with key cannot be interpreted or no suitable translations can be found then the untranslated values are returned.

String Xfc::G::KeyFile::get_value ( const String group_name,
const String key,
Error error 
) const

Gets the value associated with key under group_name.

Parameters:
group_nameA group name.
keyA key name.
errorThe return location for a G::Error, or null.
Returns:
The string value for key.

In the event the key cannot be found, a null string is returned and error is set to G::KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, a null string is returned and error is set to G::KEY_FILE_ERROR_GROUP_NOT_FOUND.

bool Xfc::G::KeyFile::has_group ( const String group_name) const

Determines whether the key file has the group group_name.

Parameters:
group_nameA group name.
Returns:
true if group_name is a part of the key file, false otherwise.
bool Xfc::G::KeyFile::has_key ( const String group_name,
const String key,
Error error 
) const

Determines whether the key file has the key key in the group group_name.

Parameters:
group_nameA group name.
keyA key name.
errorThe return location for a G::Error, or null.
Returns:
true if key is a part of group_name, false otherwise.

If group_name is null, the start group is used.

bool Xfc::G::KeyFile::load_from_data ( const char *  data,
unsigned int  length,
KeyFileFlagsField  flags,
Error error 
)

Loads a key file from memory into an empty KeyFile object.

Parameters:
dataA key file loaded in memory.
lengthThe length of data in bytes.
flagsOne or more flags from G::KeyFileFlags enumeration.
errorThe return location for a G::Error, or null.
Returns:
true if the key file could be loaded, false otherwise.

If the object cannot be created then error is set to a G::KeyFileError.

bool Xfc::G::KeyFile::load_from_data_dirs ( const String file,
String full_path,
KeyFileFlagsField  flags,
Error error 
)

This method looks for a key file named file in the paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), loads the file into the key_file and returns the file's full path in full_path.

Parameters:
fileA relative path to a filename to open and parse.
full_pathThe return location for a string containing the full path of the file.
flagsOne or more flags from G::KeyFileFlags enumeration.
errorThe return location for a G::Error, or null.
Returns:
true if the key file could be loaded, false otherwise.

If the file could not be loaded error is set to either a G::FileError or G::KeyFileError.

bool Xfc::G::KeyFile::load_from_file ( const std::string &  file,
KeyFileFlagsField  flags,
Error error 
)

Loads a key file into an empty KeyFile object.

Parameters:
fileThe path of the filename to load, in the GLib file name encoding.
flagsOne or more flags from G::KeyFileFlags enumeration.
errorThe return location for a G::Error, or null.
Returns:
true if the key file could be loaded, false otherwise.

To get the file name encoding call Xfc::String::to_filename(). If the file could not be loaded then error is set to either a G::FileError or G::KeyFileError.

void Xfc::G::KeyFile::remove_comment ( const String group_name,
const String key,
Error error 
)

Removes a comment above key from group name group_name.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error.

If key is null then comment will be removed from above group_name. If both key and group_name are null, then comment will be removed from above the first group in the file.

void Xfc::G::KeyFile::remove_comment ( const String group_name,
Error error 
)

Removes a comment from above group name group_name.

Parameters:
group_nameA group name.
errorThe return location for a G::Error.

If group_name is null, then comment will be removed from above the first group in the file.

void Xfc::G::KeyFile::remove_group ( const String group_name,
Error error 
)

Removes the specified group, group_name, from the key file.

Parameters:
group_nameA group name.
errorThe return location for a G::Error.
void Xfc::G::KeyFile::remove_key ( const String group_name,
const String key,
Error error 
)

Removes key in group_name from the key file.

Parameters:
group_nameA group name.
keyA key.
errorThe return location for a G::Error.
void Xfc::G::KeyFile::set_boolean ( const String group_name,
const String key,
bool  value 
)

Associates a new bool value with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valueA new bool value to associate with key.

If key cannot be found then it is created. If group_name is null, the start group is used.

void Xfc::G::KeyFile::set_boolean_list ( const String group_name,
const String key,
std::vector< bool > &  values 
)

Associates a list of bool values with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valuesA vector of bool holding the list of bool values.

If key cannot be found then it is created. If group_name is null, the start_group is used.

void Xfc::G::KeyFile::set_comment ( const String group_name,
const String key,
const String comment,
Error error 
)

Places a comment above key from group name group_name.

Parameters:
group_nameA group name.
keyA key.
commentA comment string.
errorThe return location for a G::Error, or null.

If key is null then comment will be written above group_name. If both key and group_name are null, then comment will be written above the first group in the file.

void Xfc::G::KeyFile::set_comment ( const String group_name,
const String comment,
Error error 
)

Places a comment above group name group_name.

Parameters:
group_nameA group name.
commentA comment string.
errorThe return location for a G::Error.

If group_name is null, then comment will be written above the first group in the file.

void Xfc::G::KeyFile::set_integer ( const String group_name,
const String key,
int  value 
)

Associates a new integer value with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valueA new integer value to associate with key.

If key cannot be found then it is created. If group_name is null, the start group is used.

void Xfc::G::KeyFile::set_integer_list ( const String group_name,
const String key,
std::vector< int > &  values 
)

Associates a list of integer values with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valuesA vector of int holding the list of integer values.

If key cannot be found then it is created. If group_name is null, the start_group is used.

void Xfc::G::KeyFile::set_list_separator ( char  separator)

Sets the character which is used to separate values in lists.

Parameters:
separatorThe separator.

Typically ';' or ',' are used as separators. The default list separator is ';'.

void Xfc::G::KeyFile::set_string ( const String group_name,
const String key,
const String value 
)

Associates a new string value with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valueA String.

If key cannot be found then it is created. If group_name cannot be found then it is created.

void Xfc::G::KeyFile::set_string ( const String group_name,
const String key,
const String locale,
const String value 
)

Associates a string value for key and locale under group_name.

Parameters:
group_nameA group name.
keyA key.
localeA locale, such as "de", "fr", or "it".
valueA String.

If the translation for key cannot be found then it is created.

void Xfc::G::KeyFile::set_string_list ( const String group_name,
const String key,
const std::vector< String > &  strings 
)

Associates a list of string values for key under group_name.

Parameters:
group_nameA group name.
keyA key.
stringsA vector of String holding the list of string values.

If key cannot be found then it is created. If group_name cannot be found then it is created.

void Xfc::G::KeyFile::set_string_list ( const String group_name,
const String key,
const String locale,
const std::vector< String > &  strings 
)

Associates a list of string values for key and locale under group_name.

Parameters:
group_nameA group name.
keyA key.
localeA locale, such as "de", "fr", or "it".
stringsA vector of String holding the list of locale string values.

If the translation for key cannot be found then it is created. If group_name is null, the start group is used.

void Xfc::G::KeyFile::set_value ( const String group_name,
const String key,
const String value 
)

Associates a new value with key under group_name.

Parameters:
group_nameA group name.
keyA key.
valueA string value.

If key cannot be found then it is created. If group_name cannot be found then it is created.

This method outputs the key file as a string.

Parameters:
errorThe return location for a G::Error, or null.
Returns:
A String holding the contents of the key file

The documentation for this class was generated from the following file:
Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC