libxml4r 0.0.0 → 0.2.6

data/.autotest

@@ -0,0 +1,30 @@
+# -*- ruby -*-
+
+Autotest.add_hook :initialize do |at|
+	at.clear_mappings # Do not remove this line
+	
+	# Put your additional test files here
+	extra_mappings_pfx = "test/"
+	extra_mappings = {
+		"libxml4r.rb" => [
+		  "test_xml_readers.rb",
+		  "test_xml_modifiers.rb",
+		  "test_xml_outputters.rb"]
+	}
+	
+	# Do not edit below these lines
+	
+	at.add_mapping /^lib\/.*\.rb$/ do |f, _|
+		m=f.gsub /.*\//, "" # Strip leading path from #{f}
+		a=extra_mappings["#{m}"]
+		a.nil? ? a=[] : a=a.map {|e| extra_mappings_pfx+e} 
+		# at.files_matching(/test\/test_#{m}$/) + a
+		["test/test_#{m}"] + a
+	end
+
+	at.add_mapping /^test\/test.*\.rb$/ do |f, _|		
+		at.files_matching(/#{f}/)
+	end
+	
+end
+

data/README.rdoc

@@ -1,17 +1,121 @@
 = libxml4r
 
-Description goes here.
+{libxml4r}[http://github.com/dreamcat4/libxml4r/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.
 
-== Note on Patches/Pull Requests
+For a full list of methods, please refer to the {RDoc Documentation}[http://rdoc.info/projects/dreamcat4/libxml4r] 
+and also the {Libxml-Ruby RDocs}[http://libxml.rubyforge.org/rdoc/]
+
+For benkchmarks / performance comparison see http://cfis.savagexi.com/2008/07/16/resurrecting-libxml-ruby
+
+== Installation
+
+	gem sources -a http://gemcutter.org
+	gem install libxml4r
+
+== 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>'
+	>> doc = s.to_xmldoc
+
+The +node["/xpath"]+ method returns the first Node matching the given {xpath}[http://www.w3schools.com/XPath/xpath_syntax.asp]
+
+	>> doc.node["author"]
+	=> <author>p. bogle</author>
+
+The +nodes["/xpath"]+ method returns an array of Nodes matching the given {xpath}[http://www.w3schools.com/XPath/xpath_syntax.asp]
+
+	>> doc.nodes["/foo/bar"]
+	=> [<bar>content</bar>, <bar>content2</bar>]
+
++nodes[]+ can be called with a block to iterate through each of the matching nodes
+
+	>>  doc.nodes["bar"] do |bar| puts bar.xpath; end
+	/foo/bar[1]
+	/foo/bar[2]
+
+You can call +node[]+ on another node to iterate and search within a smaller context of the document
+
+	>> 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
+
+== Removing the whitespace nodes amongst our data nodes
+
+	::LibXML::XML.default_keep_blanks = false
+
+Put this line at the beginning, before parsing the xml document. Othewise libxml interpolates all the 'real' data nodes with string nodes of the whitespace found between them. So `node.next` will point to the next *data* node, and not something like `"\n      "`. This is the "right" thing to do, whenever expecting to walk along or iterate over the parsed doc tree.
+
+== Namespace Stripping
+
+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/"
+	        xmlns:gContact="http://schemas.google.com/contact/2008\"
+	        xmlns:gd="http://schemas.google.com/g/2005">
+	  <title type=\"text\">Phil Bogle's Contacts</title>
+	   ...
+	</feed>
+
+With libxml4r 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
+
+	>> 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.
+
+== A Complete example
+
+Here we combine our usage of both the `libxml-ruby`, and `libxml4r` functions, which results in much smaller and more compact code. Its just a case of using the right tool for the right job.
+
+	::LibXML::XML.default_keep_blanks = false
+	@string = File.read(@launchd_plist)
+	@doc = @string.to_xmldoc.strip!
+	@doc = doc.node["/plist/dict"]
+	@nodes_plist_keys = @doc.nodes["key"]
+	@plist_keys_values = @nodes_xml_keys.collect {|n| [n.inner_xml, n.next] }
+
+== Final words
+
+Its well worth it spending some time to understand the libxml-ruby api and xpath. Its well worth it to go back and revisit all of the links dotted around this page. Those documentation are absoloutely invaluable. 100% the best.
+
+== Notes on Patches/Pull Requests
  
-* Fork the project.
+* Fork the project, and create a topic branch as per {these instructions}[http://wiki.opscode.com/display/opscode/Working+with+Git].
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Include documentation for it.
+* Include a regression test for it. So I don't break it in a future version unintentionally.
 
 == Copyright
 
-Copyright (c) 2010 dreamcat4. 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. Some coding examples here are also adapted from Phil's original explanatory texts.
+
+Copyright (c) 2008 Phil Bogle.
+Copyright (c) 2009-2010 Dreamcat4.

data/Rakefile

@@ -6,10 +6,11 @@ begin
   Jeweler::Tasks.new do |gem|
     gem.name = "libxml4r"
     gem.summary = %Q{Libxml4r provides convenience methods around the core libxml-ruby classes.}
-    gem.description = %Q{Libxml4r is a light set of methods and bolt-ons which aren't maintained by the core libxml ruby library. These methods aim to provide a more easy to use xml API. All libxml4r methods are mixed into the original LibXML::classes. (This gem was previously called libxml-bindings).}
+    gem.description = %Q{Libxml4r is a light set of methods and bolt-ons which aren't maintained by the core libxml ruby library. These methods aim to provide a more easy to use xml API. All libxml4r methods are mixed into the original LibXML::classes. (This gem was previously called libxml4r).}
     gem.email = "dreamcat4@gmail.com"
     gem.homepage = "http://github.com/dreamcat4/libxml4r"
     gem.authors = ["dreamcat4"]
+    gem.add_dependency("libxml-ruby", ">= 1.1.3")
     gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
     gem.add_development_dependency "yard", ">= 0"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.2.6

data/lib/libxml4r.rb

@@ -0,0 +1,229 @@
+require "xml/libxml"
+
+class Module #:nodoc:
+  alias_method :method_alias, :alias_method
+end
+
+module Libxml4r #: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!
+
+      # :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
+
+    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
+
+      # :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
+  end
+  
+  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
+  
+end
+
+# Mix into the standard ruby classes
+module LibXML
+  module XML #:nodoc:
+    class Document #:nodoc:
+      include ::Libxml4r::XML::Document
+    end
+
+    class Node #:nodoc:
+      include ::Libxml4r::XML::Node
+    end
+  end
+end
+class String #:nodoc:
+  include ::Libxml4r::String
+end

data/libxml4r.gemspec

@@ -0,0 +1,98 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{libxml4r}
+  s.version = "0.2.6"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["dreamcat4"]
+  s.date = %q{2010-03-09}
+  s.description = %q{Libxml4r is a light set of methods and bolt-ons which aren't maintained by the core libxml ruby library. These methods aim to provide a more easy to use xml API. All libxml4r methods are mixed into the original LibXML::classes. (This gem was previously called libxml4r).}
+  s.email = %q{dreamcat4@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".autotest",
+     ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/libxml4r.rb",
+     "libxml4r.gemspec",
+     "test/helper.rb",
+     "test/test_helper.rb",
+     "test/test_libxml4r.rb",
+     "test/test_xml_modifiers.rb",
+     "test/test_xml_outputters.rb",
+     "test/test_xml_readers.rb",
+     "test/xml/atom.xml",
+     "test/xml/books.xml",
+     "test/xml/breakfast_menu.xml",
+     "test/xml/document.xml",
+     "test/xml/merge_bug_data.xml",
+     "test/xml/namespaces.xml",
+     "test/xml/parts_system.xml",
+     "test/xml/plant_catalog.xml",
+     "test/xml/recipie.xml",
+     "test/xml/rss1.xml",
+     "test/xml/rss2.xml",
+     "test/xml/ruby_lang.xhtml",
+     "test/xml/rubynet.xml",
+     "test/xml/shiporder.xls",
+     "test/xml/shiporder.xml",
+     "test/xml/shiporder.xsd",
+     "test/xml/soap_create_path.xml",
+     "test/xml/soap_create_path_response.xml",
+     "test/xml/soap_create_reservation.xml",
+     "test/xml/soap_create_reservation_response.xml",
+     "test/xml/soap_get_price.xml",
+     "test/xml/soap_get_price_response.xml",
+     "test/xml/soap_manufacturer_names_response.xml",
+     "test/xml/soap_order_item.xml",
+     "test/xml/soap_order_item_response.xml",
+     "test/xml/soap_refresh_path.xml",
+     "test/xml/soap_refresh_path_response.xml",
+     "test/xml/soap_teardown_path.xml",
+     "test/xml/soap_teardown_path_response.xml"
+  ]
+  s.homepage = %q{http://github.com/dreamcat4/libxml4r}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Libxml4r provides convenience methods around the core libxml-ruby classes.}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_helper.rb",
+     "test/test_libxml4r.rb",
+     "test/test_xml_modifiers.rb",
+     "test/test_xml_outputters.rb",
+     "test/test_xml_readers.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<libxml-ruby>, [">= 1.1.3"])
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<libxml-ruby>, [">= 1.1.3"])
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<libxml-ruby>, [">= 1.1.3"])
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end
+