roar 1.0.2 → 1.1.1

data/Rakefile

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

data/lib/roar/client.rb

@@ -2,7 +2,7 @@ require "roar/http_verbs"
 
 module Roar
 
-  # Mix in HttpVerbs. 
+  # Mix in HttpVerbs.
   module Client
     include HttpVerbs
 
@@ -28,12 +28,17 @@ module Roar
     end
 
     def to_hash(options={})
-      options[:links] ||= false
+      # options[:links] ||= false
+      options[:user_options] ||= {}
+      options[:user_options][:links] ||= false
+
       super(options)
     end
 
     def to_xml(options={}) # sorry, but i'm not even sure if anyone uses this module.
-      options[:links] ||= false
+      options[:user_options] ||= {}
+      options[:user_options][:links] ||= false
+
       super(options)
     end
   end

data/lib/roar/decorator.rb

@@ -4,8 +4,8 @@ require 'representable/decorator'
 class Roar::Decorator < Representable::Decorator
   module HypermediaConsumer
     def links=(arr)
-      links = super
-      represented.instance_variable_set :@links, links
+      super
+      represented.instance_variable_set :@links, self.links
     end
   end
 end

data/lib/roar/http_verbs.rb

@@ -68,21 +68,5 @@ module Roar
     def http
       transport_engine.new
     end
-
-    def handle_deprecated_args(body, *args) # TODO: remove in 1.0.
-      options = args.first
-
-      if args.size > 1
-        warn %{DEPRECATION WARNING: #get, #post, #put, #delete and #patch no longer accept positional arguments. Please call them as follows:
- get(uri: "http://localhost/songs", as: "application/json")
-post(uri: "http://localhost/songs", as: "application/json")
-Thank you and have a beautiful day.}
-        options = {:uri => args[0], :as => args[1]} if args.size == 2
-        options = {:uri => args[0], :as => args[2]}
-      end
-
-      options[:body] = body
-      options
-    end
   end
 end

data/lib/roar/hypermedia.rb

@@ -33,33 +33,26 @@ module Roar
   #
   #   model.to_json(:id => 1)
   module Hypermedia
-    # links= [Hyperlink, Hyperlink] is where parsing happens.
     def self.included(base)
       base.extend ClassMethods
     end
 
-    def links=(arr) # called when assigning parsed links.
-      @links = LinkCollection[*arr]
+    # public API: #links (only helpful in clients, though).
+    attr_writer :links # this is called in parsing when Hyperlinks are deserialized.
+    def links # this is _not_ called by rendering as we go via ::links_config.
+      tuples = (@links||[]).collect { |link| [link.rel, link] }
+      # tuples.to_h
+      ::Hash[tuples] # TODO: tuples.to_h when dropping < 2.1.
     end
 
-    attr_reader :links # this is only useful after parsing.
-
-
-    module LinkConfigsMethod
-      def link_configs # we could store the ::link configs in links Definition.
-        representable_attrs[:links] ||= Representable::Inheritable::Array.new
-      end
-    end
-
-    include LinkConfigsMethod
-
   private
     # Create hypermedia links for this instance by invoking their blocks.
     # This is called in links: getter: {}.
     def prepare_links!(options)
-      return [] if options[:links] == false
+      return [] if (options[:user_options] || {})[:links] == false
 
-      LinkCollection[*compile_links_for(link_configs, options)]
+      link_configs = representable_attrs["links"].link_configs
+      compile_links_for(link_configs, options)
     end
 
     def compile_links_for(configs, *args)
@@ -72,41 +65,12 @@ module Roar
     end
 
     def prepare_link_for(href, options)
-      options = options.merge(href.is_a?(::Hash) ? href : {:href => href})
+      options = options.merge(href.is_a?(::Hash) ? href : {href: href})
       Hyperlink.new(options)
     end
 
