representable 2.4.0.rc3 → 2.4.0.rc4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f9cc279171577dec367b7910ae42b4d4f8b6240
-  data.tar.gz: 193116e06652a35c3fa5bd5124a401d51c8d5c7e
+  metadata.gz: 37e722a1246b50c21ee87fe22a3a712bc03c3ea0
+  data.tar.gz: 4c7cdfbdeb505aaff4f6295ef2b3c717cf4667e4
 SHA512:
-  metadata.gz: 14296a6fb55202f2c747cbe0a77e97a3bef8f82673eae9467cd290243dd0ed438f3ffe5fbbf7ec53728818b91459774f18e7141117d9788bd497218ad4899325
-  data.tar.gz: 35a26662c16e844cb9944cdf06cb9a5014c266f53568e714d0f37e49922076cc200e1126fb554dc13a2a0115a97479ea5ddce300bf3d6663148f9adf9ef108c8
+  metadata.gz: c64248b241a38e218d0078116f3fbd3ba79591ca6d9cbed24c80eaa0903c0b017aa5cd18dd1a7bc70f76ee26bf7a2b29b2b6b4c764579762be6a10181555f99a
+  data.tar.gz: a3a01d1dcd3ca21b5a2796eb4ad49f708b4d21d9710c160e176465710c45544b2894512322420e295c4dd6a70c8321d9d71814f8a8d448b977912fc99f17c895

data/CHANGES.md

@@ -44,13 +44,18 @@ and it suddenly is super simple to understand
 * Removed `Binding@represented` (which was never public anyway). Use `Binding#represented`.
 * Changed signature: `Binding#get(represented:)`. In now needs a hash `{represented: ..}`.
 
+# 2.4.0.rc4
+
+* The preferred way of passing user options is now `to_hash(user_options: {})`.
+* Supports nested options for nested representers.
+
 # 2.4.0.rc3
 
+* `Set` is `SetValue`. `Get` is `GetValue`.
 * `CreateObject` no longer invokes `AssignFragment`. This is now part of the official parse pipeline.
 
-# 2.4.0.rc4
+# 2.4.0.rc2
 
-* `Set` is `SetValue`. `Get` is `GetValue`.
 * Use Declarative's `::build_definition` interface instead of overwriting `::property`.
 
 # 2.3.0

data/Rakefile

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

data/lib/representable.rb

@@ -39,7 +39,7 @@ private
 
   # Compiles the document going through all properties.
   def create_representation_with(doc, options, format)
-    propagated_options = normalize_options(options) # {_private: {include: }, is_admin: true}
+    propagated_options = normalize_options(options)
 
     representable_map!(doc, propagated_options, format, :compile_fragment)
     doc
@@ -63,8 +63,8 @@ private
     Binding::Map.new(representable_bindings_for(format, options))
   end
 
-  def representable_map!(doc, propagated_options, format, method)
-    options = {doc: doc, _private: propagated_options[:_private], user_options: propagated_options, represented: represented, decorator: self}
+  def representable_map!(doc, options, format, method)
+    options = {doc: doc, options: options, represented: represented, decorator: self}
 
     representable_map(options, format).(method, options) # .(:uncompile_fragment, options)
   end
@@ -73,23 +73,24 @@ private
     representable_attrs.collect {|definition| format.build(definition) }
   end
 
-  # Make sure we do not change original options. However, private options like :include or :wrap are
-  # not passed on to child representers.
-  def normalize_options(options)
-    # here, we could also filter out local options e.g. like options[:band].
-    return options unless options.any?
-
-    propagated_options = options.dup
-    propagated_options.delete(:wrap) # FIXME.
-    propagated_options.delete(:_private)
+  module NormalizeOptions
+    def normalize_options(options)
+      return options if options.any?
+      {user_options: {}}.merge(options) # TODO: use keyword args once we drop 2.0.
+    end
+  end
 
-    private_options = {}
-    private_options[:include] = propagated_options.delete(:include) if options[:include]
-    private_options[:exclude] = propagated_options.delete(:exclude) if options[:exclude]
+  # Prepares options for a particular nested representer.
+  # This is used in Serializer and Deserializer.
+  OptionsForNested = ->(options, binding) do
+    child_options = {user_options: options[:user_options], }
 
-    propagated_options[:_private] = private_options if private_options.any?
+    # wrap:
+    child_options[:wrap] = binding[:wrap] unless binding[:wrap].nil?
 
-    propagated_options
+    # nested params:
+    child_options.merge!(options[binding.name.to_sym]) if options[binding.name.to_sym]
+    child_options
   end
 
   def representable_attrs
@@ -123,6 +124,9 @@ private
   def self.deprecations=(value)
     evaluator = value==false ? Binding::EvaluateOption : Binding::Deprecation::EvaluateOption
     ::Representable::Binding.send :include, evaluator
+
+    evaluator = value==false ? NormalizeOptions : Deprecation::NormalizeOptions
+    ::Representable.send :include, evaluator
   end
   self.deprecations = true # TODO: change to false in 2.5 or remove entirely.
 end

data/lib/representable/binding.rb

@@ -41,9 +41,10 @@ module Representable
     include Deprecatable
 
     module EvaluateOption
-      def evaluate_option(name, input=nil, options={})
+      def evaluate_option(name, input, options)
         proc = self[name]
-        proc.(send(:exec_context, options), options) # from Uber::Options::Value. # NOTE: this can also be the Proc object if it's not wrapped by Uber:::Value.
+        # puts "@@@@@ #{self.inspect}, #{name}...... #{self[name]}"
+        proc.(send(:exec_context, options), options.merge(user_options: options[:options][:user_options], input: input)) # from Uber::Options::Value. # NOTE: this can also be the Proc object if it's not wrapped by Uber:::Value.
       end
     end
     # include EvaluateOption

data/lib/representable/definition.rb

@@ -48,7 +48,7 @@ module Representable
       :"#{name}="
     end
 
-    def typed?
+    def typed? # TODO: remove.
       self[:class] or self[:extend] or self[:instance]
     end
 

data/lib/representable/deprecations.rb

@@ -1,4 +1,29 @@
 # WARNING: this will be removed in 3.0.
+module Representable::Deprecation
+  module NormalizeOptions
+    def normalize_options(options)
+
+      unless options.any?
+        options[:user_options] = {}
+        return options
+      end
+
+      options      = options.dup
+
+      user_option_keys = options.keys - [:exclude, :include, :wrap, :user_options, * representable_attrs.keys.map(&:to_sym)]
+      if user_option_keys.any?
+        user_options = {}
+        warn "[Representable] Mixing user and representable options is deprecated. Please provide your options via :user_options."
+        user_option_keys.each { |key| user_options[key] = options.delete(key) }
+
+        options[:user_options] = user_options
+      end
+
+      options # {user_options: {..}, include: [], wrap: "song", artist: {..}}
+    end
+  end
+end
+
 module Representable::Binding::Deprecation
   Options = Struct.new(:binding, :user_options, :represented, :decorator)
 
@@ -32,12 +57,14 @@ module Representable::Binding::Deprecation
       __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])
+
+
+        options[:options] ||= {}
+        Options.new(self, options[:options][:user_options], options[:represented], options[:decorator])
       else
         # user_options
-        options[:user_options]
+        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?)
@@ -54,12 +81,11 @@ module Representable::Binding::Deprecation
             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)
+      proc.(send(:exec_context, options), options.merge(user_options: options[:options][:user_options]))
     end
     private :evaluate_option_with_deprecation
 

data/lib/representable/deserializer.rb

@@ -31,31 +31,7 @@ module Representable
     options[:binding].evaluate_option(:skip_parse, input, options) ? Pipeline::Stop : input
   end
 
-  Instance = ->(input, options) do
-    options[:binding].evaluate_option(:instance, input, options)
-  end
-
   module Function
-    class CreateObject
-      def call(input, options)
-        instance_for(input, options) || class_for(input, options)
-      end
-
-    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
-
-      def class_from(input, options)
-        options[:binding].evaluate_option(:class, input, options) # FIXME: no additional args passed here, yet.
-      end
-
-      def instance_for(input, options)
-        Instance.(input, options)
-      end
-    end
-
     class Prepare
       def call(input, options)
         binding = options[:binding]
@@ -81,16 +57,30 @@ module Representable
     end
   end
 
-  CreateObject = Function::CreateObject.new
+  module CreateObject
+    Instance = ->(input, options) { options[:binding].evaluate_option(:instance, input, options)||
+        raise( DeserializeError.new(":instance did not return class constant for `#{options[:binding].name}`.")) }
+    Class    = ->(input, options) do
+      object_class = options[:binding].evaluate_option(:class, input, options) ||
+        raise( DeserializeError.new(":class did not return class constant for `#{options[:binding].name}`."))
+      object_class.new
+    end # FIXME: no additional args passed here, yet.
+
+    Populator = ->(*) { raise "Populator: implement me!" }
+  end
+
+  # CreateObject = Function::CreateObject.new
   Prepare      = Function::Prepare.new
   Decorate     = Function::Decorate.new
