representable 2.0.4 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9ae87cf0d1e79ff26480467bc624e3df5633e2b5
-  data.tar.gz: f46dd9c54daa7efb76af07add37e17780fb81b59
+  metadata.gz: 783116ac1174ef6a0aa6eaf44c768bfe3786dec0
+  data.tar.gz: bc85eaa1d218cd5c54161a607d80d6d3539937cf
 SHA512:
-  metadata.gz: 77511aff2f7d3d88a31c29b4feeec1d4b2c4dd31ec612a3c7521994007adcef4541b89ed14bf54338e796f539023b2cb6cbefc40efe71c7699c30d720c81bcce
-  data.tar.gz: 1983166eda318f1a45cbb349707aae61e2482952e9c29143a5791c6384ed9d4e7cfd1b0efc3a2d6ef083d9626e16e56aef9c6e857ad118775dbbe2d1d4e1859c
+  metadata.gz: 347783301a5545df8e009130eb741970d5635796368c3aae726f52e21f0357daefbfa367e7296b053aa14c8357ac1dcdff95b2cca828bfe2bf3f79fc34defe86
+  data.tar.gz: ff5d1a1825af70bee387b09ee7f997718744e7a69b66f80fb379dbbd726e1640aec81888dd651cbfa6c78c218342bfc2a5305f1bf741972a677037e3d6176894

data/CHANGES.md

@@ -1,3 +1,20 @@
+# 2.1.0
+
+## Breaking Changes
+
+* None, unless you messed around with internals like `Binding`.
+
+## Changes
+
+* Added `:skip_parse` to skip deserialization of fragments.
+* It's now `Binding#read_fragment -> Populator -> Deserializer`. Mostly, this got changed to allow better support for complex collection semantics when populating/deserializing as found in Object-HAL.
+* Likewise, it is `Binding#write_fragment -> Serializer`, clearly separating format-specific and generic logic.
+* Make `Definition#inspect` more readable by filtering out some instance variables like `@runtime_options`.
+* Remove `Binding#write_fragment_for`. This is `#render_fragment` now.
+* Almost 100% speedup for rendering and parsing by removing Ruby's delegation and `method_missing`.
+* Bindings are now in the following naming format: `Representable::Hash::Binding[::Collection]`. The file name is `representable/hash/binding`.
+* Move `Definition#skipable_empty_value?` and `Definition#default_for` to `Binding` as it is runtime-specific.
+
 # 2.0.4
 
 * Fix implicit rendering of JSON and XML collections where json/collection wasn't loaded properly, resulting in the native JSON's `#to_json` to be called.

data/README.md

