representable 1.7.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8702c711c2230d338b5390e3e10cd7af901d41cf
-  data.tar.gz: fb5fd9498c58b6047a3ec221950f76c39d633c42
+  metadata.gz: 57ca6d3739a88e3c3e38ecb6b4aa0b33b5da43a4
+  data.tar.gz: fc6f1765a152cbbb9300f01c60ae8f55c169ec6d
 SHA512:
-  metadata.gz: 1a66be6a8a40fa284c674ae0ab63aa77e48cf9257be1de100a474cc0a14bffe2271172104b190f7fc9987eb6927402db5e9f24953d670a3733b619fef3ac2ae9
-  data.tar.gz: 7b89c5a30d057d6e47ebd34f2881acc7d94df6e25e4a42692ce38b92e457aff7a96b1be12bb25312d997fdf6c58cbad46af2906487b7badf78e58e99925a47b5
+  metadata.gz: ff20b22f94094d5bd9b99927c1f9ed28f82b74270d30d9eab5f8cab40facf22a8a9dbe9ccbb258ec68145489c8f81bd03766c6082f6c0a16c5f54d1f45610b61
+  data.tar.gz: 1c6c950c144548a986f55cdff935348ae253eee59339a3219416aba556aef22e59f707bf8ad9a30d3a3104314eb13ad1b67911ef2ccb10489bf6c21d0dda3f7c

data/CHANGES.md

@@ -1,3 +1,8 @@
+h2. 1.7.1
+
+* Introduce `Config#options` hash to store per-representer configuration.
+* The XML representer can now automatically remove namespaces when parsing. Use `XML::remove_namespaces!` in your representer. This is a work-around until namespaces are properly implemented in representable.
+
 h2. 1.7.0
 
 * The actual serialization and deserialization (that is, calling `to_hash` etc on the object) now happens in dedicated classes: `ObjectDeserializer` and friends. If you used to override stuff in `Binding`, I'm sorry.

data/README.md

@@ -174,6 +174,35 @@ Album.new.extend(AlbumRepresenter).
 #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]>
 ```
 
+## Syncing Objects
+
+Usually, representable creates a new nested object when parsing. If you want to update an existing object, use the `parse_strategy` option.
+
+```ruby
+module AlbumRepresenter
+  include Representable::JSON
+
+  collection :songs, extend: SongRepresenter, parse_strategy: :sync
+```
+
+When parsing an album, it will now call `from_json` on the existing songs in the collection.
+
+```ruby
+album = Album.find(1)
+album.songs.first #=> #<Song:0x999 title: "Panama">
+```
+
+Note that the album already contains a song instance.
+
+```ruby
+album.extend(AlbumRepresenter).
+  from_json('{songs: [{title: "Eruption"}]}')
+
+album.songs.first #=> #<Song:0x999 title: "Eruption">
+```
+
+Now, representable didn't create a new `Song` instance but updated the existing, resulting in renaming the song.
+
 ## Inline Representers
 
 If you don't want to maintain two separate modules when nesting representations you can define the `SongRepresenter` inline.
@@ -389,6 +418,21 @@ Song.new(:title => "Truth Hits Everybody", :copyright => "The Police").
 #=> {"title":"Truth Hits Everybody","copyright":"The Police"}
 ```
 
+## Overriding Properties
+
+You might want to override a particular property in an inheriting representer. Successively calling `property(name)` will override the former definition for `name` just as you know it from overriding methods.
+
+```ruby
+module CoverSongRepresenter
+  include Representable::JSON
+
+  include SongRepresenter        # defines property :title
+  property :title, as: :known_as # overrides that definition.
+end
+```
+
+This behaviour was added in 1.7.
+
 
 ## Polymorphic Extend
 
