representable 2.3.0 → 2.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 304ec8f66cc93beff15aba84d2d4b5d5214fa5d1
-  data.tar.gz: 83a928ef451bd032509abb6c41d8ababda744a97
+  metadata.gz: a7d63369f6aa46d6611bd4f968a61ed24e91c1eb
+  data.tar.gz: f6708f841e1ada1e9e17cfd5a7c6bb43300d05d1
 SHA512:
-  metadata.gz: 5eb021bc55145ff44e467db742d2842c8971413b44f084df9046f9eb6ee66e5250fa523fae0f8d0f3f0f3938c2e38339ca08876bcd04f6fb291ab8fb4368b0b7
-  data.tar.gz: fc426cbb854f6aef32a99b5bdec3e0f364176cf9ece0d35f19c43200434db12a2d8f545430f139cc8f452baf3598183ba8bd1ab53b6ce6d944512a5ac31c1fa5
+  metadata.gz: 9acd1431d96131b220f03bd15296c94a77fc362959a46daa0b41847cc6ef2d375295e546664e3f4e911ae3118447497cf260b8cdd301f2e1662c916b940e152c
+  data.tar.gz: c45744211c992ab797ea4f6d0488930414b4587e3be8db98ae74973d135557b7f1108a913e440f8e1e8808957240b89cf0dff60b4ee463c8de86773820af3fad

data/CHANGES.md

@@ -1,3 +1,50 @@
+# 2.4.0
+
+* Breaking API change: `:parse_filter` and `:render_filter` have no deprecation as all the other, they receive one options.
+render_filter: val, doc, options
+* `Decorator` always needs a format engine included, e.g. `Representable::JSON` to build bindings at compile-time.
+* Removed `Representable::Apply`. This is now done via `Schema`.
+representer_class.representable_attrs is definitions
+* Removed `:use_decorator` option. Use a decorator instead.
+
+TODO: DEPRECATE 4-args? also, allow options[:fragment] instead of options[:result] ?
+
+
+TODO: :representable should be removing Deserialize.
+       deprecate Coercion, it sucks
+       deprecate parse/render filter
+
+pipeline
+less ifs, instead: simply remove the "middleware"
+read_fragment
+  represented.set instance.prepare.from_json
+Populator.(fragment)
+  not_found?.default.deserialize.parse_filter.set
+Deserializer.(fragment)
+   instance.class.prepare.deserialize=from_json
+
+OverwriteOnNil vs. StopOnNil
+[Instance, ->(){..}, Bla]
+
+did you ever overwrite #create_object in a binding? you can now simply pass a callable object into the pipeline.
+TODO: deprecate parse strategies in favour of :populator (analogue to Reform)
+
+elegant, easier to understand, and extend
+you know, the whole deserialize stack (same for rendering): you pass in the json, it finds the fragments for each property, passes it to  the binding, the binding deserializes, builds/finds a model, assigns values to it, and so on
+you can partially hook in with :instance or :deserialize or :parse_filter, but it's really awkward. i am now changing the architecture to a pipeline, where you plug in the features you want (e.g. "do not call :prepare, :instance, :class, etc. but run my own :populator")
+and it suddenly is super simple to understand
+
+* Added `Representable.deprecations = false` to disable slow and weird deprecation code.
+
+* Removed `Binding#user_options`. This is now available via `->(options[:user_options])`.
+* Removed `Binding#as`.
+* Removed `Binding#parent_decorator`.
+
+## Internal Changes
+* Removed `Binding@represented` (which was never public anyway). Use `Binding#represented`.
+* Changed signature: `Binding#get(represented:)`. In now needs a hash `{represented: ..}`.
+
+
 # 2.3.0
 
 * Remove dependency to Nokogiri and Multi_JSON. You have to add what you need to your `Gemfile`/`gemspec` now.

data/Gemfile

@@ -11,4 +11,9 @@ end
 group :test do
   gem "nokogiri", require: false
   gem "multi_json", require: false
+  gem "minitest-line"
+  gem "pry"
 end
+
+# gem "declarative", path: "../declarative"
+# gem "declarative", github: "apotonick/declarative"

data/README.md

