representable 1.7.7 → 1.8.0

data/Rakefile

@@ -9,9 +9,3 @@ Rake::TestTask.new(:test) do |test|
   test.test_files = FileList['test/*_test.rb']
   test.verbose = true
 end
-
-Rake::TestTask.new(:test18) do |test|
-  test.libs << 'test'
-  test.test_files = FileList['test/*_test.rb'] - ['test/mongoid_test.rb', 'test/yaml_test.rb']
-  test.verbose = true
-end

data/lib/representable.rb

@@ -1,4 +1,3 @@
-require 'representable/deprecations'
 require 'representable/definition'
 require 'representable/mapper'
 require 'representable/config'
@@ -12,8 +11,6 @@ module Representable
       extend ClassMethods
       extend ClassMethods::Declarations
       extend DSLAdditions
-
-      include Deprecations
     end
   end
 
@@ -35,9 +32,7 @@ private
   end
 
   def representable_binding_for(attribute, format, options)
-    context = attribute.options[:decorator_scope] ? self : represented # DISCUSS: pass both represented and representer into Binding and do it there?
-
-    format.build(attribute, represented, options, context)
+    format.build(attribute, represented, self, options)
   end
 
   def cleanup_options(options) # TODO: remove me. this clearly belongs in Representable.
@@ -54,8 +49,8 @@ private
   end
 
 
-  def representation_wrap
-    representable_attrs.wrap_for(self.class.name) # FIXME: where is this needed?
+  def representation_wrap(*args)
+    representable_attrs.wrap_for(self.class.name, represented, *args)
   end
 
   def represented
@@ -105,28 +100,10 @@ private
         representable_attrs.wrap = name
       end
 
-      # Declares a represented document node, which is usually a XML tag or a JSON key.
-      #
-      # Examples:
-      #
-      #   property :name
-      #   property :name, :from => :title
-      #   property :name, :class => Name
-      #   property :name, :default => "Mike"
-      #   property :name, :render_nil => true
-      #   property :name, :readable => false
-      #   property :name, :writeable => false
       def property(name, options={}, &block)
         representable_attrs << definition_class.new(name, options)
       end
 
-      # Declares a represented document node collection.
-      #
-      # Examples:
-      #
-      #   collection :products
-      #   collection :products, :from => :item
-      #   collection :products, :class => Product
       def collection(name, options={}, &block)
         options[:collection] = true # FIXME: don't override original.
         property(name, options, &block)
@@ -155,25 +132,30 @@ private
     # Allows you to nest a block of properties in a separate section while still mapping them to the outer object.
     def nested(name, options={}, &block)
       options = options.merge(
-        :decorator  => true,
-        :getter     => lambda { |*| self },
-        :setter     => lambda { |*| },
-        :instance   => lambda { |*| self }
-      )
+        :use_decorator => true,
+        :getter        => lambda { |*| self },
+        :setter        => lambda { |*| },
+        :instance      => lambda { |*| self }
+      ) # DISCUSS: should this be a macro just as :parse_strategy?
 
       property(name, options, &block)
     end
 
     def property(name, options={}, &block)
-      parent = representable_attrs[name]
+      modules = []
+
+      if options[:inherit] # TODO: move this to Definition.
+        parent  = representable_attrs[name]
+        modules << parent[:extend].evaluate(nil) if parent[:extend]# we can savely assume this is _not_ a lambda. # DISCUSS: leave that in #representer_module?
+      end # FIXME: can we handle this in super/Definition.new ?
 
       if block_given?
-        options[:extend] = inline_representer_for(parent, name, options, &block) # FIXME: passing parent sucks since we don't use it all the time.
+        handle_deprecated_inline_extend!(modules, options)
+
+        options[:extend] = inline_representer_for(modules, name, options, &block)
       end
 
-      if options[:inherit]
-        parent.options.merge!(options) and return parent
-      end # FIXME: can we handle this in super/Definition.new ?
+      return parent.merge!(options) if options.delete(:inherit)
 
       super
     end
@@ -186,16 +168,30 @@ private
     end
 
   private
-    def inline_representer_for(parent, name, options, &block)
-      representer = options[:decorator] ? Decorator : self
-
-      modules =  [representer_engine]
-      modules << parent.representer_module if options[:inherit]
-      modules << options[:extend]
+    def inline_representer_for(modules, name, options, &block)
+      representer = options[:use_decorator] ? Decorator : self
+      modules     = [representer_engine] + modules
 
       representer.inline_representer(modules.compact.reverse, name, options, &block)
     end
+
+    def handle_deprecated_inline_extend!(modules, options) # TODO: remove in 2.0.
+      return unless include_module = options.delete(:extend) and not options[:inherit]
+
+      warn "[Representable] Using :extend with an inline representer is deprecated. Include the module in the inline block."
+      modules << include_module
+    end
   end # DSLAdditions
 end
 
-require 'representable/decorator'
+
+module Representable
+  autoload :Hash, 'representable/hash'
+
+  module Hash
+    autoload :AllowSymbols, 'representable/hash/allow_symbols'
+    autoload :Collection, 'representable/hash/collection'
+  end
+
+  autoload :Decorator, 'representable/decorator'
+end

data/lib/representable/binding.rb

@@ -10,29 +10,35 @@ module Representable
 
     def self.build(definition, *args)
       # DISCUSS: move #create_binding to this class?
-      return definition.create_binding(*args) if definition.binding
+      return definition.create_binding(*args) if definition[:binding]
       build_for(definition, *args)
     end
 
-    def initialize(definition, represented, user_options={}, exec_context=represented)  # TODO: remove default arg for user options. # DISCUSS: make exec_context an options hash?
+    def initialize(definition, represented, decorator, user_options={})  # TODO: remove default arg for user options.
       super(definition)
       @represented  = represented
+      @decorator    = decorator
       @user_options = user_options
-      @exec_context = exec_context
+
+      setup_exec_context!
     end
 
     attr_reader :user_options, :represented # TODO: make private/remove.
 
+    def as # DISCUSS: private?
+      evaluate_option(:as)
+    end
+
     # Retrieve value and write fragment to the doc.
     def compile_fragment(doc)
-      represented_exec_for(:writer, doc) do
+      evaluate_option(:writer, doc) do
         write_fragment(doc, get)
       end
     end
 
     # Parse value from doc and update the model property.
     def uncompile_fragment(doc)
-      represented_exec_for(:reader, doc) do
+      evaluate_option(:reader, doc) do
         read_fragment(doc) do |value|
           set(value)
         end
@@ -55,7 +61,7 @@ module Representable
 
       if value == FragmentNotFound
         return unless has_default?
-        value = default
+        value = self[:default]
       end
 
       yield value
@@ -65,47 +71,52 @@ module Representable
       read(doc)
     end
 
-    # concept: Option#call(*args) => send(string)/lambda()
-    #   dynamic string
     def get
-      represented_exec_for(:getter) do
+      evaluate_option(:getter) do
         exec_context.send(getter)
       end
     end
 
     def set(value)
-      represented_exec_for(:setter, value) do
+      evaluate_option(:setter, value) do
         exec_context.send(setter, value)
       end
     end
 
-    # the remaining methods in this class are format-independent and should be in Definition.
+    # DISCUSS: do we really need that?
+    def representer_module_for(object, *args)
+      evaluate_option(:extend, object) # TODO: pass args? do we actually have args at the time this is called (compile-time)?
+    end
 
   private
-    attr_reader :exec_context
+    def setup_exec_context!
+      context = represented
+      context = self        if self[:exec_context] == :binding
+      context = decorator   if self[:exec_context] == :decorator
 
-    # Execute the block for +option_name+ on the represented object.
-    # Executes passed block when there's no lambda for option.
-    def represented_exec_for(option_name, *args)
-      return yield unless options[option_name]
-      call_proc_for(options[option_name], *args)
-    end
-
-    # All lambdas are executed on exec_context which is either represented or the decorator instance.
-    def call_proc_for(proc, *args)
-      return proc unless proc.is_a?(Proc)
-      # TODO: call method when proc is sympbol.
-      args << user_options # DISCUSS: we assume user_options is a Hash!
-      exec_context.instance_exec(*args, &proc)
+      @exec_context = context
     end
 
+    attr_reader :exec_context, :decorator
 
-    module Prepare
-      def representer_module_for(object, *args)
-        call_proc_for(representer_module, object)   # TODO: how to pass additional data to the computing block?`
+    # 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
-    include Prepare
+
+
+    # Options instance gets passed to lambdas when pass_options: true.
+    # This is considered the new standard way and should be used everywhere for forward-compat.
+    Options = Struct.new(:binding, :user_options, :represented, :decorator)
 
 
     # Delegates to call #to_*/from_*.
@@ -114,28 +125,39 @@ module Representable
         ObjectSerializer.new(self, object).call
       end
 
-      def deserialize(data, object=lambda { get })
+      def deserialize(data)
         # DISCUSS: does it make sense to skip deserialization of nil-values here?
-        ObjectDeserializer.new(self, object).call(data)
+        ObjectDeserializer.new(self).call(data)
       end
 
-      def create_object(fragment)
-        instance_for(fragment) or class_for(fragment)
+      def create_object(fragment, *args)
+        instance_for(fragment, *args) or class_for(fragment, *args)
       end
 
     private
       def class_for(fragment, *args)
-        item_class = class_from(fragment) or return fragment
+        item_class = class_from(fragment, *args) or return handle_deprecated_class(fragment)
         item_class.new
       end
 
       def class_from(fragment, *args)
-        call_proc_for(deserialize_class, fragment)
+        evaluate_option(:class, fragment, *args)
       end
 
       def instance_for(fragment, *args)
-        return unless options[:instance]
-        call_proc_for(options[:instance], fragment) or get
+        instance = evaluate_option(:instance, fragment, *args)
+
+        if instance === true # TODO: remove in 2.0.
+          warn "[Representable] `instance: lambda { true }` is deprecated. Apparently, you know what you're doing, so use `parse_strategy: :sync` instead."
+          return get
+        end
+
+        instance
+      end
+
+      def handle_deprecated_class(fragment) # TODO: remove in 2.0.
+        warn "[Representable] `class: lambda { nil }` is deprecated. To return the fragment from parsing, use `instance: lambda { |fragment, *args| fragment }` instead."
+        fragment
       end
     end
   end

data/lib/representable/bindings/hash_bindings.rb

@@ -12,14 +12,14 @@ module Representable
       end
 
       def read(hash)
-        return FragmentNotFound unless hash.has_key?(from) # DISCUSS: put it all in #read for performance. not really sure if i like returning that special thing.
+        return FragmentNotFound unless hash.has_key?(as) # DISCUSS: put it all in #read for performance. not really sure if i like returning that special thing.
 
-        fragment = hash[from]
+        fragment = hash[as]
         deserialize(fragment)
       end
 
       def write(hash, value)
-        hash[from] = serialize(value)
+        hash[as] = serialize(value)
       end
 
       def deserialize_from(fragment)
@@ -37,7 +37,6 @@ module Representable
 
     class CollectionBinding < PropertyBinding
       def serialize(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| super(item) } # TODO: i don't want Array but Forms here - what now?
       end
 

data/lib/representable/bindings/xml_bindings.rb

@@ -8,17 +8,17 @@ module Representable
 
       def self.build_for(definition, *args)
         return CollectionBinding.new(definition, *args)      if definition.array?
-        return HashBinding.new(definition, *args)            if definition.hash? and not definition.options[:use_attributes] # FIXME: hate this.
-        return AttributeHashBinding.new(definition, *args)   if definition.hash? and definition.options[:use_attributes]
-        return AttributeBinding.new(definition, *args)       if definition.attribute
-        return ContentBinding.new(definition, *args)         if definition.content
+        return HashBinding.new(definition, *args)            if definition.hash? and not definition[:use_attributes] # FIXME: hate this.
+        return AttributeHashBinding.new(definition, *args)   if definition.hash? and definition[:use_attributes]
+        return AttributeBinding.new(definition, *args)       if definition[:attribute]
+        return ContentBinding.new(definition, *args)         if definition[:content]
         new(definition, *args)
       end
 
       def write(parent, value)
         wrap_node = parent
 
-        if wrap = options[:wrap]
+        if wrap = self[:wrap]
           parent << wrap_node = node_for(parent, wrap)
         end
 
@@ -35,7 +35,7 @@ module Representable
       # 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)
+        node = node_for(parent, as)
         serialize_node(node, value)
       end
 
@@ -62,12 +62,12 @@ module Representable
 
     private
       def xpath
-        from
+        as
       end
 
       def find_nodes(doc)
         selector  = xpath
-        selector  = "#{options[:wrap]}/#{xpath}" if options[:wrap]
+        selector  = "#{self[:wrap]}/#{xpath}" if self[:wrap]
         nodes     = doc.xpath(selector)
       end
 
@@ -143,11 +143,11 @@ module Representable
     # Represents a tag attribute. Currently this only works on the top-level tag.
     class AttributeBinding < PropertyBinding
       def read(node)
-        deserialize(node[from])
+        deserialize(node[as])
       end
 
       def serialize_for(value, parent)
-        parent[from] = serialize(value.to_s)
+        parent[as] = serialize(value.to_s)
       end
 
       def write(parent, value)

data/lib/representable/bindings/yaml_bindings.rb

@@ -9,7 +9,7 @@ module Representable
       end
 
       def write(map, value)
-        map.children << Psych::Nodes::Scalar.new(from)
+        map.children << Psych::Nodes::Scalar.new(as)
         map.children << serialize(value)  # FIXME: should be serialize.
       end
 
@@ -36,7 +36,7 @@ module Representable
     class CollectionBinding < PropertyBinding
       def serialize(value)
         Psych::Nodes::Sequence.new.tap do |seq|
-          seq.style = Psych::Nodes::Sequence::FLOW if options[:style] == :flow
+          seq.style = Psych::Nodes::Sequence::FLOW if self[:style] == :flow
           value.each { |obj| seq.children << super(obj) }
         end
       end

data/lib/representable/coercion.rb

@@ -28,7 +28,7 @@ module Representable::Coercion
       representable_attrs.inheritable_array(:coercer_class).first.attribute(name, options[:type])
 
       # By using :getter we "pre-occupy" this directive, but we avoid creating accessors, which i find is the cleaner way.
-      options[:decorator_scope] = true
+      options[:exec_context] = :decorator
       options[:getter] = lambda { |*| coercer.coerce(name, represented.send(name)) }
       options[:setter] = lambda { |v,*| represented.send("#{name}=", coercer.coerce(name, v)) }
 

data/lib/representable/config.rb

@@ -31,13 +31,19 @@ module Representable
       values.each(*args, &block)
     end
 
-    attr_accessor :wrap
+    def wrap=(value)
+      value = value.to_s if value.is_a?(Symbol)
+      @wrap = Uber::Options::Value.new(value)
+    end
 
     # Computes the wrap string or returns false.
-    def wrap_for(name)
-      return unless wrap
-      return infer_name_for(name) if wrap === true
-      wrap
+    def wrap_for(name, context, *args)
+      return unless @wrap
+
+      value = @wrap.evaluate(context, *args)
+
+      return infer_name_for(name) if value === true
+      value
     end
 
     # Write representer configuration into this hash.