xml-mapping_extensions 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df4aa8abcf1f0411d135fc696128f7d31f58aa70
-  data.tar.gz: 654c655782c2eeb1d0916960e5f3c3a294bb5926
+  metadata.gz: f68c4d7b4c7476a3c92353cc0f19762e847f560d
+  data.tar.gz: 1d1c1252d4dafe2ea164768aa63c7345ed16a126
 SHA512:
-  metadata.gz: c653214e5cf34f8a7f8a5cc2cb4ba9fb8a745873095aa405eb3a50eb14cc083f8a2071671b5e4e413fbbd8bf29f6fa8f8c51845df47242f7c86ec2662136c74f
-  data.tar.gz: 7f7e5cfaa402d787cd09c1b66b7c9bdf72f6e64a9b6f6c3a944f2153f8f88430bef6b6cede5acc2e847ff33daf206c5f8f6e184c879f276b19087cfe4e84f25b
+  metadata.gz: 0bbef3436e6917c064244eede751febb5fe568c9537429c2a108549c04b9386f34ec48179a5b6a68cac863344c0883e12845358b08f83ba62014dba94c14de34
+  data.tar.gz: ab29250ee7e8396e0ee6232080a422117192d3447206fd6a2c52e51afa3c0ad00bd4ec4ffdc4a4e28a3970563b9180ea88f970ce8908b8f5466edb9011a10d18

data/CHANGES.md

@@ -1,3 +1,7 @@
+## 0.3.2
+
+- Add `XML::Mapping#write_xml` and `XML::Mapping::ClassMethods#parse_xml`
+
 ## 0.3.1 (19 November 2015)
 
 - Update to [typesafe_enum](https://github.com/dmolesUC3/typesafe_enum) 0.1.2.

data/README.md

@@ -1,17 +1,64 @@
 # XML::MappingExtensions
 
-[![Build Status](https://travis-ci.org/dmolesUC3/xml-mapping_extensions.png?branch=master)](https://travis-ci.org/dmolesUC3/xml-mapping_extensions)
-[![Code Climate](https://codeclimate.com/github/dmolesUC3/xml-mapping_extensions.png)](https://codeclimate.com/github/dmolesUC3/xml-mapping_extensions)
-[![Inline docs](http://inch-ci.org/github/dmolesUC3/xml-mapping_extensions.png)](http://inch-ci.org/github/dmolesUC3/xml-mapping_extensions)
+[![Build Status](https://travis-ci.org/dmolesUC3/xml-mapping_extensions.svg?branch=master)](https://travis-ci.org/dmolesUC3/xml-mapping_extensions)
+[![Code Climate](https://codeclimate.com/github/dmolesUC3/xml-mapping_extensions.svg)](https://codeclimate.com/github/dmolesUC3/xml-mapping_extensions)
+[![Inline docs](http://inch-ci.org/github/dmolesUC3/xml-mapping_extensions.svg)](http://inch-ci.org/github/dmolesUC3/xml-mapping_extensions)
 [![Gem Version](https://img.shields.io/gem/v/xml-mapping_extensions.svg)](https://github.com/dmolesUC3/xml-mapping_extensions/releases)
 
-Additional mapping nodes and other utility classes for working with
+Additional mapping nodes and other utility code for working with
 [XML::Mapping](http://multi-io.github.io/xml-mapping/).
 
-## Usage
+## Extension methods
 
-Require `xml/mapping_extensions` and extend one of the abstract node
-classes, or use one of the provided implementations.
+This gem adds two methods, `write_xml` and `parse_xml`, to XML mapping instances and classes respectively, to reduce
+boilerplate.
+
+The `write_xml` method supplements [XML::Mapping#save_to_xml] by writing the object out as a `String` rather than as an `REXML::Element`.
+
+```ruby
+elem = MyElement.new
+elem.attribute = 123
+elem.text = 'element text'
+elem.children = ['child 1', 'child 2']
+puts elem.write_xml
+```
+
+outputs
+
+```xml
+<my-element attribute='123'>
+  element text
+  <child>child 1</child>
+  <child>child 2</child>
+</my-element>
+```
+
+The `parse_xml` method supplements
+[XML::Mapping::ClassMethods#load_from_xml](http://multi-io.github.io/xml-mapping/XML/Mapping/ClassMethods.html#method-i-load_from_xml)
+by abstracting away the difference between strings, XML documents, XML elements,
+files, and IO-like objects.
+
+```ruby
+my_xml_path = 'my_xml.xml'
+my_xml_file = File.new(my_xml_path)
+my_xml_string = File.read(my_xml_path)
+my_xml_io = StringIO.new(my_xml_string)
+my_xml_document = REXML::Document.new(my_xml_string)
+my_xml_element = my_xml_document.root
+
+# Standard XML::Mapping load_from_xml method
+elem = MyXMLClass.load_from_xml(my_xml_element)
+
+# parse_xml equivalent
+[my_xml_file, my_xml_string, my_xml_io, my_xml_document, my_xml_element].each do |xml_source|
+  expect(MyXMLClass.parse_xml(xml_source)).to eq(elem) # assuming MyXMLClass implements ==
+end
+```
+
+## Custom nodes
+
+To create a custom node type, require `xml/mapping_extensions` and extend one of
+the abstract node classes, or use one of the provided implementations.
 
 ### Abstract nodes
 
@@ -21,6 +68,21 @@ classes, or use one of the provided implementations.
 Note that you must call `::XML::Mapping.add_node_class` for your new node class
 to be registered with the XML mapping engine.
 
+#### Example
+
+```ruby
+class LaTeXRationalNode < XML::MappingExtensions::NodeBase
+  def to_value(xml_text)
+    match_data = /\\frac\{([0-9.]+)\}\{([0-9.]+)\}/.match(xml_text)
+    Rational("#{match_data[1]}/#{match_data[2]}")
+  end
+
+  def to_xml_text(value)
+    "\\frac{#{value.numerator}}{#{value.denominator}}"
+  end
+end
+```
+
 ### Provided implementations
 
 - `DateNode`: maps XML Schema dates to `Date` objects
@@ -29,7 +91,7 @@ to be registered with the XML mapping engine.
 - `MimeTypeNode`: maps MIME type strings to `MIME::Type` objects
 - `TypesafeEnumNode`: maps XML strings to [typesafe_enum](https://github.com/dmolesUC3/typesafe_enum) values
 
-### Example
+#### Example
 
 ```ruby
 require 'xml/mapping_extensions'

data/lib/xml/mapping_extensions/date_node.rb

@@ -5,13 +5,9 @@ require 'time'
 module XML
   module MappingExtensions
     # XML mapping for XML Schema dates.
-    # Known limitation: loses time zone info
+    # Known limitation: loses time zone info (Ruby `Date` doesn't
+    # support it)
     class DateNode < NodeBase
-
-      def initialize(*args)
-        super
-      end
-
       # Whether date should be output with UTC "Zulu" time
       # designator ("Z")
       # @return [Boolean, nil] True if date should be output
@@ -20,15 +16,17 @@ module XML
         @options[:zulu]
       end
 
-      # param xml_text [String] an XML Schema date
+      # Converts an XML Schema date string to a `Date` object
+      # @param xml_text [String] an XML Schema date
       # @return [Date] the value as a `Date`
       def to_value(xml_text)
         Date.xmlschema(xml_text)
       end
 
+      # Converts a `Date` object to an XML schema string
       # @param value [Date] the value as a `Date`
       # @return [String] the value as an XML Schema date string, without
-      #   time zone information
+      #   time zone information unless {#zulu} is set
       def to_xml_text(value)
         text = value.xmlschema
         zulu ? "#{text}Z" : text

data/lib/xml/mapping_extensions/typesafe_enum_node.rb

@@ -11,17 +11,27 @@ module XML
     #     # for node class MyEnum
     #     typesafe_enum_node :my_enum, '@my_enum', default_value: nil, class: MyEnum
     class TypesafeEnumNode < NodeBase
+
+      # Creates a new {TypesafeEnumNode}
+      # @param :class the enum class
       def initialize(*args)
         super
         @enum_class = @options[:class]
+        fail ArgumentError, "No :class found for TypesafeEnumNode #{@attrname} of #{@owner}" unless @enum_class
       end
 
+      # Converts an enum value or value string to an enum instance
+      # @param xml_text the enum value or value string
+      # @return [TypesafeEnum::Base] an instance of the enum class declared in the initializer
       def to_value(xml_text)
         enum_instance = @enum_class.find_by_value(xml_text)
         enum_instance = @enum_class.find_by_value_str(xml_text) unless enum_instance
         enum_instance
       end
 
+      # Converts an enum value or value string to an enum instance
+      # @param enum_instance [TypesafeEnum::Base] an instance of the enum class declared in the initializer
+      # @return [String] the enum value as a string
       def to_xml_text(enum_instance)
         enum_instance.value.to_s if enum_instance
       end

data/lib/xml/mapping_extensions/version.rb

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

data/lib/xml/mapping_extensions.rb

@@ -1,7 +1,60 @@
+require 'xml/mapping'
+
 module XML
   # Additional mapping nodes and other utility classes for working with
   # [XML::Mapping](http://multi-io.github.io/xml-mapping/)
   module MappingExtensions
     Dir.glob(File.expand_path('../mapping_extensions/*.rb', __FILE__), &method(:require))
   end
+
+  module Mapping
+
+    # Writes this mapped object as an XML string.
+    #
+    # @param options [Hash] the options to be passed to
+    #   [XML::Mapping#save_to_xml](http://multi-io.github.io/xml-mapping/XML/Mapping.html#method-i-save_to_xml)
+    # @return [String] the XML form of the object, as a compact, pretty-printed string.
+    def write_xml(options = { mapping: :_default })
+      xml = save_to_xml(options)
+      formatter = REXML::Formatters::Pretty.new
+      formatter.compact = true
+      io = StringIO.new
+      formatter.write(xml, io)
+      io.string
+    end
+
+    module ClassMethods
+      # 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]
+      # @return [Object] an instance of this class.
+      def parse_xml(xml)
+        element = case xml
+                  when REXML::Document
+                    xml.root
+                  when REXML::Element
+                    xml
+                  else
+                    fail ArgumentError, "Unexpected argument type; expected XML document, String, or IO source, was #{xml.class}" unless can_parse(xml)
+                    REXML::Document.new(xml).root
+                  end
+        load_from_xml(element)
+      end
+
+      private
+
+      # Whether the argument can be parsed as an `REXML::Document`, i.e. whether
+      # it is a `String` or something `IO`-like
+      # @param arg [Object] a possibly-parsable object
+      # @return [Boolean] true if `REXML::Document.new()` should be able to parse
+      #   the argument, false otherwise
+      def can_parse(arg)
+        arg.is_a?(String) ||
+          (arg.respond_to?(:read) &&
+            arg.respond_to?(:readline) &&
+            arg.respond_to?(:nil?) &&
+            arg.respond_to?(:eof?))
+      end
+    end
+  end
 end

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

@@ -0,0 +1,51 @@
+require 'spec_helper'
+
+module XML
+  module Mapping
+
+    class ArrayNodeSpecElem
+      include ::XML::Mapping
+
+      root_element_name 'array_node_spec_elem'
+
+      array_node :child_nodes, 'child_nodes', 'child_node', class: String
+    end
+
+    describe ArrayNode do
+      it 'reads nested nodes' do
+        xml_str = '<array_node_spec_elem>
+                     <child_nodes>
+                       <child_node>foo</child_node>
+                       <child_node>bar</child_node>
+                     </child_nodes>
+                   </array_node_spec_elem>'
+        xml = REXML::Document.new(xml_str).root
+        elem = ArrayNodeSpecElem.load_from_xml(xml)
+        expect(elem.child_nodes).to eq(%w(foo bar))
+      end
+
+      it 'writes nested nodes' do
+        elem = ArrayNodeSpecElem.new
+        elem.child_nodes = %w(foo bar)
+        xml = elem.save_to_xml
+        expected_xml = '<array_node_spec_elem>
+                          <child_nodes>
+                            <child_node>foo</child_node>
+                            <child_node>bar</child_node>
+                          </child_nodes>
+                        </array_node_spec_elem>'
+        expect(xml).to be_xml(expected_xml)
+      end
+
+      it 'writes empty intermediate nodes for empty arrays' do
+        elem = ArrayNodeSpecElem.new
+        elem.child_nodes = []
+        xml = elem.save_to_xml
+        expected_xml = '<array_node_spec_elem>
+                          <child_nodes/>
+                        </array_node_spec_elem>'
+        expect(xml).to be_xml(expected_xml)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+require 'spec_helper'
+require 'tempfile'
+
+module XML
+  module Mapping
+    class ParseXMLSpecElement
+      include ::XML::Mapping
+      include Comparable
+
+      root_element_name 'element'
+
+      numeric_node :attribute, '@attribute'
+      text_node :text, 'text()'
+      array_node :children, 'child', class: String
+
+      def <=>(other)
+        return nil unless self.class == other.class
+        [:attribute, :text, :children].each do |p|
+          order = send(p) <=> other.send(p)
+          return order if order != 0
+        end
+        0
+      end
+
+      def hash
+        [:attribute, :text, :children].hash
+      end
+    end
+
+    describe '#write_xml' do
+      it 'writes an XML string' do
+        elem = ParseXMLSpecElement.new
+        elem.attribute = 123
+        elem.text = 'element text'
+        elem.children = ['child 1', 'child 2']
+        expected_xml = elem.save_to_xml
+        xml_string = elem.write_xml
+        expect(xml_string).to be_a(String)
+        expect(xml_string).to be_xml(expected_xml)
+      end
+    end
+
+    module ClassMethods
+      describe '#parse_xml' do
+
+        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 = ParseXMLSpecElement.load_from_xml(@xml_element)
+        end
+
+        it 'parses a String' do
+          elem = ParseXMLSpecElement.parse_xml(@xml_string)
+          expect(elem).to eq(@expected_element)
+        end
+
+        it 'parses a REXML::Document' do
+          elem = ParseXMLSpecElement.parse_xml(@xml_document)
+          expect(elem).to eq(@expected_element)
+        end
+
+        it 'parses a REXML::Element' do
+          elem = ParseXMLSpecElement.parse_xml(@xml_element)
+          expect(elem).to eq(@expected_element)
+        end
+
+        it 'parses an IO' do
+          xml_io = StringIO.new(@xml_string)
+          elem = ParseXMLSpecElement.parse_xml(xml_io)
+          expect(elem).to eq(@expected_element)
+        end
+
+        it 'parses a file' do
+          xml_file = Tempfile.new(%w(parse_xml_spec .xml))
+          begin
+            xml_file.write(@xml_string)
+            xml_file.rewind
+            elem = ParseXMLSpecElement.parse_xml(xml_file)
+            expect(elem).to eq(@expected_element)
+          ensure
+            xml_file.close(true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,17 +7,34 @@ module XML
       include ::XML::Mapping
     end
 
+    class LaTeXRationalNode < NodeBase
+      def to_value(xml_text)
+        match_data = /\\frac\{([0-9.]+)\}\{([0-9.]+)\}/.match(xml_text)
+        Rational("#{match_data[1]}/#{match_data[2]}")
+      end
+
+      def to_xml_text(value)
+        "\\frac{#{value.numerator}}{#{value.denominator}}"
+      end
+    end
+
     describe NodeBase do
       before :each do
         @node = NodeBase.new(SomeMappingClass, :attr_name, 'attr_name')
       end
 
       describe '#extract_attr_value' do
-        it 'forwards to #to_value'
+        it 'forwards to #to_value' do
+          node = LaTeXRationalNode.new(SomeMappingClass, :attr_name, 'attr_name')
+          expect(node.to_value('\frac{1}{2}')).to eq(Rational('1/2'))
+        end
       end
 
       describe '#set_attr_value' do
-        it 'forwards to #to_xml_text'
+        it 'forwards to #to_xml_text' do
+          node = LaTeXRationalNode.new(SomeMappingClass, :attr_name, 'attr_name')
+          expect(node.to_xml_text(Rational('1/2'))).to eq('\frac{1}{2}')
+        end
       end
 
       describe '#xml_text' do

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

@@ -90,6 +90,16 @@ module XML
         elem = TypesafeEnumNodeSpecElem.load_from_xml(doc.root)
         expect(elem.save_to_xml).to be_xml(xml_string)
       end
+
+      it 'requires a class' do
+        expect do
+          class TypesafeEnumNodeSpecElem
+            include ::XML::Mapping
+
+            typesafe_enum_node :my_bad_enum, '@my_bad_enum'
+          end
+        end.to raise_error(ArgumentError)
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xml-mapping_extensions
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - David Moles
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-20 00:00:00.000000000 Z
+date: 2015-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mime-types
@@ -198,7 +198,9 @@ files:
 - spec/.rubocop.yml
 - spec/rspec_custom_matchers.rb
 - 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/mapping_extensions_spec.rb
 - spec/unit/xml/mapping_extensions/mime_type_node_spec.rb
 - spec/unit/xml/mapping_extensions/node_base_spec.rb
 - spec/unit/xml/mapping_extensions/time_node_spec.rb
@@ -233,7 +235,9 @@ test_files:
 - spec/.rubocop.yml
 - spec/rspec_custom_matchers.rb
 - 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/mapping_extensions_spec.rb
 - spec/unit/xml/mapping_extensions/mime_type_node_spec.rb
 - spec/unit/xml/mapping_extensions/node_base_spec.rb
 - spec/unit/xml/mapping_extensions/time_node_spec.rb