<GKeyFile>

<GKeyFile>

Description

The GKeyFile struct contains only private data and should not be accessed directly.

Functions

get-boolean?

(define-values (%return) (key-file:get-boolean? self group-name key))

Returns the value associated with key under group_name as a boolean.

If key cannot be found then FALSE is returned and error is set to G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated with key cannot be interpreted as a boolean then FALSE is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

get-boolean-list

(define-values
  (%return length)
  (key-file:get-boolean-list self group-name key))

Returns the values associated with key under group_name as booleans.

If key cannot be found then NULL 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 booleans then NULL is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

length

the number of booleans returned

Inferred from %return

get-comment

(define-values (%return) (key-file:get-comment self group-name key))

Retrieves a comment above key from group_name. 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.

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.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name, or NULL

Passed as group-name

key

a key

Passed as key

get-double

(define-values (%return) (key-file:get-double self group-name key))

Returns the value associated with key under group_name as a double. If group_name is NULL, the start_group is used.

If key cannot be found then 0.0 is returned and error is set to G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated with key cannot be interpreted as a double then 0.0 is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

get-double-list

(define-values
  (%return length)
  (key-file:get-double-list self group-name key))

Returns the values associated with key under group_name as doubles.

If key cannot be found then NULL 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 doubles then NULL is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

length

the number of doubles returned

Inferred from %return

get-groups

(define-values (%return length) (key-file:get-groups self))

Returns all groups in the key file loaded with key_file. The array of returned groups will be NULL-terminated, so length may optionally be NULL.

Parameters

key_file

a GKeyFile

Passed as self

length

return location for the number of returned groups, or NULL

Passed as length

get-int64

(define-values (%return) (key-file:get-int64 self group-name key))

Returns the value associated with key under group_name as a signed 64-bit integer. This is similar to g_key_file_get_integer() but can return 64-bit results without truncation.

Parameters

key_file

a non-NULL GKeyFile

Passed as self

group_name

a non-NULL group name

Passed as group-name

key

a non-NULL key

Passed as key

get-integer

(define-values (%return) (key-file:get-integer self group-name key))

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

If key cannot be found then 0 is returned 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, or is out of range for a gint, then 0 is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

get-integer-list

(define-values
  (%return length)
  (key-file:get-integer-list self group-name key))

Returns the values associated with key under group_name as integers.

If key cannot be found then NULL 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, or are out of range for gint, then NULL is returned and error is set to G_KEY_FILE_ERROR_INVALID_VALUE.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

length

the number of integers returned

Inferred from %return

get-keys

(define-values (%return length) (key-file:get-keys self group-name))

Returns all keys for the group name group_name. The array of returned keys will be NULL-terminated, so length may optionally be NULL. In the event that the group_name cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

length

return location for the number of keys returned, or NULL

Passed as length

get-locale-for-key

(define-values
  (%return)
  (key-file:get-locale-for-key self group-name key locale))

Returns the actual locale which the result of g_key_file_get_locale_string() or g_key_file_get_locale_string_list() came from.

If calling g_key_file_get_locale_string() or g_key_file_get_locale_string_list() with exactly the same key_file, 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.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

locale

a locale identifier or NULL

Passed as locale

get-locale-string

(define-values
  (%return)
  (key-file:get-locale-string self group-name key locale))

Returns the value associated with key under group_name translated in the given locale if available. If locale is NULL then the current locale is assumed.

If locale is to be non-NULL, or if the current locale will change over the lifetime of the GKeyFile, it must be loaded with G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.

If key cannot be found then NULL 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.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

locale

a locale identifier or NULL

Passed as locale

get-locale-string-list

(define-values
  (%return length)
  (key-file:get-locale-string-list self group-name key locale))

Returns the values associated with key under group_name translated in the given locale if available. If locale is NULL then the current locale is assumed.

If locale is to be non-NULL, or if the current locale will change over the lifetime of the GKeyFile, it must be loaded with G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.

If key cannot be found then NULL 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. The returned array is NULL-terminated, so length may optionally be NULL.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

locale

a locale identifier or NULL

Passed as locale

length

return location for the number of returned strings or NULL

Inferred from %return

get-start-group

(define-values (%return) (key-file:get-start-group self))

Returns the name of the start group of the file.

Parameters

key_file

a GKeyFile

Passed as self

get-string

(define-values (%return) (key-file:get-string self group-name key))

Returns the string value associated with key under group_name. Unlike g_key_file_get_value(), this function handles escape sequences like \s.

In the event the key cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

get-string-list

(define-values
  (%return length)
  (key-file:get-string-list self group-name key))

Returns the values associated with key under group_name.

In the event the key cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

length

return location for the number of returned strings, or NULL

Inferred from %return

get-uint64

(define-values (%return) (key-file:get-uint64 self group-name key))

Returns the value associated with key under group_name as an unsigned 64-bit integer. This is similar to g_key_file_get_integer() but can return large positive results without truncation.

Parameters

key_file

a non-NULL GKeyFile

Passed as self

group_name

a non-NULL group name

Passed as group-name

key

a non-NULL key

Passed as key

get-value

(define-values (%return) (key-file:get-value self group-name key))

Returns the raw value associated with key under group_name. Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.

In the event the key cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the event that the group_name cannot be found, NULL is returned and error is set to G_KEY_FILE_ERROR_GROUP_NOT_FOUND.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

has-group?

(define-values (%return) (key-file:has-group? self group-name))

Looks whether the key file has the group group_name.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

load-from-bytes?

(define-values (%return) (key-file:load-from-bytes? self bytes flags))

Loads a key file from the data in bytes into an empty GKeyFile structure. If the object cannot be created then error is set to a GKeyFileError.

Parameters

key_file

an empty GKeyFile struct

Passed as self

bytes

a GBytes

Passed as bytes

flags

flags from GKeyFileFlags

Passed as flags

load-from-data?

(define-values (%return) (key-file:load-from-data? self data length flags))

Loads a key file from memory into an empty GKeyFile structure. If the object cannot be created then error is set to a GKeyFileError.

Parameters

key_file

an empty GKeyFile struct

Passed as self

data

key file loaded in memory

Passed as data

length

the length of data in bytes (or (gsize)-1 if data is nul-terminated)

Passed as length

flags

flags from GKeyFileFlags

Passed as flags

load-from-data-dirs

(define-values
  (%return full-path)
  (key-file:load-from-data-dirs self file flags))

This function 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 key_file and returns the file's full path in full_path. If the file could not be loaded then an error is set to either a GFileError or GKeyFileError.

Parameters

key_file

an empty GKeyFile struct

Passed as self

file

a relative path to a filename to open and parse

Passed as file

full_path

return location for a string containing the full path of the file, or NULL

Passed as full-path

flags

flags from GKeyFileFlags

Passed as flags

load-from-dirs

(define-values
  (%return full-path)
  (key-file:load-from-dirs self file search-dirs flags))

This function 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 full_path.

If the file could not be found in any of the search_dirs, G_KEY_FILE_ERROR_NOT_FOUND is returned. If the file is found but the OS returns an error when opening or reading the file, a G_FILE_ERROR is returned. If there is a problem parsing the file, a G_KEY_FILE_ERROR is returned.

Parameters

key_file

an empty GKeyFile struct

Passed as self

file

a relative path to a filename to open and parse

Passed as file

search_dirs

NULL-terminated array of directories to search

Passed as search-dirs

full_path

return location for a string containing the full path of the file, or NULL

Passed as full-path

flags

flags from GKeyFileFlags

Passed as flags

load-from-file?

(define-values (%return) (key-file:load-from-file? self file flags))

Loads a key file into an empty GKeyFile structure.

If the OS returns an error when opening or reading the file, a G_FILE_ERROR is returned. If there is a problem parsing the file, a G_KEY_FILE_ERROR is returned.

This function will never return a G_KEY_FILE_ERROR_NOT_FOUND error. If the file is not found, G_FILE_ERROR_NOENT is returned.

Parameters

key_file

an empty GKeyFile struct

Passed as self

file

the path of a filename to load, in the GLib filename encoding

Passed as file

flags

flags from GKeyFileFlags

Passed as flags

remove-comment?

(define-values (%return) (key-file:remove-comment? self group-name key))

Removes a comment above key from group_name. If key is NULL then comment 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.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name, or NULL

Passed as group-name

key

a key

Passed as key

remove-group?

(define-values (%return) (key-file:remove-group? self group-name))

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

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

