representable 1.3.5 → 1.4.0

data/CHANGES.textile

@@ -1,3 +1,8 @@
+h2. 1.4.0
+
+* We now have two strategies for representing: the old extend approach and the brand-new decorator which leaves represented objects untouched. See "README":https://github.com/apotonick/representable#decorator-vs-extend for details.
+* Internally, either extending or decorating in the Binding now happens through the representer class method `::prepare` (i.e. `Decorator::prepare` or `Representable::prepare` for modules). That means any representer module or class must expose this class method.
+
 h2. 1.3.5
 
 * Added `:reader` and `:writer` to allow overriding rendering/parsing of a property fragment and to give the user access to the entire document.

data/README.md

@@ -55,6 +55,12 @@ It also adds support for parsing.
     song = Song.new.extend(SongRepresenter).from_json(%{ {"title":"Roxanne"} })
     #=> #<Song title="Roxanne", track=nil>
 
+
+## Extend vs. Decorator
+
+If you don't want representer modules to be mixed into your objects (using `#extend`) you can use the `Decorator` strategy [described below](https://github.com/apotonick/representable#decorator-vs-extend). Decorating instead of extending was introduced in 1.4.
+
+
 ## Aliasing
 
 If your property name doesn't match the name in the document, use the `:as` option.
@@ -146,6 +152,30 @@ Parsing a documents needs both `:extend` and the `:class` option as the parser r
 
     #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]>
 
+## Decorator vs. Extend
+
+People who dislike `:extend` go use the `Decorator` strategy!
+
+    class SongRepresentation < Representable::Decorator
+      include Representable::JSON
+
+      property :title
+      property :track
+    end
+
+The `Decorator` constructor requires the represented object.
+
+    SongRepresentation.new(song).to_json
+
+This will leave the `song` instance untouched as the decorator just uses public accessors to represent the hit.
+
+In compositions you need to specify the decorators for the nested items using the `:decorator` option where you'd normally use `:extend`.
+
+    class AlbumRepresentation < Representable::Decorator
+      include Representable::JSON
+
+      collection :songs, :class => Song, :decorator => SongRepresentation
+    end
 
 ## XML Support
 

data/TODO

@@ -1,11 +1,9 @@
-* Pass key/index as first block arg to :class and :extendv
+* Pass key/index as first block arg to :class and :extend
 class: |key, hsh|
 
 * Allow passing options to Binding#serialize.
 	serialize(.., options{:exclude => ..})
 
-* Allow :writer and :reader / :getter/:setter
-
 document `XML::AttributeHash` etc
 
 * deprecate :from, make :a(lia)s authorative.
@@ -16,7 +14,7 @@ document `XML::AttributeHash` etc
 
 * have representable-options (:include, :exclude) and user-options
 
-
+* make all properties "Object-like", even arrays of strings etc.
 
 
 def compile_fragment(doc)
@@ -25,4 +23,6 @@ module ReaderWriter
     do whatever
     super
   end
-=> do that for all "features" (what parts would that be?: getter/setter, reader/writer, readable/writeable )?
+=> do that for all "features" (what parts would that be?: getter/setter, reader/writer, readable/writeable )?
+
+* alias :extend with :decorator

data/lib/representable.rb

@@ -87,7 +87,7 @@ private
     args = []
     args << binding.user_options if condition.arity > 0 # TODO: remove arity check. users should know whether they pass options or not.
 
-    not instance_exec(*args, &condition)
+    not represented.instance_exec(*args, &condition)
   end
 
   # TODO: remove in 1.4.
@@ -104,17 +104,26 @@ private
     @representable_attrs ||= self.class.representable_attrs # DISCUSS: copy, or better not?
   end
 
-  def representable_bindings_for(format, options)
-    options = cleanup_options(options)  # FIXME: make representable-options and user-options two different hashes.
-    representable_attrs.map {|attr| format.build(attr, self, options) }
-  end
-
   # Returns the wrapper for the representation. Mostly used in XML.
   def representation_wrap
     representable_attrs.wrap_for(self.class.name)
   end
 
 private
+  def representable_bindings_for(format, options)
+    options = cleanup_options(options)  # FIXME: make representable-options and user-options two different hashes.
+    representable_attrs.map {|attr| representable_binding_for(attr, format, options) }
+  end
+
+  def representable_binding_for(attribute, format, options)
+    # DISCUSS: shouldn't this happen in Binding?
+    format.build(attribute, represented, options)
+  end
+
+  def represented
+    self
+  end
+
   def cleanup_options(options) # TODO: remove me.
     options.reject { |k,v| [:include, :exclude].include?(k) }
   end
