representable 1.1.7 → 1.2.0

data/CHANGES.textile

@@ -1,7 +1,9 @@
-h2. 1.1.7
+h2. 1.2.0
+
+* Deprecated @:except@ in favor of @:exclude@.
+* A property with @false@ value will now be included in the rendered representation. Same applies to parsing, @false@ values will now be included. That particularly means properties that used to be unset (i.e. @nil@) after parsing might be @false@ now.
+* You can include @nil@ values now in your representations since @#property@ respects @:represent_nil => true@.
 
-* Added support for coercion using virtus. Note that this presently works on class level with inline representers, only.
- 
 h2. 1.1.6
 
 * Added @:if@ option to @property@.

data/README.rdoc

@@ -247,7 +247,15 @@ You can also define conditions on properties on the class layer.
     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.
+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 +:represent_nil+ option.
+
+  property :surename, :represent_nil => true
 
 == DCI
 

data/lib/representable.rb

@@ -1,4 +1,5 @@
 require 'representable/definition'
+require 'representable/deprecations'
 
 # Representable can be used in two ways.
 #
@@ -29,6 +30,7 @@ module Representable
   
   def self.included(base)
     base.class_eval do
+      include Deprecations
       extend ClassMethods
       extend ClassMethods::Declarations
       extend ClassMethods::Accessors
@@ -67,14 +69,13 @@ private
   
   # Checks and returns if the property should be included.
   def skip_property?(binding, options)
-    return true if skip_excluded_property?(binding, options)  # no need for further evaluation when :except'ed
+    return true if skip_excluded_property?(binding, options)  # no need for further evaluation when :exclude'ed
     
     skip_conditional_property?(binding)
   end
   
   def skip_excluded_property?(binding, options)
-    return unless props = options[:except] || options[:include]
-    props = options[:except] || options[:include]
+    return unless props = options[:exclude] || options[:include]
     res   = props.include?(binding.definition.name.to_sym)
     options[:include] ? !res : res
   end
@@ -86,18 +87,22 @@ private
   
   # Retrieve value and write fragment to the doc.
   def compile_fragment(bin, doc)
-    value = send(bin.definition.getter) || bin.definition.default # DISCUSS: eventually move back to Ref.
+    value = send(bin.definition.getter)
+    value = bin.definition.default_for(value)
+    
     write_fragment_for(bin, value, doc)
   end
   
   # Parse value from doc and update the model property.
   def uncompile_fragment(bin, doc)
-    value = read_fragment_for(bin, doc) || bin.definition.default
+    value = read_fragment_for(bin, doc)
+    value = bin.definition.default_for(value)
+    
     send(bin.definition.setter, value)
   end
   
   def write_fragment_for(bin, value, doc) # DISCUSS: move to Binding?
-    return unless value
+    return if bin.definition.skipable_nil_value?(value)
     bin.write(doc, value)
   end
   
@@ -140,6 +145,7 @@ private
       #   property :name, :from => :title
       #   property :name, :class => Name
       #   property :name, :default => "Mike"
+      #   property :name, :include_nil => true
       def property(name, options={})
         representable_attrs << definition_class.new(name, options)
       end

data/lib/representable/binding.rb

@@ -1,7 +1,7 @@
 module Representable
   class Binding
-    attr_reader :definition
-
+    attr_reader :definition # TODO: merge Binding and Definition.
+  
     def initialize(definition)
       @definition = definition
     end

data/lib/representable/definition.rb

@@ -37,9 +37,9 @@ module Representable
       (options[:from] || name).to_s
     end
     
-    def default
-      options[:default] ||= [] if array?  # FIXME: move to CollectionBinding!
-      options[:default]
+    def default_for(value)
+      return default if skipable_nil_value?(value)
+      value
     end
     
     def representer_module
@@ -49,5 +49,15 @@ module Representable
     def attribute
       options[:attribute]
     end
+    
+    def skipable_nil_value?(value)
+      value.nil? and not options[:represent_nil]
+    end
+    
+  private
+    def default
+      options[:default] ||= [] if array?  # FIXME: move to CollectionBinding!
+      options[:default]
+    end
   end
 end

data/lib/representable/deprecations.rb

@@ -0,0 +1,9 @@
+module Representable::Deprecations
+  def skip_excluded_property?(binding, options) # TODO: remove with 1.3.
+    if options[:except]
+      options[:exclude] = options[:except]
+      warn "The :except option is deprecated and will be removed in 1.3. Please use :exclude."
+    end # i wanted a one-liner but failed :)
+    super
+  end
+end

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "1.1.7"
+  VERSION = "1.2.0"
 end

