xml-mapping_extensions 0.4.3 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8846f750f369604e10e815fa58a11019c8dd8b3d
-  data.tar.gz: 3b05e612551a8d455108af3d7f351f5b6566b2e0
+  metadata.gz: 36f81c099c7ffafcad6ffa1af533b3a5f9ced684
+  data.tar.gz: 09a3a094c1855d14b2e3f89d72ba210bc0a7ede1
 SHA512:
-  metadata.gz: 89e7edf4af982cb52e5222f385d136911e4ca48e5719bff5c6576c691e151f152dc2ec6f91a6d6f997b1f1a6ae146677c208ae6c29f5375592498912e505bc07
-  data.tar.gz: 44b088113a9a0bc8f1335e1cc447977ca94ac9e516823c5bf436cb78060e7a2e73336a8b6208e6611ffe2ed080d2bca55eb4fea84a5334edaef1049c77033365
+  metadata.gz: b94a791a3a778e2e457e177a04c424011b012a422532aebfc9257a97ec08a3866b991a87b13df49f6ef8d65960e22fee4149426897437c5f74131e5b9ef8a14e
+  data.tar.gz: 247e5a8e25895cdbad0f3bddf62aafdde2dae6f89e77770e86fa22bd05d89741b0d36b342779851e2812cc55c7247e8d424639ce6c8b028fae5dac92e7e9a3b7

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 0.4.4 (12 July 2016)
+
+- Add '#fallback_mapping'
+
 ## 0.4.3 (11 July 2016)
 
 - Allow `write_xml` and `parse_xml` to take an `options` hash, to be passed on to `save_to_xml` or `load_from_xml`,

data/README.md

@@ -19,7 +19,7 @@ Additional mapping nodes and other utility code for working with
     - [Reading](#reading)
     - [Writing](#writing)
 - [Namespaces](#namespaces)
-
+- [Fallback mappings](#fallback-mappings)
 
 ## Extension methods
 
@@ -264,3 +264,63 @@ puts obj.write_xml
   <px:child>child 2</px:child>
 </px:element>
 ```
+
+## Fallback mappings
+
+The [XML::Mapping](http://multi-io.github.io/xml-mapping/) library provides an “alternate mapping”
+mechanism allowing
+[multiple XML mappings per class](http://multi-io.github.io/xml-mapping/#label-Multiple+Mappings+per+Class).
+However, it requires each mapping to be exhaustive -- an alternate mapping must redefine all attribute
+mappings defined in the primary, or else ignore those attributes. Sometimes, however, it is
+
+```ruby
+class ValidatingElement
+  include ::XML::Mapping
+
+  root_element_name 'element'
+  text_node :name, '@name'
+  text_node :value, '@value'
+
+  use_mapping :strict
+  numeric_node :value, '@value', writer: proc { |obj, xml| xml.add_attribute('value', Float(obj.value)) }
+end
+
+invalid_string = '<element name="abc" value="efg"/>'
+ValidatingElement.parse_xml(invalid_string, mapping: :strict)
+# ArgumentError: invalid value for Float(): "efg"
+
+elem = ValidatingElement.parse_xml(invalid_string) # OK
+# => #<XML::Mapping::ValidatingElement:0x007fa5631ae9c8>
+elem.write_xml
+# => "<element name='abc' value='efg'/>"
+
+elem.write_xml(mapping: :strict)
+# ArgumentError: invalid value for Float(): "efg"
+```
+
+So far, so good; but say we set a valid value and try to output with the
+`:strict` mapping?
+
+```ruby
+elem.value = 123
+elem.write_xml(mapping: :strict)
+# => <validating-element value='123'/>
+```
+
+Since the `:strict` mapping doesn't define a root element name, we get the
+default (based on the class name), and since it doesn't define a mapping
+for the `name` attribute, we lose that entirely.
+
+But if we add a fallback mapping --
+
+```ruby
+class ValidatingElement
+  fallback_mapping :strict, :_default
+end
+
+elem.write_xml(mapping: :strict)
+# => <element value='123' name='abc'/>
+```
+
+-- the `:strict` mapping now gets the root element name `element`,
+and the `name` attribute, as defined under the `:_default` mapping.

data/lib/xml/mapping_extensions/version.rb

@@ -1,6 +1,6 @@
 module XML
   module MappingExtensions
     # The version of this gem
-    VERSION = '0.4.3'
+    VERSION = '0.4.4'
   end
 end

data/lib/xml/mapping_extensions.rb

@@ -48,7 +48,18 @@ module XML
       io.string
     end
 
+    # Additional accessors needed for `#fallback_mapping`.
+    class Node
+      attr_reader :attrname
+      attr_accessor :mapping
+    end
+
     module ClassMethods
+
+      # Gets the configured root element names for this object.
+      # @return [Hash[Symbol, String]] the root element names for this object, by mapping.
+      attr_reader :root_element_names
+
       # Create a new instance of this class from the XML contained in
       # `xml`, which can be a string, REXML document, or REXML element
       # @param xml [String, REXML::Document, REXML::Element]
@@ -66,6 +77,26 @@ module XML
         load_from_xml(element, options)
       end
 
+      # Configures one mapping as a fallback for another, allowing mappings
+      # that differ e.g. from the default only in some small detail. Creates
+      # mapping nodes based on the fallback for all attributes for which a
+      # mapping node is present in the fallback but not in the primary, and
+      # likewise sets the root element name for the primary to the root element
+      # name for the fallback if it has not already been set.
+      #
+      # @param mapping [Symbol] the primary mapping
+      # @param fallback [Symbol] the fallback mapping to be used if the primary
+      #   mapping lacks a mapping node or root element name
+      def fallback_mapping(mapping, fallback)
+        mapping_nodes = nodes_by_attrname(mapping)
+        add_fallback_nodes(mapping_nodes, mapping, fallback)
+        xml_mapping_nodes_hash[mapping] = mapping_nodes.values
+
+        return if root_element_names[mapping]
+        fallback_name = root_element_names[fallback]
+        root_element_name(fallback_name, mapping: mapping)
+      end
+
       private
 
       # Whether the argument can be parsed as an `REXML::Document`, i.e. whether
@@ -76,9 +107,34 @@ module XML
       def can_parse(arg)
         arg.is_a?(String) ||
           (arg.respond_to?(:read) &&
-            arg.respond_to?(:readline) &&
-            arg.respond_to?(:nil?) &&
-            arg.respond_to?(:eof?))
+              arg.respond_to?(:readline) &&
+              arg.respond_to?(:nil?) &&
+              arg.respond_to?(:eof?))
+      end
+
+      # Returns the nodes for the specified mapping as a hash accessible by
+      # their attribute names.
+      # @param mapping [Symbol] the mapping
+      # @return [Hash[Symbol, Node]] the nodes
+      def nodes_by_attrname(mapping)
+        nodes = xml_mapping_nodes(mapping: mapping)
+        nodes.map { |node| [node.attrname, node] }.to_h
+      end
+
+      # Creates mapping nodes based on the fallback for all attributes for which a
+      # mapping node is present in the fallback but not in the primary.
+      # @param mapping_nodes [Hash[Symbol, Node]] The primary nodes
+      # @param mapping [Symbol] The primary mapping
+      # @param fallback [Symbol] The fallback mapping
+      def add_fallback_nodes(mapping_nodes, mapping, fallback)
+        xml_mapping_nodes(mapping: fallback).each do |fallback_node|
+          attrname = fallback_node.attrname
+          next if mapping_nodes.key?(attrname)
+
+          node = fallback_node.clone
+          fallback_node.mapping = mapping
+          mapping_nodes[attrname] = node
+        end
       end
     end
   end

data/spec/unit/xml/mapping_extensions/fallback_mapping_spec.rb

@@ -0,0 +1,97 @@
+require 'spec_helper'
+
+module XML
+  module Mapping
+    class FMSpecObject
+      include ::XML::Mapping
+
+      root_element_name 'element'
+
+      numeric_node :attribute, '@attribute'
+      text_node :text, 'text()'
+      array_node :children, 'child', class: String
+
+      use_mapping :alternate
+      text_node :attribute, '@attribute'
+      array_node :children, 'children',
+                 reader: (proc do |obj, xml|
+                   children_elem = xml.elements['children']
+                   obj.children = children_elem ? children_elem.text.split(',') : []
+                 end),
+                 writer: (proc do |obj, xml|
+                   children_text = obj.children.join(',') if obj.children && !obj.children.empty?
+                   xml.add_element('children').text = children_text if children_text
+                 end)
+
+      fallback_mapping :alternate, :_default
+    end
+
+    describe '#save_to_xml' do
+      it 'writes an XML string' do
+        obj = FMSpecObject.new
+        obj.attribute = 123
+        obj.text = 'element text'
+        obj.children = ['child 1', 'child 2']
+        saved_xml = obj.save_to_xml
+        expected_xml = '<element attribute="123">element text<child>child 1</child><child>child 2</child></element>'
+        expect(saved_xml).to be_xml(expected_xml)
+      end
+
+      it 'accepts an alternate mapping' do
+        obj = FMSpecObject.new
+        obj.attribute = 'elvis'
+        obj.text = 'element text'
+        obj.children = ['child 1', 'child 2']
+        saved_xml = obj.save_to_xml(mapping: :alternate)
+        expected_xml = '<element attribute="elvis">element text<children>child 1,child 2</children></element>'
+        expect(saved_xml).to be_xml(expected_xml)
+      end
+    end
+
+    describe '#parse_xml' do
+      it 'parses a String' do
+        xml_string = '<element attribute="123">element text<child>child 1</child><child>child 2</child></element>'
+        obj = FMSpecObject.parse_xml(xml_string)
+        expect(obj.attribute).to eq(123)
+        expect(obj.text).to eq('element text')
+        expect(obj.children).to eq(['child 1', 'child 2'])
+      end
+
+      it 'accepts an alternate mapping' do
+        xml_string = '<element attribute="elvis">element text<children>child 1,child 2</children></element>'
+        obj = FMSpecObject.parse_xml(xml_string, mapping: :alternate)
+        expect(obj.attribute).to eq('elvis')
+        expect(obj.text).to eq('element text')
+        expect(obj.children).to eq(['child 1', 'child 2'])
+      end
+    end
+
+    class ValidatingElement
+      include ::XML::Mapping
+
+      root_element_name 'element'
+      text_node :name, '@name'
+      text_node :value, '@value'
+
+      use_mapping :strict
+      numeric_node :value, '@value', writer: proc { |obj, xml| xml.add_attribute('value', Float(obj.value)) }
+
+      fallback_mapping :strict, :_default
+    end
+
+    describe '#fallback_mapping' do
+      it 'round-trips' do
+        invalid_string = '<element name="abc" value="efg"/>'
+        expect { ValidatingElement.parse_xml(invalid_string, mapping: :strict) }.to raise_error(ArgumentError)
+
+        elem = ValidatingElement.parse_xml(invalid_string) # OK
+        expect(elem.write_xml).to be_xml("<element name='abc' value='efg'/>")
+
+        expect { elem.write_xml(mapping: :strict) }.to raise_error(ArgumentError)
+
+        elem.value = 123.4
+        expect(elem.write_xml(mapping: :strict)).to be_xml("<element value='123.4' name='abc'/>")
+      end
+    end
+  end
+end

data/spec/unit/xml/mapping_extensions/mapping_extensions_spec.rb

@@ -14,7 +14,15 @@ module XML
       array_node :children, 'child', class: String
 
       use_mapping :alternate
-      text_node :text_alt, 'text()'
+      array_node :children, 'children',
+                 reader: (proc do |obj, xml|
+                   children_elem = xml.elements['children']
+                   obj.children = children_elem ? children_elem.text.split(',') : []
+                 end),
+                 writer: (proc do |obj, xml|
+                   children_text = obj.children.join(',') if obj.children && !obj.children.empty?
+                   xml.add_element('children').text = children_text if children_text
+                 end)
 
       def <=>(other)
         return nil unless self.class == other.class
@@ -45,67 +53,71 @@ module XML
       it 'accepts an alternate mapping' do
         obj = MXSpecObject.new
         obj.attribute = 123
-        obj.text_alt = 'element text'
         obj.children = ['child 1', 'child 2']
-        expected_xml = obj.save_to_xml(mapping: :alternate)
+        saved_xml = obj.save_to_xml(mapping: :alternate)
         xml_string = obj.write_xml(mapping: :alternate)
         expect(xml_string).to be_a(String)
-        expect(xml_string).to be_xml(expected_xml)
+        expect(xml_string).to be_xml(saved_xml)
       end
     end
 
-    module ClassMethods
-      describe '#parse_xml' do
+    describe '#parse_xml' do
 
-        before(:each) do
-          @xml_string = '<element attribute="123">
+      before(:each) do
+        @xml_string = '<element attribute="123">
                            element text
                            <child>child 1</child>
                            <child>child 2</child>
                          </element>'
-          @xml_document = REXML::Document.new(@xml_string)
-          @xml_element = @xml_document.root
-          @expected_element = MXSpecObject.load_from_xml(@xml_element)
-        end
+        @xml_document = REXML::Document.new(@xml_string)
+        @xml_element = @xml_document.root
+        @expected_element = MXSpecObject.load_from_xml(@xml_element)
+      end
 
-        it 'parses a String' do
-          obj = MXSpecObject.parse_xml(@xml_string)
-          expect(obj).to eq(@expected_element)
-        end
+      it 'parses a String' do
+        obj = MXSpecObject.parse_xml(@xml_string)
+        expect(obj).to eq(@expected_element)
+      end
 
-        it 'parses a REXML::Document' do
-          obj = MXSpecObject.parse_xml(@xml_document)
-          expect(obj).to eq(@expected_element)
-        end
+      it 'parses a REXML::Document' do
+        obj = MXSpecObject.parse_xml(@xml_document)
+        expect(obj).to eq(@expected_element)
+      end
 
-        it 'parses a REXML::Element' do
-          obj = MXSpecObject.parse_xml(@xml_element)
-          expect(obj).to eq(@expected_element)
-        end
+      it 'parses a REXML::Element' do
+        obj = MXSpecObject.parse_xml(@xml_element)
+        expect(obj).to eq(@expected_element)
+      end
+
+      it 'parses an IO' do
+        xml_io = StringIO.new(@xml_string)
+        obj = MXSpecObject.parse_xml(xml_io)
+        expect(obj).to eq(@expected_element)
+      end
 
-        it 'parses an IO' do
-          xml_io = StringIO.new(@xml_string)
-          obj = MXSpecObject.parse_xml(xml_io)
+      it 'parses a file' do
+        xml_file = Tempfile.new(%w(parse_xml_spec.xml))
+        begin
+          xml_file.write(@xml_string)
+          xml_file.rewind
+          obj = MXSpecObject.parse_xml(xml_file)
           expect(obj).to eq(@expected_element)
+        ensure
+          xml_file.close(true)
         end
+      end
 
-        it 'parses a file' do
-          xml_file = Tempfile.new(%w(parse_xml_spec .xml))
-          begin
-            xml_file.write(@xml_string)
-            xml_file.rewind
-            obj = MXSpecObject.parse_xml(xml_file)
-            expect(obj).to eq(@expected_element)
-          ensure
-            xml_file.close(true)
-          end
-        end
+      it 'accepts an alternate mapping' do
+        @xml_string = '<element attribute="123">
+                           element text
+                           <children>child 1,child 2</children>
+                         </element>'
+        @xml_document = REXML::Document.new(@xml_string)
+        @xml_element = @xml_document.root
 
-        it 'accepts an alternate mapping' do
-          @expected_element = MXSpecObject.load_from_xml(@xml_element, mapping: :alternate)
-          obj = MXSpecObject.parse_xml(@xml_element, mapping: :alternate)
-          expect(obj).to eq(@expected_element)
-        end
+        @expected_element = MXSpecObject.load_from_xml(@xml_element, mapping: :alternate)
+        obj = MXSpecObject.parse_xml(@xml_element, mapping: :alternate)
+        expect(obj).to eq(@expected_element)
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xml-mapping_extensions
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.4.4
 platform: ruby
 authors:
 - David Moles
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-11 00:00:00.000000000 Z
+date: 2016-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mime-types
@@ -202,6 +202,7 @@ files:
 - spec/spec_helper.rb
 - spec/unit/xml/mapping_extensions/array_node_spec.rb
 - spec/unit/xml/mapping_extensions/date_node_spec.rb
+- spec/unit/xml/mapping_extensions/fallback_mapping_spec.rb
 - spec/unit/xml/mapping_extensions/mapping_extensions_spec.rb
 - spec/unit/xml/mapping_extensions/mime_type_node_spec.rb
 - spec/unit/xml/mapping_extensions/namespace_spec.rb
@@ -241,6 +242,7 @@ test_files:
 - spec/spec_helper.rb
 - spec/unit/xml/mapping_extensions/array_node_spec.rb
 - spec/unit/xml/mapping_extensions/date_node_spec.rb
+- spec/unit/xml/mapping_extensions/fallback_mapping_spec.rb
 - spec/unit/xml/mapping_extensions/mapping_extensions_spec.rb
 - spec/unit/xml/mapping_extensions/mime_type_node_spec.rb
 - spec/unit/xml/mapping_extensions/namespace_spec.rb