-    def run_link_block(block, *args)
-      instance_exec(*args, &block)
-    end
-
-
-    # LinkCollection keeps an array of Hyperlinks to be rendered (setup in #prepare_links!)
-    # or parsed (array is passed to #links= which transforms it into a LinkCollection).
-    # It is implemented as a hash and keys links by their rel value.
-    #
-    #   {"self" => <Hyperlink ..>, ..}
-    class LinkCollection < ::Hash
-      # The only way to create is LinkCollection[<Hyperlink>, <Hyperlink>]
-      def self.[](*arr)
-        super(arr.collect { |link| [link.rel, link] })
-      end
-
-      def [](rel)
-        super(rel.to_s)
-      end
-
-      # Iterating links. Block parameters: |link| or |rel, link|.
-      # This is used Hash::HashBinding#serialize.
-      def each(&block)
-        return values.each(&block) if block.arity == 1
-        super(&block)
-      end
-
-      def collect(&block) # TODO: remove me when we drop representable 2.0.x support!
-        return values.collect(&block) if block.arity == 1
-        super(&block)
-      end
+    def run_link_block(block, options)
+      instance_exec(options[:user_options], &block)
     end
 
 
@@ -122,23 +86,34 @@ module Roar
       # The block is executed in instance context, so you may call properties or other accessors.
       # Note that you're free to put decider logic into #link blocks, too.
       def link(options, &block)
-        create_links_definition! # this assures the links are rendered at the right position.
+        heritage.record(:link, options, &block)
+
+        links_dfn = create_links_definition! # this assures the links are rendered at the right position.
 
         options = {:rel => options} unless options.is_a?(::Hash)
-        link_configs << [options, block]
-      end
 
-      include LinkConfigsMethod
+        links_dfn.link_configs << [options, block]
+      end
 
     private
       # Add a :links Definition to the representable_attrs so they get rendered/parsed.
       def create_links_definition!
-        return if representable_attrs.get(:links) # only create it once.
+        dfn = definitions["links"] and return dfn # only create it once.
 
         options = links_definition_options
-        options.merge!(:getter => lambda { |opts| prepare_links!(opts) })
+        options.merge!(getter: ->(opts) { prepare_links!(opts) })
+
+        dfn = build_definition(:links, options)
+
+
+        dfn.extend(DefinitionOptions)
+        dfn
+      end
+    end
 
-        representable_attrs.add(:links, options)
+    module DefinitionOptions
+      def link_configs
+        @link_configs ||= []
       end
     end
 
@@ -172,7 +147,6 @@ module Roar
         attrs.inject({}) { |hsh, kv| hsh[kv.first.to_s] = kv.last; hsh }.tap do |hsh|
           hsh["rel"] = hsh["rel"].to_s if hsh["rel"]
         end
-        # raise "Hyperlink without rel doesn't work!" unless @attrs["rel"]
       end
     end
   end

data/lib/roar/json/collection.rb

@@ -1,3 +1,11 @@
-require "representable/json/collection"
+require 'roar/json'
 
-Roar::JSON::Collection = Representable::JSON::Collection
+module Roar::JSON
+  module Collection
+    include Roar::JSON
+
+    def self.included(base)
+      base.send :include, Representable::Hash::Collection
+    end
+  end
+end

data/lib/roar/json/hal.rb

@@ -1,4 +1,6 @@
-require 'roar/json'
+require "roar/json"
+require "representable/json/collection"
+require "representable/json/hash"
 
 module Roar
   module JSON
@@ -46,8 +48,8 @@ module Roar
         base.class_eval do
           include Roar::JSON
           include Links       # overwrites #links_definition_options.
-          extend ClassMethods # overwrites #links_definition_options, again.
           include Resources
+          include LinksReader # gives us Decorator#links => {self=>< >}
         end
       end
 
@@ -56,8 +58,9 @@ module Roar
           super.tap do |hash|
             embedded = {}
             representable_attrs.find_all do |dfn|
-              next unless dfn[:embedded] and fragment = hash.delete(dfn.name)
-              embedded[dfn.name] = fragment
+              name = dfn[:as] ? dfn[:as].(nil) : dfn.name # DISCUSS: should we simplify that in Representable?
+              next unless dfn[:embedded] and fragment = hash.delete(name)
+              embedded[name] = fragment
             end
 
             hash["_embedded"] = embedded if embedded.any?
@@ -71,38 +74,7 @@ module Roar
         end
       end
 
-      module ClassMethods
-        def links_definition_options
-          super.merge(:as => :_links)
-        end
-      end
 
-      class LinkCollection < Hypermedia::LinkCollection
-        def initialize(array_rels, *args)
-          super(*args)
-          @array_rels = array_rels.map(&:to_s)
-        end
-
-        def is_array?(rel)
-          @array_rels.include?(rel.to_s)
-        end
-      end
-
-      # Including this module in your representer will render and parse your embedded hyperlinks
-      # following the HAL specification: http://stateless.co/hal_specification.html
-      #
-      #   module SongRepresenter
-      #     include Roar::JSON
-      #     include Roar::JSON::HAL::Links
-      #
-      #     link :self { "http://self" }
-      #   end
-      #
-      # Renders to
-      #
-      #   {"links":{"self":{"href":"http://self"}}}
-      #
-      # Note that the HAL::Links module alone doesn't prepend an underscore to +links+. Use the JSON::HAL module for that.
       module Links
         def self.included(base)
           base.extend ClassMethods  # ::links_definition_options
@@ -111,83 +83,84 @@ module Roar
         end
 
         module InstanceMethods
+          def _links
+            links
+          end
+
         private
           def prepare_link_for(href, options)
-            return super(href, options) unless options[:array]  # TODO: remove :array and use special instan
+            return super(href, options) unless options[:array]  # returns Hyperlink.
 
-            list = href.collect { |opts| Hypermedia::Hyperlink.new(opts.merge!(:rel => options[:rel])) }
-            LinkArray.new(list, options[:rel])
-          end
-
-          # TODO: move to LinksDefinition.
-          def link_array_rels
-            link_configs.collect { |cfg| cfg.first[:array] ? cfg.first[:rel] : nil }.compact
+            ArrayLink.new(options[:rel], href.collect { |opts| Hypermedia::Hyperlink.new(opts) })
           end
         end
 
 
-        require 'representable/json/hash'
-        module LinkCollectionRepresenter
-          include Representable::JSON::Hash
-
-          values :extend => lambda { |item, *|
-            item.is_a?(Array) ? LinkArrayRepresenter : Roar::JSON::HyperlinkRepresenter },
-            :instance => lambda { |fragment, *| fragment.is_a?(LinkArray) ? fragment : Roar::Hypermedia::Hyperlink.new
-          }
+        class SingleLink
+          class Representer < Representable::Decorator
+            include Representable::JSON::Hash
 
-          def to_hash(options)
-            super.tap do |hsh|  # TODO: cool: super(:exclude => [:rel]).
-              hsh.each { |k,v| v.delete("rel") }
+            def to_hash(*)
+              hash = super
+              {hash.delete("rel").to_s => hash}
             end
           end
-
-
-          def from_hash(hash, *args)
-            hash.each { |k,v| hash[k] = LinkArray.new(v, k) if is_array?(k) }
-
-            hsh = super(hash) # this is where :class and :extend do the work.
-
-            hsh.each { |k, v| v.merge!(:rel => k) }
-            hsh.values # links= expects [Hyperlink, Hyperlink]
-          end
         end
 
-        # DISCUSS: we can probably get rid of this asset.
-        class LinkArray < Array
-          def initialize(elems, rel)
-            super(elems)
+        class ArrayLink < Array
+          def initialize(rel, links)
             @rel = rel
+            super(links)
           end
