[77:7] extends: object
GKeyFile parses .ini-like config files. GKeyFile 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. For example, 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. txt # 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_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, with a locale identifier of the form
lang_COUNTRY@MODIFIER where COUNTRY and MODIFIER are optional. As a
special case, the locale C is associated with the untranslated pair
key=value (since GLib 2.84). Space before and after the = character is
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:
; character to begin comments, key files use the #
character. - Key files do not allow for ungrouped keys meaning only comments
can precede 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 from [group]. - .ini files don’t have a strongly typed boolean
entry type, they only have GetProfileInt(). In key files, only true and
false (in lower case) are allowed. 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. Here is an example of loading a key
file and reading a value: c g_autoptr(GError) error = NULL; g_autoptr(GKeyFile) key_file = g_key_file_new (); if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) { if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) g_warning ("Error loading key file: %s", error->message); return; } g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); if (val == NULL && !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) { g_warning ("Error finding key in key file: %s", error->message); return; } else if (val == NULL) { // Fall back to a default value. val = g_strdup ("default-value"); } Here is an example of
creating and saving a key file: c g_autoptr(GKeyFile) key_file = g_key_file_new (); const gchar *val = …; g_autoptr(GError) error = NULL; g_key_file_set_string (key_file, "Group Name", "SomeKey", val); // Save as a file. if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) { g_warning ("Error saving key file: %s", error->message); return; } // Or store to a GBytes for use elsewhere. gsize data_len; g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); if (data == NULL) { g_warning ("Error saving key file: %s", error->message); return; } g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); GKeyFile (Handle = null)
Creates a new empty [struct@GLib.KeyFile] object. Use [method@GLib.KeyFile.load_from_file], [method@GLib.KeyFile.load_from_data], [method@GLib.KeyFile.load_from_dirs] or [method@GLib.KeyFile.load_from_data_dirs] to read an existing key file.
Handle is an optional native handle or wrapper whose handle to adopt; when the native constructor is called.toNativeHandle (Source)
Normalizes a constructor argument into a raw pointer carrier. Accepts a raw NativeHandle, a raw NativeBuffer returned from
fn.call(...), another generated wrapper exposinghandle(), or null. Returns null when the argument carries no pointer.
Source is the raw handle, raw buffer, wrapper, or null.A raw pointer carrier or null when no pointer is present.getLib ()
Returns the opened native library for this generated wrapper.
The opened native library.handle ()
Returns the wrapped NativeHandle.
The wrapped NativeHandle.isNull ()
Returns true when the wrapped handle is null.
A bool.describe ()
Returns a small string for debugging generated wrappers.
A string.free ()
Clears all keys and groups from @key_file, and decreases the reference count by 1. If the reference count reaches zero, frees the key file and all its allocated memory.
None.get_boolean (string group_name, string key)
Returns the value associated with @key under @group_name as a boolean. If
cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as a boolean then [error@GLib.KeyFileError.INVALID_VALUE] is returned.group_name is a group name.key is a key.the value associated with the key as a boolean, or false if the key was not found or could not be parsed..get_boolean_list (string group_name, string key)
Returns the values associated with @key under @group_name as booleans. If
cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as booleans then [error@GLib.KeyFileError.INVALID_VALUE] is returned.group_name is a group name.key is a key.length is the number of booleans returned.the values associated with the key as a list of booleans, or NULL if the key was not found or could not be parsed. The returned list of booleans should be freed with [func@GLib.free] when no longer needed..get_comment (string group_name, string key)
Retrieves a comment above @key from @group_name. If @key is
NULLthen
will be read from above @group_name. If both @key andare NULL, then @comment will be read from above the first group in the file. Note that the returned string does not include the # comment markers, but does include any whitespace after them (on each line). It includes the line breaks between lines, but does not include the final line break.group_name is a group name, or NULL to get a top-level comment.key is a key, or NULL to get a group comment.a comment that should be freed with [func@GLib.free].get_double (string group_name, string key)
Returns the value associated with @key under @group_name as a double. If
cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as a double then [error@GLib.KeyFileError.INVALID_VALUE] is returned.group_name is a group name.key is a key.the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed..get_double_list (string group_name, string key)
Returns the values associated with @key under @group_name as doubles. If
cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as doubles then [error@GLib.KeyFileError.INVALID_VALUE] is returned.group_name is a group name.key is a key.length is the number of doubles returned.the values associated with the key as a list of doubles, or NULL if the key was not found or could not be parsed. The returned list of doubles should be freed with [func@GLib.free] when no longer needed..get_groups ()
Returns all groups in the key file loaded with @key_file. The array of returned groups will be
NULL-terminated, so @length may optionally beNULL.
length is return location for the number of returned groups, or NULL to ignore.a newly-allocated NULL-terminated array of strings. Use [func@GLib.strfreev] to free it..get_int64 (string group_name, string key)
Returns the value associated with @key under @group_name as a signed 64-bit integer. This is similar to [method@GLib.KeyFile.get_integer] but can return 64-bit results without truncation.
group_name is a group name.key is a key.the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed..get_integer (string group_name, string key)
Returns the value associated with @key under @group_name as an integer. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the value associated with @key cannot be interpreted as an integer, or is out of range for a
gint, then [error@GLib.KeyFileError.INVALID_VALUE] is returned.
group_name is a group name.key is a key.the value associated with the key as an integer, or 0 if the key was not found or could not be parsed..get_integer_list (string group_name, string key)
Returns the values associated with @key under @group_name as integers. If
cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. Likewise, if the values associated with @key cannot be interpreted as integers, or are out of range for gint, then [error@GLib.KeyFileError.INVALID_VALUE] is returned.group_name is a group name.key is a key.length is the number of integers returned.the values associated with the key as a list of integers, or NULL if the key was not found or could not be parsed. The returned list of integers should be freed with [func@GLib.free] when no longer needed..get_keys (string group_name)
Returns all keys for the group name @group_name. The array of returned keys will be
NULL-terminated, so @length may optionally beNULL. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
group_name is a group name.length is return location for the number of keys returned, or NULL to ignore.a newly-allocated NULL-terminated array of strings. Use [func@GLib.strfreev] to free it..get_locale_for_key (string group_name, string key, string locale)
Returns the actual locale which the result of [method@GLib.KeyFile.get_locale_string] or [method@GLib.KeyFile.get_locale_string_list] came from. If calling [method@GLib.KeyFile.get_locale_string] or [method@GLib.KeyFile.get_locale_string_list] with exactly the same
@group_name, @key and @locale, the result of those functions will have originally been tagged with the locale that is the result of this function.group_name is a group name.key is a key.locale is a locale identifier or NULL to use the current locale.the locale from the file, or NULL if the key was not found or the entry in the file was was untranslated.get_locale_string (string group_name, string key, string locale)
Returns the value associated with @key under @group_name translated in the given @locale if available. If @locale is
Cthen the untranslated value is returned (since GLib 2.84). If @locale isNULLthen the current locale is assumed. If @locale is to be non-NULL, or if the current locale will change over the lifetime of the [struct@GLib.KeyFile], it must be loaded with [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all locales. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the value associated with @key cannot be interpreted or no suitable translation can be found then the untranslated value is returned.
group_name is a group name.key is a key.locale is a locale identifier or NULL to use the current locale.a newly allocated string or NULL if the specified key cannot be found..get_locale_string_list (string group_name, string key, string locale)
Returns the values associated with @key under @group_name translated in the given @locale if available. If @locale is
Cthen the untranslated value is returned (since GLib 2.84). If @locale isNULLthen the current locale is assumed. If @locale is to be non-NULL, or if the current locale will change over the lifetime of the [struct@GLib.KeyFile], it must be loaded with [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all locales. If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the values associated with @key cannot be interpreted or no suitable translations can be found then the untranslated values are returned. The returned array isNULL-terminated, so @length may optionally beNULL.
group_name is a group name.key is a key.locale is a locale identifier or NULL to use the current locale.length is return location for the number of returned strings or NULL to ignore.a newly allocated NULL-terminated string array or NULL if the key isn’t found. The string array should be freed with [func@GLib.strfreev]..get_start_group ()
Returns the name of the start group of the file.
The start group of the key file..get_string (string group_name, string key)
Returns the string value associated with @key under @group_name. Unlike [method@GLib.KeyFile.get_value], this function handles escape sequences like
\s. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
group_name is a group name.key is a key.a newly allocated string or NULL if the specified key cannot be found..get_string_list (string group_name, string key)
Returns the values associated with @key under @group_name. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
group_name is a group name.key is a key.length is return location for the number of returned strings, or NULL to ignore.a NULL-terminated string array or NULL if the specified key cannot be found. The array should be freed with [func@GLib.strfreev]..get_uint64 (string group_name, string key)
Returns the value associated with @key under @group_name as an unsigned 64-bit integer. This is similar to [method@GLib.KeyFile.get_integer] but can return large positive results without truncation.
group_name is a group name.key is a key.the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed..get_value (string group_name, string key)
Returns the raw value associated with @key under @group_name. Use [method@GLib.KeyFile.get_string] to retrieve an unescaped UTF-8 string. If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is returned. If the @group_name cannot be found, [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
group_name is a group name.key is a key.a newly allocated string or NULL if the specified key cannot be found..has_group (string group_name)
Looks whether the key file has the group @group_name.
group_name is a group name.true if @group_name is a part of @key_file, false otherwise..has_key (string group_name, string key)
Looks whether the key file has the key @key in the group @group_name. Note that this function does not follow the rules for [struct@GLib.Error] strictly; the return value both carries meaning and signals an error. To use this function, you must pass a [struct@GLib.Error] pointer in @error, and check whether it is not
NULLto see if an error occurred. Language bindings should use [method@GLib.KeyFile.get_value] to test whether a key exists.
group_name is a group name.key is a key name.true if @key is a part of @group_name, false otherwise.load_from_bytes (object bytes, string flags)
Loads a key file from the data in @bytes into an empty [struct@GLib.KeyFile] structure. If the object cannot be created then a [error@GLib.KeyFileError] is returned.
bytes is a [struct@GLib.Bytes].flags is flags from [flags@GLib.KeyFileFlags].true if a key file could be loaded, false otherwise.load_from_data (string data, int length, string flags)
Loads a key file from memory into an empty [struct@GLib.KeyFile] structure. If the object cannot be created then a [error@GLib.KeyFileError is returned.
data is key file loaded in memory.length is the length of @data in bytes (or (gsize)-1 if data is nul-terminated).flags is flags from [flags@GLib.KeyFileFlags].true if a key file could be loaded, false otherwise.load_from_data_dirs (string file, string flags)
Looks for a key file named @file in the paths returned from [func@GLib.get_user_data_dir] and [func@GLib.get_system_data_dirs]. The search algorithm from [method@GLib.KeyFile.load_from_dirs] is used. If
is found, it’s loaded into @key_file and its full path is returned in @full_path. If the file could not be loaded then either a [error@GLib.FileError] or [error@GLib.KeyFileError] is returned.file is a relative path to a filename to open and parse.full_path is return location for a string containing the full path of the file, or NULL to ignore.flags is flags from [flags@GLib.KeyFileFlags].true if a key file could be loaded, false otherwise.load_from_dirs (string file, list search_dirs, string flags)
Looks for a key file named @file in the paths specified in @search_dirs, loads the file into @key_file and returns the file’s full path in
@search_dirs are checked in the order listed in the array, with the highest priority directory listed first. Within each directory,is looked for. If it’s not found, - characters in @file are progressively replaced with directory separators to search subdirectories of the search directory. If the file has not been found after all - characters have been replaced, the next search directory in @search_dirs is checked. If the file could not be found in any of the @search_dirs, [error@GLib.KeyFileError.NOT_FOUND] is returned. If the file is found but the OS returns an error when opening or reading the file, a [error@GLib.FileError] is returned. If there is a problem parsing the file, a [error@GLib.KeyFileError] is returned.file is a relative path to a filename to open and parse.search_dirs is NULL-terminated array of directories to search.full_path is return location for a string containing the full path of the file, or NULL to ignore.flags is flags from [flags@GLib.KeyFileFlags].true if a key file could be loaded, false otherwise.load_from_file (string file, string flags)
Loads a key file into an empty [struct@GLib.KeyFile] structure. If the OS returns an error when opening or reading the file, a [error@GLib.FileError] is returned. If there is a problem parsing the file, a [error@GLib.KeyFileError] is returned. This function will never return a [error@GLib.KeyFileError.NOT_FOUND] error. If the @file is not found, [error@GLib.FileError.NOENT] is returned.
file is the path of a filename to load, in the GLib filename encoding.flags is flags from [flags@GLib.KeyFileFlags].true if a key file could be loaded, false otherwise.ref ()
Increases the reference count of @key_file.
the same @key_file..remove_comment (string group_name, string key)
Removes a comment above @key from @group_name. If @key is
NULLthen
will be removed above @group_name. If both @key and @group_name are NULL, then @comment will be removed above the first group in the file.group_name is a group name, or NULL to get a top-level comment.key is a key, or NULL to get a group comment.true if the comment was removed, false otherwise.remove_group (string group_name)
Removes the specified group, @group_name, from the key file.
group_name is a group name.true if the group was removed, false otherwise.remove_key (string group_name, string key)
Removes @key in @group_name from the key file.
group_name is a group name.key is a key name to remove.true if the key was removed, false otherwise.save_to_file (string filename)
Writes the contents of @key_file to @filename using [func@GLib.file_set_contents]. If you need stricter guarantees about durability of the written file than are provided by [func@GLib.file_set_contents], use [func@GLib.file_set_contents_full] with the return value of [method@GLib.KeyFile.to_data]. This function can fail for any of the reasons that [func@GLib.file_set_contents] may fail.
filename is the name of the file to write to.true if successful, false otherwise.set_boolean (string group_name, string key, bool value)
Associates a new boolean value with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.value is true or false.None.set_boolean_list (string group_name, string key, list arg3List)
Associates a list of boolean values with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.list is an array of boolean values.length is length of @list.None.set_comment (string group_name, string key, string comment)
Places a comment above @key from @group_name. If @key is
NULLthen
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. Passing a non-existent @group_name or @key to this function returns false and populates @error. (In contrast, passing a non-existent group_name or key to [method@GLib.KeyFile.set_string] creates the associated group name and key.) Note that this function prepends a # comment marker to each line of @comment.group_name is a group name, or NULL to write a top-level comment.key is a key, or NULL to write a group comment.comment is a comment.true if the comment was written, false otherwise.set_double (string group_name, string key, double value)
Associates a new double value with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.value is a double value.None.set_double_list (string group_name, string key, list arg3List)
Associates a list of double values with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.list is an array of double values.length is number of double values in @list.None.set_int64 (string group_name, string key, int value)
Associates a new integer value with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.value is an integer value.None.set_integer (string group_name, string key, int value)
Associates a new integer value with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.value is an integer value.None.set_integer_list (string group_name, string key, list arg3List)
Associates a list of integer values with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.list is an array of integer values.length is number of integer values in @list.None.set_list_separator (int separator)
Sets the character which is used to separate values in lists. Typically
;or,are used as separators. The default list separator is;.
separator is the separator.None.set_locale_string (string group_name, string key, string locale, string arg4String)
Associates a string value for @key and @locale under @group_name. If the translation for @key cannot be found then it is created. If @locale is
Cthen the untranslated value is set (since GLib 2.84).
group_name is a group name.key is a key.locale is a locale identifier.string is a string.None.set_locale_string_list (string group_name, string key, string locale, list arg4List)
Associates a list of string values for @key and @locale under
If @locale is C then the untranslated value is set (since GLib 2.84). If the translation for @key cannot be found then it is created.group_name is a group name.key is a key.locale is a locale identifier.list is a NULL-terminated array of locale string values.length is the length of @list.None.set_string (string group_name, string key, string arg3String)
Associates a new string value with @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. Unlike [method@GLib.KeyFile.set_value], this function handles characters that need escaping, such as newlines.
group_name is a group name.key is a key.string is a string.None.set_string_list (string group_name, string key, list arg3List)
Associates a list of string values for @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created.
group_name is a group name.key is a key.list is an array of string values.length is number of string values in @list.None.set_uint64 (string group_name, string key, int value)
Associates a new integer value with @key under @group_name. If @key cannot be found then it is created.
group_name is a group name.key is a key.value is an integer value.None.set_value (string group_name, string key, string value)
Associates a new value with @key under @group_name. If @key cannot be found then it is created. If @group_name cannot be found then it is created. To set an UTF-8 string which may contain characters that need escaping (such as newlines or spaces), use [method@GLib.KeyFile.set_string].
group_name is a group name.key is a key.value is a string.None.to_data ()
Outputs @key_file as a string. Note that this function never reports an error.
length is return location for the length of the returned string, or NULL to ignore.a newly allocated string holding the contents of the key file.unref ()
Decreases the reference count of @key_file by 1. If the reference count reaches zero, frees the key file and all its allocated memory.
None.