@@ -527,6 +527,7 @@ Here's a list of all dynamic options and their argument signature.
 * `instance: lambda { |fragment, [i], args| }` ([see Object Creation](#polymorphic-object-creation))
 * `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))
 * `parse_filter:  lambda { |fragment, document, args| }` ([see Filters](#filters)))
 * `render_filter: lambda { |value, document, args| }` ([see Filters](#filters))
 * `if: lambda { |args| }` ([see Conditions](#conditions))
@@ -571,6 +572,24 @@ property :title, parse_filter: lambda { |fragment, doc, *args| Sanitizer.call(fr
 Just before setting the fragment to the object via the `:setter`, the `:parse_filter` is called.
 
 
+## Skip Parsing
+
+You can skip parsing for particular fragments which will completely ignore them as if they weren't present in the parsed document.
+
+```ruby
+property :title, skip_parse: lambda { |fragment, options| fragment.blank? }
+```
+
+Note that when used with collections, this is evaluated per item.
+
+```ruby
+collection :songs, skip_parse: lambda { |fragment, options| fragment["title"].blank? } do
+  property :title
+end
+```
+
+This won't parse empty incoming songs in the collection.
+
 ## Callable Options
 
 While lambdas are one option for dynamic options, you might also pass a "callable" object to a directive.
@@ -838,7 +857,7 @@ module AlbumRepresenter
 end
 ```
 
-The block for `:class` receives the currently parsed fragment. Here, this might be somthing like `{"title"=>"Weirdo", "track"=>5}`.
+The block for `:class` receives the currently parsed fragment. Here, this might be something like `{"title"=>"Weirdo", "track"=>5}`.
 
 If this is not enough, you may override the entire object creation process using `:instance`.
 

data/lib/representable.rb

@@ -41,7 +41,9 @@ private
 
   def representable_bindings_for(format, options)
     options = cleanup_options(options)  # FIXME: make representable-options and user-options  two different hashes.
+
     representable_attrs.collect {|attr| representable_binding_for(attr, format, options) }
+    # representable_attrs.binding_cache[format] ||= representable_attrs.collect {|attr| representable_binding_for(attr, format, options) }
   end
 
   def representable_binding_for(attribute, format, options)
@@ -61,7 +63,6 @@ private
     Mapper.new(bindings, represented, options) # TODO: remove self, or do we need it? and also represented!
   end
 
-
   def representation_wrap(*args)
     representable_attrs.wrap_for(self.class.name, represented, *args)
   end

data/lib/representable/binding.rb

@@ -1,8 +1,14 @@
+require "representable/populator"
 require "representable/deserializer"
 require "representable/serializer"
 
 module Representable
   # The Binding wraps the Definition instance for this property and provides methods to read/write fragments.
+
+  # The flow when parsing is Binding#read_fragment -> Populator -> Deserializer.
+  # Actual parsing the fragment from the document happens in Binding#read, everything after that is generic.
+  #
+  # Serialization: Serializer -> {frag}/[frag]/frag -> Binding#write
   class Binding
     class FragmentNotFound
     end
@@ -15,11 +21,8 @@ module Representable
 
     def initialize(definition, represented, decorator, user_options={})  # TODO: remove default arg for user options.
       @definition   = definition
-      @represented  = represented
-      @decorator    = decorator
-      @user_options = user_options
 
-      setup_exec_context!
+      setup!(represented, decorator, user_options) # this can be used in #compile_fragment/#uncompile_fragment in case we wanna reuse the Binding instance.
     end
 
     attr_reader :user_options, :represented # TODO: make private/remove.
@@ -39,37 +42,28 @@ module Representable
     # Parse value from doc and update the model property.
     def uncompile_fragment(doc)
       evaluate_option(:reader, doc) do
-        read_fragment(doc) do |value|
-          value = parse_filter(value, doc)
-          set(value)
-        end
+        read_fragment(doc)
       end
     end
 
     def write_fragment(doc, value)
       value = default_for(value)
 
-      write_fragment_for(value, doc)
-    end
-
-    def write_fragment_for(value, doc)
       return if skipable_empty_value?(value)
-      write(doc, value)
-    end
 
-    def read_fragment(doc)
-      value = read_fragment_for(doc)
+      render_fragment(value, doc)
+    end
 
-      if value == FragmentNotFound
-        return unless has_default?
-        value = self[:default]
-      end
+    def render_fragment(value, doc)
+      fragment = serialize(value) # render fragments of hash, xml, yaml.
 
-      yield value
+      write(doc, fragment)
     end
 
-    def read_fragment_for(doc)
-      read(doc)
+    def read_fragment(doc)
+      fragment = read(doc) # scalar, Array, or Hash (abstract format) or un-deserialised fragment(s).
+
+      populator.call(fragment, doc)
     end
 
     def render_filter(value, doc)
@@ -98,11 +92,75 @@ module Representable
       evaluate_option(:extend, object) # TODO: pass args? do we actually have args at the time this is called (compile-time)?
     end
 
+    # Evaluate the option (either nil, static, a block or an instance method call) or
+    # executes passed block when option not defined.
+    def evaluate_option(name, *args)
+      unless proc = self[name]
+        return yield if block_given?
+        return
+      end
+
+      # TODO: it would be better if user_options was nil per default and then we just don't pass it into lambdas.
+      options = self[:pass_options] ? Options.new(self, user_options, represented, decorator) : user_options
+
+      proc.evaluate(exec_context, *(args<<options)) # from Uber::Options::Value.
+    end
+
+    def [](name)
+      @definition[name]
+    end
+    # TODO: i don't want to define all methods here, but it is faster!
+    # TODO: test public interface.
+    def getter
+      @definition.getter
+    end
+    def setter
+      @definition.setter
+    end
+    def typed?
+      @definition.typed?
+    end
+    def representable?
+      @definition.representable?
+    end
+    def has_default?(*args)
+      @definition.has_default?(*args)
+    end
+    def name
+      @definition.name
+    end
+    def representer_module
+      @definition.representer_module
+    end
+    # perf : 1.7-1.9
+    #extend Forwardable
+    #def_delegators :@definition, *%w([] getter setter typed? representable? has_default? name representer_module)
+    # perf : 1.7-1.9
+    # %w([] getter setter typed? representable? has_default? name representer_module).each do |name|
+    #   define_method(name.to_sym) { |*args| @definition.send(name, *args) }
+    # end
+
+    def skipable_empty_value?(value)
+      return true if array? and self[:render_empty] == false and value and value.size == 0  # TODO: change in 2.0, don't render emtpy.
+      value.nil? and not self[:render_nil]
+    end
+
+    def default_for(value)
+      return self[:default] if skipable_empty_value?(value)
+      value
+    end
+
+    def array?
+      @definition.array?
+    end
+
   private
-    # Apparently, SimpleDelegator is super slow due to a regex, so we do it
-    # ourselves, right, Jimmy?
-    def method_missing(*args, &block)
-      @definition.send(*args, &block)
+    def setup!(represented, decorator, user_options)
+      @represented  = represented
+      @decorator    = decorator
+      @user_options = user_options
+
+      setup_exec_context!
     end
 
     def setup_exec_context!
@@ -115,18 +173,24 @@ module Representable
 
     attr_reader :exec_context, :decorator
 
-    # Evaluate the option (either nil, static, a block or an instance method call) or
-    # executes passed block when option not defined.
-    def evaluate_option(name, *args)
-      unless proc = self[name]
-        return yield if block_given?
-        return
-      end
+    def serialize(object)
+      serializer.call(object)
+    end
 
-      # TODO: it would be better if user_options was nil per default and then we just don't pass it into lambdas.
-      options = self[:pass_options] ? Options.new(self, user_options, represented, decorator) : user_options
+    def serializer_class
+      Serializer
+    end
 
-      proc.evaluate(exec_context, *(args<<options)) # from Uber::Options::Value.
+    def serializer
+      serializer_class.new(self)
+    end
+
+    def populator
+      populator_class.new(self)
+    end
+
+    def populator_class
+      Populator
     end
 
 
@@ -135,35 +199,27 @@ module Representable
     Options = Struct.new(:binding, :user_options, :represented, :decorator)
 
 
-    # Delegates to call #to_*/from_*.
-    module Object
-      def serialize(object)
-        ObjectSerializer.new(self, object).call
-      end
-
-      def deserialize(data)
-        # DISCUSS: does it make sense to skip deserialization of nil-values here?
-        ObjectDeserializer.new(self).call(data)
+    # generics for collection bindings.
+    module Collection
+    private
+      def populator_class
+        Populator::Collection
       end
 
-      def create_object(fragment, *args)
-        instance_for(fragment, *args) or class_for(fragment, *args)
+      def serializer_class
+        Serializer::Collection
       end
+    end
 
+    # and the same for hashes.
+    module Hash
     private
-      # DISCUSS: deprecate :class in favour of :instance and simplicity?
-      def class_for(fragment, *args)
-        item_class = class_from(fragment, *args) or raise DeserializeError.new(":class did not return class constant.")
-        item_class.new
-      end
-
-      def class_from(fragment, *args)
-        evaluate_option(:class, fragment, *args)
+      def populator_class
+        Populator::Hash
       end
 
-      def instance_for(fragment, *args)
-        # cool: if no :instance set, { return } will jump out of this method.
-        evaluate_option(:instance, fragment, *args) { return } or raise DeserializeError.new(":instance did not return object.")
+      def serializer_class
+        Serializer::Hash
       end
     end
   end

data/lib/representable/config.rb

@@ -1,3 +1,7 @@
+# Caching of Bindings
+# in Decorators, this could be an instance class var. when inherited, it is automatically busted.
+# however, in modules we can't do that. we never know when a module is "finalised", so we don't really know when to bust the cache.
+
 module Representable
   # Config contains three independent, inheritable directives: features, options and definitions.
   # It is a hash - just add directives if you need them.
@@ -77,6 +81,10 @@ module Representable
       value
     end
 
+    # def binding_cache
+    #   @binding_cache ||= {}
+    # end
+
   private
     def infer_name_for(name)
       name.to_s.split('::').last.

data/lib/representable/definition.rb

@@ -33,8 +33,9 @@ module Representable
       self
     end
 
-    extend Forwardable
-    def_delegators :@runtime_options, :[], :each
+    def [](name)
+      @runtime_options[name]
+    end
 
     def clone
       self.class.new(name, @options.clone)
@@ -49,7 +50,7 @@ module Representable
     end
 
     def representable?
-      return if self[:representable] === false
+      return if self[:representable] == false
       self[:representable] or typed?
     end
 
@@ -61,11 +62,6 @@ module Representable
       self[:hash]
     end
 
-    def default_for(value)
-      return self[:default] if skipable_empty_value?(value)
-      value
-    end
-
     def has_default?
       @options.has_key?(:default)
     end
@@ -74,15 +70,15 @@ module Representable
       @options[:extend]
     end
 
-    def skipable_empty_value?(value)
-      return true if array? and self[:render_empty] == false and value and value.size == 0  # TODO: change in 2.0, don't render emtpy.
-      value.nil? and not self[:render_nil]
-    end
-
     def create_binding(*args)
       self[:binding].call(self, *args)
     end
 
+    def inspect
+      state = (instance_variables-[:@runtime_options, :@name]).collect { |ivar| "#{ivar}=#{instance_variable_get(ivar)}" }
+      "#<Representable::Definition ==>#{name} #{state.join(" ")}>"
+    end
+
   private
     def setup!(options, &block)
       handle_extend!(options)
@@ -109,7 +105,7 @@ module Representable
     end
 
     def dynamic_options
-      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter]
+      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter, :skip_parse]
     end
 
     def handle_extend!(options)

