Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


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
Accessors
Methods

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_name A group name.
key A key.
error The 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_name A group name.
key A key.
error The 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,
Error *  error
)  const
 

Retreives a comment from above group name group_name.

Parameters:
group_name A group name.
error The 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.

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_name A group name.
key A key.
error The 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.

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_name A group name.
key A key.
error The 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_name A group name.
key A key.
error The 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_name The group name to get the keys for.
error The 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.

String Xfc::G::KeyFile::get_start_group (   )  const
 

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,
const String &  locale,
Error *  error
)  const
 

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

Parameters:
group_name A group name.
key A key.
locale A locale, or null.
error The 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.

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_name A group name.
key A key.
error The 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.

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_name A group name.
key A key.
locale A locale, such as "de", "fr", or "it".
error The 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.

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_name A group name.
key A key.
error The 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.

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_name A group name.
key A key name.
error The 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_name A 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_name A group name.
key A key name.
error The 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:
data A key file loaded in memory.
length The length of data in bytes.
flags One or more flags from G::KeyFileFlags enumeration.
error The 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:
file A relative path to a filename to open and parse.
full_path The return location for a string containing the full path of the file.
flags One or more flags from G::KeyFileFlags enumeration.
error The 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:
file The path of the filename to load, in the GLib file name encoding.
flags One or more flags from G::KeyFileFlags enumeration.
error The 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,
Error *  error
) 
 

Removes a comment from above group name group_name.

Parameters:
group_name A group name.
error The 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_comment (  const String &  group_name,
const String &  key,
Error *  error
) 
 

Removes a comment above key from group name group_name.

Parameters:
group_name A group name.
key A key.
error The 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_group (  const String &  group_name,
Error *  error
) 
 

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

Parameters:
group_name A group name.
error The 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_name A group name.
key A key.
error The 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_name A group name.
key A key.
value A 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_name A group name.
key A key.
values A 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 &  comment,
Error *  error
) 
 

Places a comment above group name group_name.

Parameters:
group_name A group name.
comment A comment string.
error The 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_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_name A group name.
key A key.
comment A comment string.
error The 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_integer (  const String &  group_name,
const String &  key,
int  value
) 
 

Associates a new integer value with key under group_name.

Parameters:
group_name A group name.
key A key.
value A 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_name A group name.
key A key.
values A 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:
separator The 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 &  locale,
const String &  value
) 
 

Associates a string value for key and locale under group_name.

Parameters:
group_name A group name.
key A key.
locale A locale, such as "de", "fr", or "it".
value A String.
If the translation for key cannot be found then it is created.

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_name A group name.
key A key.
value A 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_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_name A group name.
key A key.
locale A locale, such as "de", "fr", or "it".
strings A 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_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_name A group name.
key A key.
strings A 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_value (  const String &  group_name,
const String &  key,
const String &  value
) 
 

Associates a new value with key under group_name.

Parameters:
group_name A group name.
key A key.
value A string value.
If key cannot be found then it is created. If group_name cannot be found then it is created.

String Xfc::G::KeyFile::to_data (  Error *  error  ) 
 

This method outputs the key file as a string.

Parameters:
error The 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 4.3