AppStream-glib Reference Manual: as-node

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_attribute ()
GHashTable *	as_node_get_localized ()
const gchar *	as_node_get_localized_best ()
GHashTable *	as_node_get_localized_unwrap ()
GString *	as_node_to_xml ()
GNode *	as_node_from_xml ()
GNode *	as_node_from_file ()
GNode *	as_node_find ()
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

Object Hierarchy

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.

Functions

as_node_new ()

GNode *
as_node_new (void);

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

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 GNode.

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 GNode

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 GNode

Returns

string value

Since 0.1.0

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 GNode
key	the attribute key

Returns

string value

Since 0.1.0

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 GNode
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 GNode.
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:

<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 GNode.
error	A GError or `NULL`.

Returns

a hash table of data.

[transfer full]

Since 0.1.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 GNode.
flags	the AsNodeToXmlFlags, e.g. `AS_NODE_INSERT_FLAG_PRE_ESCAPED`.

Returns

a GString.

[transfer full]

Since 0.1.0

as_node_from_xml ()

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

Parses XML data into a DOM tree.

Parameters

data	XML data
data_len	Length of `data` , or -1 if NULL terminated
flags	AsNodeFromXmlFlags, e.g. `AS_NODE_FROM_XML_FLAG_NONE`
error	A GError or `NULL`

Returns

A populated GNode tree.

[transfer full]

Since 0.1.0

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.

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 GNode tree.

[transfer full]

Since 0.1.0

as_node_find ()

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

Gets a node from the DOM tree.

Parameters

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

Returns

A GNode, 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.

Parameters

parent	a parent GNode.
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 GNode.

[transfer full]

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 GNode.
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 GNode.
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

enum AsNodeFromXmlFlags

The flags for converting from XML.

Members

AS_NODE_FROM_XML_FLAG_NONE

No extra flags to use

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

enum AsNodeError

The error type.

Members

AS_NODE_ERROR_FAILED

Generic failure

AS_NODE_ERROR

#define AS_NODE_ERROR				as_node_error_quark ()