xmlmapper 0.5.9 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: eecda6c9e7f04c691c79c526d0fefbf4b2b46c9e
-  data.tar.gz: bd9701c0b3bad3324f7218d94dc47b0ac92105f4
+  metadata.gz: 01d484e73f2c9225912fdd49addedaa71ff18f4a
+  data.tar.gz: 274e89894d6e53f0abb8fa269e4878c2f4b3f771
 SHA512:
-  metadata.gz: 54a736eda4f3af41abfc0161a2ede5e8be5a28da6e081c288648b3f46083052a31d8aac1ce093f6404f469cf520176e5c33c1c325b1eef011ee19a1c76e96017
-  data.tar.gz: bae38c19dbf4c2ab34469f4cd2181d0699c20728d939a6f860ca5f1e9bdc84442fe48b1e86324f02c9c53fa6eab72111415b873eda278acc081380a57d140818
+  metadata.gz: 5b44469677e336a95c4f8abb685f535079f1f0deb57aec5d5fd7c77fce2142a8c19538986e1cdfff6107663d40d5ad2b41168c2b82278d92a760218fbbdf54b2
+  data.tar.gz: 38cad28864fd8dbc93c3f208ba15a428c4fbff82e0dccaead78a0b5b0a3c5f407dd48bfa9dc85551a94bb3c1e31f6be5900ee8d1c21f256c453111dd5c186985

data/CHANGELOG.md

@@ -6,7 +6,7 @@
 
 * Allow child elements to remove their parent's namespacing (dcarneiro)
 * has_many elements were returning nil because the tag name was being ignored (haarts)
-* Subclassed happymapper classes are allowed to override elements (benoist)
+* Subclassed xmlmapper classes are allowed to override elements (benoist)
 * Attributes on elements with dashes will properly created methods (alex-klepa)
 * 'Embedded' attributes break parsing when parent element is not present (geoffwa)
 
@@ -26,10 +26,10 @@
   within the xml. This implementation addresses issues with calling #to_xml
   with content that was parsed from an xpath. (zrob)
 
-* Parent HappyMapper classes may dictate the name of the tag for the child
-  HappyMapper instances. (zrob)
+* Parent XmlMapper classes may dictate the name of the tag for the child
+  XmlMapper instances. (zrob)
 
 ## 0.5.3/ 2012-09-23
 
 * String is the default type for parsed fields. (crv)
-* Update the attributes of an existing HappyMapper instance with new XML (benoist)
+* Update the attributes of an existing XmlMapper instance with new XML (benoist)

data/README.md

@@ -1,7 +1,7 @@
-HappyMapper
+Xmlmapper
 ===========
 
