gi-glib-2.0.30: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.KeyFile

Contents

- Exported types
- Methods
  - errorQuark
  - getBoolean
  - getBooleanList
  - getComment
  - getDouble
  - getDoubleList
  - getGroups
  - getInt64
  - getInteger
  - getIntegerList
  - getKeys
  - getLocaleForKey
  - getLocaleString
  - getLocaleStringList
  - getStartGroup
  - getString
  - getStringList
  - getUint64
  - getValue
  - hasGroup
  - loadFromBytes
  - loadFromData
  - loadFromDataDirs
  - loadFromDirs
  - loadFromFile
  - new
  - removeComment
  - removeGroup
  - removeKey
  - saveToFile
  - setBoolean
  - setBooleanList
  - setComment
  - setDouble
  - setDoubleList
  - setInt64
  - setInteger
  - setIntegerList
  - setListSeparator
  - setLocaleString
  - setLocaleStringList
  - setString
  - setStringList
  - setUint64
  - setValue
  - toData
  - unref

Description

`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 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_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:

- .ini files use the `;` 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 code

    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 code

    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);

Synopsis

- newtype KeyFile = KeyFile (ManagedPtr KeyFile)
- keyFileErrorQuark :: (HasCallStack, MonadIO m) => m Word32
- keyFileGetBoolean :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m ()
- keyFileGetBooleanList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m [Bool]
- keyFileGetComment :: (HasCallStack, MonadIO m) => KeyFile -> Maybe Text -> Maybe Text -> m Text
- keyFileGetDouble :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Double
- keyFileGetDoubleList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m [Double]
- keyFileGetGroups :: (HasCallStack, MonadIO m) => KeyFile -> m ([Text], CSize)
- keyFileGetInt64 :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Int64
- keyFileGetInteger :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Int32
- keyFileGetIntegerList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m [Int32]
- keyFileGetKeys :: (HasCallStack, MonadIO m) => KeyFile -> Text -> m ([Text], CSize)
- keyFileGetLocaleForKey :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Maybe Text -> m (Maybe Text)
- keyFileGetLocaleString :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Maybe Text -> m Text
- keyFileGetLocaleStringList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Maybe Text -> m ([Text], CSize)
- keyFileGetStartGroup :: (HasCallStack, MonadIO m) => KeyFile -> m (Maybe Text)
- keyFileGetString :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Text
- keyFileGetStringList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m ([Text], CSize)
- keyFileGetUint64 :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Word64
- keyFileGetValue :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m Text
- keyFileHasGroup :: (HasCallStack, MonadIO m) => KeyFile -> Text -> m Bool
- keyFileLoadFromBytes :: (HasCallStack, MonadIO m) => KeyFile -> Bytes -> [KeyFileFlags] -> m ()
- keyFileLoadFromData :: (HasCallStack, MonadIO m) => KeyFile -> Text -> CSize -> [KeyFileFlags] -> m ()
- keyFileLoadFromDataDirs :: (HasCallStack, MonadIO m) => KeyFile -> [Char] -> [KeyFileFlags] -> m [Char]
- keyFileLoadFromDirs :: (HasCallStack, MonadIO m) => KeyFile -> [Char] -> [[Char]] -> [KeyFileFlags] -> m [Char]
- keyFileLoadFromFile :: (HasCallStack, MonadIO m) => KeyFile -> [Char] -> [KeyFileFlags] -> m ()
- keyFileNew :: (HasCallStack, MonadIO m) => m KeyFile
- keyFileRemoveComment :: (HasCallStack, MonadIO m) => KeyFile -> Maybe Text -> Maybe Text -> m ()
- keyFileRemoveGroup :: (HasCallStack, MonadIO m) => KeyFile -> Text -> m ()
- keyFileRemoveKey :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> m ()
- keyFileSaveToFile :: (HasCallStack, MonadIO m) => KeyFile -> Text -> m ()
- keyFileSetBoolean :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Bool -> m ()
- keyFileSetBooleanList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> [Bool] -> m ()
- keyFileSetComment :: (HasCallStack, MonadIO m) => KeyFile -> Maybe Text -> Maybe Text -> Text -> m ()
- keyFileSetDouble :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Double -> m ()
- keyFileSetDoubleList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> [Double] -> m ()
- keyFileSetInt64 :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Int64 -> m ()
- keyFileSetInteger :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Int32 -> m ()
- keyFileSetIntegerList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> [Int32] -> m ()
- keyFileSetListSeparator :: (HasCallStack, MonadIO m) => KeyFile -> Int8 -> m ()
- keyFileSetLocaleString :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Text -> Text -> m ()
- keyFileSetLocaleStringList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Text -> [Text] -> CSize -> m ()
- keyFileSetString :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Text -> m ()
- keyFileSetStringList :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> [Text] -> CSize -> m ()
- keyFileSetUint64 :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Word64 -> m ()
- keyFileSetValue :: (HasCallStack, MonadIO m) => KeyFile -> Text -> Text -> Text -> m ()
- keyFileToData :: (HasCallStack, MonadIO m) => KeyFile -> m (Text, CSize)
- keyFileUnref :: (HasCallStack, MonadIO m) => KeyFile -> m ()

# Exported types

newtype KeyFile Source #

Memory-managed wrapper type.

Constructors

KeyFile (ManagedPtr KeyFile) |

#### Instances

Instances details

Eq KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile Methods (==) :: KeyFile -> KeyFile -> Bool Source # (/=) :: KeyFile -> KeyFile -> Bool Source #
GBoxed KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile
ManagedPtrNewtype KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile Methods toManagedPtr :: KeyFile -> ManagedPtr KeyFile Source #
TypedObject KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile Methods glibType :: IO GType Source #
HasParentTypes KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile
IsGValue (Maybe KeyFile) Source # | Convert `KeyFile` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GLib.Structs.KeyFile Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe KeyFile -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe KeyFile) Source #
type ParentTypes KeyFile Source # |
Instance details Defined in GI.GLib.Structs.KeyFile type ParentTypes KeyFile = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

hasGroup, loadFromBytes, loadFromData, loadFromDataDirs, loadFromDirs, loadFromFile, removeComment, removeGroup, removeKey, saveToFile, toData, unref.

#### Getters

getBoolean, getBooleanList, getComment, getDouble, getDoubleList, getGroups, getInt64, getInteger, getIntegerList, getKeys, getLocaleForKey, getLocaleString, getLocaleStringList, getStartGroup, getString, getStringList, getUint64, getValue.

#### Setters

setBoolean, setBooleanList, setComment, setDouble, setDoubleList, setInt64, setInteger, setIntegerList, setListSeparator, setLocaleString, setLocaleStringList, setString, setStringList, setUint64, setValue.

## errorQuark

keyFileErrorQuark :: (HasCallStack, MonadIO m) => m Word32 Source #

No description available in the introspection data.

## getBoolean

keyFileGetBoolean Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m () | (Can throw `GError`)

Returns the value associated with `key` under `groupName` as a boolean.

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 a boolean then [error`gLib`.KeyFileError.INVALID_VALUE] is returned.

Since: 2.6

## getBooleanList

keyFileGetBooleanList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m [Bool] | Returns: 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 `free` when no longer needed. (Can throw `GError`)

Returns the values associated with `key` under `groupName` as booleans.

If `key` 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.

Since: 2.6

## getComment

keyFileGetComment Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Maybe Text | `groupName`: a group name, or `NULL` to get a top-level comment
-> Maybe Text | `key`: a key, or `NULL` to get a group comment
-> m Text | Returns: a comment that should be freed with `free` (Can throw `GError`)

Retrieves a comment above `key` from `groupName`.

If `key` is `NULL` then `comment` will be read from above `groupName`. If both `key` and `groupName` 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.

Since: 2.6

## getDouble

keyFileGetDouble Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Double | Returns: the value associated with the key as a double, or `0.0` if the key was not found or could not be parsed. (Can throw `GError`)

Returns the value associated with `key` under `groupName` as a double.

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 a double then [error`gLib`.KeyFileError.INVALID_VALUE] is returned.

Since: 2.12

## getDoubleList

keyFileGetDoubleList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m [Double] | Returns: 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 `free` when no longer needed. (Can throw `GError`)

Returns the values associated with `key` under `groupName` as doubles.

If `key` 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.

Since: 2.12

## getGroups

keyFileGetGroups Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> m ([Text], CSize) | Returns: a newly-allocated `NULL`-terminated array of strings. Use `strfreev` to free it.

Returns all groups in the key file loaded with `keyFile`.

The array of returned groups will be `NULL`-terminated, so `length` may optionally be `NULL`.

Since: 2.6

## getInt64

keyFileGetInt64 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Int64 | Returns: 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. (Can throw `GError`)

Returns the value associated with `key` under `groupName` as a signed 64-bit integer.

This is similar to `keyFileGetInteger` but can return 64-bit results without truncation.

Since: 2.26

## getInteger

keyFileGetInteger Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Int32 | Returns: the value associated with the key as an integer, or `0` if the key was not found or could not be parsed. (Can throw `GError`)

Returns the value associated with `key` under `groupName` 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.

Since: 2.6

## getIntegerList

keyFileGetIntegerList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m [Int32] | Returns: 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 `free` when no longer needed. (Can throw `GError`)

Returns the values associated with `key` under `groupName` as integers.

If `key` 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.

Since: 2.6

## getKeys

keyFileGetKeys Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> m ([Text], CSize) | Returns: a newly-allocated `NULL`-terminated array of strings. Use `strfreev` to free it. (Can throw `GError`)

Returns all keys for the group name `groupName`.

The array of returned keys will be `NULL`-terminated, so `length` may optionally be `NULL`. If the `groupName` cannot be found, [error`gLib`.KeyFileError.GROUP_NOT_FOUND] is returned.

Since: 2.6

## getLocaleForKey

keyFileGetLocaleForKey Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Maybe Text | `locale`: a locale identifier or `NULL` to use the current locale
-> m (Maybe Text) | Returns: the locale from the file, or `NULL` if the key was not found or the entry in the file was was untranslated

Returns the actual locale which the result of `keyFileGetLocaleString` or `keyFileGetLocaleStringList` came from.

If calling `keyFileGetLocaleString` or `keyFileGetLocaleStringList` with exactly the same `keyFile`, `groupName`, `key` and `locale`, the result of those functions will have originally been tagged with the locale that is the result of this function.

Since: 2.56

## getLocaleString

keyFileGetLocaleString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Maybe Text | `locale`: a locale identifier or `NULL` to use the current locale
-> m Text | Returns: a newly allocated string or `NULL` if the specified key cannot be found. (Can throw `GError`)

Returns the value associated with `key` under `groupName` translated in the given `locale` if available.

If `locale` is `C` then the untranslated value is returned (since GLib 2.84).

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 `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.

Since: 2.6

## getLocaleStringList

keyFileGetLocaleStringList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Maybe Text | `locale`: a locale identifier or `NULL` to use the current locale
-> m ([Text], CSize) | Returns: a newly allocated `NULL`-terminated string array or `NULL` if the key isn’t found. The string array should be freed with `strfreev`. (Can throw `GError`)

Returns the values associated with `key` under `groupName` translated in the given `locale` if available.

If `locale` is `C` then the untranslated value is returned (since GLib 2.84).

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 `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 is `NULL`-terminated, so `length` may optionally be `NULL`.

Since: 2.6

## getStartGroup

keyFileGetStartGroup Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> m (Maybe Text) | Returns: The start group of the key file.

Returns the name of the start group of the file.

Since: 2.6

## getString

keyFileGetString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Text | Returns: a newly allocated string or `NULL` if the specified key cannot be found. (Can throw `GError`)

Returns the string value associated with `key` under `groupName`.

Unlike `keyFileGetValue`, this function handles escape sequences like `\s`.

If the key cannot be found, [error`gLib`.KeyFileError.KEY_NOT_FOUND] is returned. If the `groupName` cannot be found, [error`gLib`.KeyFileError.GROUP_NOT_FOUND] is returned.

Since: 2.6

## getStringList

keyFileGetStringList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m ([Text], CSize) | Returns: a `NULL`-terminated string array or `NULL` if the specified key cannot be found. The array should be freed with `strfreev`. (Can throw `GError`)

Returns the values associated with `key` under `groupName`.

If the key cannot be found, [error`gLib`.KeyFileError.KEY_NOT_FOUND] is returned. If the `groupName` cannot be found, [error`gLib`.KeyFileError.GROUP_NOT_FOUND] is returned.

Since: 2.6

## getUint64

keyFileGetUint64 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Word64 | Returns: 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. (Can throw `GError`)

Returns the value associated with `key` under `groupName` as an unsigned 64-bit integer.

This is similar to `keyFileGetInteger` but can return large positive results without truncation.

Since: 2.26

## getValue

keyFileGetValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> m Text | Returns: a newly allocated string or `NULL` if the specified key cannot be found. (Can throw `GError`)

Returns the raw value associated with `key` under `groupName`.

Use `keyFileGetString` to retrieve an unescaped UTF-8 string.

If the key cannot be found, [error`gLib`.KeyFileError.KEY_NOT_FOUND] is returned. If the `groupName` cannot be found, [error`gLib`.KeyFileError.GROUP_NOT_FOUND] is returned.

Since: 2.6

## hasGroup

keyFileHasGroup Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> m Bool | Returns: true if `groupName` is a part of `keyFile`, false otherwise.

Looks whether the key file has the group `groupName`.

Since: 2.6

## loadFromBytes

keyFileLoadFromBytes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an empty `KeyFile` struct
-> Bytes | `bytes`: a `Bytes`
-> [KeyFileFlags] | `flags`: flags from [flags`gLib`.KeyFileFlags]
-> m () | (Can throw `GError`)

Loads a key file from the data in `bytes` into an empty `KeyFile` structure.

If the object cannot be created then a [error`gLib`.KeyFileError] is returned.

Since: 2.50

## loadFromData

keyFileLoadFromData Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an empty key file
-> Text | `data`: key file loaded in memory
-> CSize | `length`: the length of `data` in bytes (or `(gsize)-1` if data is nul-terminated)
-> [KeyFileFlags] | `flags`: flags from [flags`gLib`.KeyFileFlags]
-> m () | (Can throw `GError`)

Loads a key file from memory into an empty `KeyFile` structure.

If the object cannot be created then a [error`gLib`.KeyFileError is returned.

Since: 2.6

## loadFromDataDirs

keyFileLoadFromDataDirs Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an empty `KeyFile` struct
-> [Char] | `file`: a relative path to a filename to open and parse
-> [KeyFileFlags] | `flags`: flags from [flags`gLib`.KeyFileFlags]
-> m [Char] | (Can throw `GError`)

Looks for a key file named `file` in the paths returned from `getUserDataDir` and `getSystemDataDirs`.

The search algorithm from `keyFileLoadFromDirs` is used. If `file` is found, it’s loaded into `keyFile` and its full path is returned in `fullPath`.

If the file could not be loaded then either a [error`gLib`.FileError] or [error`gLib`.KeyFileError] is returned.

Since: 2.6

## loadFromDirs

keyFileLoadFromDirs Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an empty `KeyFile` struct
-> [Char] | `file`: a relative path to a filename to open and parse
-> [[Char]] | `searchDirs`: `NULL`-terminated array of directories to search
-> [KeyFileFlags] | `flags`: flags from [flags`gLib`.KeyFileFlags]
-> m [Char] | (Can throw `GError`)

Looks for a key file named `file` in the paths specified in `searchDirs`, loads the file into `keyFile` and returns the file’s full path in `fullPath`.

`searchDirs` are checked in the order listed in the array, with the highest priority directory listed first. Within each directory, `file` 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 `searchDirs` is checked.

If the file could not be found in any of the `searchDirs`, [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.

Since: 2.14

## loadFromFile

keyFileLoadFromFile Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: an empty key file
-> [Char] | `file`: the path of a filename to load, in the GLib filename encoding
-> [KeyFileFlags] | `flags`: flags from [flags`gLib`.KeyFileFlags]
-> m () | (Can throw `GError`)

Loads a key file into an empty `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.

