as-node: AppStream-glib Reference Manual

## as-node as-node — A simple DOM parser |

## Stability Level

Stable, unless otherwise indicated

## Functions

GNode * | as_node_new ()
GQuark | as_node_error_quark ()
void | as_node_unref ()
const gchar * | as_node_get_name ()
const gchar * | as_node_get_data ()
const gchar * | as_node_get_comment ()
AsTag | as_node_get_tag ()
const gchar * | as_node_get_attribute ()
gint | as_node_get_attribute_as_int ()
guint | as_node_get_attribute_as_uint ()
GHashTable * | as_node_get_localized ()
const gchar * | as_node_get_localized_best ()
GHashTable * | as_node_get_localized_unwrap ()
void | as_node_set_name ()
void | as_node_set_data ()
void | as_node_set_comment ()
void | as_node_add_attribute ()
void | as_node_add_attribute_as_int ()
void | as_node_add_attribute_as_uint ()
void | as_node_remove_attribute ()
GString * | as_node_to_xml ()
GNode * | as_node_from_xml ()
GNode * | as_node_from_bytes ()
GNode * | as_node_from_file ()
gboolean | as_node_to_file ()
GNode * | as_node_find ()
GNode * | as_node_find_with_attribute ()
GNode * | as_node_insert ()
void | as_node_insert_localized ()
void | as_node_insert_hash ()

## Types and Values

enum | AsNodeToXmlFlags
enum | AsNodeFromXmlFlags
enum | AsNodeInsertFlags
enum | AsNodeError
#define | AS_NODE_ERROR
typedef | AsNode

## Includes

    #include <appstream-glib.h>

## Description

These helper functions allow parsing to and from AsApp's and the AppStream XML representation. This parser is UTF-8 safe, but not very fast, and parsers like expat should be used if full XML specification adherence is required.

See also: AsApp

## Functions

### as_node_new ()

    GNode *
    as_node_new (void);

Creates a new empty tree whicah can have nodes appended to it.

[skip]

#### Returns

a new empty tree.

[transfer full]

Since: 0.1.0

### as_node_error_quark ()

    GQuark
    as_node_error_quark (void);

#### Returns

An error quark.

Since: 0.1.0

### as_node_unref ()

    void
    as_node_unref (GNode *node);

Deallocates all notes in the tree.

#### Parameters

node | a AsNode. |

Since: 0.1.0

### as_node_get_name ()

    const gchar *
    as_node_get_name (const GNode *node);

Gets the node name, e.g. "body"

#### Parameters

node | a AsNode |

#### Returns

string value

Since: 0.1.0

### as_node_get_data ()

    const gchar *
    as_node_get_data (const GNode *node);

Gets the node data, e.g. "paragraph text"

#### Parameters

node | a AsNode |

#### Returns

string value

Since: 0.1.0

### as_node_get_comment ()

    const gchar *
    as_node_get_comment (const GNode *node);

Gets the node data, e.g. "Copyright 2014 Richard Hughes"

#### Parameters

node | a AsNode |

#### Returns

string value, or `NULL`

Since: 0.1.6

### as_node_get_tag ()

    AsTag
    as_node_get_tag (const GNode *node);

Gets the node tag enum.

#### Parameters

node | a AsNode |

#### Returns

AsTag, e.g. `AS_TAG_PKGNAME`

Since: 0.1.2

### as_node_get_attribute ()

    const gchar *
    as_node_get_attribute (const GNode *node,
                           const gchar *key);

Gets a node attribute, e.g. "false"

#### Parameters

node | a AsNode |
key | the attribute key |

#### Returns

string value

Since: 0.1.0

### as_node_get_attribute_as_int ()

    gint
    as_node_get_attribute_as_int (const GNode *node,
                                  const gchar *key);

Gets a node attribute, e.g. 34

#### Parameters

node | a AsNode |
key | the attribute key |

#### Returns

integer value, or `G_MAXINT` for error

Since: 0.1.0

### as_node_get_attribute_as_uint ()

    guint
    as_node_get_attribute_as_uint (const GNode *node,
                                   const gchar *key);

Gets a node attribute, e.g. 34

#### Parameters

node | a AsNode |
key | the attribute key |

#### Returns

integer value, or `G_MAXINT` for error

Since: 0.6.1

### as_node_get_localized ()

    GHashTable *
    as_node_get_localized (const GNode *node,
                           const gchar *key);

Extracts localized values from the DOM tree

#### Parameters

node | a AsNode |
key | the key to use, e.g. "copyright" |

#### Returns

A hash table with the locale (e.g. en_GB) as the key.

[transfer full]

Since: 0.1.0

### as_node_get_localized_best ()

    const gchar *
    as_node_get_localized_best (const GNode *node,
                                const gchar *key);

Gets the 'best' locale version of a specific data value.

#### Parameters

node | a AsNode. |
key | the tag name. |

#### Returns

the string value, or `NULL` if there was no data

Since: 0.1.0

### as_node_get_localized_unwrap ()

    GHashTable *
    as_node_get_localized_unwrap (const GNode *node,
                                  GError **error);

