representable 1.5.3 → 1.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f465aa1b0aa43a6e5d2bacba9a09352679d2e9c0
+  data.tar.gz: 63ad7fd426a19a8efdc2ee5b06590a29507011fd
+SHA512:
+  metadata.gz: 3d7a5b5b2f92d3fba72b01acace5bf14e40c80f8c55e82da3429b8870a67203eb681d2d777598848eec4d0515c9133a235ce5de36ea8365ecdc0d1d7597d7031
+  data.tar.gz: 0a76832f4640f6287abee2668ab58a867b65e573adfbbf71b1be44208215d068f5953dd88a7468b822208a20f3b78050f1f2f64ffdda87dc86b9bb9501386bfd

data/{CHANGES.textile → CHANGES.md}

@@ -1,3 +1,20 @@
+h2. 1.6.0
+
+* You can define inline representers now if you don't wanna use multiple modules and files.
+<!-- here comes some code -->
+```ruby
+property :song, class: Song do
+  property :title
+end
+```
+
+This supersedes the use for `:extend` or `:decorator`, which still works, of course.
+
+* Coercion now happens in a dedicated coercion object. This means that in your models virtus no longer creates accessors for coerced properties and thus values get coerced when rendering or parsing a document, only. If you want the old behavior, include `Virtus` into your model class and do the coercion yourself.
+* `Decorator::Coercion` is deprecated, just use `include Representable::Coercion`.
+* Introducing `Mapper` which does most of the rendering/parsing process. Be careful, if you used to override private methods like  `#compile_fragment` this no longer works, you have to override that in `Mapper` now.
+* Fixed a bug where inheriting from Decorator wouldn't inherit properties correctly.
+
 h2. 1.5.3
 
 * `Representable#update_properties_from` now always returns `represented`, which is `self` in a module representer and the decorated object in a decorator (only the latter changed).

data/Gemfile

@@ -3,4 +3,4 @@ source 'https://rubygems.org'
 gemspec
 
 #gem "virtus", :path => "../virtus"
-gem 'rake', "10.1.0.beta3"
+gem 'rake', "10.1.0"

data/README.md

@@ -174,6 +174,25 @@ Album.new.extend(AlbumRepresenter).
 #=> #<Album name="Offspring", songs=[#<Song title="Genocide">, #<Song title="Nitro", composers=["Offspring"]>]>
 ```
 
+## Inline Representers
+
+If you don't want to maintain two separate modules when nesting representations you can define the `SongRepresenter` inline.
+
+```ruby
+module AlbumRepresenter
+  include Representable::JSON
+
+  property :name
+
+  collection :songs, class: Song do
+    property :title
+    property :track
+    collection :composers
+  end
+```
+
+This works both for representer modules and decorators.
+
 ## Decorator vs. Extend
 
 People who dislike `:extend` go use the `Decorator` strategy!
@@ -576,7 +595,7 @@ class Song < OpenStruct
 end
 ```
 
