Resource Config File Support
3
LIBXFCE4UTIL Library

# Resource Config File Support

functions for reading and writing resource config files.

## Synopsis

    #include <libxfce4util/libxfce4util.h>

                        XfceRc;
    XfceRc*             xfce_rc_simple_open                 (const gchar *filename,
                                                             gboolean readonly);
    XfceRc*             xfce_rc_config_open                 (XfceResourceType type,
                                                             const gchar *resource,
                                                             gboolean readonly);
    void                xfce_rc_close                       (XfceRc *rc);
    void                xfce_rc_flush                       (XfceRc *rc);
    gboolean            xfce_rc_is_dirty                    (const XfceRc *rc);
    gboolean            xfce_rc_is_readonly                 (const XfceRc *rc);
    const gchar*        xfce_rc_get_locale                  (const XfceRc *rc);
    gchar**             xfce_rc_get_groups                  (const XfceRc *rc);
    gchar**             xfce_rc_get_entries                 (const XfceRc *rc,
                                                             const gchar *group);
    void                xfce_rc_delete_group                (XfceRc *rc,
                                                             const gchar *group,
                                                             gboolean global);
    const gchar*        xfce_rc_get_group                   (const XfceRc *rc);
    gboolean            xfce_rc_has_group                   (const XfceRc *rc,
                                                             const gchar *group);
    void                xfce_rc_set_group                   (XfceRc *rc,
                                                             const gchar *group);
    void                xfce_rc_delete_entry                (XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean global);
    gboolean            xfce_rc_has_entry                   (const XfceRc *rc,
                                                             const gchar *key);
    const gchar*        xfce_rc_read_entry                  (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *fallback);
    const gchar*        xfce_rc_read_entry_untranslated     (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *fallback);
    gboolean            xfce_rc_read_bool_entry             (const XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean fallback);
    gint                xfce_rc_read_int_entry              (const XfceRc *rc,
                                                             const gchar *key,
                                                             gint fallback);
    gchar**             xfce_rc_read_list_entry             (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *delimiter);
    void                xfce_rc_write_entry                 (XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *value);
    void                xfce_rc_write_bool_entry            (XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean value);
    void                xfce_rc_write_int_entry             (XfceRc *rc,
                                                             const gchar *key,
                                                             gint value);
    void                xfce_rc_write_list_entry            (XfceRc *rc,
                                                             const gchar *key,
                                                             gchar **value,
                                                             const gchar *separator);

## Description

Provides support for parsing INI-style resource config files like used by for example KDE and some Xfce components (like xfwm4, who uses rc files for the themes).

The parser itself is optimized for high-performance using memory and string chunks to reduce the time spent looking for heap memory (a nice side effect of this is the reduced heap corruption). But due to this fact, an XfceRc object might consume quite a lot of memory after some time of usage. Therefore you should close an XfceRc object as soon as possible after loading configuration data from the object.

## Details

### XfceRc

    typedef struct _XfceRc XfceRc;

Opaque struct that encapsulates the resource config data.

### xfce_rc_simple_open ()

    XfceRc*             xfce_rc_simple_open                 (const gchar *filename,
                                                             gboolean readonly);

Parses the resource config file specified by `filename`.

If `readonly` is `TRUE` parsing is generally faster, because only untranslated entries and entries that match the current locale will be loaded. Also if you pass `TRUE` for `readonly`, xfce_rc_simple_open will fail if `filename` does not reference a regular file.

It is no error if `readonly` is `FALSE` and the file referenced by `filename` does not exists. In this case you'll start with a fresh config, which contains only the default group and no entries.

`filename` :

  name of the filename to open.

`readonly` :

  whether to open `filename` readonly.

Returns :

  the newly created XfceRc object, or `NULL` on error.

Since 4.2

### xfce_rc_config_open ()

    XfceRc*             xfce_rc_config_open                 (XfceResourceType type,
                                                             const gchar *resource,
                                                             gboolean readonly);

`type` :

`resource` :

`readonly` :

Returns :

Since 4.2

### xfce_rc_close ()

    void                xfce_rc_close                       (XfceRc *rc);

Destructs `rc`.

If `rc` was opened read-write and contains dirty (modified) entries, these will be flushed to permanent storage first.

`rc` :

  an XfceRc object.

Since 4.2

### xfce_rc_flush ()

    void                xfce_rc_flush                       (XfceRc *rc);

Flushes all changes that currently reside only in memory back to permanent storage. Dirty configuration entries are written in the most specific file available.

`rc` :

  an XfceRc object.

Since 4.2

### xfce_rc_is_dirty ()

    gboolean            xfce_rc_is_dirty                    (const XfceRc *rc);

Checks whether `rc` has any dirty (modified) entries.

`rc` :

  an XfceRc object.

Returns :

  `TRUE` if `rc` has any dirty (modified) entries.

Since 4.2

### xfce_rc_is_readonly ()

    gboolean            xfce_rc_is_readonly                 (const XfceRc *rc);

Returns the read-only status of `rc`.

`rc` :

  an XfceRc object.

Returns :

  the read-only status.

Since 4.2

### xfce_rc_get_locale ()

    const gchar*        xfce_rc_get_locale                  (const XfceRc *rc);

Returns current locale used by `rc` to lookup translated entries.

`rc` :

  an XfceRc object.

Returns :

  a string representing the current locale.

Since 4.2

### xfce_rc_get_groups ()

    gchar**             xfce_rc_get_groups                  (const XfceRc *rc);

Returns the names of all known groups in `rc`.

Since the default groups (the "NULL group") name is `NULL`, it will not be returned with this functions. But it does not matter at all, since the default group is known to always exist.

`rc` :

  an XfceRc object.

Returns :

  a NULL-terminated string array will the names of all groups in `rc`. Should be freed using `g_strfreev()` when no longer needed.

Since 4.2

### xfce_rc_get_entries ()

    gchar**             xfce_rc_get_entries                 (const XfceRc *rc,
                                                             const gchar *group);

Returns the names of all entries in `group` if any.

`NULL` is a valid input value for `group`. xfce_rc_get_entries will then return all entries in the so called "NULL group". Though this "NULL group" should only be used for backward compatibility with old applications. You should not use it in newly written code.

`rc` :

  an XfceRc object.

`group` :

  the name of the group to get entries from.

Returns :

  a NULL-terminated string array with all entries in `group`. Has to be freed using `g_strfreev()` if no longer needed. If the specified `group` does not exists, `NULL` is returned. If the `group` has no entries, an empty string array is returned.

Since 4.2

### xfce_rc_delete_group ()

    void                xfce_rc_delete_group                (XfceRc *rc,
                                                             const gchar *group,
                                                             gboolean global);

If `rc` is a simple config object and `group` exists, it is deleted. All entries within `group` will be deleted. For simple config objects, `global` is ignored.

If `rc` is a complex config object and `group` exists, it will be deleted will all entries. If `global` is `TRUE`, the entry will be marked as deleted globally, therefore all calls to xfce_rc_read_entry and related functions will return the fallback values. If `global` is `FALSE`, the `group` will be deleted in the per-user config file, and further calls to xfce_rc_read_entry will most probably return the system-wide config entries.

`rc` :

  an XfceRc object.

`group` :

  name of the group to delete.

`global` :

  whether to delete the group globally.

Since 4.2

### xfce_rc_get_group ()

    const gchar*        xfce_rc_get_group                   (const XfceRc *rc);

Returns the name of the group in which we are searching for keys and from which we are retrieving entries. If the currently active group is the default group (the so called "NULL group"), `NULL` will be returned.

`rc` :

  an XfceRc object.

Returns :

  the name of the current group.

Since 4.2

### xfce_rc_has_group ()

    gboolean            xfce_rc_has_group                   (const XfceRc *rc,
                                                             const gchar *group);

Returns `TRUE` if the specified `group` is known about.

`rc` :

  an XfceRc object.

`group` :

  the group to search for.

Returns :

  `TRUE` if the `group` exists.

Since 4.2

### xfce_rc_set_group ()

    void                xfce_rc_set_group                   (XfceRc *rc,
                                                             const gchar *group);

Specifies the group in which keys will be read and written. Subsequent calls to xfce_rc_read_entry and xfce_rc_write_entry will be applied only in the active group.

If `group` references a group that does not exists, it will be created for you. But note, that empty groups will not be synced to permanent storage.

`rc` :

  an XfceRc object.

`group` :

  the name of the new group or `NULL` to to switch back to the default group.

Since 4.2

