representable 1.8.5 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a1a2857b730f1ccca3640f6c62cab57d6249e09
-  data.tar.gz: 52ad685bb60805ff9d8d866e356a1cd33eac1633
+  metadata.gz: c06c246f8a877ca22b35b7e5f409be0f5b1d6922
+  data.tar.gz: 57183b1d4597321d6ed84278407032b04ac3eb8a
 SHA512:
-  metadata.gz: 7a4c5aa9d35483807234ba1fe8c9e3b466c8d7e5879f38b5a635b68a0b2c1bb3df580841cadfe97159e4dddf7f63f9888dff7e73ddcc1a856270adb4d2894ad4
-  data.tar.gz: 93c1a493c867c4628595298bc49df0b04e62b7789d0a48fad84983093cc10ee43771c14791e917d580d94825f7b4a17bfd8a50b804b1285c0ab95ad8ce2783c0
+  metadata.gz: ed0821431bd7bee01cf48dc470211a78cdaa80a6de27df4961bf9028f6824a5914bf16bf86ffd59ca4698f60c56362226421aa2ea011933de82aa3072c28d081
+  data.tar.gz: df87389a3a4b6e7841915dbf9b5ae999942f2640e70c27d199cc1ded97f1d2d1f9d6df3c400a3c76110176b5cdc55acdb5c73bb97da6b0a6986321e41a8dfb0a

data/.travis.yml

@@ -5,6 +5,6 @@ matrix:
     - rvm: 1.9.3
     - rvm: 2.0.0
     - rvm: 2.1.1
-    - rvm: rbx-2
+    - rvm: rbx-2.2.10
     - rvm: jruby-19mode
 

data/CHANGES.md

@@ -1,3 +1,39 @@
+# 2.0.0
+
+## Relevant
+
+* Removed class methods `::from_json`, `::from_hash`, `::from_yaml` and `::from_xml`. Please build the instance yourself and use something along `Song.new.from_json`.
+* Inline representers in `Decorator` do *no longer inherit from `self`*. When defining an inline representer, they are always derived from `Representable::Decorator`. The base class can be changed by overriding `Decorator::default_inline_class` in the decorator class that defines an inline representer block.
+If you need to inherit common methods to all inline decorators, include the module using `::feature`: `Representer.feature(BetterProperty)`.
+* Removed behaviour for `instance: lambda { |*| nil }` which used to return `binding.get`. Simply do it yourself: `instance: lambda { |fragment, options| options.binding.get }` if you need this behaviour. If you use `:instance` and it returns `nil` it throws a `DeserializeError` now, which is way more understandable than `NoMethodError: undefined method `title=' for {"title"=>"Perpetual"}:Hash`.
+* Remove behaviour for `class: lambda { nil }` which used to return the fragment. This now throws a `DeserializeError`. Do it yourself with class: lambda { |fragment,*| fragment }.
+* Coercion now happens inside `:render_filter` and `:parse_filter` (new!) and doesn't block `:getter` and `:setter` anymore.
+    We require virtus >=1.0 now.
+* `::representation_wrap=` in now properly inherited.
+* Including modules with representable `property .., inherit: true` into a `Decorator` crashed. This works fine now.
+
+## New Stuff
+
+* Added `::for_collection` to automatically generate a collection representer for singular one. Thanks to @timoschilling for inspiring this years ago.
+* Added `::represent` that will detect collections and render the singular/collection with the respective representer.
+* Callable options
+* :parse_filter, :render_filter
+
+## Internals
+
+* Added `Representable::feature` to include a module and register it to be included into inline representers.
+* New signature: `inline_representer(base, features, name, options, &block)`.
+* Removed `::representer_engine`, the module to include is just another `register_feature` now.
+* `Config` no longer is a Hash, it's API is limited to a few methods like `#<<`, `#[]` etc. It still supports the `Enumberable` interface.
+* Moved `Representable::ClassMethods::Declarations` to `Representable::Declarative`.
+* Moved `Representable::ClassMethods` to `Representable::Declarative`.
+* Fixed: Inline decorators now work with `inherit: true`.
+* Remove `:extend` in combination with inline representer. The `:extend` option is no longer considered. Include the module directly into the inline block.
+* Deprecated class methods `::from_json` and friends. Use the instance version on an instance.
+* Use uber 0.0.7 so we can use `Uber::Callable`.
+* Removed `Decorator::Coercion`.
+* Removed `Definition#skipable_nil_value?`.
+
 # 1.8.5
 
 * Binding now uses `#method_missing` instead of SimpleDelegator for a significant performance boost of many 100%s. Thanks to @0x4a616d6573 for figuring this.

