halibut 0.2.0 → 0.3.0

data/Guardfile

@@ -2,9 +2,9 @@
 # More info at https://github.com/guard/guard#readme
 
 guard 'bundler' do
-  watch('Gemfile')
+  # watch('Gemfile')
   # Uncomment next line if Gemfile contain `gemspec' command
-  watch(/^.+\.gemspec/)
+  # watch(/^.+\.gemspec/)
 end
 
 guard 'minitest' do
@@ -21,10 +21,10 @@ guard 'minitest' do
   # Rails 3.2
   # watch(%r|^app/controllers/(.*)\.rb|) { |m| "test/controllers/#{m[1]}_test.rb" }
   # watch(%r|^app/helpers/(.*)\.rb|)     { |m| "test/helpers/#{m[1]}_test.rb" }
-  # watch(%r|^app/models/(.*)\.rb|)      { |m| "test/unit/#{m[1]}_test.rb" }  
-  
+  # watch(%r|^app/models/(.*)\.rb|)      { |m| "test/unit/#{m[1]}_test.rb" }
+
   # Rails
   # watch(%r|^app/controllers/(.*)\.rb|) { |m| "test/functional/#{m[1]}_test.rb" }
   # watch(%r|^app/helpers/(.*)\.rb|)     { |m| "test/helpers/#{m[1]}_test.rb" }
-  # watch(%r|^app/models/(.*)\.rb|)      { |m| "test/unit/#{m[1]}_test.rb" }  
+  # watch(%r|^app/models/(.*)\.rb|)      { |m| "test/unit/#{m[1]}_test.rb" }
 end

data/README.md

