representable 1.0.1 → 1.1.0

data/CHANGES.textile

@@ -1,3 +1,13 @@
+h2. 1.1.0
+
+* Added `JSON::Collection` to have plain list representations. And `JSON::Hash` for hashes.
+* Added the `hash` class method to XML and JSON to represent hashes.
+* Defining `:extend` only on a property now works for rendering. If you try parsing without a `:class` there'll be an exception, though.
+
+h2. 1.0.1
+
+* Allow passing a list of modules to :extend, like @:extend => [Ingredient, IngredientRepresenter]@.
+
 h2. 1.0.0
 
 * 1.0.0 release! Party time!

data/README.rdoc

@@ -165,6 +165,40 @@ I always wanted to be Peter's bro... in this example it is possible!
   #=> {"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.
+
+== 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
+
+
 == Customizing
 
 === Wrapping

data/lib/representable.rb

@@ -125,6 +125,11 @@ private
         options[:collection] = true
         property(name, options)
       end
+      
+      def hash(name, options={})
+        options[:hash] = true
+        property(name, options)
+      end
     end
     
     

data/lib/representable/binding.rb

@@ -6,38 +6,35 @@ module Representable
       @definition = definition
     end
     
-    
-    # Usually called in concrete ObjectBinding in #write and #read. 
+    # Main entry point for rendering/parsing a property object.
     module Hooks
-    private
-      # Must be called in serialization of concrete ObjectBinding.
-      def write_object(object)
-        object
+      def serialize(value)
+        value
       end
       
-      # Creates a typed property instance.
-      def create_object
-        definition.sought_type.new
+      def deserialize(fragment)
+        fragment
       end
     end
     
+    include Hooks
+    
     
-    # Hooks into #write_object and #create_object to extend typed properties
+    # Hooks into #serialize and #deserialize to extend typed properties
     # at runtime.
     module Extend
-    private
       # Extends the object with its representer before serialization.
-      def write_object(object)
+      def serialize(object)
         extend_for(super)
       end
       
-      def create_object
+      def deserialize(*)
         extend_for(super)
       end
       
-      def extend_for(object)  # TODO: test me.
+      def extend_for(object)
         if mod = definition.representer_module
-          object.extend(mod)
+          object.extend(*mod)
         end
         
         object

data/lib/representable/bindings/json_bindings.rb

@@ -2,53 +2,73 @@ require 'representable/binding'
 
 module Representable
   module JSON
-    class Binding < Representable::Binding
-    private
-      def collect_for(hash)
-        nodes = hash[definition.from] or return
-        nodes = [nodes] unless nodes.is_a?(Array)
-        
-        vals  = nodes.collect { |node| yield node }
-        
-        definition.array? ? vals : vals.first
+    module ObjectBinding
+      # TODO: provide a base ObjectBinding for XML/JSON/MP.
+      include Binding::Extend  # provides #serialize/#deserialize with extend.
+      
+      def serialize(object)
+        super(object).to_hash(:wrap => false)
+      end
+      
+      def deserialize(hash)
+        super(create_object).from_hash(hash)
+      end
+      
+      def create_object
+        definition.sought_type.new
       end
     end
     
-    # Represents plain key-value.
-    class TextBinding < Binding
-      def write(hash, value)
-        hash[definition.from] = value
+    
+    class JSONBinding < Representable::Binding
+      def initialize(definition) # FIXME. make generic.
+        super
+        extend ObjectBinding if definition.typed?
       end
       
       def read(hash)
-        collect_for(hash) do |value|
-          value
-        end
+        fragment = hash[definition.from]
+        deserialize_from(fragment)
+      end
+      
+      def write(hash, value)
+        hash[definition.from] = serialize_for(value)
       end
     end
-  
-    # Represents a tag with object binding.
-    class ObjectBinding < Binding
-      include Representable::Binding::Hooks # includes #create_object and #write_object.
-      include Representable::Binding::Extend
-      
-      def write(hash, object)
-        if definition.array?
-          hash[definition.from] = object.collect { |obj| serialize(obj) }
-        else
-          hash[definition.from] = serialize(object)
-        end
+    
+    
+    class PropertyBinding < JSONBinding
+      def serialize_for(value)
+        serialize(value)
       end
       
-      def read(hash)
-        collect_for(hash) do |node|
-          create_object.from_hash(node)
+      def deserialize_from(fragment)
+        deserialize(fragment)
+      end
+    end
+    
+    
+    class CollectionBinding < JSONBinding
+      def serialize_for(value)
+        value.collect { |obj| serialize(obj) }
+      end
+      
+      def deserialize_from(fragment)
+        fragment ||= {}
+        fragment.collect { |item_fragment| deserialize(item_fragment) }
+      end
+    end
+    
+    
+    class HashBinding < JSONBinding
+      def serialize_for(value)
+        {}.tap do |hash|
+          value.each { |key, obj| hash[key] = serialize(obj) }
         end
       end
       
-    private
-      def serialize(object)
-        write_object(object).to_hash(:wrap => false)
+      def deserialize_from(fragment)
+        fragment.each { |key, item_fragment| fragment[key] = deserialize(item_fragment) }
       end
     end
   end

data/lib/representable/bindings/xml_bindings.rb

@@ -2,90 +2,127 @@ require 'representable/binding'
 
 module Representable
   module XML
-    class Binding < Representable::Binding
-      def read(xml)
-        value_from_node(xml)
+    module ObjectBinding
+      # TODO: provide a base ObjectBinding for XML/JSON/MP.
+      include Binding::Extend  # provides #serialize/#deserialize with extend.
+      
+      def serialize(object)
+        super(object).to_node(:wrap => false)
       end
       
