dreamcat4-libxml-bindings 0.1.4 → 0.2.0

data/README.rdoc

@@ -1,39 +1,59 @@
 = libxml-bindings
 
-This introduction text is taken from http://thebogles.com/blog/an-hpricot-style-interface-to-libxml#,
-credit to Phil Bogle.
+{libxml-bindings}[http://github.com/dreamcat4/libxml-bindings/tree/master] is a light set of methods and bolt-ons which aren't maintained by the core {libxml ruby library}[http://libxml.rubyforge.org/install.xml]. These methods aim to provide a more convenient API interface which is provided and documented separately, but actually mixed in to extend the original LibXML::classes. Using these methods should significantly reduce the lines of code needed to perform the most common operations of accessing and manipulating an xml document structure.
 
-== Convenience functions
+For a full list of methods, please refer to the {RDoc Documentation}[http://rdoc.info/projects/dreamcat4/libxml-bindings] 
+and also the {Libxml-Ruby RDocs}[http://libxml.rubyforge.org/rdoc/]
 
-You can call to_xml_doc on any string to convert it into an XML::Document:
+For benkchmarks / performance comparison see http://cfis.savagexi.com/2008/07/16/resurrecting-libxml-ruby
+
+== Installation
+
+	gem sources -a http://gems.github.com
+	gem install dreamcat4-libxml-bindings
+
+== Getting started
+
+You can call +to_xmldoc+ on any xml string to convert it into an XML::Document
 
 	>> s = '<foo id="1"><author>p. bogle</author><bar>content</bar><bar>cont2</bar></foo>'
-	>> root = s.to_xml_doc.root
+	>> doc = s.to_xmldoc
 
-The at() method returns the first Node matching the given xpath:
+The +node["/xpath"]+ method returns the first Node matching the given {xpath}[http://www.w3schools.com/XPath/xpath_syntax.asp]
 
-	>> root.at("author")
+	>> doc.node["author"]
 	=> <author>p. bogle</author>
 
-The search() method returns a list of Nodes matching the given xpath:
+The +nodes["/xpath"]+ method returns an array of Nodes matching the given {xpath}[http://www.w3schools.com/XPath/xpath_syntax.asp]
 
-	>> root.search("bar")
+	>> doc.nodes["/foo/bar"]
 	=> [<bar>content</bar>, <bar>content2</bar>]
 
-search() can also be called with a block to iterate through each of the matching nodes:
++nodes[]+ can be called with a block to iterate through each of the matching nodes
 
-	>>  root.search("bar") do |bar| puts bar.xpath; end
+	>>  doc.nodes["bar"] do |bar| puts bar.xpath; end
 	/foo/bar[1]
 	/foo/bar[2]
 
-== Namespace helpers
+You can call +node[]+ on another node to iterate and search within a smaller context of the document
 
-The handling of default namespaces in libxml-ruby is awkward because you have to remember to pass along an array of namespace strings to every find() method call, and because you have to repeat yourself about the href of the default namespace.
+	>> foo = doc.node["/foo"]
+	>> foo.node["author"]
+	=> <author>p. bogle</author>
+	
+	>> foo.nodes["/bar"].each {|node| puts node.inner_xml}
+	=> "content2"
+	=> "cont2"
+
+For more information about XPath syntax, please see http://www.w3schools.com/XPath/xpath_syntax.asp
 
-The helpers add a register_default_namespace function that makes this simpler.
+== Namespace Stripping
 
-Suppose you had XML like the following
+The handling of default namespaces in libxml-ruby is extremely awkward and cumbersome as it requires passing along an array of namespace strings with every find() method call. It also represents ambiguity concerning the href of the default namespace.
 
+Suppose you had a namespaced XML source with xmlns:= directives like this
+	
+	>> document.to_xml
 	<?xml version="1.0" encoding="UTF-8"?>
 	<feed xmlns="http://www.w3.org/2005/Atom"
 	        xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
@@ -43,12 +63,30 @@ Suppose you had XML like the following
 	   ...
 	</feed>
 
-Then you could say the following and have it work as expected:
+With libxml-bindings its possible to do:
+
+	>> document.strip!
+
+And be left with plain xml which can be parsed more easily and without the need for specifying any confusing namespace directives
 
-	root.register_default_namespace("atom")
-	root.search("atom:title")
+	>> document.to_xml
+	<?xml version="1.0" encoding="UTF-8"?>
+	<feed>
+	  <title type=\"text\">Phil Bogle's Contacts</title>
+	   ...
+	</feed>
+	
+	>> document.node["/feed/title"].inner_xml
+	=> "Phil Bogle's Contacts"
+
+After manipulating your data model, a default namespace can later be re-applied on the top-level node. However its generally not recommended to use more than one namespace within the same xml document.
 
 == Copyright
 
-Copyright (c) 2009 dreamcat4. See LICENSE for details.
-Copyright (c) 2008 Phil Bogle. See LICENSE for details.
+ Copyright (c) 2009 dreamcat4. See LICENSE for details.
+
+== Contribution, Credits
+
+This project was started on the top of Phil Bogle's libxml_helper.rb[http://thebogles.com/blog/an-hpricot-style-interface-to-libxml#]. Most methods have been renamed to represent the api styling of the libxml project. The coding examples above are all adapted from Phil's original explanatory texts.
+
+Copyright (c) 2008 Phil Bogle.

data/Rakefile

@@ -5,10 +5,11 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "libxml-bindings"
-    gem.summary = %Q{Dreamcat4's bindings for libxml-ruby. In development. This gem will provide convenience functions for both reading and writing XML in ruby. Implemented as wrapper for underlying libxml2 / SAX. Aims are to be faster (very much) and simpler (little bit) than hpricot. This project is a continuation / extension of libxml_helper.rb by Phil Bogle.}
+    gem.summary = %Q{Dreamcat4's bindings on libxml-ruby. Convenience methods for extending the core classes.}
     gem.email = "dreamcat4@gmail.com"
     gem.homepage = "http://github.com/dreamcat4/libxml-bindings"
     gem.authors = ["dreamcat4"]
+    gem.add_dependency("libxml-ruby", ">= 1.1.3")
 
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
@@ -36,7 +37,6 @@ rescue LoadError
   end
 end
 
-
 task :default => :test
 
 require 'rake/rdoctask'
@@ -47,7 +47,12 @@ Rake::RDocTask.new do |rdoc|
   else
     version = ""
   end
-
+  # rdoc --help --webcvs, -W url
+  # github_blob_url = "<%= github_url %>/blob/v#{version}/%s"
+  # github_raw_url = "<%= github_url %>/raw/v#{version}/%s"
+  # github_blob_url = "http://github.com/dreamcat4/libxml-bindings/blob/v#{version}/%s"
+  # github_raw_url = "http://github.com/dreamcat4/libxml-bindings/raw/v#{version}/%s"
+  # rdoc.options = ["--webcvs", "#{github_blob_url}"]
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "libxml-bindings #{version}"
   rdoc.rdoc_files.include('README*')

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 1
-:patch: 4
+:patch: 0
 :major: 0
+:minor: 2

data/lib/libxml_bindings.rb

@@ -1,88 +1,229 @@
 require "xml/libxml"
 
-class XML::Node
-  ##
-  # Open up XML::Node from libxml and add convenience methods inspired
-  # by hpricot.
-  # (http://code.whytheluckystiff.net/hpricot/wiki/HpricotBasics)
-  # Also:
-  #  * provide better handling of default namespaces
-  # an array of default namespaces to past into
-  attr_accessor :default_namespaces
-  
-  # find the child node with the given xpath
-  def at(xpath)
-    self.find_first(xpath)
-  end
+class Module #:nodoc:
+  alias_method :method_alias, :alias_method
+end
+
+module LibxmlBindings #:nodoc:
+
+  module XML #:nodoc:
+    module Document
+
+      # :call-seq:
+      #   doc.last = node -> XML::Node
+      #
+      # Appends +node+ to the end of the list of nodes at this level
+      def last=(node)
+        self.last? ? self.root.sibling=node : self.root = node
+      end
+
+      # :call-seq:
+      #   doc.node["/xpath"] -> XML::Node
+      #
+      # Returns the first Node object matching +"/xpath"+, or +nil+ if no object could not be found.
+      # 
+      # *Note* its usually recommended to remove all namespaces with strip! before xpath traversal.
+      def node()
+        self.root.node()
+      end
+
+      def node_at(xpath) #:nodoc:
+        self.root.node_at(xpath)
+      end
+
+      # :call-seq:
+      #   doc.nodes["/xpath"] -> [XML::Node, XML::Node, XML::Node, ...]
+      #
+      # Returns an array containing all nodes matching +"/xpath"+, or +nil+ if no object could not be found.
+      # 
+      # *Note* its usually recommended to remove all namespaces with strip! before xpath traversal.
+      def nodes()
+        self.root.nodes()
+      end
+
+      def nodes_at(xpath) #:nodoc:
+        self.root.search(xpath)
+      end
+    
+      # :call-seq:
+      #   doc.strip! -> XML::Document
+      #   doc.strip_namespaces! -> XML::Document
+      #
+      # Strip all namespaces from this XML::Document.
+      # replaces the root node with a stripped XML::Node (and children)
+      # 
+      # *Note* Xml elements with a namespace context are usually omited from xpath search criteria. 
+      #  
+      # See: http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/XPath.html
+      def strip!
+        # Parse xml
+        xml_str = self.to_s
+        # puts "xml_str=#{xml_str}\\n"
+        xml_str.gsub! /\ ?(soap|xmlns)(:\w*)?=\"[^\"]*\"/, ""
+        xml_str.gsub! /\<\w*:/, "<"
+        xml_str.gsub! /\<\/\w*:/, "</"
+        # puts "xml_str=#{xml_str}\\n"
+        xml_doc_stripped = xml_str.to_xmldoc
+        self.root = xml_doc_stripped.root.copy(true)
+        return self
+      end
+      alias_method :strip_namespaces!, :strip!
 
-  # find the array of child nodes matching the given xpath
-  def search(xpath)
-    results = self.find(xpath).to_a
-    if block_given?
-      results.each do |result|
-        yield result
+      # :call-seq:
+      #   doc.to_xml -> String
+      # 
+      # Alias for XML::Document.to_s[http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Document.html#M000458]
+      def to_xml
+        return self.to_s
       end
+      # alias_method :to_xml, :to_s
+
     end
-    return results
-  end
 
-  # alias for search
-  def /(xpath)
-    search(xpath)
-  end
-  # return the inner contents of this node as a string
-  def inner_xml
-    child.to_s
-  end
-  
-  # alias for inner_xml
-  def inner_html
-    inner_xml
-  end
-  
-  # return this node and its contents as an xml string
-  def to_xml
-    self.to_s
-  end
+    module Node
+    
+      class SearchNodes #:nodoc:
+        def initialize(options)
+          @node = options[:node]
+          @return_many = options[:return_many]
+        end
+        def [](args)
+          @return_many ? @node.nodes_at(args) : @node.node_at(args)
+        end
+      end
 
-  # alias for path
-  def xpath
-    self.path
-  end
-  
-  # provide a name for the default namespace
-  def register_default_namespace(name)
-    self.namespace.each do |n|
-      if n.to_s == nil
-        register_namespace("#{name}:#{n.href}")
-        return
+      # :call-seq:
+      #   self.inner_html -> String
+      # 
+      # Alias for XML::Node.inner_xml[http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Node.html#M000188]
+      def inner_html
+        self.inner_xml
+      end
+      # alias_method :inner_html, :inner_xml
+
+      # :call-seq:
+      #   self.last = XML::Node -> XML::Node
+      # 
+      # Alias for XML::Node.sibling=[http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Node.html#M000223]
+      def last=(node)
+        return self.sibling = node
+      end
+      # alias_method :last=, :sibling=
+        
+      # :call-seq:
+      #   self.node["/xpath"] -> XML::Node
+      #
+      # Returns the first Node object matching +"/xpath"+, or +nil+ if no object could not be found.
+      # The path searched is relative to the node from which node[] was called.
+      # 
+      # *Note* its usually recommended to remove all namespaces with strip! before xpath traversal.
+      def node()
+        return SearchNodes.new(:node => self, :return_many => false)
       end
+    
+      def node_at(xpath) #:nodoc:
+        self.find_first(xpath)
+      end
+
+      # :call-seq:
+      #   self.nodes["/xpath"] -> [XML::Node, XML::Node, XML::Node, ...]
+      #
+      # Returns an array containing all nodes matching +"/xpath"+, or +nil+ if no object could not be found.
+      # The path searched is relative to the node from which node[] was called.
+      # 
+      # *Note* its usually recommended to remove all namespaces with strip! before xpath traversal.
+      def nodes()
+        return SearchNodes.new(:node => self, :return_many => true)
+      end
+    
+      def nodes_at(xpath) #:nodoc:
+        results = self.find(xpath).to_a
+        if block_given?
+          results.each do |result|
+            yield result
+          end
+        end
+        return results
+      end
+
+      # # :call-seq:
+      # #   self.replace!(other_node) -> XML::Node
+      # # 
+      # # Replaces the current XML::Node with +other_node+.
+      # # remove! is called on self, and it's handle will become lost.
+      # def replace!(other_node)
+      #   node_node_parent = parent if parent?
+      #   new_node_doc = self.doc if ! parent?
+      #   self.remove!
+      #   doc.root = other_node if new_node_doc
+      #   parent << other_node if parent
+      #   return other_node
+      # end
+    
+      # # :call-seq:
+      # #   self.strip! -> XML::Node
+      # #   self.strip_namespaces! -> XML::Node
+      # #
+      # # Strip namespaces from this XML::Node and all its children.
+      # # replaces this XML::Node with the stripped XML::Node (and children)
+      # # 
+      # # *Note* Xml elements with a namespace context are usually omited from xpath search criteria. 
+      # #  
+      # # See: http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/XPath.html
+      # def strip!
+      #   # Parse xml
+      #   xml_str = self.to_s
+      #   # puts "xml_str=#{xml_str}\\n"
+      #   xml_str.gsub! /\ ?(soap|xmlns)(:\w*)?=\"[^\"]*\"/, ""
+      #   xml_str.gsub! /\<\w*:/, "<"
+      #   xml_str.gsub! /\<\/\w*:/, "</"
+      #   # puts "xml_str=#{xml_str}\\n"
+      #   xml_node_stripped = xml_str.to_xmldoc
+      #   new_node = xml_doc_stripped.root.copy(true)
+      #   self.replace new_node
+      #   return new_node
+      # end
+      # 
+      # alias_method :strip_namespaces!, :strip!
+
+      # :call-seq:
+      #   self.to_xml -> String
+      # 
+      # Alias for XML::Node.to_s[http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Node.html#M000216]
+      def to_xml
+        return self.to_s
+      end
+      # alias_method :to_xml, :to_s
+    
     end
-    raise "No default namespace found"
-  end
-  
-  # register a namespace, of the form "foo:http://example.com/ns"
-  def register_namespace(name_and_href)
-    (@default_namespaces ||= []) <<name_and_href
   end
   
-  def find_with_default_ns(xpath_expr, namespace=nil)
-    find_base(xpath_expr, namespace || default_namespaces)
-  end
-  
-  def find_first_with_default_ns(xpath_expr, namespace=nil)
-    find_first_base(xpath_expr, namespace || default_namespaces)
+  module String    
+    # :call-seq:
+    #   str.to_xmldoc -> XML::Document
+    #
+    # Returns an XML Document object, or +nil+ if str could not be parsed as valid xml.
+    # 
+    # The resulting libxml instance can be parsed, manipulated, and converted back to a string.
+    def to_xmldoc
+      return XML::Parser.string(self).parse
+    end
   end
   
-  alias_method :find_base, :find unless method_defined?(:find_base)
-  alias_method :find, :find_with_default_ns
-  alias_method :find_first_base, :find_first unless method_defined?(:find_first_base)
-  alias_method :find_first, :find_first_with_default_ns
-
 end
 
-class String
-  def to_libxml_doc
-    return XML::Parser.string(self).parse
+# Mix into the standard ruby classes
+module LibXML
+  module XML #:nodoc:
+    class Document #:nodoc:
+      include LibxmlBindings::XML::Document
+    end
+
+    class Node #:nodoc:
+      include LibxmlBindings::XML::Node  
+    end
   end
 end
+class String #:nodoc:
+  include LibxmlBindings::String
+end

data/test/test_helper.rb

@@ -1,10 +1,39 @@
 require 'rubygems'
 require 'test/unit'
 require 'shoulda'
+# require 'woulda'
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'libxml_bindings'
 
 class Test::Unit::TestCase
+
+
+  def self.obj(object, &block)
+    context "#{object.class} #{object.to_s}" do
+      setup do
+        @obj = object
+      end
+
+      context '' do
+        yield
+      end
+    end
+  end
+
+  def self.should_include(*m)
+    a = [m] if m.class == Symbol
+    a = m if m.class == Array && m.first.class == Symbol
+    raise "Requires a symbol, or array of symbols" if a.nil?
+    a.each do |sym|
+      should "include #{sym}" do
+        # puts @obj
+        # puts @obj.class
+        assert @obj.include? sym.to_s
+      end
+    end
+  end
+  
 end
+

data/test/test_libxml_bindings.rb

@@ -0,0 +1,38 @@
+require 'test_helper'
+
+class TestLibxmlBindings < Test::Unit::TestCase
+  
+  should "check that libxml-bindings classes are loaded" do
+    assert LibxmlBindings::XmlDocument
+    assert LibxmlBindings::XmlNode
+    assert LibxmlBindings::String
+  end
+  
+  should "check that modules are included" do
+    assert LibXML::XML::Document.included_modules.include? LibxmlBindings::XML::Document
+    assert LibXML::XML::Node.included_modules.include? LibxmlBindings::XML::Node
+    assert String.included_modules.include? LibxmlBindings::String
+  end
+  
+  obj LibxmlBindings::XmlDocument::instance_methods do 
+    should_include :node, :nodes # xml readers
+    should_include :strip!, :last= # xml modifiers
+    should_include :to_xml # xml outputters
+  end
+
+  obj LibxmlBindings::XmlNode::instance_methods do 
+    should_include :node, :nodes # xml readers
+    should_include :strip!, :last=, :replace! # xml modifiers
+    should_include :to_xml, :inner_html # xml outputters
+  end
+
+  obj LibxmlBindings::XmlNode::SearchNodes::instance_methods do 
+    should_include :[] # xml readers
+  end
+  
+  obj LibxmlBindings::String::instance_methods do 
+    should_include :to_xmldoc
+  end
+  
+end
+

data/test/test_xml_modifiers.rb

@@ -0,0 +1,57 @@
+require 'test_helper'
+
+class TestXmlModifiers < Test::Unit::TestCase
+  context "A namespaced document" do
+    setup do
+      # choose xml file
+      # xml_file = "namespaces.xml"
+      # xml_file = "rss1.xml"
+      # xml_file = "rubynet.xml"
+      # xml_file = "shiporder.xml"
+      xml_file = "soap_manufacturer_names_response.xml"
+      # xml_file = "soap_create_reservation_response.xml"
+      
+      # Load xml file
+      xml_file = File.join(File.dirname(__FILE__), "xml", xml_file)
+      assert ! xml_file.nil?
+
+      # doc_str = File.open( xml_file, "rb").read
+      # @doc = doc_str.to_xmldoc
+      @doc = XML::Document.file xml_file
+      assert ! @doc.nil?
+      
+      # Remove namespaces
+      @doc.strip!
+    end
+
+    should "strip all namespaces from a document" do
+      assert ! @doc.strip!.nil?
+    end
+  end
+  
+  context "a partially namespaced document" do
+    setup do
+      # Insert the root node of a namespaced document into a stripped document
+    end
+    
+    # should "replace a node within a document" do
+    #   assert ! @doc.strip!.nil?
+    # end
+
+    # should "replace a node which is the root node of the document" do
+    #   assert ! @doc.strip!.nil?
+    # end
+  end
+    
+  context "a stripped document" do
+    
+    should "strip all namespaces from a node" do
+      @doc.node["/"]
+      assert ! @node.strip!.nil?
+    end
+    
+  end
+
+end
+
+

data/test/test_xml_outputters.rb

@@ -0,0 +1,53 @@
+require 'test_helper'
+
+class TestXmlOutputters < Test::Unit::TestCase
+  context "A namespaced xml document" do
+    setup do
+      # xml_file = "rss1.xml"
+      xml_file = "ruby_lang.xhtml"
+      
+      # Load xml file
+      xml_file = File.join(File.dirname(__FILE__), "xml", xml_file)
+      assert ! xml_file.nil?
+
+      @doc = XML::Document.file xml_file
+      assert ! @doc.nil?
+      
+      @doc.strip! # Remove any namespaces
+
+      @paths=[
+        "/html/body/div[@id='page']"
+        "/html/body//div[@id='intro']"
+        ]
+      
+      @replacement_node = XML::Node.new("NameString","ContentString")
+    end
+
+    should "return the inner html of a valid xhtml node" do
+      @paths.each do |path|
+        inner_html = @doc.node[path].inner_html 
+        inner_xml = @doc.node[path].inner_xml
+        
+        assert ! inner_html.nil?
+        assert inner_html == inner_xml
+      end
+    end
+    
+    should "return an xml string of the node" do
+      @paths.each do |path|
+        xml_string = @doc.node[path].to_xml
+        s = @doc.node[path].to_s
+        assert ! xml_string.nil?
+        assert xml_string == s
+      end
+    end
+        
+    should "return an xml string of the document" do
+        xml_string = @doc.to_xml
+        s = @doc.to_s
+        assert ! xml_string.nil?
+        assert xml_string == s
+    end
+        
+  end
+end