representable 2.1.1 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d4c1cc5843478c8c3c889dabd023eca71e622da8
-  data.tar.gz: c8b2850a2418de5d94dbc1024f5d84c93a979976
+  metadata.gz: 00d2530b55af3101dbb2526089519f0bdb549b83
+  data.tar.gz: ed33d0ffceab14486efa0a0e61edc84e3de03de7
 SHA512:
-  metadata.gz: 8447a73176a4dfd5cc11d7767721e083757e2c9eeeb9e0bde32d73b17fea141fd6954ca05ce45f9e88c8393d9341981cce7b4e5fc4836f7eaed39d05a0890bc8
-  data.tar.gz: a4175164b4f3eb64db40630b7d9fcc4e1574cc075268f87e6cdafbe2a8648861a07f0302fbbc54431ac6bb5934b4c3f12e704a3459a4b3c134acf029ff794496
+  metadata.gz: 4fb790c37b9c9bd1abe2f6caeff855031b5a263c44f58e8b43f37f1ada791a2e1a87efdf6dabd26a95c1e184e3d88a5049296c0459b0b95c1ac42bdd96937e72
+  data.tar.gz: 597b5614752170094138b69d7c02ef70deb5a23c300d35e22bfa3f9232b5d8572ac53dd84dd1e7500f35940f3263cd96687a981878e046f3b29a94fba3cef22a

data/CHANGES.md

@@ -1,8 +1,16 @@
+# 2.1.3
+
+* Like 2.1.2 (got yanked) because I thought it's buggy but it's not. What has changed is that `Serializer::Collection#serialize` no longer does `collection.collect` but `collection.each` since this allows filtering out unwanted elements.
+
+# 2.1.2
+
+* Added `:skip_render` options.
+
 # 2.1.1
 
 * Added `Definition#delete!` to remove options.
 * Added `Representable::apply` do iterate and change schemas.
-* Added `Config.remove` to remove properties.
+* Added `Config#remove` to remove properties.
 * Added `Representable::Debug` which just has to be included into your represented object.
 
     ```ruby

data/README.md

@@ -62,6 +62,8 @@ song = Song.new.extend(SongRepresenter).from_json(%{ {"title":"Roxanne"} })
 #=> #<Song title="Roxanne", track=nil>
 ```
 
