representable 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b78042035b57cdc5c26ba4f5e5e9ad7ecc218256
-  data.tar.gz: 602635412709132eb114614ee69e53b9b73e31b2
+  metadata.gz: 8702c711c2230d338b5390e3e10cd7af901d41cf
+  data.tar.gz: fb5fd9498c58b6047a3ec221950f76c39d633c42
 SHA512:
-  metadata.gz: 75a8db26513def9bf34f95e43ddc9edda28a8d8eda41d271b4e8b55bbad6b9dc4244d7d8d7a390996cf12907f68e71721cf940e9cbf6f4d6b6a53fd9095a4b56
-  data.tar.gz: 33a3d4c76452a0400897c3dc26c2ea66a9f5f15757ce9c87d35ddca65b4baa1ccdc740244dc4a70f39384b426075baa47d70af08fb9d835f4da94cb7ca51d68f
+  metadata.gz: 1a66be6a8a40fa284c674ae0ab63aa77e48cf9257be1de100a474cc0a14bffe2271172104b190f7fc9987eb6927402db5e9f24953d670a3733b619fef3ac2ae9
+  data.tar.gz: 7b89c5a30d057d6e47ebd34f2881acc7d94df6e25e4a42692ce38b92e457aff7a96b1be12bb25312d997fdf6c58cbad46af2906487b7badf78e58e99925a47b5

data/CHANGES.md

@@ -1,3 +1,10 @@
+h2. 1.7.0
+
+* The actual serialization and deserialization (that is, calling `to_hash` etc on the object) now happens in dedicated classes: `ObjectDeserializer` and friends. If you used to override stuff in `Binding`, I'm sorry.
+* A new option `parse_strategy: :sync`. Instead of creating a new object using the `:class` option when parsing, it uses the original object found in the represented instance. This works for property and collections.
+* `Config` is now a hash. You may find a particular definition by using `Config#[]`.
+* Properties are now overridden: when calling `property(:title)` multiple times with the same name, this will override the former `Definition`. While this slightly changes the API, it allows overriding properties cleanly in sub-representers and saves you from manually finding and fiddling with the definitions.
+
 h2. 1.6.1
 
 * Using `instance: lambda { nil }` will now treat the property as a representable object without trying to extend it. It simply calls `to_*/from_*` on the property.

data/README.md

@@ -2,7 +2,7 @@
 
 Representable maps ruby objects to documents and back.
 
