nokogiri-happymapper 0.5.6 → 0.5.7

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    OTI1ZDRjNDk4NTE1ZjAxZTA0ZjE0YzhhM2JkYTk3YmZjOWZkYjE3NA==
+  data.tar.gz: !binary |-
+    NjQyMjEyMDBmYTU5NGZmNzM2NGY4NzJkM2Q1ZDA5YmU0NzY5NDU2OA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NjY1MTkxOTI0NjM1NDI2YTdjOGUwNzFhNjkzMWNiMzg5OGQ4ZTcyZGQ3NzZm
+    YmJlNzg0MjNlYjk4MDE5N2E0M2IyNjM5MGE5MmE3M2I3MzE2MTM4MmEwZTNi
+    OTMxMzkxMTViMGI3Mzc5MmY2ZGJjOGY5YTYyNjY1OTk3YTIwZDU=
+  data.tar.gz: !binary |-
+    ZjBmZjEwMzQ4NWRmYWJmYzFiMDRkZDYwYzU5N2VjY2U5ZTEwODU1ZmRiYjVm
+    Njc5OTIyNjA3NmJhMDNmOWNhM2RjOTI5NDZhNmEzODQ5ZDc0MzMxYTM0MWE0
+    MTQzMjYzMDY0Njg4ZGE3NWFjNTU1YmY3NDAwY2ExNDhmMDdhMDc=

data/CHANGELOG.md

@@ -1,10 +1,14 @@
+## 0.5.6 / 2012-10-29
+
+* Add possibility to give a configuration block to Nokogiri when parsing (DieboldInc).
+
 ## 0.5.5 / 2012-09-30
 
 * Fix for Boolean attributes to ensure that they parse correctly (zrob)
 
 ## 0.5.4/ 2012-09-25
 
-* #wrap method allows you to better model xml content that is buried deep
+* the #wrap method allows you to better model xml content that is buried deep
   within the xml. This implementation addresses issues with calling #to_xml
   with content that was parsed from an xpath. (zrob)
 

data/README.md

@@ -13,7 +13,7 @@ This project is a fork of the great work done first by
   * Raw XML content parsing
   * [burtlo](http://github.com/burtlo/happymapper)'s `#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). 
+  * 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).
 
 ## Installation
 
@@ -42,6 +42,30 @@ Let's start with a simple example to get our feet wet. Here we have a simple exa
       <country code="de">Germany</country>
     </address>
 
