representable 0.11.0 → 0.12.0

data/CHANGES.textile

@@ -1,6 +1,13 @@
+h2. 0.12.0
+
+* @:as@ is now @:class@.
+
+
 h2. 0.11.0
 
 * Representer modules can now be injected into objects using @#extend@.
+* The @:extend@ option allows setting a representer module for a typed property. This will extend the contained object at runtime roughly following the DCI pattern.
+* Renamed @#representable_property@ and @#representable_collection@ to @#property@ and @#collection@ as we don't have to fear namespace collisions in modules.
 
 h2. 0.10.3
 

data/README.rdoc

@@ -14,7 +14,7 @@ This keeps your representation knowledge in one place when implementing REST ser
 
 * Bidirectional - rendering and parsing
 * OOP documents
-* Support for JSON and XML
+* Support for JSON, XML and MessagePack
 
 
 == Example
@@ -26,33 +26,40 @@ Since you keep forgetting the heroes of your childhood you decide to implement a
 
 == Defining Representations
 
+Representations are usually defined using a module. This makes them super flexibly, you'll see.
+
   require 'representable/json'
 
-  class Hero
+  module HeroRepresenter
     include Representable::JSON
     
-    representable_property :forename
-    representable_property :surename
+    property :forename
+    property :surename
   end
 
-This declares two simple properties. Representable will automatically add accessors to the class.
+By using #property we declare two simple attributes. Representable will automatically add accessors to the module.
 
-Alternatively, if you don't want declarations in your models, use a module.
+To use your representer include it in the matching class. Note that you could reuse a representer in multiple classes. 
 
-  module HeroRepresentation
-    include Representable
-    
-    representable_property :forename
-    representable_property :surename
+  class Hero
+  	include Representable
+    include HeroRepresenter
   end
 
-This module needs a host class to be used with.
+Many people dislike including representers on class layer. You might also extend an object at runtime.
+
+  Hero.new.extend(HeroRepresenter)
+
+Alternatively, if you don't like modules (which you shouldn't),  declarations can be put into classes directly.
 
   class Hero
     include Representable::JSON
-    include HeroRepresentation
+    
+    property :forename
+    property :surename
   end
 
+
 == Rendering
 
 Now let's create and render our first hero.
@@ -77,12 +84,12 @@ See how easy this is? You can use an object-oriented method to read from the doc
 
 == Nesting
 
-You need a second domain object. Every hero has a place he comes from.
+You need a second domain object. Every hero has a place it comes from.
 
   class Location
     include Representable::JSON
     
-    representable_property :title
+    property :title
   end
 
 Peter, where ya' from?
@@ -92,11 +99,11 @@ Peter, where ya' from?
 
 It makes sense to embed the location in the hero's document.
 
-  class Hero
-    representable_property :origin, :as => Location
+  module HeroRepresenter
+    property :origin, :class => Location
   end
 
-Using the +:as+ option allows you to include other representable objects.
+Using the +:class+ option allows you to include other representable objects.
 
   peter.origin = neverland
   peter.to_json
@@ -117,26 +124,26 @@ Representable just creates objects from the parsed document - nothing more and n
 
 Heroes have features, special abilities that make 'em a superhero.
 
-  class Hero
-    representable_collection :features
+  module HeroRepresenter
+    collection :features
   end
 
-The second API method is +representable_collection+ and, well, declares a collection.
+The second representable API method is +collection+ and, well, declares a collection.
 
   peter.features = ["stays young", "can fly"]
   peter.to_json
-#=> {"forename":"Peter","surename":"Pan","origin":{"title":"Neverland"},"features":["stays young","can fly"]}
+  #=> {"forename":"Peter","surename":"Pan","origin":{"title":"Neverland"},"features":["stays young","can fly"]}
 
 
 == Typed Collections
 
-Ok, things start working out. Your hero has a name, an origin and a list of features so far. Why not allows adding friends to Peter - nobody wants to be alone!
+Ok, things start working out. Your hero has a name, an origin and a list of features so far. Why not allow adding buddies to Peter - nobody wants to be alone!
 
-  class Hero
-    representable_collection :friends, :as => Hero
+  module HeroRepresenter
+    collection :friends, :class => Hero
   end
 
-Again, we type the collection by using the +:as+ option.
+Again, we type the collection by using the +:class+ option.
 
   nick = Hero.new
   nick.forename = "Nick"
