+--- gxml-0.10.0/docs/mallard/C.orig/gxml-serializable-objectmodel.page 1970-01-01 01:00:00.000000000 +0100
++++ gxml-0.10.0/docs/mallard/C/gxml-serializable-objectmodel.page 2016-09-23 21:21:52.000799682 +0200
+@@ -0,0 +1,19 @@
++<page xmlns="http://projectmallard.org/1.0/"
++ type="topic" id="gxml-serializable-objectmodel">
++
++ <info>
++ <revision pkgversion="0.4" version="0.1" date="2014-09-18" status="incomplete" />
++ <credit type="author">
++ <name>Daniel Espinosa</name>
++ <email>esodan@gmail.com</email>
++ </credit>
++ <license>
++ <p>Creative Commons Share Alike 3.0</p>
++ </license>
++ <link type="topic" xref="index" >Home</link>
++ </info>
++
++ <title>SerializableObjectModel implementation</title>
++ <p><code>SerializableObjectModel</code> is a class implementing <code>Serializable</code> interface. This implementation consider each object as a XML node, represented in GXml as a <code>GXml.Element</code> and its properties is represented by <code>GXml.Attr</code>. Each property, if it is a <code>Serializable</code> object, is represented as child nodes.</p>
++ <p>If a object's value property must be represented as a XML node content, then it requires to override <code>serialize_use_xml_node_value()</code> and set value at <code>serialized_xml_node_value</code>, as decribed at <link type="topic" xref="gxml-serializable#gxml-serializable-node-contents">Node content</link>.</p>
++</page>
+--- gxml-0.10.0/docs/mallard/C.orig/gxml-serializable.page 1970-01-01 01:00:00.000000000 +0100
++++ gxml-0.10.0/docs/mallard/C/gxml-serializable.page 2016-09-23 21:21:52.000799682 +0200
+@@ -0,0 +1,72 @@
++<page xmlns="http://projectmallard.org/1.0/"
++ type="topic" id="gxml-serializable">
++
++ <info>
++ <revision pkgversion="0.4" version="0.1" date="2014-09-18" status="incomplete" />
++ <credit type="author">
++ <name>Daniel Espinosa</name>
++ <email>esodan@gmail.com</email>
++ </credit>
++ <license>
++ <p>Creative Commons Share Alike 3.0</p>
++ </license>
++ <link type="topic" xref="index" />
++ </info>
++
++ <title>Serializable Interface</title>
++ <p>Implementors of this interface, could define or override the way you want to represent your class in a XML file.</p>
++ <section id="gxml-serializable-properties">
++ <title>Serializable properties</title>
++ <p>You can get control on class's properties to be serialized to XML. Allowing to provide ones, storing runtime information and ones to be stored in XML. By default, all object's properties are serialized. In order to skip properties from serialization process you must add its canonical name as key and its canonical name as value, to <code>ignored_serializable_properties</code> store.</p>
++ <p>Implementator must use <code>ignored_serializable_properties</code> property to check if a property should be serialized. This allows to dynamically remove, on convenience, properties on serialization. You can use <code>list_serializable_properties()</code> method as a convenient function, using its default implementation, or even override it at your convenience to automate dynamic serializable properties at run time; just make sure to skip the unwanted properties.</p>
++ <p>There are more methods to avoid properties serialization, like to override <code>init_properties</code> default implementation. It stores all <code>Serializale</code>'s properties to be ignored by default; you must ensure to initialize correctly, by calling <code>default_init_properties()</code> method before any other code in your overrided method.</p>
++ <section id="gxml-serializable-unknown_properties">
++ <title>Unknown XML elements</title>
++ <p>XML allows great flexibility, providing different ways to represent the same information. This is a problem when you try to deserialize them.</p>
++ <p>In order to deserialize correctly, you must create your XML, both by serializing a <code>Serializable</code> object or by hand writing. By using the former, you can add extra information, like nodes or properties, but most of them could be ignored or lost on deserialization/serialization process. To avoid data lost, you can override <code>get_enable_unknown_serializable_property ()</code> method in order to return true, your implementation or the ones in GXml, will store all unknown properties and nodes on deserialization and must serialize again back to the XML file. Even you are allowed to get this unknown objects by iterating on <code>unknown_serializable_property</code> hash table.</p>
++ </section>
++ <section id="gxml-serializable-property-name">
++ <title>Property's name</title>
++ <p>When serialize a class property, by default it uses its name given on class declaration, but is less common to see XML node mproperties with name like <code>your_property</code>, but more common is to use <code>YourProperty</code>. In order to use this kind of names, your implementation should use properties' nick name and override <code>property_use_nick()</code> method to return true. This should instruct your code to use this method to use property's nick name. This is the default in GXml default implementations.</p>
++ <p>In order to set node's name, you should override <code>node_name()</code> method.</p>
++ </section>
++ </section>
++ <section id="gxml-serializable-node-contents">
++ <title>XML node's content</title>
++ <p>By default GXml's implementations doesn't deseriaze/serialize XML node contents. In order to enable it, you must override <code>serialize_use_xml_node_value()</code> method to return true and store XML node's content to <code>serialized_xml_node_value</code> property.</p>
++ <p>Implementors could set up methods to provide a clean easy to use API to set nodes contents. In most cases, users would like to set a value through a getter or setter or through a property in the class. If you use a property, you should add it to <code>ignored_serializable_properties</code> in order to see its value in a XML node property.</p>
++ </section>
++ <section id="gxml-serializable-node-name">
++ <title>XML node name</title>
++ <p>On serialization XML node's name could be set to use a prety one. By default, node's name is the class name; becareful because name could be <code>GXmlSerializable</code>, while may you prefer to use just 'Serializable'.</p>
++ <p>In order to set node's name, you should override <code>node_name()</code> method.</p>
++ </section>
++ <section id="gxml-serializable-serialize">
++ <title>Serialize</title>
++ <p><code>Serializable</code> interface allows you to implement your own <code>serialize()</code> method. Your implementation should take a <code>GXml.Node</code> and serialize over it. Given <code>GXml.Node</code>, could be an <code>GXml.Element</code> or a <code>GXml.Document</code>, your implementaiton should take care about this and return XML nodes representing your class object.</p>
++ </section>
++ <section id="gxml-serializable-serialize-property">
++ <title>Serialize a property</title>
++ <p><code>Serializable</code> interface allows you to implement your own <code>serialize_property()</code> method. Your implementation should take a <code>GXml.Element</code> to serialize on your property. Your implementation could detect the property to serialize and get its value, from given <code>GLib.ParamSpec</code>. Your serialization could be add a <code>GXml.Attr</code> or child <code>GXml.Element</code> to the given <code>GXml.Element</code> or set a contents to it; its your choice.</p>
++ </section>
++ <section id="gxml-serializable-deserialize">
++ <title>Deserialize</title>
++ <p><code>Serializable</code> interface allows you to implement your own <code>deserialize()</code> method. Your implementation should take a <code>GXml.Node</code> and deserialize from it. Given <code>GXml.Node</code>, could be an <code>GXml.Element</code> or a <code>GXml.Document</code>, your implementaiton should take care about this and return XML nodes representing your class object.</p>
++ <p>Your implementation could take <code>GXml.Element</code>'s name to detect the property to set up or detect the root element in a <code>GXml.Document</code> to use. Then you can iterate over all node's properties and set up your object properties; you can use <code>gvalue_to_string()</code> to transform most common value types from string to the required value's type.</p>
++ <section id="gxml-serializable-deserialize-supportedtypes">
++ <title>Supported types</title>
++ <p><code>Serializable</code> interface support a number of data types to convert from its string representation. These are supported types:</p>
++ <list>
++ <item><p>integers: int8, int64, uint, long, ulong, char, uchar</p></item>
++ <item><p>boolean</p></item>
++ <item><p>floats: float, double</p></item>
++ <item><p>enumerations</p></item>
++ </list>
++ <section id="gxml-serializable-deserialize-enums">
++ <p>Enumerations have a set of utility methods to better represent on serialisation/deserialization.</p>
++ <p>Enumerations could be converted to string using its definition on <code>GLib.EnumClass</code>, by taking its nick name directly or converting to its camel case representation.</p>
++ <p>Any enumeration value type in a <code>GLib.Object</code>'s property could be deserialized from its definition given on <code>GLib.EnumClass</code> (name and nick) or from its camel case representation.</p>
++ </section>
++ </section>
++ </section>
++</page>
+--- gxml-0.10.0/docs/mallard/C.orig/index.page 1970-01-01 01:00:00.000000000 +0100
++++ gxml-0.10.0/docs/mallard/C/index.page 2016-09-23 21:21:52.000799682 +0200
+@@ -0,0 +1,25 @@
++<page xmlns="http://projectmallard.org/1.0/"
++ type="guide" id="index">
++
++ <info>
++ <revision pkgversion="0.4" version="0.1" date="2014-09-18" status="incomplete"/>
++ <credit type="author">
++ <name>Daniel Espinosa</name>
++ <email>esodan@gmail.com</email>
++ </credit>
++ <license>
++ <p>Creative Commons Share Alike 3.0</p>
++ </license>
++ </info>
++
++ <title>
++ GXml Serialization Framework Manual
++ </title>
++ <p>
++ This guide provides examples and applications of GXml's Serialization Framework.
++ </p>
++ <p>GXml Serialization Framework allows <code>GLib.Object</code> objects to be serialized to XML files.</p>
++ <p>It has a <code>Serializable</code> interface to be implemented by a <code>GLib.Object</code> class, allowing great flexibility on how the object must be represented in XML format.</p>
++ <p>Today GXml have two implementations, one of them is <code>SerializableObjectModel</code>, using a model where each object is a XML node and a each object's property is a XML node property.</p>
++ <p>Serialization Framework have containers implementations, allowing to store <code>Serializable</code> objects in arrays, hash tables and multikey stores.</p>
++</page>
projects / packages / gxml.git / commitdiff