@@ -143,6 +152,10 @@ private
       end
     end
 
+    def prepare(represented)
+      represented.extend(self)  # was: PrepareStrategy::Extend.
+    end
+
 
     module Declarations
       def representable_attrs
@@ -227,3 +240,5 @@ private
     end
   end
 end
+
+require 'representable/decorator'

data/lib/representable/binding.rb

@@ -93,24 +93,23 @@ module Representable
     end
 
 
-    # Hooks into #serialize and #deserialize to extend typed properties
+    # Hooks into #serialize and #deserialize to setup (extend/decorate) typed properties
     # at runtime.
-    module Extend
+    module Prepare
       # Extends the object with its representer before serialization.
       def serialize(*)
-        extend_for(super)
+        prepare(super)
       end
 
       def deserialize(*)
-        extend_for(super)
+        prepare(super)
       end
 
-      def extend_for(object)
-        if mod = representer_module_for(object) # :extend.
-          object.extend(*mod)
-        end
+      def prepare(object)
+        return object unless mod = representer_module_for(object) # :extend.
 
-        object
+        mod = mod.first if mod.is_a?(Array) # TODO: deprecate :extend => [..]
+        mod.prepare(object)
       end
 
     private
@@ -125,8 +124,10 @@ module Representable
       end
     end
 
+    # Overrides #serialize/#deserialize to call #to_*/from_*.
+    # Computes :class in #deserialize. # TODO: shouldn't this be in a separate module? ObjectSerialize/ObjectDeserialize?
     module Object
-      include Binding::Extend  # provides #serialize/#deserialize with extend.
+      include Binding::Prepare
 
       def serialize(object)
         return object if object.nil?
@@ -136,7 +137,9 @@ module Representable
 
       def deserialize(data)
         # DISCUSS: does it make sense to skip deserialization of nil-values here?
-        super(create_object(data)).send(deserialize_method, data, @user_options)
+        create_object(data).tap do |obj|
+          super(obj).send(deserialize_method, data, @user_options)
+        end
       end
 
       def create_object(fragment)

data/lib/representable/decorator.rb

@@ -0,0 +1,19 @@
+module Representable
+  class Decorator
+    attr_reader :represented
+
+    def self.prepare(represented)
+      new(represented)  # was: PrepareStrategy::Decorate.
+    end
+
+    include Representable # include after class methods so Decorator::prepare can't be overwritten by Representable::prepare.
+
+    def initialize(represented)
+      @represented = represented
+    end
+
+    def representable_binding_for(attr, format, options)
+      format.build(attr, represented, options)
+    end
+  end
+end

data/lib/representable/definition.rb

@@ -3,14 +3,14 @@ module Representable
   class Definition
     attr_reader :name, :options
     alias_method :getter, :name
-    
+
     def initialize(sym, options={})
       @name     = sym.to_s
       @options  = options
-      
+
       @options[:default] ||= [] if array?  # FIXME: move to CollectionBinding!
     end
-    
+
     def clone
       self.class.new(name, options.clone) # DISCUSS: make generic Definition.cloned_attribute that passes list to constructor.
     end
@@ -18,48 +18,48 @@ module Representable
     def setter
       :"#{name}="
     end
-    
+
     def typed?
       sought_type.is_a?(Class) or representer_module or options[:instance]  # also true if only :extend is set, for people who want solely rendering.
     end
-    
+
     def array?
       options[:collection]
     end
-    
+
     def hash?
       options[:hash]
     end
-    
+
     def sought_type
       options[:class]
     end
-    
+
     def from
       (options[:from] || options[:as] || name).to_s
     end
-    
+
     def default_for(value)
       return default if skipable_nil_value?(value)
       value
     end
-    
+
     def has_default?
       options.has_key?(:default)
     end
-    
+
     def representer_module
-      options[:extend]
+      options[:extend] or options[:decorator]
     end
-    
+
     def attribute
       options[:attribute]
     end
-    
+
     def skipable_nil_value?(value)
       value.nil? and not options[:render_nil]
     end
-    
+
     def default
       options[:default]
     end

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "1.3.5"
+  VERSION = "1.4.0"
 end

data/test/representable_test.rb

