roar 0.12.9 → 1.0.0.beta1

data/gemfiles/Gemfile.representable-2.0

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gemspec path: '../'
+
+gem 'representable', '~> 2.0.0'

data/gemfiles/Gemfile.representable-2.1

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gemspec path: '../'
+
+gem 'representable', '~> 2.1.0'

data/lib/roar.rb

@@ -1,4 +1,4 @@
-
+require 'roar/version'
 module Roar
   def self.root
     File.expand_path '../..', __FILE__

data/lib/roar/client.rb

@@ -0,0 +1,38 @@
+require "roar/http_verbs"
+
+module Roar
+  # Automatically add accessors for properties and collections. Also mixes in HttpVerbs.
+  module Client
+    include HttpVerbs
+
+    def self.extended(base)
+      base.instance_eval do
+        representable_attrs.each do |attr|
+          name = attr.name
+          next if name == "links" # ignore hyperlinks.
+
+          # TODO: could anyone please make this better?
+          instance_eval %Q{
+            def #{name}=(v)
+              @#{name} = v
+            end
+
+            def #{name}
+              @#{name}
+            end
+          }
+        end
+      end
+    end
+
+    def to_hash(options={})
+      options[:links] ||= false
+      super(options)
+    end
+
+    def to_xml(options={}) # sorry, but i'm not even sure if anyone uses this module.
+      options[:links] ||= false
+      super(options)
+    end
+  end
+end

data/lib/roar/{representer/feature/coercion.rb → coercion.rb}

@@ -1,7 +1,8 @@
+gem 'virtus'
 require 'virtus'
 require 'representable/coercion'
 
-module Roar::Representer::Feature
+module Roar
   # Use the +:type+ option to specify the conversion type.
   # class ImmigrantSong
   #   include Roar::Representer::JSON

data/lib/roar/decorator.rb

@@ -2,18 +2,10 @@ require 'roar/representer'
 require 'representable/decorator'
 
 class Roar::Decorator < Representable::Decorator
-  extend Roar::Representer::InheritableArray
-
   module HypermediaConsumer
-    def links_array=(*args)
-      super # TODO: this currently sets #links which is not obvious.
-      represented.links = links
-    end
-
-    # TODO: what is the deal with #links_array and #links?
-    def links=(*args)
-      super
-      represented.links = links
+    def links=(arr)
+      links = super
+      represented.instance_variable_set :@links, links
     end
   end
 end

data/lib/roar/http_verbs.rb

@@ -0,0 +1,88 @@
+require 'roar/transport/net_http'
+
+module Roar
+  # Gives HTTP-power to representers. They can serialize, send, process and deserialize HTTP-requests.
+  module HttpVerbs
+
+    class << self
+      attr_accessor :transport_engine
+
+      def included(base)
+        base.extend ClassMethods
+      end
+    end
+    self.transport_engine = ::Roar::Transport::NetHTTP
+
+
+    module ClassMethods
+      # GETs +url+ with +format+ and returns deserialized represented object.
+      def get(*args)
+        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(options={}, &block)
+      response = http.post_uri(options.merge(:body => serialize), &block)
+      handle_response(response)
+    end
+
+    # GETs +url+ with +format+, deserializes the returned document and updates properties accordingly.
+    def get(options={}, &block)
+      response = http.get_uri(options, &block)
+      handle_response(response)
+    end
+
+    # Serializes the object, PUTs it to +url+ with +format+, deserializes the returned document
+    # and updates properties accordingly.
+    def put(options={}, &block)
+      response = http.put_uri(options.merge(:body => serialize), &block)
+      handle_response(response)
+      self
+    end
+
+    def patch(options={}, &block)
+      response = http.patch_uri(options.merge(:body => serialize), &block)
+      handle_response(response)
+      self
+    end
+
+    def delete(options, &block)
+      http.delete_uri(options, &block)
+      self
+    end
+
+  private
+    def handle_response(response)
+      document = response.body
+      deserialize(document)
+    end
+
+    def http
+      transport_engine.new
+    end
+
+    def handle_deprecated_args(body, *args) # TODO: remove in 1.0.
+      options = args.first
+
+      if args.size > 1
+        warn %{DEPRECATION WARNING: #get, #post, #put, #delete and #patch no longer accept positional arguments. Please call them as follows:
+ get(uri: "http://localhost/songs", as: "application/json")
+post(uri: "http://localhost/songs", as: "application/json")
+Thank you and have a beautiful day.}
+        options = {:uri => args[0], :as => args[1]} if args.size == 2
+        options = {:uri => args[0], :as => args[2]}
+      end
+
+      options[:body] = body
+      options
+    end
+  end
+end

data/lib/roar/hypermedia.rb