-  Deserializer =  ->(input, options) { options[:binding].evaluate_option(:deserialize, input, options) }
+  Deserializer = ->(input, options) { options[:binding].evaluate_option(:deserialize, input, options) }
+
+  Deserialize  =  ->(input, args) do
+    binding, fragment, options = args[:binding], args[:fragment], args[:options]
 
-  Deserialize  =  ->(input, options) do
-    binding, fragment, user_options = options[:binding], options[:fragment], options[:user_options]
+    # user_options:
+    child_options = OptionsForNested.(options, args[:binding])
 
-    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)
+    input.send(binding.deserialize_method, fragment, child_options)
   end
 
   ParseFilter = ->(input, options) do
@@ -106,13 +96,13 @@ module Representable
   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])
+    return input unless private = options[:options]
+    return input unless props = (options[:options][:exclude] || options[:options][:include])
 
     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
+    return input if options[:options][:include]&&res
+    return input if options[:options][:exclude]&&!res
     Pipeline::Stop
   end
 end

data/lib/representable/hash/collection.rb

@@ -17,19 +17,26 @@ module Representable::Hash
       end
     end
 
+    # TODO: revise lonely collection and build separate pipeline where we just use Serialize, etc.
 
     def create_representation_with(doc, options, format)
+      options = normalize_options(options)
+      options[:_self] = options
+
       bin   = representable_bindings_for(format, options).first
 
       Collect[*bin.default_render_fragment_functions].
-        (represented, {doc: doc, fragment: represented, user_options: options, binding: bin, represented: represented})
+        (represented, {doc: doc, fragment: represented, options: options, binding: bin, represented: represented})
     end
 
     def update_properties_from(doc, options, format)
+      options = normalize_options(options)
+      options[:_self] = options
+
       bin   = representable_bindings_for(format, options).first
 
       value = Collect[*bin.default_parse_fragment_functions].
-        (doc, fragment: doc, document: doc, user_options: options, binding: bin, represented: represented)
+        (doc, fragment: doc, document: doc, options: options, binding: bin, represented: represented)
 
       represented.replace(value)
     end

data/lib/representable/hash_methods.rb

@@ -4,14 +4,14 @@ module Representable
       hash  = filter_keys_for!(represented, options) # FIXME: this modifies options and replicates logic from Representable.
       bin   = representable_map(options, format).first
 
-      Collect::Hash[*bin.default_render_fragment_functions].(hash, {doc: doc, user_options: options, binding: bin, represented: represented, decorator: self})
+      Collect::Hash[*bin.default_render_fragment_functions].(hash, {doc: doc, options: options, binding: bin, represented: represented, decorator: self})
     end
 
     def update_properties_from(doc, options, format)
       hash  = filter_keys_for!(doc, options)
       bin   = representable_map(options, format).first
 
-      value = Collect::Hash[*bin.default_parse_fragment_functions].(hash, fragment: hash, document: doc, binding: bin, represented: represented, user_options: options, decorator: self)
+      value = Collect::Hash[*bin.default_parse_fragment_functions].(hash, fragment: hash, document: doc, binding: bin, represented: represented, options: options, decorator: self)
 
       represented.replace(value)
     end

data/lib/representable/parse_strategies.rb

@@ -24,7 +24,7 @@ module Representable
       options[:parse_pipeline] = ->(input, options) do
         pipeline = Pipeline[*parse_functions] # TODO: AssignFragment
         pipeline = Pipeline::Insert.(pipeline, SetValue, delete: true) # remove the setter function.
-        pipeline = Pipeline::Insert.(pipeline, populator, replace: CreateObject) # let the populator do CreateObject's job.
+        pipeline = Pipeline::Insert.(pipeline, populator, replace: CreateObject::Populator) # let the actual populator do the job.
         # puts pipeline.extend(Representable::Pipeline::Debug).inspect
         pipeline
       end
@@ -72,8 +72,8 @@ module Representable
         options[:setter]       = lambda { |*args| }
         options[:pass_options] = true
         options[:instance]     = options[:collection] ?
-          lambda { |fragment, i, options| options.binding.get(represented: options.represented)[i] } :
-          lambda { |fragment, options|    options.binding.get(represented: options.represented) }
+          lambda { |options| options[:binding].get(options)[options[:index]] } :
+          lambda { |options| options[:binding].get(options) }
       end
     end
 
@@ -82,11 +82,10 @@ module Representable
     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)
+        options[:instance]     = lambda { |options|
+          object_class = options[:binding][:class].evaluate(self, options)
 
-          object_class.find_by({id: fragment["id"]}) or object_class.new
+          object_class.find_by({id: options[:fragment]["id"]}) or object_class.new
         }
       end
     end

data/lib/representable/pipeline.rb

