/* Copyright(C) 2006 The gtkmm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or(at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ _MODULE(GLib-2.0) #include #include #include #include #include #include #ifndef DOXYGEN_SHOULD_SKIP_THIS extern "C" { typedef struct _GKeyFile GKeyFile; } #endif namespace Glib { _WRAP_ENUM(KeyFileFlags, GKeyFileFlags) /** Exception class for KeyFile errors. */ _WRAP_GERROR(KeyFileError, GKeyFileError) /** This class 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. * * @code * # 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 * @endcode * * 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 in value are escaped as \\n, \\t, \\r, and \\\\, respectively. To preserve leading spaces in * values, 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: * - .ini files use the ';' character to begin comments, key files use the '#' character. * - Key files allow only comments before the first group. * - Key files are always encoded in UTF-8. * - Key and Group names are case-sensitive, for example a group called [GROUP] is a different group from [group]. * * Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple * times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged * together. Another difference is that keys and group names in key files are not restricted to ASCII characters. * * @newin{2,14} */ class KeyFile { _CLASS_GENERIC(KeyFile, GKeyFile) public: //TODO: GKeyFile now seems to be a reference-counted type. //TODO: Maybe replace all the get_*/set_* methods with some generic get/set //methods when it is possible. /** Creates a new, empty KeyFile object. */ KeyFile(); /** Destructor */ ~KeyFile(); _IGNORE(g_key_file_free) /** Creates a glibmm KeyFile wrapper for a GKeyFile object. * Note, when using this that when the wrapper is deleted, * it will not automatically deleted the GKeyFile unless you * set the delete_c_instance boolean to true. * @param castitem The C instance to wrap * @param delete_c_instance If the C instance should be deleted when * the wrapper is deleted. */ KeyFile(GKeyFile* castitem, bool takes_ownership = false); public: _WRAP_METHOD(bool load_from_file(const std::string& filename, KeyFileFlags flags = Glib::KEY_FILE_NONE), g_key_file_load_from_file) /** Loads a KeyFile from memory * @param data The data to use as a KeyFile * @param flags Bitwise combination of the flags to use for the KeyFile * @return true if the KeyFile was successfully loaded, false otherwise * @throw Glib::KeyFileError */ bool load_from_data(const Glib::ustring& data, KeyFileFlags flags = Glib::KEY_FILE_NONE); _IGNORE(g_key_file_load_from_data) // TODO: This is wrong - full_path should be a std::string& (an out param). //_WRAP_METHOD(bool load_from_dirs(const std::string& file, const Glib::ArrayHandle& search_dirs, Glib::ArrayHandle& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE), g_key_file_load_from_dirs) // This has to be wrapped by hand. //_WRAP_METHOD(bool load_from_dirs(const std::string& file, const Glib::ArrayHandle& search_dirs, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE, g_key_file_load_from_dirs) /** Looks for a KeyFile named @a file in the paths returned from * g_get_user_data_dir() and g_get_system_data_dirs() and loads them * into the keyfile object, placing the full path to the file in * @a full_path. * @param file The file to search for * @param full_path Return location for a string containing the full path of the file * @param flags Bitwise combination of the flags to use for the KeyFile * @return true if the KeyFile was successfully loaded, false otherwise * @throw Glib::KeyFileError * @throw Glib::FileError */ bool load_from_data_dirs(const std::string& file, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE); _IGNORE(g_key_file_load_from_data_dirs) /** Outputs the KeyFile as a string * @return A string object holding the contents of KeyFile * @throw Glib::KeyFileError */ Glib::ustring to_data(); _IGNORE(g_key_file_to_data) _WRAP_METHOD(Glib::ustring get_start_group() const, g_key_file_get_start_group) /** Gets a list of all groups in the KeyFile * @returns A list containing the names of the groups */ Glib::ArrayHandle get_groups() const; _IGNORE(g_key_file_get_groups) /** Gets a list of all keys from the group @a group_name. * @param group_name The name of a group * @returns A list containing the names of the keys in @a group_name * @throw Glib::KeyFileError */ Glib::ArrayHandle get_keys(const Glib::ustring& group_name) const; _IGNORE(g_key_file_get_keys) _WRAP_METHOD(bool has_group(const Glib::ustring& group_name) const, g_key_file_has_group) _WRAP_METHOD(bool has_key(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_has_key) _WRAP_METHOD(Glib::ustring get_value(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_value) _WRAP_METHOD(Glib::ustring get_string(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_string) /** Gets the value associated with @a key under @a group_name translated * into the current locale. * @return the value as a Glib::ustring * @throw Glib::KeyFileError */ Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key) const; _IGNORE(g_key_file_get_locale_string) _WRAP_METHOD(Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const, g_key_file_get_locale_string) /** Gets the value in the first group, under @a key, interpreting it as * a boolean. * @param key The name of the key. * @return The value of @a key as a boolean. * @throw Glib::KeyFileError. * @newin{2,6} */ bool get_boolean(const Glib::ustring& key) const; _WRAP_METHOD(bool get_boolean(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_boolean) /** Gets the value in the first group, under @a key, interpreting it as * an integer. * @param key The name of the key * @return The value of @a key as an integer * @throw Glib::KeyFileError * @newin{2,6} */ int get_integer(const Glib::ustring& key) const; _WRAP_METHOD(int get_integer(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_integer) /** Gets the value in the first group, under @a key, interpreting it as * a signed 64-bit integer. This is similar to get_integer() but can return * 64-bit results without truncation. * @param key The name of the key. * @return The value of @a key as a signed 64-bit integer, or 0 if * the key was not found or could not be parsed. * @throw Glib::KeyFileError. * @newin{2,28} */ gint64 get_int64(const Glib::ustring& key) const; _WRAP_METHOD(gint64 get_int64(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_int64) /** Gets the value in the first group, under @a key, interpreting it as * an unsigned 64-bit integer. This is similar to get_integer() but can * return large positive results without truncation. * @param key The name of the key. * @return The value of @a key as an unsigned 64-bit integer, or 0 * if the key was not found or could not be parsed. * @throw Glib::KeyFileError. * @newin{2,28} */ guint64 get_uint64(const Glib::ustring& key) const; _WRAP_METHOD(guint64 get_uint64(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_uint64) /** Gets the value in the first group, under @a key, interpreting it as * a double. * @param key The name of the key * @return The value of @a key as an double * @throw Glib::KeyFileError * * @newin{2,14} */ double get_double(const Glib::ustring& key) const; _WRAP_METHOD(double get_double(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_double) _WRAP_METHOD(void set_double(const Glib::ustring& group_name, const Glib::ustring& key, double value), g_key_file_set_double) /** Associates a new double value with @a key under the start group. * If @a key cannot be found then it is created. * * @newin{2,12} * @param key A key. * @param value An double value. */ void set_double(const Glib::ustring& key, double value); /** Returns the values associated with @a key under @a group_name * @param group_name The name of a group * @param key The name of a key * @return A list containing the values requested * @throw Glib::KeyFileError */ Glib::ArrayHandle get_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const; _IGNORE(g_key_file_get_string_list) /** Returns the values associated with @a key under @a group_name * translated into the current locale, if available. * @param group_name The name of a group * @param key The name of a key * @return A list containing the values requested * @throw Glib::KeyFileError */ Glib::ArrayHandle get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const; /** Returns the values associated with @a key under @a group_name * translated into @a locale, if available. * @param group_name The name of a group * @param key The name of a key * @param locale The name of a locale * @return A list containing the values requested * @throw Glib::KeyFileError */ Glib::ArrayHandle get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const; _IGNORE(g_key_file_get_locale_string_list) /** Returns the values associated with @a key under @a group_name * @param group_name The name of a group * @param key The name of a key * @return A list of booleans * @throw Glib::KeyFileError */ Glib::ArrayHandle get_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key) const; _IGNORE(g_key_file_get_boolean_list) /** Returns the values associated with @a key under @a group_name * @param group_name The name of a group * @param key The name of a key * @return A list of integers * @throw Glib::KeyFileError */ Glib::ArrayHandle get_integer_list(const Glib::ustring& group_name, const Glib::ustring& key) const; _IGNORE(g_key_file_get_integer_list) /** Returns the values associated with @a key under @a group_name * @param group_name The name of a group * @param key The name of a key * @return A list of doubles * @throw Glib::KeyFileError */ Glib::ArrayHandle get_double_list(const Glib::ustring& group_name, const Glib::ustring& key) const; _IGNORE(g_key_file_get_double_list) /** Get comment from top of file * @return The comment * @throw Glib::KeyFileError */ Glib::ustring get_comment() const; /** Get comment from above a group * @param group_name The group * @return The comment * @throw Glib::KeyFileError */ Glib::ustring get_comment(const Glib::ustring& group_name) const; _WRAP_METHOD(Glib::ustring get_comment(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_comment) _WRAP_METHOD(void set_list_separator(gchar separator), g_key_file_set_list_separator) _WRAP_METHOD(void set_value(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& value), g_key_file_set_value) _WRAP_METHOD(void set_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& string), g_key_file_set_string) _WRAP_METHOD(void set_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ustring& string), g_key_file_set_locale_string) _WRAP_METHOD(void set_boolean(const Glib::ustring& group_name, const Glib::ustring& key, bool value), g_key_file_set_boolean) _WRAP_METHOD(void set_integer(const Glib::ustring& group_name, const Glib::ustring& key, int value), g_key_file_set_integer) _WRAP_METHOD(void set_int64(const Glib::ustring& group_name, const Glib::ustring& key, gint64 value), g_key_file_set_int64) _WRAP_METHOD(void set_uint64(const Glib::ustring& group_name, const Glib::ustring& key, guint64 value), g_key_file_set_uint64) /** Sets a list of string values for @a key under @a group_name. If * key cannot be found it is created. If @a group_name cannot be found * it is created. * @param group_name The name of a group * @param key The name of a key * @param list A list holding objects of type Glib::ustring */ void set_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle& list); _IGNORE(g_key_file_set_string_list) /** Sets a list of string values for the @a key under @a group_name and marks * them as being for @a locale. If the @a key or @a group_name cannot be * found, they are created. * @param group_name The name of a group * @param key The name of a key * @param locale A locale * @param list A list holding objects of type Glib::ustring */ void set_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ArrayHandle& list); _IGNORE(g_key_file_set_locale_string_list) /** Sets a list of booleans for the @a key under @a group_name. * If either the @a key or @a group_name cannot be found they are created. * @param group_name The name of a group * @param key The name of a key * @param list A list holding object of type bool */ void set_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle& list); _IGNORE(g_key_file_set_boolean_list) /** Sets a list of integers for the @a key under @a group_name. * If either the @a key or @a group_name cannot be found they are created. * @param group_name The name of a group * @param key The name of a key * @param list A list holding object of type int */ void set_integer_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle& list); _IGNORE(g_key_file_set_integer_list) /** Sets a list of doubles for the @a key under @a group_name. * If either the @a key or @a group_name cannot be found they are created. * @param group_name The name of a group * @param key The name of a key * @param list A list holding object of type int * * @newin{2,14} */ void set_double_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle& list); _IGNORE(g_key_file_set_double_list) /** Places @a comment at the start of the file, before the first group. * @param comment The Comment * @throw Glib::KeyFileError */ void set_comment(const Glib::ustring& comment); /** Places @a comment above @a group_name. * @param group_name The Group the comment should be above * @param comment The comment * @throw Glib::KeyFileError */ void set_comment(const Glib::ustring& group_name, const Glib::ustring& comment); _WRAP_METHOD(void set_comment(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& comment), g_key_file_set_comment) _WRAP_METHOD(void remove_comment(const Glib::ustring& group_name, const Glib::ustring& key), g_key_file_remove_comment) _WRAP_METHOD(void remove_key(const Glib::ustring& group_name, const Glib::ustring& key), g_key_file_remove_key) _WRAP_METHOD(void remove_group(const Glib::ustring& group_name), g_key_file_remove_group) GKeyFile* gobj() { return gobject_; } const GKeyFile* gobj() const { return gobject_; } protected: GKeyFile* gobject_; bool owns_gobject_; private: // noncopyable KeyFile(const KeyFile&); KeyFile& operator=(const KeyFile&); }; } // namespace Glib