multi_xml 0.0.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+group :development, :test do
+  gem 'hpricot', "~> 0.8.2", :require => nil
+  gem 'libxml-ruby', "~> 1.1.4", :require => nil
+  gem 'nokogiri', "~> 1.4.3", :require => nil
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: .
+  specs:
+    multi_xml (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    hpricot (0.8.2)
+    libxml-ruby (1.1.4)
+    nokogiri (1.4.3.1)
+    rake (0.8.7)
+    rspec (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.2)
+  hpricot (~> 0.8.2)
+  libxml-ruby (~> 1.1.4)
+  multi_xml!
+  nokogiri (~> 1.4.3)
+  rake (~> 0.8.7)
+  rspec (~> 1.3.0)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Erik Michaels-Ober
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,32 @@
+= MultiXML
+
+Lots of Ruby libraries utilize XML parsing in some form, and everyone has their favorite XML library. In order to best support multiple XML parsers and libraries, <tt>multi_xml</tt> is a general-purpose swappable XML backend library. You use it like so:
+
+  require 'multi_xml'
+  
+  MultiXml.engine = :nokogiri
+  MultiXml.parse('<tag>This is the contents</tag>') # parsed using Nokogiri
+  
+  MultiXml.engine = :rexml
+  MultiXml.engine = MultiJson::Engines::Rexml # equivalent to previous line
+  MultiXml.parse('<tag>This is the contents</tag>') # parsed using REXML
+
+The <tt>engine</tt> setter takes either a symbol or a class (to allow for custom XML parsers) that responds to <tt>.parse</tt> at the class level.
+
+MultiXML tries to have intelligent defaulting. That is, if you have any of the supported engines already loaded, it will utilize them before attempting to load any. When loading, libraries are ordered by speed. First LibXML, then Nokogiri, then Hpricot, then REXML.
+
+== Inspriation
+
+MultiXML was inspired by MultiJSON[http://github.com/intridea/multi_json/].
+
+== Submitting Patches
+
+1. Fork the project.
+2. Commit your feature or bug fix.
+3. Add tests for it. This is important so it doesn't break in the future.
+4. Do not mess with gemspec, version, or history. (If you want to have your own version, that's fine, but please do so in a separate commit.)
+5. Submit a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Erik Michaels-Ober. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,28 @@
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+Bundler::GemHelper.install_tasks
+
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "multi_xml #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec

data/lib/multi_xml.rb

@@ -0,0 +1,65 @@
+module MultiXml
+  module_function
+
+  # Get the current engine class.
+  def engine
+    return @engine if @engine
+    self.engine = self.default_engine
+    @engine
+  end
+
+  REQUIREMENT_MAP = [
+    ['libxml', :libxml],
+    ['nokogiri', :nokogiri],
+    ['hpricot', :hpricot],
+    ['rexml/document', :rexml]
+  ]
+
+  # The default engine based on what you currently
+  # have loaded and installed. First checks to see
+  # if any engines are already loaded, then checks
+  # to see which are installed if none are loaded.
+  def default_engine
+    return :libxml if defined?(::LibXML)
+    return :nokogiri if defined?(::Nokogiri)
+    return :hpricot if defined?(::Hpricot)
+
+    REQUIREMENT_MAP.each do |(library, engine)|
+      begin
+        require library
+        return engine
+      rescue LoadError
+        next
+      end
+    end
+  end
+
+  # Set the XML parser utilizing a symbol, string, or class.
+  # Supported by default are:
+  #
+  # * <tt>:libxml</tt>
+  # * <tt>:nokogiri</tt>
+  # * <tt>:hpricot</tt>
+  # * <tt>:rexml</tt>
+  def engine=(new_engine)
+    case new_engine
+      when String, Symbol
+        require "multi_xml/engines/#{new_engine}"
+        @engine = MultiXml::Engines.const_get("#{new_engine.to_s.split('_').map{|s| s.capitalize}.join('')}")
+      when Class
+        @engine = new_engine
+      else
+        raise "Did not recognize your engine specification. Please specify either a symbol or a class."
+    end
+  end
+
+  # Parse a XML string into Ruby.
+  #
+  # <b>Options</b>
+  #
+  # <tt>:symbolize_keys</tt> :: If true, will use symbols instead of strings for the keys.
+  def parse(string, options = {})
+    engine.parse(string, options)
+  end
+
+end

data/lib/multi_xml/engines/rexml.rb

@@ -0,0 +1,221 @@
+require 'rexml/parsers/baseparser'
+require 'rexml/text'
+require 'date'
+require 'time'
+require 'yaml'
+require 'bigdecimal'
+
+module MultiXml
+  module Engines
+    # Use REXML to parse XML.
+    class Rexml
+
+      def self.parse(string, options = {}) #:nodoc:
+        string.strip!
+        stack = []
+        parser = ::REXML::Parsers::BaseParser.new(string)
+
+        while true
+          event = parser.pull
+          case event[0]
+          when :end_document
+            break
+          when :start_element
+            stack.push RexmlUtilityNode.new(event[1], event[2])
+          when :end_element
+            if stack.size > 1
+              temp = stack.pop
+              stack.last.add_node(temp)
+            end
+          when :text, :cdata
+            stack.last.add_node(event[1]) unless event[1].strip.length == 0 || stack.empty?
+          end
+        end
+        hash = (stack.length > 0 ? stack.pop.to_hash : {})
+        options[:symbolize_keys] ? symbolize_keys(hash) : hash
+      end
+
+      def self.symbolize_keys(hash) #:nodoc:
+        hash.inject({}){|result, (key, value)|
+          new_key = case key
+                    when String then key.to_sym
+                    else key
+                    end
+          new_value = case value
+                      when Hash then symbolize_keys(value)
+                      else value
+                      end
+          result[new_key] = new_value
+          result
+        }
+      end
+    end
+
+    class RexmlUtilityNode #:nodoc:
+      attr_accessor :name, :attributes, :children, :type
+
+      def self.typecasts
+        @@typecasts
+      end
+
+      def self.typecasts=(obj)
+        @@typecasts = obj
+      end
+
+      def self.available_typecasts
+        @@available_typecasts
+      end
+
+      def self.available_typecasts=(obj)
+        @@available_typecasts = obj
+      end
+
+      self.typecasts = {}
+      self.typecasts["integer"]       = lambda{|v| v.nil? ? nil : v.to_i}
+      self.typecasts["boolean"]       = lambda{|v| v.nil? ? nil : (v.strip != "false")}
+      self.typecasts["datetime"]      = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
+      self.typecasts["date"]          = lambda{|v| v.nil? ? nil : Date.parse(v)}
+      self.typecasts["dateTime"]      = lambda{|v| v.nil? ? nil : Time.parse(v).utc}
+      self.typecasts["decimal"]       = lambda{|v| v.nil? ? nil : BigDecimal(v.to_s)}
+      self.typecasts["double"]        = lambda{|v| v.nil? ? nil : v.to_f}
+      self.typecasts["float"]         = lambda{|v| v.nil? ? nil : v.to_f}
+      self.typecasts["symbol"]        = lambda{|v| v.nil? ? nil : v.to_sym}
+      self.typecasts["string"]        = lambda{|v| v.to_s}
+      self.typecasts["yaml"]          = lambda{|v| v.nil? ? nil : YAML.load(v)}
+      self.typecasts["base64Binary"]  = lambda{|v| v.unpack('m').first }
+
+      self.available_typecasts = self.typecasts.keys
+
+      def initialize(name, normalized_attributes = {})
+        
+        # unnormalize attribute values
+        attributes = Hash[* normalized_attributes.map { |key, value|
+          [ key, unnormalize_xml_entities(value) ]
+        }.flatten]
+        
+        @name         = name.tr("-", "_")
+        # leave the type alone if we don't know what it is
+        @type         = self.class.available_typecasts.include?(attributes["type"]) ? attributes.delete("type") : attributes["type"]
+
+        @nil_element  = attributes.delete("nil") == "true"
+        @attributes   = undasherize_keys(attributes)
+        @children     = []
+        @text         = false
+      end
+
+      def add_node(node)
+        @text = true if node.is_a? String
+        @children << node
+      end
+
+      def to_hash
+        if @type == "file"
+          f = StringIO.new((@children.first || '').unpack('m').first)
+          class << f
+            attr_accessor :original_filename, :content_type
+          end
+          f.original_filename = attributes['name'] || 'untitled'
+          f.content_type = attributes['content_type'] || 'application/octet-stream'
+          return {name => f}
+        end
+
+        if @text
+          t = typecast_value( unnormalize_xml_entities( inner_html ) )
+          t.class.send(:attr_accessor, :attributes)
+          t.attributes = attributes
+          return { name => t }
+        else
+          #change repeating groups into an array
+          groups = @children.inject({}) { |s,e| (s[e.name] ||= []) << e; s }
+
+          out = nil
+          if @type == "array"
+            out = []
+            groups.each do |k, v|
+              if v.size == 1
+                out << v.first.to_hash.entries.first.last
+              else
+                out << v.map{|e| e.to_hash[k]}
+              end
+            end
+            out = out.flatten
+
+          else # If Hash
+            out = {}
+            groups.each do |k,v|
+              if v.size == 1
+                out.merge!(v.first)
+              else
+                out.merge!( k => v.map{|e| e.to_hash[k]})
+              end
+            end
+            out.merge! attributes unless attributes.empty?
+            out = out.empty? ? nil : out
+          end
+
+          if @type && out.nil?
+            { name => typecast_value(out) }
+          else
+            { name => out }
+          end
+        end
+      end
+
+      # Typecasts a value based upon its type. For instance, if
+      # +node+ has #type == "integer",
+      # {{[node.typecast_value("12") #=> 12]}}
+      #
+      # @param value<String> The value that is being typecast.
+      #
+      # @details [:type options]
+      #   "integer"::
+      #     converts +value+ to an integer with #to_i
+      #   "boolean"::
+      #     checks whether +value+, after removing spaces, is the literal
+      #     "true"
+      #   "datetime"::
+      #     Parses +value+ using Time.parse, and returns a UTC Time
+      #   "date"::
+      #     Parses +value+ using Date.parse
+      #
+      # @return <Integer, TrueClass, FalseClass, Time, Date, Object>
+      #   The result of typecasting +value+.
+      #
+      # @note
+      #   If +self+ does not have a "type" key, or if it's not one of the
+      #   options specified above, the raw +value+ will be returned.
+      def typecast_value(value)
+        return value unless @type
+        proc = self.class.typecasts[@type]
+        proc.nil? ? value : proc.call(value)
+      end
+
+      # Take keys of the form foo-bar and convert them to foo_bar
+      def undasherize_keys(params)
+        params.keys.each do |key, value|
+          params[key.tr("-", "_")] = params.delete(key)
+        end
+        params
+      end
+
+      # Get the inner_html of the REXML node.
+      def inner_html
+        @children.join
+      end
+
+      # Converts the node into a readable HTML node.
+      #
+      # @return <String> The HTML node in text form.
+      def to_html
+        attributes.merge!(:type => @type ) if @type
+        "<#{name}#{attributes.to_xml_attributes}>#{@nil_element ? '' : inner_html}</#{name}>"
+      end
+      alias :to_s :to_html
+
+      def unnormalize_xml_entities value
+        ::REXML::Text.unnormalize(value)
+      end
+    end
+
+  end
+end

data/lib/multi_xml/version.rb

@@ -0,0 +1,3 @@
+module MultiXml
+  VERSION = "0.0.1"
+end

data/multi_xml.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "multi_xml/version"
+
+Gem::Specification.new do |s|
+  s.add_development_dependency("bundler", ["~> 1.0.2"])
+  s.add_development_dependency("hpricot", ["~> 0.8.2"])
+  s.add_development_dependency("libxml-ruby", ["~> 1.1.4"])
+  s.add_development_dependency("nokogiri", ["~> 1.4.3"])
+  s.add_development_dependency("rake", ["~> 0.8.7"])
+  s.add_development_dependency("rspec", ["~> 1.3.0"])
+  s.name        = "multi_xml"
+  s.version     = MultiXml::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Erik Michaels-Ober"]
+  s.email       = ["sferik@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/multi_xml"
+  s.summary     = %q{A gem to provide swappable XML backends utilizing LibXML, Nokogiri, Hpricot, or REXML.}
+  s.description = s.summary
+  s.rubyforge_project = "multi_xml"
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/spec/multi_xml_spec.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class MockDecoder
+  def self.parse(string)
+    '<tag>This is the contents</tag>'
+  end
+end
+
+describe "MultiXml" do
+  context 'engines' do
+    it 'should default to the best available gem' do
+      pending
+      require 'libxml'
+      MultiXml.engine.name.should == 'MultiXml::Engines::Libxml'
+    end
+
+    it 'should be settable via a symbol' do
+      pending
+      MultiXml.engine = :libxml
+      MultiXml.engine.name.should == 'MultiXml::Engines::Libxml'
+    end
+
+    it 'should be settable via a class' do
+      MultiXml.engine = MockDecoder
+      MultiXml.engine.name.should == 'MockDecoder'
+    end
+  end
+
+  %w(libxml nokogiri hpricot rexml).each do |engine|
+    context engine do
+      before do
+        begin
+          MultiXml.engine = engine
+        rescue LoadError
+          pending "Engine #{engine} couldn't be loaded (not installed?)"
+        end
+      end
+
+      describe '.parse' do
+        it 'should properly parse some XML' do
+          MultiXml.parse('<tag>This is the contents</tag>').should == {'tag' => 'This is the contents'}
+        end
+
+        it 'should allow for symbolization of keys' do
+          MultiXml.parse('<tag>This is the contents</tag>', :symbolize_keys => true).should == {:tag => 'This is the contents'}
+        end
+      end
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format=nested

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'multi_xml'
+require 'spec'
+require 'spec/autorun'
+require 'rubygems'
+begin
+  require 'bundler'
+  Bundler.setup
+rescue LoadError
+  $stderr.puts "Bundler (or a dependency) not available."
+end
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,177 @@
+--- !ruby/object:Gem::Specification 
+name: multi_xml
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Erik Michaels-Ober
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-02 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 0
+        - 2
+        version: 1.0.2
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 59
+        segments: 
+        - 0
+        - 8
+        - 2
+        version: 0.8.2
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: libxml-ruby
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 1
+        - 4
+        version: 1.1.4
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 4
+        - 3
+        version: 1.4.3
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 49
+        segments: 
+        - 0
+        - 8
+        - 7
+        version: 0.8.7
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id006
+description: A gem to provide swappable XML backends utilizing LibXML, Nokogiri, Hpricot, or REXML.
+email: 
+- sferik@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/multi_xml.rb
+- lib/multi_xml/engines/rexml.rb
+- lib/multi_xml/version.rb
+- multi_xml.gemspec
+- spec/multi_xml_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://rubygems.org/gems/multi_xml
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: multi_xml
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A gem to provide swappable XML backends utilizing LibXML, Nokogiri, Hpricot, or REXML.
+test_files: 
+- spec/multi_xml_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb