representable 1.2.9 → 1.3.0

data/test/json_test.rb

@@ -146,8 +146,9 @@ module JsonTest
 
       describe "#representable_bindings_for" do
         it "returns bindings for each property" do
-          assert_equal 2, @band.send(:representable_bindings_for, Representable::JSON::PropertyBinding).size
-          assert_equal "name", @band.send(:representable_bindings_for, Representable::JSON::PropertyBinding).first.name
+          bins = @band.send(:representable_bindings_for, Representable::JSON::PropertyBinding, {})
+          assert_equal 2, bins.size
+          assert_equal "name", bins.first.name
         end
       end
     end

data/test/representable_test.rb

@@ -1,15 +1,6 @@
 require 'test_helper'
 
 class RepresentableTest < MiniTest::Spec
-  def self.representer!(name=:representer, &block)
-    let(name) do
-      Module.new do
-        include Representable::Hash
-        instance_exec(&block)
-      end
-    end
-  end
-
   class Band
     include Representable
     property :name
@@ -257,10 +248,6 @@ class RepresentableTest < MiniTest::Spec
       assert_equal nil, @band.groupies
     end
     
-    it "still accepts deprecated :except option" do # FIXME: remove :except option.
-      assert_equal @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:except => [:groupies]}, Representable::Hash::PropertyBinding), @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:exclude => [:groupies]}, Representable::Hash::PropertyBinding)
-    end
-    
     it "accepts :include option" do
       @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:include => [:groupies]}, Representable::Hash::PropertyBinding)
       assert_equal 2, @band.groupies
@@ -282,6 +269,13 @@ class RepresentableTest < MiniTest::Spec
       @band.update_properties_from({"groupies"=>false}, {}, Representable::Hash::PropertyBinding)
       assert_equal false, @band.groupies
     end
+
+    it "ignores properties not present in the incoming document" do
+      @band.instance_eval do
+        def name=(*); raise "I should never be called!"; end
+      end
+      @band.update_properties_from({}, {}, Representable::Hash::PropertyBinding)
+    end
     
     it "ignores (no-default) properties not present in the incoming document" do
       { Representable::JSON => [{}, Representable::Hash::PropertyBinding], 
@@ -302,6 +296,39 @@ class RepresentableTest < MiniTest::Spec
         assert_equal nil, @band.name, "Failed in #{format}"
       end
     end
+
+    describe "passing options" do
+      module TrackRepresenter
+        include Representable::Hash
+        property :nr
+
+        def to_hash(options)
+          @nr = options[:nr]
+          super
+        end
+        def from_hash(data, options)
+          super
+          @nr = options[:nr]
+        end
+        attr_accessor :nr
+      end
+
+      representer! do
+        property :track, :extend => TrackRepresenter
+      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}})
+        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
+        end
+      end
+    end
   end
   
   describe "#create_representation_with" do
@@ -320,10 +347,6 @@ class RepresentableTest < MiniTest::Spec
       assert_equal({"name"=>"No One's Choice"}, hash)
     end
     
-    it "still accepts deprecated :except option" do # FIXME: remove :except option.
-      assert_equal @band.send(:create_representation_with, {}, {:except => [:groupies]}, Representable::Hash::PropertyBinding), @band.send(:create_representation_with, {}, {:exclude => [:groupies]}, Representable::Hash::PropertyBinding)
-    end
-    
     it "accepts :include option" do
       hash = @band.send(:create_representation_with, {}, {:include => [:groupies]}, Representable::Hash::PropertyBinding)
       assert_equal({"groupies"=>2}, hash)
@@ -375,6 +398,19 @@ class RepresentableTest < MiniTest::Spec
         assert_equal({"name"=>"No One's Choice", "groupies" => nil}, hash)
       end
     end
+
+    it "does not propagate private options to nested objects" do
+      cover_rpr = Module.new do
+        include Representable::Hash
+        property :title
+        property :original, :extend => self
+      end
+
+      # FIXME: we should test all representable-options (:include, :exclude, ?)
+
+      Class.new(OpenStruct).new(:title => "Roxanne", :original => Class.new(OpenStruct).new(:title => "Roxanne (Don't Put On The Red Light)")).extend(cover_rpr).
+        to_hash(:include => [:original]).must_equal({"original"=>{"title"=>"Roxanne (Don't Put On The Red Light)"}})
+    end
   end
   
   describe ":if" do
@@ -416,11 +452,11 @@ class RepresentableTest < MiniTest::Spec
   describe ":extend and :class" do
     module UpcaseRepresenter
       def to_hash(*); upcase; end
-      def from_hash(hsh); self.class.new hsh.upcase; end   # DISCUSS: from_hash must return self.
+      def from_hash(hsh, *args); self.class.new hsh.upcase; end   # DISCUSS: from_hash must return self.
     end
     module DowncaseRepresenter 
       def to_hash(*); downcase; end
-      def from_hash(hsh); hsh.downcase; end
+      def from_hash(hsh, *args); hsh.downcase; end
     end
     class UpcaseString < String; end
     
@@ -487,7 +523,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); data; end } },
+            property :name, :extend => lambda { |name| Module.new { def from_hash(data, *args); data; end } },
                             :class  => nil
           end
 

data/test/test_helper.rb

@@ -53,4 +53,13 @@ end
 MiniTest::Spec.class_eval do
   include AssertJson::Assertions
   include XmlHelper
+
+  def self.representer!(format=Representable::Hash, name=:representer, &block)
+    let(name) do
+      Module.new do
+        include format
+        instance_exec(&block)
+      end
+    end
+  end
 end

data/test/xml_test.rb

@@ -378,41 +378,63 @@ class CollectionTest < MiniTest::Spec
       end
     end
   end
-  
+
+  require 'representable/xml/collection'
+  class CollectionRepresenterTest < MiniTest::Spec
+    module SongRepresenter
+      include Representable::XML
+      property :name
+    end
+
+    describe "XML::Collection" do
+      describe "with contained objects" do
+        representer!(Representable::XML::Collection)  do
+          items :class => Song, :extend => SongRepresenter
+          self.representation_wrap= :songs
+        end
+
+        it "renders objects with #to_xml" do
+          assert_xml_equal "<songs><song><name>Days Go By</name></song><song><name>Can't Take Them All</name></song></songs>", [Song.new("Days Go By"), Song.new("Can't Take Them All")].extend(representer).to_xml
+        end
+
+        it "returns objects array from #from_xml" do
+          assert_equal [Song.new("Days Go By"), Song.new("Can't Take Them All")], [].extend(representer).from_xml("<songs><song><name>Days Go By</name></song><song><name>Can't Take Them All</name></song></songs>")
+        end
+      end
+    end
+  end
+
   require 'representable/xml/hash'
   describe "XML::AttributeHash" do  # TODO: move to HashTest.
-    before do
-      @songs_representer = Module.new do
-        include Representable::XML::AttributeHash
-        self.representation_wrap= :favs
-      end
+    representer!(Representable::XML::AttributeHash) do
+      self.representation_wrap= :favs
     end
     
     describe "#to_xml" do
       it "renders values into attributes converting values to strings" do
-        assert_xml_equal "<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(@songs_representer).to_xml
+        assert_xml_equal "<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(representer).to_xml
       end
       
       it "respects :exclude" do
-        assert_xml_equal "<favs two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(@songs_representer).to_xml(:exclude => [:one])
+        assert_xml_equal "<favs two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(representer).to_xml(:exclude => [:one])
       end
       
       it "respects :include" do
-        assert_xml_equal "<favs two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(@songs_representer).to_xml(:include => [:two])
+        assert_xml_equal "<favs two=\"Can't Take Them All\" />", {:one => :Graveyards, :two => "Can't Take Them All"}.extend(representer).to_xml(:include => [:two])
       end
     end
     
     describe "#from_json" do
       it "returns hash" do
