collection-json 0.0.6 → 0.1.0

data/README.md

@@ -1,6 +1,6 @@
 # CollectionJSON
 
-A lightweight gem to easily build response objects with a MIME type of
+A lightweight gem to easily build and parse response objects with a MIME type of
 'application/vnd.collection+json'.
 
 Read http://amundsen.com/media-types/collection/ for more information about this
@@ -8,35 +8,37 @@ media type.
 
 ## Usage
 
+### Building
+
 Use ```CollectionJSON.generate_for``` to build a response object which you can
 call ```to_json``` on.
 
 ```ruby
-response = CollectionJSON.generate_for('/friends/') do |builder|
+collection = CollectionJSON.generate_for('/friends/') do |builder|
   builder.add_link '/friends/rss', 'feed'
   user.friends.each do |friend|
     builder.add_item("/friends/#{friend.id}") do |item|
-      item.add_data "full-name", friend.full_name
-      item.add_data "email", friend.email
-      item.add_link "/blogs/#{friend.id}", "blog", "", "Blog"
-      item.add_link "/blogs/#{friend.id}", "avatar", "", "Avatar", "image"
+      item.add_data "full-name", {"value" => friend.full_name}
+      item.add_data "email", {"value" => friend.email}
+      item.add_link "/blogs/#{friend.id}", "blog", {"prompt" => "Blog"}
+      item.add_link "/blogs/#{friend.id}", "avatar", {"prompt" => "Avatar", "render" => "image"}
     end
   end
-  builder.add_query("/friends/search", "search", "Search") do |query|
+  builder.add_query("/friends/search", "search", {"prompt" => "Search"}) do |query|
     query.add_data "search"
   end
   builder.set_template do |template|
-    template.add_data "full-name", "", "Full Name"
-    template.add_data "email", "", "Email"
-    template.add_data "blog", "", "Blog"
-    template.add_data "avatar", "", "Avatar"
+    template.add_data "full-name", {"prompt" => "Full Name"}
+    template.add_data "email", {"prompt" => "Email"}
+    template.add_data "blog", {"prompt" => "Blog"}
+    template.add_data "avatar", {"prompt" => "Avatar"}
   end
 end
 
-response.to_json
+collection.to_json
 ```
 
-Sample output:
+Output:
 
 ```javascript
 { "collection" :
@@ -98,7 +100,7 @@ Sample output:
     "queries" : [
       {"rel" : "search", "href" : "http://example.org/friends/search", "prompt" : "Search",
         "data" : [
-          {"name" : "search"}
+          {"name" : "q", "prompt" : "Search Query"}
         ]
       }
     ],
@@ -116,6 +118,50 @@ Sample output:
 }
 ```
 
+### Parsing
+
+CollectionJSON also helps you to consume APIs by parsing JSON strings:
+
+```ruby
+collection = CollectionJSON.parse(json)
+collection.href # => "http://example.org/friends/"
+collection.items.count # => 3
+```
+
+You can then build queries:
+
+```ruby
+collection.queries.first.build({'search' => 'puppies'}) # => "http://example.org/friends/search?q=puppies"
+```
+
+It also builds templates:
+
+```ruby
+built_template = collection.template.build({"full-name" => "Lol Cat", "email" => "lol@cats.com"})
+built_template.to_json
+```
+
+Output:
+
+```javascript
+{
+  "template" : {
+    "data" : [
+      {
+        "name" : "full-name",
+        "value" : "Lol Cat"
+      },
+      {
+        "name" : "email",
+        "value" : "lol@cats.com"
+      }
+    ]
+  }
+}
+```
+
+## Notes
+
 Set the ```COLLECTION_JSON_HOST``` environment variable to automatically add
 this to the href's. Eg. ```COLLECTION_JSON_HOST=http://example.org```
 

data/lib/collection-json.rb

@@ -1,16 +1,15 @@
 require 'json'
 require "collection-json/version"
