representable 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f465aa1b0aa43a6e5d2bacba9a09352679d2e9c0
-  data.tar.gz: 63ad7fd426a19a8efdc2ee5b06590a29507011fd
+  metadata.gz: b78042035b57cdc5c26ba4f5e5e9ad7ecc218256
+  data.tar.gz: 602635412709132eb114614ee69e53b9b73e31b2
 SHA512:
-  metadata.gz: 3d7a5b5b2f92d3fba72b01acace5bf14e40c80f8c55e82da3429b8870a67203eb681d2d777598848eec4d0515c9133a235ce5de36ea8365ecdc0d1d7597d7031
-  data.tar.gz: 0a76832f4640f6287abee2668ab58a867b65e573adfbbf71b1be44208215d068f5953dd88a7468b822208a20f3b78050f1f2f64ffdda87dc86b9bb9501386bfd
+  metadata.gz: 75a8db26513def9bf34f95e43ddc9edda28a8d8eda41d271b4e8b55bbad6b9dc4244d7d8d7a390996cf12907f68e71721cf940e9cbf6f4d6b6a53fd9095a4b56
+  data.tar.gz: 33a3d4c76452a0400897c3dc26c2ea66a9f5f15757ce9c87d35ddca65b4baa1ccdc740244dc4a70f39384b426075baa47d70af08fb9d835f4da94cb7ca51d68f

data/CHANGES.md

@@ -1,3 +1,9 @@
+h2. 1.6.1
+
+* Using `instance: lambda { nil }` will now treat the property as a representable object without trying to extend it. It simply calls `to_*/from_*` on the property.
+* You can use an inline representer and still have a `:extend` which will be automatically included in the inline representer. This is handy if you want to "extend" a base representer with an inline block. Thanks to @pixelvitamina for requesting that.
+* Allow inline representers with `collection`. Thanks to @rsutphin!
+
 h2. 1.6.0
 
 * You can define inline representers now if you don't wanna use multiple modules and files.

data/README.md

@@ -193,6 +193,17 @@ module AlbumRepresenter
 
 This works both for representer modules and decorators.
 
+You can use an inline representer along with `:extend`. The latter will automatically be included in the inline representer. This is handy if you want to inline-extend a base decorator.
+
+```ruby
+module AlbumRepresenter
+  include Representable::JSON
+
+  property :hit, extend: SongRepresenter do
+    property :numbers_sold
+  end
+```
+
 ## Decorator vs. Extend
 
 People who dislike `:extend` go use the `Decorator` strategy!