@@ -19,7 +19,18 @@ module Representable
     def evaluate(block, input, options)
       block.call(input, options)
     end
-  end
+
+
+    module Insert # TODO: explicit test.
+      # Macro to quickly modify an array of functions via Pipeline::Insert and return a
+      # Pipeline instance.
+      def insert(functions, new_function, options)
+        Pipeline.new(Insert.(functions, new_function, options))
+
+      end
+    end
+    extend Insert
+  end # Pipeline
 
 
   # Collect applies a pipeline to each element of input.

data/lib/representable/pipeline_factories.rb

@@ -67,8 +67,15 @@ module Representable
       functions = [AssignFragment]
       functions << SkipParse if self[:skip_parse]
 
-      if typed?
-        functions << CreateObject
+      if self[:class] or self[:extend] or self[:instance] or self[:populator]
+        if self[:populator]
+          functions << CreateObject::Populator
+        elsif self[:parse_strategy]
+          functions << CreateObject::Instance # TODO: remove in 2.5.
+        else
+          functions << (self[:class] ? CreateObject::Class : CreateObject::Instance)
+        end
+
         functions << Prepare     if self[:prepare]
         functions << Decorate    if self[:extend]
         if representable?

data/lib/representable/serializer.rb

@@ -37,11 +37,11 @@ module Representable
 
   Serialize = ->(input, options) do
     return if input.nil? # DISCUSS: how can we prevent that?
-    binding, user_options = options[:binding], options[:user_options]
+    binding, options = options[:binding], options[:options] # FIXME: rename to :local_options.
 
-    user_options = user_options.merge(wrap: binding[:wrap]) unless binding[:wrap].nil? # DISCUSS: can we leave that here?
+    options_for_nested = OptionsForNested.(options, binding)
 
-    input.send(binding.serialize_method, user_options)
+    input.send(binding.serialize_method, options_for_nested)
   end
 
   WriteFragment = ->(input, options) { options[:binding].write(options[:doc], input, options[:as]) }

data/lib/representable/version.rb

@@ -1,3 +1,3 @@
 module Representable
-  VERSION = "2.4.0.rc3"
+  VERSION = "2.4.0.rc4"
 end

data/test-with-deprecations/as_test.rb

@@ -0,0 +1,65 @@
+require 'test_helper'
+
+class AsTest < MiniTest::Spec
+  for_formats(
+    :hash => [Representable::Hash, {"title" => "Wie Es Geht"}, {"title" => "Revolution"}],
+    # :xml  => [Representable::XML, "<open_struct>\n  <song>\n    <name>Alive</name>\n  </song>\n</open_struct>", "<open_struct><song><name>You've Taken Everything</name></song>/open_struct>"],
+    # :yaml => [Representable::YAML, "---\nsong:\n  name: Alive\n", "---\nsong:\n  name: You've Taken Everything\n"],
+  ) do |format, mod, input, output|
+
+    let (:song) { representer.prepare(Song.new("Revolution")) }
+    let (:format) { format }
+
+
+    describe "as: with :symbol" do
+      representer!(:module => mod) do
+        property :name, :as => :title
+      end
+
+      it { render(song).must_equal_document output }
+      it { parse(song, input).name.must_equal "Wie Es Geht" }
+    end
+
+
+    describe "as: with lambda" do
+      representer!(:module => mod) do
+        property :name, :as => lambda { |*| "#{self.class}" }
+      end
+
+      it { render(song).must_equal_document({"Song" => "Revolution"}) }
+      it { parse(song, {"Song" => "Wie Es Geht"}).name.must_equal "Wie Es Geht" }
+    end
+
+
+    describe "lambda arguments" do
+      representer! do
+        property :name, :as => lambda { |*args| args.inspect }
+      end
+
+      it { render(song, :volume => 1).must_equal_document({"[{:volume=>1}]" => "Revolution"}) }
+      it { parse(song, {"[{:volume=>1}]" => "Wie Es Geht"}, :volume => 1).name.must_equal "Wie Es Geht" }
+    end
+  end
+end
+
+
+# hash: to_hash(wrap: ) is representation_wrap
+
+class AsXmlTest < MiniTest::Spec
+  Band  = Struct.new(:name, :label)
+  Album = Struct.new(:band)
+  Label = Struct.new(:name)
+
+  representer!(module: Representable::XML, decorator: true) do
+    self.representation_wrap = :album
+    property :band, as: :combo do
+      self.representation_wrap = :band
+      property :name
+    end
+  end
+
+  it do
+    skip
+    representer.new(Album.new(Band.new("Offspring"))).to_xml.must_equal ""
+  end
+end