-require "collection-json/collection"
+require "collection-json/attributes/collection"
 require "collection-json/builder"
 
 COLLECTION_JSON_VERSION = "1.0"
 ROOT_NODE = 'collection'
 
-VALID_LINK_ATTRIBUTES = %w{href rel name render prompt}.map(&:to_sym)
-
 module CollectionJSON
   def self.generate_for(href, &block)
-    response = Collection.new(href)
+    response = Collection.new
+    response.href href
     if block_given?
       builder = Builder.new(response)
       yield(builder)
@@ -29,6 +28,6 @@ module CollectionJSON
 
   def self.parse(json)
     hash = JSON.parse(json)
-    collection = Collection.from_hash(hash)
+    collection = Collection.from_hash(hash[ROOT_NODE])
   end
 end

data/lib/collection-json/attribute.rb

@@ -0,0 +1,62 @@
+require 'json'
+
+Dir[File.dirname(__FILE__) + "/transformers/*.rb"].each do |file|
+  require file
+end
+
+module CollectionJSON
+  class Attribute
+    def self.nested_attributes
+      @nested_attributes ||= []
+    end
+
+    def self.attribute(name, opts={})
+      nested_attributes << name
+      define_method(name) do |arg=nil|
+        if arg
+          if opts[:transform]
+            instance_variable_set(:"@#{name}", opts[:transform].call(arg))
+          else
+            instance_variable_set(:"@#{name}", arg)
+          end
+        else
+          unless instance_variable_get(:"@#{name}").nil?
+             instance_variable_get(:"@#{name}")
+           else
+            opts[:default]
+          end
+        end
+      end
+    end
+
+    def self.root_node(value = nil)
+      @root_node = value.to_s if value
+      @root_node
+    end
+
+    def self.from_hash(hash)
+      self.new.tap do |item|
+        hash.each { |k,v| item.send(k, v) if item.respond_to?(k) }
+      end
+    end
+
+    def to_hash
+      hash = Hash.new.tap do |item|
+        self.class.nested_attributes.each do |attribute|
+          value = send(attribute)
+          item[attribute] = value unless skip_value?(value)
+        end
+      end
+      self.class.root_node ? {self.class.root_node => hash} : hash
+    end
+
+    def to_json(*args)
+      to_hash.to_json(args)
+    end
+
+    private
+    def skip_value?(value)
+      value.nil? || value.respond_to?(:length) && value.length == 0
+    end
+  end
+end

data/lib/collection-json/attributes/collection.rb

@@ -0,0 +1,25 @@
+require_relative '../attribute'
+require_relative 'link'
+require_relative 'item'
+require_relative 'query'
+require_relative 'error'
+require_relative 'template'
+
+module CollectionJSON
+  class Collection < Attribute
+    root_node :collection
+    attribute :href, transform: URI
+    attribute :version
+    attribute :links,
+              transform:  lambda { |links| links.each.map { |l| Link.from_hash(l) }},
+              default:    []
+    attribute :items,
+              transform:  lambda { |items| items.each.map { |i| Item.from_hash(i) }},
+              default:    []
+    attribute :queries,
+              transform:  lambda { |queries| queries.each.map { |q| Query.from_hash(q) }},
+              default:    []
+    attribute :template, transform: lambda { |template| Template.from_hash(template) }
+    attribute :error, transform: lambda { |template| Error.from_hash(template) }
+  end
+end

data/lib/collection-json/attributes/data.rb

@@ -1,16 +1,9 @@
-module CollectionJSON
-  class Data < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def name; self['name']; end
-    def name=(value); self['name'] = value; end
+require_relative '../attribute'
 
-    def value; self['value']; end
-    def value=(value); self['value'] = value; end
-
-    def prompt; self['prompt']; end
-    def prompt=(value); self['prompt'] = value; end
+module CollectionJSON
+  class Data < Attribute
+    attribute :name
+    attribute :value
+    attribute :prompt
   end
 end

data/lib/collection-json/attributes/error.rb

