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:

List of all members.

## Public Member Functions

Constructors

- KeyFile ()
    Construct an empty key file.
- ~KeyFile ()
    Destructor; Frees the memory allocated to the key file.

Accessors

- GKeyFile * g_key_file () const
    Get a pointer to the GKeyFile object.
- operator GKeyFile * () const
    Conversion operator; Safely converts a G::KeyFile object into a GKeyFile pointer.
- String get_start_group () const
    Gets the name of the start group of the file.
- std::vector< String > get_groups () const
    Gets all groups in the key file.
- std::vector< String > get_keys (const String &group_name, Error *error) const
    Gets all keys for the group name group_name.
- bool has_group (const String &group_name) const
    Determines whether the key file has the group group_name.
- bool 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.
- String get_value (const String &group_name, const String &key, Error *error) const
    Gets the value associated with key under group_name.
- String get_string (const String &group_name, const String &key, Error *error) const
    Gets the value associated with key under group_name.
- String 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.
- bool 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.
- int get_integer (const String &group_name, const String &key, Error *error) const
    Gets the value associated with key under group_name as an integer.
- std::vector< String > get_string_list (const String &group_name, const String &key, Error *error) const
    Gets the string values associated with key under group_name.
- std::vector< String > 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.
- std::vector< bool > get_boolean_list (const String &group_name, const String &key, Error *error) const
    Gets the values associated with key under group_name as bools.
- std::vector< int > get_integer_list (const String &group_name, const String &key, Error *error) const
    Gets the values associated with key under group_name as integers.
- String get_comment (const String &group_name, const String &key, Error *error) const
    Retreives a comment above key from group name group_name.
- String get_comment (const String &group_name, Error *error) const
    Retreives a comment from above group name group_name.

Methods

- void set_list_separator (char separator)
    Sets the character which is used to separate values in lists.
- bool load_from_file (const std::string &file, KeyFileFlagsField flags, Error *error)
    Loads a key file into an empty KeyFile object.
- bool load_from_data (const char *data, unsigned int length, KeyFileFlagsField flags, Error *error)
    Loads a key file from memory into an empty KeyFile object.
- bool 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.
- String to_data (Error *error)
    This method outputs the key file as a string.
- void set_value (const String &group_name, const String &key, const String &value)
    Associates a new value with key under group_name.
- void set_string (const String &group_name, const String &key, const String &value)
    Associates a new string value with key under group_name.
- void 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.
- void set_boolean (const String &group_name, const String &key, bool value)
    Associates a new bool value with key under group_name.
- void set_integer (const String &group_name, const String &key, int value)
    Associates a new integer value with key under group_name.
- void 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.
- void 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.
- void 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.
- void 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.
- void set_comment (const String &group_name, const String &key, const String &comment, Error *error)
    Places a comment above key from group name group_name.
- void set_comment (const String &group_name, const String &comment, Error *error)
    Places a comment above group name group_name.
- void remove_comment (const String &group_name, const String &key, Error *error)
    Removes a comment above key from group name group_name.
- void remove_comment (const String &group_name, Error *error)
    Removes a comment from above group name group_name.
- void remove_key (const String &group_name, const String &key, Error *error)
    Removes key in group_name from the key file.
- void remove_group (const String &group_name, Error *error)
    Removes the specified group, group_name, from the key file.

## 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:

- keyfile.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3