XML Helper Functions

## XML Helper Functions XML Helper Functions — Functions to help format and parse glabels XML properties |

## Synopsis

    #include <libglabels/lgl-xml.h>

    #define             LGL_XML_NAME_SPACE

    gchar *             lgl_xml_get_prop_string             (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *default_val);
    gchar *             lgl_xml_get_prop_i18n_string        (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *default_val);
    gdouble             lgl_xml_get_prop_double             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble default_val);
    gboolean            lgl_xml_get_prop_boolean            (xmlNodePtr node,
                                                             const gchar *property,
                                                             gboolean default_val);
    gint                lgl_xml_get_prop_int                (xmlNodePtr node,
                                                             const gchar *property,
                                                             gint default_val);
    guint               lgl_xml_get_prop_uint               (xmlNodePtr node,
                                                             const gchar *property,
                                                             guint default_val);
    gdouble             lgl_xml_get_prop_length             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble default_val);

    void                lgl_xml_set_prop_string             (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *val);
    void                lgl_xml_set_prop_double             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble val);
    void                lgl_xml_set_prop_boolean            (xmlNodePtr node,
                                                             const gchar *property,
                                                             gboolean val);
    void                lgl_xml_set_prop_int                (xmlNodePtr node,
                                                             const gchar *property,
                                                             gint val);
    void                lgl_xml_set_prop_uint_hex           (xmlNodePtr node,
                                                             const gchar *property,
                                                             guint val);
    void                lgl_xml_set_prop_length             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble val);

    gboolean            lgl_xml_is_node                     (xmlNodePtr node,
                                                             const gchar *name);
    gchar *             lgl_xml_get_node_content            (xmlNodePtr node);

    void                lgl_xml_set_default_units           (lglUnits units);

## Description

This section describes a number of "helper" functions for formatting and parsing various types of properties for tags in glabels XML file formats.

These functions are basically wrappers to functions from libxml2.

## Details

### LGL_XML_NAME_SPACE

    #define LGL_XML_NAME_SPACE "http://glabels.org/xmlns/3.0/"

### lgl_xml_get_prop_string ()

    gchar *             lgl_xml_get_prop_string             (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *default_val);

Return value of property as a string.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as a pointer to a gchar string. This string should be freed with `g_free()`.

### lgl_xml_get_prop_i18n_string ()

    gchar *             lgl_xml_get_prop_i18n_string        (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *default_val);

Return value of a translatable property as a string.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as a pointer to a gchar string. This string should be freed with `g_free()`.

### lgl_xml_get_prop_double ()

    gdouble             lgl_xml_get_prop_double             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble default_val);

Return value of property as a double.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as a double.

### lgl_xml_get_prop_boolean ()

    gboolean            lgl_xml_get_prop_boolean            (xmlNodePtr node,
                                                             const gchar *property,
                                                             gboolean default_val);

Return value of property as a boolean.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as a boolean.

### lgl_xml_get_prop_int ()

    gint                lgl_xml_get_prop_int                (xmlNodePtr node,
                                                             const gchar *property,
                                                             gint default_val);

Return value of property as an integer.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as an integer.

### lgl_xml_get_prop_uint ()

    guint               lgl_xml_get_prop_uint               (xmlNodePtr node,
                                                             const gchar *property,
                                                             guint default_val);

Return value of property (usually formatted in hex) as an unsigned integer.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the property as an unsigned integer.

### lgl_xml_get_prop_length ()

    gdouble             lgl_xml_get_prop_length             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble default_val);

Return value of a length property as a double, converting to internal units (points). The property is expected to be formatted as a number followed by a units string. If there is no units string, the length is assumed to be in points. Valid units strings are "pt" for points, "in" for inches, "mm" for millimeters, "cm" for centimeters, and "pc" for picas.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`default_val` : | a default value to return if property not found
Returns : | the length in points.

### lgl_xml_set_prop_string ()

    void                lgl_xml_set_prop_string             (xmlNodePtr node,
                                                             const gchar *property,
                                                             const gchar *val);

Set a property from a string.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the value to set

### lgl_xml_set_prop_double ()

    void                lgl_xml_set_prop_double             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble val);

Set a property from a double.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the value to set

### lgl_xml_set_prop_boolean ()

    void                lgl_xml_set_prop_boolean            (xmlNodePtr node,
                                                             const gchar *property,
                                                             gboolean val);

Set a property from a boolean.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the value to set

### lgl_xml_set_prop_int ()

    void                lgl_xml_set_prop_int                (xmlNodePtr node,
                                                             const gchar *property,
                                                             gint val);

Set a property from an integer.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the value to set

### lgl_xml_set_prop_uint_hex ()

    void                lgl_xml_set_prop_uint_hex           (xmlNodePtr node,
                                                             const gchar *property,
                                                             guint val);

Set a property from an unsigned integer and format in hex.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the value to set

### lgl_xml_set_prop_length ()

    void                lgl_xml_set_prop_length             (xmlNodePtr node,
                                                             const gchar *property,
                                                             gdouble val);

Set a property from a length, performing any necessary conversion. Length properties are formatted as a number followed by a units string. The units of the formatted property is determined by the most recent call to `lgl_xml_set_default_units()`.

`node` : | the libxml2 xmlNodePtr of the node
`property` : | the property name
`val` : | the length to set in internal units (points)

### lgl_xml_is_node ()

    gboolean            lgl_xml_is_node                     (xmlNodePtr node,
                                                             const gchar *name);

Test if a node name matches given name.

`node` : | the libxml2 xmlNodePtr of the node
`name` : | the node name
Returns : | TRUE if the name of the node matches. Otherwise FALSE.

### lgl_xml_get_node_content ()

    gchar *             lgl_xml_get_node_content            (xmlNodePtr node);

Get the content of a node.

`node` : | the libxml2 xmlNodePtr of the node
Returns : | the property as a pointer to a gchar string. This string should be freed with `g_free()`.

### lgl_xml_set_default_units ()

    void                lgl_xml_set_default_units           (lglUnits units);

Set the default units when formatting lengths. See `lgl_xml_set_prop_length()`.

`units` : | default units selection (lglUnits)