as-node

as-node — A simple DOM parser

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

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.

See also: AsApp

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:

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 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 ()