roar 0.11.4 → 0.11.5

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+## 0.11.5
+
+* Introducing HAL::links method to map arrays of link objects in the HAL format. This completes the HAL/JSON specification.
+
 ## 0.11.4
 
 * Links can now return a hash of attributes as `link :self do {:href => fruit_path(self), :title => "Yummy stuff"} end`.
@@ -21,7 +25,7 @@
 * You can include nil values now in your representations since #property respects :represent_nil => true.
 
 * The `:except` option got deprecated in favor of `:exclude`.
-* Hyperlinks can now have arbitrary attributes. To render, just provide `#link` with the options 
+* Hyperlinks can now have arbitrary attributes. To render, just provide `#link` with the options
 <code>link :self, :title => "Mee!", "data-remote" => true</code>
 When parsing, the options are avaible via `OpenStruct` compliant readers.
 <code>link = Hyperlink.from_json({\"rel\":\"self\",\"data-url\":\"http://self\"} )

data/Gemfile

@@ -3,7 +3,7 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in roar.gemspec
 gemspec
 
-#gem "representable", :path => "../representable"
+gem "representable", "~> 1.2.9"
 
 
 group :test do

data/README.textile

@@ -6,10 +6,10 @@ h2. Introduction
 
 Roar is a framework for parsing and rendering REST documents. Nothing more. With Roar, REST documents - also known as representations - are defined using a new concept called representers. Both syntax and semantics are declared in Ruby modules that can be mixed into your domain models, following clean OOP patterns.
 
-Roar comes with built-in JSON, JSON::HAL and XML support. It exposes a highly modular architecture and makes it very simple to add new media types and functionality where needed. Additional features include client HTTP support, coercion, client-side caching, awesome hypermedia support and more. Representers feel pretty well in DCI environments, too.
+Roar comes with built-in JSON, JSON::HAL and XML support. It exposes a highly modular architecture and makes it very simple to add new media types and functionality where needed. Additional features include client HTTP support, coercion, client-side caching, awesome hypermedia support and more. Representers fit pretty well in DCI environments, too.
+
+Roar is completely framework-agnostic and loves being used in web kits like Rails, Webmachine, Sinatra, Padrino, etc. Actually, Roar makes it fun designing real, hypermedia-driven, and resource-oriented systems that will even make Steve sleep happily at night so he finally gets some REST!
 
-Roar is completely framework-agnostic and loves being used in web kits like Rails, Webmachine, Sinatra, Padrino, etc. Actually, Roar makes it fun designing real, hypermedia-driven, and resource-oriented systems that will even make Steve sleep happily at night so he finally gets some REST! 
- 
 h2. Example
 
 Say your webshop consists of two completely separated apps. The REST backend, a Sinatra app, serves articles and processes orders. The frontend, being browsed by your clients, is a rich Rails application. It queries the services for articles, renders them nicely and reads or writes orders with REST calls. That being said, the frontend turns out to be a pure REST client.
@@ -34,7 +34,7 @@ pre. { "article": {
   "title":  "Lonestar Beer",
   "id":     4711,
   "links":[
-    { "rel":  "self", 
+    { "rel":  "self",
       "href": "http://articles/lonestarbeer"}
   ]}
 }
@@ -66,13 +66,13 @@ require 'roar/representer/feature/hypermedia'
 module ArticleRepresenter
   include Roar::Representer::JSON
   include Roar::Representer::Feature::Hypermedia
-  
+
   property :title
   property :id
-  
+
   link :self do
     article_url(self)
-  end 
+  end
 end
 </pre>
 
@@ -103,14 +103,14 @@ What if we wanted to check an existing order? We'd @GET http://orders/1@, right?
     {"title": "Lonestar Beer",
     "id":     666,
     "links":[
-      { "rel":  "self", 
+      { "rel":  "self",
         "href": "http://articles/lonestarbeer"}
     ]}
   ],
   "links":[
-    { "rel":  "self", 
+    { "rel":  "self",
       "href": "http://orders/1"},
-    { "rel":  "items", 
+    { "rel":  "items",
       "href": "http://orders/1/items"}
   ]}
 }
@@ -133,20 +133,20 @@ module OrderRepresenter
 
   property :id
   property :client_id
-  
+
   collection :articles, :class => Article
-  
+
   link :self do
     order_url(represented)
   end
-  
+
   link :items do
     items_url
-  end 
+  end
 end
 </pre>
 
-Representers don't have to be in modules, but can be 
+Representers don't have to be in modules, but can be
 
 The declarative @#collection@ method lets us define compositions of representers.
 
@@ -164,7 +164,7 @@ If we were to implement an endpoint for creating new orders, we'd allow POST to
     order.to_json
   end
 </pre>
- 
+
 Look how the @#from_json@ method helps extracting data from the incoming document and, again, @#to_json@ returns the freshly created order's representation. Roar's representers are truely working in both directions, rendering and parsing and thus prevent you from redundant knowledge sharing.
 
 
@@ -212,9 +212,9 @@ First, check the JSON document we get back from the POST.
   "client_id":  1337,
   "articles":   [],
   "links":[
-    { "rel":  "self", 
+    { "rel":  "self",
       "href": "http://orders/42"},
-    { "rel":  "items", 
+    { "rel":  "items",
       "href": "http://orders/42/items"}
   ]}
 }
@@ -258,7 +258,7 @@ Again, we use hypermedia to retrieve the order's URL. And now, the added article
 [*Note:* If this looks clumsy - It's just the raw API for representers. You might be interested in the upcoming DSL that simplifys frequent workflows as updating a representer.]
 
 <pre>
-order.to_attributes #=> {:id => 42, :client_id => 1337, 
+order.to_attributes #=> {:id => 42, :client_id => 1337,
   :articles => [{:title => "Lonestar Beer", :id => 666}]}
 </pre>
 
@@ -266,7 +266,7 @@ This is cool, we used REST representers and hypermedia to create an order and fi
 
 
 h3. Using Accessors
- 
+
 What if the ordering API is going a different way? What if we had to place articles into the order document ourselves, and then PUT this representation to @http://orders/42@? No problem with representers!
 
 Here's what could happen in the frontend.
@@ -283,7 +283,8 @@ h2. More Features
 
 Be sure to check out the bundled features.
 
-# *Coercion* transforms values to typed objects when parsing a document. Uses virtus. 
+# *Coercion* transforms values to typed objects when parsing a document. Uses virtus.
+# *Faraday* support, if you want to use it install the Faraday gem and require 'roar/representer/transport/faraday' and configure 'Roar::Representer::Feature::HttpVerbs.transport_engine = Roar::Representer::Transport::Faraday'
 
 h2. What is REST about?
 

data/lib/roar/representer.rb

@@ -7,7 +7,7 @@ module Roar
         include Representable
       end
     end
-    
+
   private
     def before_serialize(*)
     end

data/lib/roar/representer/feature/client.rb

@@ -6,19 +6,19 @@ module Roar
     module Feature
       module Client
         include HttpVerbs
-        
+
         def self.extended(base)
           base.instance_eval do
             representable_attrs.each do |attr|
               next unless attr.instance_of? Representable::Definition # ignore hyperlinks etc for now.
               name = attr.name
-              
+
               # TODO: could anyone please make this better?
               instance_eval %Q{
                 def #{name}=(v)
                   @#{name} = v
                 end
-                
+
                 def #{name}
                   @#{name}
                 end

data/lib/roar/representer/feature/coercion.rb

@@ -6,7 +6,7 @@ module Roar::Representer::Feature
   # class ImmigrantSong
   #   include Roar::Representer::JSON
   #   include Roar::Representer::Feature::Coercion
-  #   
+  #
   #   property :composed_at, :type => DateTime, :default => "May 12th, 2012"
   # end
   module Coercion

data/lib/roar/representer/feature/http_verbs.rb

@@ -1,5 +1,4 @@
 require 'roar/representer/transport/net_http'
-require 'roar/representer/transport/faraday'  # Do not require here
 
 module Roar
   # Gives HTTP-power to representers. They can serialize, send, process and deserialize HTTP-requests.
@@ -9,13 +8,13 @@ module Roar
 
         class << self
           attr_accessor :transport_engine
-          
+
           def included(base)
             base.extend ClassMethods
           end
         end
         self.transport_engine = ::Roar::Representer::Transport::NetHTTP
-        
+
 
         module ClassMethods
           # GETs +url+ with +format+ and returns deserialized represented object.
@@ -23,26 +22,26 @@ module Roar
             new.get(*args)
           end
         end
-        
-        
+
+
         attr_writer :transport_engine
         def transport_engine
           @transport_engine || HttpVerbs.transport_engine
         end
-        
+
         # Serializes the object, POSTs it to +url+ with +format+, deserializes the returned document
         # and updates properties accordingly.
         def post(url, format)
           response = http.post_uri(url, serialize, format)
           handle_response(response)
         end
-        
+
         # GETs +url+ with +format+, deserializes the returned document and updates properties accordingly.
         def get(url, format)
           response = http.get_uri(url, format)
           handle_response(response)
         end
-        
+
         # Serializes the object, PUTs it to +url+ with +format+, deserializes the returned document
         # and updates properties accordingly.
         def put(url, format)
@@ -50,7 +49,7 @@ module Roar
           handle_response(response)
           self
         end
-        
+
         def patch(url, format)
           response = http.patch_uri(url, serialize, format)
           handle_response(response)

data/lib/roar/representer/feature/hypermedia.rb

@@ -33,65 +33,87 @@ module Roar
       #     "http://orders/#{opts[:id]}"
       #   end
       #
-      #   model.to_json(:id => 1) 
+      #   model.to_json(:id => 1)
       module Hypermedia
         def self.included(base)
           base.extend ClassMethods
         end
-        
+
+        # TODO: the whole declarative setup in representable should happen on instance level so we don't need to share methods between class and instance.
+        module LinksDefinitionMethods
+        private
+          def create_links_definition
+            representable_attrs << links = LinksDefinition.new(*links_definition_options)
+            links
+          end
+
+          def links_definition
+            representable_attrs.find { |d| d.is_a?(LinksDefinition) } or create_links_definition
+          end
+        end
+        include LinksDefinitionMethods
+        def links_definition_options  # FIXME: make this unnecessary.
+          self.class.links_definition_options
+        end
+
         def before_serialize(options={})
           prepare_links!(options) unless options[:links] == false  # DISCUSS: doesn't work when links are already setup (e.g. from #deserialize).
           super # Representer::Base
         end
-        
-        def links=(link_list)
-          links.replace(link_list)
-        end
-        
+
+        attr_writer :links
+
         def links
           @links ||= LinkCollection.new
         end
-        
-      protected
+
+        def links_array
+          links.values  # FIXME: move to LinkCollection#to_a.
+        end
+
+        def links_array=(ary)
+          # FIXME: move to LinkCollection
+          self.links= LinkCollection.new
+          ary.each do |lnk|
+            self.links[lnk.rel.to_s] = lnk
+          end
+        end
+
+      private
         # Setup hypermedia links by invoking their blocks. Usually called by #serialize.
         def prepare_links!(*args)
-          links_def = find_links_definition or return
-          
-          links_def.rel2block.each do |config|  # config is [{..}, block]
-            options = config.first
-            href = run_link_block(config.last, *args) or next
-            options.merge! href.is_a?(Hash) ? href : {:href => href}
-
-            links.update_link(Feature::Hypermedia::Hyperlink.new(options))
+          links_definition.each do |config|  # config is [{..}, block]
+            options, block  = config.first, config.last
+            href            = run_link_block(block, *args) or next
+
+            links.add(prepare_link_for(href, options))
           end
         end
-        
+
+        def prepare_link_for(href, options)
+          options.merge! href.is_a?(Hash) ? href : {:href => href}
+          Hyperlink.new(options)
+        end
+
         def run_link_block(block, *args)
           instance_exec(*args, &block)
         end
-        
-        def find_links_definition
-          representable_attrs.find { |d| d.is_a?(LinksDefinition) }
-        end
-        
-        
-        class LinkCollection < Array
+
+
+        class LinkCollection < Hash
+          # DISCUSS: make Link#rel return string always.
           def [](rel)
-            link = find { |l| l.rel.to_s == rel.to_s } and return link
+            self.fetch(rel.to_s, nil)
           end
-          
-          # Checks if the link is already contained by querying for its +rel+.
-          # If so, it gets replaced. Otherwise, the new link gets appended.
-          def update_link(link)
-            if i = find_index { |l| l.rel.to_s == link.rel.to_s }
-              return self[i] = link
-            end
-            self << link
+
+          def add(link) # FIXME: use Hash API.
+            self[link.rel.to_s] = link
           end
         end
-        
-        
+
+
         module ClassMethods
+          include LinksDefinitionMethods
           # Declares a hypermedia link in the document.
           #
           # Example:
@@ -103,48 +125,46 @@ module Roar
           # The block is executed in instance context, so you may call properties or other accessors.
           # Note that you're free to put decider logic into #link blocks, too.
           def link(options, &block)
-            links = find_links_definition || create_links
-            
             options = {:rel => options} if options.is_a?(Symbol)
-            links.rel2block << [options, block]
-          end
-          
-          def find_links_definition
-            representable_attrs.find { |d| d.is_a?(LinksDefinition) }
-          end
-          
-        private
-          def create_links
-            LinksDefinition.new(*links_definition_options).tap do |links|
-              representable_attrs << links
-            end
+            links_definition << [options, block]
           end
         end
-        
-        
+
+
         class LinksDefinition < Representable::Definition
-          # TODO: hide rel2block in interface.
-          attr_writer :rel2block
-          
-          def rel2block
-            @rel2block ||= []
+          include Enumerable
+
+          attr_accessor :rel2block
+          def initialize(*)
+            super
+            @rel2block = []
+          end
+
+          def <<(args)
+            rel2block << args
+          end
+
+          def each(*args, &block)
+            rel2block.each(*args, &block)
           end
-          
+
+          # DISCUSS: where do we need this?
           def clone
             super.tap { |d| d.rel2block = rel2block.clone }
           end
         end
-        
-        
+
+
         require "ostruct"
         # An abstract hypermedia link with arbitrary attributes.
         class Hyperlink < OpenStruct
           include Enumerable
-          
+
           def each(*args, &block)
             marshal_dump.each(*args, &block)
           end
-          
+
+          # FIXME: do we need this method any longer?
           def replace(hash)
             # #marshal_load requires symbol keys: http://apidock.com/ruby/v1_9_3_125/OpenStruct/marshal_load
             marshal_load(hash.inject({}) { |h, (k,v)| h[k.to_sym] = v; h })
@@ -153,4 +173,4 @@ module Roar
       end
     end
   end
-end 
+end