@@ -1,4 +1,8 @@
-# Halibut
+# Halibut [![endorse](http://api.coderwall.com/locks/endorsecount.png)](http://coderwall.com/locks)
+
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/locks/halibut)
+[![Build Status](https://secure.travis-ci.org/locks/halibut.png?branch=master)](https://travis-ci.org/locks/halibut)
+[![Dependency Status](https://gemnasium.com/locks/halibut.png)](https://gemnasium.com/locks/halibut)
 
 Halibut is a tiny gem that makes it easier to deal with the [HAL](http://stateless.co/hal_specification.html) format.
 

data/halibut.gemspec

@@ -36,5 +36,4 @@ Gem::Specification.new do |gem|
 
   gem.add_development_dependency "rb-fsevent"
   gem.add_development_dependency "terminal-notifier-guard"
-
 end

data/lib/halibut.rb

@@ -2,8 +2,7 @@ require "halibut/version"
 
 # Halibut is the main namespace
 module Halibut
-  autoload :Builder, 'halibut/builder'
-
+  autoload :Builder,     'halibut/builder'
   autoload :RelationMap, 'halibut/relation_map'
 end
 
@@ -16,6 +15,6 @@ end
 
 # Halibut::HAL contains the domain objects that reflect the HAL specs.
 module Halibut::HAL
-  autoload :Link, 'halibut/hal/link'
+  autoload :Link,     'halibut/hal/link'
   autoload :Resource, 'halibut/hal/resource'
 end

data/lib/halibut/adapter/json.rb

@@ -3,10 +3,6 @@ require 'multi_json'
 module Halibut::Adapter
 
   module JSON
-    def self.extended(base)
-      base.extend InstanceMethods
-    end
-
     def self.load(json)
       ResourceExtractor.new(json).resource
     end
@@ -16,6 +12,10 @@ module Halibut::Adapter
     end
 
     private
+    def self.extended(base)
+      base.extend InstanceMethods
+    end
+
     module InstanceMethods
       def to_json
         MultiJson.dump self.to_hash
@@ -61,7 +61,7 @@ module Halibut::Adapter
       def extract_resources(resources)
         resources.each do |relation,values|
           embeds = ([] << values).flatten
-        
+
           embeds.map  {|embed| MultiJson.dump embed                     }
                 .map  {|embed| Halibut::Adapter::JSON.load embed        }
                 .each {|embed| @halibut.embed_resource(relation, embed) }

data/lib/halibut/adapter/xml.rb

@@ -3,31 +3,34 @@ require 'nokogiri'
 module Halibut::Adapter
 
   module XML
-    def self.extended(base)
-      base.extend InstanceMethods
-    end
-
     def self.load(xml)
       ResourceExtractor.new(xml).resource
     end
 
     def self.dump(resource)
+      raise NotImplementedError
     end
 
     private
+    def self.extended(base)
+      base.extend InstanceMethods
+    end
+
     module InstanceMethods
       def to_xml
+        raise NotImplementedError
       end
     end
 
     class ResourceExtractor
+
+      attr_reader :resource
+
       def initialize(xml)
         xml = Nokogiri::XML(xml)
 
         @document = xml.root
-        @halibut  = Halibut::HAL::Resource.new extract_self_link
-
-        # binding.pry
+        @resource = Halibut::HAL::Resource.new extract_self_link
 
         extract_curie
         extract_properties
@@ -35,10 +38,6 @@ module Halibut::Adapter
         extract_resources
       end
 
-      def resource
-        @halibut
-      end
-
       private
       def extract_self_link
         @document.attr 'href'
@@ -48,7 +47,7 @@ module Halibut::Adapter
         @document.namespace_scopes
                  .reject {|ns| ns.prefix.eql? 'xsi' }
                  .each do |ns|
-          @halibut.add_link 'curie', ns.href, name: ns.prefix
+          @resource.add_link 'curie', ns.href, name: ns.prefix
         end
       end
 
@@ -56,7 +55,7 @@ module Halibut::Adapter
         properties = @document.xpath '/resource/*[not(self::link) and not(self::resource)]'
 
         properties.each do |property|
-          @halibut.set_property property.name, property.content
+          @resource.set_property property.name, property.content
         end
       end
 
@@ -64,25 +63,24 @@ module Halibut::Adapter
         links = @document.xpath('/resource/link')
 
         links.each do |link|
-          @halibut.add_link link.attribute('rel').value,
-                            link.attribute('href').value,
-                            extract_link_options(link)
+          @resource.add_link link['rel'],
+                             link['href'],
+                             extract_link_options(link)
         end
       end
 
       # In case there are no options on the link, it returns an empty hash
       def extract_link_options(link)
-        link.attributes.reject {|k,v| k=='rel' || k=='href' }
-            .map    {|k,v| { k => v.value } }
-            .reduce(:merge) || {}
+        Hash[link.reject {|(key)| key.eql? 'rel'  }
+                 .reject {|(key)| key.eql? 'href' }]
       end
 
       def extract_resources
         @document.xpath('/resource/resource')
                  .map  {|r| [] << r['rel'] << ResourceExtractor.new(r.to_xml).resource }
-                 .each {|rel,res| @halibut.embed_resource rel, res }
+                 .each {|rel,res| @resource.embed_resource rel, res }
       end
     end
   end
 
-end
+end

data/lib/halibut/builder.rb

@@ -4,8 +4,14 @@ module Halibut
 
   # Builder provides a very thin wrapper around creating a HAL resource.
   class Builder
-    attr_accessor :resource
 
+    # The HAL resource built
+    attr_reader :resource
+
+    #
+    #
+    # @param [String] href
+    # @param [Proc]   blk
     def initialize(href=nil, &blk)
       @resource = Halibut::HAL::Resource.new href
 
@@ -21,6 +27,10 @@ module Halibut
     end
 
     private
+
+    # This is the root context of Halibut::Builder.
+    #
+    #
     class RootContext
       extend Forwardable
 
@@ -33,8 +43,23 @@ module Halibut
         instance_eval(&blk) if block_given?
       end
 
+      # Adds a namespace to the resource.
+      #
+      # A namespace is a conceptual abstraction of CURIE links.
+      # Since the client of the library doesn't need to handle CURIE links
+      # directly because they're just for dereferencing link relations, no
+      # CURIE links are presented.
+      #
+      #     resource = Halibut::Builder.new do
+      #       namespace :john, 'http://appleseed.com'
+      #     end.resource
+      #     resource.namespace(:john).href
+      #     # => "http://appleseed.com"
+      #
+      # @param [String,Symbol] name name of the namespace
+      # @param [String]        href URI of the namespace
       def namespace(name, href)
-        @resource.add_link("curie", href, name: name)
+        @resource.add_namespace(name, href)
       end
 
       def resource(rel, href=nil, &blk)
@@ -43,6 +68,23 @@ module Halibut
         @resource.embed_resource(rel, embedded.resource)
       end
 
+      # Adds links or resources to a relation.
+      #
+      # Relation allows the user to specify links, or resources, per relation,
+      # instead of individually.
+      # This feature was introduced as an attempt to reduce repeating the
+      # relation per link/resource, and thus reducing typos.
+      #
+      #     resource = Halibut::Builder.new do
+      #       relation :john do
+      #         link 'http://appleseed.com/john'
+      #       end
+      #     end.resource
+      #     resource.links[:john].first.href
+      #
+      # @param [String,Symbol] rel
+      # @param [Proc]          blk Instructions to be executed in the relation
+      #                            context
       def relation(rel, &blk)
         RelationContext.new(@resource, rel, &blk)
       end
@@ -58,7 +100,6 @@ module Halibut
         instance_eval(&blk) if block_given?
       end
 
-      private
       def link(href, opts={})
         @resource.add_link(@rel, href, opts)
       end
@@ -72,4 +113,4 @@ module Halibut
 
   end
 
-end
+end

data/lib/halibut/hal/link.rb

@@ -5,29 +5,56 @@ module Halibut::HAL
   class Link
     extend Forwardable
 
+    # The URI associated with this link.
     attr_reader :href
 
     def_delegators :@options, :templated, :templated?, :type,
                    :name, :profile, :title, :hreflang
+
     # Returns an instance of a HAL Link object
     #
+    #     # link with no options
+    #     link = Link.new('http://homeopathy.org')
+    #
+    #     # link with name and type options
+    #     link = Link.new('http://homeopathy.org', name: 'Homeopath'
+    #                                            , type: 'text/html')
+    #
+    # If you pass an options that is not one of the reserved link properties
+    # as defined by the spec, they are dropped.
+    # It should possibly raise an error, hafta think about it.
+    #
     # @param [String]  href      URI or URI Template
-    # @param [Boolean] templated true if URI Template or false otherwise
     # @param [Hash]    opts      Options: type, name, profile, title, hreflang
     #
     # @return [Halibut::HAL::Link] HAL Link object
     def initialize(href, opts={})
-      @href = href
+      @href    = href
       @options = Options.new opts
     end
 
-    # Returns the Link as a Hash
+    # Simply returns a hash of the href and the options that are not empty.
+    #
+    #     link = Link.new('/links', name: 'Links')
+    #     link.to_hash
+    #     # => { "href" => "/links", "name" => "links" }
     #
     # @return [Hash] hash from Link Object
     def to_hash
       { 'href' => href }.merge @options
     end
 
+    # Generic comparison method.
+    #
+    # Two objects are the same if they have the same href and the same options.
+    #
+    #     link_one = Link.new('/link', name: 'One', type: 'text/html')
+    #     link_two = Link.new('/link', name: 'One', type: 'text/html')
+    #     link_one == link_two
+    #     # => true
+    #
+    # @param [Link] other Link object to compare to
+    # @return [true,false] return of the comparison of the two objects
     def ==(other)
       @href == other.href && @options == other.options
     end
@@ -36,6 +63,15 @@ module Halibut::HAL
     attr_reader :options
 
     private
+    # Options reifies the various optional properties of a link, as per the
+    # spec.
+    #
+    #     hash = { name: 'John le Carré', templated: true }
+    #     opts = Options.new(hash)
+    #     opts.name    # => John le Carré
+    #     opts['name'] # => John le Carré
+    #     opts[:name]  # => John le Carré
+    #
     class Options
       attr_reader :templated, :type, :name,
                   :profile, :title, :hreflang
@@ -59,23 +95,36 @@ module Halibut::HAL
         @templated || false
       end
 
+      # When converting to a hash, options that weren't set (.nil? == true) are
+      # kept out.
+      #
+      # This might have some implications, as it does not 'serialiaze' options
+      # that were explicitely set to nil. On the other hand, one can argue that
+      # if they were explicitly set to nil, then they shouldn't show up anyway.
       def to_hash
-        instance_variables.each_with_object({}) do |name, output|
-          next if (ivar = instance_variable_get(name)).nil?
+        instance_variables.each_with_object({}) do |ivar, hash|
+          name  = ivar.to_s.reverse.chomp("@").reverse
+          value = instance_variable_get(ivar)
 
-          output[name[1..-1]] = ivar
+          next if value.nil?
+
+          hash[name] = value
         end
       end
 
+      # Straight forward comparison between two Options objects.
+      #
+      #     opts_one = Options.new(name: 'Link', templated: true)
+      #     opts_two = Options.new(name: 'Link', templated: true)
+      #     opts_one == opts_two
+      #     # => true
+      #
+      # @param [Options] other Options object to compare to.
+      # @return [true,false] whether these two objects are equivalent or not.
       def ==(other)
-        templated == other.templated &&
-        type      == other.type      &&
-        name      == other.name      &&
-        profile   == other.profile   &&
-        title     == other.title     &&
-        hreflang  == other.hreflang
+        to_hash == other.to_hash
       end
     end
   end
 
-end
+end

data/lib/halibut/hal/resource.rb

@@ -4,12 +4,38 @@ module Halibut::HAL
   #
   # spec spec spec
   class Resource
-    attr_reader :properties, :links, :embedded
 
-    # TDK
+    # All the properties set in this resource
+    attr_reader :properties
+
+    # A collection of links, grouped by relation
+    attr_reader :links
+
+    # A collection of embedded resources, grouped by relation.
+    attr_reader :embedded
+
+    # A collection of namespaces defined in the document
+    attr_reader :namespace
+
+    # Initialize a new Resource.
+    #
+    # As defined in the spec, the resource SHOULD have a self link, but it
+    # isn't required.
+    # Also optionally, I'm toying with the idea of being able to pass in
+    # properties, links and embedded resources as parameters to this method,
+    # like suggested in https://github.com/locks/halibut/issues/1.
+    #
+    #     # Resource without self link (e.g. POSTing a new resource)
+    #     resource = Halibut::HAL::Resource.new
+    #     resource.set_property :name,   'Halibut Rules'
+    #     resource.set_property :winner, 'Tiger Blood'
+    #
+    #     # Resource with a self link
+    #     resource = Halibut::HAL::Resource.new
     #
     # @param [String] href Link that will be added to the self relation.
-    def initialize(href=nil)
+    def initialize(href=nil, properties={}, links={}, embedded={})
+      @namespaces = Halibut::RelationMap.new
       @links      = Halibut::RelationMap.new
       @embedded   = Halibut::RelationMap.new
       @properties = {}
@@ -17,7 +43,28 @@ module Halibut::HAL
       add_link('self', href) if href
     end
 
-    # TDK
+    # Returns the self link of the resource.
+    #
+    # @return [String,nil] the self link of the resource
+    def href
+      @links.fetch('self', []).map(&:href).first
+    end
+
+    def namespace(name)
+      @links['curie'].select {|ns| ns.name == name }.first
+    end
+    alias_method :ns, :namespace
+
+    def namespaces
+      @links['curie']
+    end
+
+    # Sets a property in the resource.
+    #
+    #     resource = Halibut::HAL::Resource.new
+    #     resource.set_property :name, 'FooBar'
+    #     resource.property :name
+    #     # => "FooBar"
     #
     # @param [Object] property the key
     # @param [Object] value    the value
@@ -27,17 +74,38 @@ module Halibut::HAL
 
     # Returns the value of a property in the resource
     #
+    #     resource = Halibut::HAL::Resource.new
+    #     resource.set_property :name, 'FooBar'
+    #     resource.property :name
+    #     # => "FooBar"
+    #
     # @param [String] property property
-    def get_property property
-      @properties[property]
+    def property(property)
+      @properties.fetch(property, nil)
     end
 
-    # Adds link to relation
+    # Adds a namespace to the resource.
+    #
+    # @param [String] name The name of the namespace
+    # @param [String] href The templated URI of the namespace
+    def add_namespace(name, href)
+      @links.add 'curie', Link.new(href, templated: true, name: name)
+    end
+
+    # Adds link to relation.
+    #
+    #     resource = Halibut::HAL::Resource.new
+    #     resource.add_link 'next', '/resource/2', name: 'Foo'
+    #     link = resource.links['next'].first
+    #     link.href
+    #     # => "/resource/2"
+    #     link.name
+    #     # => "Foo"
     #
     # @param [String]      relation  relation
     # @param [String]      href      href
-    # @param [true, false] templated templated
-    # @param [Hash]        opts      options: name, type, hreflang
+    # @param [Hash]        opts      options: templated, type, name, profile,
+    #                                  title, hreflang
     def add_link(relation, href, opts={})
       @links.add relation, Link.new(href, opts)
     end

data/lib/halibut/relation_map.rb

@@ -6,7 +6,7 @@ module Halibut
   class RelationMap
     extend Forwardable
 
-    def_delegators :@relations, :[], :empty?, :==
+    def_delegators :@relations, :[], :empty?, :==, :fetch
 
     def initialize
       @relations = {}
@@ -14,6 +14,14 @@ module Halibut
 
     # Adds an object to a relation.
     #
+    #     relations = RelationMap.new
+    #     relations.add 'self', Link.new('/resource/1')
+    #     relations['self']
+    #     # => [#<Halibut::HAL::Link:0x007fa0ca5b92b8 @href=\"/resource/1\",
+    #          @options=#<Halibut::HAL::Link::Options:0x007fa0ca5b9240
+    #          @templated=nil, @type=nil, @name=nil, @profile=nil,
+    #          @title=nil, @hreflang=nil>>]
+    #
     # @param [String] relation relation that the object belongs to
     # @param [Object] item     the object to add to the relation
     def add(relation, item)

data/lib/halibut/version.rb

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

data/spec/adapter/xml_spec.rb

@@ -15,7 +15,6 @@ describe Halibut::Adapter::XML do
   end
 
   it "deserializes from XML" do
-    # skip "Test is failing god knows why."
     builder = Halibut::Builder.new 'https://example.com/api/customer/123456' do
       property 'age', "33"
       property 'expired', "false"

data/spec/resource_spec.rb

@@ -1,12 +1,11 @@
 require_relative 'spec_helper'
 
 describe Halibut::HAL::Resource do
+  subject { Halibut::HAL::Resource.new }
   let(:templated_uri) { "http://example.com/{path}{?query}" }
   let(:normal_uri)    { "http://example.com" }
 
   describe "Properties" do
-    subject { Halibut::HAL::Resource.new }
-
     it "set property" do
       subject.set_property "property", "value"
 
@@ -16,7 +15,7 @@ describe Halibut::HAL::Resource do
     it "read property" do
       subject.set_property "property", "value"
 
-      subject.get_property('property').must_equal "value"
+      subject.property('property').must_equal "value"
     end
   end
 
@@ -24,8 +23,8 @@ describe Halibut::HAL::Resource do
 
     describe "self link" do
       it "no default" do
-        resource = Halibut::HAL::Resource.new
-        resource.links.must_be_empty
+        subject.links.must_be_empty
+        subject.href.must_be_nil
       end
 
       it "default" do
@@ -33,9 +32,47 @@ describe Halibut::HAL::Resource do
 
         resource.links.wont_be_empty
         resource.links['self'].first.href.must_equal normal_uri
+        resource.href.must_equal normal_uri
       end
     end
 
+    it "adds link to resource" do
+      subject.links.must_be_empty
+
+      subject.add_link 'lol', normal_uri
+      subject.links['lol'].first.href.must_equal normal_uri
+    end
+
+  end
+
+  describe "Namespaces" do
+    let(:href) { 'http://relations.com/{rel}' }
+
+    it "has a single namespace" do
+      subject.add_namespace 'lol', href
+
+      subject.namespaces.size.must_equal 1
+      subject.namespaces.first.must_equal subject.namespace('lol')
+
+      subject.namespace('lol').must_be :templated?
+      subject.namespace('lol').href.must_equal href
+      subject.namespace('lol').name.must_equal 'lol'
+    end
+
+    it "has multiple namespaces" do
+      subject.add_namespace 'lol', "http://lol.com/{rel}"
+      subject.add_namespace 'lmao', "http://lmao.com/{rel}"
+
+      subject.namespaces.size.must_equal 2
+
+      subject.namespace('lol').must_be :templated?
+      subject.namespace('lol').href.must_equal 'http://lol.com/{rel}'
+      subject.namespace('lol').name.must_equal 'lol'
+
+      subject.namespace('lmao').must_be :templated?
+      subject.namespace('lmao').href.must_equal 'http://lmao.com/{rel}'
+      subject.namespace('lmao').name.must_equal 'lmao'
+    end
   end
 
   describe "Embedded resources" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: halibut
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-27 00:00:00.000000000 Z
+date: 2012-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json