-Happymapper allows you to parse XML data and convert it quickly and easily into ruby data structures.
+Xmlmapper allows you to parse XML data and convert it quickly and easily into ruby data structures.
 
 This project is a fork of the great work done first by
 [jnunemaker](https://github.com/jnunemaker/happymapper).
@@ -11,20 +11,20 @@ This project is a fork of the great work done first by
   * [Nokogiri](http://nokogiri.org/) support
   * Text nodes parsing
   * Raw XML content parsing
-  * `#to_xml` support utilizing the same HappyMapper tags
+  * `#to_xml` support utilizing the same XmlMapper tags
   * Numerous fixes for namespaces when using composition of classes
   * Fixes for instances of XML where a namespace is defined but no elements with that namespace are found
 
 ## Installation
 
-### [Rubygems](https://rubyygems.org/gems/nokogiri-happymapper)
+### [Rubygems](https://rubyygems.org/gems/xmlmapper)
 
-    $ gem install nokogiri-happymapper
+    $ gem install xmlmapper
 
 ### [Bundler](http://gembundler.com/)
-Add the `nokogiri-happymapper` gem to your project's `Gemfile`.
+Add the `xmlmapper` gem to your project's `Gemfile`.
 
-    gem 'nokogiri-happymapper', :require => 'happymapper'
+    gem 'xmlmapper'
 
 Run the bundler command to install the gem:
 
@@ -42,14 +42,14 @@ 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.
+XmlMapper provides support for simple, zero configuration parsing as well as the ability to model the XML content in classes.
 
-## HappyMapper.parse(XML)
+## XmlMapper.parse(XML)
 
 With no classes or configuration you can parse the example XML with little effort:
 
 ```ruby
-address = HappyMapper.parse(ADDRESS_XML_DATA)
+address = XmlMapper.parse(ADDRESS_XML_DATA)
 address.street # => Milchstrasse
 address.housenumber # => 23
 address.postcode # => 26131
@@ -66,13 +66,13 @@ It is important to be aware that this no configuration parsing is limited in cap
 
 ## Address.parse(XML)
 
-Happymapper will let you easily model this information as a class:
+XmlMapper will let you easily model this information as a class:
 
 ```ruby
-require 'happymapper'
+require 'xmlmapper'
 
 class Address
-  include HappyMapper
+  include XmlMapper
 
   tag 'address'
   element :street, String, :tag => 'street'
@@ -83,7 +83,7 @@ class Address
 end
 ```
 
-To make a class HappyMapper compatible you simply `include HappyMapper` within the class definition. This takes care of all the work of defining all the speciality methods and magic you need to get running. As you can see we immediately start using these methods.
+To make a class XmlMapper compatible you simply `include XmlMapper` within the class definition. This takes care of all the work of defining all the speciality methods and magic you need to get running. As you can see we immediately start using these methods.
 
 * `tag` matches the name of the XML tag name 'address'.
 
@@ -119,7 +119,7 @@ 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.
 
-The `parse` method, like `tag` and `element` are all added when you included HappyMapper in the class. Parse is a wonderful, magical place that converts all these declarations that you have made into the data structure you are about to know and love.
+The `parse` method, like `tag` and `element` are all added when you included XmlMapper in the class. Parse is a wonderful, magical place that converts all these declarations that you have made into the data structure you are about to know and love.
 
 But what about the `:single => true`? Right, that is because by default when your object is all done parsing it will be an array. In this case an array with one element, but an array none the less. So the following are equivalent to each other:
 
@@ -159,10 +159,10 @@ 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.
 
 ```ruby
-require 'happymapper'
+require 'xmlmapper'
 
 class Address
-  include HappyMapper
+  include XmlMapper
 
   tag 'address'
 
@@ -221,7 +221,7 @@ class Feed
 end
 
 class Link
-  include HappyMapper
+  include XmlMapper
 
   attribute :rel, String
   attribute :type, String
@@ -257,7 +257,7 @@ Well if we only going to parse country, on it's own, we would likely create a cl
 
 ```ruby
 class Country
-  include HappyMapper
+  include XmlMapper
 
   tag 'country'
 
@@ -274,7 +274,7 @@ Awesome, now if we were to redeclare our `Address` class we would use our new `C
 
 ```ruby
 class Address
-  include HappyMapper
+  include XmlMapper
 
   tag 'address'
 
@@ -291,7 +291,7 @@ class Address
 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.
+Instead of `String`, `Boolean`, or `Integer` we say that it is a `Country` and XmlMapper takes care of the details of continuing the XML mapping through the country element.
 
 ```ruby
 address = Address.parse(ADDRESS_XML_DATA, :single => true)
@@ -324,7 +324,7 @@ You may want to map the sub-elements contained buried in the 'gallery' as top le
 
 ```ruby
 class Media
-  include HappyMapper
+  include XmlMapper
 
   has_one :title, String, :xpath => 'gallery/title'
   has_one :link, String, :xpath => 'gallery/title/@href'
@@ -339,7 +339,7 @@ While mapping XML to objects you may arrive at a point where you have two or mor
 
 ```ruby
 class Article
-  include HappyMapper
+  include XmlMapper
 
   has_one :title, String
   has_one :author, String
@@ -350,7 +350,7 @@ class Article
 end
 
 class Gallery
-  include HappyMapper
+  include XmlMapper
 
   has_one :title, String
   has_one :author, String
@@ -365,7 +365,7 @@ In this example there are definitely two similarities between our two pieces of
 
 ```ruby
 class Content
-  include HappyMapper
+  include XmlMapper
 
   has_one :title, String
   has_one :author, String
@@ -373,13 +373,13 @@ class Content
 end
 
 class Article < Content
-  include HappyMapper
+  include XmlMapper
 
   has_one :entry, String
 end
 
 class Gallery < Content
-  include HappyMapper
+  include XmlMapper
 
   has_many :photos, String
 end
@@ -403,21 +403,21 @@ module Content
 end
 
 class Article
-  include HappyMapper
+  include XmlMapper
 
   include Content
   has_one :entry, String
 end
 
 class Gallery
-  include HappyMapper
+  include XmlMapper
 
   include Content
   has_many :photos, String
 end
 ```
 
-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.
+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 xmlmapper elements as well as any other methods that may rely on those instance variables that come along in the package.
 
 
 ## Filtering with XPATH (non-greedy)
@@ -440,10 +440,10 @@ I ran into a case where I wanted to capture all the pictures that were directly
 The following `Media` class is where I started:
 
 ```ruby
-require 'happymapper'
+require 'xmlmapper'
 
 class Media
-  include HappyMapper
+  include XmlMapper
 
   has_many :galleries, Gallery, :tag => 'gallery'
   has_many :pictures, Picture, :tag => 'picture'
@@ -492,7 +492,7 @@ Here again is our address example with a made up namespace called `prefix` that
 
 ```ruby
 class Address
-  include HappyMapper
+  include XmlMapper
 
   tag 'address'
   namespace 'prefix'
@@ -587,7 +587,7 @@ Parsing the XML to objects only required you to simply specify the prefix of the
 
 ```ruby
 class Address
-  include HappyMapper
+  include XmlMapper
 
   register_namespace 'prefix', 'http://www.unicornland.com/prefix'
   register_namespace 'different', 'http://www.trollcountry.com/different'
@@ -602,4 +602,4 @@ class Address
   element :country, Country, :tag => 'country', :namespace => 'different'
 
 end
-```
+```

data/lib/xmlmapper.rb

@@ -1 +1,776 @@
-require 'happymapper'
+require 'nokogiri'
+require 'date'
+require 'time'
+require 'xmlmapper/anonymous_mapper'
+
+module XmlMapper
+  class Boolean; end
+  class XmlContent; end
+
+  extend AnonymousMapper
+
+  DEFAULT_NS = "xmlmapper"
+
+  def self.included(base)
+    if !(base.superclass <= XmlMapper)
+      base.instance_eval do
+        @attributes = {}
+        @elements = {}
+        @registered_namespaces = {}
+        @wrapper_anonymous_classes = {}
+      end
+    else
+      base.instance_eval do
+        @attributes =
+            superclass.instance_variable_get(:@attributes).dup
+        @elements =
+            superclass.instance_variable_get(:@elements).dup
+        @registered_namespaces =
+            superclass.instance_variable_get(:@registered_namespaces).dup
+        @wrapper_anonymous_classes =
+            superclass.instance_variable_get(:@wrapper_anonymous_classes).dup
+      end
+    end
+
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+
+    #
+    # The xml has the following attributes defined.
+    #
+    # @example
+    #
+    #     "<country code='de'>Germany</country>"
+    #
+    #     # definition of the 'code' attribute within the class
+    #     attribute :code, String
+    #
+    # @param [Symbol] name the name of the accessor that is created
+    # @param [String,Class] type the class name of the name of the class whcih
+    #     the object will be converted upon parsing
+    # @param [Hash] options additional parameters to send to the relationship
+    #
+    def attribute(name, type, options={})
+      attribute = Attribute.new(name, type, options)
+      @attributes[name] = attribute
+      attr_accessor attribute.method_name.intern
+    end
+
+    #
+    # The elements defined through {#attribute}.
+    #
+    # @return [Array<Attribute>] a list of the attributes defined for this class;
+    #     an empty array is returned when there have been no attributes defined.
+    #
+    def attributes
+      @attributes.values
+    end
+
+    #
+    # Register a namespace that is used to persist the object namespace back to
+    # XML.
+    #
+    # @example
+    #
+    #     register_namespace 'prefix', 'http://www.unicornland.com/prefix'
+    #
+    #     # the output will contain the namespace defined
+    #
+    #     "<outputXML xmlns:prefix="http://www.unicornland.com/prefix">
+    #     ...
+    #     </outputXML>"
+    #
+    # @param [String] namespace the xml prefix
+    # @param [String] ns url for the xml namespace
+    #
+    def register_namespace(namespace, ns)
+      @registered_namespaces.merge!({namespace => ns})
+    end
+
+    #
+    # An element defined in the XML that is parsed.
+    #
+    # @example
+    #
+    #     "<address location='home'>
+    #        <city>Oldenburg</city>
+    #      </address>"
+    #
+    #     # definition of the 'city' element within the class
+    #
+    #     element :city, String
+    #
+    # @param [Symbol] name the name of the accessor that is created
+    # @param [String,Class] type the class name of the name of the class whcih
+    #     the object will be converted upon parsing
+    # @param [Hash] options additional parameters to send to the relationship
+    #
+    def element(name, type, options={})
+      element = Element.new(name, type, options)
+      @elements[name] = element
+      attr_accessor element.method_name.intern
+    end
+
+    #
+    # The elements defined through {#element}, {#has_one}, and {#has_many}.
+    #
+    # @return [Array<Element>] a list of the elements contained defined for this
+    #     class; an empty array is returned when there have been no elements
+    #     defined.
+    #
+    def elements
+      @elements.values
+    end
+
+    #
+    # The value stored in the text node of the current element.
+    #
+    # @example
+    #
+    #     "<firstName>Michael Jackson</firstName>"
+    #
+    #     # definition of the 'firstName' text node within the class
+    #
+    #     content :first_name, String
+    #
+    # @param [Symbol] name the name of the accessor that is created
+    # @param [String,Class] type the class name of the name of the class whcih
+    #     the object will be converted upon parsing. By Default String class will be taken.
+    # @param [Hash] options additional parameters to send to the relationship
+    #
+    def content(name, type=String, options={})
+      @content = TextNode.new(name, type, options)
+      attr_accessor @content.method_name.intern
+    end
+
+    #
+    # Sets the object to have xml content, this will assign the XML contents
+    # that are parsed to the attribute accessor xml_content. The object will
+    # respond to the method #xml_content and will return the XML data that
+    # it has parsed.
+    #
+    def has_xml_content
+      attr_accessor :xml_content
+    end
+
+    #
+    # The object has one of these elements in the XML. If there are multiple,
+    # the last one will be set to this value.
+    #
+    # @param [Symbol] name the name of the accessor that is created
+    # @param [String,Class] type the class name of the name of the class whcih
+    #     the object will be converted upon parsing
+    # @param [Hash] options additional parameters to send to the relationship
+    #
+    # @see #element
+    #
+    def has_one(name, type, options={})
+      element name, type, {:single => true}.merge(options)
+    end
+
+    #
+    # The object has many of these elements in the XML.
+    #
+    # @param [Symbol] name the name of accessor that is created
+    # @param [String,Class] type the class name or the name of the class which
+    #     the object will be converted upon parsing.
+    # @param [Hash] options additional parameters to send to the relationship
+    #
+    # @see #element
+    #
+    def has_many(name, type, options={})
+      element name, type, {:single => false}.merge(options)
+    end
+
+    #
+    # The list of registered after_parse callbacks.
+    #
+    def after_parse_callbacks
+      @after_parse_callbacks ||= []
+    end
+
+    #
+    # Register a new after_parse callback, given as a block.
+    #
+    # @yield [object] Yields the newly-parsed object to the block after parsing.
+    #     Sub-objects will be already populated.
+    def after_parse(&block)
+      after_parse_callbacks.push(block)
+    end
+
+    #
+    # Specify a namespace if a node and all its children are all namespaced
+    # elements. This is simpler than passing the :namespace option to each
+    # defined element.
+    #
+    # @param [String] namespace the namespace to set as default for the class
+    #     element.
+    #
+    def namespace(namespace = nil)
+      @namespace = namespace if namespace
+      @namespace
+    end
+
+    #
+    # @param [String] new_tag_name the name for the tag
+    #
+    def tag(new_tag_name)
+      @tag_name = new_tag_name.to_s unless new_tag_name.nil? || new_tag_name.to_s.empty?
+    end
+
+    #
+    # The name of the tag
+    #
+    # @return [String] the name of the tag as a string, downcased
+    #
+    def tag_name
+      @tag_name ||= to_s.split('::')[-1].downcase
+    end
+
+    # There is an XML tag that needs to be known for parsing and should be generated
+    # during a to_xml.  But it doesn't need to be a class and the contained elements should
+    # be made available on the parent class
+    #
+    # @param [String] name the name of the element that is just a place holder
+    # @param [Proc] blk the element definitions inside the place holder tag
+    #
+    def wrap(name, &blk)
+      # Get an anonymous XmlMapper that has 'name' as its tag and defined
+      # in '&blk'.  Then save that to a class instance variable for later use
+      wrapper = AnonymousWrapperClassFactory.get(name, &blk)
+      @wrapper_anonymous_classes[wrapper.inspect] = wrapper
+
+      # Create getter/setter for each element and attribute defined on the anonymous XmlMapper
+      # onto this class. They get/set the value by passing thru to the anonymous class.
+      passthrus = wrapper.attributes + wrapper.elements
+      passthrus.each do |item|
+        class_eval %{
+          def #{item.method_name}
+            @#{name} ||= self.class.instance_variable_get('@wrapper_anonymous_classes')['#{wrapper.inspect}'].new
+            @#{name}.#{item.method_name}
+          end
+          def #{item.method_name}=(value)
+            @#{name} ||= self.class.instance_variable_get('@wrapper_anonymous_classes')['#{wrapper.inspect}'].new
+            @#{name}.#{item.method_name} = value
+          end
+        }
+      end
+
+      has_one name, wrapper
+    end
+
+    # The callback defined through {.with_nokogiri_config}.
+    #
+    # @return [Proc] the proc to pass to Nokogiri to setup parse options. nil if empty.
+    #
+    def nokogiri_config_callback
+      @nokogiri_config_callback
+    end
+
+    # Register a config callback according to the block Nokogori expects when calling Nokogiri::XML::Document.parse().
+    # See http://nokogiri.org/Nokogiri/XML/Document.html#method-c-parse
+    #
+    # @param [Proc] the proc to pass to Nokogiri to setup parse options
+    #
+    def with_nokogiri_config(&blk)
+      @nokogiri_config_callback = blk
+    end
+
+    #
+    # @param [Nokogiri::XML::Node,Nokogiri:XML::Document,String] xml the XML
+    #     contents to convert into Object.
+    # @param [Hash] options additional information for parsing. :single => true
+    #     if requesting a single object, otherwise it defaults to retuning an
+    #     array of multiple items. :xpath information where to start the parsing
+    #     :namespace is the namespace to use for additional information.
+    #
+    def parse(xml, options = {})
+
+      # create a local copy of the objects namespace value for this parse execution
+      namespace = @namespace
+
+      # If the XML specified is an Node then we have what we need.
+      if xml.is_a?(Nokogiri::XML::Node) && !xml.is_a?(Nokogiri::XML::Document)
+        node = xml
+      else
+
+        # If xml is an XML document select the root node of the document
+        if xml.is_a?(Nokogiri::XML::Document)
+          node = xml.root
+        else
+
+          # Attempt to parse the xml value with Nokogiri XML as a document
+          # and select the root element
+          xml = Nokogiri::XML(
+            xml, nil, nil,
+            Nokogiri::XML::ParseOptions::STRICT,
+            &nokogiri_config_callback
+          )
+          node = xml.root
+        end
+
+        # if the node name is equal to the tag name then the we are parsing the
+        # root element and that is important to record so that we can apply
+        # the correct xpath on the elements of this document.
+
+        root = node.name == tag_name
+      end
+
+      # if any namespaces have been provied then we should capture those and then
+      # merge them with any namespaces found on the xml node and merge all that
+      # with any namespaces that have been registered on the object
+
+      namespaces = options[:namespaces] || {}
+      namespaces = namespaces.merge(xml.collect_namespaces) if xml.respond_to?(:collect_namespaces)
+      namespaces = namespaces.merge(@registered_namespaces)
+
+      # if a namespace has been provided then set the current namespace to it
+      # or set the default namespace to the one defined under 'xmlns'
+      # or set the default namespace to the namespace that matches 'xmlmapper's
+
+      if options[:namespace]
+        namespace = options[:namespace]
+      elsif namespaces.has_key?("xmlns")
+        namespace ||= DEFAULT_NS
+        namespaces[DEFAULT_NS] = namespaces.delete("xmlns")
+      elsif namespaces.has_key?(DEFAULT_NS)
+        namespace ||= DEFAULT_NS
+      end
+
+      # from the options grab any nodes present and if none are present then
+      # perform the following to find the nodes for the given class
+
+      nodes = options.fetch(:nodes) do
+
+        # when at the root use the xpath '/' otherwise use a more gready './/'
+        # unless an xpath has been specified, which should overwrite default
+        # and finally attach the current namespace if one has been defined
+        #
+
+        xpath  = (root ? '/' : './/')
+        xpath  = options[:xpath].to_s.sub(/([^\/])$/, '\1/') if options[:xpath]
+        xpath += "#{namespace}:" if namespace
+
+        nodes = []
+
+        # when finding nodes, do it in this order:
+        # 1. specified tag if one has been provided
+        # 2. name of element
+        # 3. tag_name (derived from class name by default)
+
+        # If a tag has been provided we need to search for it.
+
+        if options.key?(:tag)
+          begin
+            nodes = node.xpath(xpath + options[:tag].to_s, namespaces)
+          rescue
+            # This exception takes place when the namespace is often not found
+            # and we should continue on with the empty array of nodes.
+          end
+        else
+
+          # This is the default case when no tag value is provided.
+          # First we use the name of the element `items` in `has_many items`
+          # Second we use the tag name which is the name of the class cleaned up
+
+          [options[:name], tag_name].compact.each do |xpath_ext|
+            begin
+              nodes = node.xpath(xpath + xpath_ext.to_s, namespaces)
+            rescue
+              break
+              # This exception takes place when the namespace is often not found
+              # and we should continue with the empty array of nodes or keep looking
+            end
+            break if nodes && !nodes.empty?
+          end
+
+        end
+
+        nodes
+      end
+
+      # Nothing matching found, we can go ahead and return
+      return ( ( options[:single] || root ) ? nil : [] ) if nodes.size == 0
+
+      # 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.
+
+      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
+
+      collection = []
+
+      nodes.each_slice(limit) do |slice|
+
+        part = slice.map do |n|
+
+          # If an existing XmlMapper object is provided, update it with the
+          # values from the xml being parsed.  Otherwise, create a new object
+
+          obj = options[:update] ? options[:update] : new
+
+          attributes.each do |attr|
+            value = attr.from_xml_node(n, namespace, namespaces)
+            value = attr.default if value.nil?
+            obj.send("#{attr.method_name}=", value)
+          end
+
+          elements.each do |elem|
+            obj.send("#{elem.method_name}=",elem.from_xml_node(n, namespace, namespaces))
+          end
+
+          if @content
+            obj.send("#{@content.method_name}=",@content.from_xml_node(n, namespace, namespaces))
+          end
+
+          # If the XmlMapper 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(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
+          end
+
+          # If the XmlMapper 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(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
+          end
+
+          # Call any registered after_parse callbacks for the object's class
+
+          obj.class.after_parse_callbacks.each { |callback| callback.call(obj) }
+
+          # 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
+
+        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 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
+      end
+    end
+  end
+
+  # Set all attributes with a default to their default values
+  def initialize
+    super
+    self.class.attributes.reject {|attr| attr.default.nil?}.each do |attr|
+      send("#{attr.method_name}=", attr.default)
+    end
+  end
+
+  #
+  # Create an xml representation of the specified class based on defined
+  # XmlMapper elements and attributes. The method is defined in a way
+  # that it can be called recursively by classes that are also XmlMapper
+  # classes, allowg for the composition of classes.
+  #
+  # @param [Nokogiri::XML::Builder] builder an instance of the XML builder which
+  #     is being used when called recursively.
+  # @param [String] default_namespace The name of the namespace which is the
+  #     default for the xml being produced; this is the namespace of the
+  #     parent
+  # @param [String] namespace_override The namespace specified with the element
+  #     declaration in the parent. Overrides the namespace declaration in the
+  #     element class itself when calling #to_xml recursively.
+  # @param [String] tag_from_parent The xml tag to use on the element when being
+  #     called recursively.  This lets the parent doc define its own structure.
+  #     Otherwise the element uses the tag it has defined for itself.  Should only
+  #     apply when calling a child XmlMapper element.
+  #
+  # @return [String,Nokogiri::XML::Builder] return XML representation of the
+  #      XmlMapper object; when called recursively this is going to return
+  #      and Nokogiri::XML::Builder object.
+  #
+  def to_xml(builder = nil, default_namespace = nil, namespace_override = nil,
+             tag_from_parent = nil)
+
+    #
+    # If to_xml has been called without a passed in builder instance that
+    # means we are going to return xml output. When it has been called with
+    # a builder instance that means we most likely being called recursively
+    # and will return the end product as a builder instance.
+    #
+    unless builder
+      write_out_to_xml = true
+      builder = Nokogiri::XML::Builder.new
+    end
+
+    #
+    # Find the attributes for the class and collect them into an array
+    # that will be placed into a Hash structure
+    #
+    attributes = self.class.attributes.collect do |attribute|
+
+      #
+      # If an attribute is marked as read_only then we want to ignore the attribute
+      # when it comes to saving the xml document; so we wiill not go into any of
+      # the below process
+      #
+      unless attribute.options[:read_only]
+
+        value = send(attribute.method_name)
+        value = nil if value == attribute.default
+
+        #
+        # If the attribute defines an on_save lambda/proc or value that maps to
+        # a method that the class has defined, then call it with the value as a
+        # parameter.
+        #
+        if on_save_action = attribute.options[:on_save]
+          if on_save_action.is_a?(Proc)
+            value = on_save_action.call(value)
+          elsif respond_to?(on_save_action)
+            value = send(on_save_action,value)
+          end
+        end
+
+        #
+        # Attributes that have a nil value should be ignored unless they explicitly
+        # state that they should be expressed in the output.
+        #
+        if not value.nil? || attribute.options[:state_when_nil]
+          attribute_namespace = attribute.options[:namespace]
+          [ "#{attribute_namespace ? "#{attribute_namespace}:" : ""}#{attribute.tag}", value ]
+        else
+          []
+        end
+
+      else
+        []
+      end
+
+    end.flatten
+
+    attributes = Hash[ *attributes ]
+
+    #
+    # Create a tag in the builder that matches the class's tag name unless a tag was passed
+    # in a recursive call from the parent doc.  Then append
+    # any attributes to the element that were defined above.
+    #
+    builder.send("#{tag_from_parent || self.class.tag_name}_",attributes) do |xml|
+
+      #
+      # Add all the registered namespaces to the root element.
+      # When this is called recurisvely by composed classes the namespaces
+      # are still added to the root element
+      #
+      # However, we do not want to add the namespace if the namespace is 'xmlns'
+      # which means that it is the default namesapce of the code.
+      #
+      if self.class.instance_variable_get('@registered_namespaces') && builder.doc.root
+        self.class.instance_variable_get('@registered_namespaces').each_pair do |name,href|
+          name = nil if name == "xmlns"
+          builder.doc.root.add_namespace(name,href)
+        end
+      end
+
+      #
+      # If the object we are serializing has a namespace declaration we will want
+      # to use that namespace or we will use the default namespace.
+      # When neither are specifed we are simply using whatever is default to the
+      # builder
+      #
+      namespace_for_parent = namespace_override
+      if self.class.respond_to?(:namespace) && self.class.namespace
+        namespace_for_parent ||= self.class.namespace
+      end
+      namespace_for_parent ||= default_namespace
+
+      xml.parent.namespace =
+          builder.doc.root.namespace_definitions.find { |x| x.prefix == namespace_for_parent }
+
+
+      #
+      # When a content has been defined we add the resulting value
+      # the output xml
+      #
+      if content = self.class.instance_variable_get('@content')
+
+        unless content.options[:read_only]
+          text_accessor = content.tag || content.name
+          value = send(text_accessor)
+
+          if on_save_action = content.options[:on_save]
+            if on_save_action.is_a?(Proc)
+              value = on_save_action.call(value)
+            elsif respond_to?(on_save_action)
+              value = send(on_save_action,value)
+            end
+          end
+
+          builder.text(value)
+        end
+
+      end
+
+      #
+      # for every define element (i.e. has_one, has_many, element) we are
+      # going to persist each one
+      #
+      self.class.elements.each do |element|
+
+        #
+        # If an element is marked as read only do not consider at all when
+        # saving to XML.
+        #
+        unless element.options[:read_only]
+
+          tag = element.tag || element.name
+
+          #
+          # The value to store is the result of the method call to the element,
+          # by default this is simply utilizing the attr_accessor defined. However,
+          # this allows for this method to be overridden
+          #
+          value = send(element.name)
+
+          #
+          # If the element defines an on_save lambda/proc then we will call that
+          # operation on the specified value. This allows for operations to be
+          # performed to convert the value to a specific value to be saved to the xml.
+          #
+          if on_save_action = element.options[:on_save]
+            if on_save_action.is_a?(Proc)
+              value = on_save_action.call(value)
+            elsif respond_to?(on_save_action)
+              value = send(on_save_action,value)
+            end
+          end
+
+          #
+          # Normally a nil value would be ignored, however if specified then
+          # an empty element will be written to the xml
+          #
+          if value.nil? && element.options[:single] && element.options[:state_when_nil]
+            xml.send("#{tag}_","")
+          end
+
+          #
+          # To allow for us to treat both groups of items and singular items
+          # equally we wrap the value and treat it as an array.
+          #
+          if value.nil?
+            values = []
+          elsif value.respond_to?(:to_ary) && !element.options[:single]
+            values = value.to_ary
+          else
+            values = [value]
+          end
+
+          values.each do |item|
+
+            if item.is_a?(XmlMapper)
+
+              #
+              # Other items are convertable to xml through the xml builder
+              # process should have their contents retrieved and attached
+              # to the builder structure
+              #
+              item.to_xml(xml, self.class.namespace || default_namespace,
+                          element.options[:namespace],
+                          element.options[:tag] || nil)
+
+            elsif !item.nil?
+
+              item_namespace = element.options[:namespace] || self.class.namespace || default_namespace
+
+              #
+              # When a value exists we should append the value for the tag
+              #
+              if item_namespace
+                xml[item_namespace].send("#{tag}_",item.to_s)
+              else
+                xml.send("#{tag}_",item.to_s)
+              end
+
+            else
+
+              #
+              # Normally a nil value would be ignored, however if specified then
+              # an empty element will be written to the xml
+              #
+              xml.send("#{tag}_","") if element.options[:state_when_nil]
+
+            end
+
+          end
+
+        end
+      end
+
+    end
+
+    # Write out to XML, this value was set above, based on whether or not an XML
+    # builder object was passed to it as a parameter. When there was no parameter
+    # we assume we are at the root level of the #to_xml call and want the actual
+    # xml generated from the object. If an XML builder instance was specified
+    # then we assume that has been called recursively to generate a larger
+    # XML document.
+    write_out_to_xml ? builder.to_xml : builder
+
+  end
+
+  # Parse the xml and update this instance. This does not update instances
+  # of XmlMappers that are children of this object.  New instances will be
+  # created for any XmlMapper children of this object.
+  #
+  # Params and return are the same as the class parse() method above.
+  def parse(xml, options = {})
+    self.class.parse(xml, options.merge!(:update => self))
+  end
+
+  private
+
+  # Factory for creating anonmyous XmlMappers
+  class AnonymousWrapperClassFactory
+   def self.get(name, &blk)
+     Class.new do
+       include XmlMapper
+       tag name
+       instance_eval &blk
+     end
+   end
+  end
+
+end
+
+require 'xmlmapper/supported_types'
+require 'xmlmapper/item'
+require 'xmlmapper/attribute'
+require 'xmlmapper/element'
+require 'xmlmapper/text_node'