-
           attr_reader :rel
 
-          def merge!(attrs)
-            each { |lnk| lnk.merge!(attrs) }
+
+          # [Hyperlink, Hyperlink]
+          class Representer < Representable::Decorator
+            include Representable::JSON::Collection
+
+            items extend: SingleLink::Representer,
+                  class:  Roar::Hypermedia::Hyperlink
+
+            def to_hash(*)
+              links = super.flat_map(&:values) # [{"self"=>{"href": ..}}, ..]
+
+              { represented.rel.to_s => links } # {"self"=>[{"lang"=>"en", "href"=>"http://en.hit"}, {"lang"=>"de", "href"=>"http://de.hit"}]}
+            end
           end
         end
 
-        require 'representable/json/collection'
-        module LinkArrayRepresenter
+
+        # Represents all links for  "_links":  [Hyperlink, [Hyperlink, Hyperlink]]
+        class Representer < Representable::Decorator # links could be a simple collection property.
           include Representable::JSON::Collection
 
-          items :extend => Roar::JSON::HyperlinkRepresenter,
-            :class => Roar::Hypermedia::Hyperlink
+          # render: decorates represented.links with ArrayLink::R or SingleLink::R and calls #to_hash.
+          # parse:  instantiate either Array or Hypermedia instance, decorate respectively, call #from_hash.
+          items decorator: ->(options) { options[:input].is_a?(Array) ? ArrayLink::Representer : SingleLink::Representer },
+                class:     ->(options) { options[:input].is_a?(Array) ? Array : Hypermedia::Hyperlink }
+
+          def to_hash(options)
+            super.inject({}) { |links, hash| links.merge!(hash) } # [{ rel=>{}, rel=>[{}, {}] }]
+          end
 
-          def to_hash(*)
-            super.tap do |ary|
-              ary.each { |lnk| rel = lnk.delete("rel") }
+          def from_hash(hash, *args)
+            collection = hash.collect do |rel, value| # "self" => [{"href": "//"}, ] or "self" => {"href": "//"}
+              value.is_a?(Array) ? value.collect { |link| link.merge("rel"=>rel) } : value.merge("rel"=>rel)
             end
+
+            super(collection) # [{rel=>self, href=>//}, ..] or {rel=>self, href=>//}
           end
         end
 
 
         module ClassMethods
           def links_definition_options
-            # property :links_array,
             {
-              :as       => :links,
-              :extend   => HAL::Links::LinkCollectionRepresenter,
-              :instance => lambda { |*| LinkCollection.new(link_array_rels) }, # defined in InstanceMethods as this is executed in represented context.
+              # collection: false,
+              :as       => :_links,
+              decorator: Links::Representer,
+              instance: ->(*) { Array.new }, # defined in InstanceMethods as this is executed in represented context.
               :exec_context => :decorator,
             }
           end
@@ -199,7 +172,7 @@ module Roar
           #      {:lang => "de", :href => "http://de.hit"}]
           #   end
           def links(options, &block)
-            options = {:rel => options} if options.is_a?(Symbol)
+            options = {:rel => options} if options.is_a?(Symbol) || options.is_a?(String)
             options[:array] = true
             link(options, &block)
           end
@@ -217,6 +190,24 @@ module Roar
           end
         end
       end
+
+      # This is only helpful in client mode. It shouldn't be used per default.
+      module LinksReader
+        def links
+          return unless @links
+          tuples = @links.collect do |link|
+            if link.is_a?(Array)
+              next unless link.any?
+              [link.first.rel, link]
+            else
+              [link.rel, link]
+            end
+          end.compact
+
+          # tuples.to_h
+          ::Hash[tuples] # TODO: tuples.to_h when dropping < 2.1.
+        end
+      end
     end
   end
 end

data/lib/roar/json.rb

