serialisable 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d1e4397bf79459b96b569b558d46de21f445186
-  data.tar.gz: 6d175852e351b5bd7de719fb2ad63c7390b819d5
+  metadata.gz: 398799ae5550e1a9379df90c241567166e12eeb7
+  data.tar.gz: d785cbed52c32917be7d480a865f80dffcc1316d
 SHA512:
-  metadata.gz: 864ee9628a74de37b91a14615db426b6e9146b653d1846449dbfee1c51ea553d91192490b2522c45b73b2468b025cbbc8b00dffa8bc64c27cf09f2681a96f72f
-  data.tar.gz: 53d06c080b9c9c1650836e0e42fd310057c586999abb598db6d50c6a877ca314987e501ca508dc32a3564b69b0d7b0c829101db26d2f9438f59d14c5d8a5d3b5
+  metadata.gz: 1ff5997b676acdbc6335fc0d1525eaa3196738a0c398dfb5b35adbe2fc3291b57b0a7304ed4bdf9ed0e6f5a1087072df8a7e2e274407949b64a186e07fa3c4a8
+  data.tar.gz: 1c1d395a6771858063ff8ab519e1ffabf808a32365bda9933108af81bd0f27b18b41442e3e68077db0654c4854e78f6f448b5c08dae21d8250df984fec94d48c

data/lib/serialisable.rb

@@ -1,34 +1,218 @@
 require 'nokogiri'
-
+require_relative 'serialisable/selector'
+
+# Serialisable allows you to easily define an object that can deserialise xml
+# into instances of itself. It provides a simple but powerful DSL for defining
+# elements and attributes.
+#
+#   require 'serialisable'
+#   require 'time'
+#
+#   class Play
+#     extend Serialisable
+#
+#     root 'play'
+#     element :artist, 'artist'
+#     element :name, 'name'
+#     element :played_at, 'playedat', Time
+#   end
+#
+#   class User
+#     extend Serialisable
+#
+#     root 'user'
+#     attribute :id, 'id', :to_i
+#     element   :name, 'name'
+#     elements  :plays, 'plays', Play
+#
+#     def inspect
+#       "#<User:#{id} #{name}>"
+#     end
+#   end
+#
+#   user = User.deserialise <<XML
+#   <?xml version="1.0" encoding="utf-8"?>
+#   <user id="12452">
+#     <name>John Doe</name>
+#     <plays>
+#       <play>
+#         <artist>Arctic Monkeys</artist>
+#         <name>505</name>
+#         <playedat>2014-02-03T12:23:55Z</playedat>
+#       </play>
+#       <play>
+#         <artist>Aphex Twin</artist>
+#         <name>Windowlicker</name>
+#         <playedat>2014-02-03T12:26:13Z</playedat>
+#       </play>
+#     </plays>
+#   </user>
+#   XML
+#
+#   p user
+#   #=> #<User:12452 John Doe>
+#   p user.plays.map(&:name)
+#   #=> ["505", "Windowlicker"]
+#
+#
+# @example Type as Symbol
+#
+#   class Count
+#     extend Serialisable
+#
+#     root 'count'
+#     attribute :value, 'value', :to_i
+#   end
+#
+#   count = Count.deserialise <<XML
+#   <?xml version="1.0" encoding="utf-8"?>
+#   <count value="500" />
+#   XML
+#
+#   p count.value #=> 500
+#
+#
+# @example Type as object responding to +#parse+
+#
+#   class IntParser
+#     def parse(str); str.to_i; end
+#   end
+#
+#   class Count
+#     extend Serialisable
+#
+#     root 'count'
+#     attribute :value, 'value', IntParser
+#   end
+#
+#   count = Count.deserialise <<XML
+#   <?xml version="1.0" encoding="utf-8"?>
+#   <count value="500" />
+#   XML
+#
+#   p count.value #=> 500
+#
+#
 module Serialisable
+  def self.extended(obj)
+    obj.instance_variable_set(:@__selectors, [])
+  end
+
+  # Define the element that makes up the root for the class.
+  #
+  # @param selector [String] Name of xml element to mark as the root.
   def root(selector)
     @__root = selector
-    @__element = {}
-    @__elements = {}
-    @__attribute = {}
   end
 
-  def attribute(name, selector, type=String)
-    @__attribute[name] = [selector, type]
+  # Define an attribute selector. This will match an attribute in the defined
+  # root element that has the name given by +selector+.
+  #
+  # @param name [Symbol] Name of the method to be defined on the class that
+  #   returns the value matched.
+  # @param selector [String] Name of xml attribute to match against.
+  # @param type [Symbol, #parse] If a symbol is given the matched string will
+  #   have the method named by it called on it. If an object responding to
+  #   #parse is given then the string value will be passed to that method.
+  def attribute(name, selector, type = nil)
+    @__selectors << Selector::Attribute.new(name, selector, type)
   end
 
-  def element(name, selector, type=String)
-    @__element[name] = [selector, type]
+  # Define an element selector. This will match a node in the defined root
+  # element that has the name given by +selector+.
+  #
+  # @overload element(name, serialisable)
+  #   Use this when the node being matched contains nested xml.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param serialisable [Serialisable]
+  #
+  # @overload element(name, root, serialisable)
+  #   Use this when the node being matched contains nested xml and the root
+  #   needs to be set.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param root [String] Name of the root of the nested element, this
+  #     overrides any root set on the +serialisable+ passed.
+  #   @param serialisable [Serialisable] Serialisable object that represents
+  #     the nested element.
+  #
+  # @overload element(name, selector, type=nil)
+  #   Use this when the node only contains text.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param selector [String] Name of xml attribute to match against.
+  #   @param type [Symbol, #parse] If a symbol is given the matched string will
+  #     have the method named by it called on it. If an object responding to
+  #     #parse is given then the string value will be passed to that method.
+  #
+  def element(name, selector, type = nil)
+    if selector.respond_to?(:__deserialise, true)
+      @__selectors << Selector::Nested.new(name, selector)
+
+    elsif type.respond_to?(:__deserialise, true)
+      cloned_type = type.clone
+      cloned_type.instance_variable_set(:@__root, selector)
+      @__selectors << Selector::Nested.new(name, cloned_type)
+
+    else
+      @__selectors << Selector::Node.new(name, selector, type)
+    end
   end
 
-  def elements(name, *args)
-    case args.size
-    when 1
-      klass = args.first
-      @__elements[name] = [nil, klass]
-    when 2
-      selector, type = args
-      @__elements[name] = [selector, type]
+  # Define an elements selector. This will match all nodes in the defined root
+  # element that has the name given by +selector+. The method created by this
+  # will return an array of matching values.
+  #
+  # @overload elements(name, serialisable)
+  #   Use this when the nodes being matched contains nested xml.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param serialisable [Serialisable]
+  #
+  # @overload elements(name, root, serialisable)
+  #   Use this when the nodes being matched contains nested xml and the root
+  #   needs to be set.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param root [String] Name of the root of the nested element, this
+  #     overrides any root set on the +serialisable+ passed.
+  #   @param serialisable [Serialisable] Serialisable object that represents
+  #     the nested element.
+  #
+  # @overload elements(name, selector, type=nil)
+  #   Use this when the nodes only contain text.
+  #
+  #   @param name [Symbol] Name of the method to be defined on the class that
+  #     returns the value matched.
+  #   @param selector [String] Name of xml attribute to match against.
+  #   @param type [Symbol, #parse] If a symbol is given the matched string will
+  #     have the method named by it called on it. If an object responding to
+  #     #parse is given then the string value will be passed to that method.
+  #
+  def elements(name, selector, type = nil)
+    if selector.respond_to?(:__deserialise_all, true)
+      @__selectors << Selector::NestedMultiple.new(name, selector, type)
+
+    elsif type.respond_to?(:__deserialise_all, true)
+      cloned_type = type.clone
+      cloned_type.instance_variable_set(:@__root, selector)
+      @__selectors << Selector::NestedMultiple.new(name, cloned_type)
+
     else
-      raise ArgumentError
+      @__selectors << Selector::Nodes.new(name, selector, type)
     end
   end
 
+  # Deserialises the given +xml+ into an instance of the class.
+  #
+  # @param xml [String]
+  # @return An instance of the class that the method was called on.
   def deserialise(xml)
     __deserialise Nokogiri::XML(xml)
   end
@@ -37,99 +221,21 @@ module Serialisable
 
   def __deserialise_all(doc)
     doc = doc.children.find_all {|node| node.name == @__root }