data/test/definition_test.rb

@@ -55,6 +55,62 @@ class DefinitionTest < MiniTest::Spec
     end
   end
   
+  describe "#skipable_nil_value?" do
+    # default if skipable_nil_value?
+    before do
+      @def = Representable::Definition.new(:song, :represent_nil => true)
+    end
+    
+    it "returns false when not nil" do
+      assert_equal false, @def.skipable_nil_value?("Disconnect, Disconnect")
+    end
+    
+    it "returns false when nil and :represent_nil => true" do
+      assert_equal false, @def.skipable_nil_value?(nil)
+    end
+    
+    it "returns true when nil and :represent_nil => false" do
+      assert_equal true, Representable::Definition.new(:song).skipable_nil_value?(nil)
+    end
+    
+    it "returns false when not nil and :represent_nil => false" do
+      assert_equal false, Representable::Definition.new(:song).skipable_nil_value?("Fatal Flu")
+    end
+  end
+  
+  
+  describe "#default_for" do
+    before do
+      @def = Representable::Definition.new(:song, :default => "Insider")
+    end
+    
+    it "always returns value when value not nil" do
+      assert_equal "Black And Blue", @def.default_for("Black And Blue")
+    end
+    
+    it "returns false when value false" do
+      assert_equal false, @def.default_for(false)
+    end
+    
+    it "returns default when value nil" do
+      assert_equal "Insider", @def.default_for(nil)
+    end
+    
+    it "returns nil when value nil and :represent_nil true" do
+      @def = Representable::Definition.new(:song, :represent_nil => true)
+      assert_equal nil, @def.default_for(nil)
+    end
+    
+    it "returns nil when value nil and :represent_nil true even when :default is set" do
+      @def = Representable::Definition.new(:song, :represent_nil => true, :default => "The Quest")
+      assert_equal nil, @def.default_for(nil)
+    end
+    
+    it "returns nil if no :default" do
+      @def = Representable::Definition.new(:song)
+      assert_equal nil, @def.default_for(nil)
+    end
+  end
     
   describe ":collection => true" do
     before do
@@ -70,7 +126,7 @@ class DefinitionTest < MiniTest::Spec
     end
     
     it "responds to #default" do
-      assert_equal [], @def.default
+      assert_equal [], @def.send(:default)
     end
   end
   
@@ -87,12 +143,12 @@ class DefinitionTest < MiniTest::Spec
   describe ":default => value" do
     it "responds to #default" do
       @def = Representable::Definition.new(:song)
-      assert_equal nil, @def.default
+      assert_equal nil, @def.send(:default)
     end
     
     it "accepts a default value" do
       @def = Representable::Definition.new(:song, :default => "Atheist Peace")
-      assert_equal "Atheist Peace", @def.default
+      assert_equal "Atheist Peace", @def.send(:default)
     end
   end
   

data/test/representable_test.rb

@@ -229,12 +229,16 @@ class RepresentableTest < MiniTest::Spec
       assert_equal 2, @band.groupies
     end
     
-    it "accepts :except option" do
-      @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:except => [:groupies]}, Representable::JSON)
+    it "accepts :exclude option" do
+      @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:exclude => [:groupies]}, Representable::JSON)
       assert_equal "No One's Choice", @band.name
       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::JSON), @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:exclude => [:groupies]}, Representable::JSON)
+    end
+    
     it "accepts :include option" do
       @band.update_properties_from({"name"=>"No One's Choice", "groupies"=>2}, {:include => [:groupies]}, Representable::JSON)
       assert_equal 2, @band.groupies
@@ -245,47 +249,10 @@ class RepresentableTest < MiniTest::Spec
       assert_equal @band, @band.update_properties_from({"name"=>"Nofx"}, {}, Representable::JSON)
     end
     
-    describe ":if" do
-      before do
-        @pop = Class.new(PopBand) { attr_accessor :fame }
-      end
-      
-      it "respects property when condition true" do
-        @pop.class_eval { property :fame, :if => lambda { true } }
-        band = @pop.new
-        band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
-        assert_equal "oh yes", band.fame
-      end
-      
-      it "ignores property when condition false" do
-        @pop.class_eval { property :fame, :if => lambda { false } }
-        band = @pop.new
-        band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
-        assert_equal nil, band.fame
-      end
-      
-      it "ignores property when :except'ed even when condition is true" do
-        @pop.class_eval { property :fame, :if => lambda { true } }
-        band = @pop.new
-        band.update_properties_from({"fame"=>"oh yes"}, {:except => [:fame]}, Representable::JSON)
-        assert_equal nil, band.fame
-      end
-      
-      
-      it "executes block in instance context" do
-        @pop.class_eval { property :fame, :if => lambda { groupies } }
-        band = @pop.new
-        band.groupies = true
-        band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
-        assert_equal "oh yes", band.fame
-      end
-      
-    end
-    
-    it "what" do
-      
+    it "includes false attributes" do
+      @band.update_properties_from({"groupies"=>false}, {}, Representable::JSON)
+      assert_equal false, @band.groupies
     end