@@ -37,10 +37,10 @@ module Roar
       def links_definition_options
         # FIXME: this doesn't belong into the generic JSON representer.
         {
-          :collection     => true,
-          :class          => Hypermedia::Hyperlink,
-          :extend         => HyperlinkRepresenter,
-          :exec_context   => :decorator,
+          class:          Hypermedia::Hyperlink,
+          decorator:      HyperlinkDecorator,
+          collection:     true,
+          exec_context:   :decorator
         }
       end
     end
@@ -48,7 +48,7 @@ module Roar
 
     require "representable/json/hash"
     # Represents a hyperlink in standard roar+json hash representation.
-    module HyperlinkRepresenter
+    class HyperlinkDecorator < Representable::Decorator
       include Representable::JSON::Hash
     end
   end

data/lib/roar/version.rb

@@ -1,3 +1,3 @@
 module Roar
-  VERSION = "1.0.2"
+  VERSION = "1.1.1"
 end

data/lib/roar/xml.rb

@@ -35,10 +35,10 @@ module Roar
         # FIXME: this doesn't belong into the generic XML representer.
         {
           :as => :link,
-          :collection   => true,
           :class        => Hypermedia::Hyperlink,
           :extend       => XML::HyperlinkRepresenter,
           :exec_context => :decorator,
+          collection: true
           } # TODO: merge with JSON.
       end
     end

data/lib/roar.rb

@@ -1,6 +1,6 @@
 require 'roar/version'
+
 module Roar
-  def self.root
-    File.expand_path '../..', __FILE__
-  end
 end
+
+require "roar/decorator"

data/roar.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Nick Sutterer"]
   s.email       = ["apotonick@gmail.com"]
-  s.homepage    = "http://rubygems.org/gems/roar"
+  s.homepage    = "http://trailblazer.to/gems/roar"
   s.summary     = %q{Parse and render REST API documents using representers.}
   s.description = %q{Object-oriented representers help you defining nested REST API documents which can then be rendered and parsed using one and the same concept.}
   s.license = 'MIT'
@@ -17,14 +17,16 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency "representable", ">= 2.0.1", "<= 3.0.0"
+  s.required_ruby_version = '>= 1.9.3'
 
-  s.add_development_dependency "rake", ">= 0.10.1"
+  s.add_runtime_dependency "representable", "~> 3.0"
+
+  s.add_development_dependency "rake"
   s.add_development_dependency "test_xml", "0.1.6"
-  s.add_development_dependency "minitest",	">= 5.4.2"
+  s.add_development_dependency 'minitest', '>= 5.10'
   s.add_development_dependency "sinatra"
   s.add_development_dependency "sinatra-contrib"
   s.add_development_dependency "virtus", ">= 1.0.0"
   s.add_development_dependency "faraday"
-  s.add_development_dependency "json"
+  s.add_development_dependency "multi_json"
 end

data/test/client_test.rb

@@ -30,7 +30,7 @@ class ClientTest < MiniTest::Spec
     # since this is considered dangerous, we test the mutuable options.
     it "adds links: false to options" do
       song.to_hash(options = {})
-      options.must_equal({:links => false})
+      options.must_equal(user_options: {links: false})
     end
   end
 end

data/test/coercion_feature_test.rb

@@ -1,14 +1,17 @@
 require 'test_helper'
 require 'roar/coercion'
+require 'roar/decorator'
 
 class CoercionFeatureTest < MiniTest::Spec
   describe "Coercion" do
-    class ImmigrantSong
+    class SongDecorator < Roar::Decorator
       include Roar::JSON
       include Roar::Coercion
 
       property :composed_at, :type => DateTime, :default => "May 12th, 2012"
+    end
 
+    class ImmigrantSong
       attr_accessor :composed_at
       def composed_at=(v) # in ruby 2.2, #label= is not there, all at sudden. what *is* that?
         @composed_at = v
@@ -16,7 +19,9 @@ class CoercionFeatureTest < MiniTest::Spec
     end
 
     it "coerces into the provided type" do