+Happymapper provides support for simple, zero configuration parsing as well as the ability to model the XML content in classes.
+
+## HappyMapper.parse(XML)
+
+With no classes or configuration you can parse the example XML with little effort:
+
+```ruby
+address = HappyMapper.parse(ADDRESS_XML_DATA)
+address.street # => Milchstrasse
+address.housenumber # => 23
+address.postcode # => 26131
+address.city # => Oldenburg
+address.country.code # => de
+address.country.content # => Germany
+```
+
+It is important to be aware that this no configuration parsing is limited in capacity:
+
+* All element names are converted to accessor methods with [underscorized](http://rubydoc.info/gems/activesupport/ActiveSupport/Inflector:underscore) names
+* All value fields are left as String types
+* Determining if there is just one or multiple child elements is hard, so it assumes it is one until it finds another with the same name.
+
+## Address.parse(XML)
+
 Happymapper will let you easily model this information as a class:
 
     require 'happymapper'
@@ -62,7 +86,7 @@ To make a class HappyMapper compatible you simply `include HappyMapper` within t
 * `tag` matches the name of the XML tag name 'address'.
 
 * `element` defines accessor methods for the specified symbol (e.g. `:street`,`:housenumber`) that will return the class type (e.g. `String`,`Integer`) of the XML tag specified (e.g. `:tag => 'street'`, `:tag => 'housenumber'`).
-    
+
 When you define an element with an accessor with the same name as the tag, this is the case for all the examples above, you can omit the `:tag`. These two element declaration are equivalent to each other:
 
     element :street, String, :tag => 'street'
@@ -83,7 +107,7 @@ These three statements are equivalent to each other.
 With the mapping of the address XML articulated in our Address class it is time to parse the data:
 
     address = Address.parse(ADDRESS_XML_DATA, :single => true)
-    puts address.street 
+    puts address.street
 
 Assuming that the constant `ADDRESS_XML_DATA` contains a string representation of the address XML data this is fairly straight-forward save for the `parse` method.
 
@@ -117,7 +141,7 @@ Your resulting `streets` method will now return an array.
 
     address = Address.parse(ADDRESS_XML_DATA, :single => true)
     puts address.streets.join('\n')
-    
+
 Imagine that you have to write `streets.join('\n')` for the rest of eternity throughout your code. It would be a nightmare and one that you could avoid by creating your own convenience method.
 
      require 'happymapper'
@@ -126,13 +150,13 @@ Imagine that you have to write `streets.join('\n')` for the rest of eternity thr
        include HappyMapper
 
        tag 'address'
-       
+
        has_many :streets, String
-       
+
        def streets
          @streets.join('\n')
        end
-       
+
        element :postcode, String, :tag => 'postcode'
        element :housenumber, String, :tag => 'housenumber'
        element :city, String, :tag => 'city'
@@ -156,7 +180,7 @@ Now when we call the method `streets` we get a single value, but we still have t
 Attributes are absolutely the same as `element` or `has_many`
 
     attribute :location, String, :tag => 'location
-    
+
 Again, you can omit the tag if the attribute accessor symbol matches the name of the attribute.
 
 
@@ -211,9 +235,9 @@ Well if we only going to parse country, on it's own, we would likely create a cl
 
     class Country
       include HappyMapper
-  
+
       tag 'country'
-  
+
       attribute :code, String
       content :name, String
     end
@@ -228,24 +252,24 @@ Awesome, now if we were to redeclare our `Address` class we would use our new `C
       include HappyMapper
 
       tag 'address'
-  
+
       has_many :streets, String, :tag => 'street'
-  
+
       def streets
         @streets.join('\n')
       end
-      
+
       element :postcode, String, :tag => 'postcode'
       element :housenumber, String, :tag => 'housenumber'
       element :city, String, :tag => 'city'
       element :country, Country, :tag => 'country'
     end
-  
+
 Instead of `String`, `Boolean`, or `Integer` we say that it is a `Country` and HappyMapper takes care of the details of continuing the XML mapping through the country element.
 
     address = Address.parse(ADDRESS_XML_DATA, :single => true)
     puts address.country.code
-  
+
 A quick note, in the above example we used the constant `Country`. We could have used `'Country'`. The nice part of using the latter declaration, enclosed in quotes, is that you do not have to define your class before this class. So Country and Address can live in separate files and as long as both constants are available when it comes time to parse you are golden.
 
 ## Custom XPATH
@@ -258,12 +282,12 @@ Getting to elements deep down within your XML can be a little more work if you d
       <gallery>
         <title href="htttp://fishlovers.org/friends">Friends Who Like Fish</title>
         <picture>
-          <name>Burtie Sanchez</name>  
+          <name>Burtie Sanchez</name>
           <img>burtie01.png</img>
         </picture>
       </gallery>
       <picture>
-        <name>Unsorted Photo</name>  
+        <name>Unsorted Photo</name>
         <img>bestfriends.png</img>
       </picture>
     </media>
@@ -272,36 +296,36 @@ You may want to map the sub-elements contained buried in the 'gallery' as top le
 
     class Media
       include HappyMapper
-  
+
       has_one :title, String, :xpath => 'gallery/title'
       has_one :link, String, :xpath => 'gallery/title/@href'
     end
 
 
-## Subclasses
+## Shared Functionality
 
-### Inheritance (it doesn't work!)
+### Inheritance Approach
 
 While mapping XML to objects you may arrive at a point where you have two or more very similar structures.
 
     class Article
       include HappyMapper
-  
+
       has_one :title, String
       has_one :author, String
       has_one :published, Time
-  
+
       has_one :entry, String
-  
+
     end
 
     class Gallery
       include HappyMapper
-  
+
       has_one :title, String
       has_one :author, String
       has_one :published, Time
-  
+
       has_many :photos, String
 
     end
@@ -310,29 +334,27 @@ In this example there are definitely two similarities between our two pieces of
 
     class Content
       include HappyMapper
-  
+
       has_one :title, String
       has_one :author, String
       has_one :published, Time
-
     end
 
     class Article < Content
       include HappyMapper
-      
+
       has_one :entry, String
     end
-    
+
     class Gallery < Content
       include HappyMapper
-      
+
       has_many :photos, String
     end
-    
-However, *this does not work*. And the reason is because each one of these element declarations are method calls that are defining elements on the class itself. So it is not passed down through inheritance.
 
-You can however, use some module mixin power to save you those keystrokes and impress your friends.
+### Module Mixins Approache
 
+You can also solve the above problem through mixins.
 
     module Content
       def self.included(content)
@@ -340,23 +362,22 @@ You can however, use some module mixin power to save you those keystrokes and im
         content.has_one :author, String
         content.has_one :published, Time
       end
-      
+
       def published_time
         @published.strftime("%H:%M:%S")
       end
-      
     end
 
     class Article
       include HappyMapper
-      
+
       include Content
       has_one :entry, String
     end
 
     class Gallery
       include HappyMapper
-      
+
       include Content
       has_many :photos, String
     end
@@ -372,23 +393,23 @@ I ran into a case where I wanted to capture all the pictures that were directly
     <media>
       <gallery>
         <picture>
-          <name>Burtie Sanchez</name>  
+          <name>Burtie Sanchez</name>
           <img>burtie01.png</img>
         </picture>
       </gallery>
       <picture>
-        <name>Unsorted Photo</name>  
+        <name>Unsorted Photo</name>
         <img>bestfriends.png</img>
       </picture>
     </media>
-    
+
 The following `Media` class is where I started:
 
     require 'happymapper'
 
     class Media
       include HappyMapper
-  
+
       has_many :galleries, Gallery, :tag => 'gallery'
       has_many :pictures, Picture, :tag => 'picture'
     end
@@ -424,20 +445,20 @@ Here again is our address example with a made up namespace called `prefix` that
 
     class Address
       include HappyMapper
-      
+
       tag 'address'
       namespace 'prefix'
       # ... rest of the code ...
     end
-    
-Of course, if that is too easy for you, you can append a `:namespace => 'prefix` to every one of the elements that you defined. 
+
+Of course, if that is too easy for you, you can append a `:namespace => 'prefix` to every one of the elements that you defined.
 
     has_many :street, String, :tag => 'street', :namespace => 'prefix'
     element :postcode, String, :tag => 'postcode', :namespace => 'prefix'
     element :housenumber, String, :tag => 'housenumber', :namespace => 'prefix'
     element :city, String, :tag => 'city', :namespace => 'prefix'
     element :country, Country, :tag => 'country', :namespace => 'prefix'
-    
+
 I definitely recommend the former, as it saves you a whole hell of lot of typing. However, there are times when appending a namespace to an element declaration is important and that is when it has a different namespace then `namespsace 'prefix'`.
 
 Imagine that our `country` actually belonged to a completely different namespace.
@@ -455,7 +476,7 @@ Imagine that our `country` actually belonged to a completely different namespace
 Well we would need to specify that namespace:
 
     element :country, Country, :tag => 'country', :namespace => 'different'
-    
+
 With that we should be able to parse as we once did.
 
 ## Large Datasets (in_groups_of)
@@ -478,7 +499,7 @@ Saving a class to XML is as easy as calling `#to_xml`.  The end result will be t
 When you are saving data to xml it is often important to change or manipulate data to a particular format. For example, a time object:
 
     has_one :published_time, Time, :on_save => lambda {|time| time.strftime("%H:%M:%S") if time }
-  
+
 Here we add the options `:on_save` and specify a lambda which will be executed on the method call to `:published_time`.
 
 ### :state_when_nil
@@ -486,7 +507,7 @@ Here we add the options `:on_save` and specify a lambda which will be executed o
 When an element contains a nil value, or perhaps the result of the :on_save lambda correctly results in a nil value you will be happy that the element will not appear in the resulting XML. However, there are time when you will want to see that element and that's when `:state_when_nil` is there for you.
 
     has_one :favorite_color, String, :state_when_nil => true
-    
+
 The resulting XML will include the 'favorite_color' element even if the favorite color has not been specified.
 
 ### :read_only
@@ -496,7 +517,7 @@ saving to XML, you can ensure that takes place by stating that it is `read only`
 
     has_one :modified, Boolean, :read_only => true
     attribute :temporary, Boolean, :read_only => true
-    
+
 This is useful if perhaps the incoming XML is different than the out-going XML.
 
 ### namespaces
@@ -505,17 +526,17 @@ While parsing the XML only required you to simply specify the prefix of the name
 
     class Address
       include HappyMapper
-      
+
       register_namespace 'prefix', 'http://www.unicornland.com/prefix'
       register_namespace 'different', 'http://www.trollcountry.com/different'
-      
+
       tag 'address'
       namespace 'prefix'
-      
+
       has_many :street, String
       element :postcode, String
       element :housenumber, String
       element :city, String
       element :country, Country, :tag => 'country', :namespace => 'different'
-    
+
     end

data/lib/happymapper/anonymous_mapper.rb

@@ -0,0 +1,114 @@
+module HappyMapper
+  module AnonymousMapper
+
+    def parse(xml_content)
+
+      # TODO: this should be able to handle all the types of functionality that parse is able
+      #   to handle which includes the text, xml document, node, fragment, etc.
+      xml = Nokogiri::XML(xml_content)
+
+      happymapper_class = create_happymapper_class_with_element(xml.root)
+
+      # With all the elements and attributes defined on the class it is time
+      # for the class to actually use the normal HappyMapper powers to parse
+      # the content. At this point this code is utilizing all of the existing
+      # code implemented for parsing.
+      happymapper_class.parse(xml_content, :single => true)
+
+    end
+
+    private
+
+    #
+    # Borrowed from Active Support to convert unruly element names into a format
+    # known and loved by Rubyists.
+    #
+    def underscore(camel_cased_word)
+      word = camel_cased_word.to_s.dup
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      word.tr!("-", "_")
+      word.downcase!
+      word
+    end
+
+    #
+    # Used internally when parsing to create a class that is capable of
+    # parsing the content. The name of the class is of course not likely
+    # going to match the content it will be able to parse so the tag
+    # value is set to the one provided.
+    #
+    def create_happymapper_class_with_tag(tag_name)
+      happymapper_class = Class.new
+      happymapper_class.class_eval do
+        include HappyMapper
+        tag tag_name
+      end
+      happymapper_class
+    end
+
+    #
+    # Used internally to create and define the necessary happymapper
+    # elements.
+    #
+    def create_happymapper_class_with_element(element)
+      happymapper_class = create_happymapper_class_with_tag(element.name)
+
+      happymapper_class.namespace element.namespace.prefix if element.namespace
+
+      element.namespaces.each do |prefix,namespace|
+        happymapper_class.register_namespace prefix, namespace
+      end
+
+      element.attributes.each do |name,attribute|
+        define_attribute_on_class(happymapper_class,attribute)
+      end
+
+      element.children.each do |element|
+        define_element_on_class(happymapper_class,element)
+      end
+
+      happymapper_class
+    end
+
+
+    #
+    # Define a HappyMapper element on the provided class based on
+    # the element provided.
+    #
+    def define_element_on_class(class_instance,element)
+
+      # When a text element has been provided create the necessary
+      # HappyMapper content attribute if the text happens to content
+      # some content.
+
+      if element.text? and element.content.strip != ""
+        class_instance.content :content, String
+      end
+
+      # When the element has children elements, that are not text
+      # elements, then we want to recursively define a new HappyMapper
+      # class that will have elements and attributes.
+
+      element_type = if !element.elements.reject {|e| e.text? }.empty? or !element.attributes.empty?
+        create_happymapper_class_with_element(element)
+      else
+        String
+      end
+
+      method = class_instance.elements.find {|e| e.name == element.name } ? :has_many : :has_one
+
+      class_instance.send(method,underscore(element.name),element_type)
+    end
+
+    #
+    # Define a HappyMapper attribute on the provided class based on
+    # the attribute provided.
+    #
+    def define_attribute_on_class(class_instance,attribute)
+      class_instance.attribute underscore(attribute.name), String
+    end
+
+  end
+
+end

data/lib/happymapper/attribute.rb

@@ -1,3 +1,21 @@
 module HappyMapper
-  class Attribute < Item; end
-end
+  class Attribute < Item
+    attr_accessor :default
+
+    # @see Item#initialize
+    # Additional options:
+    #   :default => Object The default value for this
+    def initialize(name, type, o={})
+      super
+      self.default = o[:default]
+    end
+
+    def find(node, namespace, xpath_options)
+      if options[:xpath]
+        yield(node.xpath(options[:xpath],xpath_options))
+      else
+        yield(node[tag])
+      end
+    end
+  end
+end

data/lib/happymapper/element.rb

@@ -1,3 +1,53 @@
 module HappyMapper
-  class Element < Item; end
-end
+  class Element < Item
+
+    def find(node, namespace, xpath_options)
+      if self.namespace
+        # from the class definition
+        namespace = self.namespace
+      elsif options[:namespace]
+        namespace = options[:namespace]
+      end
+
+      if options[:single]
+        if options[:xpath]
+          result = node.xpath(options[:xpath], xpath_options)
+        else
+          result = node.xpath(xpath(namespace), xpath_options)
+        end
+
+        if result
+          value = yield(result.first)
+          handle_attributes_option(result, value, xpath_options)
+          value
+        end
+      else
+        target_path = options[:xpath] ? options[:xpath] : xpath(namespace)
+        node.xpath(target_path, xpath_options).collect do |result|
+          value = yield(result)
+          handle_attributes_option(result, value, xpath_options)
+          value
+        end
+      end
+    end
+
+    def handle_attributes_option(result, value, xpath_options)
+      if options[:attributes].is_a?(Hash)
+        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]
+            attribute_value = Attribute.new(xml_attribute.name.to_sym, *attribute_options).from_xml_node(result, namespace, xpath_options)
+
+            result.instance_eval <<-EOV
+                def value.#{xml_attribute.name}
+            #{attribute_value.inspect}
+                end
+            EOV
+          end # if attributes_options
+        end # attribute_nodes.each
+      end # if options[:attributes]
+    end # def handle...
+
+  end
+end