data/lib/representable/deserializer.rb

@@ -1,24 +1,14 @@
 module Representable
-  class CollectionDeserializer
-    def initialize(binding) # TODO: get rid of binding dependency
-      @binding = binding
-    end
-
-    def deserialize(fragment)
-      # puts "deserialize #{@binding.name}" # TODO: introduce Representable::Debug.
-
-      # next step: get rid of collect.
-      fragment.enum_for(:each_with_index).collect do |item_fragment, i|
-        @deserializer = ObjectDeserializer.new(@binding)
-
-        @deserializer.call(item_fragment, i) # FIXME: what if obj nil?
-      end
-    end
-  end
-
-
-  class ObjectDeserializer
-    # dependencies: Def#options, Def#create_object
+  # Deserializer's job is deserializing the already parsed fragment into a scalar or an object.
+  # This object is then returned to the Populator.
+  #
+  # It respects :deserialize, :prepare, :class, :instance
+  #
+  # Collection bindings return an array of parsed fragment items (still native format, e.g. Nokogiri node, for nested objects).
+  #
+  # Workflow
+  #   call -> instance/class -> prepare -> deserialize -> from_json.
+  class Deserializer
     def initialize(binding)
       @binding = binding
     end
@@ -27,9 +17,7 @@ module Representable
       return fragment unless @binding.typed? # customize with :extend. this is not really straight-forward.
 
       # what if create_object is responsible for providing the deserialize-to object?