Since: 2.6

## new

keyFileNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m KeyFile | Returns: an empty `KeyFile`.

Creates a new empty `KeyFile` object.

Use `keyFileLoadFromFile`, `keyFileLoadFromData`, `keyFileLoadFromDirs` or `keyFileLoadFromDataDirs` to read an existing key file.

Since: 2.6

## removeComment

keyFileRemoveComment Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Maybe Text | `groupName`: a group name, or `NULL` to get a top-level comment
-> Maybe Text | `key`: a key, or `NULL` to get a group comment
-> m () | (Can throw `GError`)

Removes a comment above `key` from `groupName`.

If `key` is `NULL` then `comment` will be removed above `groupName`. If both `key` and `groupName` are `NULL`, then `comment` will be removed above the first group in the file.

Since: 2.6

## removeGroup

keyFileRemoveGroup Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> m () | (Can throw `GError`)

Removes the specified group, `groupName`, from the key file.

Since: 2.6

## removeKey

keyFileRemoveKey Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key name to remove
-> m () | (Can throw `GError`)

Removes `key` in `groupName` from the key file.

Since: 2.6

## saveToFile

keyFileSaveToFile Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `filename`: the name of the file to write to
-> m () | (Can throw `GError`)

Writes the contents of `keyFile` to `filename` using `fileSetContents`.

