## IpatchXml IpatchXml — XML tree functions |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchXmlNode;
                        IpatchXmlAttr;
    GNode *             ipatch_xml_new_node                 (GNode *parent,
                                                             const char *name,
                                                             const char *value,
                                                             const char *attr_name,
                                                             ...);
    GNode *             ipatch_xml_new_node_strv            (GNode *parent,
                                                             const char *name,
                                                             const char *value,
                                                             const char **attr_names,
                                                             const char **attr_values);
    gpointer            ipatch_xml_get_data                 (GNode *node,
                                                             const char *key);
    void                ipatch_xml_set_data                 (GNode *node,
                                                             const char *key,
                                                             gpointer data);
    void                ipatch_xml_set_data_full            (GNode *node,
                                                             const char *key,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);
    gpointer            ipatch_xml_steal_data               (GNode *node,
                                                             const char *key);
    gpointer            ipatch_xml_get_qdata                (GNode *node,
                                                             GQuark quark);
    void                ipatch_xml_set_qdata                (GNode *node,
                                                             GQuark quark,
                                                             gpointer data);
    void                ipatch_xml_set_qdata_full           (GNode *node,
                                                             GQuark quark,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);
    gpointer            ipatch_xml_steal_qdata              (GNode *node,
                                                             GQuark quark);
    void                ipatch_xml_destroy                  (GNode *node);
    GNode *             ipatch_xml_copy                     (GNode *node);
    void                ipatch_xml_set_name                 (GNode *node,
                                                             const char *name);
    void                ipatch_xml_set_value                (GNode *node,
                                                             const char *value);
    void                ipatch_xml_set_value_printf         (GNode *node,
                                                             const char *format,
                                                             ...);
    void                ipatch_xml_take_name                (GNode *node,
                                                             char *name);
    void                ipatch_xml_take_value               (GNode *node,
                                                             char *value);
    const char *        ipatch_xml_get_name                 (GNode *node);
    gboolean            ipatch_xml_test_name                (GNode *node,
                                                             const char *cmpname);
    const char *        ipatch_xml_get_value                (GNode *node);
    char *              ipatch_xml_dup_value                (GNode *node);
    gboolean            ipatch_xml_test_value               (GNode *node,
                                                             const char *cmpvalue);
    void                ipatch_xml_set_attribute            (GNode *node,
                                                             const char *attr_name,
                                                             const char *attr_value);
    void                ipatch_xml_set_attributes           (GNode *node,
                                                             const char *attr_name,
                                                             const char *attr_value,
                                                             const char *attr2_name,
                                                             ...);
    const char *        ipatch_xml_get_attribute            (GNode *node,
                                                             const char *name);
    gboolean            ipatch_xml_test_attribute           (GNode *node,
                                                             const char *attr_name,
                                                             const char *cmpval);
    GNode *             ipatch_xml_find_child               (GNode *node,
                                                             const char *name);
    GNode *             ipatch_xml_find_by_path             (GNode *node,
                                                             const char *path);
    char *              ipatch_xml_to_str                   (GNode *node,
                                                             guint indent);
    gboolean            ipatch_xml_save_to_file             (GNode *node,
                                                             guint indent,
                                                             const char *filename,
                                                             GError **err);
    GNode *             ipatch_xml_from_str                 (const char *str,
                                                             GError **err);
    GNode *             ipatch_xml_load_from_file           (const char *filename,
                                                             GError **err);
    IpatchXmlNode *     ipatch_xml_node_new                 (void);
    void                ipatch_xml_node_free                (IpatchXmlNode *node);
    IpatchXmlNode *     ipatch_xml_node_duplicate           (const IpatchXmlNode *xmlnode);
    IpatchXmlAttr *     ipatch_xml_attr_new                 (void);
    void                ipatch_xml_attr_free                (IpatchXmlAttr *attr);
    IpatchXmlAttr *     ipatch_xml_attr_duplicate           (const IpatchXmlAttr *attr);

## Description

Functions for manipulating XML node trees and saving/loading to/from XML content in strings or files. XML node trees use the glib GNode N-ary tree data type for added flexibility.

## Details

### IpatchXmlNode

    typedef struct {
      char *name;		/* XML element name */
      char *value;		/* Text content of element */
      GData *qdata;		/* To associate arbitrary data with XML nodes */
      GList *attributes;	/* List of IpatchXmlAttr structures */
    } IpatchXmlNode;

An XML element node. Note that a given node can contain only one text value.