data/Gemfile

@@ -2,8 +2,8 @@ source 'https://rubygems.org'
 
 gemspec
 
-#gem "virtus", :path => "../virtus"
-
 platform :rbx do
-  gem 'psych'
+  gem "psych"
+  gem "rubysl-irb"
+  gem "json_pure"
 end

data/README.md

@@ -4,7 +4,7 @@ Representable maps Ruby objects to documents and back.
 
 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 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.
+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.
 
 
 ## Installation
@@ -267,7 +267,7 @@ module AlbumRepresenter
 
 This works both for representer modules and decorators.
 
-An inline representer is just a Ruby module. You can include other representer modules. This is handy when having a base representer that needs to be extended in the inline block.
+An inline representer is just a Ruby module (or a `Decorator` class). You can include other representer modules. This is handy when having a base representer that needs to be extended in the inline block.
 
 ```ruby
 module AlbumRepresenter
@@ -280,6 +280,66 @@ module AlbumRepresenter
   end
 ```
 
+If you need to include modules in all inline representers automatically, register it as a feature.
+
+```ruby
+module AlbumRepresenter
+  include Representable::JSON
+  feature Link # imports ::link
+
+  link "/album/1"
+
+  property :hit do
+    link "/hit/1" # link method imported automatically.
+  end
+```
+
+
+## Representing Singular Models And Collections
+
+You can explicitly define representers for collections of models using a ["Lonely Collection"](#lonely-collections). Or you can let representable  do that for you.
+
+Rendering a collection of objects comes for free, using `::for_collection`.
+
+```ruby
+  Song.all.extend(SongRepresenter.for_collection).to_hash
+  #=> [{title: "Sevens"}, {title: "Eric"}]
+```
+
+For parsing, you need to provide the class constant to which the items should be deserialized to.
+
+```ruby
+module SongRepresenter
+  include Representable::Hash
+  property :title
+
+  collection_representer class: Song
+end
+```
+
+You can now parse collections to `Song` instances.
+
+```ruby
+[].extend(SongRepresenter.for_collection).from_hash([{title: "Sevens"}, {title: "Eric"}])
+```
+
+As always, this works for decorators _and_ modules.
+
+In case you don't want to know whether or not you're working with a collection or singular model, use `::represent`.
+
+```ruby
+# singular
+SongRepresenter.represent(Song.find(1)).to_hash #=> {title: "Sevens"}
+
+# collection
+SongRepresenter.represent(Song.all).to_hash #=> [{title: "Sevens"}, {title: "Eric"}]
+```
+
+As you can see, `::represent` figures out the correct representer for you (works also for parsing!).
+
+Note: the implicit collection representer internally is implemented using a lonely collection. Everything you pass to `::collection_representer` is simply provided to the `::items` call in the lonely collection. That allows you to use `:parse_strategy` and all the other goodies, too.
+
+
 ## Document Nesting
 
 Not always does the structure of the desired document map to your objects. The `::nested` method allows you to structure properties in a separate section while still mapping the properties to the outer object.

data/Rakefile

@@ -6,6 +6,6 @@ task :default => :test
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  test.test_files = FileList['test/*_test.rb']
+  test.test_files = FileList['test/**/*_test.rb']
   test.verbose = true
 end

data/lib/representable.rb

@@ -1,16 +1,27 @@
+require 'representable/inheritable'
+require 'representable/config'
 require 'representable/definition'
 require 'representable/mapper'
-require 'representable/config'
+require 'representable/for_collection'
+require 'representable/represent'
+require 'representable/declarative'
+
+
+require 'uber/callable'
+require 'representable/pipeline'
 
 module Representable
   attr_writer :representable_attrs
 
   def self.included(base)
     base.class_eval do
+      extend Declarative
       extend ClassInclusions, ModuleExtensions
       extend ClassMethods
-      extend ClassMethods::Declarations
-      extend DSLAdditions
+      extend Feature
+      extend ForCollection
+      extend Represent
+      # register_feature Representable # Representable gets included automatically when creating inline representer.
     end
   end
 
@@ -40,7 +51,7 @@ private
   end
 
   def representable_attrs
-    @representable_attrs ||= self.class.representable_attrs # DISCUSS: copy, or better not?
+    @representable_attrs ||= self.class.representable_attrs # DISCUSS: copy, or better not? what about "freezing"?
   end
 
   def representable_mapper(format, options)
@@ -60,17 +71,18 @@ private
   module ClassInclusions
     def included(base)
       super
-      base.representable_attrs.inherit(representable_attrs)
+      base.inherit_module!(self)
     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)