@@ -1,16 +1,9 @@
-module CollectionJSON
-  class Error < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def title; self['title']; end
-    def title=(value); self['title'] = value; end
+require_relative '../attribute'
 
-    def code; self['code']; end
-    def code=(value); self['code'] = value; end
-
-    def message; self['message']; end
-    def message=(value); self['message'] = value; end
+module CollectionJSON
+  class Error < Attribute
+    attribute :title
+    attribute :code
+    attribute :message
   end
 end

data/lib/collection-json/attributes/item.rb

@@ -1,29 +1,15 @@
-require_relative 'link'
+require_relative '../attribute'
 require_relative 'data'
+require_relative 'link'
 
 module CollectionJSON
-  class Item < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def href; self['href']; end
-    def href=(value); self['href'] = value; end
-
-    def links
-      self['links'].map {|link| Link.from_hash(link)}
-    end
-
-    def links=(array)
-      self['links'] = array
-    end
-
-    def data
-      self['data'].map {|data| Data.from_hash(data)}
-    end
-
-    def data=(array)
-      self['data'] = array
-    end
+  class Item < Attribute
+    attribute :href, transform: URI
+    attribute :data,
+              transform:  lambda { |data| data.each.map { |d| Data.from_hash(d) }},
+              default:    []
+    attribute :links,
+              transform:  lambda { |links| links.each.map { |l| Link.from_hash(l) }},
+              default:    []
   end
 end

data/lib/collection-json/attributes/link.rb

@@ -1,22 +1,11 @@
-module CollectionJSON
-  class Link < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def href; self['href']; end
-    def href=(value); self['href'] = value; end
-
-    def rel; self['rel']; end
-    def rel=(value); self['rel'] = value; end
+require_relative '../attribute'
 
-    def name; self['name']; end
-    def name=(value); self['name'] = value; end
-
-    def render; self['render']; end
-    def render=(value); self['render'] = value; end
-
-    def prompt; self['prompt']; end
-    def prompt=(value); self['prompt'] = value; end
+module CollectionJSON
+  class Link < Attribute
+    attribute :href, transform: URI
+    attribute :rel
+    attribute :name
+    attribute :render
+    attribute :prompt
   end
 end

data/lib/collection-json/attributes/query.rb

@@ -1,30 +1,13 @@
+require_relative '../attribute'
 require_relative 'data'
 
 module CollectionJSON
-  class Query < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def href; self['href']; end
-    def href=(value); self['href'] = value; end
-
-    def rel; self['rel']; end
-    def rel=(value); self['rel'] = value; end
-
-    def name; self['name']; end
-    def name=(value); self['name'] = value; end
-
-    def prompt; self['prompt']; end
-    def prompt=(value); self['prompt'] = value; end
-
-    def data
-      self['data'].map {|data| Data.from_hash(data)}
-    end
-
-    def data=(array)
-      self['data'] = array
-    end
+  class Query < Attribute
+    attribute :href, transform: URI
+    attribute :rel
+    attribute :data,
+              transform:  lambda { |data| data.each.map { |d| Data.from_hash(d) }},
+              default:    []
 
     def build(params = {})
       URI(href).tap do |uri|

data/lib/collection-json/attributes/template.rb

@@ -1,26 +1,19 @@
 require_relative 'data'
 
 module CollectionJSON
-  class Template < Hash
-    def self.from_hash(hash)
-      self.new.merge! hash
-    end
-
-    def data
-      self['data'].map {|data| Data.from_hash(data)}
-    end
-
-    def data=(array)
-      self['data'] = array
-    end
+  class Template < Attribute
+    attribute :data,
+              transform:  lambda { |data| data.each.map { |d| Data.from_hash(d) }},
+              default:    []
 
     def build(params = {})