### xfce_rc_delete_entry ()

    void                xfce_rc_delete_entry                (XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean global);

Similar to xfce_rc_delete_group, but works on an entry in the current group.

`rc` :

  an XfceRc object.

`key` :

  the key to delete.

`global` :

  whether to delete `key` globally.

Since 4.2

### xfce_rc_has_entry ()

    gboolean            xfce_rc_has_entry                   (const XfceRc *rc,
                                                             const gchar *key);

Checks whether the `key` has an entry in the current group.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

Returns :

  `TRUE` if the `key` is available, else `FALSE`.

Since 4.2

### xfce_rc_read_entry ()

    const gchar*        xfce_rc_read_entry                  (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *fallback);

Reads the value of an entry specified by `key` in the current group.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

`fallback` :

  a default value returned if the `key` was not found.

Returns :

  the value for this `key`, or `fallback` if `key` was not found.

Since 4.2

### xfce_rc_read_entry_untranslated ()

    const gchar*        xfce_rc_read_entry_untranslated     (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *fallback);

Reads the value of an entry specified by `key` in the current group. The untranslated entry is returned. You normally do not need this.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

`fallback` :

  a default value returned if the `key` was not found.

Returns :

  the untranslated value for this `key`, or `fallback` if `key` was not found.

Since 4.2

### xfce_rc_read_bool_entry ()

    gboolean            xfce_rc_read_bool_entry             (const XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean fallback);

Reads the value of an entry specified by `key` in the current group and interpret it as a boolean value. Currently "on", "true" and "yes" are accepted as true, everything else is false.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

`fallback` :

  a default value returned if the `key` was not found.

Returns :

  the value for this `key`.

Since 4.2

### xfce_rc_read_int_entry ()

    gint                xfce_rc_read_int_entry              (const XfceRc *rc,
                                                             const gchar *key,
                                                             gint fallback);

Reads the value of an entry specified by `key` in the current group and interprets it as an integer value.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

`fallback` :

  a default value returned if the `key` was not found.

Returns :

  the value for this `key`.

Since 4.2

### xfce_rc_read_list_entry ()

    gchar**             xfce_rc_read_list_entry             (const XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *delimiter);

Reads a list of strings in the entry specified by key in the current group. The returned list has to be freed using `g_strfreev()` when no longer needed.

`rc` :

  an XfceRc object.

`key` :

  the key to search for.

`delimiter` :

  a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings. If NULL, "," is used.

Returns :

  the list or NULL if the entry does not exist.

Since 4.2

### xfce_rc_write_entry ()

    void                xfce_rc_write_entry                 (XfceRc *rc,
                                                             const gchar *key,
                                                             const gchar *value);

Writes a `key`/`value` pair. This has no effect if the resource config was opened readonly, else the value will be written to permanent storage on the next call to xfce_rc_flush or when `rc` is destroyed using xfce_rc_close.

If `rc` was opened using xfce_rc_config_open, the value will be written to the most specific config file.

`rc` :

  an XfceRc object.

`key` :

  the key to write.

`value` :

  the value to write.

Since 4.2

### xfce_rc_write_bool_entry ()

    void                xfce_rc_write_bool_entry            (XfceRc *rc,
                                                             const gchar *key,
                                                             gboolean value);

Wrapper for xfce_rc_write_entry, that stores a boolean `value`.

`rc` :

  an XfceRc object.

`key` :

  the key to write.

`value` :

  the value to write.

Since 4.2

### xfce_rc_write_int_entry ()

    void                xfce_rc_write_int_entry             (XfceRc *rc,
                                                             const gchar *key,
                                                             gint value);

Wrapper for xfce_rc_write_entry, that stores an integer `value`.

`rc` :

  an XfceRc object.

`key` :

  the key to write.

`value` :

  the value to write.

Since 4.2

### xfce_rc_write_list_entry ()

    void                xfce_rc_write_list_entry            (XfceRc *rc,
                                                             const gchar *key,
                                                             gchar **value,
                                                             const gchar *separator);

Wrapper for xfce_rc_write_entry, that stores a string list `value`.

`rc` :

  an XfceRc object.

`key` :

  the key to write.

`value` :

  a `NULL` terminated list of strings to store in the entry specified by key.

`separator` :

  the list separator. Defaults to "," if `NULL`.

Since 4.2