as-node

as-node — A simple DOM parser

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <appstream-glib.h>

enum                AsNodeToXmlFlags;
enum                AsNodeFromXmlFlags;
enum                AsNodeInsertFlags;
enum                AsNodeError;
#define             AS_NODE_ERROR
typedef             AsNode;
GNode *             as_node_new                         (void);
GQuark              as_node_error_quark                 (void);
void                as_node_unref                       (GNode *node);
const gchar *       as_node_get_name                    (const GNode *node);
const gchar *       as_node_get_data                    (const GNode *node);
const gchar *       as_node_get_comment                 (const GNode *node);
AsTag               as_node_get_tag                     (const GNode *node);
const gchar *       as_node_get_attribute               (const GNode *node,
                                                         const gchar *key);
gint                as_node_get_attribute_as_int        (const GNode *node,
                                                         const gchar *key);
guint               as_node_get_attribute_as_uint       (const GNode *node,
                                                         const gchar *key);
GHashTable *        as_node_get_localized               (const GNode *node,
                                                         const gchar *key);
const gchar *       as_node_get_localized_best          (const GNode *node,
                                                         const gchar *key);
GHashTable *        as_node_get_localized_unwrap        (const GNode *node,
                                                         GError **error);
void                as_node_set_name                    (GNode *node,
                                                         const gchar *name);
void                as_node_set_data                    (GNode *node,
                                                         const gchar *cdata,
                                                         AsNodeInsertFlags insert_flags);
void                as_node_set_comment                 (GNode *node,
                                                         const gchar *comment);
void                as_node_add_attribute               (GNode *node,
                                                         const gchar *key,
                                                         const gchar *value);
void                as_node_add_attribute_as_int        (GNode *node,
                                                         const gchar *key,
                                                         gint value);
void                as_node_add_attribute_as_uint       (GNode *node,
                                                         const gchar *key,
                                                         guint value);
void                as_node_remove_attribute            (GNode *node,
                                                         const gchar *key);
GString *           as_node_to_xml                      (const GNode *node,
                                                         AsNodeToXmlFlags flags);
GNode *             as_node_from_xml                    (const gchar *data,
                                                         AsNodeFromXmlFlags flags,
                                                         GError **error);
GNode *             as_node_from_bytes                  (GBytes *bytes,
                                                         AsNodeFromXmlFlags flags,
                                                         GError **error);
GNode *             as_node_from_file                   (GFile *file,
                                                         AsNodeFromXmlFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
gboolean            as_node_to_file                     (const GNode *root,
                                                         GFile *file,
                                                         AsNodeToXmlFlags flags,
                                                         GCancellable *cancellable,
                                                         GError **error);
GNode *             as_node_find                        (GNode *root,
                                                         const gchar *path);
GNode *             as_node_find_with_attribute         (GNode *root,
                                                         const gchar *path,
                                                         const gchar *attr_key,
                                                         const gchar *attr_value);
GNode *             as_node_insert                      (GNode *parent,
                                                         const gchar *name,
                                                         const gchar *cdata,
                                                         AsNodeInsertFlags insert_flags,
                                                         ...);
void                as_node_insert_localized            (GNode *parent,
                                                         const gchar *name,
                                                         GHashTable *localized,
                                                         AsNodeInsertFlags insert_flags);
void                as_node_insert_hash                 (GNode *parent,
                                                         const gchar *name,
                                                         const gchar *attr_key,
                                                         GHashTable *hash,
                                                         AsNodeInsertFlags insert_flags);

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

Details

enum AsNodeToXmlFlags

typedef enum {
	AS_NODE_TO_XML_FLAG_NONE		= 0, /* Since: 0.1.0 */
	AS_NODE_TO_XML_FLAG_ADD_HEADER		= 1, /* Since: 0.1.0 */
	AS_NODE_TO_XML_FLAG_FORMAT_MULTILINE = 2, /* Since: 0.1.0 */
	AS_NODE_TO_XML_FLAG_FORMAT_INDENT = 4, /* Since: 0.1.0 */
	AS_NODE_TO_XML_FLAG_INCLUDE_SIBLINGS = 8, /* Since: 0.1.4 */
	AS_NODE_TO_XML_FLAG_SORT_CHILDREN = 16, /* Since: 0.2.1 */
} AsNodeToXmlFlags;

The flags for converting to XML.

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

typedef enum {
	AS_NODE_FROM_XML_FLAG_NONE		= 0,		/* Since: 0.1.0 */
	AS_NODE_FROM_XML_FLAG_LITERAL_TEXT = 1 << 0, /* Since: 0.1.3 */
	AS_NODE_FROM_XML_FLAG_KEEP_COMMENTS = 1 << 1, /* Since: 0.1.6 */
	AS_NODE_FROM_XML_FLAG_ONLY_NATIVE_LANGS = 1 << 2, /* Since: 0.6.5 */
} AsNodeFromXmlFlags;

The flags for converting from XML.

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

typedef enum {
	AS_NODE_INSERT_FLAG_NONE		= 0, /* Since: 0.1.0 */
	AS_NODE_INSERT_FLAG_PRE_ESCAPED		= 1, /* Since: 0.1.0 */
	AS_NODE_INSERT_FLAG_SWAPPED		= 2, /* Since: 0.1.0 */
	AS_NODE_INSERT_FLAG_NO_MARKUP		= 4, /* Since: 0.1.1 */
	AS_NODE_INSERT_FLAG_DEDUPE_LANG		= 8, /* Since: 0.1.4 */
	AS_NODE_INSERT_FLAG_MARK_TRANSLATABLE = 16, /* Since: 0.2.1 */
	AS_NODE_INSERT_FLAG_BASE64_ENCODED = 32, /* Since: 0.3.1 */
} AsNodeInsertFlags;

The flags to use when inserting a node.

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

typedef enum {
	AS_NODE_ERROR_FAILED,
	AS_NODE_ERROR_INVALID_MARKUP,		/* Since: 0.2.4 */
	AS_NODE_ERROR_NO_SUPPORT,		/* Since: 0.3.0 */
} AsNodeError;

The error type.

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;

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.

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"

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"

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"

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.

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"

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

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

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

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.

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
<span style="color: red"><description>
 <span style="color: red"><p>Hi</p></span>
 <span style="color: red"><p>Czesc</p></span>
 <span style="color: red"><ul>
  <span style="color: red"><li>First</li></span>
  <span style="color: red"><li>Pierwszy</li></span>
 </ul></span>
</description></span>

into a hash that contains:

1
2
"C"  ->  "<span style="color: red"><p>Hi</p></span><span style="color: red"><ul><span style="color: red"><li>First</li></span></ul></span>"
"pl" ->  "<span style="color: red"><p>Czesc</p></span><span style="color: red"><ul><span style="color: red"><li>Pierwszy</li></span></ul></span>"

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"

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.

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.

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.

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.

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.

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"

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.

node :

a AsNode.

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,
                                                         AsNodeFromXmlFlags flags,
                                                         GError **error);

Parses XML data into a DOM tree.

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.

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.

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.

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.

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.

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.

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.

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.

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