@@ -2,6 +2,11 @@
 
 Representable maps Ruby objects to documents and back.
 
+[![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+[![Build
+Status](https://travis-ci.org/apotonick/representable.svg)](https://travis-ci.org/apotonick/representable)
+[![Gem Version](https://badge.fury.io/rb/representable.svg)](http://badge.fury.io/rb/representable)
+
 In other words: Take an object and decorate it with a representer module. This will allow you to render a JSON, XML or YAML document from that object. But that's only half of it! You can also use representers to parse a document and create or populate an object.
 
 Representable is helpful for all kind of mappings, rendering and parsing workflows. However, it is mostly useful in API code. Are you planning to write a real REST API with representable? Then check out the [Roar](http://github.com/apotonick/roar) gem first, save work and time and make the world a better place instead.
@@ -1362,6 +1367,34 @@ end
 
 This is an implementation detail most people shouldn't worry about.
 
+
+### Defaults
+
+Declaring default options for `property`, `nested`, `collection` and `hash` is
+easy as:
+
+```ruby
+defaults render_nil: true
+```
+
+You can also pass a block for dynamic default options based on the property
+name or on the property options.
+
+```ruby
+defaults render_nil: true do |name|
+  { as: name.to_s.camelize }
+end
+```
+
+```ruby
+defaults render_nil: true do |name, options|
+  {
+    as: name.to_s.camelize,
+    embedded: options.fetch(:hash, false)
+  }
+end
+```
+
 ## Symbol Keys vs. String Keys
 
 When parsing representable reads properties from hashes by using their string keys.

data/lib/representable.rb

@@ -1,21 +1,18 @@
-require 'forwardable'
-
-require 'representable/inheritable'
-require 'representable/config'
-require 'representable/definition'
-require 'representable/mapper'
-require 'representable/for_collection'
-require 'representable/represent'
-require 'representable/declarative'
-require 'representable/apply'
-require "representable/populator"
-require "representable/deserializer"
-require "representable/serializer"
-require "representable/cached"
+require "uber/delegates"
 
+require "declarative/schema"
 
-require "uber/callable"
+require "representable/config"
+require "representable/definition"
+require "representable/declarative"
+require "representable/deserializer"
+require "representable/serializer"
+require "representable/binding"
 require "representable/pipeline"
+require "representable/insert" # Pipeline::Insert
+require "representable/cached"
+require "representable/for_collection"
+require "representable/represent"
 
 module Representable
   attr_writer :representable_attrs
@@ -23,86 +20,90 @@ module Representable
   def self.included(base)
     base.class_eval do
       extend Declarative
-      extend ClassInclusions, ModuleExtensions
+      # make Representable horizontally and vertically inheritable.
+      extend ModuleExtensions, ::Declarative::Heritage::Inherited, ::Declarative::Heritage::Included
       extend ClassMethods
-      extend Feature
       extend ForCollection
       extend Represent
-      extend Apply
-      # register_feature Representable # Representable gets included automatically when creating inline representer.
     end
   end
 
 private
   # Reads values from +doc+ and sets properties accordingly.
   def update_properties_from(doc, options, format)
-    propagated_options, private_options = normalize_options!(options)
+    propagated_options = normalize_options(options)
 
-    representable_mapper(format, propagated_options).deserialize(represented, doc, propagated_options, private_options)
+    representable_map!(doc, propagated_options, format, :uncompile_fragment)
+    represented
   end
 
   # Compiles the document going through all properties.
   def create_representation_with(doc, options, format)
-    propagated_options, private_options = normalize_options!(options)
+    propagated_options = normalize_options(options) # {_private: {include: }, is_admin: true}
 
-    representable_mapper(format, propagated_options).serialize(represented, doc, propagated_options, private_options)
+    representable_map!(doc, propagated_options, format, :compile_fragment)
+    doc
   end
 
-  def representable_bindings_for(format, options)
-    representable_attrs.collect {|definition| representable_binding_for(definition, format, options) }
+  class Binding::Map < Array
+    def call(method, options)
+      each do |bin|
+        options[:binding] = bin # this is so much faster than options.merge().
+        bin.send(method, options)
+      end
+    end
+
+     # TODO: Merge with Definitions.
+    def <<(binding) # can be slow. this is compile time code.
+      (existing = find { |bin| bin.name == binding.name }) ? self[index(existing)] = binding : super(binding)
+    end
+  end
+
+  def representable_map(options, format)
+    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}
+
+    representable_map(options, format).(method, options) # .(:uncompile_fragment, options)
   end
 
-  def representable_binding_for(definition, format, options)
-    format.build(definition, self)
+  def representable_bindings_for(format, options)
+    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)
+  def normalize_options(options)
     # here, we could also filter out local options e.g. like options[:band].
-    private_options = {}
-    return [options, private_options] if options.size == 0
+    return options unless options.any?
 
     propagated_options = options.dup
+    propagated_options.delete(:wrap) # FIXME.
+    propagated_options.delete(:_private)
 
+    private_options = {}
     private_options[:include] = propagated_options.delete(:include) if options[:include]
     private_options[:exclude] = propagated_options.delete(:exclude) if options[:exclude]
-    propagated_options.delete(:wrap) # FIXME.
 
-    [propagated_options, private_options]
-  end
+    propagated_options[:_private] = private_options if private_options.any?
 
-  def representable_attrs
-    @representable_attrs ||= self.class.representable_attrs # DISCUSS: copy, or better not? what about "freezing"?
+    propagated_options
   end
 
-  def representable_mapper(format, options)
-    bindings = representable_bindings_for(format, options)
-    Mapper.new(bindings)
+  def representable_attrs
+    @representable_attrs ||= self.class.definitions
   end
 
   def representation_wrap(*args)
-    representable_attrs.wrap_for(nil, represented, *args) { self.class.name }
+    representable_attrs.wrap_for(represented, *args)
   end
 
   def represented
     self
   end
 
-  module ClassInclusions
-    def included(base)
-      super
-      base.inherit_module!(self)
-    end
-
-    def inherited(subclass) # DISCUSS: this could be in Decorator? but then we couldn't do B < A(include X) for non-decorators, right?
-      super
-      # FIXME: subclass.representable_attrs is ALWAYS empty at this point.
-      subclass.representable_attrs.inherit!(representable_attrs) # this should be inherit_class!
-      # DISCUSS: this could also just be: subclass.inheritable_attr :representable_attrs --> superclass.representable_attrs.clone
-    end
-  end
-
   module ModuleExtensions
     # Copies the representable_attrs reference to the extended object.
     # Note that changing attrs in the instance will affect the class configuration.
@@ -112,32 +113,18 @@ private
     end
   end
 
-
   module ClassMethods
-    # Gets overridden by Decorator as inheriting representers via include in Decorator means a bit more work (manifesting).
-    def inherit_module!(parent)
-      representable_attrs.inherit!(parent.representable_attrs) # Module just inherits.
-    end
-
     def prepare(represented)
       represented.extend(self)
     end
   end
 
-
-  module Feature
-    def feature(*mods)
-      mods.each do |mod|
-        include mod
-        register_feature(mod)
-      end
-    end
-
-  private
-    def register_feature(mod)
-      representable_attrs[:features][mod] = true
-    end
+  require "representable/deprecations"
+  def self.deprecations=(value)
+    evaluator = value==false ? Binding::EvaluateOption : Binding::Deprecation::EvaluateOption
+    ::Representable::Binding.send :include, evaluator
   end
+  self.deprecations = true # TODO: change to false in 2.5 or remove entirely.
 end
 
-require 'representable/autoload'
+require 'representable/autoload'

data/lib/representable/binding.rb

@@ -1,143 +1,57 @@
 module Representable
-  # The Binding wraps the Definition instance for this property and provides methods to read/write fragments.
-
-  # The flow when parsing is Binding#read_fragment -> Populator -> Deserializer.
-  # Actual parsing the fragment from the document happens in Binding#read, everything after that is generic.
+  # The Binding provides methods to read/write the fragment for one property.
   #
-  # Serialization: Serializer -> {frag}/[frag]/frag -> Binding#write
+  # Actually parsing the fragment from the document happens in Binding#read, everything after that is generic.
   class Binding
     class FragmentNotFound
     end
 
-    def self.build(definition, *args)
-      # DISCUSS: move #create_binding to this class?
-      return definition.create_binding(*args) if definition[:binding]
-      build_for(definition, *args)
+    def self.build(definition)
+      return definition.create_binding if definition[:binding]
+      build_for(definition)
     end
 
-    def initialize(definition, parent_decorator)
+    def initialize(definition)
       @definition       = definition
-      @parent_decorator = parent_decorator # DISCUSS: where's this needed?
-
-      # static options. do this once.
-      @representable    = @definition.representable?
       @name             = @definition.name
-      @skip_filters     = self[:readable]==false || self[:writeable]==false || self[:if] # Does this binding contain :if, :readable or :writeable settings?
       @getter           = @definition.getter
       @setter           = @definition.setter
-      @array            = @definition.array?
-      @typed            = @definition.typed?
-      @has_default      = @definition.has_default?
-    end
-
-    attr_reader :user_options, :represented # TODO: make private/remove.
-
-    # DISCUSS: an overall strategy to speed up option reads will come around 3.0.
-    attr_reader :representable, :name, :getter, :setter, :array, :typed, :skip_filters, :has_default
-    alias_method :representable?, :representable
-    alias_method :array?, :array
-    alias_method :typed?, :typed
-    alias_method :skip_filters?, :skip_filters
-    alias_method :has_default?, :has_default
 
-    def as # DISCUSS: private?
-      @as ||= evaluate_option(:as)
+      setup_exec_context!
     end
 
+    attr_reader :name, :getter, :setter
+    extend Uber::Delegates
+    delegates :@definition, :has_default?, :representable?, :array?, :typed?
+
     # Single entry points for rendering and parsing a property are #compile_fragment
     # and #uncompile_fragment in Mapper.
-    #
-    # DISCUSS:
-    # currently, we need to call B#update! before compile_fragment/uncompile_fragment.
-    # this will change to B#renderer(represented, options).call
-    #                     B#parser  (represented, options).call
-    # goal is to have two objects for 2 entirely different tasks.
 
-    # Retrieve value and write fragment to the doc.
-    def compile_fragment(doc)
-      evaluate_option(:writer, doc) do
-        value = render_filter(get, doc)
-        write_fragment(doc, value)
+    module Deprecatable
+      # Retrieve value and write fragment to the doc.
+      def compile_fragment(options)
+        render_pipeline(nil, options).(nil, options)
       end
-    end
 
-    # Parse value from doc and update the model property.
-    def uncompile_fragment(doc)
-      evaluate_option(:reader, doc) do
-        read_fragment(doc)
+      # Parse value from doc and update the model property.
+      def uncompile_fragment(options)
+        parse_pipeline(options[:doc], options).(options[:doc], options)
       end
     end
+    include Deprecatable
 
-    def write_fragment(doc, value)
-      value = default_for(value)
-
-      return if skipable_empty_value?(value)
-
-      render_fragment(value, doc)
-    end
-
-    def render_fragment(value, doc)
-      fragment = serialize(value) { return } # render fragments of hash, xml, yaml.
-
-      write(doc, fragment)
-    end
-
-    def read_fragment(doc)
-      fragment = read(doc) # scalar, Array, or Hash (abstract format) or un-deserialised fragment(s).
-
-      populator.call(fragment, doc)
-    end
-
-    def render_filter(value, doc)
-      evaluate_option(:render_filter, value, doc) { value }
-    end
-
-    def parse_filter(value, doc)
-      evaluate_option(:parse_filter, value, doc) { value }
-    end
-
-    def get
-      evaluate_option(:getter) do
-        exec_context.send(getter)
+    module EvaluateOption
+      def evaluate_option(name, input=nil, 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.
       end
     end
-
-    def set(value)
-      evaluate_option(:setter, value) do
-        exec_context.send(setter, value)
-      end
-    end
-
-    # DISCUSS: do we really need that?
-    #   1.38      0.104     0.021     0.000     0.083    40001   Representable::Binding#representer_module_for
-    #   1.13      0.044     0.017     0.000     0.027    40001   Representable::Binding#representer_module_for (with memoize).
-    def representer_module_for(object, *args)
-      # TODO: cache this!
-      evaluate_option(:extend, object) # TODO: pass args? do we actually have args at the time this is called (compile-time)?
-    end
-
-    # 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 = @definition[name] # TODO: this could dispatch directly to the @definition using #send?
-        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, parent_decorator) : user_options
-
-      proc.evaluate(exec_context, *(args<<options)) # from Uber::Options::Value.
-    end
+    # include EvaluateOption
 
     def [](name)
       @definition[name]
     end
 
-    #   1.55      0.031     0.022     0.000     0.009    60004   Representable::Binding#skipable_empty_value?
-    #   1.51      0.030     0.022     0.000     0.008    60004   Representable::Binding#skipable_empty_value?
-    # after polymorphism:
-    # 1.44      0.031     0.022     0.000     0.009    60002   Representable::Binding#skipable_empty_value?
     def skipable_empty_value?(value)
       value.nil? and not self[:render_nil]
     end
@@ -147,112 +61,41 @@ module Representable
       value
     end
 
-    # Note: this method is experimental.
-    def update!(represented, user_options)
-      @represented = represented
-
-      setup_user_options!(user_options)
-      setup_exec_context!
-    end
-
     attr_accessor :cached_representer
 
-  private
-    def setup_user_options!(user_options)
-      @user_options  = user_options
-      # this is the propagated_options.
-      @user_options  = user_options.merge(wrap: false) if self[:wrap] == false
+    require "representable/pipeline_factories"
+    include Factories
 
-      # @user_options  = user_options.merge(wrap: self[:wrap]) if self[:wrap]
-    end
+  private
 
-    #   1.80      0.066     0.027     0.000     0.039    30002   Representable::Binding#setup_exec_context!
-    #   0.98      0.034     0.014     0.000     0.020    30002   Representable::Binding#setup_exec_context!
     def setup_exec_context!
-      return @exec_context = @represented unless self[:exec_context]
-      @exec_context = self             if self[:exec_context] == :binding
-      @exec_context = parent_decorator if self[:exec_context] == :decorator
+      @exec_context = ->(options) { options[:represented] }     unless self[:exec_context]
+      @exec_context = ->(options) { self }                      if self[:exec_context] == :binding
+      @exec_context = ->(options) { options[:decorator] }       if self[:exec_context] == :decorator
     end
 
-    attr_reader :exec_context, :parent_decorator
-
-    def serialize(object, &block)
-      serializer.call(object, &block)
+    def exec_context(options)
+      @exec_context.(options)
     end
 
-    module Factories
-      def serializer_class
-        Serializer
-      end
-
-      def serializer
-        @serializer ||= serializer_class.new(self)
-      end
-
-      def populator
-        @populator ||= populator_class.new(self)
-      end
-
-      def populator_class
-        Populator
-      end
-
-      def deserializer_class
-        Deserializer
-      end
-
-      def deserializer
-        @deserializer ||= deserializer_class.new(self)
-      end
+    def parse_pipeline(input, options)
+      @parse_pipeline ||= pipeline_for(:parse_pipeline, input, options) { Pipeline[*parse_functions] }
     end
-    include Factories
-
-
-    # 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)
 
+    def render_pipeline(input, options)
+      @render_pipeline ||= pipeline_for(:render_pipeline, input, options) { Pipeline[*render_functions] }
+    end
 
     # generics for collection bindings.
     module Collection
-    private
-      def populator_class
-        Populator::Collection
-      end
-
-      def serializer_class
-        Serializer::Collection
-      end
-
-      def deserializer_class
-        Deserializer::Collection
-      end
-
       def skipable_empty_value?(value)
         # TODO: this can be optimized, again.
         return true if value.nil? and not self[:render_nil] # FIXME: test this without the "and"
         return true if self[:render_empty] == false and value and value.size == 0  # TODO: change in 2.0, don't render emtpy.
       end
     end
-
-    # and the same for hashes.
-    module Hash
-    private
-      def populator_class
-        Populator::Hash
-      end
-
-      def serializer_class
-        Serializer::Hash
-      end
-
-      def deserializer_class
-        Deserializer::Hash
-      end
-    end
   end
 
-
   class DeserializeError < RuntimeError
   end
 end