+      base.representable_attrs.inherit!(representable_attrs) # this should be inherit_class!
     end
   end
 
   module ModuleExtensions
-    # Copies the representable_attrs to the extended object.
+    # Copies the representable_attrs reference to the extended object.
+    # Note that changing attrs in the instance will affect the class configuration.
     def extended(object)
       super
       object.representable_attrs=(representable_attrs) # yes, we want a hard overwrite here and no inheritance.
@@ -79,119 +91,30 @@ private
 
 
   module ClassMethods
-    # Create and yield object and options. Called in .from_json and friends.
-    def create_represented(document, *args)
-      new.tap do |represented|
-        yield represented, *args if block_given?
-      end
+    # 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)  # was: PrepareStrategy::Extend.
+      represented.extend(self)
     end
-
-
-    module Declarations
-      def representable_attrs
-        @representable_attrs ||= build_config
-      end
-
-      def representation_wrap=(name)
-        representable_attrs.wrap = name
-      end
-
-      def property(name, options={}, &block)
-        representable_attrs << definition_class.new(name, options)
-      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
-
-    private
-      def definition_class
-        Definition
-      end
-
-      def build_config
-        Config.new
-      end
-    end # Declarations
   end
 
-  # Internal module for DSL sugar that should not go into the core library.
-  module DSLAdditions
-    # 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)
-      modules = []
-
-      if options[:inherit] # TODO: move this to Definition.
-        parent  = representable_attrs[name]
-        modules << parent[:extend].evaluate(nil) if parent[:extend]# we can savely assume this is _not_ a lambda. # DISCUSS: leave that in #representer_module?
-      end # FIXME: can we handle this in super/Definition.new ?
 
-      if block_given?
-        handle_deprecated_inline_extend!(modules, options)
-
-        options[:extend] = inline_representer_for(modules, name, options, &block)
-      end
-
-      return parent.merge!(options) if options.delete(:inherit)
-
-      super
-    end
-
-    def inline_representer(base_module, name, options, &block) # DISCUSS: separate module?
-      Module.new do
-        include *base_module # Representable::JSON or similar.
-        instance_exec &block
+  module Feature
+    def feature(*mods)
+      mods.each do |mod|
+        include mod
+        register_feature(mod)
       end
     end
 
   private
-    def inline_representer_for(modules, name, options, &block)
-      representer = options[:use_decorator] ? Decorator : self
-      modules     = [representer_engine] + modules
-
-      representer.inline_representer(modules.compact.reverse, name, options, &block)
+    def register_feature(mod)
+      representable_attrs[:features][mod] = true
     end
-
-    def handle_deprecated_inline_extend!(modules, options) # TODO: remove in 2.0.
-      return unless include_module = options.delete(:extend) and not options[:inherit]
-
-      warn "[Representable] Using :extend with an inline representer is deprecated. Include the module in the inline block."
-      modules << include_module
-    end
-  end # DSLAdditions
-end
-
-
-module Representable
-  autoload :Hash, 'representable/hash'
-
-  module Hash
-    autoload :AllowSymbols, 'representable/hash/allow_symbols'
-    autoload :Collection, 'representable/hash/collection'
   end
-
-  autoload :Decorator, 'representable/decorator'
 end
+
+require 'representable/autoload'

data/lib/representable/TODO.getting_serious

@@ -1,5 +1,11 @@
+* Cleanup the manifest part in Decorator.
+
 * all property objects should be extended/wrapped so we don't need the switch.
 
 # Deprecations
 
-* deprecate instance: { nil } which is superseded by parse_strategy: :sync
+* deprecate instance: { nil } which is superseded by parse_strategy: :sync
+
+
+
+from_hash, property :band, class: vergessen

data/lib/representable/autoload.rb

@@ -0,0 +1,10 @@
+module Representable
+  autoload :Hash, 'representable/hash'
+
+  module Hash
+    autoload :AllowSymbols, 'representable/hash/allow_symbols'
+    autoload :Collection, 'representable/hash/collection'
+  end
+
+  autoload :Decorator, 'representable/decorator'
+end

data/lib/representable/binding.rb

@@ -14,7 +14,7 @@ module Representable
     end
 
     def initialize(definition, represented, decorator, user_options={})  # TODO: remove default arg for user options.
-      @definition = definition
+      @definition   = definition
       @represented  = represented
       @decorator    = decorator
       @user_options = user_options
@@ -31,7 +31,8 @@ module Representable
     # Retrieve value and write fragment to the doc.
     def compile_fragment(doc)
       evaluate_option(:writer, doc) do
-        write_fragment(doc, get)
+        value = render_filter(get, doc)
+        write_fragment(doc, value)
       end
     end
 
@@ -39,6 +40,7 @@ module Representable
     def uncompile_fragment(doc)
       evaluate_option(:reader, doc) do
         read_fragment(doc) do |value|
+          value = parse_filter(value, doc)
           set(value)
         end
       end
@@ -70,6 +72,15 @@ module Representable
       read(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)
@@ -142,7 +153,7 @@ module Representable
     private
       # DISCUSS: deprecate :class in favour of :instance and simplicity?
       def class_for(fragment, *args)
-        item_class = class_from(fragment, *args) or return handle_deprecated_class(fragment)
+        item_class = class_from(fragment, *args) or raise DeserializeError.new(":class did not return class constant.")
         item_class.new
       end
 
@@ -151,20 +162,13 @@ module Representable
       end
 
       def instance_for(fragment, *args)
-        instance = evaluate_option(:instance, fragment, *args)
-
-        if instance === true # TODO: remove in 2.0.
-          warn "[Representable] `instance: lambda { true }` is deprecated. Apparently, you know what you're doing, so use `parse_strategy: :sync` instead."
-          return get
-        end
-
-        instance
-      end
-
-      def handle_deprecated_class(fragment) # TODO: remove in 2.0.
-        warn "[Representable] `class: lambda { nil }` is deprecated. To return the fragment from parsing, use `instance: lambda { |fragment, *args| fragment }` instead."
-        fragment
+        # cool: if no :instance set, { return } will jump out of this method.
+        evaluate_option(:instance, fragment, *args) { return } or raise DeserializeError.new(":instance did not return object.")
       end
     end
   end
+
+
+  class DeserializeError < RuntimeError
+  end
 end