-      object = @binding.create_object(fragment, *args) # customize with :instance and :class.
-
-      # DISCUSS: what parts should be in this class, what in Binding?
+      object        = create_object(fragment, *args) # customize with :instance and :class.
       representable = prepare(object) # customize with :prepare and :extend.
 
       deserialize(representable, fragment, @binding.user_options) # deactivate-able via :representable => false.
@@ -39,13 +27,13 @@ module Representable
     def deserialize(object, fragment, options) # TODO: merge with #serialize.
       return object unless @binding.representable?
 
-      @binding.send(:evaluate_option, :deserialize, object, fragment) do
+      @binding.evaluate_option(:deserialize, object, fragment) do
         object.send(@binding.deserialize_method, fragment, options)
       end
     end
 
     def prepare(object)
-      @binding.send(:evaluate_option, :prepare, object) do
+      @binding.evaluate_option(:prepare, object) do
         prepare!(object)
       end
     end
@@ -59,5 +47,56 @@ module Representable
       mod.prepare(object)
     end
     # in deserialize, we should get the original object?
+
+    def create_object(fragment, *args)
+      instance_for(fragment, *args) or class_for(fragment, *args)
+    end
+
+    def class_for(fragment, *args)
+      item_class = class_from(fragment, *args) or raise DeserializeError.new(":class did not return class constant.")
+      item_class.new
+    end
+
+    def class_from(fragment, *args)
+      @binding.evaluate_option(:class, fragment, *args)
+    end
+
+    def instance_for(fragment, *args)
+      # cool: if no :instance set, { return } will jump out of this method.
+      @binding.evaluate_option(:instance, fragment, *args) { return } or raise DeserializeError.new(":instance did not return object.")
+    end
+
+
+
+    # Collection does exactly the same as Deserializer but for a collection.
+    class Collection < self
+      def call(fragment)
+        collection = [] # this can be replaced, e.g. AR::Collection or whatever.
+
+        fragment.each_with_index do |item_fragment, i|
+          # add more per-item options here!
+          next if @binding.evaluate_option(:skip_parse, item_fragment)
+
+          collection << deserialize!(item_fragment, i) # FIXME: what if obj nil?
+        end
+
+        collection # with parse_strategy: :sync, this is ignored.
+      end
+
+    private
+      def deserialize!(*args)
+        # TODO: re-use deserializer.
+        Deserializer.new(@binding).call(*args)
+      end
+    end
+
+
+    class Hash < Collection
+      def call(hash)
+        {}.tap do |hsh|
+          hash.each { |key, fragment| hsh[key] = deserialize!(fragment) }
+        end
+      end
+    end
   end
 end