... | ... | @@ -19,57 +19,57 @@ You can access most updated documentation, generated from `master`, using the [p |
|
|
|
|
|
## Wrap libxml2
|
|
|
|
|
|
libxml2 is a C based library, so no GObject interface is avairable for it. GXml wraps it using [`GNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GNode.html) derived classes, providing an API to hide most details on its use.
|
|
|
libxml2 is a C based library, so no GObject interface is avairable for it. GXml wraps it using [`XNode`](https://gnome.pages.gitlab.gnome.org/gxml/dev/GXml.XNode.html) derived classes, providing an API to hide most details on its use.
|
|
|
|
|
|
For DOM4 API using [`GNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GNode.html), all returned objects are created on the fly with internal references to libxml2's native nodes pointers in order to provide automatic memory management like unref an object, so **is highly recommended to use `GNode` DOM4 API instead to use libxml2 structs**.
|
|
|
For DOM4 API using [`Node`](https://gnome.pages.gitlab.gnome.org/gxml/dev/GXml.Node.html), all returned objects are created on the fly with internal references to libxml2's native nodes pointers in order to provide automatic memory management like unref an object, so **is highly recommended to use `GNode` DOM4 API instead to use libxml2 structs**.
|
|
|
|
|
|
libxml2's tree `xmlDoc*` is used by GXml's [`GDocument`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GDocument.html) objects so, any modification to that pointers should use libxml2's API. Fortunally, GXml's `GNode` API provides a DOM4 one for most common use cases.
|
|
|
libxml2's tree `xmlDoc*` is used by GXml's [`XDocument`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.XDocument.html) objects so, any modification to that pointers should use libxml2's API. Fortunally, GXml's `Node` API provides a DOM4 one for most common use cases.
|
|
|
|
|
|
## W3C DOM4
|
|
|
|
|
|
DOM4 provides a reach API, full of features, most of them not implemented yet in current 0.18 release.
|
|
|
|
|
|
DOM4 is implemented by [`GNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GNode.html) derived classes wrappers and by a pure GObject implementation classes derived from [`GomNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GomNode.html).
|
|
|
DOM4 is implemented by [`Node`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.Node.html) derived classes wrappers and by a pure GObject implementation classes derived from [`Node`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.Node.html).
|
|
|
|
|
|
[`GomNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GomNode.html) and its descendants, fixes some limitations inherited by [`GNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.GNode.html) from libxml2, like the ability to have more than one child [`DomText`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.DomText.html) in a [`DomElement`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.DomElement.html); there are more room for improvements in `GomNode` than in `GNode` in the future.
|
|
|
[`Node`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.Node.html) and its descendants, fixes some limitations inherited by [`XNode`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.XNode.html) from libxml2, like the ability to have more than one child [`DomText`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.DomText.html) in a [`DomElement`](https://gnome.pages.gitlab.gnome.org/gxml/GXml.DomElement.html); there are more room for improvements in `Node` than in `XNode` in the future.
|
|
|
|
|
|
# Serialization
|
|
|
|
|
|
Serialization is the process to represent to/back GObject in XML. Can be many different ways to archive that.
|
|
|
|
|
|
In GXml you can simple derive a class from `GElement` or `GomElement`to be able to set properties or add new nodes, but only if they are the `GNode` or `GomElement` descendants, respectively.
|
|
|
In GXml you can simple derive a class from `Element` to be able to set properties or add new nodes, but only if they are the `Node` descendants.
|
|
|
|
|
|
## GomNode for fast de/serialization
|
|
|
## Node for fast de/serialization
|
|
|
|
|
|
`GomNode` currently use `xmlTextReader` to parse an XML document whith an efficient performance and reduced footprint too.
|
|
|
`Node` currently use `xmlTextReader` to parse an XML document whith an efficient performance and reduced footprint too.
|
|
|
|
|
|
`GomNode`, uses `xmlTextWritter` with an improved parser, so write down XML documents fast.
|
|
|
`Node`, uses `xmlTextWritter` with an improved parser, so write down XML documents **fast**.
|
|
|
|
|
|
> For examples and detailed information go to [GomElement](gomelement) page.
|
|
|
> For examples and detailed information go to [Element](element) page.
|
|
|
|
|
|
### GObject to XML and back
|
|
|
|
|
|
GomNode's descendant GomElement, provides an easy way to use GObject's properties to XML Node's attributes, mapping a one to one XML element node to a GObject.
|
|
|
`Node`'s descendant `Element`, provides an easy way to use GObject's properties to XML Node's attributes, mapping a one to one XML element node to a GObject.
|
|
|
|
|
|
#### XML structure changes tolerant
|
|
|
|
|
|
|
|
|
##### XML changes tolerant
|
|
|
|
|
|
Like a `DomElement`, `GomElement` descendants can have any DOM node and attributes; it is not limited to GObject's properties defined at class declaration, so is very easy to add new nodes and attributes to source XML and `GomElement`, just map the ones defined at class declaration, but allows you to use DOM4 API to access them.
|
|
|
Like a `DomElement`, `Element` descendants can have any DOM node and attributes; it is not limited to GObject's properties defined at class declaration, so is very easy to add new nodes and attributes to source XML and `Element`, just map the ones defined at class declaration, but allows you to use DOM4 API to access them.
|
|
|
|
|
|
##### No XML data lost
|
|
|
|
|
|
In the same way, when you write down an `GomElement`, with pre-parsed childs, any modification to GObject's properties and/or DOM nodes will be preserved.
|
|
|
In the same way, when you write down an `Element`, with pre-parsed childs, any modification to GObject's properties and/or DOM nodes will be preserved.
|
|
|
|
|
|
#### Collections
|
|
|
|
|
|
One feature added to GomNode derived classes, are [Link Collections] (collections). Take a list of child nodes and clasify them in collection, with different ways to access them, provides a powerful mechanism to manage your XML data.
|
|
|
One feature added to `Node` derived classes, are [Link Collections] (collections). Take a list of child nodes and classify them in collection, with different ways to access them, provides a powerful mechanism to manage your XML data.
|
|
|
|
|
|
From a simple array to hash tables using one, two and three keys to access them, provides fast and easy ways to take advantage of your data layout.
|
|
|
|
|
|
#### Properties as Objects
|
|
|
|
|
|
Serialize objects from `GObject` properties are easy with `GomProperty` interface implementations.
|
|
|
Serialize objects from `GObject` properties are easy with `GXml.Property` interface implementations.
|
|
|
|
|
|
In `GomElement` derived classes you can use simple properties types like bool or double, to `GObject` based values mapped to XML Element nodes or simple attributes. |
|
|
In `GXml.Element` derived classes you can use simple properties types like bool or double, to `GObject` based values mapped to XML Element nodes or simple attributes. |