-    private
-      def xpath
-        definition.from
+      def deserialize(hash)
+        super(create_object).from_node(hash)
       end
-
-      def collect_for(xml)
-        nodes = xml.search("./#{xpath}")
-        vals  = nodes.collect { |node| yield node }
-        
-        definition.array? ? vals : vals.first
+      
+      def deserialize_node(node)
+        deserialize(node)
+      end
+      
+      def serialize_node(node, value)
+        serialize(value)
+      end
+      
+      def create_object
+        definition.sought_type.new
       end
     end
     
     
-    # Represents a tag attribute.
-    class AttributeBinding < Binding
-      def write(xml, values)
-        xml[definition.from] = values.to_s
+    class PropertyBinding < Binding
+      def initialize(definition)
+        super
+        extend ObjectBinding if definition.typed? # FIXME.
       end
-
+      
+      def write(parent, value)
+        parent << serialize_for(value, parent)
+      end
+      
+      def read(node)
+        nodes = node.search("./#{xpath}")
+        return 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 =  Nokogiri::XML::Node.new(definition.from, parent.document)
+        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)
+      end
+      
     private
-      def value_from_node(xml)
-        xml[definition.from]
+      def xpath
+        definition.from
       end
     end
     
-    
-    # Represents text content in a tag. # FIXME: is this tested???
-    class TextBinding < Binding
-      def write(xml, value)
-        if definition.array?
-          value.each do |v|
-            add(xml, definition.from, v)
-          end
-        else
-          add(xml, definition.from, value)
+    class CollectionBinding < PropertyBinding
+      def write(parent, value)
+        serialize_items(value, parent).each do |node|
+          parent << node
         end
       end
-
-    private
-      def value_from_node(xml)
-        collect_for(xml) do |node| 
-          node.content
+      
+      def serialize_items(value, parent)
+        value.collect do |obj|
+          serialize_for(obj, parent)
         end
       end
       
-      def add(xml, name, value)
-        child = xml.add_child Nokogiri::XML::Node.new(name, xml.document)
-        child.content = value
+      def deserialize_from(nodes)
+        nodes.collect do |item|
+          deserialize_node(item)
+        end
       end
     end
     
-
-    # Represents a tag with object binding.
-    class ObjectBinding < Binding
-      include Representable::Binding::Hooks # includes #create_object and #write_object.
-      include Representable::Binding::Extend
-      
-      # Adds the ref's markup to +xml+. 
-      def write(xml, object)
-        if definition.array?
-          object.each do |item|
-            write_entity(xml, item)
-          end
-        else
-          write_entity(xml, object)
+    
+    class HashBinding < CollectionBinding
+      def serialize_items(value, parent)
+        value.collect do |k, v|
+          node = Nokogiri::XML::Node.new(k, parent.document)
+          serialize_node(node, v)
         end
       end
-
-    private
-      # Deserializes the ref's element from +xml+.
-      def value_from_node(xml)
-        collect_for(xml) do |node|
-          create_object.from_node(node)
+      
+      def deserialize_from(nodes)
+        {}.tap do |hash|
+          nodes.children.each do |node|
+            hash[node.name] = deserialize_node(node)
+          end
         end
       end
+    end
+    
+    
+    # Represents a tag attribute. Currently this only works on the top-level tag.
+    class AttributeBinding < PropertyBinding
+      def read(node)
+        deserialize(node[definition.from])
+      end
+      
+      def serialize_for(value, parent)
+        parent[definition.from] = serialize(value.to_s)
+      end
       
-      def write_entity(xml, entity)
-        xml.add_child(write_object(entity).to_node)
+      def write(parent, value)
+        serialize_for(value, parent)
       end
     end
   end

data/lib/representable/definition.rb

@@ -1,22 +1,12 @@
 module Representable
   # Created at class compile time. Keeps configuration options for one property.
   class Definition
-    attr_reader :name, :sought_type, :from, :default, :representer_module, :attribute
+    attr_reader :name, :options
     alias_method :getter, :name
     
     def initialize(sym, options={})
-      @name               = sym.to_s
-      @array              = options[:collection]
-      @from               = (options[:from] || name).to_s
-      @sought_type        = options[:class]
-      @default            = options[:default]
-      @default            ||= [] if array?
-      @representer_module = options[:extend]  # DISCUSS: move to Representable::DCI?
-      @attribute          = options[:attribute] 
-    end
-
-    def instance_variable_name
-      :"@#{name}"
+      @name     = sym.to_s
+      @options  = options
     end
 
     def setter
@@ -24,26 +14,36 @@ module Representable
     end
     
     def typed?
-      sought_type.is_a?(Class)
+      sought_type.is_a?(Class) or representer_module  # also true if only :extend is set, for people who want solely rendering.
     end
     
     def array?
-      @array
-    end
-    
-    # Applies the block to +value+ which might also be a collection.
-    def apply(value)
-      return value unless value # DISCUSS: is that ok here?
-      
-      if array?
-        value = value.collect do |item|
-          yield item
-        end
-      else
-        value = yield value
-      end
-      
-      value
+      options[:collection]
+    end
+    
+    def hash?
+      options[:hash]
+    end
+    
+    def sought_type
+      options[:class]
+    end
+    
+    def from
+      (options[:from] || name).to_s
+    end
+    
+    def default
+      options[:default] ||= [] if array?  # FIXME: move to CollectionBinding!
+      options[:default]
+    end
+    
+    def representer_module
+      options[:extend]
+    end
+    
+    def attribute
+      options[:attribute]
     end
   end
 end