representable 2.3.0 → 2.4.0.rc1

data/lib/representable/decorator.rb

@@ -1,11 +1,8 @@
 require "representable"
+require "uber/inheritable_attr"
 
 module Representable
   class Decorator
-    class << self
-      include Cloneable
-    end
-
     attr_reader :represented
     alias_method :decorated, :represented
 
@@ -14,57 +11,31 @@ module Representable
       new(represented)
     end
 
-    def self.default_inline_class
+    def self.default_nested_class #FIXME. SHOULD we move that into NestedBuilder?
       Representable::Decorator
     end
 
+    # extend ::Declarative::Heritage::Inherited # DISCUSS: currently, that is handled via Representable::inherited.
+
     # This is called from inheritable_attr when inheriting a decorator class to a subclass.
     # Explicitly subclassing the Decorator makes sure representable_attrs is a clean version.
     def self.clone
-      Class.new(self) # DISCUSS: why isn't this called by Ruby?
+      Class.new(self)
     end
 
     include Representable # include after class methods so Decorator::prepare can't be overwritten by Representable::prepare.
+    include Cached
 
-    # TODO: implement that just by calling ::property(name, options){include mod} on the inheriting representer.
-    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
-
+    extend Uber::InheritableAttr
+    inheritable_attr :map
+    self.map = Binding::Map.new
 
     def initialize(represented)
       @represented = represented
     end
 
-  private
-    def self.build_inline(base, features, name, options, &block)
-      Class.new(base || default_inline_class) do
-        feature *features
-        class_eval &block
-      end
+    def self.nested_builder
+      ::Declarative::Schema::DSL::NestedBuilder
     end
   end
 end

data/lib/representable/definition.rb

@@ -1,27 +1,27 @@
-require 'uber/options'
+require "uber/options"
 require "representable/parse_strategies"
 
 module Representable
   # Created at class compile time. Keeps configuration options for one property.
-  class Definition
-    include Representable::Cloneable
-
-    attr_reader :name
-    alias_method :getter, :name
+  class Definition < ::Declarative::Definitions::Definition
 
     def initialize(sym, options={}, &block)
-      @options = Cloneable::Hash.new # allows deep cloning. we then had to set Pipeline cloneable.
-      @name    = sym.to_s
-      options  = options.clone
+      options[:extend] = options[:nested] if options[:nested]
+
+      super
 
       # defaults:
       options[:parse_filter]  = Pipeline[*options[:parse_filter]]
       options[:render_filter] = Pipeline[*options[:render_filter]]
-      options[:as]          ||= @name
 
       setup!(options, &block)
     end
 
+    def name
+      self[:name]
+    end
+    alias_method :getter, :name
+
     def merge!(options, &block)
       options = options.clone
 
@@ -39,13 +39,11 @@ module Representable
     end
 
     def [](name)
+      # return nil if name==:extend && self[:nested].nil?
+      # return Uber::Options::Value.new(self[:nested]) if name==:extend
       @runtime_options[name]
     end
 
-    def clone
-      self.class.new(name, @options.clone)
-    end
-
     def setter
       :"#{name}="
     end
@@ -91,6 +89,7 @@ module Representable
 
       # DISCUSS: we could call more macros here (e.g. for :nested).
       Representable::ParseStrategy.apply!(options)
+      Representable::Populator.apply!(options)
 
       yield options if block_given?
       @options.merge!(options)
@@ -110,7 +109,7 @@ module Representable
     end
 
     def dynamic_options
-      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :render_filter, :parse_filter, :skip_parse, :skip_render]
+      [:as, :getter, :setter, :class, :instance, :reader, :writer, :extend, :prepare, :if, :deserialize, :serialize, :skip_parse, :skip_render]
     end
 
     def handle_extend!(options)

data/lib/representable/deprecations.rb

@@ -0,0 +1,90 @@
+# WARNING: this will be removed in 3.0.
+module Representable::Binding::Deprecation
+  Options = Struct.new(:binding, :user_options, :represented, :decorator)
+
+  module EvaluateOption
+    def evaluate_option(name, input=nil, options={})
+      return evaluate_option_with_deprecation(name, input, options, :user_options) if name==:as
+      return evaluate_option_with_deprecation(name, input, options, :user_options) if name==:if
+      return evaluate_option_with_deprecation(name, input, options, :user_options) if name==:getter
+      return evaluate_option_with_deprecation(name, input, options, :doc, :user_options) if name==:writer
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:skip_render
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:skip_parse
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:serialize
+      return evaluate_option_with_deprecation(name, input, options, :doc, :user_options) if name==:reader
+      return evaluate_option_with_deprecation(name, input, options, :input, :index, :user_options) if name==:instance
+      return evaluate_option_with_deprecation(name, input, options, :input, :index, :user_options) if name==:class
+      return evaluate_option_with_deprecation(name, input, options, :input, :fragment, :user_options) if name==:deserialize
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:prepare
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:extend
+      return evaluate_option_with_deprecation(name, input, options, :input, :user_options) if name==:setter
+    end
+
+
+    def evaluate_option_with_deprecation(name, input, options, *positional_arguments)
+      unless proc = self[name]
+        return # FIXME: why do we need this?
+      end
+
+      options[:input] = input
+
+
+      __options = if self[:pass_options]
+        warn %{[Representable] The :pass_options option is deprecated. Please access environment objects via options[:binding].
+  Learn more here: http://trailblazerb.org/gems/representable/upgrading-guide.html#pass-options}
+        Options.new(self, options[:user_options], options[:represented], options[:decorator])
+      else
+        # user_options
+        options[:user_options]
+      end
+      # options[:user_options] = __options # TODO: always make this user_options in Representable 3.0.
+
+      if proc.send(:proc?) or proc.send(:method?)
+        arity = proc.instance_variable_get(:@value).arity if proc.send(:proc?)
+        arity = send(:exec_context, options).method(proc.instance_variable_get(:@value)).arity if proc.send(:method?)
+        if arity  != 1 or name==:getter or name==:if or name==:as
+          warn %{[Representable] Positional arguments for `:#{name}` are deprecated. Please use options or keyword arguments.
+  #{name}: ->(options) { options[:#{positional_arguments.join(" | :")}] } or
+  #{name}: ->(#{positional_arguments.join(":, ")}:) {  }
+  Learn more here: http://trailblazerb.org/gems/representable/upgrading-guide.html#positional-arguments
+  }
+          deprecated_args = []
+          positional_arguments.each do |arg|
+            next if arg == :index && options[:index].nil?
+            deprecated_args << __options  and next if arg == :user_options# either hash or Options object.
+            deprecated_args << options[arg]
+          end
+
+          return proc.(send(:exec_context, options), *deprecated_args)
+        end
+      end
+
+      proc.(send(:exec_context, options), options)
+    end
+    private :evaluate_option_with_deprecation
+
+
+    def represented
+      warn "[Representable] Binding#represented is deprecated. Use options[:represented] instead."
+      @represented
+    end
+
+    def compile_fragment(options)
+      @represented = options[:represented]
+      @parent_decorator = options[:decorator]
+      super
+    end
+
+    # Parse value from doc and update the model property.
+    def uncompile_fragment(options)
+      @represented = options[:represented]
+      @parent_decorator = options[:decorator]
+      super
+    end
+
+    def get(options={}) # DISCUSS: evluate if we really need this.
+      warn "[Representable] Binding#get is deprecated."
+      self[:getter] ? Representable::Getter.(nil, options.merge(binding: self)) : Representable::Get.(nil, options.merge(binding: self))
+    end
+  end
+end

data/lib/representable/deserializer.rb

@@ -1,115 +1,120 @@
 module Representable
-  # Deserializer's job is deserializing the already parsed fragment into a scalar or an object.
-  # This object is then returned to the Populator.
-  #
-  # It respects :deserialize, :prepare, :class, :instance
-  #
-  # Collection bindings return an array of parsed fragment items (still native format, e.g. Nokogiri node, for nested objects).
-  #
-  # Workflow
-  #   call -> instance/class -> prepare -> deserialize -> from_json.
-  class Deserializer
-    def initialize(binding)
-      @binding = binding
-    end
+  # we don't use keyword args, because i didn't want to discriminate 1.9 users, yet.
+  # this will soon get introduces and remove constructs like options[:binding][:default].
 
-    def call(fragment, *args) # FIXME: args is always i.
-      return fragment unless @binding.typed? # customize with :extend. this is not really straight-forward.
-      return fragment if fragment.nil?
+  # Deprecation strategy:
+  # binding.evaluate_option_with_deprecation(:reader, options, :doc)
+  #   => binding.evaluate_option(:reader, options) # always pass in options.
 
-      # what if create_object is responsible for providing the deserialize-to object?
-      object        = create_object(fragment, *args) # customize with :instance and :class.
-      representable = prepare(object) # customize with :prepare and :extend.
+  AssignFragment = ->(input, options) { options[:fragment] = input }
 
-      deserialize(representable, fragment, @binding.user_options) # deactivate-able via :representable => false.
-    end
+  ReadFragment = ->(input, options) { options[:binding].read(input, options[:as]) }
+  Reader = ->(input, options) { options[:binding].evaluate_option(:reader, input, options) }
 
-  private
-    def deserialize(object, fragment, options) # TODO: merge with #serialize.
-      return object unless @binding.representable?
+  StopOnNotFound = ->(input, options) do
+    Binding::FragmentNotFound == input ? Pipeline::Stop : input
+  end
 
-      @binding.evaluate_option(:deserialize, object, fragment) do
-        demarshal(object, fragment, options)
-      end
-    end
+  StopOnNil = ->(input, options) do # DISCUSS: Not tested/used, yet.
+    input.nil? ? Pipeline::Stop : input
+  end
 
-    def demarshal(object, fragment, options)
-      object.send(@binding.deserialize_method, fragment, options)
-    end
+  OverwriteOnNil = ->(input, options) do
+    input.nil? ? (Set.(input, options); Pipeline::Stop) : input
+  end
 
-    module Prepare
-      def prepare(object)
-        @binding.evaluate_option(:prepare, object) do
-          prepare!(object)
-        end
-      end
+  Default = ->(input, options) do
+    Binding::FragmentNotFound == input ? options[:binding][:default] : input
+  end
 
-      def prepare!(object)
-        mod = @binding.representer_module_for(object)
+  SkipParse = ->(input, options) do
+    options[:binding].evaluate_option(:skip_parse, input, options) ? Pipeline::Stop : input
+  end
+
+  Instance = ->(input, options) do
+    options[:binding].evaluate_option(:instance, input, options)
+  end
 
-        return object unless mod
+  module Function
+    class CreateObject
+      def call(input, options)
+        AssignFragment.(input, options)
 
-        prepare_for(mod, object)
+        instance_for(input, options) || class_for(input, options)
       end
 
-      def prepare_for(mod, object)
-        mod.prepare(object)
+    private
+      def class_for(input, options)
+        item_class = class_from(input, options) or raise DeserializeError.new(":class did not return class constant for `#{options[:binding].name}`.")
+        item_class.new
       end
-    end
-    include Prepare
 
-    def create_object(fragment, *args)
-      instance_for(fragment, *args) or class_for(fragment, *args)
-    end
+      def class_from(input, options)
+        options[:binding].evaluate_option(:class, input, options) # FIXME: no additional args passed here, yet.
+      end
 
-    def class_for(fragment, *args)
-      item_class = class_from(fragment, *args) or raise DeserializeError.new(":class did not return class constant.")
-      item_class.new
+      def instance_for(input, options)
+        Instance.(input, options)
+      end
     end
 
-    def class_from(fragment, *args)
-      @binding.evaluate_option(:class, fragment, *args)
+    class Prepare
+      def call(input, options)
+        binding = options[:binding]
+
+        binding.evaluate_option(:prepare, input, options)
+      end
     end
 
-    def instance_for(fragment, *args)
-      # cool: if no :instance set, { return } will jump out of this method.
-      @binding.evaluate_option(:instance, fragment, *args) { return } or raise DeserializeError.new(":instance did not return object.")
+    class Decorate
+      def call(object, options)
+        binding = options[:binding]
+
+        return object unless object # object might be nil.
+
+        mod = binding.evaluate_option(:extend, object, options)
+
+        prepare_for(mod, object, binding)
+      end
+
+      def prepare_for(mod, object, binding)
+        mod.prepare(object)
+      end
     end
+  end
 
+  CreateObject = Function::CreateObject.new
+  Prepare      = Function::Prepare.new
+  Decorate     = Function::Decorate.new
+  Deserializer =  ->(input, options) { options[:binding].evaluate_option(:deserialize, input, options) }
 
+  Deserialize  =  ->(input, options) do
+    binding, fragment, user_options = options[:binding], options[:fragment], options[:user_options]
 
-    # Collection does exactly the same as Deserializer but for a collection.
-    class Collection < self
-      def call(fragment)
-        collection = [] # this can be replaced, e.g. AR::Collection or whatever.
+    user_options = user_options.merge(wrap: binding[:wrap]) unless binding[:wrap].nil? # DISCUSS: can we leave that here?
+    input.send(binding.deserialize_method, fragment, user_options)
+  end
 
-        fragment.each_with_index do |item_fragment, i|
-          # add more per-item options here!
-          next if @binding.evaluate_option(:skip_parse, item_fragment) # TODO: pass in index!
+  ParseFilter = ->(input, options) do
+    options[:binding][:parse_filter].(input, options)
+  end
 
-          collection << deserialize!(item_fragment, i) # FIXME: what if obj nil?
-        end
+  Setter = ->(input, options) { options[:binding].evaluate_option(:setter, input, options) }
+  Set = ->(input, options) { options[:binding].send(:exec_context, options).send(options[:binding].setter, input) }
 
-        collection # with parse_strategy: :sync, this is ignored.
-      end
 
-    private
-      def deserialize!(*args)
-        item_deserializer.call(*args)
-      end
+  Stop = ->(*) { Pipeline::Stop }
 
-      def item_deserializer
-        @item_deserializer = Deserializer.new(@binding)
-      end
-    end
+  If = ->(input, options) { options[:binding].evaluate_option(:if, nil, options) ? input : Pipeline::Stop }
 
+  StopOnExcluded = ->(input, options) do
+    return input unless private = options[:_private]
+    return input unless props = (private[:exclude] || private[:include])
 
-    class Hash < Collection
-      def call(hash)
-        {}.tap do |hsh|
-          hash.each { |key, fragment| hsh[key] = deserialize!(fragment) }
-        end
-      end
-    end
+    res = props.include?(options[:binding].name.to_sym) # false with include: Stop. false with exclude: go!
+
+    return input if private[:include]&&res
+    return input if private[:exclude]&&!res
+    Pipeline::Stop
   end
 end

data/lib/representable/for_collection.rb

@@ -13,9 +13,11 @@ module Representable
 
       # what happens here is basically
       # Module.new { include Representable::JSON::Collection; ... }
-      build_inline(nil, [singular.collection_representer_class], "", {}) {
-        items options.merge(:extend => singular)
-      }
+      nested_builder.(
+        _base:     default_nested_class,
+        _features: [singular.collection_representer_class],
+        _block:    ->(*) { items options.merge(:extend => singular) }
+      )
     end
 
     def collection_representer(options={})