@@ -303,6 +303,10 @@ class RepresentableTest < MiniTest::Spec
     end
 
     describe "passing options" do
+      class Track
+        attr_accessor :nr
+      end
+
       module TrackRepresenter
         include Representable::Hash
         property :nr
@@ -312,25 +316,25 @@ class RepresentableTest < MiniTest::Spec
           super
         end
         def from_hash(data, options)
-          super
-          @nr = options[:nr]
+          super.tap do
+            @nr = options[:nr]
+          end
         end
-        attr_accessor :nr
       end
 
       representer! do
-        property :track, :extend => TrackRepresenter
+        property :track, :extend => TrackRepresenter, :class => Track
       end
 
       describe "#to_hash" do
         it "propagates to nested objects" do
-          Song.new("Ocean Song", Object.new).extend(representer).to_hash(:nr => 9).must_equal({"track"=>{"nr"=>9}})
+          Song.new("Ocean Song", Track.new).extend(representer).to_hash(:nr => 9).must_equal({"track"=>{"nr"=>9}})
         end
       end
 
       describe "#from_hash" do
         it "propagates to nested objects" do
-          Song.new.extend(representer).from_hash({"track"=>{"nr" => "replace me"}}, :nr => 9).track.must_equal 9
+          Song.new.extend(representer).from_hash({"track"=>{"nr" => "replace me"}}, :nr => 9).track.nr.must_equal 9
         end
       end
     end
@@ -452,6 +456,31 @@ class RepresentableTest < MiniTest::Spec
       assert_equal "oh yes", band.fame
     end
 
+    describe "executing :if lambda in represented instance context" do
+      representer! do
+        property :label, :if => lambda { signed_contract }
+      end
+
+      subject { OpenStruct.new(:signed_contract => false, :label => "Fat") }
+
+      it "skips when false" do
+        subject.extend(representer).to_hash.must_equal({})
+      end
+
+      it "represents when true" do
+        subject.signed_contract= true
+        subject.extend(representer).to_hash.must_equal({"label"=>"Fat"})
+      end
+
+      it "works with decorator" do
+        rpr = representer
+        Class.new(Representable::Decorator) do
+          include rpr
+        end.new(subject).to_hash.must_equal({})
+      end
+    end
+
+
     describe "propagating user options to the block" do
       representer! do
         property :name, :if => lambda { |opts| opts[:include_name] }
@@ -506,12 +535,14 @@ class RepresentableTest < MiniTest::Spec
 
   describe ":extend and :class" do
     module UpcaseRepresenter
+      include Representable
       def to_hash(*); upcase; end
-      def from_hash(hsh, *args); self.class.new hsh.upcase; end   # DISCUSS: from_hash must return self.
+      def from_hash(hsh, *args); replace hsh.upcase; end   # DISCUSS: from_hash must return self.
     end
     module DowncaseRepresenter
+      include Representable
       def to_hash(*); downcase; end
-      def from_hash(hsh, *args); hsh.downcase; end
+      def from_hash(hsh, *args); replace hsh.downcase; end
     end
     class UpcaseString < String; end
 
@@ -533,7 +564,7 @@ class RepresentableTest < MiniTest::Spec
 
     describe ":instance" do
       obj = String.new("Fate")
-      mod = Module.new { def from_hash(*); self; end }
+      mod = Module.new { include Representable; def from_hash(*); self; end }
       representer! do
         property :name, :extend => mod, :instance => lambda { |name| obj }
       end
@@ -578,7 +609,7 @@ class RepresentableTest < MiniTest::Spec
 
         describe "when :class lambda returns nil" do
           representer! do
-            property :name, :extend => lambda { |name| Module.new { def from_hash(data, *args); data; end } },
+            property :name, :extend => lambda { |name| Module.new { include Representable; def from_hash(data, *args); data; end } },
                             :class  => nil
           end
 
@@ -618,6 +649,16 @@ class RepresentableTest < MiniTest::Spec
       end
     end
 
+    describe ":decorator" do
+      let (:extend_rpr) { Module.new { include Representable::Hash; collection :songs, :extend => SongRepresenter } }
+      let (:decorator_rpr) { Module.new { include Representable::Hash; collection :songs, :decorator => SongRepresenter } }
+      let (:songs) { [Song.new("Bloody Mary")] }
+
+      it "is aliased to :extend" do
+        Album.new(songs).extend(extend_rpr).to_hash.must_equal Album.new(songs).extend(decorator_rpr).to_hash
+      end
+    end
+
     describe ":binding" do
       representer! do
         class MyBinding < Representable::Binding