char *`name`; | XML element name
char *`value`; | XML text value or `NULL`
GData *`qdata`; |
GList *`attributes`; | Linked list of IpatchXmlAttr structures

### IpatchXmlAttr

    typedef struct {
      char *name;
      char *value;
    } IpatchXmlAttr;

Structure for storing an XML attribute.

char *`name`; | Attribute name
char *`value`; | Attribute value

### ipatch_xml_new_node ()

    GNode *             ipatch_xml_new_node                 (GNode *parent,
                                                             const char *name,
                                                             const char *value,
                                                             const char *attr_name,
                                                             ...);

Create a new XML tree node and append it to the given `parent`, if supplied. Note that the returned GNode can be used with other N-Array glib operations.

`parent` : | Parent node to add new node to as a child, or `NULL` to create new root node
`name` : | Name of the new XML node
`value` : | Text value to assign to the new node or `NULL`
`attr_name` : | First attribute name to assign or `NULL`
`...` : | If `attr_name` was supplied first string value to be assigned should be the first parameter, additional name/value attribute string pairs may follow terminated by a `NULL` name.
Returns : | New XML tree node

### ipatch_xml_new_node_strv ()

    GNode *             ipatch_xml_new_node_strv            (GNode *parent,
                                                             const char *name,
                                                             const char *value,
                                                             const char **attr_names,
                                                             const char **attr_values);

Like `ipatch_xml_new_node()` but takes attribute name/values as separate strv arrays.

`parent` : | Parent node to add new node to as a child, or `NULL` to create new root node
`name` : | Name of the new XML node
`value` : | Text value to assign to the new node or `NULL`
`attr_names` : | `NULL` terminated array of attribute names or `NULL`
`attr_values` : | `NULL` terminated array of attribute values or `NULL`
Returns : | New XML tree node

### ipatch_xml_get_data ()

    gpointer            ipatch_xml_get_data                 (GNode *node,
                                                             const char *key);

Lookup data assigned to an XML node using a quark. This is faster than `ipatch_xml_get_data()` since the key must be converted to a quark anyways.

`node` : | XML node
`quark` : | Quark key
Returns : | The data pointer or `NULL` if not set

### ipatch_xml_set_data ()

    void                ipatch_xml_set_data                 (GNode *node,
                                                             const char *key,
                                                             gpointer data);

Assigns arbitrary data to an XML node specified by a `key`.

`node` : | XML node
`key` : | Name of the key
`data` : | Data to associate with the key

### ipatch_xml_set_data_full ()

    void                ipatch_xml_set_data_full            (GNode *node,
                                                             const char *key,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);

Assigns arbitrary data to an XML node specified by a `key`. Also assigns a `destroy_func` callback to destroy the data when it is removed.

`node` : | XML node
`key` : | Name of the key
`data` : | Data to associate with the key

### ipatch_xml_steal_data ()

    gpointer            ipatch_xml_steal_data               (GNode *node,
                                                             const char *key);

Remove keyed data from an XML node, but don't call the data's destroy notify. Caller is thus given the ownership of the data.

`node` : | XML node
`key` : | Name of the key
Returns : | The data pointer or `NULL` if not set

### ipatch_xml_get_qdata ()

    gpointer            ipatch_xml_get_qdata                (GNode *node,
                                                             GQuark quark);

### ipatch_xml_set_qdata ()

    void                ipatch_xml_set_qdata                (GNode *node,
                                                             GQuark quark,
                                                             gpointer data);

Assigns arbitrary data to an XML node specified by a `quark` key. This is faster than `ipatch_xml_set_data()` since the key must be converted to a quark anyways.

`node` : | XML node
`quark` : | Quark key
`data` : | Data to associate with the key

### ipatch_xml_set_qdata_full ()

    void                ipatch_xml_set_qdata_full           (GNode *node,
                                                             GQuark quark,
                                                             gpointer data,
                                                             GDestroyNotify destroy_func);

Assigns arbitrary data to an XML node specified by a `key`. Also assigns a `destroy_func` callback to destroy the data when it is removed. This is faster than `ipatch_xml_set_data_full()` since the key must be converted to a quark anyways.

`node` : | XML node
`quark` : | Quark key
`data` : | Data to associate with the key

### ipatch_xml_steal_qdata ()

    gpointer            ipatch_xml_steal_qdata              (GNode *node,
                                                             GQuark quark);