remove-key?

(define-values (%return) (key-file:remove-key? self group-name key))

Removes key in group_name from the key file.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key name to remove

Passed as key

save-to-file?

(define-values (%return) (key-file:save-to-file? self filename))

Writes the contents of key_file to filename using g_file_set_contents(). If you need stricter guarantees about durability of the written file than are provided by g_file_set_contents(), use g_file_set_contents_full() with the return value of g_key_file_to_data().

This function can fail for any of the reasons that g_file_set_contents() may fail.

Parameters

key_file

a GKeyFile

Passed as self

filename

the name of the file to write to

Passed as filename

set-boolean

(define-values () (key-file:set-boolean self group-name key value))

Associates a new boolean value with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

TRUE or FALSE

Passed as value

set-boolean-list

(define-values () (key-file:set-boolean-list self group-name key list))

Associates a list of boolean values with key under group_name. If key cannot be found then it is created. If group_name is NULL, the start_group is used.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

list

an array of boolean values

Passed as list

length

length of list

Inferred from list

set-comment?

(define-values (%return) (key-file:set-comment? self group-name key comment))

Places a comment above key from group_name.

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.

Note that this function prepends a '#' comment marker to each line of comment.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name, or NULL

Passed as group-name

key

a key

Passed as key

comment

a comment

Passed as comment

set-double

(define-values () (key-file:set-double self group-name key value))

Associates a new double value with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

a double value

Passed as value

set-double-list

(define-values () (key-file:set-double-list self group-name key list))

Associates a list of double values with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

list

an array of double values

Passed as list

length

number of double values in list

Inferred from list

set-int64

(define-values () (key-file:set-int64 self group-name key value))

Associates a new integer value with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

an integer value

Passed as value

set-integer

(define-values () (key-file:set-integer self group-name key value))

Associates a new integer value with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

an integer value

Passed as value

set-integer-list

(define-values () (key-file:set-integer-list self group-name key list))

Associates a list of integer values with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

list

an array of integer values

Passed as list

length

number of integer values in list

Inferred from list

set-list-separator

(define-values () (key-file:set-list-separator self separator))

Sets the character which is used to separate values in lists. Typically ';' or ',' are used as separators. The default list separator is ';'.

Parameters

key_file

a GKeyFile

Passed as self

separator

the separator

Passed as separator

set-locale-string

(define-values
  ()
  (key-file:set-locale-string self group-name key locale string))

Associates a string value for key and locale under group_name. If the translation for key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

locale

a locale identifier

Passed as locale

string

a string

Passed as string

set-locale-string-list

(define-values
  ()
  (key-file:set-locale-string-list self group-name key locale list))

Associates a list of string values for key and locale under group_name. If the translation for key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

locale

a locale identifier

Passed as locale

list

a NULL-terminated array of locale string values

Passed as list

length

the length of list

Inferred from list

set-string

(define-values () (key-file:set-string self group-name key string))

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 g_key_file_set_value(), this function handles characters that need escaping, such as newlines.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

string

a string

Passed as string

set-string-list

(define-values () (key-file:set-string-list self group-name key list))

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.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

list

an array of string values

Passed as list

length

number of string values in list

Inferred from list

set-uint64

(define-values () (key-file:set-uint64 self group-name key value))

Associates a new integer value with key under group_name. If key cannot be found then it is created.

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

an integer value

Passed as value

set-value

(define-values () (key-file:set-value self group-name key 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 g_key_file_set_string().

Parameters

key_file

a GKeyFile

Passed as self

group_name

a group name

Passed as group-name

key

a key

Passed as key

value

a string

Passed as value

to-data

(define-values (%return length) (key-file:to-data self))

This function outputs key_file as a string.

Note that this function never reports an error, so it is safe to pass NULL as error.

Parameters

key_file

a GKeyFile

Passed as self

length

return location for the length of the returned string, or NULL

Passed as length

unref

(define-values () (key-file:unref self))

Decreases the reference count of key_file by 1. If the reference count reaches zero, frees the key file and all its allocated memory.

Parameters

key_file

a GKeyFile

Passed as self

key-file:new

(define-values (%return) (key-file:new))

Undocumented

key-file:error-quark

(define-values (%return) (key-file:error-quark))

Undocumented