+Note that parsing hashes per default does [require string keys](#symbol-keys-vs-string-keys) and does _not_ pick up symbol keys.
+
 ## 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](#decorator-vs-extend). Decorating instead of extending was introduced in 1.4.
@@ -528,6 +530,7 @@ Here's a list of all dynamic options and their argument signature.
 * `reader: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
 * `writer: lambda { |document, args| }` ([see Read And Write](#overriding-read-and-write))
 * `skip_parse: lambda { |fragment, args| }` ([see Skip Parsing](#skip-parsing))
+* `skip_render: lambda { |object, args| }` ([see Skip Rendering](#skip-rendering))
 * `parse_filter:  lambda { |fragment, document, args| }` ([see Filters](#filters)))
 * `render_filter: lambda { |value, document, args| }` ([see Filters](#filters))
 * `if: lambda { |args| }` ([see Conditions](#conditions))
@@ -590,6 +593,17 @@ end
 
 This won't parse empty incoming songs in the collection.
 
+## Skip Rendering
+
+The exact same also works for rendering. You can skip rendering properties and items of collections.
+
+```ruby
+property :title, skip_render: lambda { |object, options| options[:skip_title] == true }
+```
+
+In collections, this will be run per item.
+
+
 ## Callable Options
 
 While lambdas are one option for dynamic options, you might also pass a "callable" object to a directive.
@@ -1300,12 +1314,57 @@ end
 
 This is an implementation detail most people shouldn't worry about.
 
+## Symbol Keys vs. String Keys
+
+When parsing representable reads properties from hashes by using their string keys.
+
+```ruby
+song.from_hash("title" => "Road To Never")
+```
+
+To allow symbol keys also include the `AllowSymbols` module.
+
+```ruby
+module SongRepresenter
+  include Representable::Hash
+  include Representable::Hash::AllowSymbols
+  # ..
+end
+```
+
+This will give you a behavior close to Rails' `HashWithIndifferentAccess` by stringifying the incoming hash internally.
+
+
+## Debugging
+
+Representable is a generic mapper using recursions and things that might be hard to understand from the outside. That's why we got the `Debug` module which will give helpful output about what it's doing when parsing or rendering.
+
+You can extend objects on the run to see what they're doing.
+
+```ruby
+song.extend(SongRepresenter).extend(Representable::Debug).from_json("..")
+song.extend(SongRepresenter).extend(Representable::Debug).to_json
+```
+
+`Debug` can also be included statically into your representer or decorator.
+
+```ruby
+class SongRepresenter < Representable::Decorator
+  include Representable::JSON
+  include Representable::Debug
+
+  property :title
+end
+```
+
+It's probably a good idea not to do this in production.
+
 
 ## Copyright
 
 Representable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his inspiring work.
 
-* Copyright (c) 2011-2013 Nick Sutterer <apotonick@gmail.com>
+* Copyright (c) 2011-2015 Nick Sutterer <apotonick@gmail.com>
 * ROXML is Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.
 
 Representable is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/representable/binding.rb

@@ -55,7 +55,8 @@ module Representable
     end
 
     def render_fragment(value, doc)
-      fragment = serialize(value) # render fragments of hash, xml, yaml.
+      # DISCUSS: should we return a Skip object instead of this block trick? (same in Populator?)
+      fragment = serialize(value) { return } # render fragments of hash, xml, yaml.
 
       write(doc, fragment)
     end
@@ -173,8 +174,8 @@ module Representable
 
     attr_reader :exec_context, :decorator
 
-    def serialize(object)
-      serializer.call(object)
+    def serialize(object, &block)
+      serializer.call(object, &block)
     end
 
     def serializer_class

data/lib/representable/definition.rb

@@ -111,7 +111,7 @@ module Representable
     end
 
     def dynamic_options
-      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter, :skip_parse]
+      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter, :skip_parse, :skip_render]
     end
 
     def handle_extend!(options)

data/lib/representable/populator.rb

@@ -17,6 +17,7 @@ module Representable
         return unless @binding.has_default?
         value = @binding[:default]
       else
+        # DISCUSS: should we return a Skip object instead of this block trick? (same in Binding#serialize?)
         value = deserialize(fragment) { return } # stop here if skip_parse?
       end
 

data/lib/representable/serializer.rb

@@ -1,16 +1,23 @@
 require "representable/deserializer"
 
 module Representable
+  # serialize -> serialize! -> marshal. # TODO: same flow in deserialize.
   class Serializer < Deserializer
-    def call(object)
+    def call(object, &block)
       return object if object.nil? # DISCUSS: move to Object#serialize ?
 
-      serialize(object, @binding.user_options)
+      serialize(object, @binding.user_options, &block)
     end
 
   private
+    def serialize(object, user_options, &block)
+      return yield if @binding.evaluate_option(:skip_render, object) # this will jump out of #render_fragment. introduce Skip object here.
+
+      serialize!(object, user_options)
+    end
+
     # Serialize one object by calling to_json etc. on it.
-    def serialize(object, user_options)
+    def serialize!(object, user_options)
       object = prepare(object)
 
       return object unless @binding.representable?
@@ -27,7 +34,15 @@ module Representable
 
     class Collection < self
       def serialize(array, *args)
-        array.collect { |item| super(item, *args) } # TODO: i don't want Array but Forms here - what now?
+        collection = [] # TODO: unify with Deserializer::Collection.
+
+        array.each do |item|
+          next if @binding.evaluate_option(:skip_render, item) # TODO: allow skipping entire collections? same for deserialize.
+
+          collection << serialize!(item, *args)
+        end # TODO: i don't want Array but Forms here - what now?
+
+        collection
       end
     end
 

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "2.1.1"
+  VERSION = "2.1.3"
 end

data/representable.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.add_dependency "uber", "~> 0.0.7"
 
   s.add_development_dependency "rake"
-  s.add_development_dependency "test_xml", ">= 0.1.6"
+  s.add_development_dependency "test_xml", "0.1.6"
   s.add_development_dependency "minitest", ">= 5.4.1"
   s.add_development_dependency "mocha", ">= 0.13.0"
   s.add_development_dependency "mongoid"

data/test/skip_test.rb

@@ -1,6 +1,6 @@
 require 'test_helper'
 
-class SkipTest < MiniTest::Spec
+class SkipParseTest < MiniTest::Spec
   representer! do
     property :title
     property :band,
@@ -25,4 +25,42 @@ class SkipTest < MiniTest::Spec
   # skip_parse is _per item_.
   let (:airplay) { OpenStruct.new(station: "JJJ") }
   it { song.from_hash({"airplays" => [{"station" => "JJJ"}, {}]}, skip?: true).airplays.must_equal [airplay] }
+
+  # it skips parsing of items as if they hadn't been in the document.
+  it { song.from_hash({"airplays" => [{"station" => "JJJ"}, {}, {"station" => "JJJ"}]}, skip?: true).airplays.must_equal [airplay, airplay] }
+end
+
+class SkipRenderTest < MiniTest::Spec
+  representer! do
+    property :title
+    property :band,
+      skip_render: lambda { |object, opts| opts[:skip?] and object.name == "Rancid" } do
+        property :name
+    end
+
+    collection :airplays,
+      skip_render: lambda { |object, opts| puts object.inspect; opts[:skip?] and object.station == "Radio Dreyeckland" } do
+        property :station
+    end
+  end
+
+  let (:song)      { OpenStruct.new(title: "Black Night", band: OpenStruct.new(name: "Time Again")).extend(representer) }
+  let (:skip_song) { OpenStruct.new(title: "Time Bomb",   band: OpenStruct.new(name: "Rancid")).extend(representer) }
+
+  # do render.
+  it { song.to_hash(skip?: true).must_equal({"title"=>"Black Night", "band"=>{"name"=>"Time Again"}}) }
+  # skip.
+  it { skip_song.to_hash(skip?: true).must_equal({"title"=>"Time Bomb"}) }
+
+  # do render all collection items.
+  it do
+    song = OpenStruct.new(airplays: [OpenStruct.new(station: "JJJ"), OpenStruct.new(station: "ABC")]).extend(representer)
+    song.to_hash(skip?: true).must_equal({"airplays"=>[{"station"=>"JJJ"}, {"station"=>"ABC"}]})
+  end
+
+  # skip middle item.
+  it do
+    song = OpenStruct.new(airplays: [OpenStruct.new(station: "JJJ"), OpenStruct.new(station: "Radio Dreyeckland"), OpenStruct.new(station: "ABC")]).extend(representer)
+    song.to_hash(skip?: true).must_equal({"airplays"=>[{"station"=>"JJJ"}, {"station"=>"ABC"}]})
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: representable
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.3
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-22 00:00:00.000000000 Z
+date: 2014-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -70,14 +70,14 @@ dependencies:
   name: test_xml
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
         version: 0.1.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
         version: 0.1.6
 - !ruby/object:Gem::Dependency