-I do not recommend this approach as it bloats your domain classes with representation logic that is barely needed elsewhere.
+I do not recommend this approach as it bloats your domain classes with representation logic that is barely needed elsewhere. Use [decorators](#decorator-vs-extend) instead.
 
 
 ## More Options
@@ -679,17 +698,19 @@ module SongRepresenter
 end
 ```
 
-When using a decorator representer, use the `Representable::Decorator::Coercion` module.
+In a decorator it works alike.
 
 ```ruby
 module SongRepresenter < Representable::Decorator
   include Representable::JSON
-  include Representable::Decorator::Coercion
+  include Representable::Coercion
 
   property :recorded_at, :type => DateTime
 end
 ```
 
+Coercing values only happens when rendering or parsing a document. Representable does not create accessors in your model as `virtus` does.
+
 ## Undocumented Features
 
 (Please don't read this section!)

data/TODO

@@ -6,7 +6,6 @@ class: |key, hsh|
 
 document `XML::AttributeHash` etc
 
-* deprecate :from, make :a(lia)s authorative.
 * cleanup ReadableWriteable
 * deprecate Representable::*::ClassMethods (::from_hash and friends)
 
@@ -14,7 +13,7 @@ document `XML::AttributeHash` etc
 
 * have representable-options (:include, :exclude) and user-options
 
-* make all properties "Object-like", even arrays of strings etc.
+* make all properties "Object-like", even arrays of strings etc. This saves us from having `extend ObjectBinding if typed?` and we could just call to_hash/from_hash on all attributes. performance issues here? otherwise: implement!
 
 
 def compile_fragment(doc)
@@ -27,4 +26,13 @@ module ReaderWriter
 
 * make lambda options optional (arity == 0)
 
-* pass args to methods when arity matches
+* pass args to methods when arity matches
+
+* DISCUSS if Decorator.new.representable_attrs != Decorator.representable_attrs ? (what about performance?)
+* REMOVE :from, make :a(lia)s authorative.
+
+* does :instance not work with :decorator ?
+* make it easy to override Binding#options via #to_hash(whatever: {hit: {decorator: HitDecorator}})
+
+* DISCUSS: should inline representers be created at runtime, so we don't need ::representer_engine?
+* deprecate `Decorator::Coercion`.

data/lib/representable.rb

@@ -1,31 +1,8 @@
 require 'representable/deprecations'
 require 'representable/definition'
-require 'representable/feature/readable_writeable'
-
-# Representable can be used in two ways.
-#
-# == On class level
-#
-# To try out Representable you might include the format module into the represented class directly and then
-# define the properties.
-#
-#   class Hero < ActiveRecord::Base
-#     include Representable::JSON
-#     property :name
-#
-# This will give you to_/from_json for each instance. However, this approach limits your class to one representation.
-#
-# == On module level
-#
-# Modules give you much more flexibility since you can mix them into objects at runtime, following the DCI
-# pattern.
-#
-#   module HeroRepresenter
-#     include Representable::JSON
-#     property :name
-#   end
-#
-#   hero.extend(HeroRepresenter).to_json
+require 'representable/mapper'
+require 'representable/config'
+
 module Representable
   attr_writer :representable_attrs
 
@@ -36,103 +13,64 @@ module Representable
       extend ClassMethods::Declarations
 
       include Deprecations
-      include Feature::ReadableWriteable
     end
   end
 
   # Reads values from +doc+ and sets properties accordingly.
   def update_properties_from(doc, options, format)
-    representable_bindings_for(format, options).each do |bin|
-      deserialize_property(bin, doc, options)
-    end
-    represented
+    # deserialize_for(bindings, mapper ? , options)
+    representable_mapper(format, options).deserialize(doc, options)
   end
 
 private
   # Compiles the document going through all properties.
   def create_representation_with(doc, options, format)
-    representable_bindings_for(format, options).each do |bin|
-      serialize_property(bin, doc, options)
-    end
-    doc
+    representable_mapper(format, options).serialize(doc, options)
   end
 
-  def serialize_property(binding, doc, options)
-    return if skip_property?(binding, options)
-    compile_fragment(binding, doc)
-  end
-
-  def deserialize_property(binding, doc, options)
-    return if skip_property?(binding, options)
-    uncompile_fragment(binding, doc)
-  end
-
-  # Checks and returns if the property should be included.
-  def skip_property?(binding, options)
-    return true if skip_excluded_property?(binding, options)  # no need for further evaluation when :exclude'ed
-
-    skip_conditional_property?(binding)
-  end
-
-  def skip_excluded_property?(binding, options)
-    return unless props = options[:exclude] || options[:include]
-    res   = props.include?(binding.name.to_sym)
-    options[:include] ? !res : res
+  def representable_bindings_for(format, options)
+    options = cleanup_options(options)  # FIXME: make representable-options and user-options  two different hashes.
+    representable_attrs.collect {|attr| representable_binding_for(attr, format, options) }
   end
 
-  def skip_conditional_property?(binding)
-    # TODO: move to Binding.
-    return unless condition = binding.options[:if]
-
-    args = []
-    args << binding.user_options if condition.arity > 0 # TODO: remove arity check. users should know whether they pass options or not.
-
-    not represented.instance_exec(*args, &condition)
-  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?
 
-  # TODO: remove in 1.4.
-  def compile_fragment(bin, doc)
-    bin.compile_fragment(doc)
+    format.build(attribute, represented, options, context)
   end
 
-  # TODO: remove in 1.4.
-  def uncompile_fragment(bin, doc)
-    bin.uncompile_fragment(doc)
+  def cleanup_options(options) # TODO: remove me. this clearly belongs in Representable.
+    options.reject { |k,v| [:include, :exclude].include?(k) }
   end
 
   def representable_attrs
     @representable_attrs ||= self.class.representable_attrs # DISCUSS: copy, or better not?
   end
 
-  # Returns the wrapper for the representation. Mostly used in XML.
-  def representation_wrap
-    representable_attrs.wrap_for(self.class.name)
+  def representable_mapper(format, options)
+    bindings = representable_bindings_for(format, options)
+    Mapper.new(bindings, represented, options) # TODO: remove self, or do we need it? and also represented!
   end
 
-private
-  def representable_bindings_for(format, options)
-    options = cleanup_options(options)  # FIXME: make representable-options and user-options two different hashes.
-    representable_attrs.map {|attr| representable_binding_for(attr, format, options) }
-  end
 
-  def representable_binding_for(attribute, format, options)
-    # DISCUSS: shouldn't this happen in Binding?
-    format.build(attribute, represented, options)
+  def representation_wrap
+    representable_attrs.wrap_for(self.class.name) # FIXME: where is this needed?
   end
 
   def represented
     self
   end
 
-  def cleanup_options(options) # TODO: remove me.
-    options.reject { |k,v| [:include, :exclude].include?(k) }
-  end
-
   module ClassInclusions
     def included(base)
       super
       base.representable_attrs.inherit(representable_attrs)
     end
+
+    def inherited(base) # DISCUSS: this could be in Decorator? but then we couldn't do B < A(include X) for non-decorators, right?
+      super
+      base.representable_attrs.inherit(representable_attrs)
+    end
   end
 
   module ModuleExtensions
@@ -177,8 +115,12 @@ private
       #   property :name, :render_nil => true
       #   property :name, :readable => false
       #   property :name, :writeable => false
-      def property(name, options={})
-        representable_attrs << definition_class.new(name, options)
+      def property(name, options={}, &block)
+        if block_given? # DISCUSS: separate module?
+          options[:extend] = inline_representer(representer_engine, &block)
+        end
+
+        (representable_attrs << definition_class.new(name, options)).last
       end
 
       # Declares a represented document node collection.
@@ -208,37 +150,15 @@ private
       def build_config
         Config.new
       end
-    end
-  end
-
-
-  # NOTE: the API of Config is subject to change so don't rely too much on this private object.
-  class Config < Array
-    attr_accessor :wrap
-
-    # Computes the wrap string or returns false.
-    def wrap_for(name)
-      return unless wrap
-      return infer_name_for(name) if wrap === true
-      wrap
-    end
 
-    def clone
-      self.class.new(collect { |d| d.clone })
-    end
-
-    def inherit(parent)
-      push(*parent.clone)
-    end
-
-  private
-    def infer_name_for(name)
-      name.to_s.split('::').last.
-       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-       gsub(/([a-z\d])([A-Z])/,'\1_\2').
-       downcase
+      def inline_representer(base_module, &block) # DISCUSS: separate module?
+        Module.new do
+          include base_module
+          instance_exec &block
+        end
+      end
     end
   end
 end
 
-require 'representable/decorator'
+require 'representable/decorator'

data/lib/representable/coercion.rb

@@ -1,17 +1,42 @@
 require "virtus"
 
 module Representable::Coercion
+  class Coercer
+    include Virtus
+
+    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)
+    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
-      include Virtus
       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
     end
+
   end
 
   module ClassMethods
-    def property(name, args={})
-       attribute(name, args[:type]) if args[:type] # FIXME (in virtus): undefined method `superclass' for VirtusCoercionTest::SongRepresenter:Module
-      super(name, args)
+    def property(name, options={})
+      return super unless options[:type]
+
+      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[:getter] = lambda { |*| coercer.coerce(name, represented.send(name)) }
+      options[:setter] = lambda { |v,*| represented.send("#{name}=", coercer.coerce(name, v)) }
+
+      super
     end
   end
+
+  def coercer
+    @coercer ||= representable_attrs.inheritable_array(:coercer_class).first.new
+  end
 end

data/lib/representable/config.rb

@@ -0,0 +1,52 @@
+module Representable
+  # NOTE: the API of Config is subject to change so don't rely too much on this private object.
+  class Config < Array
+    # 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
+
+        parent.inheritable_arrays.keys.each do |k|
+          inheritable_array(k).push *parent.inheritable_array(k).clone
+        end
+      end
+    end
+
+
+    attr_accessor :wrap
+
+    # Computes the wrap string or returns false.
+    def wrap_for(name)
+      return unless wrap
+      return infer_name_for(name) if wrap === true
+      wrap
+    end
+
+    module InheritMethods
+      def clone
+        self.class.new(collect { |d| d.clone })
+      end
+
+      def inherit(parent)
+        push(*parent.clone)
+      end
+    end
+    include InheritMethods
+    include InheritableArray # overrides #inherit.
+
+  private
+    def infer_name_for(name)
+      name.to_s.split('::').last.
+       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+       gsub(/([a-z\d])([A-Z])/,'\1_\2').
+       downcase
+    end
+  end
+end

data/lib/representable/decorator.rb

@@ -4,7 +4,14 @@ module Representable
     alias_method :decorated, :represented
 
     def self.prepare(represented)
-      new(represented)  # was: PrepareStrategy::Decorate.
+      new(represented)
+    end
+
+    def self.inline_representer(base_module, &block) # DISCUSS: separate module?
+      Class.new(self) do
+        include base_module
+        instance_exec &block
+      end
     end
 
     include Representable # include after class methods so Decorator::prepare can't be overwritten by Representable::prepare.
@@ -12,11 +19,5 @@ module Representable
     def initialize(represented)
       @represented = represented
     end
-
-    def representable_binding_for(attr, format, options)
-      context = attr.options[:decorator_scope] ? self : represented  # DISCUSS: should Decorator know this kinda stuff?
-
-      format.build(attr, represented, options, context)
-    end
   end
 end