halibut 0.4.1 → 0.5.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MWYxOTQ4OTZiYzU2ZWQyZjk1OTE3NzVmMTA3OTVkMzBhMTQ5NmIyYQ==
+    ZDNlOWE2ZGIyZDI1ZjUzM2UzY2E2NjBhYTIwNGExYTYyNGM5Njk5ZQ==
   data.tar.gz: !binary |-
-    NDYzNzNhZjdkZWYxOTg1NjQzOWEzYWQwM2UzZTk0N2FmOWNhYTc1Zg==
+    ZjViM2MwNzNlNmZlYmQxYzI2ZTQwMTUyM2UwYThmMjI5ZWY1NzlkOA==
 SHA512:
   metadata.gz: !binary |-
-    OTdjNmE0Mzg3MDlmZmJlMzc2ZGI1YzE3ZTc4OGZiMjdmNDc2ZDhhMzUwOTM4
-    ODA4NDhkNGQ1MjlkMjhjNzY3N2MyMzM4YWVmMjdiM2Q1YmY2NGM0MmM3OGYy
-    Y2U1NDNkMjNmOGNkYjBjYmUzYjQxNTI2ZGU2ZWM0MWU4Y2MzY2I=
+    ODI1OGE1NDEyN2RiZDUzYTlhMTQzYmM5ZWIxODdlNTdjNDEzZWU0NDA5NGM0
+    NTI2NjQxMWY4YmRiYmNiOGJhYTY5MDVlMmE3ZDBhMmNiMGQ5NTkxNzI0OWFm
+    MjBkMDY3ZjBhZmVjZDk1NWEyZWMxYmQwM2JlOWMxYTc1NmJlOTE=
   data.tar.gz: !binary |-
-    ZDAxZTlhYjRjNzEyOTM4ODg3ZmJmYzczMGU1YTVhMDBlNmZmNzcwNWYyNzhk
-    NmU4MTJmNWVjYTQzNWE5OTEzMDUzYjNkYzcxODk5ZjM4ZjQ5YTNjMzQyYTZk
-    YzYwOGU2ZjMxOGIzMWJhZWFkZDY5YWVmMGM1NTYwZTk0NmE1OGE=
+    OTFmODkyOWJmM2U5MzA0MDQ0NDBiZmUzZGNmZTY0Y2UwOWIwZWM1NTAwYzVi
+    YjZkMjRjZGM2OGYwNTI0MTJmY2RmOTE0MjFkYTYzNmY4ZDU2MDFhZDk5M2I1
+    Mzc4NTIyM2U3NDE5NTYzMjY3ZmQwYWI5ZDUzNDA0MWY2ZmJjMGI=

data/.gitignore

@@ -23,4 +23,7 @@ doc/
 .DS_Store
 
 # Rubinius
+
+# IntelliJ
+.idea
 .rbx

data/.travis.yml

@@ -6,7 +6,7 @@ rvm:
 - ruby-head
 - jruby-19mode
 - jruby-head
-- rbx-2.1.1
+- rbx-2
 deploy:
   provider: rubygems
   api_key:

data/README.md

@@ -1,4 +1,4 @@
-# Halibut [![endorse](http://api.coderwall.com/locks/endorsecount.png)](http://coderwall.com/locks) [![Stories in Ready](http://badge.waffle.io/locks/halibut.png)](http://waffle.io/locks/halibut)  
+# Halibut [![Stories in Ready](http://badge.waffle.io/locks/halibut.png)](http://waffle.io/locks/halibut) [![Gitter chat](https://badges.gitter.im/locks/halibut.png)](https://gitter.im/locks/halibut)
 
 [![Gem Version](https://badge.fury.io/rb/halibut.png)](http://badge.fury.io/rb/halibut)
 [![Build Status](https://secure.travis-ci.org/locks/halibut.png?branch=master)](https://travis-ci.org/locks/halibut)
@@ -44,13 +44,19 @@ order.set_property "total", 30.00
 order.set_property "currency", "USD"
 order.set_property "status", "shipped"
 
+payment = Halibut::Core::Resource.new "/orders/123/payment"
+payment.set_property "method", "credit"
+payment.set_property "amount", "30.00"
+payment.set_property "auth_code", "ABZ127"
+
 resource = Halibut::Core::Resource.new "/orders"
 resource.add_link "find", "/orders{?id}", templated: true
 resource.add_link "next", "/orders/1", "name" => 'hotdog'
 resource.add_link "next", "/orders/9"
 resource.set_property "currentlyProcessing", 14
 resource.set_property "shippedToday", 20
-resource.embed_resource "orders", order
+resource.embed_resource "payment", payment
+resource.add_embed_resource "orders", order
 ```
 
 ### Halibut::Builder

data/halibut.gemspec

@@ -7,6 +7,7 @@ Gem::Specification.new do |gem|
   gem.description   = %q{Toolkit to work with HAL}
   gem.summary       = %q{A HAL parser and builder for use in Hypermedia APIs}
   gem.homepage      = "http://locks.github.com/halibut"
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/lib/halibut.rb

@@ -10,6 +10,8 @@ require 'halibut/builder'
 module Halibut::Adapter; end
 
 require 'halibut/adapter/json'
+Halibut.extend Halibut::Adapter::JSON::ConvenienceMethods
+
 
 # Halibut::Core contains the domain objects that reflect the HAL specs.
 module Halibut::Core; end

data/lib/halibut/adapter/json.rb

@@ -111,5 +111,11 @@ module Halibut::Adapter
         end
       end
     end
+
+    module ConvenienceMethods
+      def parse_json(json_str_or_io)
+        Halibut::Adapter::JSON.parse(json_str_or_io)
+      end
+    end
   end
 end

data/lib/halibut/builder.rb

@@ -9,10 +9,10 @@ module Halibut
     #
     # @param [String] href
     # @param [Proc]   blk
-    def initialize(href=nil, &blk)
+    def initialize(href=nil, &resource_definition)
       @resource = Halibut::Core::Resource.new href
 
-      RootContext.new(@resource, &blk)
+      RootContext.new(@resource, &resource_definition)
     end
 
     # Returns the resource built.
@@ -28,10 +28,10 @@ module Halibut
     #
     class RootContext
 
-      def initialize(resource, &blk)
+      def initialize(resource, &resource_definition)
         @resource = resource
 
-        instance_eval(&blk) if block_given?
+        instance_eval(&resource_definition) if block_given?
       end
 
       # Sets a property on the resource.
@@ -78,8 +78,8 @@ module Halibut
       # @param [String] rel  Embedded resource relation to the parent resource
       # @param [String] href URI to the resource itself
       # @param [Proc]   blk  Instructions to construct the embedded resource
-      def resource(rel, href=nil, &blk)
-        embedded = Halibut::Builder.new(href, &blk)
+      def resource(rel, href=nil, &embedded_definition)
+        embedded = Halibut::Builder.new(href, &embedded_definition)
 
         @resource.embed_resource(rel, embedded.resource)
       end
@@ -101,26 +101,26 @@ module Halibut
       # @param [String,Symbol] rel
       # @param [Proc]          blk Instructions to be executed in the relation
       #                            context
-      def relation(rel, &blk)
-        RelationContext.new(@resource, rel, &blk)
+      def relation(rel, &relation_definition)
+        RelationContext.new(@resource, rel, &relation_definition)
       end
     end
 
     class RelationContext
 
-      def initialize(resource, rel, &blk)
+      def initialize(resource, rel, &relation_definition)
         @resource = resource
         @rel      = rel
 
-        instance_eval(&blk) if block_given?
+        instance_eval(&relation_definition) if block_given?
       end
 
       def link(href, opts={})
         @resource.tap {|obj| obj.add_link(@rel, href, opts) }
       end
 
-      def resource(href=nil, &blk)
-        embedded = Halibut::Builder.new(href, &blk)
+      def resource(href=nil, &embedded_definition)
+        embedded = Halibut::Builder.new(href, &embedded_definition)
 
         @resource.embed_resource(@rel, embedded.resource)
       end

data/lib/halibut/core/relation_map.rb

@@ -8,8 +8,11 @@ module Halibut::Core
 
     def_delegators :@relations, :[], :empty?, :==, :fetch
 
-    def initialize
+    DEFAULT_OPTIONS = { single_item_arrays: false }
+
+    def initialize(options = {})
       @relations = {}
+      @options = DEFAULT_OPTIONS.merge(options)
     end
 
     # Adds an object to a relation.
@@ -25,6 +28,10 @@ module Halibut::Core
     # @param [String] relation relation that the object belongs to
     # @param [Object] item     the object to add to the relation
     def add(relation, item)
+      unless item.respond_to?(:to_hash)
+        raise ArgumentError.new('only items that can be converted to hashes with #to_hash are permitted')
+      end
+
       @relations[relation] = @relations.fetch(relation, []) << item
     end
 
@@ -37,10 +44,21 @@ module Halibut::Core
     def to_hash
       @relations.each_with_object({}) do |(rel,val), obj|
         rel = rel.to_s
-        val = val.length == 1 ? val.first.to_hash : val.map(&:to_hash)
 
-        obj[rel] = val
+        hashed_val = val.map(&:to_hash)
+        if val.length == 1 && !single_item_arrays?
+          hashed_val = val.first.to_hash
+        end
+
+        obj[rel] = hashed_val
       end
     end
+
+    # Returns true if the relation map is configured to always to
+    # permit single arrays when to_hash is called. The default behavior
+    # is to convert single item arrays into instances
+    def single_item_arrays?
+      @options[:single_item_arrays]
+    end
   end
 end

data/lib/halibut/core/resource.rb

@@ -38,9 +38,10 @@ module Halibut::Core
     #
     # @param [String] href Link that will be added to the self relation.
     def initialize(href=nil, properties={}, links={}, embedded={})
-      @namespaces = RelationMap.new
-      @links      = RelationMap.new
-      @embedded   = RelationMap.new
+      @namespaces      = RelationMap.new
+      @links           = RelationMap.new
+      @embedded        = RelationMap.new
+      @embedded_arrays = RelationMap.new(single_item_arrays: true)
       @properties = {}
 
       add_link('self', href) if href
@@ -123,20 +124,37 @@ module Halibut::Core
 
     # Embeds resource in relation
     #
+    # To embed many resources, call #add_embedded_resource with each item
+    #
     # @param [String]   relation relation
     # @param [Resource] resource resource to embed
     def embed_resource(relation, resource)
+      warn 'Calling Halibut::Core::Resource#embed_resource for populating an array is deprecated. Use Halibut::Core::Resource#add_embeded_resource instead.' if @embedded[relation]
       @embedded.add relation, resource
     end
 
+    # Embeds resource in a relation array
+    #
+    # To embed a single object, see #embed_resource.
+    #
+    # @param [String]   relation relation
+    # @param [Resource] resource resource to embed
+    def add_embedded_resource(relation, resource)
+      @embedded_arrays.add relation, resource
+    end
+
     # Hash representation of the resource.
     # Will ommit links and embedded keys if they're empty
     #
     # @return [Hash] hash representation of the resource
     def to_hash
       {}.merge(@properties).tap do |h|
-        h['_links']    = {}.merge @links    unless @links.empty?
-        h['_embedded'] = {}.merge @embedded unless @embedded.empty?
+        h['_links'] = {}.merge @links    unless @links.empty?
+
+        combined_embedded = {}
+        combined_embedded.merge! @embedded unless @embedded.empty?
+        combined_embedded.merge! @embedded_arrays unless @embedded_arrays.empty?
+        h['_embedded'] = combined_embedded unless combined_embedded.empty?
       end
     end
 

data/lib/halibut/version.rb

@@ -1,4 +1,4 @@
 module Halibut
   # Semver version (I'll try, pinkie promise)
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/spec/adapter/json_spec.rb

@@ -16,6 +16,27 @@ describe Halibut::Adapter::JSON do
     MultiJson.load(subject).must_equal MultiJson.load(json)
   end
 
+  it "serializes to JSON with links and embedded resources" do
+    json = load_json "serialize"
+
+    order = Halibut::Core::Resource.new "/orders/123"
+    order.set_property "total", 30.00
+    order.set_property "currency", "USD"
+    order.set_property "status", "shipped"
+
+    resource = Halibut::Core::Resource.new "/orders"
+    resource.add_link "find", "/orders{?id}", templated: true
+    resource.add_link "next", "/orders/1", "name" => 'hotdog'
+    resource.add_link "next", "/orders/9"
+    resource.set_property "currentlyProcessing", 14
+    resource.set_property "shippedToday", 20
+    resource.add_embedded_resource "orders", order
+
+    subject = Halibut::Adapter::JSON.dump resource
+
+    MultiJson.load(subject).must_equal MultiJson.load(json)
+  end
+
   it "deserializes from JSON" do
     subject = Halibut::Adapter::JSON.parse(load_json "serialize")
 

data/spec/builder_spec.rb

@@ -1,6 +1,4 @@
 require_relative 'spec_helper'
-
-
 require 'hash'
 
 describe Halibut::Builder do

data/spec/core/relation_map_spec.rb

@@ -9,22 +9,72 @@ describe Halibut::Core::RelationMap do
     subject.must_be_empty
   end
 
-  it "has a single item per relation" do
-    subject.add 'first' , 'first'
-    subject.add 'second', 'second'
+  describe '#add' do
+    it "has a single item per relation" do
+      subject.add 'first' , { value: 'first' }
+      subject.add 'second', { value: 'second' }
 
-    subject['first'].first.must_equal  'first'
-    subject['second'].last.must_equal  'second'
+      subject['first'].first[:value].must_equal 'first'
+      subject['second'].last[:value].must_equal 'second'
 
-  end
+    end
+
+    it "has various items per relation" do
+      subject.add 'first', { value: 'first' }
+      subject.add 'first', { value: 'second' }
 
-  it "has various items per relation" do
-    subject.add 'first', 'first'
-    subject.add 'first', 'second'
+      subject['first'].length.must_equal  2
+      subject['first'].first[:value].must_equal 'first'
+      subject['first'].last[:value].must_equal  'second'
+    end
 
-    subject['first'].length.must_equal  2
-    subject['first'].first.must_equal 'first'
-    subject['first'].last.must_equal  'second'
+    # todo: throw an exception if add receives a value that does not respond to to_hash
+    it 'throws an exception if item does not respond to #to_hash' do
+      assert_raises(ArgumentError) do
+        subject.add 'first', 'not-hashable'
+      end
+    end
   end
 
-end
+  describe '#to_hash' do
+    describe 'when single item arrays become objects' do
+      it 'generates single item relations correctly' do
+        subject.add('person', { name: 'bob' })
+
+        subject.to_hash['person'][:name].must_equal 'bob'
+      end
+
+      it 'generates multi item relations correctly' do
+        subject.add('person', { name: 'bob' })
+        subject.add('person', { name: 'floyd' })
+
+        hashed_people = subject.to_hash['person']
+        hashed_people.length.must_equal 2
+        hashed_people[0][:name].must_equal 'bob'
+        hashed_people[1][:name].must_equal 'floyd'
+      end
+    end
+
+    describe 'when single item arrays stay arrays' do
+      subject { Halibut::Core::RelationMap.new(single_item_arrays: true) }
+
+      it 'generates single item relations correctly' do
+        subject.add('person', { name: 'bob' })
+
+        hashed_people = subject.to_hash['person']
+        hashed_people.length.must_equal 1
+        hashed_people[0][:name].must_equal 'bob'
+      end
+
+      it 'generates multi item relations correctly' do
+        subject.add('person', { name: 'bob' })
+        subject.add('person', { name: 'floyd' })
+
+        hashed_people = subject.to_hash['person']
+        hashed_people.length.must_equal 2
+        hashed_people[0][:name].must_equal 'bob'
+        hashed_people[1][:name].must_equal 'floyd'
+      end
+    end
+  end
+end

data/spec/core/resource_spec.rb

@@ -88,15 +88,50 @@ describe Halibut::Core::Resource do
     let(:res2) { Halibut::Core::Resource.new "http://secnd-resource.com" }
 
     it "no embedded resource" do
-      subject.embedded.must_be_empty
+      subject.to_hash['_embedded'].must_be_nil
     end
 
     it "has embedded resource" do
-      subject.embed_resource 'users', res1
-      subject.embed_resource 'users', res2
+      subject.embed_resource 'user', res1
+
+      subject.to_hash['_embedded']['user'].must_equal res1.to_hash
+    end
+
+    it "deprecates calling embed_resource twice for the same relation" do
+      subject.embed_resource 'user', res1
+
+      # this call intentionally generates a deprecation warning
+      subject.embed_resource 'user', res2
+
+      subject.to_hash['_embedded']['user'].length.must_equal 2
+      subject.to_hash['_embedded']['user'].first.must_equal res1.to_hash
+      subject.to_hash['_embedded']['user'].last.must_equal res2.to_hash
+    end
+  end
+
+  describe "Embedded arrays" do
+    subject { Halibut::Core::Resource.new }
+    let(:res1) { Halibut::Core::Resource.new "http://first-resource.com" }
+    let(:res2) { Halibut::Core::Resource.new "http://secnd-resource.com" }
+
+    it "has no embedded arrays" do
+      subject.embedded.must_be_empty
+    end
+
+    it "has a resource embedded into an array" do
+      subject.add_embedded_resource 'users', res1
+
+      subject.to_hash['_embedded']['users'].length.must_equal 1
+      subject.to_hash['_embedded']['users'].first.must_equal res1.to_hash
+    end
+
+    it "has multiple resources embedded into an array" do
+      subject.add_embedded_resource 'users', res1
+      subject.add_embedded_resource 'users', res2
 
-      subject.embedded['users'].first.must_equal res1
-      subject.embedded['users'].last.must_equal  res2
+      subject.to_hash['_embedded']['users'].length.must_equal 2
+      subject.to_hash['_embedded']['users'].first.must_equal res1.to_hash
+      subject.to_hash['_embedded']['users'].last.must_equal res2.to_hash
     end
   end
 

data/spec/halibut_spec.rb

@@ -0,0 +1,25 @@
+require_relative 'spec_helper'
+
+describe Halibut do 
+  describe ".parse_json" do
+    describe "(valid_hal_json_str)" do 
+      it "returns a Resource" do 
+        Halibut.parse_json("{}").must_be_kind_of Halibut::Core::Resource 
+      end
+    end
+
+    describe "(valid_hal_json_io)" do
+      it "returns a Resource" do 
+        Halibut.parse_json(StringIO.new("{}")).must_be_kind_of Halibut::Core::Resource 
+      end
+    end
+
+    describe "(invalid_json)" do
+      it "raises exception" do 
+        proc { Halibut.parse_json StringIO.new("wat") }.must_raise MultiJson::LoadError
+      end
+    end
+
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: halibut
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Ricardo Mendes
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-17 00:00:00.000000000 Z
+date: 2014-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -102,10 +102,12 @@ files:
 - spec/fixtures/minimal.json
 - spec/fixtures/serialize.json
 - spec/fixtures/simple.json
+- spec/halibut_spec.rb
 - spec/link_relation_spec.rb
 - spec/spec_helper.rb
 homepage: http://locks.github.com/halibut
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -123,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A HAL parser and builder for use in Hypermedia APIs
@@ -138,5 +140,6 @@ test_files:
 - spec/fixtures/minimal.json
 - spec/fixtures/serialize.json
 - spec/fixtures/simple.json
+- spec/halibut_spec.rb
 - spec/link_relation_spec.rb
 - spec/spec_helper.rb