[gxml/newattr: 1/13] DESIGN: design document (used for newattr branch right now)

[Richard Hans Schwarting <rschwart src gnome org>]

commit b843164dee9eebc1805279ebfbc94d78972192d3
Author: Richard Schwarting <aquarichy gmail com>
Date:   Tue Oct 15 20:59:44 2013 -0400

    DESIGN: design document (used for newattr branch right now)

 DESIGN             |   68 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 gxml/Attr.vala     |    8 ++----
 gxml/NodeList.vala |   11 ++++----
 3 files changed, 77 insertions(+), 10 deletions(-)
---
diff --git a/DESIGN b/DESIGN
new file mode 100644
index 0000000..15ec7bb
--- /dev/null
+++ b/DESIGN
@@ -0,0 +1,68 @@
+* 2013-10-15
+
+** Attributes
+
+Currently attributes are:
+- Xml.Attr nodes inside their Xml.Node
+- in a GXml.Node, we keep a proxy GLib.HashTable as our DOM's NamedNodeMap
+  - the GLib.HashTable is created on first access
+  - it creates a GXml.Attr for each Xml.Attr in the subject Xml.Node's properties
+
+- Users modify the GLib.HashTable
+  - periodically we sync the GLib.HashTable of GXml.Attrs with the underlying Xml.Node.properties
+     - (like when we're stringifying (since we use libxml2's stringification functions) or saving the 
document)
+  
+
+New design
+- store them in GXml.Document.node_dict like Elements, treating
+  Xml.Attr as Xml.Node (is that really valid? alternatively,
+  corresponding attr dictionary)
+- eliminate syncing
+
+GXml.Attr support requirements
+- already supported through BackedNode
+  - namespace prefixes
+  - local_name
+  - node_name
+  - child_nodes (invisibly returning a NodeChildNodeList instead of an AttrChildNodeList)
+  - insert_before, replace_child, remove_child, append_child, has_child_nodes; even get better error handling
+
+- need to support
+  - specified property (cur impl is a stub anyway)
+  - *node_value*; this is not just node->content
+    - currently we travers Xml.Attr's children via a GXml.AttrChildNodeList
+      - could we replace AttrChildNodeList if we just treat Xml.Attr as an Xml.Node?
+        - yes, we could use NodeChildNodeList; and we already treat Xml.Attr as an Xml.Node in 
'parent_as_xmlnode'
+    - still want to build like that
+      - mystery:
+       - if we get a GXml.Element with an attribute lang=de, and we
+          change lang=en, but we don't sync yet, how do we end up with
+          lang=en when we call GXml.Attr.node_value?  Shouldn't it
+          still pick up lang=de from the underlying Xml.Node'
+          Xml.Attr?
+       - No, because GXml.Element.set_attribute creates a new
+          GXml.Attr using Document.create_attribute, which creates a
+          new Xml.Attr using Xml.Doc.new_prop, and then replaces the
+          old GXml.Attr.  So, yes, the underlying Xml.Doc still has
+          the old Xml.Attr with lang=de, but our attributes
+          GLib.HashTable proxy in our GXml.Element has the new
+          GXml.Attr with Xml.Attr (which is not yet attached to the
+          actual underlying Xml.Node or Xml.Doc) and when we stringify
+          or save to disk, we sync first.
+    - we'll iterate directly over Xml.Attr's children (using a
+      NodeChildNodeList though) to build our future string that we'll
+      return (using a NodeList interfae for easy iteration despite
+      performance penalty and to prepare for replacing libxml2 some
+      day)
+  - name (copy cur impl)
+  - value (copy cur impl)
+  - clone_node; currently we don't allow that on Attrs, and we might want to continue to not
+  - to_string (copy cur impl)
+
+GXml.Element
+- set_attr
+
+  
+  
+
+
diff --git a/gxml/Attr.vala b/gxml/Attr.vala
index ee4e1c2..d718322 100644
--- a/gxml/Attr.vala
+++ b/gxml/Attr.vala
@@ -56,6 +56,9 @@ namespace GXml {
         * @see GXml.Node
         */
        public class Attr : Node {
+               /** Private properties */
+               internal Xml.Attr *node;
+
                /**
                 * { inheritDoc}
                 */
@@ -95,9 +98,6 @@ namespace GXml {
                        }
                }
 
-               /** Private properties */
-               internal Xml.Attr *node;
-
                /** Constructors */
                internal Attr (Xml.Attr *node, Document doc) {
                        // TODO: wish valac would warn against using this. before calling base()
@@ -146,7 +146,6 @@ namespace GXml {
                        internal set {
                                // TODO: consider adding an empty () method to NodeList
                                foreach (Node child in this.child_nodes) {
-                                       // TODO: this doesn't clear the actual underlying attributes' values, 
is this what we want to do?  It works if we eventually sync up values
                                        this.remove_child (child);
                                }
                                this.append_child (this.owner_document.create_text_node (value));
@@ -158,7 +157,6 @@ namespace GXml {
                /**
                 * { inheritDoc}
                 */
-               /* already doc'd in Node */
                public override NodeList? child_nodes {
                        owned get {
                                // TODO: always create a new one?
diff --git a/gxml/NodeList.vala b/gxml/NodeList.vala
index 56ce709..948cee3 100644
--- a/gxml/NodeList.vala
+++ b/gxml/NodeList.vala
@@ -415,6 +415,7 @@ namespace GXml {
                        }
                }
        }
+
        internal class AttrChildNodeList : ChildNodeList {
                Xml.Attr *parent;
 
@@ -427,6 +428,11 @@ namespace GXml {
                        }
                }
 
+               internal AttrChildNodeList (Xml.Attr* parent, Document owner) {
+                       this.parent = parent;
+                       this.owner = owner;
+               }
+
                internal override Xml.Node *parent_as_xmlnode {
                        get {
                                /* This is disgusting, but we do this for the case where
@@ -439,11 +445,6 @@ namespace GXml {
                                return (Xml.Node*)parent;
                        }
                }
-
-               internal AttrChildNodeList (Xml.Attr* parent, Document owner) {
-                       this.parent = parent;
-                       this.owner = owner;
-               }
        }
        internal class EntityChildNodeList : ChildNodeList {
                Xml.Entity *parent;