-      song = ImmigrantSong.new.from_json("{\"composed_at\":\"November 18th, 1983\"}")
+      song      = ImmigrantSong.new
+      decorator = SongDecorator.new(song)
+      decorator.from_json("{\"composed_at\":\"November 18th, 1983\"}")
       assert_equal DateTime.parse("Fri, 18 Nov 1983 00:00:00 +0000"), song.composed_at
     end
   end

data/test/decorator_test.rb

@@ -27,11 +27,15 @@ class DecoratorTest < MiniTest::Spec
     describe "JSON" do
       let (:decorator_class) { rpr_mod = rpr
         Class.new(Roar::Decorator) do
+          include Roar::JSON
+          include Roar::Hypermedia
+
           include rpr_mod
         end }
       let (:decorator) { decorator_class.new(model) }
 
-      it "rendering links works" do
+      it "xxxrendering links works" do
+        pp decorator.send(:representable_attrs)
         decorator.to_hash.must_equal({"links"=>[{"rel"=>"self", "href"=>"http://self"}]})
       end
 
@@ -42,7 +46,7 @@ class DecoratorTest < MiniTest::Spec
 
       it "does not set links on represented" do
         decorator_class.new(model_with_links).from_hash("links"=>[{:rel=>:self, :href=>"http://self"}])
-        model_with_links.links.must_equal nil
+        model_with_links.links.must_be_nil
       end
 
       class ConsumingDecorator < Roar::Decorator
@@ -63,10 +67,10 @@ class DecoratorTest < MiniTest::Spec
           decorator.from_hash("links"=>[{:rel=>:self, :href=>"http://percolator"}])
 
           # links are always set on decorator instance.
-          decorator       .links[:self].must_equal(link(:rel=>:self, :href=>"http://percolator"))
+          decorator.links["self"].must_equal(link(:rel=>:self, :href=>"http://percolator"))
 
           # and propagated to represented with HypermediaConsumer.
-          model_with_links.links[:self].must_equal(link(:rel=>:self, :href=>"http://percolator"))
+          model_with_links.links["self"].must_equal(link(:rel=>:self, :href=>"http://percolator"))
         end
       end
     end
@@ -78,6 +82,8 @@ class DecoratorTest < MiniTest::Spec
       end
       let (:decorator_class) { rpr_mod = rpr
         Class.new(Roar::Decorator) do
+          include Roar::XML
+          include Roar::Hypermedia
           include rpr_mod
           self.representation_wrap = :song
         end
@@ -97,10 +103,13 @@ class DecoratorTest < MiniTest::Spec
 
     describe "JSON::HAL" do
       representer_for([Roar::JSON::HAL]) do
+        # feature Roar::JSON::HAL
         link(:self) { "http://self" }
       end
       let (:decorator_class) { rpr_mod = rpr
         Class.new(Roar::Decorator) do
+          include Roar::JSON::HAL
+
           include rpr_mod
         end
       }
@@ -116,15 +125,16 @@ class DecoratorTest < MiniTest::Spec
       end
 
       describe "Decorator::HypermediaClient" do
-        let (:decorator) { rpr_mod = rpr
+        let (:decorator_class) { rpr_mod = rpr
           Class.new(Roar::Decorator) do
+            include Roar::JSON::HAL
             include rpr_mod
             include Roar::Decorator::HypermediaConsumer
           end }
 
         it "propagates links to represented" do
-          decorator.new(model_with_links).from_hash("_links"=>{"self"=>{:href=>"http://self"}})
-          model_with_links.links[:self].must_equal(link(:rel=>"self", :href=>"http://self"))
+          decorator_class.new(model_with_links).from_hash("_links"=>{"self"=>{:href=>"http://self"}})
+          model_with_links.links["self"].must_equal(link(:rel=>"self", :href=>"http://self"))
         end
       end
     end