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, onlytrue
andfalse
(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
Memory-managed wrapper type.
Constructors
KeyFile (ManagedPtr KeyFile) |
Instances
Eq KeyFile Source # | |
GBoxed KeyFile Source # | |
Defined in GI.GLib.Structs.KeyFile | |
ManagedPtrNewtype KeyFile Source # | |
Defined in GI.GLib.Structs.KeyFile Methods toManagedPtr :: KeyFile -> ManagedPtr KeyFile # | |
TypedObject KeyFile Source # | |
Defined in GI.GLib.Structs.KeyFile | |
HasParentTypes KeyFile Source # | |
Defined in GI.GLib.Structs.KeyFile | |
IsGValue (Maybe KeyFile) Source # | Convert |
Defined in GI.GLib.Structs.KeyFile Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe KeyFile -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe KeyFile) # | |
type ParentTypes KeyFile Source # | |
Defined in GI.GLib.Structs.KeyFile type ParentTypes KeyFile = '[] :: [Type] |
Methods
Click to display all available methods, including inherited ones
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m () | (Can throw |
Returns the value associated with key
under groupName
as a
boolean.
If key
cannot be found then [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. Likewise, if the value associated with key
cannot be interpreted
as a boolean then [errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.6
getBooleanList
keyFileGetBooleanList Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m [Bool] | Returns:
the values associated with the key as a list of booleans, or |
Returns the values associated with key
under groupName
as
booleans.
If key
cannot be found then [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. Likewise, if the values associated with key
cannot be interpreted
as booleans then [errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.6
getComment
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Maybe Text |
|
-> Maybe Text |
|
-> m Text | Returns: a comment that should be freed with |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Double | Returns: the value associated with the key as a double, or
|
Returns the value associated with key
under groupName
as a double.
If key
cannot be found then [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. Likewise, if the value associated with key
cannot be interpreted
as a double then [errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.12
getDoubleList
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m [Double] | Returns:
the values associated with the key as a list of doubles, or |
Returns the values associated with key
under groupName
as
doubles.
If key
cannot be found then [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. Likewise, if the values associated with key
cannot be interpreted
as doubles then [errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.12
getGroups
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> m ([Text], CSize) | Returns: a newly-allocated
|
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Int64 | Returns: the value associated with the key as a signed 64-bit integer, or
|
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Int32 | Returns: the value associated with the key as an integer, or
|
Returns the value associated with key
under groupName
as an
integer.
If key
cannot be found then [errorgLib
.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
[errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.6
getIntegerList
keyFileGetIntegerList Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m [Int32] | Returns:
the values associated with the key as a list of integers, or |
Returns the values associated with key
under groupName
as
integers.
If key
cannot be found then [errorgLib
.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
[errorgLib
.KeyFileError.INVALID_VALUE] is returned.
Since: 2.6
getKeys
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> m ([Text], CSize) | Returns: a newly-allocated
|
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,
[errorgLib
.KeyFileError.GROUP_NOT_FOUND] is returned.
Since: 2.6
getLocaleForKey
keyFileGetLocaleForKey Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Maybe Text |
|
-> m (Maybe Text) | Returns: the locale from the file, or |
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 |
|
-> Text |
|
-> Text |
|
-> Maybe Text |
|
-> m Text | Returns: a newly allocated string or |
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
[flagsgLib
.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all
locales.
If key
cannot be found then [errorgLib
.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 |
|
-> Text |
|
-> Text |
|
-> Maybe Text |
|
-> m ([Text], CSize) | Returns:
a newly allocated |
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
[flagsgLib
.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all
locales.
If key
cannot be found then [errorgLib
.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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Text | Returns: a newly allocated string or |
Returns the string value associated with key
under groupName
.
Unlike keyFileGetValue
, this function handles escape
sequences like \s
.
If the key cannot be found, [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. If the groupName
cannot be found,
[errorgLib
.KeyFileError.GROUP_NOT_FOUND] is returned.
Since: 2.6
getStringList
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m ([Text], CSize) | Returns:
a |
Returns the values associated with key
under groupName
.
If the key cannot be found, [errorgLib
.KeyFileError.KEY_NOT_FOUND] is
returned. If the groupName
cannot be found,
[errorgLib
.KeyFileError.GROUP_NOT_FOUND] is returned.
Since: 2.6
getUint64
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Word64 | Returns: the value associated with the key as an unsigned 64-bit integer,
or |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m Text | Returns: a newly allocated string or |
Returns the raw value associated with key
under groupName
.
Use keyFileGetString
to retrieve an unescaped UTF-8 string.
If the key cannot be found, [errorgLib
.KeyFileError.KEY_NOT_FOUND]
is returned. If the groupName
cannot be found,
[errorgLib
.KeyFileError.GROUP_NOT_FOUND] is returned.
Since: 2.6
hasGroup
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> m Bool | Returns: true if |
Looks whether the key file has the group groupName
.
Since: 2.6
loadFromBytes
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Bytes |
|
-> [KeyFileFlags] |
|
-> m () | (Can throw |
Loads a key file from the data in bytes
into an empty KeyFile
structure.
If the object cannot be created then a [errorgLib
.KeyFileError] is returned.
Since: 2.50
loadFromData
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> CSize |
|
-> [KeyFileFlags] |
|
-> m () | (Can throw |
Loads a key file from memory into an empty KeyFile
structure.
If the object cannot be created then a [errorgLib
.KeyFileError is returned.
Since: 2.6
loadFromDataDirs
keyFileLoadFromDataDirs Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> [Char] |
|
-> [KeyFileFlags] |
|
-> m [Char] | (Can throw |
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 [errorgLib
.FileError] or
[errorgLib
.KeyFileError] is returned.
Since: 2.6
loadFromDirs
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> [Char] |
|
-> [[Char]] |
|
-> [KeyFileFlags] |
|
-> m [Char] | (Can throw |
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
,
[errorgLib
.KeyFileError.NOT_FOUND] is returned. If
the file is found but the OS returns an error when opening or reading the
file, a [errorgLib
.FileError] is returned. If there is a problem parsing the
file, a [errorgLib
.KeyFileError] is returned.
Since: 2.14
loadFromFile
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> [Char] |
|
-> [KeyFileFlags] |
|
-> m () | (Can throw |
Loads a key file into an empty KeyFile
structure.
If the OS returns an error when opening or reading the file, a
[errorgLib
.FileError] is returned. If there is a problem parsing the file,
a [errorgLib
.KeyFileError] is returned.
This function will never return a [errorgLib
.KeyFileError.NOT_FOUND]
error. If the file
is not found, [errorgLib
.FileError.NOENT] is returned.
Since: 2.6
new
Creates a new empty KeyFile
object.
Use keyFileLoadFromFile
,
keyFileLoadFromData
, keyFileLoadFromDirs
or
keyFileLoadFromDataDirs
to
read an existing key file.
Since: 2.6
removeComment
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Maybe Text |
|
-> Maybe Text |
|
-> m () | (Can throw |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> m () | (Can throw |
Removes the specified group, groupName
,
from the key file.
Since: 2.6
removeKey
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> m () | (Can throw |
Removes key
in groupName
from the key file.
Since: 2.6
saveToFile
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> m () | (Can throw |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Bool |
|
-> 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 |
|
-> Text |
|
-> Text |
|
-> [Bool] |
|
-> m () |
Associates a list of boolean values with key
under groupName
.
If key
cannot be found then it is created.
Since: 2.6
setComment
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Maybe Text |
|
-> Maybe Text |
|
-> Text |
|
-> m () | (Can throw |
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.
Note that this function prepends a #
comment marker to
each line of comment
.
Since: 2.6
setDouble
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Double |
|
-> m () |
Associates a new double value with key
under groupName
.
If key
cannot be found then it is created.
Since: 2.12
setDoubleList
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> [Double] |
|
-> m () |
Associates a list of double values with key
under groupName
.
If key
cannot be found then it is created.
Since: 2.12
setInt64
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Int64 |
|
-> m () |
Associates a new integer value with key
under groupName
.
If key
cannot be found then it is created.
Since: 2.26
setInteger
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Int32 |
|
-> 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 |
|
-> Text |
|
-> Text |
|
-> [Int32] |
|
-> 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 |
|
-> Int8 |
|
-> 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 |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> 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 |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> [Text] |
|
-> CSize |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> [Text] |
|
-> CSize |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Word64 |
|
-> m () |
Associates a new integer value with key
under groupName
.
If key
cannot be found then it is created.
Since: 2.26
setValue
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> Text |
|
-> Text |
|
-> Text |
|
-> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> m (Text, CSize) | Returns: a newly allocated string holding the contents of the key file (Can throw |
Outputs keyFile
as a string.
Note that this function never reports an error.
Since: 2.6
unref
Arguments
:: (HasCallStack, MonadIO m) | |
=> KeyFile |
|
-> 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