@@ -722,6 +733,38 @@ Coercing values only happens when rendering or parsing a document. Representable
 property :title, :binding => lambda { |*args| JSON::TitleBinding.new(*args) }
 ```
 
+* You can use the parsed document fragment directly as a representable instance by returning `nil` in `:class`.
+
+<!-- here comes some code -->
+```ruby
+property :song, :class => lambda { |*| nil }
+```
+
+This makes sense when your parsing looks like this.
+
+<!-- here comes some code -->
+```ruby
+hit.from_hash(song: <#Song ..>)
+```
+
+Representable will not attempt to create a `Song` instance for you but use the provided from the document.
+
+* The same goes the other way when rendering. Just provide an empty `:instance` block.
+
+<!-- here comes some code -->
+```ruby
+property :song, :instance => lambda { |*| nil }
+```
+
+This will treat the `song` property instance as a representable object.
+
+<!-- here comes some code -->
+```ruby
+hit.to_json # this will call hit.song.to_json
+```
+
+Rendering `collection`s works the same. Parsing doesn't work out-of-the-box, currently, as we're still unsure how to map items to fragments.
+
 ## Copyright
 
 Representable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his inspiring work.

data/lib/representable.rb

@@ -11,6 +11,7 @@ module Representable
       extend ClassInclusions, ModuleExtensions
       extend ClassMethods
       extend ClassMethods::Declarations
+      extend DSLAdditions
 
       include Deprecations
     end
@@ -77,7 +78,7 @@ private
     # Copies the representable_attrs to the extended object.
     def extended(object)
       super
-      object.representable_attrs=(representable_attrs)
+      object.representable_attrs=(representable_attrs) # yes, we want a hard overwrite here and no inheritance.
     end
   end
 
@@ -116,10 +117,6 @@ private
       #   property :name, :readable => false
       #   property :name, :writeable => false
       def property(name, options={}, &block)
-        if block_given? # DISCUSS: separate module?
-          options[:extend] = inline_representer(representer_engine, &block)
-        end
-
         (representable_attrs << definition_class.new(name, options)).last
       end
 
@@ -130,9 +127,9 @@ private
       #   collection :products
       #   collection :products, :from => :item
       #   collection :products, :class => Product
-      def collection(name, options={})
+      def collection(name, options={}, &block)
         options[:collection] = true
-        property(name, options)
+        property(name, options, &block)
       end
 
       def hash(name=nil, options={})
@@ -150,15 +147,29 @@ private
       def build_config
         Config.new
       end
+    end # Declarations
+  end
+
+  # Internal module for DSL sugar that should not go into the core library.
+  module DSLAdditions
+    def property(name, options={}, &block)
+      return super unless block_given?
+
+      inline = inline_representer(representer_engine, &block)
+      inline.module_eval { include options[:extend] } if options[:extend]
 
-      def inline_representer(base_module, &block) # DISCUSS: separate module?
-        Module.new do
-          include base_module
-          instance_exec &block
-        end
+      options[:extend] = inline
+      super
+    end
+
+  private
+    def inline_representer(base_module, &block) # DISCUSS: separate module?
+      Module.new do
+        include base_module
+        instance_exec &block
       end
     end
-  end
+  end # DSLAdditions
 end
 
 require 'representable/decorator'

data/lib/representable/binding.rb

@@ -162,7 +162,7 @@ module Representable
 
       def instance_for(fragment, *args)
         return unless options[:instance]
-        call_proc_for(options[:instance], fragment)
+        call_proc_for(options[:instance], fragment) or get
       end
     end
   end

data/lib/representable/bindings/hash_bindings.rb

@@ -4,17 +4,17 @@ module Representable
   module Hash
     module ObjectBinding
       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?
@@ -26,40 +26,40 @@ module Representable
         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)
       end
-      
+
       def write(hash, value)
         hash[from] = serialize_for(value)
       end
-      
+
       def serialize_for(value)
         serialize(value)
       end
-      
+
       def deserialize_from(fragment)
         deserialize(fragment)
       end
     end
-    
-    
+
+
     class CollectionBinding < PropertyBinding
       def serialize_for(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 { |obj| serialize(obj) }
+        value.collect { |item| serialize(item) }
       end
-      
+
       def deserialize_from(fragment)
         fragment.collect { |item_fragment| deserialize(item_fragment) }
       end
     end
-    
-    
+
+
     class HashBinding < PropertyBinding
       def serialize_for(value)
         # requires value to respond to #each with two block parameters.
@@ -67,7 +67,7 @@ module Representable
           value.each { |key, obj| hsh[key] = serialize(obj) }
         end
       end
-      
+
       def deserialize_from(fragment)
         {}.tap do |hsh|
           fragment.each { |key, item_fragment| hsh[key] = deserialize(item_fragment) }

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "1.6.0"
+  VERSION = "1.6.1"
 end

data/test/generic_test.rb

@@ -0,0 +1,91 @@
+require 'test_helper'
+
+class GenericTest < MiniTest::Spec
+# one day, this file will contain all engine-independent test cases. one day...
+  let (:new_album)  { OpenStruct.new.extend(representer) }
+  let (:album)      { OpenStruct.new(:songs => ["Fuck Armageddon"]).extend(representer) }
+  let (:song) { OpenStruct.new(:title => "Resist Stance").extend(song_representer) }
+  let (:song_representer) { Module.new do include Representable::Hash; property :title end  }
+
+
+  describe "::collection" do
+    representer! do
+      collection :songs
+    end
+
+    it "initializes property with empty array" do
+      new_album.from_hash({})
+      new_album.songs.must_equal [] # DISCUSS: do we really want this?
+    end
+
+    it "overrides property with empty array" do
+      album.from_hash({})
+      album.songs.must_equal [] # DISCUSS: do we really want this?
+    end
+  end
+
+
+  describe ":representable with property" do # TODO: introduce :representable option?
+    representer! do
+      property :song, :instance => lambda { |*| nil }
+    end
+
+    let (:hit) { hit = OpenStruct.new(:song => song).extend(representer) } # note that song is already representable.
+
+    it "calls #to_hash on song instance, nothing else" do
+      hit.to_hash.must_equal("song"=>{"title"=>"Resist Stance"})
+    end
+
+    it "calls #from_hash on the existing song instance, nothing else" do
+      song_id = hit.song.object_id
+      hit.from_hash("song"=>{"title"=>"Suffer"})
+      hit.song.title.must_equal "Suffer"
+      hit.song.object_id.must_equal song_id
+    end
+  end
+
+
+  describe ":representable with collection" do # TODO: introduce :representable option?
+    representer! do
+      collection :songs, :instance => lambda { |*| nil }
+    end
+    let (:album) { OpenStruct.new(:songs => [song]).extend(representer) }
+
+    it "calls #to_hash on song instances, nothing else" do
+      album.to_hash.must_equal("songs"=>[{"title"=>"Resist Stance"}])
+    end
+
+    it "calls #from_hash on the existing song instance, nothing else" do
+      album.songs.instance_eval do
+        def from_hash(items, *args)
+          #puts items #=> {"title"=>"Suffer"}
+          first.from_hash(items)  # example how you can use this.
+        end
+      end
+
+      song = album.songs.first
+      song_id = song.object_id
+      album.from_hash("songs"=>[{"title"=>"Suffer"}])
+      song.title.must_equal "Suffer"
+      song.object_id.must_equal song_id
+    end
+  end
+
+
+  describe "mix :extend and inline representers" do
+    representer! do
+      rpr_module = Module.new do
+        include Representable::Hash
+        property :title
+      end
+      property :song, :extend => rpr_module do
+        property :artist
+      end
+    end
+
+    it do OpenStruct.new(:song => OpenStruct.new(:title => "The Fever And The Sound", :artist => "Strung Out")).extend(representer).
+      to_hash.
+      must_equal({"song"=>{"artist"=>"Strung Out", "title"=>"The Fever And The Sound"}})
+    end
+  end
+end

data/test/hash_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
 require 'representable/hash'
 
-class YamlTest < MiniTest::Spec
+class HashTest < MiniTest::Spec
   def self.hash_representer(&block)
     Module.new do
       include Representable::Hash
@@ -59,6 +59,39 @@ class YamlTest < MiniTest::Spec
         end
       end
     end
+
+
+    describe "with :extend and :as" do
+      hash_song = hash_representer do property :name end
+
+      let (:hash_album) { Module.new do
+        include Representable::Hash
+        property :song, :extend => hash_song, :class => Song, :as => :hit
+      end }
+
+      let (:album) { OpenStruct.new(:song => Song.new("Liar")).extend(hash_album) }
+
+      it { album.to_hash.must_equal("hit" => {"name" => "Liar"}) }
+      it { album.from_hash("hit" => {"name" => "Go With Me"}).must_equal OpenStruct.new(:song => Song.new("Go With Me")) }
+    end
+    # describe "FIXME COMBINE WITH ABOVE with :extend and :as" do
+    #   hash_song = Module.new do
+    #     include Representable::XML
+    #     self.representation_wrap = :song
+    #     property :name
+    #   end
+
+    #   let (:hash_album) { Module.new do
+    #     include Representable::XML
+    #     self.representation_wrap = :album
+    #     property :song, :extend => hash_song, :class => Song, :as => :hit
+    #   end }
+
+    #   let (:album) { OpenStruct.new(:song => Song.new("Liar")).extend(hash_album) }
+
+    #   it { album.to_xml.must_equal_xml("<album><hit><name>Liar</name></hit></album>") }
+    #   #it { album.from_hash("hit" => {"name" => "Go With Me"}).must_equal OpenStruct.new(:song => Song.new("Go With Me")) }
+    # end
   end
 
 
@@ -86,7 +119,7 @@ class YamlTest < MiniTest::Spec
 
 
     describe "with :class and :extend" do
-      hash_song = hash_representer do 
+      hash_song = hash_representer do
         property :name
         property :track
       end
@@ -119,7 +152,7 @@ class YamlTest < MiniTest::Spec
   class DefinitionTest < MiniTest::Spec
     it "what" do
       class Representable::Hash::Binding < SimpleDelegator
-        
+
       end
 
       definition  = Representable::Definition.new(:name)

data/test/json_test.rb

@@ -398,7 +398,7 @@ end
         end
 
         it "creates emtpy array from default if configured" do
-          cd = Compilation.from_json({}.to_json)
+          cd = Compilation.from_json("{}")
           assert_equal [], cd.bands
         end
       end

data/test/representable_test.rb

@@ -452,6 +452,29 @@ class RepresentableTest < MiniTest::Spec
       end
     end
 
+    {
+      :hash => [Representable::Hash, {"songs"=>[{"name"=>"Alive"}]}, {"songs"=>[{"name"=>"You've Taken Everything"}]}],
+      :json => [Representable::JSON, "{\"songs\":[{\"name\":\"Alive\"}]}", "{\"songs\":[{\"name\":\"You've Taken Everything\"}]}"],
+      :xml  => [Representable::XML, "<open_struct>\n  <song>\n    <name>Alive</name>\n  </song>\n</open_struct>", "<open_struct><song><name>You've Taken Everything</name></song></open_struct>", { :from => :song }],
+      :yaml => [Representable::YAML, "---\nsongs:\n- name: Alive\n", "---\nsongs:\n- name: You've Taken Everything\n"],
+    }.each do |format, cfg|
+      mod, output, input, collection_options = cfg
+      collection_options ||= {}
+
+      describe "[#{format}] collection with :class" do
+        let (:request) { representer.prepare(OpenStruct.new(:songs => [song])) }
+
+        representer!(mod) do
+          collection :songs, collection_options.merge(:class => Song) do
+            property :name
+          end
+        end
+
+        it { request.send("to_#{format}").must_equal output }
+        it { request.send("from_#{format}", input).songs.first.name.must_equal "You've Taken Everything"}
+      end
+    end
+
     describe "without :class" do
       representer! do
         property :song do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-15 00:00:00.000000000 Z
+date: 2013-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -195,6 +195,7 @@ files:
 - test/decorator_test.rb
 - test/definition_test.rb
 - test/example.rb
+- test/generic_test.rb
 - test/hash_bindings_test.rb
 - test/hash_test.rb
 - test/inheritance_test.rb