@@ -594,6 +638,17 @@ Album.new.to_xml #=>
 </album>
 ```
 
+### Namespaces
+
+Support for namespaces are not yet implemented. However, if an incoming parsed document contains namespaces, you can automatically remove them.
+
+```ruby
+module AlbumRepresenter
+  include Representable::XML
+
+  remove_namespaces!
+```
+
 ## Avoiding Modules
 
 There's been a rough discussion whether or not to use `extend` in Ruby. If you want to save that particular step when representing objects, define the representers right in your classes.

data/TODO

@@ -35,4 +35,6 @@ module ReaderWriter
 * make it easy to override Binding#options via #to_hash(whatever: {hit: {decorator: HitDecorator}})
 
 * DISCUSS: should inline representers be created at runtime, so we don't need ::representer_engine?
-* deprecate `Decorator::Coercion`.
+* deprecate `Decorator::Coercion`.
+
+* cleanup XML so it matches the current #serialize standard.

data/lib/representable/binding.rb

@@ -23,15 +23,6 @@ module Representable
 
     attr_reader :user_options, :represented # TODO: make private/remove.
 
-    # Main entry point for rendering/parsing a property object.
-    def serialize(value)
-      value
-    end
-
-    def deserialize(fragment, *args)
-      fragment
-    end
-
     # Retrieve value and write fragment to the doc.
     def compile_fragment(doc)
       represented_exec_for(:writer, doc) do

data/lib/representable/bindings/hash_bindings.rb

@@ -2,74 +2,62 @@ require 'representable/binding'
 
 module Representable
   module Hash
-    module ObjectBinding
+    class PropertyBinding < Representable::Binding
       include Binding::Object
 
-      def serialize_method
-        :to_hash
-      end
-
-      def deserialize_method
-        :from_hash
-      end
-    end
-
-
-    class PropertyBinding < Representable::Binding
       def self.build_for(definition, *args)  # TODO: remove default arg.
         return CollectionBinding.new(definition, *args)  if definition.array?
         return HashBinding.new(definition, *args)        if definition.hash?
         new(definition, *args)
       end
 
-      def initialize(*args) # FIXME. make generic.
-        super
-        extend ObjectBinding if typed?
-      end
-
       def read(hash)
         return FragmentNotFound unless hash.has_key?(from) # DISCUSS: put it all in #read for performance. not really sure if i like returning that special thing.
 
         fragment = hash[from]
-        deserialize_from(fragment)
+        deserialize(fragment)
       end
 
       def write(hash, value)
-        hash[from] = serialize_for(value)
-      end
-
-      def serialize_for(value)
-        serialize(value)
+        hash[from] = serialize(value)
       end
 
       def deserialize_from(fragment)
         deserialize(fragment)
       end
+
+      def serialize_method
+        :to_hash
+      end
+
+      def deserialize_method
+        :from_hash
+      end
     end
 
     class CollectionBinding < PropertyBinding
-      def serialize_for(value)
+      def serialize(value)
         # value.enum_for(:each_with_index).collect { |obj, i| serialize(obj, i) } # DISCUSS: provide ary index/hash key for representer_module_for?
-        value.collect { |item| serialize(item) } # TODO: i don't want Array but Forms here - what now?
+        value.collect { |item| super(item) } # TODO: i don't want Array but Forms here - what now?
       end
 
-      def deserialize_from(fragment)
+      def deserialize(fragment)
         CollectionDeserializer.new(self).deserialize(fragment)
       end
     end
 
 
     class HashBinding < PropertyBinding
-      def serialize_for(value)
+      def serialize(value)
         # requires value to respond to #each with two block parameters.
         {}.tap do |hsh|
-          value.each { |key, obj| hsh[key] = serialize(obj) }
+          value.each { |key, obj| hsh[key] = super(obj) }
         end
       end
 
-      def deserialize_from(fragment)
+      def deserialize(fragment)
         {}.tap do |hsh|
-          fragment.each { |key, item_fragment| hsh[key] = deserialize(item_fragment) }
+          fragment.each { |key, item_fragment| hsh[key] = super(item_fragment) }
         end
       end
     end

data/lib/representable/bindings/xml_bindings.rb

@@ -3,28 +3,9 @@ require 'representable/bindings/hash_bindings.rb'
 
 module Representable
   module XML
-    module ObjectBinding
+    class PropertyBinding < Binding
       include Binding::Object
 
-      def serialize_method
-        :to_node
-      end
-
-      def deserialize_method
-        :from_node
-      end
-
-      def content_for(node) # TODO: move to ScalarDecorator.
-        node
-      end
-
-      def serialize_node(node, value)
-        serialize(value)
-      end
-    end
-
-
-    class PropertyBinding < Binding
       def self.build_for(definition, *args)
         return CollectionBinding.new(definition, *args)      if definition.array?
         return HashBinding.new(definition, *args)            if definition.hash? and not definition.options[:use_attributes] # FIXME: hate this.
@@ -33,11 +14,6 @@ module Representable
         new(definition, *args)
       end
 
-      def initialize(*args)
-        super
-        extend ObjectBinding if typed? # FIXME.
-      end
-
       def write(parent, value)
         wrap_node = parent
 
@@ -63,6 +39,8 @@ module Representable
       end
 
       def serialize_node(node, value)
+        return serialize(value) if typed?
+
         node.content = serialize(value)
         node
       end
@@ -72,6 +50,15 @@ module Representable
         #deserialize(nodes.first)
       end
 
+      # DISCUSS: why is this public?
+      def serialize_method
+        :to_node
+      end
+
+      def deserialize_method
+        :from_node
+      end
+
     private
       def xpath
         from
@@ -88,6 +75,8 @@ module Representable
       end
 
       def content_for(node) # TODO: move this into a ScalarDecorator.
+        return node if typed?
+
         node.content
       end
     end

data/lib/representable/bindings/yaml_bindings.rb

@@ -2,57 +2,46 @@ require 'representable/binding'
 
 module Representable
   module YAML
-    module ObjectBinding
-      include Binding::Object
-
-      def serialize_method
-        :to_ast
-      end
-
-      def deserialize_method
-        :from_hash
-      end
-
-      def write_scalar(value)
-        value
-      end
-    end
-
     class PropertyBinding < Representable::Hash::PropertyBinding
       def self.build_for(definition, *args)
         return CollectionBinding.new(definition, *args) if definition.array?
         new(definition, *args)
       end
 
-      def initialize(*args) # FIXME. make generic.
-        super
-        extend ObjectBinding if typed?
-      end
-
       def write(map, value)
         map.children << Psych::Nodes::Scalar.new(from)
-        map.children << serialize_for(value)  # FIXME: should be serialize.
+        map.children << serialize(value)  # FIXME: should be serialize.
       end
 
-      def serialize_for(value)
-        write_scalar serialize(value)
+      def serialize(value)
+        write_scalar super(value)
       end
 
       def write_scalar(value)
+        return value if typed?
+
         Psych::Nodes::Scalar.new(value.to_s)
       end
+
+      def serialize_method
+        :to_ast
+      end
+
+      def deserialize_method
+        :from_hash
+      end
     end
 
 
     class CollectionBinding < PropertyBinding
-      def serialize_for(value)
+      def serialize(value)
         Psych::Nodes::Sequence.new.tap do |seq|
           seq.style = Psych::Nodes::Sequence::FLOW if options[:style] == :flow
           value.each { |obj| seq.children << super(obj) }
         end
       end
 
-      def deserialize_from(fragment)  # FIXME: redundant from Hash::Bindings
+      def deserialize(fragment)  # FIXME: redundant from Hash::Bindings
         CollectionDeserializer.new(self).deserialize(fragment)
       end
     end

data/lib/representable/config.rb

@@ -40,6 +40,11 @@ module Representable
       wrap
     end
 
+    # Write representer configuration into this hash.
+    def options
+      @options ||= {}
+    end
+
     module InheritMethods
       def cloned
         collect { |d| d.clone }

data/lib/representable/serializer.rb

@@ -2,7 +2,7 @@ require "representable/deserializer"
 
 module Representable
   class ObjectSerializer < ObjectDeserializer
-    def call
+    def call # TODO: make typed? switch here!
       return @object if @object.nil?
 
       representable = prepare(@object)
@@ -12,6 +12,9 @@ module Representable
 
   private
     def serialize(object, user_options)
+      # TODO: this used to be handled in #serialize where Object added it's behaviour. treat scalars as objects to remove this switch:
+      return object unless @binding.typed?
+
       object.send(@binding.serialize_method, user_options.merge!({:wrap => false}))
     end
   end

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "1.7.0"
+  VERSION = "1.7.1"
 end

data/lib/representable/xml.rb

@@ -14,6 +14,10 @@ module Representable
 
 
     module ClassMethods
+      def remove_namespaces!
+        representable_attrs.options[:remove_namespaces] = true
+      end
+
       # Creates a new Ruby object from XML using mapping information declared in the class.
       #
       # Accepts a block yielding the currently iterated Definition. If the block returns false
@@ -35,9 +39,9 @@ module Representable
       end
     end
 
-
     def from_xml(doc, *args)
-      node = Nokogiri::XML(doc).root
+      node = parse_xml(doc, *args)
+
       from_node(node, *args)
     end
 
@@ -55,5 +59,18 @@ module Representable
     def to_xml(*args)
       to_node(*args).to_s
     end
+
+  private
+    def remove_namespaces?
+      # TODO: make local Config easily extendable so you get Config#remove_ns? etc.
+      representable_attrs.options[:remove_namespaces]
+    end
+
+    def parse_xml(doc, *args)
+      node = Nokogiri::XML(doc)
+
+      node.remove_namespaces! if remove_namespaces?
+      node.root
+    end
   end
 end

data/test/config_test.rb

@@ -45,6 +45,14 @@ class ConfigTest < MiniTest::Spec
     it { subject["title"].must_equal definition }
   end
 
+  describe "#options" do
+    it { subject.options.must_equal({}) }
+    it do
+      subject.options[:namespacing] = true
+      subject.options[:namespacing].must_equal true
+    end
+  end
+
   describe "Config inheritance" do
     # TODO: this section will soon be moved to uber.
     describe "inheritance when including" do

data/test/json_test.rb

@@ -127,10 +127,6 @@ module JsonTest
       end
 
       describe "#build_for" do
-        it "returns ObjectBinding" do
-          assert_kind_of Representable::Hash::ObjectBinding, Representable::Hash::PropertyBinding.build_for(Def.new(:band, :class => Hash), nil)
-        end
-
         it "returns TextBinding" do
           assert_kind_of Representable::Hash::PropertyBinding, Representable::Hash::PropertyBinding.build_for(Def.new(:band), nil)
         end

data/test/xml_test.rb

@@ -80,6 +80,18 @@ class XmlTest < MiniTest::Spec
       end
     end
 
+    describe "#from_xml with remove_namespaces! and xmlns present" do
+      before do
+        @Band.remove_namespaces!
+        @band = @Band.new
+        @xml = %{<band xmlns="exists"><name>Nofx</name><label>NOFX</label></band>}
+      end
+
+      it "parses with xmlns present" do
+        @band.from_xml(@xml)
+        assert_equal ["Nofx", "NOFX"], [@band.name, @band.label]
+      end
+    end
 
     describe "#from_node" do
       before do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.7.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-31 00:00:00.000000000 Z
+date: 2013-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri