hal-client 2.3.1 → 2.4.0

data/hal-client.gemspec

@@ -18,12 +18,13 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rest-client", "~> 1.6", '>= 1.6.0'
-  spec.add_dependency "addressable", "~> 2.3", '>= 2.3.0'
-  spec.add_dependency "multi_json", "~> 1.9", '>= 1.9.0'
+  spec.add_dependency "rest-client", "~> 1.6"
+  spec.add_dependency "addressable", "~> 2.3"
+  spec.add_dependency "multi_json", "~> 1.9"
 
   spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake", "~> 10.1", '>= 10.1.0'
-  spec.add_development_dependency "rspec", "~> 2.14", '>= 2.14.0'
-  spec.add_development_dependency "webmock", "~> 1.16", '>= 1.16.0'
+  spec.add_development_dependency "rake", "~> 10.1"
+  spec.add_development_dependency "rspec", "~> 3.0.0.beta"
+  spec.add_development_dependency "webmock", "~> 1.16"
+  spec.add_development_dependency "rspec-collection_matchers"
 end

data/lib/hal_client/collection.rb

@@ -52,6 +52,15 @@ class HalClient
       end
     end
 
+    # Returns one or more randomly selected item from the first page
+    # of the collection.
+    #
+    # count - number of items to return. If specified return type will
+    #   an collection. Default: return a single item
+    def sample(*arg)
+      first_page.related("item").sample(*arg)
+    end
+
     protected
 
     attr_reader :first_page

data/lib/hal_client/links_section.rb

@@ -0,0 +1,67 @@
+class HalClient
+
+  # Encapsulates a "_links" section.
+  class LinksSection
+    UNSET = Object.new
+
+    def initialize(section, namespaces=nil)
+      @namespaces = namespaces || CurieResolver.new(section.fetch("curies"){[]})
+
+      @section = fully_qualified section
+    end
+
+    attr_reader :namespaces
+
+    # Returns the URLs or URL templates of each link with the
+    # specified rel in this section.
+    #
+    # link_rel - The fully qualified link relation
+    # default_proc - (optional) A proc to execute to create a
+    #   default value if the specified link_rel does not exist
+    #
+    # Yields the link_rel to the default_proc if the specified
+    # link_rel is not present and returns the return value of the
+    # default_proc.
+    #
+    # Raises KeyError if the specified link_rel is not present and no
+    # default_value or default_proc are provided.
+    def hrefs(link_rel, &default_proc)
+      default_proc ||= ->(link_rel){
+        raise KeyError, "No resources are related via `#{link_rel}`"
+      }
+
+      return default_proc.call(link_rel) unless section.key? link_rel
+
+      [section.fetch(link_rel)]
+        .flatten
+        .map{|link| resolve_to_url(link)}
+    end
+
+    protected
+
+    attr_reader :section
+
+    def resolve_to_url(link)
+      (fail HalClient::InvalidRepresentationError) unless link.respond_to? :fetch
+
+      url = link.fetch("href")
+      is_templated = link.fetch("templated", false)
+
+      if is_templated
+        Addressable::Template.new(url)
+      else
+        url
+      end
+
+    rescue KeyError
+      fail HalClient::InvalidRepresentationError
+    end
+    
+    def fully_qualified(relations_section)
+      Hash[relations_section.map {|rel, link_info|
+        [(namespaces.resolve rel), link_info]
+      }]
+    end
+
+  end
+end

data/lib/hal_client/representation.rb

@@ -1,3 +1,4 @@
+require 'forwardable'
 require 'addressable/template'
 
 require 'hal_client'
@@ -8,6 +9,7 @@ class HalClient
   # HAL representation of a single resource. Provides access to
   # properties, links and embedded representations.
   class Representation
+    extend Forwardable
 
     # Create a new Representation
     #
@@ -65,7 +67,7 @@ class HalClient
 
     # Returns the URL of the resource this representation represents.
     def href
-      @href ||= link_section.fetch("self").fetch("href")
+      @href ||= links.hrefs('self').first
     end
 
     # Returns the value of the specified property or representations
@@ -129,14 +131,11 @@ class HalClient
         raise KeyError, "No resources are related via `#{link_rel}`"
       }
 
-      embedded = embedded_or_nil(link_rel)
-      linked = linked_or_nil(link_rel, options)
+      embedded = embedded(link_rel) { nil }
+      linked = linked(link_rel, options) { nil }
+      return default_proc.call(link_rel) if embedded.nil? and linked.nil?
 
-      if !embedded.nil? or !linked.nil?
-        RepresentationSet.new (Array(embedded) + Array(linked))
-      else
-        default_proc.call link_rel
-      end
+      RepresentationSet.new (Array(embedded) + Array(linked))
     end
 
     # Returns urls of resources related via the specified
@@ -156,6 +155,32 @@ class HalClient
         map(&:href)
     end
 
+    # Returns values of the `href` member of links and the URL of
+    # embedded representations related via the specified link rel. The
+    # only difference between this and `#related_hrefs` is that this
+    # method makes no attempt to expand templated links. For templated
+    # links the returned collection will include the template pattern
+    # as encoded in the HAL document.
+    #
+    # link_rel - The link rel of interest
+    # default_proc - an option proc that will be called with `name`
+    #  to produce default value if the specified property or link does not
+    #  exist
+    #
+    # Raises KeyError if the specified link does not exist
+    #   and no default_proc is provided.
+    def raw_related_hrefs(link_rel, &default_proc)
+      default_proc ||= ->(link_rel){
+        raise KeyError, "No resources are related via `#{link_rel}`"
+      }
+
+      embedded = embedded(link_rel) { nil }
+      linked = links.hrefs(link_rel) { nil }
+      return default_proc.call(link_rel) if embedded.nil? and linked.nil?
+
+      Array(linked) + Array(embedded).map(&:href)
+    end
+
     # Returns a short human readable description of this
     # representation.
     def to_s
@@ -181,36 +206,44 @@ class HalClient
       @raw
     end
 
-    def link_section
-      @link_section ||= fully_qualified raw.fetch("_links", {})
+    def links
+      @links ||= LinksSection.new raw.fetch("_links"){{}}
     end
 
     def embedded_section
       @embedded_section ||= fully_qualified raw.fetch("_embedded", {})
     end
 
-    def embedded(link_rel)
-      relations = boxed embedded_section.fetch(link_rel)
+    def embedded(link_rel, &default_proc)
+      default_proc ||= ->(link_rel) {
+        fail KeyError, "#{link_rel} embed not found"
+      }
+
+      relations = embedded_section.fetch(link_rel) { MISSING }
+      return default_proc.call(link_rel) if relations == MISSING
 
-      relations.map{|it| Representation.new hal_client: hal_client, parsed_json: it}
+      (boxed relations).map{|it| Representation.new hal_client: hal_client, parsed_json: it}
 
     rescue InvalidRepresentationError => err
       fail InvalidRepresentationError, "/_embedded/#{jpointer_esc(link_rel)} is not a valid representation"
 end
 
-    def embedded_or_nil(link_rel)
-      embedded link_rel
-
-    rescue KeyError
-      nil
-    end
+    def linked(link_rel, options, &default_proc)
+      default_proc ||= ->(link_rel,_options) {
+        fail KeyError, "#{link_rel} link not found"
+      }
 
-    def linked(link_rel, options)
-      relations = boxed link_section.fetch(link_rel)
+      relations = links.hrefs(link_rel) { MISSING }
+      return default_proc.call(link_rel, options) if relations == MISSING
 
-      relations.
-        map {|link| href_from link, options }.
-        map {|href| Representation.new href: href, hal_client: hal_client }
+      relations
+        .map {|url_or_tmpl|
+          if url_or_tmpl.respond_to? :expand
+            url_or_tmpl.expand(options).to_s
+          else
+            url_or_tmpl
+          end }
+        .map {|href| Representation.new href: href, hal_client: hal_client }
 
     rescue InvalidRepresentationError => err
       fail InvalidRepresentationError, "/_links/#{jpointer_esc(link_rel)} is not a valid link"
@@ -220,14 +253,6 @@ end
       str.gsub "/", "~1"
     end
 
-    def linked_or_nil(link_rel, options)
-      linked link_rel, options
-
-    rescue KeyError
-      nil
-    end
-
-
     def boxed(list_hash_or_nil)
       if hashish? list_hash_or_nil
         [list_hash_or_nil]
@@ -241,29 +266,17 @@ end
       end
     end
 
-    def href_from(link, options)
-      raw_href = link.fetch('href')
-
-      if link.fetch('templated', false)
-        Addressable::Template.new(raw_href).expand(options).to_s
-      else
-        raw_href
-      end
-    end
-
     def fully_qualified(relations_section)
       Hash[relations_section.map {|rel, link_info|
         [(namespaces.resolve rel), link_info]
       }]
     end
 
-    def namespaces
-      @namespaces ||= CurieResolver.new raw.fetch("_links", {}).fetch("curies", [])
-    end
-
     def hashish?(thing)
       thing.respond_to?(:fetch) && thing.respond_to?(:key?)
     end
 
+    def_delegators :links, :namespaces
+
   end
 end

data/lib/hal_client/version.rb

@@ -1,3 +1,3 @@
 class HalClient
-  VERSION = "2.3.1"
+  VERSION = "2.4.0"
 end

data/lib/hal_client.rb

@@ -7,6 +7,7 @@ class HalClient
   autoload :Representation, 'hal_client/representation'
   autoload :RepresentationSet, 'hal_client/representation_set'
   autoload :CurieResolver, 'hal_client/curie_resolver'
+  autoload :LinksSection, 'hal_client/links_section'
   autoload :Collection, 'hal_client/collection'
   autoload :InvalidRepresentationError, 'hal_client/errors'
   autoload :NotACollectionError, 'hal_client/errors'

data/spec/hal_client/links_section_spec.rb

@@ -0,0 +1,56 @@
+require "spec_helper"
+require 'hal-client'
+
+describe HalClient::LinksSection, "namespaces embedded" do
+  subject(:section) { described_class.new(raw_section) }
+
+  specify { expect(section.hrefs("up"))
+    .to contain_exactly "http://example.com/parent" }
+
+  specify { expect(section.hrefs(fully_qualified_first_rel))
+    .to contain_exactly "http://example.com/foo" }
+
+  specify { expect(section.hrefs(fully_qualified_second_rel))
+    .to contain_exactly "http://example.com/bar", "http://example.com/baz" }
+
+  specify { expect(section.hrefs("search"))
+      .to all match respond_to(:pattern).and respond_to(:expand) }
+  specify { expect(section.hrefs("search").first.pattern).to eq "http://example.com/s{?q}" }
+
+  specify { expect{section.hrefs("nonexistent")}.to raise_error KeyError }
+
+  let(:fully_qualified_first_rel) { "http://rels.example.com/first" }
+  let(:fully_qualified_second_rel) { "http://rels.example.com/2/second" }
+
+  let(:raw_section) {
+    { "curies" => [{ "name" => "ns1",
+                     "href" => "http://rels.example.com/{rel}",
+                     "templated" => true},
+                   { "name" => "ns2",
+                     "href" => "http://rels.example.com/2/{rel}",
+                     "templated" => true}],
+      "up" => {"href" => "http://example.com/parent"},
+      "search" => {"href" => "http://example.com/s{?q}", "templated" => true },
+      "ns1:first" => {"href" => "http://example.com/foo"},
+      "ns2:second" => [{"href" => "http://example.com/bar"},
+                       {"href" => "http://example.com/baz"}]
+    } }
+
+  matcher :all do |expected|
+    match do |actual|
+      actual.all?{|it| expected === it}
+    end
+  end
+end
+
+describe HalClient::LinksSection, "invalid" do
+  subject(:section) { described_class.new(raw_section) }
+
+  specify { expect{section.hrefs("bareurl")}
+      .to raise_error HalClient::InvalidRepresentationError }
+
+  let(:raw_section) {
+    { "bareurl" => "http://example.com/boom" }
+  }
+
+end

data/spec/hal_client/representation_set_spec.rb

@@ -21,16 +21,20 @@ describe HalClient::RepresentationSet do
     end
   end
 
-  its(:count) { should eq 2 }
-  its(:empty?) { should be_false }
+  specify { expect(repr_set.count).to eq 2 }
+  specify { expect(repr_set.empty?).to be false }
 
   describe "#any?" do
-    it "returns true if there are any" do
-      expect(subject.any?{|it| it == foo_repr }).to be_true
+    it "returns true if there are any matching" do
+      expect(subject.any?{|it| it == foo_repr }).to be true
     end
 
-    it "returns false if there aren't any" do
-      expect(subject.any?{|it| false }).to be_false
+    it "returns true if there are any matchin" do
+      expect(subject.any?).to be true
+    end
+
+    it "returns false if there aren't any matching" do
+      expect(subject.any?{|it| false }).to be false
     end
   end
 
@@ -126,7 +130,7 @@ describe HalClient::RepresentationSet do
     match { |repr_set|
       repr_set.any?{|it| it.href == url}
     }
-    failure_message_for_should { |repr_set|
+    failure_message { |repr_set|
       "Expected representation of <#{url}> but found only #{repr_set.map(&:href)}"
     }
   end

data/spec/hal_client/representation_spec.rb

@@ -8,7 +8,7 @@ describe HalClient::Representation do
   ,"_links": {
     "self": { "href": "http://example.com/foo" }
     ,"link1": { "href": "http://example.com/bar" }
-    ,"link2": { "href": "http://example.com/people{?name}"
+    ,"templated_link": { "href": "http://example.com/people{?name}"
                 ,"templated": true }
     ,"link3": [{ "href": "http://example.com/link3-a" }
                ,{ "href": "http://example.com/link3-b" }]
@@ -32,18 +32,17 @@ HAL
       repr.related("link1").post("abc")
     end
 
-    specify {
-      expect(
-        post_request.
-        with(:body => "abc", :headers => {'Content-Type' => 'application/hal+json'})
-      ).to have_been_made
+    specify("makes request") {
+      expect(post_request.with(:body => "abc",
+                                :headers => {'Content-Type' => 'application/hal+json'}))
+        .to have_been_made
     }
   end
 
   describe "#to_s" do
     subject(:return_val) { repr.to_s }
 
-    it { should eq "#<HalClient::Representation: http://example.com/foo>" }
+    it { is_expected.to eq "#<HalClient::Representation: http://example.com/foo>" }
   end
 
   specify { expect(repr.property "prop1").to eq 1 }
@@ -55,7 +54,7 @@ HAL
   specify { expect(repr.has_property? "nonexistent-prop").to be false }
 
 
-  its(:href) { should eq "http://example.com/foo" }
+  specify { expect(subject.href).to eq "http://example.com/foo" }
 
   describe "#fetch" do
     context "for existent property" do
@@ -135,7 +134,7 @@ HAL
     end
 
     context "for existent templated link" do
-      subject { repr.related "link2", name: "bob" }
+      subject { repr.related "templated_link", name: "bob" }
       it { should have(1).item }
       it { should include_representation_of "http://example.com/people?name=bob"  }
     end
@@ -153,25 +152,16 @@ HAL
     end
   end
 
-  describe "#related_hrefs" do
-    context "for existent link" do
-      subject { repr.related_hrefs "link1" }
-      it { should have(1).item }
-      it { should include "http://example.com/bar" }
-    end
+  specify { expect(repr.related_hrefs "link1")
+      .to contain_exactly "http://example.com/bar" }
+  specify { expect(repr.related_hrefs "embed1")
+      .to contain_exactly "http://example.com/baz" }
+  specify { expect { repr.related_hrefs 'wat' }.to raise_exception KeyError }
 
-    context "for existent embedded" do
-      subject { repr.related_hrefs "embed1" }
-      it { should have(1).item }
-      it { should include "http://example.com/baz" }
-    end
-
-    context "non-existent item w/o default" do
-      it "raises exception" do
-        expect{repr.related_hrefs 'wat'}.to raise_exception KeyError
-      end
-    end
-  end
+  specify { expect(repr.raw_related_hrefs("templated_link").map(&:pattern))
+      .to contain_exactly "http://example.com/people{?name}" }
+  specify { expect(repr.raw_related_hrefs("link1"))
+      .to contain_exactly "http://example.com/bar" }
 
   specify { expect(subject.has_related? "link1").to be true }
   specify { expect(subject.related? "link1").to be true }
@@ -193,17 +183,17 @@ HAL
 }
 HAL
 
-    describe "#related return value " do
+    describe "#related return value" do
       subject(:return_val) { repr.related("http://example.com/rels/bar") }
       it { should include_representation_of "http://example.com/bar" }
     end
 
-    describe "#[] return value " do
+    describe "#[] return value" do
       subject(:return_val) { repr["http://example.com/rels/bar"] }
       it { should include_representation_of "http://example.com/bar" }
     end
 
-    describe "#related_hrefs return value " do
+    describe "#related_hrefs return value" do
       subject(:return_val) { repr.related_hrefs("http://example.com/rels/bar") }
       it { should include "http://example.com/bar" }
     end
@@ -276,7 +266,7 @@ HAL
     match { |repr_set|
       repr_set.any?{|it| it.href == url}
     }
-    failure_message_for_should { |repr_set|
+    failure_message { |repr_set|
       "Expected representation of <#{url}> but found only #{repr_set.map(&:href)}"
     }
   end

data/spec/spec_helper.rb

@@ -3,3 +3,4 @@ $LOAD_PATH << Pathname(__FILE__).dirname + "../lib"
 require 'rspec'
 require 'webmock/rspec'
 require 'multi_json'
+require 'rspec/collection_matchers'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hal-client
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-21 00:00:00.000000000 Z
+date: 2014-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -19,9 +19,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.6'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 1.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -30,9 +27,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.6'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 1.6.0
 - !ruby/object:Gem::Dependency
   name: addressable
   requirement: !ruby/object:Gem::Requirement
@@ -41,9 +35,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.3'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -52,9 +43,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.3'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: multi_json
   requirement: !ruby/object:Gem::Requirement
@@ -63,9 +51,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.9'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 1.9.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -74,9 +59,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.9'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 1.9.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -101,9 +83,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '10.1'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 10.1.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -112,9 +91,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '10.1'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 10.1.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,10 +98,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.14'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.14.0
+        version: 3.0.0.beta
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -133,10 +106,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.14'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.14.0
+        version: 3.0.0.beta
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -145,9 +115,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.16'
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 1.16.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -156,9 +123,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rspec-collection_matchers
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: 1.16.0
+        version: '0'
 description: An easy to use interface for REST APIs that use HAL.
 email:
 - pezra@barelyenough.org
@@ -178,11 +158,13 @@ files:
 - lib/hal_client/collection.rb
 - lib/hal_client/curie_resolver.rb
 - lib/hal_client/errors.rb
+- lib/hal_client/links_section.rb
 - lib/hal_client/representation.rb
 - lib/hal_client/representation_set.rb
 - lib/hal_client/version.rb
 - spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
+- spec/hal_client/links_section_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb
 - spec/hal_client_spec.rb
@@ -202,7 +184,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1374848680285234334
+      hash: -1767932783931261453
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -211,7 +193,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1374848680285234334
+      hash: -1767932783931261453
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -221,6 +203,7 @@ summary: Use HAL APIs easily
 test_files:
 - spec/hal_client/collection_spec.rb
 - spec/hal_client/curie_resolver_spec.rb
+- spec/hal_client/links_section_spec.rb
 - spec/hal_client/representation_set_spec.rb
 - spec/hal_client/representation_spec.rb
 - spec/hal_client_spec.rb