[gxml] Added API for TextWriter interface implementations

[Daniel Espinosa Ortiz <despinosa src gnome org>]

commit abe0a9cf26962710e4a334cdfe4988811fe4e6b4
Author: Daniel Espinosa <esodan gmail com>
Date:   Mon May 4 15:10:18 2015 -0500

    Added API for TextWriter interface implementations
    
    * GXml.Document and GXml.Element added finalize functions to be used
      with GXml.TextWriter interface

 gxml/Document.vala |   80 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 gxml/Element.vala  |   10 ++++++
 2 files changed, 90 insertions(+), 0 deletions(-)
---
diff --git a/gxml/Document.vala b/gxml/Document.vala
index 8adf728..bd394e7 100644
--- a/gxml/Document.vala
+++ b/gxml/Document.vala
@@ -21,6 +21,12 @@
  */
 
 using Gee;
+
+public errordomain GXml.DocumentError {
+  INVALID_DOCUMENT_ERROR,
+  INVALID_FILE
+}
+
 /**
  * Interface to handle XML documents.
  *
@@ -44,6 +50,19 @@ public interface GXml.Document : Object, GXml.Node
    */
   public abstract GXml.Node create_element (string name);
   /**
+   * This method should finalize a new created { link GXml.Element}.
+   *
+   * Once a { link GXml.Element} was created and setup, you should finalize it
+   * by calling this method. Is a good practice to call this function, even if
+   * current implemention doesn't requires it.
+   *
+   * Setup a new { link GXml.Element} include: set its attributes and add childs
+   * { link GXml.Node}. When finish, call this function.
+   *
+   * This function is useful when using { link GXml.TextWriter} implementations.
+   */
+  public virtual void finalize_element () { return; }
+  /**
    * Creates a new { link GXml.Text}.
    *
    * Is a matter of you to add as a child to any other
@@ -51,10 +70,71 @@ public interface GXml.Document : Object, GXml.Node
    */
   public abstract GXml.Node create_text (string text);
   /**
+   * This method should finalize a new created { link GXml.Text}.
+   *
+   * Once a { link GXml.Text} was created and setup, you should finalize it
+   * by calling this method. Is a good practice to call this function, even if
+   * current implemention doesn't requires it.
+   *
+   * Setup a new { link GXml.Text} include: set its text, done when it is created.
+   * When finish, call this fucntion.
+   *
+   * This function is useful when using { link GXml.TextWriter} implementations.
+   */
+  public virtual void finalize_text () { return; }
+  /**
    * Creates a new { link GXml.Comment}.
    *
    * Is a matter of you to add as a child to any other
    * { link GXml.Node}, like a { link GXml.Element} node.
    */
   public abstract GXml.Node create_comment (string text);
+  /**
+   * This method should finalize a new created { link GXml.Comment}.
+   *
+   * Once a { link GXml.Comment} was created and setup, you should finalize it
+   * by calling this method. Is a good practice to call this function, even if
+   * current implemention doesn't requires it.
+   *
+   * Setup a new { link GXml.Comment} include: set its text, done when it is created.
+   * When finish, call this fucntion.
+   *
+   * This function is useful when using { link GXml.TextWriter} implementations.
+   */
+  public virtual void finalize_comment () { return; }
+  /**
+   * Creates a new { link GXml.Document} using default implementation class.
+   *
+   * As an interface you can create your own implementation of it, but if 
+   * default one is required use this.
+   */
+   public static GXml.Document new_default ()
+   {
+     return new xDocument ();
+   }
+  /**
+   * Creates a new { link GXml.Document} from a file path using default implementation class.
+   *
+   * As an interface you can create your own implementation of it, but if 
+   * default one is required use this.
+   */
+   public static GXml.Document new_default_for_path (string path)
+     throws GLib.Error
+   {
+     File f = File.new_for_path (path);
+     return GXml.Document.new_default_for_file (f);
+   }
+  /**
+   * Creates a new { link GXml.Document} from a { link GLib.File} using default implementation class.
+   *
+   * As an interface you can create your own implementation of it, but if 
+   * default one is required use this.
+   */
+   public static GXml.Document new_default_for_file (GLib.File file)
+     throws GLib.Error
+   {
+     if (!file.query_exists ())
+       throw new DocumentError.INVALID_FILE ("Invalid file");
+     return new xDocument.from_path (file.get_path ());
+   }
 }
diff --git a/gxml/Element.vala b/gxml/Element.vala
index 20c71c2..dfda260 100644
--- a/gxml/Element.vala
+++ b/gxml/Element.vala
@@ -46,6 +46,16 @@ public interface GXml.Element : Object, GXml.Node
      * All attributes could be get using { link GXml.Node.attrs} property.
      */
     public abstract GXml.Node get_attr (string name);
+  /**
+   * This method should finalize a new created { link GXml.Attribute}.
+   *
+   * Once a { link GXml.Attribute} was created and setup, you should finalize it
+   * by calling this method. Is a good practice to call this function, even if
+   * current implemention doesn't requires it.
+   *
+   * This function is useful when using { link GXml.TextWriter} implementations.
+   */
+  public virtual void finalize_attr () { return; }
     /**
      * This should be just a different name for { link GXml.Node.name}.
      */