her 0.3.1 → 0.3.2

data/README.md

@@ -1,4 +1,4 @@
-# Her [![Build Status](https://secure.travis-ci.org/remiprev/her.png)](http://travis-ci.org/remiprev/her) [![Gem dependency status](https://gemnasium.com/remiprev/her.png?travis)](https://gemnasium.com/remiprev/her)
+# Her [![Build Status](https://secure.travis-ci.org/remiprev/her.png?branch=master)](http://travis-ci.org/remiprev/her) [![Gem dependency status](https://gemnasium.com/remiprev/her.png?travis)](https://gemnasium.com/remiprev/her)
 
 Her is an ORM (Object Relational Mapper) that maps REST resources to Ruby objects. It is designed to build applications that are powered by a RESTful API instead of a database.
 
@@ -75,6 +75,7 @@ For example, to add a API token header to your requests, you would do something
 ```ruby
 class TokenAuthentication < Faraday::Middleware
   def initialize(app, options={})
+    @app = app
     @options = options
   end
 
@@ -549,6 +550,8 @@ These fine folks helped with Her:
 * [@tysontate](https://github.com/tysontate)
 * [@nfo](https://github.com/nfo)
 * [@simonprevost](https://github.com/simonprevost)
+* [@jmlacroix](https://github.com/jmlacroix)
+* [@thomsbg](https://github.com/thomsbg)
 
 ## License
 

data/Rakefile

@@ -1,6 +1,6 @@
 require "bundler"
-Bundler.require :development
-
+require "rake"
+require "yard"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 

data/her.gemspec

@@ -23,11 +23,11 @@ Gem::Specification.new do |s|
   s.add_development_dependency "redcarpet", "~> 2.1"
   s.add_development_dependency "mocha", "~> 0.12"
   s.add_development_dependency "guard", "~> 1.2"
-  s.add_development_dependency "guard-rspec", "~> 0.7"
+  s.add_development_dependency "guard-rspec", "~> 1.2"
   s.add_development_dependency "rb-fsevent", "~> 0.9"
   s.add_development_dependency "growl", "~> 1.0"
 
-  s.add_runtime_dependency "activesupport"
+  s.add_runtime_dependency "activesupport", ">= 3.0.0"
   s.add_runtime_dependency "faraday", "~> 0.8"
   s.add_runtime_dependency "multi_json", "~> 1.3"
 end

data/lib/her/model.rb

@@ -29,15 +29,13 @@ module Her
     included do
       extend Her::Model::Base
       extend Her::Model::HTTP
-      extend Her::Model::ORM
       extend Her::Model::Relationships
       extend Her::Model::Hooks
-      extend Her::Model::Paths
 
       # Define default settings
       base_path = self.name.split("::").last.underscore.pluralize
-      collection_path "/#{base_path}"
-      resource_path "/#{base_path}/:id"
+      collection_path "#{base_path}"
+      resource_path "#{base_path}/:id"
       uses_api Her::API.default_api
     end
   end

data/lib/her/model/hooks.rb

@@ -59,23 +59,26 @@ module Her
         perform_after_hooks(resource, *hooks.reverse)
       end # }}}
 
-      private
       # @private
       def hooks # {{{
-        @her_hooks
+        @her_hooks ||= begin
+          if superclass.respond_to?(:hooks)
+            superclass.hooks.dup
+          else
+            {}
+          end
+        end
       end # }}}
 
+      private
       # @private
       def set_hook(time, name, action) # {{{
-        @her_hooks ||= {}
-        (@her_hooks["#{time}_#{name}".to_sym] ||= []) << action
+        (self.hooks["#{time}_#{name}".to_sym] ||= []) << action
       end # }}}
 
       # @private
       def perform_hook(record, time, name) # {{{
-        @her_hooks ||= {}
-        hooks = @her_hooks["#{time}_#{name}".to_sym] || []
-        hooks.each do |hook|
+        Array(self.hooks["#{time}_#{name}".to_sym]).each do |hook|
           if hook.is_a? Symbol
             record.send(hook)
           else

data/lib/her/model/http.rb

@@ -2,6 +2,13 @@ module Her
   module Model
     # This module interacts with Her::API to fetch HTTP data
     module HTTP
+      # Automatically inherit a superclass' api
+      def her_api # {{{
+        @her_api ||= begin
+          superclass.her_api if superclass.respond_to?(:her_api)
+        end
+      end # }}}
+
       # Link a model with a Her::API object
       def uses_api(api) # {{{
         @her_api = api
@@ -9,8 +16,13 @@ module Her
 
       # Main request wrapper around Her::API. Used to make custom request to the API.
       # @private
-      def request(attrs={}, &block) # {{{
-        yield @her_api.request(attrs)
+      def request(attrs={}) # {{{
+        parsed_data = her_api.request(attrs)
+        if block_given?
+          yield parsed_data
+        else
+          parsed_data
+        end
       end # }}}
 
       # Make a GET request and return either a collection or a resource

data/lib/her/model/introspection.rb

@@ -2,32 +2,6 @@ module Her
   module Model
     module Introspection
       extend ActiveSupport::Concern
-
-      module ClassMethods
-        # Finds a class at the same level as this one or at the global level.
-        def nearby_class(name)
-          sibling_class(name) || name.constantize rescue nil
-        end
-
-        protected
-        # Looks for a class at the same level as this one with the given name.
-        # @private
-        def sibling_class(name)
-          if mod = self.containing_module
-            "#{mod.name}::#{name}".constantize rescue nil
-          else
-            name.constantize rescue nil
-          end
-        end
-
-        # If available, returns the containing Module for this class.
-        # @private
-        def containing_module # {{{
-          return unless self.name =~ /::/
-          self.name.split("::")[0..-2].join("::").constantize
-        end # }}}
-      end
-
       # Inspect an element, returns it for introspection.
       #
       # @example
@@ -38,7 +12,7 @@ module Her
       #   @user = User.find(1)
       #   p @user # => #<User(/users/1) id=1 name="Tobias Fünke">
       def inspect # {{{
-        "#<#{self.class}(#{self.class.build_request_path(@data)}) #{@data.inject([]) { |memo, item| key, value = item; memo << "#{key}=#{attribute_for_inspect(value)}"}.join(" ")}>"
+        "#<#{self.class}(#{request_path}) #{@data.inject([]) { |memo, item| key, value = item; memo << "#{key}=#{attribute_for_inspect(value)}"}.join(" ")}>"
       end # }}}
 
       private
@@ -52,6 +26,32 @@ module Her
           value.inspect
         end
       end # }}}
+
+      module ClassMethods
+        # Finds a class at the same level as this one or at the global level.
+        # @private
+        def nearby_class(name) # {{{
+          sibling_class(name) || name.constantize rescue nil
+        end # }}}
+
+        protected
+        # Looks for a class at the same level as this one with the given name.
+        # @private
+        def sibling_class(name) # {{{
+          if mod = self.containing_module
+            "#{mod.name}::#{name}".constantize rescue nil
+          else
+            name.constantize rescue nil
+          end
+        end # }}}
+
+        # If available, returns the containing Module for this class.
+        # @private
+        def containing_module # {{{
+          return unless self.name =~ /::/
+          self.name.split("::")[0..-2].join("::").constantize
+        end # }}}
+      end
     end
   end
 end

data/lib/her/model/orm.rb

@@ -2,7 +2,8 @@ module Her
   module Model
     # This module adds ORM-like capabilities to the model
     module ORM
-      attr_reader :metadata, :errors
+      extend ActiveSupport::Concern
+      attr_accessor :data, :metadata, :errors
 
       # Initialize a new object with data received from an HTTP request
       # @private
@@ -10,10 +11,12 @@ module Her
         @data = {}
         @metadata = data.delete(:_metadata) || {}
         @errors = data.delete(:_errors) || {}
+
+        # Only keep the keys that don't have corresponding writer methods
         cleaned_data = data.inject({}) do |memo, item|
           key, value = item
           send "#{key}=".to_sym, value unless value.nil?
-          respond_to?("#{key}=") ? memo : memo.merge({ key => value })
+          writer_method_defined?(key) ? memo : memo.merge({ key => value })
         end
         @data.merge! self.class.parse_relationships(cleaned_data)
       end # }}}
@@ -27,34 +30,29 @@ module Her
 
       # Handles missing methods by routing them through @data
       # @private
-      def method_missing(method, attrs=nil) # {{{
-        assignment_method = method.to_s =~ /\=$/
-        method = method.to_s.gsub(/(\?|\!|\=)$/, "").to_sym
-        if !attrs.nil? and assignment_method
-          @data ||= {}
-          @data[method.to_s.gsub(/\=$/, "").to_sym] = attrs
+      def method_missing(method, *args, &blk) # {{{
+        if method.to_s.end_with?('=')
+          @data[method.to_s.chomp('=').to_sym] = args.first
+        elsif method.to_s.end_with?('?')
+          @data.include?(method.to_s.chomp('?').to_sym)
+        elsif @data.include?(method)
+          @data[method]
         else
-          if @data and @data.include?(method)
-            @data[method]
-          else
-            super
-          end
+          super
         end
       end # }}}
 
+      # Handles returning true for the cases handled by method_missing
+      def respond_to?(method, include_private = false) # {{{
+        method.to_s.end_with?('=') || method.to_s.end_with?('?') || @data.include?(method) || super
+      end # }}}
+
       # Override the method to prevent from returning the object ID (in ruby-1.8.7)
       # @private
       def id # {{{
         @data[:id] || super
       end # }}}
 
-      # Initialize a collection of resources with raw data from an HTTP request
-      #
-      # @param [Array] parsed_data
-      def new_collection(parsed_data) # {{{
-        Her::Model::ORM.initialize_collection(self, parsed_data)
-      end # }}}
-
       # Return `true` if a resource was not saved yet
       def new? # {{{
         !@data.include?(:id)
@@ -70,56 +68,20 @@ module Her
         @errors.any?
       end # }}}
 
-      # Fetch a specific resource based on an ID
-      #
-      # @example
-      #   @user = User.find(1)
-      #   # Fetched via GET "/users/1"
-      def find(id, params={}) # {{{
-        request(params.merge(:_method => :get, :_path => "#{build_request_path(params.merge(:id => id))}")) do |parsed_data|
-          new(parsed_data[:data])
-        end
+      # Return `true` if the other object is also a Her::Model and has matching data
+      def ==(other) # {{{
+        other.is_a?(Her::Model) && @data == other.data
       end # }}}
 
-      # Fetch a collection of resources
-      #
-      # @example
-      #   @users = User.all
-      #   # Fetched via GET "/users"
-      def all(params={}) # {{{
-        request(params.merge(:_method => :get, :_path => "#{build_request_path(params)}")) do |parsed_data|
-          new_collection(parsed_data)
-        end
+      # Delegate to the == method
+      def eql?(other) # {{{
+        self == other
       end # }}}
 
-      # Create a resource and return it
-      #
-      # @example
-      #   @user = User.create({ :fullname => "Tobias Fünke" })
-      #   # Called via POST "/users/1"
-      def create(params={}) # {{{
-        resource = new(params)
-        wrap_in_hooks(resource, :create, :save) do |resource, klass|
-          params = resource.instance_eval { @data }
-          request(params.merge(:_method => :post, :_path => "#{build_request_path(params)}")) do |parsed_data|
-            resource.instance_eval do
-              @data = parsed_data[:data]
-              @metadata = parsed_data[:metadata]
-              @errors = parsed_data[:errors]
-            end
-          end
-        end
-        resource
-      end # }}}
-
-      # Save an existing resource and return it
-      #
-      # @example
-      #   @user = User.save_existing(1, { :fullname => "Tobias Fünke" })
-      #   # Called via PUT "/users/1"
-      def save_existing(id, params) # {{{
-        resource = new(params.merge(:id => id))
-        resource.save
+      # Delegate to @data, allowing models to act correctly in code like:
+      #     [ Model.find(1), Model.find(1) ].uniq # => [ Model.find(1) ]
+      def hash # {{{
+        @data.hash
       end # }}}
 
       # Save a resource
@@ -136,7 +98,7 @@ module Her
       #   @user.save
       #   # Called via POST "/users"
       def save # {{{
-        params = @data.dup
+        params = to_params
         resource = self
 
         if @data[:id]
@@ -149,9 +111,9 @@ module Her
 
         self.class.wrap_in_hooks(resource, *hooks) do |resource, klass|
           klass.request(params.merge(:_method => method, :_path => "#{request_path}")) do |parsed_data|
-            @data = parsed_data[:data]
-            @metadata = parsed_data[:metadata]
-            @errors = parsed_data[:errors]
+            self.data = parsed_data[:data]
+            self.metadata = parsed_data[:metadata]
+            self.errors = parsed_data[:errors]
           end
         end
         self
@@ -167,24 +129,114 @@ module Her
         resource = self
         self.class.wrap_in_hooks(resource, :destroy) do |resource, klass|
           klass.request(:_method => :delete, :_path => "#{request_path}") do |parsed_data|
-            @data = parsed_data[:data]
-            @metadata = parsed_data[:metadata]
-            @errors = parsed_data[:errors]
+            self.data = parsed_data[:data]
+            self.metadata = parsed_data[:metadata]
+            self.errors = parsed_data[:errors]
           end
         end
         self
       end # }}}
 
-      # Destroy an existing resource
+      # Convert into a hash of request parameters
       #
       # @example
-      #   User.destroy_existing(1)
-      #   # Called via DELETE "/users/1"
-      def destroy_existing(id, params={}) # {{{
-        request(params.merge(:_method => :delete, :_path => "#{build_request_path(params.merge(:id => id))}")) do |parsed_data|
-          new(parsed_data[:data])
-        end
+      #   @user.to_params
+      #   # => { :id => 1, :name => 'John Smith' }
+      def to_params # {{{
+        @data.dup
+      end # }}}
+
+      private
+
+      # @private
+      def writer_method_defined?(key) # {{{
+        self.class.instance_methods.include?("#{key}=".to_sym) || # Ruby 1.9
+          self.class.instance_methods.include?("#{key}=") # Ruby 1.8
       end # }}}
+
+      module ClassMethods
+        # Initialize a collection of resources with raw data from an HTTP request
+        #
+        # @param [Array] parsed_data
+        def new_collection(parsed_data) # {{{
+          Her::Model::ORM.initialize_collection(self, parsed_data)
+        end # }}}
+
+        # Fetch specific resource(s) by their ID
+        #
+        # @example
+        #   @user = User.find(1)
+        #   # Fetched via GET "/users/1"
+        #
+        # @example
+        #   @users = User.find([1, 2])
+        #   # Fetched via GET "/users/1" and GET "/users/2"
+        def find(*ids) # {{{
+          params = ids.last.is_a?(Hash) ? ids.pop : {}
+          results = ids.flatten.compact.uniq.map do |id|
+            request(params.merge(:_method => :get, :_path => "#{build_request_path(params.merge(:id => id))}")) do |parsed_data|
+              new(parsed_data[:data])
+            end
+          end
+          if ids.length > 1 || ids.first.kind_of?(Array)
+            results
+          else
+            results.first
+          end
+        end # }}}
+
+        # Fetch a collection of resources
+        #
+        # @example
+        #   @users = User.all
+        #   # Fetched via GET "/users"
+        def all(params={}) # {{{
+          request(params.merge(:_method => :get, :_path => "#{build_request_path(params)}")) do |parsed_data|
+            new_collection(parsed_data)
+          end
+        end # }}}
+
+        # Create a resource and return it
+        #
+        # @example
+        #   @user = User.create({ :fullname => "Tobias Fünke" })
+        #   # Called via POST "/users/1"
+        def create(params={}) # {{{
+          resource = new(params)
+          wrap_in_hooks(resource, :create, :save) do |resource, klass|
+            params = resource.to_params
+            request(params.merge(:_method => :post, :_path => "#{build_request_path(params)}")) do |parsed_data|
+              resource.instance_eval do
+                @data = parsed_data[:data]
+                @metadata = parsed_data[:metadata]
+                @errors = parsed_data[:errors]
+              end
+            end
+          end
+          resource
+        end # }}}
+
+        # Save an existing resource and return it
+        #
+        # @example
+        #   @user = User.save_existing(1, { :fullname => "Tobias Fünke" })
+        #   # Called via PUT "/users/1"
+        def save_existing(id, params) # {{{
+          resource = new(params.merge(:id => id))
+          resource.save
+        end # }}}
+
+        # Destroy an existing resource
+        #
+        # @example
+        #   User.destroy_existing(1)
+        #   # Called via DELETE "/users/1"
+        def destroy_existing(id, params={}) # {{{
+          request(params.merge(:_method => :delete, :_path => "#{build_request_path(params.merge(:id => id))}")) do |parsed_data|
+            new(parsed_data[:data])
+          end
+        end # }}}
+      end
     end
   end
 end