-      data = self.data.inject([]) do |array,data|
-        result = data.select {|k,v| %w{name value}.include?(k)}
-        result['value'] = params[data.name] if params[data.name]
-        result['value'] != nil ? array << result : array
+      {'template' => Hash.new}.tap do |hash|
+        hash['template']['data'] = data.inject([]) do |array,data|
+          result = {'name' => data.name, 'value' => data.value}
+          result['value'] = params[data.name] if params[data.name]
+          result['value'].nil? ? array : array << result
+        end
       end
-      { 'template' => { 'data' => data } }
     end
   end
 end

data/lib/collection-json/builder.rb

@@ -6,48 +6,47 @@ module CollectionJSON
       @collection = collection
     end
 
-    def set_error(opts = {})
-      collection.error = opts
+    def set_error(params = {})
+      collection.error = params
     end
 
-    def set_code(code)
-      collection.code = code
+    def add_link(href, rel, params = {})
+      params.merge!({'rel' => rel, 'href' => href})
+      collection.links << Link.from_hash(params)
     end
 
-    def add_link(href, rel, opts = {})
-      href = CollectionJSON.add_host(href)
-
-      opts.select! {|k,v| VALID_LINK_ATTRIBUTES.include? k}
-      opts.merge!({'rel' => rel, 'href' => href})
-      collection.links << Link.from_hash(opts)
-    end
-
-    def add_item(href, data = [], links = [], &block)
-      href = CollectionJSON.add_host(href)
-      collection.items << Item.from_hash({'href' => href}).tap do |item|
-        item_builder = ItemBuilder.new(data, links)
-        yield(item_builder) if block_given?
-        item.merge!({'data' => item_builder.data}) if item_builder.data.length > 0
-        item.merge!({'links' => item_builder.links}) if item_builder.links.length > 0
+    def add_item(href, params = {}, &block)
+      params.merge!({'href' => href})
+      collection.items << Item.from_hash(params).tap do |item|
+        if block_given?
+          data = []
+          links = []
+          item_builder = ItemBuilder.new(data, links)
+          yield(item_builder)
+          item.data data
+          item.links links
+        end
       end
     end
 
-    def add_query(href, rel, prompt = '', data = [], &block)
-      href = CollectionJSON.add_host(href)
-      collection.queries << Query.from_hash({'href' => href, 'rel' => rel}).tap do |query|
+    def add_query(href, rel, params = {}, &block)
+      params.merge!({'href' => href, 'rel' => rel})
+      collection.queries << Query.from_hash(params).tap do |query|
+        data = []
         query_builder = QueryBuilder.new(data)
         yield(query_builder) if block_given?
-        query.merge!({'prompt' => prompt}) if prompt != ''
-        query.merge!({'data' => query_builder.data}) if query_builder.data.length > 0
+        query.data data
       end
     end
 
-    def set_template(data = [], &block)
-      collection.template = Template.new.tap do |template|
+    def set_template(params = {}, &block)
+      if block_given?
+        data = params['data'] || []
         template_builder = TemplateBuilder.new(data)
-        yield(template_builder) if block_given?
-        template.merge!({'data' => template_builder.data}) if template_builder.data.length > 0
+        yield(template_builder) 
+        params.merge!({'data' => data})
       end
+      collection.template params
     end
   end
 
@@ -59,20 +58,14 @@ module CollectionJSON
       @links = links
     end
 
-    def add_data(name, value = '', prompt = '')
-      data << {name: name}.tap do |data|
-        data.merge!({'value' => value}) if value != ''
-        data.merge!({'prompt' => prompt}) if prompt != ''
-      end
+    def add_data(name, params = {})
+      params.merge!({'name' => name})
+      data << params
     end
 
-    def add_link(href, rel, name = '', prompt = '', render = '')
-      href = CollectionJSON.add_host(href)
-      links << Link.from_hash({'href' => href, 'rel' => rel}).tap do |link|
-        link.merge!({'name' => name}) if name != ''
-        link.merge!({'prompt' => prompt}) if prompt != ''
-        link.merge!({'render' => render}) if render != ''
-      end
+    def add_link(href, rel, params = {})
+      params.merge!({'rel' => rel, 'href' => href})
+      links << params
     end
   end
 