@@ -0,0 +1,174 @@
+module Roar
+  # Define hypermedia links in your representations.
+  #
+  # Example:
+  #
+  #   class Order
+  #     include Roar::Representer::JSON
+  #
+  #     property :id
+  #
+  #     link :self do
+  #       "http://orders/#{id}"
+  #     end
+  #
+  # If you want more attributes, just pass a hash to #link.
+  #
+  #     link :rel => :next, :title => "Next, please!" do
+  #       "http://orders/#{id}"
+  #     end
+  #
+  # If you need dynamic attributes, the block can return a hash.
+  #
+  #     link :preview do
+  #       {:href => image.url, :title => image.name}
+  #     end
+  #
+  # Sometimes you need values from outside when the representation links are rendered. Just pass them
+  # to the render method, they will be available as block parameters.
+  #
+  #   link :self do |opts|
+  #     "http://orders/#{opts[:id]}"
+  #   end
+  #
+  #   model.to_json(:id => 1)
+  module Hypermedia
+    # links= [Hyperlink, Hyperlink] is where parsing happens.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    def links=(arr) # called when assigning parsed links.
+      @links = LinkCollection[*arr]
+    end
+
+    attr_reader :links # this is only useful after parsing.
+
+
+    module LinkConfigsMethod
+      def link_configs # we could store the ::link configs in links Definition.
+        representable_attrs[:links] ||= Representable::Inheritable::Array.new
+      end
+    end
+
+    include LinkConfigsMethod
+
+  private
+    # Create hypermedia links for this instance by invoking their blocks.
+    # This is called in links: getter: {}.
+    def prepare_links!(options)
+      return [] if options[:links] == false
+
+      LinkCollection[*compile_links_for(link_configs, options)]
+    end
+
+    def compile_links_for(configs, *args)
+      configs.collect do |config|
+        options, block  = config.first, config.last
+        href            = run_link_block(block, *args) or next
+
+        prepare_link_for(href, options)
+      end.compact # FIXME: make this less ugly.
+    end
+
+    def prepare_link_for(href, options)
+      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
+
+
+    # LinkCollection keeps an array of Hyperlinks to be rendered (setup in #prepare_links!)
+    # or parsed (array is passed to #links= which transforms it into a LinkCollection).
+    # It is implemented as a hash and keys links by their rel value.
+    #
+    #   {"self" => <Hyperlink ..>, ..}
+    class LinkCollection < ::Hash
+      # The only way to create is LinkCollection[<Hyperlink>, <Hyperlink>]
+      def self.[](*arr)
+        super(arr.collect { |link| [link.rel, link] })
+      end
+
+      def [](rel)
+        super(rel.to_s)
+      end
+
+      # Iterating links. Block parameters: |link| or |rel, link|.
+      # This is used Hash::HashBinding#serialize.
+      def collect(&block)
+        return values.collect(&block) if block.arity == 1
+        super(&block)
+      end
+    end
+
+
+    module ClassMethods
+      # Declares a hypermedia link in the document.
+      #
+      # Example:
+      #
+      #   link :self do
+      #     "http://orders/#{id}"
+      #   end
+      #
+      # 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)
+        create_links_definition! # this assures the links are rendered at the right position.
+
+        options = {:rel => options} unless options.is_a?(::Hash)
+        link_configs << [options, block]
+      end
+
+      include LinkConfigsMethod
+
+    private
+      # Add a :links Definition to the representable_attrs so they get rendered/parsed.
+      def create_links_definition!
+        return if representable_attrs.get(:links) # only create it once.
+
+        options = links_definition_options
+        options.merge!(:getter => lambda { |opts| prepare_links!(opts) })
+
+        representable_attrs.add(:links, options)
+      end
+    end
+
+
+    # An abstract hypermedia link with arbitrary attributes.
+    class Hyperlink
+      extend Forwardable
+      def_delegators :@attrs, :each, :collect
+
+       def initialize(attrs={})
+         @attrs = attributes!(attrs)
+       end
+
+      def replace(attrs) # makes it work with Hash::Hash.
+        @attrs = attributes!(attrs)
+        self
+      end
+
+      # Only way to write to Hyperlink after creation.
+      def merge!(attrs)
+        @attrs.merge!(attributes!(attrs))
+      end
+
+    private
+      def method_missing(name)
+        @attrs[name.to_s]
+      end
+
+      # Converts keys to strings.
+      def attributes!(attrs)
+        attrs.inject({}) { |hsh, kv| hsh[kv.first.to_s] = kv.last; hsh }.tap do |hsh|
+          hsh["rel"] = hsh["rel"].to_s if hsh["rel"]
+        end
+        # raise "Hyperlink without rel doesn't work!" unless @attrs["rel"]
+      end
+    end
+  end
+end

data/lib/roar/json.rb

@@ -0,0 +1,55 @@
+require 'roar/representer'
+require 'roar/hypermedia'
+require 'representable/json'
+
+module Roar
+  module JSON
+    def self.included(base)
+      base.class_eval do
+        include Representer
+        include Representable::JSON
+
+        extend ClassMethods
+        include InstanceMethods # otherwise Representable overrides our #to_json.
+      end
+    end
+
+    module InstanceMethods
+      def from_json(document, options={})
+        document = '{}' if document.nil? or document.empty?
+
+        super
+      end
+
+      # Generic entry-point for rendering.
+      def serialize(*args)
+        to_json(*args)
+      end
+
+      def deserialize(*args)
+        from_json(*args)
+      end
+    end
+
+
+    module ClassMethods
+      # TODO: move to instance method, or remove?
+      def links_definition_options
+        # FIXME: this doesn't belong into the generic JSON representer.
+        {
+          :collection     => true,
+          :class          => Hypermedia::Hyperlink,
+          :extend         => HyperlinkRepresenter,
+          :exec_context   => :decorator,
+        }
+      end
+    end
+
+
+    require "representable/json/hash"
+    # Represents a hyperlink in standard roar+json hash representation.
+    module HyperlinkRepresenter
+      include Representable::JSON::Hash
+    end
+  end
+end