-        assert_equal({"one" => "Graveyards", "two" => "Can't Take Them All"}, {}.extend(@songs_representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />"))
+        assert_equal({"one" => "Graveyards", "two" => "Can't Take Them All"}, {}.extend(representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />"))
       end
     
       it "respects :exclude" do
-        assert_equal({"two" => "Can't Take Them All"}, {}.extend(@songs_representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", :exclude => [:one]))
+        assert_equal({"two" => "Can't Take Them All"}, {}.extend(representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", :exclude => [:one]))
       end
       
       it "respects :include" do
-        assert_equal({"one" => "Graveyards"}, {}.extend(@songs_representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", :include => [:one]))
+        assert_equal({"one" => "Graveyards"}, {}.extend(representer).from_xml("<favs one=\"Graveyards\" two=\"Can't Take Them All\" />", :include => [:one]))
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.2.9
+  version: 1.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-04 00:00:00.000000000 Z
+date: 2013-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -148,12 +148,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- .rspec
 - .travis.yml
 - CHANGES.textile
 - Gemfile
-- LICENSE
-- README.rdoc
+- README.md
 - Rakefile
 - TODO
 - gemfiles/Gemfile.mongoid-2.4

data/.rspec

@@ -1 +0,0 @@
---colour

data/LICENSE

@@ -1,20 +0,0 @@
-Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,416 +0,0 @@
-= Representable
-
-<em>Maps documents to Ruby objects and back.</em>
-
-
-== Introduction
-
-_Representable_ maps fragments in documents to attributes in Ruby objects and back. It allows parsing representations giving an object-oriented interface to the document. But that's only half of it! Representable can also render documents from an object instance. 
-
-This keeps your representation knowledge in one place when implementing REST services and clients.
-
-
-== Features
-
-* Bidirectional - rendering and parsing
-* OOP access to documents
-* Support for JSON, XML and YAML.
-* Coercion support with virtus[https://github.com/solnic/virtus]
-
-
-== Example
-
-Since you keep forgetting the heroes of your childhood you decide to implement a REST service for storing and querying those. You choose representable for handling representations.
-
-  gem 'representable'
-
-
-== Defining Representations
-
-Representations are usually defined using a module. This makes them super flexibly, you'll see.
-
-  require 'representable/json'
-
-  module HeroRepresenter
-    include Representable::JSON
-    
-    property :forename
-    property :surename
-  end
-
-By using #property we declare two simple attributes that should be considered when representing.
-
-To use your representer include it in the matching class. Note that you could reuse a representer in multiple classes. The represented class must have getter and setter methods for each property.
-
-  class Hero
-    attr_accessor :forename, :surename
-  	
-    include Representable
-    include HeroRepresenter
-  end
-
-Many people dislike including representers on class layer. You might also extend an object at runtime.
-
-  Hero.new.extend(HeroRepresenter)
-
-Alternatively, if you don't like modules (which you shouldn't),  declarations can be put into classes directly. We call that inline representers.
-
-  class Hero
-    attr_accessor :forename, :surename
-  	
-    include Representable::JSON
-    
-    property :forename
-    property :surename
-  end
-
-
-== Rendering
-
-Now let's create and render our first hero.
-
-  peter = Hero.new
-  peter.forename = "Peter"
-  peter.surename = "Pan"
-
-  peter.to_json
-  #=> {"forename":"Peter","surename":"Pan"}
-
-Those two properties are considered when rendering in #to_json.
-
-== Parsing
-
-The cool thing about Representable is: it works bidirectional. The document definition in your representer module can also be used for parsing documents and assigning property values.
-
-  hook = Hero.from_json('{"forename":"Captain","surename":"Hook"}')
-  hook.forename #=> "Captain"
-  
-See how easy this is? You can use an object-oriented method to read from the document. 
-
-== Nesting
-
-You need a second domain object. Every hero has a place it comes from.
-
-  class Location
-    attr_accessor :title
-  	
-    include Representable::JSON
-    
-    property :title
-  end
-
-Peter, where ya' from?
-  
-  neverland = Location.new
-  neverland.title = "Neverland"
-
-It makes sense to embed the location in the hero's document.
-
-  module HeroRepresenter
-    property :origin, :class => Location
-  end
-
-Using the +:class+ option allows you to include other representable objects.
-
-  peter.origin = neverland
-  peter.to_json
-  #=> {"forename":"Peter","surename":"Pan","origin":{"title":"Neverland"}}
-
-
-== Parsing Nested Documents
-
-Don't forget how easy it is to parse nested representations.
-
-  hook = Hero.from_json('{"name":"Captain","surename":"Hook","origin":{"title":"Dark Ocean"}}')
-  hook.origin.inspect #=> #<Location:0x910d7c8 @title="Dark Ocean">
-  hook.origin.title #=> "Dark Ocean"
-
-Representable just creates objects from the parsed document - nothing more and nothing less.
-
-== Simple Collections
-
-Heroes have features, special abilities that make 'em a superhero.
-
-  module HeroRepresenter
-    collection :features
-  end
-
-The second representable API method is +collection+ and, well, declares a collection.
-
-  peter.features = ["stays young", "can fly"]
-  peter.to_json
-  #=> {"forename":"Peter","surename":"Pan","origin":{"title":"Neverland"},"features":["stays young","can fly"]}
-
-
-== Typed Collections
-
-Ok, things start working out. Your hero has a name, an origin and a list of features so far. Why not allow adding buddies to Peter - nobody wants to be alone!
-
-  module HeroRepresenter
-    collection :friends, :class => Hero
-  end
-
-Again, we type the collection by using the +:class+ option.
-
-  nick = Hero.new
-  nick.forename = "Nick"
-
-  el = Hero.new
-  el.forename = "El"
-
-  peter.friends = [nick, el]
-
-I always wanted to be Peter's bro... in this example it is possible! 
-  
-  peter.to_json
-  #=> {"forename":"Peter","surename":"Pan","origin":{"title":"Neverland"},"features":["stays young","can fly"],"friends":[{"name":"Nick"},{"name":"El"}]}
-
-
-== Hashes
-
-Hashes can be represented the same way collections work. Here, use the #hash class method. 
-
-== Lonely Collections
-
-Need an array represented without any wrapping?
-
-  ["stays young", "can fly"].extend(Representable::JSON::Collection).to_json
-  #=> "[\"stays young\", \"can fly\"]"
-  
-You can use #items to configure the element representations contained in the array.
-
-  module FeaturesRepresenter
-    include Representable::JSON::Collection
-    
-    items :class => Hero, :extend => HeroRepresenter
-  end
-
-Collections and hashes can also be deserialized. Note that this also works for XML.
-
-== Lonely Hashes
-
-The same goes with hashes where #values lets you configure the hash's values.
-
-  module FriendsRepresenter
-    include Representable::JSON::Hash
-    
-    values :class => Hero, :extend => HeroRepresenter
-  end
-  
-  {:stu => Hero.new("Stu"), :clive => Hero.new("Cleavage")}.extend(FriendsRepresenter).to_json
-
-In XML, if you want to store hash attributes in tag attributes instead of dedicated nodes, use XML::AttributeHash.
-
-
-== Customizing
-
-=== Wrapping
-
-Representable is designed to be very simple. However, a few tweaks are available. What if you want to wrap your document?
-
-  module HeroRepresenter
-    self.representation_wrap = true
-  end
-
-  peter.to_json #=> {"hero":{"name":"Peter","surename":"Pan"}}
-
-You can also provide a custom wrapper.
-
-  module HeroRepresenter
-    self.representation_wrap = :boy
-  end
-
-  peter.to_json #=> {"boy":{"name":"Peter","surename":"Pan"}}
-
-
-=== Mapping
-
-If your accessor name doesn't match the attribute name in the document, use the +:from+ matcher.
-
-  module HeroRepresenter
-    property :forename, :from => :i_am_called
-  end
-  
-  peter.to_json #=> {"i_am_called":"Peter","surename":"Pan"}
-
-
-=== Filtering and Conditions
-
-Representable allows you to skip and include properties when rendering or parsing.
-
-  peter.to_json(:include => :forename)
-  #=> {"forename":"Peter"}
-
-It gives you convenient +:exclude+ and +:include+ options.
-
-You can also define conditions on properties on the class layer.
-
-  module HeroRepresenter
-    property :friends, :if => lambda { forename == "Peter" }
-  end
-  
-When rendering or parsing, the +friends+ property is considered only if the condition block evals to true. Note that the block is executed in instance context, giving you access to instance methods.
-
-=== False and Nil Values
-
-Since 1.2 +false+ values are considered when parsing and rendering. That particularly means properties that used to be unset (i.e. +nil+) after parsing might be +false+ now. Vice versa, +false+ values that weren't included in the rendered document will be visible now.
-
-If you want +nil+ values to be included when rendering, use the +:render_nil+ option.
-
-  property :surename, :render_nil => true
-
-== DCI
-
-Representers roughly follow the {DCI}[http://en.wikipedia.org/wiki/Data,_context_and_interaction] pattern when used on objects, only.
-
-  Hero.new.extend(HeroRepresenter)
-
-The only difference is that you have to define which representers to use for typed properties.
-
-  module HeroRepresenter
-    property :forename
-    property :surename
-    collection :features
-    property :origin, :class => Location
-    collection :friends, :class => Hero, :extend => HeroRepresenter
-  end
-
-There's no need to specify a representer for the +origin+ property since the +Location+ class statically includes its representation. For +friends+, we can use +:extend+ to tell representable which module to mix in dynamically.
-
-== XML support
-
-Representable allows declaring a document's syntax and structure while having different formats. Currently, it ships with JSON, XML and YAML bindings.
-  
-  class Hero
-    include Representable::XML
-  end
-  
-  peter.to_xml
-  #=> <hero>
-    <name>Peter</name>
-    <surename>Pan</surename>
-    <location>
-      <title>Neverland</title>
-    </location>
-    <hero>
-      <name>Nick</name>
-    </hero>
-    <hero>
-      <name>El</name>
-    </hero>
-  </hero>
-
-The #to_xml method gives us an XML representation of Peter - great!
-
-=== Mapping tag attributes
-
-You can also map properties to tag attributes in representable.
-
-  class Hero
-  	attr_accessor :name
-    include Representable::XML
-    property :name, :attribute => true
-  end
-  
-  Hero.new(:name => "Peter Pan").to_xml
-  #=> <hero name="Peter Pan" />
-
-Naturally, this works for both ways.
-
-=== Wrapping collections
-
-It is sometimes unavoidable to wrap tag lists in a container tag.
-
-  module AlbumRepresenter
-    include Representable::XML
-
-    collection :songs, :from => :song, :wrap => :songs
-  end
-
-Note that +:wrap+ defines the container tag name.
-
-  Album.new.to_xml #=> 
-    <album>
-      <songs>
-        <song>Laundry Basket</song>
-        <song>Two Kevins</song>
-        <song>Wright and Rong</song>
-      </songs>
-    </album>
-
-
-== YAML Support
-
-Representers also come in handy if you need to render or parse YAML. The YAML module works exactly like the others.
-
-  module HotBandsRepresenter
-    include Representable::YAML
-
-    property :for
-    collection :names
-  end
-
-Now, just call #to_yaml to render or #from_yaml to parse.
-
-  HotBands.new(:for => "Nick", :names => ["Bad Religion", "Van Halen", "Mozart"]).
-    extend(HotBandsRepresenter).
-    to_yaml
-
-  #=> ---
-  for: Nick
-  names:
-  - Bad Religion
-  - Van Halen
-  - Mozart
-
-=== Nested Objects
-
-The YAML parser does handle nested objects just like JSON and XML does it.
-
-=== Flow Style Lists
-
-If you want flow style (aka inline style) lists, use the :style option. See http://www.yaml.org/spec/1.2/spec.html#id2790088 for more infos on flow sequences.
-
-  module HotBandsRepresenter
-    include Representable::YAML
-
-    collection :names, :style => :flow
-  end
-
-  #=> ---
-  names: [Bad Religion, Van Halen, Mozart]
-
-Need anything else for YAML? Let me know.
-
-== Coercion
-
-If you fancy coercion when parsing a document you can use the Coercion module which uses virtus[https://github.com/solnic/virtus] for type conversion.
-
-Include virtus in your Gemfile, first. Be sure to include virtus 0.5.0 or greater.
-
-  gem 'virtus'
-
-Use the +:type+ option to specify the conversion target. Note that +:default+ still works.
-
-  module HeroRepresenter
-    include Representable::JSON
-    include Virtus
-    include Representable::Coercion
-      
-    property :born_at, :type => DateTime, :default => "May 12th, 2012"
-  end
-
-
-== More
-
-Instead of spreading knowledge about your representations about the entire framework, Representable keeps rendering and parsing representations in one single, testable asset. It is a new abstraction layer missing in many "RESTful" frameworks.
-
-Representable was written with REST representations in mind. However, it is a generic module for working with documents. If you do consider using it for a REST project, check out the {Roar framework}[http://github.com/apotonick/roar], which comes with representers, built-in hypermedia support and more. It internally uses Representable and streamlines the process for building hypermedia-driven REST applications.
-
-
-== Copyright
-
-Representable is a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his inspiring work.
-
-* Copyright (c) 2011 Nick Sutterer <apotonick@gmail.com>
-* ROXML is Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.