-    
   end
   
   describe "#create_representation_with" do
@@ -299,17 +266,79 @@ class RepresentableTest < MiniTest::Spec
       assert_equal({"name"=>"No One's Choice", "groupies"=>2}, @band.send(:create_representation_with, {}, {}, Representable::JSON))
     end
     
-    it "accepts :except option" do
-      hash = @band.send(:create_representation_with, {}, {:except => [:groupies]}, Representable::JSON)
+    it "accepts :exclude option" do
+      hash = @band.send(:create_representation_with, {}, {:exclude => [:groupies]}, Representable::JSON)
       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::JSON), @band.send(:create_representation_with, {}, {:exclude => [:groupies]}, Representable::JSON)
+    end
+    
     it "accepts :include option" do
       hash = @band.send(:create_representation_with, {}, {:include => [:groupies]}, Representable::JSON)
       assert_equal({"groupies"=>2}, hash)
     end
+
+    it "does not write nil attributes" do
+      @band.groupies = nil
+      assert_equal({"name"=>"No One's Choice"}, @band.send(:create_representation_with, {}, {}, Representable::JSON))
+    end
+
+    it "writes false attributes" do
+      @band.groupies = false
+      assert_equal({"name"=>"No One's Choice","groupies"=>false}, @band.send(:create_representation_with, {}, {}, Representable::JSON))
+    end
+    
+    it "includes nil attribute when :represent_nil is true" do
+      mod = Module.new do
+        include Representable::JSON
+        property :name
+        property :groupies, :represent_nil => true
+      end
+      
+      @band.extend(mod) # FIXME: use clean object.
+      @band.groupies = nil
+      hash = @band.send(:create_representation_with, {}, {}, Representable::JSON)
+      assert_equal({"name"=>"No One's Choice", "groupies" => nil}, hash)
+    end
   end
   
+  describe ":if" do
+    before do
+      @pop = Class.new(PopBand) { attr_accessor :fame }
+    end
+    
+    it "respects property when condition true" do
+      @pop.class_eval { property :fame, :if => lambda { true } }
+      band = @pop.new
+      band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
+      assert_equal "oh yes", band.fame
+    end
+    
+    it "ignores property when condition false" do
+      @pop.class_eval { property :fame, :if => lambda { false } }
+      band = @pop.new
+      band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
+      assert_equal nil, band.fame
+    end
+    
+    it "ignores property when :exclude'ed even when condition is true" do
+      @pop.class_eval { property :fame, :if => lambda { true } }
+      band = @pop.new
+      band.update_properties_from({"fame"=>"oh yes"}, {:exclude => [:fame]}, Representable::JSON)
+      assert_equal nil, band.fame
+    end
+    
+    
+    it "executes block in instance context" do
+      @pop.class_eval { property :fame, :if => lambda { groupies } }
+      band = @pop.new
+      band.groupies = true
+      band.update_properties_from({"fame"=>"oh yes"}, {}, Representable::JSON)
+      assert_equal "oh yes", band.fame
+    end
+  end
   
   describe "Config" do
     before do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 1.1.7
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-13 00:00:00.000000000 Z
+date: 2012-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &80366830 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *80366830
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &80366420 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *80366420
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &80365840 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +53,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80365840
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: test_xml
-  requirement: &80365210 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +69,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80365210
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &80364570 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +85,15 @@ dependencies:
         version: 2.8.1
   type: :development
   prerelease: false
-  version_requirements: *80364570
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.8.1
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &80364280 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +101,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80364280
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mongoid
-  requirement: &80363910 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +117,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80363910
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: virtus
-  requirement: &80363490 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,7 +133,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *80363490
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Maps representation documents from and to Ruby objects. Includes XML
   and JSON support, plain properties, collections and compositions.
 email:
@@ -121,6 +161,7 @@ files:
 - lib/representable/bindings/xml_bindings.rb
 - lib/representable/coercion.rb
 - lib/representable/definition.rb
+- lib/representable/deprecations.rb
 - lib/representable/json.rb
 - lib/representable/json/collection.rb
 - lib/representable/json/hash.rb
@@ -159,7 +200,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Maps representation documents from and to Ruby objects. Includes XML and