Remove keyed data from an XML node, but don't call the data's destroy notify. Caller is thus given the ownership of the data. This is faster than `ipatch_xml_steal_data()` since the key must be converted to a quark anyways.

`node` : | XML node
`quark` : | Quark key
Returns : | The data pointer or `NULL` if not set

### ipatch_xml_destroy ()

    void                ipatch_xml_destroy                  (GNode *node);

Free an XML tree (a root `node` and all its children). Does not need to be the actual root of a tree, i.e., can remove a sub tree.

`node` : | Root of XML tree/sub tree to destroy

### ipatch_xml_copy ()

    GNode *             ipatch_xml_copy                     (GNode *node);

Perform a deep copy on an XML tree.

`node` : | XML tree to copy
Returns : | New duplicate XML tree.

### ipatch_xml_set_name ()

    void                ipatch_xml_set_name                 (GNode *node,
                                                             const char *name);

Set the name of an XML node.

`node` : | XML node
`name` : | Name to assign

### ipatch_xml_set_value ()

    void                ipatch_xml_set_value                (GNode *node,
                                                             const char *value);

Set the text value of an XML node.

`node` : | XML node
`value` : | Text value to assign or `NULL` to clear it

### ipatch_xml_set_value_printf ()

    void                ipatch_xml_set_value_printf         (GNode *node,
                                                             const char *format,
                                                             ...);

Assign a value to an XML node using a printf format and arguments.

`node` : | XML node
`format` : | Printf format
`...` : | Printf arguments

### ipatch_xml_take_name ()

    void                ipatch_xml_take_name                (GNode *node,
                                                             char *name);

Like `ipatch_xml_set_name()` but takes over the allocation of `name` rather than duplicating it.

`node` : | XML node
`name` : | Name to assign or `NULL` to clear it

### ipatch_xml_take_value ()

    void                ipatch_xml_take_value               (GNode *node,
                                                             char *value);

Like `ipatch_xml_set_value()` but takes over the allocation of `value` rather than duplicating it.

`node` : | XML node
`value` : | Text value to assign

### ipatch_xml_get_name ()

    const char *        ipatch_xml_get_name                 (GNode *node);

Get the name of an XML node.

`node` : | XML node to get name of
Returns : | Name of XML node which is internal and should not be modified or freed.

### ipatch_xml_test_name ()

    gboolean            ipatch_xml_test_name                (GNode *node,
                                                             const char *cmpname);

Test if the node has the given name.

`node` : | XML node to get name of
`cmpname` : | Name to compare to
Returns : | `TRUE` if the node has the given name, `FALSE` otherwise

### ipatch_xml_get_value ()

    const char *        ipatch_xml_get_value                (GNode *node);

Get the text value of an XML node.

`node` : | XML node to get value of
Returns : | Value of XML node or `NULL`, which is internal and should not be modified or freed.

### ipatch_xml_dup_value ()

    char *              ipatch_xml_dup_value                (GNode *node);

Duplicate the text value of an XML node. Like `ipatch_xml_get_value()` but makes a copy of the value which the caller owns.

`node` : | XML node to duplicate value of
Returns : | Newly allocated duplicate value of XML node or `NULL`.

### ipatch_xml_test_value ()

    gboolean            ipatch_xml_test_value               (GNode *node,
                                                             const char *cmpvalue);

Test if the node has the given value.

`node` : | XML node to get name of
`cmpvalue` : | Value to compare to
Returns : | `TRUE` if the node has the given value, `FALSE` otherwise

### ipatch_xml_set_attribute ()

    void                ipatch_xml_set_attribute            (GNode *node,
                                                             const char *attr_name,
                                                             const char *attr_value);

Set or unset an attribute of an XML node. If there is already an existing attribute with the given `attr_name`, its value will be replaced.

`node` : | XML node
`attr_name` : | Attribute name to assign to
`attr_value` : | Attribute value to assign or `NULL` to unset

### ipatch_xml_set_attributes ()

    void                ipatch_xml_set_attributes           (GNode *node,
                                                             const char *attr_name,
                                                             const char *attr_value,
                                                             const char *attr2_name,
                                                             ...);

Set one or more attributes of an XML node.

`node` : | XML node
`attr_name` : | First attribute name
`attr_value` : | First attribute value
`...` : | Additional name/value attribute strings, terminated by a `NULL` name

### ipatch_xml_get_attribute ()

    const char *        ipatch_xml_get_attribute            (GNode *node,
                                                             const char *name);