@@ -633,6 +674,58 @@ class RepresentableTest < MiniTest::Spec
       end
     end
 
+    describe "decorator" do
+      # TODO: Move to global place since it's used twice.
+      class SongRepresentation < Representable::Decorator
+        include Representable::JSON
+        property :name
+      end
+
+      class AlbumRepresentation < Representable::Decorator
+        include Representable::JSON
+
+        collection :songs, :class => Song, :extend => SongRepresentation
+      end
+
+      let (:song) { Song.new("Mama, I'm Coming Home") }
+      let (:album) { Album.new([song]) }
+      let (:decorator) { AlbumRepresentation.new(album) }
+
+      it "renders" do
+        decorator.to_hash.must_equal({"songs"=>[{"name"=>"Mama, I'm Coming Home"}]})
+        album.wont_respond_to :to_hash
+        song.wont_respond_to :to_hash # DISCUSS: weak test, how to assert blank slate?
+      end
+
+      it "parses" do
+        decorator.from_hash({"songs"=>[{"name"=>"Atomic Garden"}]})
+        album.songs.first.must_be_kind_of Song
+        album.songs.must_equal [Song.new("Atomic Garden")]
+        album.wont_respond_to :to_hash
+        song.wont_respond_to :to_hash # DISCUSS: weak test, how to assert blank slate?
+      end
+    end
+
+    describe "::prepare" do
+      let (:song) { Song.new("Still Friends In The End") }
+      let (:album) { Album.new([song]) }
+
+      describe "module including Representable" do
+        it "uses :extend strategy" do
+          album_rpr = Module.new { include Representable::Hash; collection :songs, :class => Song, :extend => SongRepresenter}
+
+          album_rpr.prepare(album).to_hash.must_equal({"songs"=>[{"name"=>"Still Friends In The End"}]})
+          album.must_respond_to :to_hash
+        end
+      end
+
+      describe "Decorator subclass" do
+        it "uses :decorate strategy" do
+          AlbumRepresentation.prepare(album).to_hash.must_equal({"songs"=>[{"name"=>"Still Friends In The End"}]})
+          album.wont_respond_to :to_hash
+        end
+      end
+    end
   end
 
   describe "Config" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.3.5
+  version: 1.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-18 00:00:00.000000000 Z
+date: 2013-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -176,6 +176,7 @@ files:
 - lib/representable/bindings/xml_bindings.rb
 - lib/representable/bindings/yaml_bindings.rb
 - lib/representable/coercion.rb
+- lib/representable/decorator.rb
 - lib/representable/definition.rb
 - lib/representable/deprecations.rb
 - lib/representable/feature/readable_writeable.rb
@@ -198,7 +199,6 @@ files:
 - test/hash_test.rb
 - test/json_test.rb
 - test/mongoid_test.rb
-- test/polymorphic_test.rb
 - test/representable_test.rb
 - test/test_helper.rb
 - test/test_helper_test.rb

data/test/polymorphic_test.rb

@@ -1,45 +0,0 @@
-require 'test_helper'
-
-module PolymorphicExtender
-  def self.extended(model)
-    model.extend(representer_name_for(model))
-  end
-  
-  def self.representer_name_for(model)
-    PolymorphicTest.const_get("#{model.class.to_s.split("::").last}Representer")
-  end
-end
-
-
-class PolymorphicTest < MiniTest::Spec
-  class PopSong < Song
-  end
-  
-  module SongRepresenter
-    include Representable::JSON
-    property :name
-  end
-  
-  module PopSongRepresenter
-    include Representable::JSON
-    property :name, :from => "known_as"
-  end
-  
-  class Album
-    attr_accessor :songs
-  end
-  
-  module AlbumRepresenter
-    include Representable::JSON
-    collection :songs, :extend => PolymorphicExtender
-  end
-  
-  
-  describe "PolymorphicExtender" do
-    it "extends each model with the correct representer in #to_json" do
-      album = Album.new
-      album.songs = [PopSong.new("Let Me Down"), Song.new("The 4 Horsemen")]
-      assert_equal "{\"songs\":[{\"known_as\":\"Let Me Down\"},{\"name\":\"The 4 Horsemen\"}]}", album.extend(AlbumRepresenter).to_json
-    end
-  end
-end