halibut 0.1.0 → 0.2.0

data/.gitignore

@@ -20,4 +20,7 @@ _yardoc
 doc/
 
 # OS X artifacts
-.DS_Store
+.DS_Store
+
+# Rubinius
+.rbx

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "spec/test-resources"]
+	path = spec/test-resources
+	url = https://github.com/HalBuilder/halbuilder-test-resources.git

data/.travis.yml

@@ -1,11 +1,11 @@
+language: ruby
+gemfile: Gemfile.travis
+bundler_args: --without development
 rvm:
-  - ree
-  - 1.8.7
   - 1.9.2
   - 1.9.3
   - ruby-head
-  - jruby-18mode
   - jruby-19mode
   - jruby-head
-  - rbx-18mode
   - rbx-19mode
+

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source :rubygems
 
 # Specify your gem's dependencies in halibut.gemspec
-gemspec
+gemspec

data/Gemfile.travis

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in halibut.gemspec
+gemspec
+
+group :travis do
+  gem "rake"
+  gem "minitest"
+
+  gem "hash-differ"
+end

data/README.md

@@ -1,6 +1,13 @@
 # Halibut
 
-TODO: Write a gem description
+Halibut is a tiny gem that makes it easier to deal with the [HAL](http://stateless.co/hal_specification.html) format.
+
+In providing tools to build, (de)serialize, and manipulate HAL resources,
+Halibut has the following goals:
+
+- Provide Ruby abstractions
+- Clean, small API
+- Easily composable, for use in other libraries
 
 ## Installation
 
@@ -18,56 +25,98 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+There are three ways to get a resource with halibut: manual, Builder, and JSON.
 
-## RDD
+### Manual
 
 ```ruby
-# Namespaces
-Halibut::JSON
-Halibut::XML
-Halibut::HAL
-
-Halibut::JSON::Document
-Halibut::JSON::Builder
+require 'halibut'
+
+# manually creating a resource
+order = Halibut::HAL::Resource.new "/orders/123"
+order.set_property "total", 30.00
+order.set_property "currency", "USD"
+order.set_property "status", "shipped"
+
+resource = Halibut::HAL::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
+```
 
-Halibut::XML::Document
-Halibut::XML::Builder
+### Halibut::Builder
+```ruby
+require 'halibut/builder'
 
-Halibut::HAL::Document
-Halibut::HAL::Document::LinkSet
-Halibut::HAL::Document::ResourceSet
-Halibut::HAL::Document::AttributeSet (?)
-Halibut::HAL::Link
-Halibut::HAL::Resource
+builder = Halibut::Builder.new '/orders' do
+    property 'currentlyProcessing', 14
+    property 'shippedToday', 20
+    
+    namespace 'th', 'http://things-db.com/{rel}'
+    
+    link 'find', '/orders{?id}', templated: true
+    link 'next', '/orders/1', name: 'hotdog'
+    link 'next', '/orders/9'
+    
+    link 'th:manufacturer', '/manufacturer/1'
+    link 'th:manufacturer', '/manufacturer/2'
+    link 'th:manufacturer', '/manufacturer/3'
+end
 
-hal = Halibut::XML::Builder.new "/api/news" do |it|
-    it.attr "some_attribute", "The Value of the Attribute"
-    it.attr "another_attribute", "The Value of Another Attribute"
+# alternatively
 
-    it.link "search", "/api/news{?search}", :templated => true
+builder = Halibut::Builder.new '/orders' do
+    property 'currentlyProcessing', 14
+    property 'shippedToday', 20
+    
+    namespace 'th', 'http://things-db.com/{rel}'
     
-    it.resource "relation", "/href/etc" do |r|
-        r.attr "again", "this"
-        r.attr "this",  "again"
-        
-        r.link "search", "/href/etc?search={term}", :templated => true, :title => "Embedded Resource"
+    link 'find', '/orderes{?id}', templated: true
+    relation 'next' do
+        link '/orders/1', name: 'hotdog'
+        link '/orders/9'
     end
-    it.resource "relation", "/href/more" do |r|
-        r.attr "again", "this"
-        r.attr "this",  "again"
-        
-        r.link "search", "/href/more?search={term}", :templated => true, :title => "Embedded Resource"
+    relation 'th:manufacturer' do
+        link '/manufacturers/1'
+        link '/manufacturers/2'
+        link '/manufacturers/3'
     end
 end
-hal.to_xml
 
-news = Halibut::HAL::Link.new "index", "/api/news"
+resource = builder.resource
+```
+
+### JSON
+```ruby
+require 'halibut/adapter/json'
+
+# converting to JSON
+Halibut::Adapter::JSON.dump resource
+
+# creating a resource from JSON
+resource = Halibut::Adapter::JSON.load 'resource.json'
+```
+
+### XML
+```ruby
+require 'halibut/adapter/xml'
+
+# converting to XML
+# Coming soon…
+
+# creating a resource from XML
+resource = Halibut::Adapter::XML.load 'resource.xml'
 ```
 
 ## Contributing
 
 1. Fork it
+    1. `git submodule update --init`
+    2. `bundle install`, optionally pass `--without-development` and use your
+       own tools
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/Rakefile

@@ -3,8 +3,8 @@ require "bundler/gem_tasks"
 
 require 'rake/testtask'
 
-task :default => [:test,:spec]
+task :default => [:test, :spec]
 
 Rake::TestTask.new do |t|
-  t.pattern = "spec/*_spec.rb"
+  t.pattern = "spec/**/*_spec.rb"
 end

data/TODO

@@ -0,0 +1,2 @@
+hm, link options could be a Struct. that way I'd get
+link.option, link[:option] and link['option'] IIRC?

data/halibut.gemspec

@@ -14,22 +14,27 @@ Gem::Specification.new do |gem|
   gem.name          = "halibut"
   gem.require_paths = ["lib"]
   gem.version       = Halibut::VERSION
-  
+
+  gem.required_ruby_version = '~> 1.9.3'
+
   gem.add_dependency "multi_json"
   gem.add_dependency "nokogiri"
-  gem.add_dependency "uri_template"
-  
-  gem.add_development_dependency "rake"
-  
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "pry-full"
-  gem.add_development_dependency "pry-coolline"
-  #gem.add_development_dependency "pry-debundle"
-  
-  gem.add_development_dependency "minitest"
+  gem.add_dependency "addressable"
+
+  gem.add_development_dependency "minitest", ">= 4.1"
+
+  gem.add_development_dependency "pry", ">= 0.9.10"
+  gem.add_development_dependency "pry-doc"
+  gem.add_development_dependency "pry-stack_explorer"
+  gem.add_development_dependency "pry-coolline", "0.1.5"
+  gem.add_development_dependency "pry-rescue", "0.13"
+  gem.add_development_dependency "hash-differ"
+
   gem.add_development_dependency "guard"
   gem.add_development_dependency "guard-bundler"
   gem.add_development_dependency "guard-minitest"
 
+  gem.add_development_dependency "rb-fsevent"
   gem.add_development_dependency "terminal-notifier-guard"
+
 end

data/lib/halibut.rb

@@ -2,8 +2,20 @@ require "halibut/version"
 
 # Halibut is the main namespace
 module Halibut
+  autoload :Builder, 'halibut/builder'
+
+  autoload :RelationMap, 'halibut/relation_map'
+end
+
+# The Adapter namespace contains classes that aid in the
+# mapping of HAL Resources into a specific format.
+module Halibut::Adapter
+  autoload :JSON, 'halibut/adapter/json'
+  autoload :XML,  'halibut/adapter/xml'
 end
 
-require 'halibut/resource'
-require 'halibut/link'
-require 'halibut/relation_map'
+# Halibut::HAL contains the domain objects that reflect the HAL specs.
+module Halibut::HAL
+  autoload :Link, 'halibut/hal/link'
+  autoload :Resource, 'halibut/hal/resource'
+end

data/lib/halibut/adapter/json.rb

@@ -0,0 +1,72 @@
+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
+
+    def self.dump(resource)
+      MultiJson.dump resource.to_hash
+    end
+
+    private
+    module InstanceMethods
+      def to_json
+        MultiJson.dump self.to_hash
+      end
+    end
+
+    class ResourceExtractor
+      def initialize(json)
+        @halibut = Halibut::HAL::Resource.new
+        json     = MultiJson.load(json)
+
+        links      = json.delete '_links'
+        resources  = json.delete '_embedded'
+        properties = json
+
+        properties and extract_properties properties
+        links      and extract_links      links
+        resources  and extract_resources  resources
+      end
+
+      def resource
+        @halibut
+      end
+
+      private
+      def extract_properties(properties)
+        properties.each_pair do |property, value|
+          @halibut.set_property(property, value)
+        end
+      end
+
+      def extract_links(links)
+        links.each do |relation,values|
+          links = ([] << values).flatten
+
+          links.each do |attrs|
+            href      = attrs.delete 'href'
+            @halibut.add_link(relation, href, attrs)
+          end
+        end
+      end
+
+      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) }
+        end
+      end
+    end
+  end
+end

data/lib/halibut/adapter/xml.rb

@@ -0,0 +1,88 @@
+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)
+    end
+
+    private
+    module InstanceMethods
+      def to_xml
+      end
+    end
+
+    class ResourceExtractor
+      def initialize(xml)
+        xml = Nokogiri::XML(xml)
+
+        @document = xml.root
+        @halibut  = Halibut::HAL::Resource.new extract_self_link
+
+        # binding.pry
+
+        extract_curie
+        extract_properties
+        extract_links
+        extract_resources
+      end
+
+      def resource
+        @halibut
+      end
+
+      private
+      def extract_self_link
+        @document.attr 'href'
+      end
+
+      def extract_curie
+        @document.namespace_scopes
+                 .reject {|ns| ns.prefix.eql? 'xsi' }
+                 .each do |ns|
+          @halibut.add_link 'curie', ns.href, name: ns.prefix
+        end
+      end
+
+      def extract_properties
+        properties = @document.xpath '/resource/*[not(self::link) and not(self::resource)]'
+
+        properties.each do |property|
+          @halibut.set_property property.name, property.content
+        end
+      end
+
+      def extract_links
+        links = @document.xpath('/resource/link')
+
+        links.each do |link|
+          @halibut.add_link link.attribute('rel').value,
+                            link.attribute('href').value,
+                            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) || {}
+      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 }
+      end
+    end
+  end
+
+end

data/lib/halibut/builder.rb

@@ -0,0 +1,75 @@
+require 'halibut/hal/resource'
+
+module Halibut
+
+  # Builder provides a very thin wrapper around creating a HAL resource.
+  class Builder
+    attr_accessor :resource
+
+    def initialize(href=nil, &blk)
+      @resource = Halibut::HAL::Resource.new href
+
+      RootContext.new(@resource, &blk)
+    end
+
+    def respond_to?(meth, *args)
+      RootContext.new(@resource).respond_to? meth
+    end
+
+    def method_missing meth, *args
+      RootContext.new(@resource).send meth, *args
+    end
+
+    private
+    class RootContext
+      extend Forwardable
+
+      def_delegator :@resource, :set_property, :property
+      def_delegator :@resource, :add_link,     :link
+
+      def initialize(resource, &blk)
+        @resource = resource
+
+        instance_eval(&blk) if block_given?
+      end
+
+      def namespace(name, href)
+        @resource.add_link("curie", href, name: name)
+      end
+
+      def resource(rel, href=nil, &blk)
+        embedded = Halibut::Builder.new(href, &blk)
+
+        @resource.embed_resource(rel, embedded.resource)
+      end
+
+      def relation(rel, &blk)
+        RelationContext.new(@resource, rel, &blk)
+      end
+
+    end
+
+    class RelationContext
+
+      def initialize(resource, rel, &blk)
+        @resource = resource
+        @rel      = rel
+
+        instance_eval(&blk) if block_given?
+      end
+
+      private
+      def link(href, opts={})
+        @resource.add_link(@rel, href, opts)
+      end
+
+      def resource(href=nil, &blk)
+        embedded = Halibut::Builder.new(href, &blk)
+
+        @resource.embed_resource(@rel, embedded.resource)
+      end
+    end
+
+  end
+
+end