@@ -158,7 +165,7 @@ I always wanted to be Peter's bro... in this example it is possible!
 
 Representable is designed to be very simple. However, a few tweaks are available. What if you want to wrap your document?
 
-  class Hero
+  module HeroRepresenter
     self.representation_wrap = true
   end
 
@@ -166,7 +173,7 @@ Representable is designed to be very simple. However, a few tweaks are available
 
 You can also provide a custom wrapper.
 
-  class Hero
+  module HeroRepresenter
     self.representation_wrap = :boy
   end
 
@@ -177,23 +184,40 @@ You can also provide a custom wrapper.
 
 If your accessor name doesn't match the attribute name in the document, use the +:from+ matcher.
 
-  class Hero
-    representable_property :forename, :from => :name
+  module HeroRepresenter
+    property :forename, :from => :i_am_called
   end
   
-  peter.to_json #=> {"name":"Peter","surename":"Pan"}
+  peter.to_json #=> {"i_am_called":"Peter","surename":"Pan"}
 
 
 === Filtering
 
-Representable allows you to skip properties when rendering or parsing.
-
-  peter.to_json do |name|
-    name == :forename
-  end
+Representable allows you to skip and include properties when rendering or parsing.
 
+  peter.to_json(:include => :forename)
   #=> {"forename":"Peter"}
 
+It gives you convenient +:exclude+ and +:include+ options.
+
+
+== DCI
+
+Representers roughly follow the {DCI}[http://en.wikipedia.org/wiki/Data,_context_and_interaction] pattern when used on objects, only.
+
+  Hero.new.extend(HeroRepresenter)
+
+The only difference is that you have to define which representers to use for typed properties.
+
+	module HeroRepresenter
+	  property :forename
+	  property :surename
+	  collection :features
+	  property :origin, :class => Location
+	  collection :friends, :class => Hero, :extend => HeroRepresenter
+	end
+
+There's no need to specify a representer for the +origin+ property since the +Location+ class statically includes its representation. For +friends+, we can use +:extend+ to tell representable which module to mix in dynamically.
 
 == XML support
 

data/lib/representable.rb

@@ -3,6 +3,7 @@ require 'representable/definition'
 module Representable
   def self.included(base)
     base.class_eval do
+      extend ClassMethods
       extend ClassMethods::Declarations
       extend ClassMethods::Accessors
       
@@ -21,9 +22,9 @@ module Representable
   end
   
   # Reads values from +doc+ and sets properties accordingly.
-  def update_properties_from(doc, &block)
+  def update_properties_from(doc, options, &block)
     representable_bindings.each do |bin|
-      next if eval_property_block(bin, &block)  # skip if block is false.
+      next if skip_property?(bin, options)
       
       value = bin.read(doc) || bin.definition.default
       send(bin.definition.setter, value)
@@ -33,9 +34,9 @@ module Representable
   
 private
   # Compiles the document going through all properties.
-  def create_representation_with(doc, &block)
+  def create_representation_with(doc, options, &block)
     representable_bindings.each do |bin|
-      next if eval_property_block(bin, &block)  # skip if block is false.
+      next if skip_property?(bin, options)
       
       value = send(bin.definition.getter) || bin.definition.default # DISCUSS: eventually move back to Ref.
       bin.write(doc, value) if value
@@ -43,11 +44,11 @@ private
     doc
   end
   
-  # Returns true unless a eventually given block returns false. Yields the symbolized
-  # property name.
-  def eval_property_block(binding)
-    # TODO: no magic symbol conversion!
-    block_given? and not yield binding.definition.name.to_sym
+  # Checks and returns if the property should be included.
+  def skip_property?(binding, options)
+    return unless props = options[:except] || options[:include]
+    res = props.include?(binding.definition.name.to_sym)
+    options[:include] ? !res : res
   end
   
   def representable_attrs
@@ -65,6 +66,13 @@ private
   
   
   module ClassMethods # :nodoc:
+    # Create and yield object and options. Called in .from_json and friends. 
+    def create_represented(document, *args)
+      new.tap do |represented|
+        yield represented, *args if block_given?
+      end
+    end
+    
     module Declarations
       def definition_class
         Definition
@@ -74,13 +82,13 @@ private
       #
       # Examples:
       #
-      #   representable_property :name
-      #   representable_property :name, :from => :title
-      #   representable_property :name, :as => Name
-      #   representable_property :name, :accessors => false
-      #   representable_property :name, :default => "Mike"
-      def representable_property(name, options={})
-        attr = add_representable_property(name, options)
+      #   property :name
+      #   property :name, :from => :title
+      #   property :name, :class => Name
+      #   property :name, :accessors => false
+      #   property :name, :default => "Mike"
+      def property(name, options={})
+        attr = add_property(name, options)
         
         attr_reader(attr.getter) unless options[:accessors] == false
         attr_writer(attr.getter) unless options[:accessors] == false
@@ -90,22 +98,23 @@ private
       #
       # Examples:
       #
-      #   representable_collection :products
-      #   representable_collection :products, :from => :item
-      #   representable_collection :products, :as => Product
-      def representable_collection(name, options={})
+      #   collection :products
+      #   collection :products, :from => :item
+      #   collection :products, :class => Product
+      def collection(name, options={})
         options[:collection] = true
-        representable_property(name, options)
+        property(name, options)
       end
       
     private
-      def add_representable_property(*args)
+      def add_property(*args)
         definition_class.new(*args).tap do |attr|
           representable_attrs << attr
         end
       end
     end
-
+    
+    
     module Accessors
       def representable_attrs
         @representable_attrs ||= Config.new
@@ -117,6 +126,7 @@ private
     end
   end
   
+  
   class Config < Array
     attr_accessor :wrap
     
@@ -135,4 +145,17 @@ private
        downcase
     end
   end
+  
+  
+  # Allows mapping formats to representer classes.
+  # DISCUSS: this module might be removed soon.
+  module Represents
+    def represents(format, options)
+      representer[format] = options[:with]
+    end
+    
+    def representer
+      @represents_map ||= {}
+    end
+  end
 end

data/lib/representable/binding.rb

@@ -0,0 +1,47 @@
+module Representable
+  class Binding
+    attr_reader :definition
+
+    def initialize(definition)
+      @definition = definition
+    end
+    
+    
+    # Usually called in concrete ObjectBinding in #write and #read. 
+    module Hooks
+    private
+      # Must be called in serialization of concrete ObjectBinding.
+      def write_object(object)
+        object
+      end
+      
+      # Creates a typed property instance.
+      def create_object
+        definition.sought_type.new
+      end
+    end
+    
+    
+    # Hooks into #write_object and #create_object to extend typed properties
+    # at runtime.
+    module Extend
+    private
+      # Extends the object with its representer before serialization.
+      def write_object(object)
+        extend_for(super)
+      end
+      
+      def create_object
+        extend_for(super)
+      end
+      
+      def extend_for(object)  # TODO: test me.
+        if mod = definition.representer_module
+          object.extend(mod)
+        end
+        
+        object
+      end
+    end
+  end
+end

data/lib/representable/bindings/json_bindings.rb

@@ -1,16 +1,8 @@
+require 'representable/binding'
+
 module Representable
   module JSON
-    class Binding
-      attr_reader :definition
-
-      def initialize(definition)
-        @definition = definition
-      end
-      
-      def read(hash)
-        value_from_hash(hash)
-      end
-      
+    class Binding < Representable::Binding
     private
       def collect_for(hash)
         nodes = hash[definition.from] or return
@@ -27,9 +19,8 @@ module Representable
       def write(hash, value)
         hash[definition.from] = value
       end
-
-    private
-      def value_from_hash(hash)
+      
+      def read(hash)
         collect_for(hash) do |value|
           value
         end
@@ -38,20 +29,27 @@ module Representable
   
     # Represents a tag with object binding.
     class ObjectBinding < Binding
-      def write(hash, value)
+      include Representable::Binding::Hooks # includes #create_object and #write_object.
+      include Representable::Binding::Extend
+      
+      def write(hash, object)
         if definition.array?
-          hash[definition.from] = value.collect {|v| v.to_hash(:wrap => false)}
+          hash[definition.from] = object.collect { |obj| serialize(obj) }
         else
-          hash[definition.from] = value.to_hash(:wrap => false)
+          hash[definition.from] = serialize(object)
         end
       end
-
-    private
-      def value_from_hash(hash)
+      
+      def read(hash)
         collect_for(hash) do |node|
-          definition.sought_type.from_hash(node)  # call #from_hash as it's already deserialized.
+          create_object.from_hash(node)
         end
       end
+      
+    private
+      def serialize(object)
+        write_object(object).to_hash(:wrap => false)
+      end
     end
   end
 end