data/lib/roar/json/collection.rb

@@ -0,0 +1,3 @@
+require "representable/json/collection"
+
+Roar::JSON::Collection = Representable::JSON::Collection

data/lib/roar/{representer/json → json}/collection_json.rb

@@ -1,4 +1,4 @@
-module Roar::Representer::JSON
+module Roar::JSON
   # Implementation of the Collection+JSON media format, http://amundsen.com/media-types/collection/format/
   #
   # When clients want to add or update an item the collection's filled out template is POSTed or PUT. You can parse that using the
@@ -9,8 +9,8 @@ module Roar::Representer::JSON
     def self.included(base)
       base.class_eval do
         include Roar::Representer
-        include Roar::Representer::JSON
-        include Roar::Representer::Feature::Hypermedia
+        include Roar::JSON
+        include Roar::Hypermedia
 
         extend ClassMethods
 
@@ -21,7 +21,7 @@ module Roar::Representer::JSON
           OpenStruct.new  # TODO: handle preset values.
         end
 
-        collection :queries, :extend => Roar::Representer::JSON::HyperlinkRepresenter
+        collection :queries, :extend => Roar::JSON::HyperlinkRepresenter, :class => lambda { |fragment,*| ::Hash }
         def queries
           compile_links_for(representable_attrs.collection_representers[:queries].link_configs)
         end
@@ -45,9 +45,9 @@ module Roar::Representer::JSON
         def __href
           compile_links_for(representable_attrs.collection_representers[:href].link_configs).first.href
         end
-        
 
-        
+
+
         include ClientMethods
       end
     end
@@ -62,9 +62,9 @@ module Roar::Representer::JSON
       # TODO: provide automatic copying from the ItemRepresenter here.
       def template(&block)
         mod = representable_attrs.collection_representers[:object_template] = Module.new do
-          include Roar::Representer::JSON
-          include Roar::Representer::JSON::CollectionJSON::DataMethods
-          
+          include Roar::JSON
+          include Roar::JSON::CollectionJSON::DataMethods
+
           extend PropertyWithRenderNil
 
           module_exec(&block)
@@ -76,7 +76,7 @@ module Roar::Representer::JSON
         end
 
         representable_attrs.collection_representers[:template] = Module.new do
-          include Roar::Representer::JSON
+          include Roar::JSON
           include mod
 
           #self.representation_wrap = false
@@ -93,9 +93,9 @@ module Roar::Representer::JSON
 
       def queries(&block)
         mod = representable_attrs.collection_representers[:queries] = Module.new do
-          include Roar::Representer::JSON
-          include Roar::Representer::Feature::Hypermedia
-          
+          include Roar::JSON
+          include Roar::Hypermedia
+
           module_exec(&block)
 
           def to_hash(*)
@@ -109,9 +109,9 @@ module Roar::Representer::JSON
         collection :items, { :extend => lambda {|*| representable_attrs.collection_representers[:items] } }.merge!(options)
 
         mod = representable_attrs.collection_representers[:items] = Module.new do
-          include Roar::Representer::JSON
-          include Roar::Representer::Feature::Hypermedia
-          include Roar::Representer::JSON::CollectionJSON::DataMethods
+          include Roar::JSON
+          include Roar::Hypermedia
+          include Roar::JSON::CollectionJSON::DataMethods
           extend SharedClassMethodsBullshit
 
           module_exec(&block)
@@ -122,7 +122,7 @@ module Roar::Representer::JSON
             compile_links_for(representable_attrs.collection_representers[:href].link_configs).first.href
           end
           def __href=(v)
-            @__href = Roar::Representer::Feature::Hypermedia::Hyperlink.new(:href => v)
+            @__href = Roar::Hypermedia::Hyperlink.new(:href => v)
           end
           def href
             @__href
@@ -137,8 +137,8 @@ module Roar::Representer::JSON
       module SharedClassMethodsBullshit
         def href(&block)
           mod = representable_attrs.collection_representers[:href] = Module.new do
-            include Roar::Representer::JSON
-            include Roar::Representer::Feature::Hypermedia
+            include Roar::JSON
+            include Roar::Hypermedia
 
 
             link(:href, &block)
@@ -190,7 +190,7 @@ module Roar::Representer::JSON
       end
 
       def __href=(v)
-        @__href = Roar::Representer::Feature::Hypermedia::Hyperlink.new(:href => v)
+        @__href = Roar::Hypermedia::Hyperlink.new(:href => v)
       end
       def href
         @__href