Denormalize AppData data like this:

    1
    2
    3
    4
    5
    6
    7
    8
    <description>
     <p>Hi</p>
     <p xml:lang="pl">Czesc</p>
     <ul>
      <li>First</li>
      <li xml:lang="pl">Pierwszy</li>
     </ul>
    </description>

into a hash that contains:

    1
    2
    "C"  ->  "<p>Hi</p><ul><li>First</li></ul>"
    "pl" ->  "<p>Czesc</p><ul><li>Pierwszy</li></ul>"

#### Parameters

node | a AsNode. |
error | A GError or `NULL`. |

#### Returns

a hash table of data.

[transfer full]

Since: 0.1.0

### as_node_set_name ()

    void
    as_node_set_name (GNode *node,
                      const gchar *name);

Sets the node name, e.g. "body"

[skip]

#### Parameters

node | a AsNode |
name | the new name |

Since: 0.1.4

### as_node_set_data ()

    void
    as_node_set_data (GNode *node,
                      const gchar *cdata,
                      AsNodeInsertFlags insert_flags);

Sets new data on a node.

[skip]

#### Parameters

node | a AsNode |
cdata | new data |
insert_flags | any `AsNodeInsertFlags`. |

Since: 0.1.1

### as_node_set_comment ()

    void
    as_node_set_comment (GNode *node,
                         const gchar *comment);

Sets new comment for the node.

[skip]

#### Parameters

node | a AsNode |
comment | new comment |

Since: 0.1.6

### as_node_add_attribute ()

    void
    as_node_add_attribute (GNode *node,
                           const gchar *key,
                           const gchar *value);

Adds a new attribute to a node.

[skip]

#### Parameters

node | a AsNode |
key | the attribute key |
value | new data |

Since: 0.1.1

### as_node_add_attribute_as_int ()

    void
    as_node_add_attribute_as_int (GNode *node,
                                  const gchar *key,
                                  gint value);

Adds a new attribute to a node.

[skip]

#### Parameters

node | a AsNode |
key | the attribute key |
value | new data |

Since: 0.3.1

### as_node_add_attribute_as_uint ()

    void
    as_node_add_attribute_as_uint (GNode *node,
                                   const gchar *key,
                                   guint value);

Adds a new attribute to a node.

[skip]

#### Parameters

node | a AsNode |
key | the attribute key |
value | new data |

Since: 0.6.1

### as_node_remove_attribute ()

    void
    as_node_remove_attribute (GNode *node,
                              const gchar *key);

Removes a node attribute, e.g. "type"

[skip]

#### Parameters

node | a AsNode |
key | the attribute key |

Since: 0.2.0

### as_node_to_xml ()

    GString *
    as_node_to_xml (const GNode *node,
                    AsNodeToXmlFlags flags);

Converts a node and it's children to XML.

#### Parameters

node | a AsNode. |
flags | the AsNodeToXmlFlags, e.g. `AS_NODE_TO_XML_FLAG_NONE`. |

#### Returns

a GString.

[transfer full]

Since: 0.1.0

### as_node_from_xml ()

    GNode *
    as_node_from_xml (const gchar *data,
                      AsNodeFromXmlFlags flags,
                      GError **error);

Parses XML data into a DOM tree.

[skip]

#### Parameters

data | XML data |
flags | AsNodeFromXmlFlags, e.g. `AS_NODE_FROM_XML_FLAG_NONE` |
error | A GError or `NULL` |

#### Returns

A populated AsNode tree.

[transfer none]

Since: 0.1.0

### as_node_from_bytes ()

    GNode *
    as_node_from_bytes (GBytes *bytes,
                        AsNodeFromXmlFlags flags,
                        GError **error);

Parses XML data into a DOM tree.

[skip]

#### Parameters

bytes | a GBytes |
flags | AsNodeFromXmlFlags, e.g. `AS_NODE_FROM_XML_FLAG_NONE` |
error | A GError or `NULL` |

#### Returns

A populated AsNode tree.

[transfer none]

Since: 0.7.6

### as_node_from_file ()

    GNode *
    as_node_from_file (GFile *file,
                       AsNodeFromXmlFlags flags,
                       GCancellable *cancellable,
                       GError **error);

Parses an XML file into a DOM tree.

[skip]

#### Parameters

file | file |
flags | AsNodeFromXmlFlags, e.g. `AS_NODE_FROM_XML_FLAG_NONE` |
cancellable | A GCancellable, or `NULL` |
error | A GError or `NULL` |

#### Returns

A populated AsNode tree.

[transfer none]

Since: 0.1.0

### as_node_to_file ()

    gboolean
    as_node_to_file (const GNode *root,
                     GFile *file,
                     AsNodeToXmlFlags flags,
                     GCancellable *cancellable,
                     GError **error);

Exports a DOM tree to an XML file.

[skip]

#### Parameters

root | A populated AsNode tree |
file | a GFile |
flags | AsNodeToXmlFlags, e.g. `AS_NODE_TO_XML_FLAG_NONE` |
cancellable | A GCancellable, or `NULL` |
error | A GError or `NULL` |

