unhappymapper 0.4.0 → 0.4.1

data/README.md

@@ -1,39 +1,43 @@
-HappyMapper
-===========
+UnhappyMapper
+=============
 
-Happymapper allows you to parse XML data and convert it quickly and easily into ruby data structures.
+UnHappymapper allows you to parse XML data and convert it quickly and easily into ruby data structures.
 
-This project is a grandchild (a fork of a fork) of the great work done first by [jnunemaker](https://github.com/jnunemaker/happymapper) and then by [dam5s](http://github.com/dam5s/happymapper/).
-=======
+This project is a grandchild (a fork of a fork) of the great work done first by [jnunemaker](https://github.com/jnunemaker/happymapper) and then by [dam5s](http://github.com/dam5s/happymapper/). I found both of these projects when I started to work on a project that had a serious case of XML and required a number of bug fixes and also new features. Both of the previous maintainers are too busy or not interested in the new functionality so I have released a new gem.
 
-Installation
-------------
+###Major Differences
+
+  * [dam5s](http://github.com/dam5s/happymapper/)'s fork added [Nokogiri](http://nokogiri.org/) support
+  * `#to_xml` support utilizing the same HappyMapper tags
+  * Fixes for [namespaces when using composition of classes](https://github.com/burtlo/happymapper/commit/fd1e898c70f7289d2d2618d629b56f2f6623785c)
+  * Fixes for instances of XML where a [namespace is defined but no elements with that namespace are found](https://github.com/burtlo/happymapper/commit/9614221a80ff3bda18ff859aa751dff29cf52fd3). 
 
-*Build the gem yourself:*
+
+## Installation
+
+### [Rubygems](https://rubygems.org/gems/unhappymapper)
+
+    $ gem install unhappymapper
+
+### [Source](https://github.com/burtlo/happymapper)
 
     $ git clone https://github.com/burtlo/happymapper
     $ cd happymapper
     $ git checkout master
-    $ gem build nokogiri-happymapper.gemspec
-    $ gem install --local happymapper-X.X.X.gem
+    $ gem build unhappymapper.gemspec
+    $ gem install --local unhappymapper-X.X.X.gem
 
-*For you [Bundler's](http://gembundler.com/) out there, you can add it to your Gemfile and then `bundle install`*
+### [Bundler](http://gembundler.com/)
 
-    gem 'happymapper', :git => "git://github.com/burtlo/happymapper.git"
+Add the unhappymapper gem to your project's `Gemfile`.
 
-Differences
------------
+    gem 'unhappymapper'
 
-  * [dam5s](http://github.com/dam5s/happymapper/)'s fork added [Nokogiri](http://nokogiri.org/) support
-  * `#to_xml` support utilizing the same HappyMapper tags
-  * Fixes for [namespaces when using composition of classes](https://github.com/burtlo/happymapper/commit/fd1e898c70f7289d2d2618d629b56f2f6623785c)
-  * Fixes for instances of XML where a [namespace is defined but no elements with that namespace are found](https://github.com/burtlo/happymapper/commit/9614221a80ff3bda18ff859aa751dff29cf52fd3). 
+Run the bundler command to install the gem:
 
+    $ bundle install
 
-Examples
---------
-
-## Element Mapping
+# Examples
 
 Let's start with a simple example to get our feet wet. Here we have a simple example of XML that defines some address information:
 
@@ -163,6 +167,40 @@ Attributes are absolutely the same as `element` or `has_many`
 Again, you can omit the tag if the attribute accessor symbol matches the name of the attribute.
 
 
+### Attributes On Empty Child Elements
+
+    <feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom">
+      <id>tag:all-the-episodes.heroku.com,2005:/tv_shows</id>
+      <link rel="alternate" type="text/html" href="http://all-the-episodes.heroku.com"/>
+      <link rel="self" type="application/atom+xml" href="http://all-the-episodes.heroku.com/tv_shows.atom"/>
+      <title>TV Shows</title>
+      <updated>2011-07-10T06:52:27Z</updated>
+    </feed>
+
+In this case you would need to map an element to a new `Link` class just to access `<link>`s attributes, except that there is an alternate syntax. Instead of
+
+    class Feed
+      # ....
+      has_many :links, Link, :tag => 'link', :xpath => '.'
+    end
+
+    class Link
+      include HappyMapper
+
+      attribute :rel, String
+      attribute :type, String
+      attribute :href, String
+    end
+
+You can drop the `Link` class and simply replace the `has_many` on `Feed` with
+
+    element :link, String, :single => false, :attributes => { :rel => String, :type => String, :href => String }
+
+As there is no content, the type given for `:link` (`String` above) is irrelevant, but `nil` won't work and other types may try to perform typecasting and fail. You can omit the :single => false for elements that only occur once within their parent.
+
+This syntax is most appropriate for elements that (a) have attributes but no content and (b) only occur at only one level of the heirarchy. If `<feed>` contained another element that also contained a `<link>` (as atom feeds generally do) it would be DRY-er to use the first syntax, i.e. with a separate `Link` class.
+
+
 ## Class composition (and Text Node)
 
 Our address has a country and that country element has a code. Up until this point we neglected it as we declared a `country` as being a `String`.
@@ -247,9 +285,9 @@ You may want to map the sub-elements contained buried in the 'gallery' as top le
     end
 
 
-### Subclasses
+## Subclasses
 
-## Inheritance (it doesn't work!)
+### Inheritance (it doesn't work!)
 
 While mapping XML to objects you may arrive at a point where you have two or more very similar structures.
 
@@ -334,7 +372,8 @@ You can however, use some module mixin power to save you those keystrokes and im
 Here, when we include `Content` in both of these classes the module method `#included` is called and our class is given as a parameter. So we take that opportunity to do some surgery and define our happymapper elements as well as any other methods that may rely on those instance variables that come along in the package.
 
 
-## Subclasses
+## Filtering with XPATH
+
 I ran into a case where I wanted to capture all the pictures that were directly under media, but not the ones contained within a gallery.
 
     <media>
@@ -426,6 +465,16 @@ Well we would need to specify that namespace:
     
 With that we should be able to parse as we once did.
 
+## Large Datasets (in_groups_of)
+
+When dealing with large sets of XML that simply cannot or should not be placed into memory the objects can be handled in groups through the `:in_groups_of` parameter.
+
+    Address.parse(LARGE_ADDRESS_XML_DATA,:in_groups_of => 5) do |group|
+      puts address.streets
+    end
+
+This trivial block will parse the large set of XML data and in groups of 5 addresses at a time display the streets.
+
 ## Saving to XML
 
 Saving a class to XML is as easy as calling `#to_xml`.  The end result will be the current state of your object represented as xml. Let's cover some details that are sometimes necessary and features present to make your life easier.
@@ -476,4 +525,4 @@ While parsing the XML only required you to simply specify the prefix of the name
       element :city, String
       element :country, Country, :tag => 'country', :namespace => 'different'
     
-    end
+    end

data/lib/happymapper.rb

@@ -289,42 +289,79 @@ module HappyMapper
         nodes
       end
 
+      # If the :limit option has been specified then we are going to slice
+      # our node results by that amount to allow us the ability to deal with
+      # a large result set of data.
 
-      collection = nodes.collect do |n|
-        obj = new
+      limit = options[:in_groups_of] || nodes.size
+      
+      # If the limit of 0 has been specified then the user obviously wants
+      # none of the nodes that we are serving within this batch of nodes.
+      
+      return [] if limit == 0
 
-        attributes.each do |attr|
-          obj.send("#{attr.method_name}=",
-          attr.from_xml_node(n, namespace, namespaces))
-        end
+      collection = []
+      
+      nodes.each_slice(limit) do |slice|
+        
+        part = slice.map do |n|
+          obj = new
 
-        elements.each do |elem|
-          obj.send("#{elem.method_name}=",
-          elem.from_xml_node(n, namespace, namespaces))
-        end
+          attributes.each do |attr|
+            obj.send("#{attr.method_name}=",attr.from_xml_node(n, namespace, namespaces))
+          end
+
+          elements.each do |elem|
+            obj.send("#{elem.method_name}=",elem.from_xml_node(n, namespace, namespaces))
+          end
 
-        obj.send("#{@text_node.method_name}=",
-        @text_node.from_xml_node(n, namespace, namespaces)) if @text_node
+          if @text_node
+            obj.send("#{@text_node.method_name}=",@text_node.from_xml_node(n, namespace, namespaces))
+          end
+          
+          # If the HappyMapper class has the method #xml_value=, 
+          # attr_writer :xml_value, or attr_accessor :xml_value then we want to
+          # assign the current xml that we just parsed to the xml_value
         
-        if obj.respond_to?('xml_value=')
-          n.namespaces.each {|name,path| n[name] = path }
-          obj.xml_value = n.to_xml
-          obj.class.class_eval { define_method(:to_xml) { @xml_value } }
-        end
+          if obj.respond_to?('xml_value=')
+            n.namespaces.each {|name,path| n[name] = path }
+            obj.xml_value = n.to_xml
+          end
+          
+          # If the HappyMapper class has the method #xml_content=,
+          # attr_write :xml_content, or attr_accessor :xml_content then we want to
+          # assign the child xml that we just parsed to the xml_content
 
-        if obj.respond_to?('xml_content=')
-          n = n.children if n.respond_to?(:children)
-          obj.xml_content = n.to_xml
+          if obj.respond_to?('xml_content=')
+            n = n.children if n.respond_to?(:children)
+            obj.xml_content = n.to_xml
+          end
+        
+          # collect the object that we have created
+          
+          obj
         end
+        
+        # If a block has been provided and the user has requested that the objects
+        # be handled in groups then we should yield the slice of the objects to them
+        # otherwise continue to lump them together
 
-        obj
+        if block_given? and options[:in_groups_of]
+          yield part
+        else
+          collection += part
+        end
+        
       end
 
       # per http://libxml.rubyforge.org/rdoc/classes/LibXML/XML/Document.html#M000354
       nodes = nil
-      
 
-      if options[:single] || root
+      # If the :single option has been specified or we are at the root element
+      # then we are going to return the first item in the collection. Otherwise
+      # the return response is going to be an entire array of items.
+
+      if options[:single] or root
         collection.first
       else
         collection

data/lib/happymapper/item.rb

@@ -229,7 +229,7 @@ module HappyMapper
 
       def handle_attributes_option(result, value, xpath_options)
         if options[:attributes].is_a?(Hash)
-          result = result.first if result.respond_to?(:first)
+          result = result.first unless result.respond_to?(:attribute_nodes)
 
           result.attribute_nodes.each do |xml_attribute|
             if attribute_options = options[:attributes][xml_attribute.name.to_sym]

data/spec/fixtures/atom.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<feed xml:lang="en-US" xmlns="http://www.w3.org/2005/Atom">
+  <id>tag:www.example.com,2005:/tv_shows</id>
+  <link rel="alternate" type="text/html" href="http://www.example.com"/>
+  <link rel="self" type="application/atom+xml" href="http://www.example.com/tv_shows.atom"/>
+  <title>TV Shows</title>
+  <updated>2011-07-08T13:47:01Z</updated>
+  <entry>
+    <id>tag:www.example.com,2005:TvShow/17</id>
+    <published>2011-07-08T13:47:01Z</published>
+    <updated>2011-07-08T13:47:01Z</updated>
+    <link rel="alternate" type="text/html" href="http://www.example.com/sources/channel-twenty-seven/tv_shows/name-goes-here.atom"/>
+    <title>Name goes here</title>
+    <content type="html">Name goes here (0 episodes)</content>
+    <author>
+      <name>Source URL goes here</name>
+    </author>
+  </entry>
+</feed>

data/spec/happymapper_spec.rb

@@ -69,6 +69,24 @@ module Analytics
   end
 end
 
+module Atom
+  class Feed
+    include HappyMapper
+    tag 'feed'
+
+    attribute :xmlns, String, :single => true
+    element :id, String, :single => true
+    element :title, String, :single => true
+    element :updated, DateTime, :single => true
+    element :link, String, :single => false, :attributes => {
+        :rel => String,
+        :type => String,
+        :href => String
+      }
+    # has_many :entries, Entry # nothing interesting in the entries
+  end
+end
+
 class Address
   include HappyMapper
 
@@ -701,6 +719,12 @@ describe HappyMapper do
     first.current_condition.icon.should == 'http://deskwx.weatherbug.com/images/Forecast/icons/cond007.gif'
   end
 
+  it "parses xml with attributes of elements that aren't :single => true" do
+    feed = Atom::Feed.parse(fixture_file('atom.xml'))
+    feed.link.first.href.should == 'http://www.example.com'
+    feed.link.last.href.should == 'http://www.example.com/tv_shows.atom'
+  end
+
   it "should parse xml with nested elements" do
     radars = Radar.parse(fixture_file('radar.xml'))
     first = radars[0]
@@ -893,10 +917,6 @@ describe HappyMapper do
       @article.photos.first.title.should_not be_nil
     end
     
-    it "should contain the attributes in the as_xml" do
-      @article.to_xml.should_not be_nil
-    end
-    
     it "should parse the publish options for Article" do
       @article.publish_options.should_not be_nil
     end
@@ -908,19 +928,7 @@ describe HappyMapper do
     it "should only find only items at the parent level" do
       @article.photos.length.should == 1
     end
-  
-    it "should have as_xml" do
-      @article.photos.first.to_xml.should_not be_nil
-    end
-    
-    it "should be parseable because it has the namespaces" do
-      lambda { Nokogiri::XML(@article.photos.first.to_xml).to_s }.should_not raise_error
-    end
     
-    it "should be parseable because it has the namespaces" do
-      lambda { Nokogiri::XML(@article.photos.first.to_xml).to_s }.should_not raise_error
-    end
-        
     before(:all) do
       @article = Article.parse(fixture_file('subclass_namespace.xml'))
     end
@@ -937,5 +945,24 @@ describe HappyMapper do
        @article.photos.first.title.should_not be_nil
      end
    end
+   
+   
+   describe "with limit option" do
+     it "should return results with limited size: 6" do
+       sizes = []
+       posts = Post.parse(fixture_file('posts.xml'), :in_groups_of => 6) do |a|
+         sizes << a.size
+       end
+       sizes.should == [6, 6, 6, 2]
+     end
+
+     it "should return results with limited size: 10" do
+       sizes = []
+       posts = Post.parse(fixture_file('posts.xml'), :in_groups_of => 10) do |a|
+         sizes << a.size
+       end
+       sizes.should == [10, 10]
+     end
+   end
   
 end

metadata

@@ -1,10 +1,10 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: unhappymapper
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.4.1
   prerelease: 
-  version: 0.4.0
 platform: ruby
-authors: 
+authors:
 - Damien Le Berrigaud
 - John Nunemaker
 - David Bolton
@@ -14,42 +14,39 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-22 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-08-22 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: nokogiri
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70134376050820 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.4.2
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: *70134376050820
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70134376050340 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.3.0
   type: :development
-  version_requirements: *id002
-description: Object to XML Mapping Library, using Nokogiri (fork from John Nunemaker's Happymapper)
+  prerelease: false
+  version_requirements: *70134376050340
+description: Object to XML Mapping Library, using Nokogiri (fork from John Nunemaker's
+  Happymapper)
 email: franklin.webber@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.md
 - TODO
-files: 
+files:
 - lib/happymapper.rb
 - lib/happymapper/attribute.rb
 - lib/happymapper/element.rb
@@ -61,6 +58,7 @@ files:
 - spec/fixtures/ambigous_items.xml
 - spec/fixtures/analytics.xml
 - spec/fixtures/analytics_profile.xml
+- spec/fixtures/atom.xml
 - spec/fixtures/commit.xml
 - spec/fixtures/current_weather.xml
 - spec/fixtures/dictionary.xml
@@ -88,39 +86,36 @@ files:
 - spec/ignay_spec.rb
 - spec/spec_helper.rb
 - spec/xpath_spec.rb
-has_rdoc: true
 homepage: http://github.com/burtlo/happymapper
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Provides a simple way to map XML to Ruby Objects and back again.
-test_files: 
+test_files:
 - spec/fixtures/address.xml
 - spec/fixtures/ambigous_items.xml
 - spec/fixtures/analytics.xml
 - spec/fixtures/analytics_profile.xml
+- spec/fixtures/atom.xml
 - spec/fixtures/commit.xml
 - spec/fixtures/current_weather.xml
 - spec/fixtures/dictionary.xml