roar 1.0.0 → 1.0.1

data/lib/roar/json/json_api.rb

@@ -22,7 +22,7 @@ module Roar
           singular = self # e.g. Song::Representer
 
           # this basically does Module.new { include Hash::Collection .. }
-          build_inline(nil, [Document::Collection, Representable::Hash::Collection, Roar::JSON], "", {}) do
+          build_inline(nil, [Representable::Hash::Collection, Document::Collection, Roar::JSON], "", {}) do
             items extend: singular, :parse_strategy => :sync
 
             representable_attrs[:resource_representer] = singular.representable_attrs[:resource_representer]
@@ -36,7 +36,7 @@ module Roar
       module Singular
         def to_hash(options={})
           # per resource:
-          super(:exclude => [:links]).tap do |hash|
+          super(options.merge(:exclude => [:links])).tap do |hash|
             hash["links"] = hash.delete("_links") if hash["_links"]
           end
         end
@@ -81,7 +81,7 @@ module Roar
 
           # Per-model links.
           def links(&block)
-            nested(:_links, &block)
+            nested(:_links, :inherit => true, &block)
           end
 
           # TODO: always create _links.

data/lib/roar/version.rb

@@ -1,3 +1,3 @@
 module Roar
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

data/roar.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Nick Sutterer"]
   s.email       = ["apotonick@gmail.com"]
   s.homepage    = "http://rubygems.org/gems/roar"
-  s.summary     = %q{Resource-oriented architectures in Ruby.}
-  s.description = %q{Streamlines the development of RESTful, resource-oriented architectures in Ruby.}
+  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'
 
   s.files         = `git ls-files`.split("\n")

data/test/decorator_client_test.rb

@@ -0,0 +1,64 @@
+require 'test_helper'
+require 'roar/decorator'
+require 'roar/client'
+
+class DecoratorClientTest < MiniTest::Spec
+  class Crew
+    attr_accessor :moniker, :company
+  end
+  
+  class CrewDecorator < Roar::Decorator
+    include Roar::JSON
+    include Roar::Hypermedia
+
+    property :moniker, as: :name
+    property :company, as: :label
+
+    link(:self) do
+      "http://bands/#{represented.moniker}"
+    end
+  end
+
+  class CrewClient < CrewDecorator
+    include Roar::Client
+  end
+
+  before do
+    @crew = Crew.new
+    @client = CrewClient.new(@crew)
+  end    
+
+  describe 'HttpVerbs integration' do
+    describe '#get' do
+      it 'updates instance with incoming representation' do
+        @client.get(uri: 'http://localhost:4567/bands/slayer', as: 'application/json')
+        @crew.moniker.must_equal 'Slayer'
+        @crew.company.must_equal 'Canadian Maple'
+      end
+    end
+
+    describe '#post' do
+      it 'creates a new resource with the given values' do
+        @crew.moniker = 'Strung Out'
+        @crew.company.must_be_nil
+
+        @client.post(uri: 'http://localhost:4567/bands', as: 'application/xml')
+        @crew.moniker.must_equal 'STRUNG OUT'
+        @crew.company.must_be_nil
+      end
+    end
+  end
+
+  describe '#to_hash' do
+    it 'suppresses rendering links' do
+      @crew.moniker = 'Silence'
+      @client.to_json.must_equal %{{\"name\":\"Silence\",\"links\":[]}}
+    end
+    
+    # since this is considered dangerous, we test the mutuable options.
+    it "adds links: false to options" do
+      @client.to_hash(options = {})
+      options.must_equal({:links => false})
+    end
+  end
+end

data/test/json_api_test.rb

@@ -2,394 +2,409 @@ require 'test_helper'
 require 'roar/json/json_api'
 require 'json'
 
-class JSONAPITest < MiniTest::Spec
-  let(:song) {
-    s = OpenStruct.new(
-      bla: "halo",
-      id: "1",
-      title: 'Computadores Fazem Arte',
-      album: OpenStruct.new(id: 9, title: "Hackers"),
-      :album_id => "9",
-      :musician_ids => ["1","2"],
-      :composer_id => "10",
-      :listener_ids => ["8"],
-      musicians: [OpenStruct.new(id: 1, name: "Eddie Van Halen"), OpenStruct.new(id: 2, name: "Greg Howe")]
-    )
-
-  }
-
-  # minimal resource, singular
-  module MinimalSingular
-    include Roar::JSON::JSONAPI
-    type :songs
-
-    property :id
-  end
-
-  class MinimalSingularDecorator < Roar::Decorator
-    include Roar::JSON::JSONAPI
-    type :songs
+require "representable/version"
+if Gem::Version.new(Representable::VERSION) >= Gem::Version.new("2.1.4") # TODO: remove check once we bump representable dependency.
+  class JSONAPITest < MiniTest::Spec
+    let(:song) {
+      s = OpenStruct.new(
+        bla: "halo",
+        id: "1",
+        title: 'Computadores Fazem Arte',
+        album: OpenStruct.new(id: 9, title: "Hackers"),
+        :album_id => "9",
+        :musician_ids => ["1","2"],
+        :composer_id => "10",
+        :listener_ids => ["8"],
+        musicians: [OpenStruct.new(id: 1, name: "Eddie Van Halen"), OpenStruct.new(id: 2, name: "Greg Howe")]
+      )
 
-    property :id
-  end
+    }
 
-  [MinimalSingular, MinimalSingularDecorator].each do |representer|
-    describe "minimal singular with #{representer}" do
-      subject { representer.prepare(song) }
+    # minimal resource, singular
+    module MinimalSingular
+      include Roar::JSON::JSONAPI
+      type :songs
 
-      it { subject.to_json.must_equal "{\"songs\":{\"id\":\"1\"}}" }
-      it { subject.from_json("{\"songs\":{\"id\":\"2\"}}").id.must_equal "2"  }
+      property :id
     end
-  end
-
 
+    class MinimalSingularDecorator < Roar::Decorator
+      include Roar::JSON::JSONAPI
+      type :songs
 
-  module Singular
-    include Roar::JSON::JSONAPI
-    type :songs
+      property :id
+    end
 
-    property :id
-    property :title
+    [MinimalSingular, MinimalSingularDecorator].each do |representer|
+      describe "minimal singular with #{representer}" do
+        subject { representer.prepare(song) }
 
-    # local per-model "id" links
-    links do
-      property :album_id, :as => :album
-      collection :musician_ids, :as => :musicians
+        it { subject.to_json.must_equal "{\"songs\":{\"id\":\"1\"}}" }
+        it { subject.from_json("{\"songs\":{\"id\":\"2\"}}").id.must_equal "2"  }
+      end
     end
-    has_one :composer
-    has_many :listeners
 
+    module Singular
+      include Roar::JSON::JSONAPI
+      type :songs
 
-    # global document links.
-    link "songs.album" do
-      {
-        type: "album",
-        href: "http://example.com/albums/{songs.album}"
-      }
-    end
+      property :id
+      property :title, if: lambda { |args| args[:omit_title] != true }
 
-    compound do
-      property :album do
-        property :title
+      # local per-model "id" links
+      links do
+        property :album_id, :as => :album
+        collection :musician_ids, :as => :musicians
       end
+      has_one :composer
+      has_many :listeners
 
-      collection :musicians do
-        property :name
-      end
-    end
-  end
 
-  class SingularDecorator < Roar::Decorator
-    include Roar::JSON::JSONAPI
-    type :songs
+      # global document links.
+      link "songs.album" do
+        {
+          type: "album",
+          href: "http://example.com/albums/{songs.album}"
+        }
+      end
 
-    property :id
-    property :title
+      compound do
+        property :album do
+          property :title
+        end
 
-    # local per-model "id" links
-    links do
-      property :album_id, :as => :album
-      collection :musician_ids, :as => :musicians
+        collection :musicians do
+          property :name
+        end
+      end
     end
-    has_one :composer
-    has_many :listeners
 
+    class SingularDecorator < Roar::Decorator
+      include Roar::JSON::JSONAPI
+      type :songs
 
-    # global document links.
-    link "songs.album" do
-      {
-        type: "album",
-        href: "http://example.com/albums/{songs.album}"
-      }
-    end
-
-    compound do
-      property :album do
-        property :title
-      end
+      property :id
+      property :title, if: lambda { |args| args[:omit_title] != true }
 
-      collection :musicians do
-        property :name
+      # NOTE: it is important to call has_one, then links, then has_many to assert that they all write
+      #to the same _links property and do NOT override things.
+      has_one :composer
+      # local per-model "id" links
+      links do
+        property :album_id, :as => :album
+        collection :musician_ids, :as => :musicians
       end
-    end
-  end
+      has_many :listeners
 
-  [Singular, SingularDecorator].each do |representer|
-    describe "singular with #{representer}" do
-      subject { song.extend(Singular) }
 
-      let (:document) do
+      # global document links.
+      link "songs.album" do
         {
-          "songs" => {
-            "id" => "1",
-            "title" => "Computadores Fazem Arte",
-            "links" => {
-              "album" => "9",
-              "musicians" => [ "1", "2" ],
-              "composer"=>"10",
-              "listeners"=>["8"]
-            }
-          },
-          "links" => {
-            "songs.album"=> {
-              "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
-            }
-          },
-          "linked" => {
-            "album"=> [{"title"=>"Hackers"}],
-            "musicians"=> [
-              {"name"=>"Eddie Van Halen"},
-              {"name"=>"Greg Howe"}
-            ]
-          }
+          type: "album",
+          href: "http://example.com/albums/{songs.album}"
         }
       end
 
-      # to_hash
-      it do
-        subject.to_hash.must_equal document
-      end
+      compound do
+        property :album do
+          property :title
+        end
 
-      # #to_json
-      it do
-        subject.to_json.must_equal JSON.generate(document)
-      end
-
-      # #from_json
-      it do
-        song = OpenStruct.new.extend(Singular)
-        song.from_json(
-          JSON.generate(
-            {
-              "songs" => {
-                "id" => "1",
-                "title" => "Computadores Fazem Arte",
-                "links" => {
-                  "album" => "9",
-                  "musicians" => [ "1", "2" ],
-                  "composer"=>"10",
-                  "listeners"=>["8"]
-                }
-              },
-              "links" => {
-                "songs.album"=> {
-                  "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
-                }
-              }
-            }
-          )
-        )
-
-        song.id.must_equal "1"
-        song.title.must_equal "Computadores Fazem Arte"
-        song.album_id.must_equal "9"
-        song.musician_ids.must_equal ["1", "2"]
-        song.composer_id.must_equal "10"
-        song.listener_ids.must_equal ["8"]
+        collection :musicians do
+          property :name
+        end
       end
     end
-  end
-
 
-  # collection with links
-  [Singular, SingularDecorator].each do |representer|
-    describe "collection with links and compound" do
-      subject { Singular.for_collection.prepare([song, song]) }
+    [Singular, SingularDecorator].each do |representer|
+      describe "singular with #{representer}" do
+        subject { song.extend(Singular) }
 
-      let (:document) do
-        {
-          "songs" => [
-            {
+        let (:document) do
+          {
+            "songs" => {
               "id" => "1",
               "title" => "Computadores Fazem Arte",
               "links" => {
                 "album" => "9",
                 "musicians" => [ "1", "2" ],
                 "composer"=>"10",
-              "listeners"=>["8"]
+                "listeners"=>["8"]
               }
-            }, {
-              "id" => "1",
-              "title" => "Computadores Fazem Arte",
-              "links" => {
-                "album" => "9",
-                "musicians" => [ "1", "2" ],
-                "composer"=>"10",
-              "listeners"=>["8"]
+            },
+            "links" => {
+              "songs.album"=> {
+                "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
               }
-            }
-          ],
-          "links" => {
-            "songs.album" => {
-              "href" => "http://example.com/albums/{songs.album}",
-              "type" => "album" # DISCUSS: does that have to be albums ?
             },
-          },
-          "linked"=>{
-            "album"    =>[{"title"=>"Hackers"}], # only once!
-            "musicians"=>[{"name"=>"Eddie Van Halen"}, {"name"=>"Greg Howe"}]
+            "linked" => {
+              "album"=> [{"title"=>"Hackers"}],
+              "musicians"=> [
+                {"name"=>"Eddie Van Halen"},
+                {"name"=>"Greg Howe"}
+              ]
+            }
           }
-        }
-      end
+        end
+
+        # to_hash
+        it do
+          subject.to_hash.must_equal document
+        end
+
+        # to_hash(options)
+        it do
+          subject.to_hash(omit_title: true)['songs'].wont_include('title')
+        end
+
+        # #to_json
+        it do
+          subject.to_json.must_equal JSON.generate(document)
+        end
+
+        # #from_json
+        it do
+          song = OpenStruct.new.extend(Singular)
+          song.from_json(
+            JSON.generate(
+              {
+                "songs" => {
+                  "id" => "1",
+                  "title" => "Computadores Fazem Arte",
+                  "links" => {
+                    "album" => "9",
+                    "musicians" => [ "1", "2" ],
+                    "composer"=>"10",
+                    "listeners"=>["8"]
+                  }
+                },
+                "links" => {
+                  "songs.album"=> {
+                    "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
+                  }
+                }
+              }
+            )
+          )
 
-      # to_hash
-      it do
-        subject.to_hash.must_equal document
+          song.id.must_equal "1"
+          song.title.must_equal "Computadores Fazem Arte"
+          song.album_id.must_equal "9"
+          song.musician_ids.must_equal ["1", "2"]
+          song.composer_id.must_equal "10"
+          song.listener_ids.must_equal ["8"]
+        end
       end
-
-      # #to_json
-      it { subject.to_json.must_equal JSON.generate(document) }
     end
 
 
-    # from_json
-    it do
-      song1, song2 = Singular.for_collection.prepare([OpenStruct.new, OpenStruct.new]).from_json(
-        JSON.generate(
+    # collection with links
+    [Singular, SingularDecorator].each do |representer|
+      describe "collection with links and compound with #{representer}" do
+        subject { representer.for_collection.prepare([song, song]) }
+
+        let (:document) do
           {
             "songs" => [
               {
                 "id" => "1",
                 "title" => "Computadores Fazem Arte",
                 "links" => {
+                  "composer"=>"10",
                   "album" => "9",
                   "musicians" => [ "1", "2" ],
-                  "composer"=>"10",
                   "listeners"=>["8"]
-                },
-              },
-              {
-                "id" => "2",
-                "title" => "Talking To Remind Me",
+                }
+              }, {
+                "id" => "1",
+                "title" => "Computadores Fazem Arte",
                 "links" => {
-                  "album" => "1",
-                  "musicians" => [ "3", "4" ],
-                  "composer"=>"2",
-                  "listeners"=>["6"]
+                  "composer"=>"10",
+                  "album" => "9",
+                  "musicians" => [ "1", "2" ],
+                  "listeners"=>["8"]
                 }
-              },
+              }
             ],
             "links" => {
-              "songs.album"=> {
-                "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
-              }
+              "songs.album" => {
+                "href" => "http://example.com/albums/{songs.album}",
+                "type" => "album" # DISCUSS: does that have to be albums ?
+              },
+            },
+            "linked"=>{
+              "album"    =>[{"title"=>"Hackers"}], # only once!
+              "musicians"=>[{"name"=>"Eddie Van Halen"}, {"name"=>"Greg Howe"}]
             }
           }
+        end
+
+        # to_hash
+        it do
+          subject.to_hash.must_equal document
+        end
+
+        # to_hash(options)
+        it do
+          subject.to_hash(omit_title: true)['songs'].each do |song|
+            song.wont_include('title')
+          end
+        end
+
+        # #to_json
+        it { subject.to_json.must_match /linked/ } # hash ordering changes, and i don't care why.
+      end
+
+
+      # from_json
+      it do
+        song1, song2 = Singular.for_collection.prepare([OpenStruct.new, OpenStruct.new]).from_json(
+          JSON.generate(
+            {
+              "songs" => [
+                {
+                  "id" => "1",
+                  "title" => "Computadores Fazem Arte",
+                  "links" => {
+                    "album" => "9",
+                    "musicians" => [ "1", "2" ],
+                    "composer"=>"10",
+                    "listeners"=>["8"]
+                  },
+                },
+                {
+                  "id" => "2",
+                  "title" => "Talking To Remind Me",
+                  "links" => {
+                    "album" => "1",
+                    "musicians" => [ "3", "4" ],
+                    "composer"=>"2",
+                    "listeners"=>["6"]
+                  }
+                },
+              ],
+              "links" => {
+                "songs.album"=> {
+                  "href"=>"http://example.com/albums/{songs.album}", "type"=>"album"
+                }
+              }
+            }
+          )
         )
-      )
 
-      song1.id.must_equal "1"
-      song1.title.must_equal "Computadores Fazem Arte"
-      song1.album_id.must_equal "9"
-      song1.musician_ids.must_equal ["1", "2"]
-      song1.composer_id.must_equal "10"
-      song1.listener_ids.must_equal ["8"]
-
-      song2.id.must_equal "2"
-      song2.title.must_equal "Talking To Remind Me"
-      song2.album_id.must_equal "1"
-      song2.musician_ids.must_equal ["3", "4"]
-      song2.composer_id.must_equal "2"
-      song2.listener_ids.must_equal ["6"]
+        song1.id.must_equal "1"
+        song1.title.must_equal "Computadores Fazem Arte"
+        song1.album_id.must_equal "9"
+        song1.musician_ids.must_equal ["1", "2"]
+        song1.composer_id.must_equal "10"
+        song1.listener_ids.must_equal ["8"]
+
+        song2.id.must_equal "2"
+        song2.title.must_equal "Talking To Remind Me"
+        song2.album_id.must_equal "1"
+        song2.musician_ids.must_equal ["3", "4"]
+        song2.composer_id.must_equal "2"
+        song2.listener_ids.must_equal ["6"]
+      end
     end
-  end
 
 
-  class CollectionWithoutCompound <  self
-    module Representer
-      include Roar::JSON::JSONAPI
-      type :songs
+    class CollectionWithoutCompound <  self
+      module Representer
+        include Roar::JSON::JSONAPI
+        type :songs
 
-      property :id
-      property :title
+        property :id
+        property :title
 
-      # local per-model "id" links
-      links do
-        property :album_id, :as => :album
-        collection :musician_ids, :as => :musicians
-      end
-      has_one :composer
-      has_many :listeners
+        # local per-model "id" links
+        links do
+          property :album_id, :as => :album
+          collection :musician_ids, :as => :musicians
+        end
+        has_one :composer
+        has_many :listeners
 
 
-      # global document links.
-      link "songs.album" do
-        {
-          type: "album",
-          href: "http://example.com/albums/{songs.album}"
-        }
+        # global document links.
+        link "songs.album" do
+          {
+            type: "album",
+            href: "http://example.com/albums/{songs.album}"
+          }
+        end
       end
-    end
 
-    subject { [song, song].extend(Singular.for_collection) }
+      subject { [song, song].extend(Singular.for_collection) }
 
-    # to_json
-    it do
-      subject.extend(Representer.for_collection).to_hash.must_equal(
-        {
-          "songs"=>[{"id"=>"1", "title"=>"Computadores Fazem Arte", "links"=>{"album"=>"9", "musicians"=>["1", "2"], "composer"=>"10", "listeners"=>["8"]}}, {"id"=>"1", "title"=>"Computadores Fazem Arte", "links"=>{"album"=>"9", "musicians"=>["1", "2"], "composer"=>"10", "listeners"=>["8"]}}],
-          "links"=>{"songs.album"=>{"href"=>"http://example.com/albums/{songs.album}", "type"=>"album"}
+      # to_json
+      it do
+        subject.extend(Representer.for_collection).to_hash.must_equal(
+          {
+            "songs"=>[{"id"=>"1", "title"=>"Computadores Fazem Arte", "links"=>{"album"=>"9", "musicians"=>["1", "2"], "composer"=>"10", "listeners"=>["8"]}}, {"id"=>"1", "title"=>"Computadores Fazem Arte", "links"=>{"album"=>"9", "musicians"=>["1", "2"], "composer"=>"10", "listeners"=>["8"]}}],
+            "links"=>{"songs.album"=>{"href"=>"http://example.com/albums/{songs.album}", "type"=>"album"}
+            }
           }
-        }
-      )
+        )
+      end
     end
-  end
 
 
-  class ExplicitMeta < self
-    module Representer
-      include Roar::JSON::JSONAPI
+    class ExplicitMeta < self
+      module Representer
+        include Roar::JSON::JSONAPI
 
-      type :songs
-      property :id
+        type :songs
+        property :id
 
-      meta do
-        property :page
+        meta do
+          property :page
+        end
       end
-    end
 
-    module Page
-      def page
-        2
+      module Page
+        def page
+          2
+        end
       end
-    end
 
-    let (:song) { Struct.new(:id).new(1) }
+      let (:song) { Struct.new(:id).new(1) }
 
-    subject { [song, song].extend(Representer.for_collection).extend(Page) }
+      subject { [song, song].extend(Representer.for_collection).extend(Page) }
 
-    # to_json
-    it do
-      subject.to_hash.must_equal(
-        {
-          "songs"=>[{"id"=>1}, {"id"=>1}],
-          "meta" =>{"page"=>2}
-        }
-      )
+      # to_json
+      it do
+        subject.to_hash.must_equal(
+          {
+            "songs"=>[{"id"=>1}, {"id"=>1}],
+            "meta" =>{"page"=>2}
+          }
+        )
+      end
     end
-  end
 
 
-  class ImplicitMeta < self
-    module Representer
-      include Roar::JSON::JSONAPI
+    class ImplicitMeta < self
+      module Representer
+        include Roar::JSON::JSONAPI
 
-      type :songs
-      property :id
-    end
+        type :songs
+        property :id
+      end
 
-    let (:song) { Struct.new(:id).new(1) }
+      let (:song) { Struct.new(:id).new(1) }
 
-    subject { [song, song].extend(Representer.for_collection) }
+      subject { [song, song].extend(Representer.for_collection) }
 
-    # to_json
-    it do
-      subject.to_hash("meta" => {"page" => 2}).must_equal(
-        {
-          "songs"=>[{"id"=>1}, {"id"=>1}],
-          "meta" =>{"page"=>2}
-        }
-      )
+      # to_json
+      it do
+        subject.to_hash("meta" => {"page" => 2}).must_equal(
+          {
+            "songs"=>[{"id"=>1}, {"id"=>1}],
+            "meta" =>{"page"=>2}
+          }
+        )
+      end
     end
   end
-end
+end