representable 1.7.7 → 1.8.0

data/lib/representable/definition.rb

@@ -1,16 +1,36 @@
+require 'uber/options'
+require "representable/parse_strategies"
+
 module Representable
   # Created at class compile time. Keeps configuration options for one property.
-  class Definition
-    attr_reader :name, :options
+  class Definition < Hash
+    attr_reader :name
     alias_method :getter, :name
 
     def initialize(sym, options={})
-      @name     = sym.to_s
-      @options  = options
+      super()
+      options = options.clone
+
+      handle_deprecations!(options)
+
+      @name   = sym.to_s
+      # defaults:
+      options[:as] ||= @name
+
+      setup!(options)
+    end
+
+    # TODO: test merge!.
+    def merge!(options)
+      setup!(options)
+      self
     end
 
-    def clone
-      self.class.new(name, options.clone) # DISCUSS: make generic Definition.cloned_attribute that passes list to constructor.
+    private :default, :[]=
+
+    def options # TODO: remove in 2.0.
+      warn "Representable::Definition#option is deprecated, use #[] directly."
+      self
     end
 
     def setter
@@ -18,65 +38,77 @@ module Representable
     end
 
     def typed?
-      deserialize_class.is_a?(Class) or representer_module or options[:instance]  # also true if only :extend is set, for people who want solely rendering.
-    end
-
-    def array?
-      options[:collection]
+      self[:class] or self[:extend] or self[:instance]
     end
 
-    def hash?
-      options[:hash]
+    def representable?
+      return if self[:representable] === false
+      self[:representable] or typed?
     end
 
-    def deserialize_class
-      options[:class]
+    def array?
+      self[:collection]
     end
 
-    def from
-      # TODO: deprecate :from.
-      (options[:from] || options[:as] || name).to_s
+    def hash?
+      self[:hash]
     end
 
     def default_for(value)
-      return default if skipable_nil_value?(value)
+      return self[:default] if skipable_nil_value?(value)
       value
     end
 
     def has_default?
-      options.has_key?(:default)
+      has_key?(:default)
     end
 
     def representer_module
-      options[:extend] or options[:decorator]
+      self[:extend]
     end
 
-    def attribute
-      options[:attribute]
+    def skipable_nil_value?(value)
+      value.nil? and not self[:render_nil]
     end
 
-    def content
-      options[:content]
+    def create_binding(*args)
+      self[:binding].call(self, *args)
     end
 
-    def skipable_nil_value?(value)
-      value.nil? and not options[:render_nil]
+  private
+    def setup!(options)
+      handle_extend!(options)
+      handle_as!(options)
+
+      # DISCUSS: we could call more macros here (e.g. for :nested).
+      Representable::ParseStrategy.apply!(options)
+
+      for name, value in options
+        value = Uber::Options::Value.new(value) if dynamic_options.include?(name)
+        self[name] = value
+      end
     end
 
-    def default
-      options[:default]
+    def dynamic_options
+      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if]
     end
 
-    def binding
-      options[:binding]
+    def handle_extend!(options)
+      mod = options.delete(:extend) || options.delete(:decorator) and options[:extend] = mod
     end
 
-    def create_binding(*args)
-      binding.call(self, *args)
+    def handle_as!(options)
+      options[:as] = options[:as].to_s if options[:as].is_a?(Symbol) # Allow symbols for as:
     end
 
-    def sync?
-      options[:parse_strategy] == :sync
+    # TODO: remove in 2.0.
+    def handle_deprecations!(options)
+      raise "The :from option got replaced by :as in Representable 1.8!" if options[:from]
+
+      if options[:decorator_scope]
+        warn "[Representable] Deprecation: `decorator_scope: true` is deprecated, use `exec_context: :decorator` instead."
+        options.merge!(:exec_context => :decorator)
+      end
     end
   end
 end

data/lib/representable/deserializer.rb

@@ -1,56 +1,52 @@
 module Representable
-  class CollectionDeserializer < Array # always is the targeted collection, already.
+  class CollectionDeserializer
     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] })
+      fragment.enum_for(:each_with_index).collect do |item_fragment, i|
+        @deserializer = ObjectDeserializer.new(@binding)
 
-        @deserializer.call(item_fragment) # FIXME: what if obj nil?
-      }
+        @deserializer.call(item_fragment, i) # FIXME: what if obj nil?
+      end
     end
   end
 
 
   class ObjectDeserializer
-    # dependencies: Def#options, Def#create_object, Def#get
-    def initialize(binding, object)
+    # dependencies: Def#options, Def#create_object
+    def initialize(binding)
       @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?
+    def call(fragment, *args) # FIXME: args is always i.
+      return fragment unless @binding.typed? # customize with :extend. this is not really straight-forward.
 
-      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
+      # 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?
-      representable = prepare(@object)
-      deserialize(representable, fragment, @binding.user_options)
-      #yield @object
+      representable = prepare(object) # customize with :prepare and :extend.
+
+      deserialize(representable, fragment, @binding.user_options) # deactivate-able via :representable => false.
     end
 
   private
-    def deserialize(object, fragment, options)
+    def deserialize(object, fragment, options) # TODO: merge with #serialize.
+      return object unless @binding.representable?
+
       object.send(@binding.deserialize_method, fragment, options)
     end
 
     def prepare(object)
+      @binding.send(:evaluate_option, :prepare, object) do
+        prepare!(object)
+      end
+    end
+
+    def prepare!(object)
       mod = @binding.representer_module_for(object)
 
       return object unless mod

data/lib/representable/hash.rb

@@ -26,10 +26,11 @@ module Representable
     end
 
 
+    # Note: `#from_hash` still does _not_ stringify incoming hashes. This is per design: Representable is not made for hashes, only,
+    # but for any arbitrary data structure. A generic `key.to_s` with non-hash data would result in weird issues.
+    # I decided it's more predictable to require the user to provide stringified keys.
     def from_hash(data, options={}, binding_builder=PropertyBinding)
-      if wrap = options[:wrap] || representation_wrap
-        data = data[wrap.to_s] || {} # DISCUSS: don't initialize this more than once. # TODO: this should be done with #read.
-      end
+      data = filter_wrap(data, options)
 
       update_properties_from(data, options, binding_builder)
     end
@@ -37,9 +38,19 @@ module Representable
     def to_hash(options={}, binding_builder=PropertyBinding)
       hash = create_representation_with({}, options, binding_builder)
 
-      return hash unless wrap = options[:wrap] || representation_wrap
+      return hash unless wrap = options[:wrap] || representation_wrap(options)
 
       {wrap => hash}
     end
+
+  private
+    def filter_wrap(data, options)
+      return data unless wrap = options[:wrap] || representation_wrap(options)
+      filter_wrap_for(data, wrap)
+    end
+
+    def filter_wrap_for(data, wrap)
+      data[wrap.to_s] || {} # DISCUSS: don't initialize this more than once. # TODO: this should be done with #read.
+    end
   end
 end

data/lib/representable/hash/allow_symbols.rb

@@ -0,0 +1,27 @@
+module Representable
+  module Hash
+    module AllowSymbols
+    private
+      def filter_wrap_for(data, *args)
+        super(Conversion.stringify_keys(data), *args)
+      end
+
+      def update_properties_from(data, *args)
+        super(Conversion.stringify_keys(data), *args)
+      end
+    end
+
+    class Conversion
+      # DISCUSS: we could think about mixin in IndifferentAccess here (either hashie or ActiveSupport).
+      # or decorating the hash.
+      def self.stringify_keys(hash)
+        hash = hash.dup
+
+        hash.keys.each do |k|
+          hash[k.to_s] = hash.delete(k)
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/representable/json.rb

@@ -1,4 +1,3 @@
-require 'representable/hash'
 require 'multi_json'
 
 module Representable

data/lib/representable/json/collection.rb

@@ -1,5 +1,3 @@
-require 'representable/hash/collection'
-
 module Representable::JSON
   module Collection
     include Representable::JSON

data/lib/representable/mapper.rb

@@ -1,12 +1,11 @@
-require 'representable/feature/readable_writeable'
+require 'representable/readable_writeable'
 
 module Representable
   # Render and parse by looping over the representer's properties and dispatching to bindings.
   # Conditionals are handled here, too.
   class Mapper
-  # DISCUSS: we need @represented here for evaluating the :if blocks. this could be done in the bindings_for asset.
     module Methods
-      def initialize(bindings, represented, options)
+      def initialize(bindings, represented, options) # TODO: get rid of represented dependency.
         @represented  = represented # the (extended) model.
         @bindings     = bindings
       end
@@ -17,7 +16,7 @@ module Representable
         bindings.each do |bin|
           deserialize_property(bin, doc, options)
         end
-        represented
+        @represented
       end
 
       def serialize(doc, options)
@@ -28,8 +27,6 @@ module Representable
       end
 
     private
-      attr_reader :represented
-
       def serialize_property(binding, doc, options)
         return if skip_property?(binding, options)
         compile_fragment(binding, doc)
@@ -54,13 +51,9 @@ module Representable
       end
 
       def skip_conditional_property?(binding)
-        # TODO: move to Binding.
-        return unless condition = binding.options[:if]
-
-        args = []
-        args << binding.user_options if condition.arity > 0 # TODO: remove arity check. users should know whether they pass options or not.
+        return unless condition = binding[:if]
 
-        not represented.instance_exec(*args, &condition)
+        not binding.send(:evaluate_option, :if)
       end
 
       def compile_fragment(bin, doc)
@@ -73,6 +66,6 @@ module Representable
     end
 
     include Methods
-    include Feature::ReadableWriteable # DISCUSS: make this pluggable.
+    include ReadableWriteable # DISCUSS: make this pluggable.
   end
 end

data/lib/representable/parse_strategies.rb

@@ -0,0 +1,57 @@
+module Representable
+  # Parse strategies are just a combination of representable's options. They save you from memoizing the
+  # necessary parameters.
+  #
+  # Feel free to contribute your strategy if you think it's worth sharing!
+  class ParseStrategy
+    def self.apply!(options)
+      return unless strategy = options[:parse_strategy]
+
+      strategy = :proc if strategy.is_a?(::Proc)
+
+      parse_strategies[strategy].apply!(name, options)
+    end
+
+    def self.parse_strategies
+      {
+        :sync                 => Sync,
+        :find_or_instantiate  => FindOrInstantiate,
+        :proc                 => Proc
+      }
+    end
+
+
+    class Proc
+      def self.apply!(name, options)
+        options[:setter]       = lambda { |*| }
+        options[:pass_options] = true
+        options[:instance]     = options[:parse_strategy]
+      end
+    end
+
+
+    class Sync
+      def self.apply!(name, options)
+        options[:setter]       = lambda { |*| }
+        options[:pass_options] = true
+        options[:instance]     = options[:collection] ?
+          lambda { |fragment, i, options| options.binding.get[i] } :
+          lambda { |fragment, options|    options.binding.get }
+      end
+    end
+
+
+    # replaces current collection.
+    class FindOrInstantiate
+      def self.apply!(name, options)
+        options[:pass_options] = true
+        options[:instance]     = lambda { |fragment, *args|
+          args = args.last # TODO: don't pass i as separate block parameter but in Options.
+          object_class = args.binding[:class].evaluate(self, fragment, args)
+
+          object_class.find(fragment["id"]) or object_class.new
+        }
+      end
+    end
+  end
+end

data/lib/representable/readable_writeable.rb

@@ -0,0 +1,29 @@
+module Representable
+  module ReadableWriteable
+    def deserialize_property(binding, doc, options)
+      return unless binding.writeable?
+      super
+    end
+
+    def serialize_property(binding, doc, options)
+      return unless binding.readable?
+      super
+    end
+  end
+
+
+  # TODO: i hate monkey-patching Definition here since it globally adds this options. However, for now this should be ok :-)
+  Definition.class_eval do
+    # Checks and returns if the property is writeable
+    def writeable?
+      return self[:writeable] if self.has_key?(:writeable)
+      true
+    end
+
+    # Checks and returns if the property is readable
+    def readable?
+      return self[:readable] if self.has_key?(:readable)
+      true
+    end
+  end
+end