-
-    attrs_list = doc.map do |node|
-      attrs = SerialisableHelpers.get_multiples(node, @__elements)
-      attrs += SerialisableHelpers.get_singles(node, @__element)
-      attrs += SerialisableHelpers.get_attributes(node, @__attribute)
-
-      attrs
-    end
-
-    objs = []
-    attrs_list.each do |attrs|
-      attrs = Hash[attrs]
-
-      attrs.each do |key, value|
-        define_method key do
-          instance_variable_get(:@__serialisable_attrs)[key]
-        end
-      end
-
-      obj = new
-      obj.instance_variable_set(:@__serialisable_attrs, attrs)
-      objs << obj
-    end
-
-    objs
+    doc.map {|node| __select(node) }
   end
 
   def __deserialise(doc)
-    doc = doc.children.find {|node| node.name == @__root }
-
-    attrs = SerialisableHelpers.get_multiples(doc, @__elements)
-    attrs += SerialisableHelpers.get_singles(doc, @__element)
-    attrs += SerialisableHelpers.get_attributes(doc, @__attribute)
-
-    attrs = Hash[attrs]
-
-    attrs.each do |key, value|
-      define_method key do
-        instance_variable_get(:@__serialisable_attrs)[key]
-      end
-    end
-
-    obj = new
-    obj.instance_variable_set(:@__serialisable_attrs, attrs)
-    obj
+    node = doc.children.find {|node| node.name == @__root }
+    __select(node)
   end
-end
-
-module SerialisableHelpers
-  extend self
 
-  def get_multiples(root, hash)
-    hash.map do |name, (selector, type)|
-      if type.respond_to?(:__deserialise_all, true)
-        [name, type.send(:__deserialise_all, root)]
-      else
-        values = root.children.find_all {|node| node.name == selector }
-          .map {|node| node.children.to_s }
-          .map {|value| parse_type(value, type) }
-
-        [name, values]
-      end
-    end
-  end
-
-  def get_singles(root, hash)
-    hash.map do |name, (selector, type)|
-      if selector.respond_to?(:__deserialise, true)
-        [name, selector.send(:__deserialise, root)]
-      else
-        value = root.children.find {|node| node.name == selector }.children.to_s
-        value = parse_type(value, type)
-
-        [name, value]
-      end
-    end
-  end
-
-  def get_attributes(root, hash)
-    hash.map do |name, (selector, type)|
-      value = root.attributes[selector].value
-      value = parse_type(value, type)
-
-      [name, value]
-    end
-  end
-
-  # Parses the value read from xml if the type given responds to the method
-  # #parse, otherwise returns the string value.
-  #
-  # @param value [String]
-  # @param type [#parse]
-  def parse_type(value, type)
-    type.respond_to?(:parse) ? type.parse(value) : value
+  def __select(node)
+    new.tap {|obj|
+      @__selectors.each {|selector|
+        obj.singleton_class.send(:define_method, selector.name) {
+          selector.match(node)
+        }
+      }
+    }
   end
 end

data/lib/serialisable/selector.rb

@@ -0,0 +1,57 @@
+module Serialisable
+
+  # @abstract Must implement #match
+  class Selector
+    attr_reader :name
+
+    def initialize(name, selector, type = nil)
+      @name = name
+      @selector = selector
+      @type = type
+    end
+
+    def parse(value)
+      if @type.respond_to?(:parse)
+        @type.parse(value)
+      elsif @type.is_a?(Symbol)
+        value.send(@type)
+      else
+        value
+      end
+    end
+
+    class Attribute < Selector
+      def match(root)
+        parse root.attributes[@selector].value
+      end
+    end
+
+    class Node < Selector
+      def match(root)
+        parse root.children
+          .find {|node| node.name == @selector }
+          .children.to_s
+      end
+    end
+
+    class Nodes < Selector
+      def match(root)
+        root.children
+          .find_all {|node| node.name == @selector }
+          .map {|node| parse node.children.to_s }
+      end
+    end
+
+    class Nested < Selector
+      def match(root)
+        @selector.send(:__deserialise, root)
+      end
+    end
+
+    class NestedMultiple < Selector
+      def match(root)
+        @selector.send(:__deserialise_all, root)
+      end
+    end
+  end
+end