-In other words: Take an object and extend it with a representer module. This will allow you to render a JSON, XML or YAML document from that object. But that's only half of it! You can also use representers to parse a document and create an object.
+In other words: Take an object and decorate it with a representer module. This will allow you to render a JSON, XML or YAML document from that object. But that's only half of it! You can also use representers to parse a document and create or populate an object.
 
 Representable is helpful for all kind of rendering and parsing workflows. However, it is mostly useful in API code. Are you planning to write a real REST API with representable? Then check out the [roar](http://github.com/apotonick/roar) gem first, save work and time and make the world a better place instead.
 

data/lib/representable.rb

@@ -117,7 +117,7 @@ private
       #   property :name, :readable => false
       #   property :name, :writeable => false
       def property(name, options={}, &block)
-        (representable_attrs << definition_class.new(name, options)).last
+        representable_attrs << definition_class.new(name, options)
       end
 
       # Declares a represented document node collection.

data/lib/representable/TODO.getting_serious

@@ -0,0 +1,5 @@
+* all property objects should be extended/wrapped so we don't need the switch.
+
+# Deprecations
+
+* deprecate instance: { nil } which is superseded by parse_strategy: :sync

data/lib/representable/binding.rb

@@ -1,4 +1,6 @@
-require 'delegate'
+require "delegate"
+require "representable/deserializer"
+require "representable/serializer"
 
 module Representable
   # The Binding wraps the Definition instance for this property and provides methods to read/write fragments.
@@ -26,7 +28,7 @@ module Representable
       value
     end
 
-    def deserialize(fragment)
+    def deserialize(fragment, *args)
       fragment
     end
 
@@ -84,6 +86,8 @@ module Representable
       end
     end
 
+    # the remaining methods in this class are format-independent and should be in Definition.
+
   private
     attr_reader :exec_context
 
@@ -103,47 +107,23 @@ module Representable
     end
 
 
-    # Hooks into #serialize and #deserialize to setup (extend/decorate) typed properties
-    # at runtime.
     module Prepare
-      # Extends the object with its representer before serialization.
-      def serialize(*)
-        prepare(super)
-      end
-
-      def deserialize(*)
-        prepare(super)
-      end
-
-      def prepare(object)
-        return object unless mod = representer_module_for(object) # :extend.
-
-        mod = mod.first if mod.is_a?(Array) # TODO: deprecate :extend => [..]
-        mod.prepare(object)
-      end
-
-    private
       def representer_module_for(object, *args)
         call_proc_for(representer_module, object)   # TODO: how to pass additional data to the computing block?`
       end
     end
+    include Prepare
 
-    # 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::Prepare
 
+    # Delegates to call #to_*/from_*.
+    module Object
       def serialize(object)
-        return object if object.nil?
-
-        super.send(serialize_method, @user_options.merge!({:wrap => false}))  # TODO: pass :binding => self
+        ObjectSerializer.new(self, object).call
       end
 
-      def deserialize(data)
+      def deserialize(data, object=lambda { get })
         # DISCUSS: does it make sense to skip deserialization of nil-values here?
-        create_object(data).tap do |obj|
-          super(obj).send(deserialize_method, data, @user_options)
-        end
+        ObjectDeserializer.new(self, object).call(data)
       end
 
       def create_object(fragment)
@@ -152,7 +132,7 @@ module Representable
 
     private
       def class_for(fragment, *args)
-        item_class = class_from(fragment) or return fragment # DISCUSS: is it legal to return the very fragment here?
+        item_class = class_from(fragment) or return fragment
         item_class.new
       end
 

data/lib/representable/bindings/hash_bindings.rb

@@ -47,15 +47,14 @@ module Representable
       end
     end
 
-
     class CollectionBinding < PropertyBinding
       def serialize_for(value)
         # value.enum_for(:each_with_index).collect { |obj, i| serialize(obj, i) } # DISCUSS: provide ary index/hash key for representer_module_for?
-        value.collect { |item| serialize(item) }
+        value.collect { |item| serialize(item) } # TODO: i don't want Array but Forms here - what now?
       end
 
       def deserialize_from(fragment)
-        fragment.collect { |item_fragment| deserialize(item_fragment) }
+        CollectionDeserializer.new(self).deserialize(fragment)
       end
     end
 

data/lib/representable/bindings/xml_bindings.rb

@@ -1,28 +1,29 @@
 require 'representable/binding'
+require 'representable/bindings/hash_bindings.rb'
 
 module Representable
   module XML
     module ObjectBinding
       include Binding::Object
-      
+
       def serialize_method
         :to_node
       end
-      
+
       def deserialize_method
         :from_node
       end
-      
-      def deserialize_node(node)
-        deserialize(node)
+
+      def content_for(node) # TODO: move to ScalarDecorator.
+        node
       end
-      
+
       def serialize_node(node, value)
         serialize(value)
       end
     end
-    
-    
+
+
     class PropertyBinding < Binding
       def self.build_for(definition, *args)
         return CollectionBinding.new(definition, *args)      if definition.array?
@@ -36,45 +37,41 @@ module Representable
         super
         extend ObjectBinding if typed? # FIXME.
       end
-      
+
       def write(parent, value)
         wrap_node = parent
-        
+
         if wrap = options[:wrap]
           parent << wrap_node = node_for(parent, wrap)
         end
 
         wrap_node << serialize_for(value, parent)
       end
-      
+
       def read(node)
         nodes = find_nodes(node)
         return FragmentNotFound if nodes.size == 0 # TODO: write dedicated test!
-        
+
         deserialize_from(nodes)
       end
-      
+
       # Creates wrapped node for the property.
       def serialize_for(value, parent)
       #def serialize_for(value, parent, tag_name=definition.from)
         node = node_for(parent, from)
         serialize_node(node, value)
       end
-      
+
       def serialize_node(node, value)
         node.content = serialize(value)
         node
       end
-      
+
       def deserialize_from(nodes)
-        deserialize_node(nodes.first)
-      end
-      
-      # DISCUSS: rename to #read_from ?
-      def deserialize_node(node)
-        deserialize(node.content)
+        content_for deserialize(nodes.first)
+        #deserialize(nodes.first)
       end
-      
+
     private
       def xpath
         from
@@ -89,18 +86,25 @@ module Representable
       def node_for(parent, name)
         Nokogiri::XML::Node.new(name.to_s, parent.document)
       end
+
+      def content_for(node) # TODO: move this into a ScalarDecorator.
+        node.content
+      end
     end
-    
+
     class CollectionBinding < PropertyBinding
       def serialize_for(value, parent)
         # return NodeSet so << works.
         set_for(parent, value.collect { |item| super(item, parent) })
       end
-      
+
       def deserialize_from(nodes)
-        nodes.collect do |item|
-          deserialize_node(item)
+        content_nodes = nodes.collect do |item| # TODO: move this to Node?
+          content_for(item)
         end
+
+        # *Deserializer doesn't want anything format specific!
+        CollectionDeserializer.new(self).deserialize(content_nodes)
       end
 
     private
@@ -108,8 +112,8 @@ module Representable
         Nokogiri::XML::NodeSet.new(parent.document, nodes)
       end
     end
-    
-    
+
+
     class HashBinding < CollectionBinding
       def serialize_for(value, parent)
         set_for(parent, value.collect do |k, v|
@@ -117,16 +121,16 @@ module Representable
           serialize_node(node, v)
         end)
       end
-      
+
       def deserialize_from(nodes)
         {}.tap do |hash|
           nodes.children.each do |node|
-            hash[node.name] = deserialize_node(node)
+            hash[node.name] = deserialize(content_for node)
           end
         end
       end
     end
-    
+
     class AttributeHashBinding < CollectionBinding
       # DISCUSS: use AttributeBinding here?
       def write(parent, value)  # DISCUSS: is it correct overriding #write here?
@@ -135,7 +139,7 @@ module Representable
         end
         parent
       end
-      
+
       def deserialize_from(node)
         {}.tap do |hash|
           node.each do |k,v|
@@ -144,18 +148,18 @@ module Representable
         end
       end
     end
-    
-    
+
+
     # Represents a tag attribute. Currently this only works on the top-level tag.
     class AttributeBinding < PropertyBinding
       def read(node)
         deserialize(node[from])
       end
-      
+
       def serialize_for(value, parent)
         parent[from] = serialize(value.to_s)
       end
-      
+
       def write(parent, value)
         serialize_for(value, parent)
       end

data/lib/representable/bindings/yaml_bindings.rb

@@ -4,11 +4,11 @@ module Representable
   module YAML
     module ObjectBinding
       include Binding::Object
-      
+
       def serialize_method
         :to_ast
       end
-      
+
       def deserialize_method
         :from_hash
       end
@@ -28,7 +28,7 @@ module Representable
         super
         extend ObjectBinding if typed?
       end
-      
+
       def write(map, value)
         map.children << Psych::Nodes::Scalar.new(from)
         map.children << serialize_for(value)  # FIXME: should be serialize.
@@ -42,8 +42,8 @@ module Representable
         Psych::Nodes::Scalar.new(value.to_s)
       end
     end
-    
-    
+
+
     class CollectionBinding < PropertyBinding
       def serialize_for(value)
         Psych::Nodes::Sequence.new.tap do |seq|
@@ -51,9 +51,9 @@ module Representable
           value.each { |obj| seq.children << super(obj) }
         end
       end
-      
+
       def deserialize_from(fragment)  # FIXME: redundant from Hash::Bindings
-        fragment.collect { |item_fragment| deserialize(item_fragment) }
+        CollectionDeserializer.new(self).deserialize(fragment)
       end
     end
   end

data/lib/representable/config.rb

@@ -1,6 +1,6 @@
 module Representable
   # NOTE: the API of Config is subject to change so don't rely too much on this private object.
-  class Config < Array
+  class Config < Hash
     # DISCUSS: experimental. this will soon be moved to a separate gem
     module InheritableArray
       def inheritable_array(name)
@@ -19,6 +19,17 @@ module Representable
       end
     end
 
+    def <<(definition)
+      self[definition.name] = definition
+    end
+
+    def [](name)
+      fetch(name.to_s, nil)
+    end
+
+    def each(*args, &block)
+      values.each(*args, &block)
+    end
 
     attr_accessor :wrap
 
@@ -30,18 +41,22 @@ module Representable
     end
 
     module InheritMethods
-      def clone
-        self.class.new(collect { |d| d.clone })
+      def cloned
+        collect { |d| d.clone }
       end
 
       def inherit(parent)
-        push(*parent.clone)
+        push(parent.cloned)
       end
     end
     include InheritMethods
     include InheritableArray # overrides #inherit.
 
   private
+    def push(defs)
+      defs.each { |d| self << d }
+    end
+
     def infer_name_for(name)
       name.to_s.split('::').last.
        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').

data/lib/representable/definition.rb

@@ -72,5 +72,9 @@ module Representable
     def create_binding(*args)
       binding.call(self, *args)
     end
+
+    def sync?
+      options[:parse_strategy] == :sync
+    end
   end
 end

data/lib/representable/deserializer.rb

@@ -0,0 +1,63 @@
+module Representable
+  class CollectionDeserializer < Array # always is the targeted collection, already.
+    def initialize(binding) # TODO: get rid of binding dependency
+      # next step: use #get always.
+      @binding = binding
+      collection = []
+      # should be call to #default:
+      collection = binding.get if binding.sync?
+
+      super collection
+    end
+
+    def deserialize(fragment)
+      # next step: get rid of collect.
+      fragment.enum_for(:each_with_index).collect { |item_fragment, i|
+        @deserializer = ObjectDeserializer.new(@binding, lambda { self[i] })
+
+        @deserializer.call(item_fragment) # FIXME: what if obj nil?
+      }
+    end
+  end
+
+
+  class ObjectDeserializer
+    # dependencies: Def#options, Def#create_object, Def#get
+    def initialize(binding, object)
+      @binding = binding
+      @object  = object
+    end
+
+    def call(fragment)
+      # TODO: this used to be handled in #serialize where Object added it's behaviour. treat scalars as objects to remove this switch:
+      return fragment unless @binding.typed?
+
+      if @binding.sync?
+        # TODO: this is also done when instance: { nil }
+        @object = @object.call # call Binding#get or Binding#get[i]
+      else
+        @object = @binding.create_object(fragment)
+      end
+
+      # DISCUSS: what parts should be in this class, what in Binding?
+      representable = prepare(@object)
+      deserialize(representable, fragment, @binding.user_options)
+      #yield @object
+    end
+
+  private
+    def deserialize(object, fragment, options)
+      object.send(@binding.deserialize_method, fragment, options)
+    end
+
+    def prepare(object)
+      mod = @binding.representer_module_for(object)
+
+      return object unless mod
+
+      mod = mod.first if mod.is_a?(Array) # TODO: deprecate :extend => [..]
+      mod.prepare(object)
+    end
+    # in deserialize, we should get the original object?
+  end
+end