If you need stricter guarantees about durability of the written file than are provided by `fileSetContents`, use `fileSetContentsFull` with the return value of `keyFileToData`.

This function can fail for any of the reasons that `fileSetContents` may fail.

Since: 2.40

## setBoolean

keyFileSetBoolean Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Bool | `value`: true or false
-> m () |

Associates a new boolean value with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.6

## setBooleanList

keyFileSetBooleanList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> [Bool] | `list`: an array of boolean values
-> m () |

Associates a list of boolean values with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.6

## setComment

keyFileSetComment Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Maybe Text | `groupName`: a group name, or `NULL` to write a top-level comment
-> Maybe Text | `key`: a key, or `NULL` to write a group comment
-> Text | `comment`: a comment
-> m () | (Can throw `GError`)

Places a comment above `key` from `groupName`.

If `key` is `NULL` then `comment` will be written above `groupName`. If both `key` and `groupName` are `NULL`, then `comment` will be written above the first group in the file.

Passing a non-existent `groupName` or `key` to this function returns false and populates `error`. (In contrast, passing a non-existent `group_name` or `key` to `keyFileSetString` creates the associated group name and key.)

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

Since: 2.6

## setDouble

keyFileSetDouble Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Double | `value`: a double value
-> m () |

Associates a new double value with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.12