data/lib/serialisable/version.rb

@@ -1,3 +1,3 @@
 module Serialisable
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/spec/serialisable/selector_spec.rb

@@ -0,0 +1,166 @@
+require_relative '../spec_helper'
+
+describe Serialisable::Selector do
+  describe '#name' do
+    let(:selector_name) { "some name" }
+    subject { Serialisable::Selector.new(selector_name, nil) }
+
+    it 'returns the name' do
+      subject.name.must_equal selector_name
+    end
+  end
+
+  describe Serialisable::Selector::Attribute do
+    describe '#match' do
+      describe 'when type not given' do
+        subject { Serialisable::Selector::Attribute.new(nil, 'hey') }
+
+        let(:xml) { '<el hey="1" what="5"/>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching attribute' do
+          subject.match(doc.children.first).must_equal "1"
+        end
+      end
+
+      describe 'when symbol given as type' do
+        subject { Serialisable::Selector::Attribute.new(nil, 'hey', :to_i) }
+
+        let(:xml) { '<el hey="1" what="5"/>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching attribute' do
+          subject.match(doc.children.first).must_equal 1
+        end
+      end
+
+      describe 'when object responding to #parse given as type' do
+        let(:type) { Class.new { def parse(v); v.to_i; end }.new }
+        subject { Serialisable::Selector::Attribute.new(nil, 'hey', type) }
+
+        let(:xml) { '<el hey="1" what="5"/>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching attribute' do
+          subject.match(doc.children.first).must_equal 1
+        end
+      end
+    end
+  end
+
+  describe Serialisable::Selector::Node do
+    describe '#match' do
+      describe 'when type not given' do
+        subject { Serialisable::Selector::Node.new(nil, 'hey') }
+
+        let(:xml) { '<el><hey>5</hey><what>6</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching node' do
+          subject.match(doc.children.first).must_equal "5"
+        end
+      end
+
+      describe 'when symbol given as type' do
+        subject { Serialisable::Selector::Node.new(nil, 'hey', :to_i) }
+
+        let(:xml) { '<el><hey>5</hey><what>6</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching node' do
+          subject.match(doc.children.first).must_equal 5
+        end
+      end
+
+      describe 'when object responding to #parse given as type' do
+        let(:type) { Class.new { def parse(v); v.to_i; end }.new }
+        subject { Serialisable::Selector::Node.new(nil, 'hey', type) }
+
+        let(:xml) { '<el><hey>5</hey><what>6</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching node' do
+          subject.match(doc.children.first).must_equal 5
+        end
+      end
+    end
+  end
+
+  describe Serialisable::Selector::Nodes do
+    describe '#match' do
+      describe 'when no type given' do
+        subject { Serialisable::Selector::Nodes.new(nil, 'hey') }
+
+        let(:xml) { '<el><hey>5</hey><hey>6</hey><what>7</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching nodes' do
+          subject.match(doc.children.first).must_equal ['5', '6']
+        end
+      end
+
+      describe 'when symbol given as type' do
+        subject { Serialisable::Selector::Nodes.new(nil, 'hey', :to_i) }
+
+        let(:xml) { '<el><hey>5</hey><hey>6</hey><what>7</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching nodes' do
+          subject.match(doc.children.first).must_equal [5, 6]
+        end
+      end
+
+      describe 'when object responding to #parse given as type' do
+        let(:type) { Class.new { def parse(v); v.to_i; end }.new }
+        subject { Serialisable::Selector::Nodes.new(nil, 'hey', type) }
+
+        let(:xml) { '<el><hey>5</hey><hey>6</hey><what>7</what></el>' }
+        let(:doc) { Nokogiri::XML(xml) }
+
+        it 'returns the matching nodes' do
+          subject.match(doc.children.first).must_equal [5, 6]
+        end
+      end
+    end
+  end
+
+  describe Serialisable::Selector::Nested do
+    describe '#match' do
+      let(:root)   { mock }
+      let(:nested) { mock }
+      let(:parsed) { mock }
+      subject { Serialisable::Selector::Nested.new(nil, nested, nil) }
+
+      before {
+        nested
+          .expects(:send)
+          .with(:__deserialise, root)
+          .returns(parsed)
+      }
+
+      it 'calls the private #__deserialise method' do
+        subject.match(root).must_equal parsed
+      end
+    end
+  end
+
+  describe Serialisable::Selector::NestedMultiple do
+    describe '#match' do
+      let(:root)   { mock }
+      let(:nested) { mock }
+      let(:parsed) { mock }
+      subject { Serialisable::Selector::NestedMultiple.new(nil, nested, nil) }
+
+      before {
+        nested
+          .expects(:send)
+          .with(:__deserialise_all, root)
+          .returns(parsed)
+      }
+
+      it 'calls the private #__deserialise_all method' do
+        subject.match(root).must_equal parsed
+      end
+    end
+  end
+end

data/spec/serialisable_spec.rb

@@ -79,6 +79,44 @@ EOS
         result.song.name.must_equal '505'
       end
     end
+
+    describe 'with a nested serialisable given a root' do
+      subject {
+        track = Class.new {
+          extend Serialisable
+
+          root 'track'
+          element :artist, 'artist'
+          element :name, 'name'
+        }
+
+        Class.new {
+          extend Serialisable
+
+          root 'songs'
+          element :song, 'song', track
+        }
+      }
+
+      let(:xml) {
+        <<EOS
+<?xml version="1.0" encoding="utf-8"?>
+<songs>
+  <song>
+    <artist>Arctic Monkeys</artist>
+    <name>505</name>
+  </song>
+</songs>
+EOS
+      }
+
+      it 'deserialises the nested object correctly' do
+        result = subject.deserialise(xml)
+
+        result.song.artist.must_equal 'Arctic Monkeys'
+        result.song.name.must_equal '505'
+      end
+    end
   end
 
   describe '#elements' do
@@ -149,24 +187,51 @@ EOS
       end
     end
 
-    it 'raises an exception if not given less than two arguments' do
-      lambda {
-        Class.new {
+    describe 'with a list of nested objects given a root' do
+      subject {
+        track = Class.new {
           extend Serialisable
 
-          elements :name
+          root 'track'
+          element :artist, 'artist'
+          element :name, 'name'
         }
-      }.must_raise ArgumentError
-    end
 
-    it 'raises an exception if given more than three arguments' do
-      lambda {
         Class.new {
           extend Serialisable
 
-          elements :name, 'one', 'two', 'three'
+          root 'songs'
+          elements :songs, 'song', track
         }
-      }.must_raise ArgumentError
+      }
+
+      let(:xml) {
+        <<EOS
+<?xml version="1.0" encoding="utf-8"?>
+<songs>
+  <song>
+    <artist>Arctic Monkeys</artist>
+    <name>505</name>
+  </song>
+  <song>
+    <artist>Aphex Twin</artist>
+    <name>Windowlicker</name>
+  </song>
+</songs>
+EOS
+      }
+
+      it 'takes xml and returns an object with a list of nested objects' do
+        result = subject.deserialise(xml)
+
+        result.songs.length.must_equal 2
+
+        result.songs[0].artist.must_equal 'Arctic Monkeys'
+        result.songs[0].name.must_equal '505'
+
+        result.songs[1].artist.must_equal 'Aphex Twin'
+        result.songs[1].name.must_equal 'Windowlicker'
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -1,4 +1,6 @@
 require 'minitest/autorun'
 require 'minitest/pride'
 
+require 'mocha/setup'
+
 require_relative '../lib/serialisable'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serialisable
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Joshua Hawxwell
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-08 00:00:00.000000000 Z
+date: 2014-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -16,42 +16,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.1
+        version: '1.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.1
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: '5.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.2.0
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: '1.0'
 description: |2
       Serialisable provides a simple DSL for turning xml into ruby objects.
 email: m@hawx.me
@@ -61,9 +61,11 @@ extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
+- lib/serialisable/selector.rb
 - lib/serialisable/version.rb
 - lib/serialisable.rb
 - spec/spec_helper.rb
+- spec/serialisable/selector_spec.rb
 - spec/serialisable_spec.rb
 homepage: http://github.com/hawx/serialisable
 licenses:
@@ -91,4 +93,6 @@ specification_version: 4
 summary: Serialisable allows easy xml deserialisation
 test_files:
 - spec/spec_helper.rb
+- spec/serialisable/selector_spec.rb
 - spec/serialisable_spec.rb
+has_rdoc: