representable 1.8.5 → 2.0.0.rc1

data/lib/representable/bindings/xml_bindings.rb

@@ -34,7 +34,6 @@ 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, as)
         serialize_node(node, value)
       end

data/lib/representable/coercion.rb

@@ -1,43 +1,35 @@
 require "virtus"
 
-module Representable::Coercion
-  class Coercer
-    virtus_coercer = Virtus.respond_to?(:model) ? Virtus.model : Virtus
-    include virtus_coercer
-
-    def coerce(name, v) # TODO: test me.
-      # set and get the value as i don't know where exactly coercion happens in virtus.
-      send("#{name}=", v)
-      send(name)
+module Representable
+  module Coercion
+    class Coercer
+      # This gets called when the :render_filter or :parse_filter option is evaluated.
+      # Usually the Coercer instance is an element in a Pipeline to allow >1 filters per property.
+      def call(value, doc, options)
+        Virtus::Attribute.build(options.binding[:type]).coerce(value)
+      end
     end
-  end
-  # separate coercion object doesn't give us initializer and accessors in the represented object (with module representer)!
 
-  def self.included(base)
-    base.class_eval do
-      extend ClassMethods
-      # FIXME: use inheritable_attr when it's ready.
-      representable_attrs.inheritable_array(:coercer_class) << Class.new(Coercer) unless representable_attrs.inheritable_array(:coercer_class).first
+
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        register_feature Coercion
+      end
     end
 
-  end
 
-  module ClassMethods
-    def property(name, options={})
-      return super unless options[:type]
+    module ClassMethods
+      def build_definition(name, options, &block) # Representable::Declarative
+        return super unless type = options[:type]
 
-      representable_attrs.inheritable_array(:coercer_class).first.attribute(name, options[:type])
+        options[:pass_options]  = true # TODO: remove, standard.
 
-      # By using :getter we "pre-occupy" this directive, but we avoid creating accessors, which i find is the cleaner way.
-      options[:exec_context] = :decorator
-      options[:getter] = lambda { |*| coercer.coerce(name, represented.send(name)) }
-      options[:setter] = lambda { |v,*| represented.send("#{name}=", coercer.coerce(name, v)) }
+        options[:render_filter] << coercer = Coercer.new
+        options[:parse_filter]  << coercer
 
-      super
+        super
+      end
     end
   end
-
-  def coercer
-    @coercer ||= representable_attrs.inheritable_array(:coercer_class).first.new
-  end
-end
+end

data/lib/representable/config.rb

@@ -1,73 +1,72 @@
 module Representable
-  # NOTE: the API of Config is subject to change so don't rely too much on this private object.
-  class Config < Hash
-    # DISCUSS: experimental. this will soon be moved to a separate gem
-    module InheritableArray
-      def inheritable_array(name)
-        inheritable_arrays[name] ||= []
-      end
-      def inheritable_arrays
-        @inheritable_arrays ||= {}
-      end
-
-      def inherit(parent)
-        super
+  # Config contains three independent, inheritable directives: features, options and definitions.
+  # It is a hash - just add directives if you need them.
+  #
+  # You may access/alter the property Definitions using #each, #collect, #add, #get.
+  #
+  # * features, [options]: "horizontally"+"vertically" inherited values (inline representer)
+  # * definitions, [options], wrap: "vertically" inherited (class inheritance, module inclusion)
+  #
+  # Inheritance works via Config#inherit!(parent).
+  class Config < Inheritable::Hash
+    # Keep in mind that performance doesn't matter here as 99.9% of all representers are created
+    # at compile-time.
 
-        parent.inheritable_arrays.keys.each do |k|
-          inheritable_array(k).push *parent.inheritable_array(k).clone
+    # Stores Definitions from ::property. It preserves the adding order (1.9+).
+    # Same-named properties get overridden, just like in a Hash.
+    class Definitions < Inheritable::Hash
+      def add(name, options, &block)
+        if options[:inherit] # i like that: the :inherit shouldn't be handled outside.
+          return get(name).merge!(options, &block)
         end
+
+        self[name.to_s] = Definition.new(name, options, &block)
       end
-    end
 
-    def <<(definition)
-      self[definition.name] = definition
+      def get(name)
+        self[name.to_s]
+      end
+
+      extend Forwardable
+      def_delegators :values, :each # so we look like an array. this is only used in Mapper. we could change that so we don't need to hide the hash.
     end
 
-    def [](name)
-      fetch(name.to_s, nil)
+
+    def initialize
+      super
+      merge!(
+        :features    => @features     = Inheritable::Hash.new,
+        :definitions => @definitions  = Definitions.new,
+        :options     => @options      = Inheritable::Hash.new,
+        :wrap        => nil )
     end
+    attr_reader :options
 
-    def each(*args, &block)
-      values.each(*args, &block)
+    def features
+      @features.keys
     end
 
+    # delegate #collect etc to Definitions instance.
+    extend Forwardable
+    def_delegators :@definitions, :get, :add, :each, :size
+    # #collect comes from Hash and then gets delegated to @definitions. don't like that.
+
     def wrap=(value)
       value = value.to_s if value.is_a?(Symbol)
-      @wrap = Uber::Options::Value.new(value)
+      self[:wrap] = Uber::Options::Value.new(value)
     end
 
     # Computes the wrap string or returns false.
     def wrap_for(name, context, *args)
-      return unless @wrap
+      return unless self[:wrap]
 
-      value = @wrap.evaluate(context, *args)
+      value = self[:wrap].evaluate(context, *args)
 
       return infer_name_for(name) if value === true
       value
     end
 
-    # Write representer configuration into this hash.
-    def options
-      @options ||= {}
-    end
-
-    module InheritMethods
-      def cloned
-        collect { |d| d.clone }
-      end
-
-      def inherit(parent)
-        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/declarative.rb

@@ -0,0 +1,78 @@
+module Representable
+  module Declarative
+    def representable_attrs
+      @representable_attrs ||= build_config
+    end
+
+    def representation_wrap=(name)
+      representable_attrs.wrap = name
+    end
+
+    def collection(name, options={}, &block)
+      options[:collection] = true # FIXME: don't override original.
+      property(name, options, &block)
+    end
+
+    def hash(name=nil, options={}, &block)
+      return super() unless name  # allow Object.hash.
+
+      options[:hash] = true
+      property(name, options, &block)
+    end
+
+    # 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(
+        :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)
+      representable_attrs.add(name, options) do |default_options| # handles :inherit.
+        build_definition(name, default_options, &block)
+      end
+    end
+
+    def build_inline(base, features, name, options, &block) # DISCUSS: separate module?
+      Module.new do
+        include Representable
+        feature *features # Representable::JSON or similar.
+        include base if base # base when :inherit, or in decorator.
+
+        instance_exec &block
+      end
+    end
+
+  private
+    # NOTE: this will soon be extracted to separate class, use at your own risk.
+    def build_definition(name, options, &block)
+      # change options[..]= here.
+
+      base = nil
+
+      if options[:inherit] # TODO: move this to Definition.
+        base = representable_attrs.get(name).representer_module
+      end # FIXME: can we handle this in super/Definition.new ?
+
+      if block
+        options[:_inline] = true
+        options[:extend]  = inline_representer_for(base, representable_attrs.features, name, options, &block)
+      end
+    end
+
+    def inline_representer_for(base, features, name, options, &block)
+      representer = options[:use_decorator] ? Decorator : self
+
+      representer.build_inline(base, features.reverse, name, options, &block)
+    end
+
+    def build_config
+      Config.new
+    end
+  end # Declarations
+end

data/lib/representable/decorator.rb

@@ -3,28 +3,57 @@ module Representable
     attr_reader :represented
     alias_method :decorated, :represented
 
+    # TODO: when moving all class methods into ClassMethods, i get a segfault.
     def self.prepare(represented)
       new(represented)
     end
 
-    def self.inline_representer(base_module, name, options, &block)
-      # FIXME: it is wrong to inherit from self here as we just want to "inherit" the included modules but nothing else.
-      Class.new(self).tap do |decorator|
-        decorator.class_eval do # Ruby 1.8.7 wouldn't properly execute the block passed to Class.new!
-          # Remove parent's property definitions before defining the inline ones. #FIXME: don't inherit from self, remove those 2 lines.
-          representable_attrs.clear
-          representable_attrs.inheritable_arrays.clear
+    def self.default_inline_class
+      Representable::Decorator
+    end
 
-          include *base_module
-          instance_exec &block
+    include Representable # include after class methods so Decorator::prepare can't be overwritten by Representable::prepare.
+
+    module InheritModule
+      def inherit_module!(parent)
+        inherited_attrs = parent.representable_attrs[:definitions].keys
+
+        super # in Representable, calls representable_attrs.inherit!(parent.representable_attrs).
+        # now, inline representers are still modules, which is wrong.
+        manifest!(inherited_attrs)
+      end
+
+    private
+       # one level deep manifesting modules into Decorators.
+      def manifest!(names)
+        names.each do |name| # only definitions.
+          definition = representable_attrs.get(name)
+          next unless definition[:_inline] and mod = definition.representer_module # only inline representers.
+
+          # here, we can include Decorator features.
+          inline_representer = build_inline(nil, representable_attrs.features, definition.name, {}) {
+            include mod
+          } # the includer controls what "wraps" the module.
+
+          definition.merge!(:extend => inline_representer)
         end
       end
     end
+    extend InheritModule
 
-    include Representable # include after class methods so Decorator::prepare can't be overwritten by Representable::prepare.
 
     def initialize(represented)
       @represented = represented
     end
+
+  private
+    def self.build_inline(base, features, name, options, &block)
+      Class.new(base || default_inline_class).tap do |decorator|
+        decorator.class_eval do # Ruby 1.8.7 wouldn't properly execute the block passed to Class.new!
+          feature *features
+          instance_exec &block
+        end
+      end
+    end
   end
 end

data/lib/representable/definition.rb

@@ -3,34 +3,41 @@ require "representable/parse_strategies"
 
 module Representable
   # Created at class compile time. Keeps configuration options for one property.
-  class Definition < Hash
+  class Definition
+    include Representable::Cloneable
+
     attr_reader :name
     alias_method :getter, :name
 
-    def initialize(sym, options={})
-      super()
-      options = options.clone
-
-      handle_deprecations!(options)
+    def initialize(sym, options={}, &block)
+      @options = {}
+      # @options = Inheritable::Hash.new # allows deep cloning. we then had to set Pipeline cloneable.
+      @name    = sym.to_s
+      options  = options.clone
 
-      @name   = sym.to_s
       # defaults:
-      options[:as] ||= @name
+      options[:parse_filter]  = Pipeline[*options[:parse_filter]]
+      options[:render_filter] = Pipeline[*options[:render_filter]]
+      options[:as]          ||= @name
 
-      setup!(options)
+      setup!(options, &block)
     end
 
-    # TODO: test merge!.
-    def merge!(options)
-      setup!(options)
+    def merge!(options, &block)
+      options = options.clone
+
+      options[:parse_filter]  = @options[:parse_filter].push(*options[:parse_filter])
+      options[:render_filter] = @options[:render_filter].push(*options[:render_filter])
+
+      setup!(options, &block) # FIXME: this doesn't yield :as etc.
       self
     end
 
-    private :[]= # TODO: re-privatize #default when this is sorted with Rubinius.
+    extend Forwardable
+    def_delegators :@runtime_options, :[], :each
 
-    def options # TODO: remove in 2.0.
-      warn "Representable::Definition#option is deprecated, use #[] directly."
-      self
+    def clone
+      self.class.new(name, @options.clone)
     end
 
     def setter
@@ -55,44 +62,54 @@ module Representable
     end
 
     def default_for(value)
-      return self[:default] if skipable_nil_value?(value)
+      return self[:default] if skipable_empty_value?(value)
       value
     end
 
     def has_default?
-      has_key?(:default)
+      @options.has_key?(:default)
     end
 
     def representer_module
-      self[:extend]
+      @options[:extend]
     end
 
     def skipable_empty_value?(value)
       return true if array? and self[:render_empty] == false and value and value.size == 0  # TODO: change in 2.0, don't render emtpy.
       value.nil? and not self[:render_nil]
     end
-    alias_method :skipable_nil_value?, :skipable_empty_value? # TODO: remove in 1.9 .
 
     def create_binding(*args)
       self[:binding].call(self, *args)
     end
 
   private
-    def setup!(options)
+    def setup!(options, &block)
       handle_extend!(options)
       handle_as!(options)
 
       # DISCUSS: we could call more macros here (e.g. for :nested).
       Representable::ParseStrategy.apply!(options)
 
+      yield options if block_given?
+      @options.merge!(options)
+
+      runtime_options!(@options)
+    end
+
+    # wrapping dynamic options in Value does save runtime, as this is used very frequently (and totally unnecessary to wrap an option
+    # at runtime, its value never changes).
+    def runtime_options!(options)
+      @runtime_options = {}
+
       for name, value in options
         value = Uber::Options::Value.new(value) if dynamic_options.include?(name)
-        self[name] = value
+        @runtime_options[name] = value
       end
     end
 
     def dynamic_options
-      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize]
+      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter]
     end
 
     def handle_extend!(options)
@@ -102,15 +119,5 @@ module Representable
     def handle_as!(options)
       options[:as] = options[:as].to_s if options[:as].is_a?(Symbol) # Allow symbols for as:
     end
-
-    # 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