## setDoubleList

keyFileSetDoubleList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> [Double] | `list`: an array of double values
-> m () |

Associates a list of double values with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.12

## setInt64

keyFileSetInt64 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Int64 | `value`: an integer value
-> m () |

Associates a new integer value with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.26

## setInteger

keyFileSetInteger Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Int32 | `value`: an integer value
-> m () |

Associates a new integer value with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.6

## setIntegerList

keyFileSetIntegerList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> [Int32] | `list`: an array of integer values
-> m () |

Associates a list of integer values with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.6

## setListSeparator

keyFileSetListSeparator Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Int8 | `separator`: the separator
-> m () |

Sets the character which is used to separate values in lists.

Typically `;` or `,` are used as separators. The default list separator is `;`.

Since: 2.6

## setLocaleString

keyFileSetLocaleString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Text | `locale`: a locale identifier
-> Text | `string`: a string
-> m () |

Associates a string value for `key` and `locale` under `groupName`.

If the translation for `key` cannot be found then it is created.

If `locale` is `C` then the untranslated value is set (since GLib 2.84).

Since: 2.6

## setLocaleStringList

keyFileSetLocaleStringList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Text | `locale`: a locale identifier
-> [Text] | `list`: a `NULL`-terminated array of locale string values
-> CSize | `length`: the length of `list`
-> m () |

Associates a list of string values for `key` and `locale` under `groupName`.

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.

Since: 2.6

## setString

keyFileSetString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Text | `string`: a string
-> m () |

Associates a new string value with `key` under `groupName`.

If `key` cannot be found then it is created. If `groupName` cannot be found then it is created. Unlike `keyFileSetValue`, this function handles characters that need escaping, such as newlines.

Since: 2.6

## setStringList

keyFileSetStringList Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> [Text] | `list`: an array of string values
-> CSize | `length`: number of string values in `list`
-> m () |

Associates a list of string values for `key` under `groupName`.

If `key` cannot be found then it is created. If `groupName` cannot be found then it is created.

Since: 2.6

## setUint64

keyFileSetUint64 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Word64 | `value`: an integer value
-> m () |

Associates a new integer value with `key` under `groupName`.

If `key` cannot be found then it is created.

Since: 2.26

## setValue

keyFileSetValue Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> Text | `groupName`: a group name
-> Text | `key`: a key
-> Text | `value`: a string
-> m () |

Associates a new value with `key` under `groupName`.

If `key` cannot be found then it is created. If `groupName` 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 `keyFileSetString`.

Since: 2.6

## toData

keyFileToData Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> m (Text, CSize) | Returns: a newly allocated string holding the contents of the key file (Can throw `GError`)

Outputs `keyFile` as a string.

Note that this function never reports an error.

Since: 2.6

## unref

keyFileUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> KeyFile | `keyFile`: a key file
-> m () |

Decreases the reference count of `keyFile` by 1.

If the reference count reaches zero, frees the key file and all its allocated memory.

Since: 2.32