Get the value of an attribute of an XML node.

`node` : | XML node
`attr_name` : | Name of attribute
Returns : | Value of the named attribute or `NULL` if not found, value is internal and should not be modified or freed.

### ipatch_xml_test_attribute ()

    gboolean            ipatch_xml_test_attribute           (GNode *node,
                                                             const char *attr_name,
                                                             const char *cmpval);

Test if an attribute of an XML node is a given value or exists (`cmpval` = `NULL`).

`node` : | XML node
`attr_name` : | Name of attribute
`cmpval` : | Value to compare attribute to (`NULL` to just check existence).
Returns : | `TRUE` if attribute exists and matches `cmpval` (if set).

### ipatch_xml_find_child ()

    GNode *             ipatch_xml_find_child               (GNode *node,
                                                             const char *name);

Find a child node with the given `name`. Only searches the children of `node` and does not search recursively.

`node` : | XML node
`name` : | Node name of child to find
Returns : | Matching node or `NULL` if not found.

### ipatch_xml_find_by_path ()

    GNode *             ipatch_xml_find_by_path             (GNode *node,
                                                             const char *path);

Get a node in a tree from a path string.

`node` : | XML node
`path` : | Path specification in the form "name1.name2.name3" where each child of a node is separated by a '.' character.
Returns : | Matching node or `NULL` if not found.

### ipatch_xml_to_str ()

    char *              ipatch_xml_to_str                   (GNode *node,
                                                             guint indent);

Render an XML tree to a string.

`node` : | XML node
`indent` : | Number of spaces of indent per level (0 for no indent)
Returns : | Newly allocated string of XML content representing `node`, free with `g_free()` when done using it.

### ipatch_xml_save_to_file ()

    gboolean            ipatch_xml_save_to_file             (GNode *node,
                                                             guint indent,
                                                             const char *filename,
                                                             GError **err);

Store an XML tree to a file.

`node` : | XML tree to save
`indent` : | Number of spaces to indent per level
`filename` : | File name to save to
`err` : | Location to store error info or `NULL` to ignore
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set)

### ipatch_xml_from_str ()

    GNode *             ipatch_xml_from_str                 (const char *str,
                                                             GError **err);

Parse XML content into an XML node tree.

`str` : | XML content to parse
`err` : | Location to store error info or `NULL` to ignore
Returns : | Newly allocated XML node tree or `NULL` on error (`err` may be set), can be freed with `ipatch_xml_destroy()`.

### ipatch_xml_load_from_file ()

    GNode *             ipatch_xml_load_from_file           (const char *filename,
                                                             GError **err);

Parse an XML file into an XML node tree.

`filename` : | File name containing XML content to parse
`err` : | Location to store error info or `NULL` to ignore
Returns : | Newly allocated XML node tree or `NULL` on error (`err` may be set), can be freed with `ipatch_xml_destroy()`.

### ipatch_xml_node_new ()

    IpatchXmlNode *     ipatch_xml_node_new                 (void);

Create a new XML node structure. Not normally used.

Returns : | New XML node structure, which should be added to a GNode.

### ipatch_xml_node_free ()

    void                ipatch_xml_node_free                (IpatchXmlNode *node);

Free an XML node structure and its contents. Not normally used.

`xmlnode` : | XML node structure to free

### ipatch_xml_node_duplicate ()

    IpatchXmlNode *     ipatch_xml_node_duplicate           (const IpatchXmlNode *xmlnode);

Duplicate an XML node structure and its contents. Not normally used. Note that arbitrary user data assigned to the XML node will not be duplicated.

`xmlnode` : | XML node structure to duplicate
Returns : | New duplicate of `xmlnode`.

### ipatch_xml_attr_new ()

    IpatchXmlAttr *     ipatch_xml_attr_new                 (void);

Create a new XML attribute structure. Not normally used.

Returns : | New XML attribute structure which should be added to an IpatchXmlNode attributes list.

### ipatch_xml_attr_free ()

    void                ipatch_xml_attr_free                (IpatchXmlAttr *attr);

Free an XML attribute structure. Not normally used.

`attr` : | Attribute structure to free

### ipatch_xml_attr_duplicate ()

    IpatchXmlAttr *     ipatch_xml_attr_duplicate           (const IpatchXmlAttr *attr);

Duplicate an XML attribute structure. Not normally used.

`attr` : | Attribute structure to duplicate
Returns : | New duplicate attribute structure

## See Also

IpatchXmlObject