#### Returns

`TRUE` for success

Since: 0.2.0

### as_node_find ()

    GNode *
    as_node_find (GNode *root,
                  const gchar *path);

Gets a node from the DOM tree.

[skip]

#### Parameters

root | a root node, or `NULL` |
path | a path in the DOM, e.g. "html/body" |

#### Returns

A AsNode, or `NULL` if not found

Since: 0.1.0

### as_node_find_with_attribute ()

    GNode *
    as_node_find_with_attribute (GNode *root,
                                 const gchar *path,
                                 const gchar *attr_key,
                                 const gchar *attr_value);

Gets a node from the DOM tree with a specified attribute.

[skip]

#### Parameters

root | a root node, or `NULL` |
path | a path in the DOM, e.g. "html/body" |
attr_key | the attribute key |
attr_value | the attribute value |

#### Returns

A AsNode, or `NULL` if not found

Since: 0.1.0

### as_node_insert ()

    GNode *
    as_node_insert (GNode *parent,
                    const gchar *name,
                    const gchar *cdata,
                    AsNodeInsertFlags insert_flags,
                    ...);

Inserts a node into the DOM.

[skip]

#### Parameters

parent | a parent AsNode. |
name | the tag name, e.g. "id". |
cdata | the tag data, or `NULL`, e.g. "org.gnome.Software.desktop". |
insert_flags | any `AsNodeInsertFlags`. |
... | any attributes to add to the node, terminated by `NULL` |

#### Returns

A populated AsNode.

[transfer none]

Since: 0.1.0

### as_node_insert_localized ()

    void
    as_node_insert_localized (GNode *parent,
                              const gchar *name,
                              GHashTable *localized,
                              AsNodeInsertFlags insert_flags);

Inserts a localized key into the DOM.

#### Parameters

parent | a parent AsNode. |
name | the tag name, e.g. "id". |
localized | the hash table of data, with the locale as the key. |
insert_flags | any `AsNodeInsertFlags`. |

Since: 0.1.0

### as_node_insert_hash ()

    void
    as_node_insert_hash (GNode *parent,
                         const gchar *name,
                         const gchar *attr_key,
                         GHashTable *hash,
                         AsNodeInsertFlags insert_flags);

Inserts a hash table of data into the DOM.

#### Parameters

parent | a parent AsNode. |
name | the tag name, e.g. "id". |
attr_key | the key to use as the attribute in the XML, e.g. "key". |
hash | the hash table with the key as the key to use in the XML. |
insert_flags | any `AsNodeInsertFlags`. |

Since: 0.1.0

## Types and Values

### enum AsNodeToXmlFlags

The flags for converting to XML.

#### Members

AS_NODE_TO_XML_FLAG_NONE | No extra flags to use |
AS_NODE_TO_XML_FLAG_ADD_HEADER | Add an XML header to the data |
AS_NODE_TO_XML_FLAG_FORMAT_MULTILINE | Split up children with a newline |
AS_NODE_TO_XML_FLAG_FORMAT_INDENT | Indent the XML by child depth |
AS_NODE_TO_XML_FLAG_INCLUDE_SIBLINGS | Include the siblings when converting |
AS_NODE_TO_XML_FLAG_SORT_CHILDREN | Sort the tags by alphabetical order |

### enum AsNodeFromXmlFlags

The flags for converting from XML.

#### Members

AS_NODE_FROM_XML_FLAG_NONE | No extra flags to use |
AS_NODE_FROM_XML_FLAG_LITERAL_TEXT | Treat the text as an exact string |
AS_NODE_FROM_XML_FLAG_KEEP_COMMENTS | Retain comments in the XML file |
AS_NODE_FROM_XML_FLAG_ONLY_NATIVE_LANGS | Only load native languages |

### enum AsNodeInsertFlags

The flags to use when inserting a node.

#### Members

AS_NODE_INSERT_FLAG_NONE | No extra flags to use |
AS_NODE_INSERT_FLAG_PRE_ESCAPED | The data is already XML escaped |
AS_NODE_INSERT_FLAG_SWAPPED | The name and key should be swapped |
AS_NODE_INSERT_FLAG_NO_MARKUP | Preformat the 'description' markup |
AS_NODE_INSERT_FLAG_DEDUPE_LANG | No xml:lang keys where text matches 'C' |
AS_NODE_INSERT_FLAG_MARK_TRANSLATABLE | Mark the tag name as translatable |
AS_NODE_INSERT_FLAG_BASE64_ENCODED | The data is Base64 enoded |

### enum AsNodeError

The error type.

#### Members

AS_NODE_ERROR_FAILED | Generic failure |
AS_NODE_ERROR_INVALID_MARKUP | XML markup was invalid |
AS_NODE_ERROR_NO_SUPPORT | No support for parsing |

### AS_NODE_ERROR

    #define AS_NODE_ERROR				as_node_error_quark ()

### AsNode

    typedef GNode AsNode;