gimpconfigwriter

## gimpconfigwriter gimpconfigwriter — Functions for writing config info to a file for libgimpconfig. |

## Synopsis

                        GimpConfigWriter;
    GimpConfigWriter *  gimp_config_writer_new_file         (const gchar *filename,
                                                             gboolean atomic,
                                                             const gchar *header,
                                                             GError **error);
    GimpConfigWriter *  gimp_config_writer_new_fd           (gint fd);
    GimpConfigWriter *  gimp_config_writer_new_string       (GString *string);
    void                gimp_config_writer_open             (GimpConfigWriter *writer,
                                                             const gchar *name);
    void                gimp_config_writer_comment_mode     (GimpConfigWriter *writer,
                                                             gboolean enable);
    void                gimp_config_writer_print            (GimpConfigWriter *writer,
                                                             const gchar *string,
                                                             gint len);
    void                gimp_config_writer_printf           (GimpConfigWriter *writer,
                                                             const gchar *format,
                                                             ...);
    void                gimp_config_writer_identifier       (GimpConfigWriter *writer,
                                                             const gchar *identifier);
    void                gimp_config_writer_string           (GimpConfigWriter *writer,
                                                             const gchar *string);
    void                gimp_config_writer_data             (GimpConfigWriter *writer,
                                                             gint length,
                                                             const guint8 *data);
    void                gimp_config_writer_comment          (GimpConfigWriter *writer,
                                                             const gchar *comment);
    void                gimp_config_writer_linefeed         (GimpConfigWriter *writer);
    void                gimp_config_writer_revert           (GimpConfigWriter *writer);
    void                gimp_config_writer_close            (GimpConfigWriter *writer);
    gboolean            gimp_config_writer_finish           (GimpConfigWriter *writer,
                                                             const gchar *footer,
                                                             GError **error);

## Description

Functions for writing config info to a file for libgimpconfig.

## Details

### GimpConfigWriter

    typedef struct _GimpConfigWriter GimpConfigWriter;

### gimp_config_writer_new_file ()

    GimpConfigWriter *  gimp_config_writer_new_file         (const gchar *filename,
                                                             gboolean atomic,
                                                             const gchar *header,
                                                             GError **error);

Creates a new GimpConfigWriter and sets it up to write to `filename`. If `atomic` is `TRUE`, a temporary file is used to avoid possible race conditions. The temporary file is then moved to `filename` when the writer is closed.

`filename` : | a filename
`atomic` : | if `TRUE` the file is written atomically
`header` : | text to include as comment at the top of the file
`error` : | return location for errors
Returns : | a new GimpConfigWriter or `NULL` in case of an error

Since GIMP 2.4

### gimp_config_writer_new_fd ()

    GimpConfigWriter *  gimp_config_writer_new_fd           (gint fd);

Returns : | a new GimpConfigWriter or `NULL` in case of an error

Since GIMP 2.4

### gimp_config_writer_new_string ()

    GimpConfigWriter *  gimp_config_writer_new_string       (GString *string);

Returns : | a new GimpConfigWriter or `NULL` in case of an error

Since GIMP 2.4

### gimp_config_writer_open ()

    void                gimp_config_writer_open             (GimpConfigWriter *writer,
                                                             const gchar *name);

This function writes the opening parenthese followed by `name`. It also increases the indentation level and sets a mark that can be used by `gimp_config_writer_revert()`.

`writer` : | a GimpConfigWriter
`name` : | name of the element to open

Since GIMP 2.4

### gimp_config_writer_comment_mode ()

    void                gimp_config_writer_comment_mode     (GimpConfigWriter *writer,
                                                             gboolean enable);

This function toggles whether the `writer` should create commented or uncommented output. This feature is used to generate the system-wide installed gimprc that documents the default settings.

Since comments have to start at the beginning of a line, this funtion will insert a newline if necessary.

`writer` : | a GimpConfigWriter
`enable` : | `TRUE` to enable comment mode, `FALSE` to disable it

Since GIMP 2.4

### gimp_config_writer_print ()

    void                gimp_config_writer_print            (GimpConfigWriter *writer,
                                                             const gchar *string,
                                                             gint len);

Appends a space followed by `string` to the `writer`. Note that string must not contain any special characters that might need to be escaped.

`writer` : | a GimpConfigWriter
`string` : | a string to write
`len` : | number of bytes from `string` or -1 if `string` is NUL-terminated.

Since GIMP 2.4

### gimp_config_writer_printf ()

    void                gimp_config_writer_printf           (GimpConfigWriter *writer,
                                                             const gchar *format,
                                                             ...);

A printf-like function for GimpConfigWriter.

`writer` : | a GimpConfigWriter
`format` : | a format string as described for `g_strdup_printf()`.
`...` : | list of arguments according to `format`

Since GIMP 2.4

### gimp_config_writer_identifier ()

    void                gimp_config_writer_identifier       (GimpConfigWriter *writer,
                                                             const gchar *identifier);

Writes an identifier to `writer`. The `string` is *not* quoted and special characters are *not* escaped.

`writer` : | a GimpConfigWriter
`identifier` : | a NUL-terminated string

Since GIMP 2.4

### gimp_config_writer_string ()

    void                gimp_config_writer_string           (GimpConfigWriter *writer,
                                                             const gchar *string);

Writes a string value to `writer`. The `string` is quoted and special characters are escaped.

`writer` : | a GimpConfigWriter
`string` : | a NUL-terminated string

Since GIMP 2.4

### gimp_config_writer_data ()

    void                gimp_config_writer_data             (GimpConfigWriter *writer,
                                                             gint length,
                                                             const guint8 *data);

`writer` : | a GimpConfigWriter

Since GIMP 2.4

### gimp_config_writer_comment ()

    void                gimp_config_writer_comment          (GimpConfigWriter *writer,
                                                             const gchar *comment);

Appends the `comment` to `str` and inserts linebreaks and hash-marks to format it as a comment. Note that this function does not handle non-ASCII characters.

`writer` : | a GimpConfigWriter
`comment` : | the comment to write (ASCII only)

Since GIMP 2.4

### gimp_config_writer_linefeed ()

    void                gimp_config_writer_linefeed         (GimpConfigWriter *writer);

`writer` : |

### gimp_config_writer_revert ()

    void                gimp_config_writer_revert           (GimpConfigWriter *writer);

Reverts all changes to `writer` that were done since the last call to `gimp_config_writer_open()`. This can only work if you didn't call `gimp_config_writer_close()` yet.

`writer` : | a GimpConfigWriter

Since GIMP 2.4

### gimp_config_writer_close ()

    void                gimp_config_writer_close            (GimpConfigWriter *writer);

Closes an element opened with `gimp_config_writer_open()`.

`writer` : | a GimpConfigWriter

Since GIMP 2.4

### gimp_config_writer_finish ()

    gboolean            gimp_config_writer_finish           (GimpConfigWriter *writer,
                                                             const gchar *footer,
                                                             GError **error);

This function finishes the work of `writer` and frees it afterwards. It closes all open elements, appends an optional comment and releases all resources allocated by `writer`. You must not access the `writer` afterwards.

`writer` : | a GimpConfigWriter
`footer` : | text to include as comment at the bottom of the file
`error` : | return location for possible errors
Returns : | `TRUE` if everything could be successfully written, `FALSE` otherwise

Since GIMP 2.4