@@ -83,11 +76,9 @@ module CollectionJSON
       @data = data
     end
 
-    def add_data(name, value = '', prompt = '')
-      data << Data.from_hash({'name' => name}).tap do |data|
-        data.merge!({'value' => value}) if value != ''
-        data.merge!({'prompt' => prompt}) if prompt != ''
-      end
+    def add_data(name, params = {})
+      params.merge!({'name' => name})
+      data << params
     end
   end
 
@@ -98,11 +89,9 @@ module CollectionJSON
       @data = data
     end
 
-    def add_data(name, value = '', prompt = '')
-      data << Data.from_hash({'name' => name}).tap do |data|
-        data.merge!({'value' => value}) if value != ''
-        data.merge!({'prompt' => prompt}) if prompt != ''
-      end
+    def add_data(name, params = {})
+      params.merge!({'name' => name})
+      data << params
     end
   end
 end

data/lib/collection-json/transformers/uri.rb

@@ -0,0 +1,11 @@
+module CollectionJSON
+  class URI
+    def self.call(href)
+      if ENV['COLLECTION_JSON_HOST'] && !href[/^http/]
+        ENV['COLLECTION_JSON_HOST'] + href
+      else
+        href
+      end
+    end
+  end
+end

data/lib/collection-json/version.rb

@@ -1,3 +1,3 @@
 module CollectionJSON
-  VERSION = "0.0.6"
+  VERSION = "0.1.0"
 end

data/spec/collection-json/attributes/collection_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+require 'collection-json/attributes/collection'
+
+describe CollectionJSON::Collection do
+  it 'be serializable' do
+    collection = CollectionJSON::Collection.from_hash({
+      href: '/',
+      links: [{href: '/place'}],
+      items: [{
+          data: [{name: 'full-name', value: 'phil'}]
+        }]
+      })
+    collection.to_json.class.should eq(String)
+  end
+end

data/spec/collection-json/attributes/item_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+require 'collection-json/attributes/item'
+
+describe CollectionJSON::Item do
+  it 'be serializable' do
+    item = CollectionJSON::Item.from_hash({
+      href: 'http://www.example.com',
+      links: [{href: 'http://www.example.com/place'}],
+      data: [{name: 'full-name', value: 'phil'}]
+      })
+    item.to_json.class.should eq(String)
+  end
+end

data/spec/collection-json/attributes/template_spec.rb

@@ -27,6 +27,7 @@ describe CollectionJSON::Template do
       json = result.to_json
       hash = JSON.parse(json)
       hash['template']['data'].length.should eq(2)
+      hash['template']['data'].first.keys.length.should eq(2)
     end
   end
 end

data/spec/collection-json_spec.rb

@@ -50,20 +50,20 @@ describe CollectionJSON do
         builder.add_link '/friends/rss', 'feed'
         @friends.each do |friend|
           builder.add_item("/friends/#{friend['id']}") do |item|
-            item.add_data "full-name", friend["full-name"]
-            item.add_data "email", friend["email"]
-            item.add_link "/blogs/#{friend['id']}", "blog", "", "Blog"
-            item.add_link "/blogs/#{friend['id']}", "avatar", "", "Avatar", "image"
+            item.add_data "full-name", {'value' => friend["full-name"]}
+            item.add_data "email", {'value' => friend["email"]}
+            item.add_link "/blogs/#{friend['id']}", "blog", {'prompt' => "Blog"}
+            item.add_link "/blogs/#{friend['id']}", "avatar", {'prompt' => "Avatar", 'render' => 'image'}
           end
         end
-        builder.add_query("/friends/search", "search", "Search") do |query|
+        builder.add_query("/friends/search", "search", {'prompt' => "Search"}) do |query|
           query.add_data "search"
         end
         builder.set_template do |template|
-          template.add_data "full-name", "", "Full Name"
-          template.add_data "email", "", "Email"
-          template.add_data "blog", "", "Blog"
-          template.add_data "avatar", "", "Avatar"
+          template.add_data "full-name", {'prompt' => "Full Name"}
+          template.add_data "email", {'prompt' => "Email"}
+          template.add_data "blog", {'prompt' => "Blog"}
+          template.add_data "avatar", {'prompt' => "Avatar"}
         end
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: collection-json
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-17 00:00:00.000000000 Z
+date: 2012-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70109179999880 !ruby/object:Gem::Requirement
+  requirement: &70343263781380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70109179999880
+  version_requirements: *70343263781380
 description: Lightweight gem for building Collection+JSON responses.
 email:
 - sebastian@uprise.co.nz
@@ -35,6 +35,8 @@ files:
 - Rakefile
 - collection-json.gemspec
 - lib/collection-json.rb
+- lib/collection-json/attribute.rb
+- lib/collection-json/attributes/collection.rb
 - lib/collection-json/attributes/data.rb
 - lib/collection-json/attributes/error.rb
 - lib/collection-json/attributes/item.rb
@@ -42,8 +44,10 @@ files:
 - lib/collection-json/attributes/query.rb
 - lib/collection-json/attributes/template.rb
 - lib/collection-json/builder.rb
-- lib/collection-json/collection.rb
+- lib/collection-json/transformers/uri.rb
 - lib/collection-json/version.rb
+- spec/collection-json/attributes/collection_spec.rb
+- spec/collection-json/attributes/item_spec.rb
 - spec/collection-json/attributes/template_spec.rb
 - spec/collection-json_spec.rb
 - spec/spec_helper.rb
@@ -72,6 +76,8 @@ signing_key:
 specification_version: 3
 summary: Builds Collection+JSON responses.
 test_files:
+- spec/collection-json/attributes/collection_spec.rb
+- spec/collection-json/attributes/item_spec.rb
 - spec/collection-json/attributes/template_spec.rb
 - spec/collection-json_spec.rb
 - spec/spec_helper.rb

data/lib/collection-json/collection.rb

@@ -1,72 +0,0 @@
-require_relative 'attributes/link'
-require_relative 'attributes/item'
-require_relative 'attributes/query'
-require_relative 'attributes/error'
-require_relative 'attributes/template'
-
-module CollectionJSON
-  class Collection
-    attr_reader :href, :links, :items, :queries, :template, :version, :error
-    attr_writer :version
-
-    def self.from_hash(hash)
-      self.new(hash[ROOT_NODE]['href']).tap do |collection|
-        %w{items links queries error template}.each do |attribute|
-          if hash[ROOT_NODE][attribute]
-            collection.send("#{attribute}=", hash[ROOT_NODE][attribute])
-          end
-        end
-      end
-    end
-
-    def initialize(href)
-      @href = CollectionJSON.add_host(href)
-      @version = COLLECTION_JSON_VERSION
-      @items = []
-      @links = []
-      @queries = []
-      @error = nil
-      @template = nil
-    end
-
-    def items=(array)
-      @items = array.map {|item| Item.from_hash(item)}
-    end
-
-    def links=(array)
-      @links = array.map {|link| Link.from_hash(link)}
-    end
-
-    def queries=(array)
-      @queries = array.map {|query| Query.from_hash(query)}
-    end
-
-    def template=(template)
-      @template = Template.from_hash(template)
-    end
-
-    def error=(error)
-      @error = Error.from_hash(error)
-    end
-
-    def collection
-      {ROOT_NODE => body}
-    end
-
-    def to_json(*args)
-      collection.to_json(args)
-    end
-
-    private
-    def body
-      {href: href, version: version}.tap do |body|
-        %w{items links queries}.each do |child_name|
-          child = send(child_name)
-          body.merge!({child_name => child}) if child.length > 0
-        end
-        body.merge!({error: error}) if error
-        body.merge!({template: template}) if template
-      end
-    end
-  end
-end