her 0.6.3 → 0.6.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ODI2OTY3MmY1ZmU0OTRiYWJmZmQ5NTk5NTczYzgxYmJhOGVlY2M3Mg==
+    NzFmYjMyNGNlODUyZjk4N2I2MzA5ZGZmYjdkNTQyYTQ5YzZiMzlhMw==
   data.tar.gz: !binary |-
-    Mjg2ZTEwOGExNGZjZTcwYTVjOGQ2YjhiOWIwMDUzZjMzZTllNDc4Zg==
+    ODJkYzM0YTU3YTI3YTI2ZmNlNmIxM2UxOTAzZTc2YTA3NTJjMTM0Zg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    MDI1OGYxM2U2ODA3MTRiZGE4NmQ3ZTczMzRiYzAyOTA0NGI5MDYxNWZhMzg0
-    OWI2ODJkMDlhMWY5NThkZmZkNjhhMGVmYjRmY2JkOWU4ZWM2ZmZhYjczMTVk
-    ODg1ODMxOWJhZDZlNjVkZmE1YWE3NjQ4MDFkMjY0MmMxNzNiOTQ=
+    ODEzZjJhOTYwNDM0OGI0NGQzYzBmMGVkODdiYjk3NDFkY2E5ZTNkZTRkYWZl
+    MDlhODA5ZDY4NTJhZjE2MDM1MDIzMjViZDIzMjUxMTdhZDA1OTE4NDliODRj
+    MDdkMzdiMTI2MzAzNDE4NjkxNDY5ZDRhNmFmNGJjMjlmODcyNjA=
   data.tar.gz: !binary |-
-    N2U0Yzc3NWM2OGI0MzYwOTdkNjRiNWY2N2M2NGVmNWY5NTMzMmQwZGFiMGVm
-    Zjg3YWUzNDU4ZmM2ZmU1NmE2N2QzNTE4N2FkY2E2Mjk3NTU5ODhlMWE4MTk3
-    ZDM4OGM3NTgyNDA2ZmM5YzQ5MmY0NGM4OGMzNWFlZGFjZjczY2U=
+    MTBiODVmMmEzMDI5NTI2NmE0NGMzNDIyNWJkNjRiZTM2YTAxYzc1YjFhMTA4
+    YTM5NWRmNzVhNjE2Yjc0MDVkYTNiMjYyY2NkMTg2ODYxYjJhZDdlZjYzNmVk
+    NmYyNDc2M2IwYmVlNWU1YjU3Y2ZmYTE0YmQ1YWMyYjE4ZGM1YzQ=

data/.yardopts

@@ -0,0 +1,2 @@
+--protected
+--no-private

data/README.md

@@ -19,6 +19,8 @@ That’s it!
 
 ## Usage
 
+_For a complete reference of all the methods you can use, check out [the documentation](http://rdoc.info/github/remiprev/her)._
+
 First, you have to define which API your models will be bound to. For example, with Rails, you would create a new `config/initializers/her.rb` file with these lines:
 
 ```ruby
@@ -98,7 +100,7 @@ user = User.new(fullname: "Maeby Fünke")
 user.save
 ```
 
-You can look into the [`her-example`](https://github.com/remiprev/her-example) repository for a sample application using Her. For a complete reference of all the methods you can use, check out [the documentation](http://rdoc.info/github/remiprev/her).
+You can look into the [`her-example`](https://github.com/remiprev/her-example) repository for a sample application using Her.
 
 ## Middleware
 

data/her.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = Her::VERSION
   s.authors     = ["Rémi Prévost"]
   s.email       = ["remi@exomel.com"]
-  s.homepage    = "http://remiprev.github.com/her"
+  s.homepage    = "http://her-rb.org"
   s.license     = "MIT"
   s.summary     = "A simple Representational State Transfer-based Hypertext Transfer Protocol-powered Object Relational Mapper. Her?"
   s.description = "Her is an ORM that maps REST resources and collections to Ruby objects"

data/lib/her/api.rb

@@ -6,9 +6,9 @@ module Her
     attr_reader :base_uri, :connection, :options
 
     # Setup a default API connection. Accepted arguments and options are the same as {API#setup}.
-    def self.setup(attrs={}, &block)
+    def self.setup(opts={}, &block)
       @default_api = new
-      @default_api.setup(attrs, &block)
+      @default_api.setup(opts, &block)
     end
 
     # Create a new API object. This is useful to create multiple APIs and use them with the `uses_api` method.
@@ -29,9 +29,9 @@ module Her
 
     # Setup the API connection.
     #
-    # @param [Hash] attrs the Faraday options
-    # @option attrs [String] :url The main HTTP API root (eg. `https://api.example.com`)
-    # @option attrs [String] :ssl A hash containing [SSL options](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates)
+    # @param [Hash] opts the Faraday options
+    # @option opts [String] :url The main HTTP API root (eg. `https://api.example.com`)
+    # @option opts [String] :ssl A hash containing [SSL options](https://github.com/technoweenie/faraday/wiki/Setting-up-SSL-certificates)
     #
     # @return Faraday::Connection
     #
@@ -65,10 +65,10 @@ module Her
     #     connection.use MyCustomParser
     #     connection.use Faraday::Adapter::NetHttp
     #   end
-    def setup(attrs={}, &blk)
-      attrs[:url] = attrs.delete(:base_uri) if attrs.include?(:base_uri) # Support legacy :base_uri option
-      @base_uri = attrs[:url]
-      @options = attrs
+    def setup(opts={}, &blk)
+      opts[:url] = opts.delete(:base_uri) if opts.include?(:base_uri) # Support legacy :base_uri option
+      @base_uri = opts[:url]
+      @options = opts
       @connection = Faraday.new(@options) do |connection|
         yield connection if block_given?
       end
@@ -80,20 +80,20 @@ module Her
     # and a metadata Hash.
     #
     # @private
-    def request(attrs={})
-      method = attrs.delete(:_method)
-      path = attrs.delete(:_path)
-      headers = attrs.delete(:_headers)
-      attrs.delete_if { |key, value| key.to_s =~ /^_/ } # Remove all internal parameters
+    def request(opts={})
+      method = opts.delete(:_method)
+      path = opts.delete(:_path)
+      headers = opts.delete(:_headers)
+      opts.delete_if { |key, value| key.to_s =~ /^_/ } # Remove all internal parameters
       response = @connection.send method do |request|
         request.headers.merge!(headers) if headers
         if method == :get
           # For GET requests, treat additional parameters as querystring data
-          request.url path, attrs
+          request.url path, opts
         else
           # For POST, PUT and DELETE requests, treat additional parameters as request body
           request.url path
-          request.body = attrs
+          request.body = opts
         end
       end
 
@@ -102,7 +102,7 @@ module Her
 
     private
     # @private
-    def self.default_api(attrs={})
+    def self.default_api(opts={})
       defined?(@default_api) ? @default_api : nil
     end
   end

data/lib/her/middleware/accept_json.rb

@@ -2,10 +2,12 @@ module Her
   module Middleware
     # This middleware adds a "Accept: application/json" HTTP header
     class AcceptJSON < Faraday::Middleware
+      # @private
       def add_header(headers)
         headers.merge! "Accept" => "application/json"
       end
 
+      # @private
       def call(env)
         add_header(env[:request_headers])
         @app.call(env)

data/lib/her/middleware/first_level_parse_json.rb

@@ -6,6 +6,7 @@ module Her
       #
       # @param [String] body The response body
       # @return [Mixed] the parsed response
+      # @private
       def parse(body)
         json = parse_json(body)
         errors = json.delete(:errors) || {}
@@ -21,6 +22,7 @@ module Her
       # the value of `env[:body]`.
       #
       # @param [Hash] env The response environment
+      # @private
       def on_complete(env)
         env[:body] = case env[:status]
         when 204

data/lib/her/middleware/parse_json.rb

@@ -1,6 +1,7 @@
 module Her
   module Middleware
     class ParseJSON < Faraday::Response::Middleware
+      # @private
       def parse_json(body = nil)
         body ||= '{}'
         message = "Response from the API must behave like a Hash or an Array (last JSON response was #{body.inspect})"

data/lib/her/middleware/second_level_parse_json.rb

@@ -7,6 +7,7 @@ module Her
       #
       # @param [String] body The response body
       # @return [Mixed] the parsed response
+      # @private
       def parse(body)
         json = parse_json(body)
 
@@ -21,6 +22,7 @@ module Her
       # the value of `env[:body]`.
       #
       # @param [Hash] env The response environment
+      # @private
       def on_complete(env)
         env[:body] = case env[:status]
         when 204

data/lib/her/model.rb

@@ -38,6 +38,7 @@ module Her
     include Her::Model::NestedAttributes
 
     # Supported ActiveModel modules
+    include ActiveModel::AttributeMethods
     include ActiveModel::Validations
     include ActiveModel::Conversion
     include ActiveModel::Dirty

data/lib/her/model/associations.rb

@@ -52,10 +52,10 @@ module Her
         # Define an *has_many* association.
         #
         # @param [Symbol] name The name of the method added to resources
-        # @param [Hash] attrs Options
-        # @option attrs [String] :class_name The name of the class to map objects to
-        # @option attrs [Symbol] :data_key The attribute where the data is stored
-        # @option attrs [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
         #
         # @example
         #   class User
@@ -70,16 +70,17 @@ module Her
         #   @user = User.find(1)
         #   @user.articles # => [#<Article(articles/2) id=2 title="Hello world.">]
         #   # Fetched via GET "/users/1/articles"
-        def has_many(name, attrs={})
-          Her::Model::Associations::HasManyAssociation.attach(self, name, attrs)
+        def has_many(name, opts={})
+          Her::Model::Associations::HasManyAssociation.attach(self, name, opts)
         end
 
         # Define an *has_one* association.
         #
         # @param [Symbol] name The name of the method added to resources
-        # @option attrs [String] :class_name The name of the class to map objects to
-        # @option attrs [Symbol] :data_key The attribute where the data is stored
-        # @option attrs [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
         #
         # @example
         #   class User
@@ -94,17 +95,18 @@ module Her
         #   @user = User.find(1)
         #   @user.organization # => #<Organization(organizations/2) id=2 name="Foobar Inc.">
         #   # Fetched via GET "/users/1/organization"
-        def has_one(name, attrs={})
-          Her::Model::Associations::HasOneAssociation.attach(self, name, attrs)
+        def has_one(name, opts={})
+          Her::Model::Associations::HasOneAssociation.attach(self, name, opts)
         end
 
         # Define a *belongs_to* association.
         #
         # @param [Symbol] name The name of the method added to resources
-        # @option attrs [String] :class_name The name of the class to map objects to
-        # @option attrs [Symbol] :data_key The attribute where the data is stored
-        # @option attrs [Path] :path The relative path where to fetch the data (defaults to `/{class_name}.pluralize/{id}`)
-        # @option attrs [Symbol] :foreign_key The foreign key used to build the `:id` part of the path (defaults to `{name}_id`)
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{class_name}.pluralize/{id}`)
+        # @option opts [Symbol] :foreign_key The foreign key used to build the `:id` part of the path (defaults to `{name}_id`)
         #
         # @example
         #   class User
@@ -119,8 +121,8 @@ module Her
         #   @user = User.find(1) # => #<User(users/1) id=1 team_id=2 name="Tobias">
         #   @user.team # => #<Team(teams/2) id=2 name="Developers">
         #   # Fetched via GET "/teams/2"
-        def belongs_to(name, attrs={})
-          Her::Model::Associations::BelongsToAssociation.attach(self, name, attrs)
+        def belongs_to(name, opts={})
+          Her::Model::Associations::BelongsToAssociation.attach(self, name, opts)
         end
       end
     end

data/lib/her/model/associations/association.rb

@@ -2,22 +2,71 @@ module Her
   module Model
     module Associations
       class Association
-        attr_accessor :query_attrs
+        # @private
+        attr_accessor :params
 
         # @private
         def initialize(parent, opts = {})
           @parent = parent
           @opts = opts
-          @query_attrs = {}
+          @params = {}
 
           @klass = @parent.class.her_nearby_class(@opts[:class_name])
           @name = @opts[:name]
         end
 
+        # @private
+        def self.parse_single(association, klass, data)
+          data_key = association[:data_key]
+          return {} unless data[data_key]
+
+          klass = klass.her_nearby_class(association[:class_name])
+          { association[:name] => klass.new(data[data_key]) }
+        end
+
+        # @private
+        def assign_single_nested_attributes(attributes)
+          if @parent.attributes[@name].blank?
+            @parent.attributes[@name] = @klass.new(@klass.parse(attributes))
+          else
+            @parent.attributes[@name].assign_attributes(attributes)
+          end
+        end
+
+        # @private
+        def fetch(opts = {})
+          return @opts[:default].try(:dup) if @parent.attributes.include?(@name) && @parent.attributes[@name].empty? && @params.empty?
+
+          if @parent.attributes[@name].blank? || @params.any?
+            path = build_association_path lambda { "#{@parent.request_path(@params)}#{@opts[:path]}" }
+            @klass.get(path, @params)
+          else
+            @parent.attributes[@name]
+          end
+        end
+
+        # @private
+        def build_association_path(code)
+          begin
+            instance_exec(&code)
+          rescue Her::Errors::PathError
+            return nil
+          end
+        end
+
         # Add query parameters to the HTTP request performed to fetch the data
-        def where(attrs = {})
-          return self if attrs.blank?
-          self.clone.tap { |a| a.query_attrs = a.query_attrs.merge(attrs) }
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :comments
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.where(:approved => 1) # Fetched via GET "/users/1/comments?approved=1
+        def where(params = {})
+          return self if params.blank? && @parent.attributes[@name].blank?
+          self.clone.tap { |a| a.params = a.params.merge(params) }
         end
         alias all where
 

data/lib/her/model/associations/belongs_to_association.rb

@@ -3,33 +3,30 @@ module Her
     module Associations
       class BelongsToAssociation < Association
         # @private
-        def self.attach(klass, name, attrs)
-          attrs = {
+        def self.attach(klass, name, opts)
+          opts = {
             :class_name => name.to_s.classify,
             :name => name,
             :data_key => name,
+            :default => nil,
             :foreign_key => "#{name}_id",
             :path => "/#{name.to_s.pluralize}/:id"
-          }.merge(attrs)
-          klass.associations[:belongs_to] << attrs
+          }.merge(opts)
+          klass.associations[:belongs_to] << opts
 
           klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}
               cached_name = :"@_her_association_#{name}"
 
               cached_data = (instance_variable_defined?(cached_name) && instance_variable_get(cached_name))
-              cached_data || instance_variable_set(cached_name, Her::Model::Associations::BelongsToAssociation.new(self, #{attrs.inspect}))
+              cached_data || instance_variable_set(cached_name, Her::Model::Associations::BelongsToAssociation.new(self, #{opts.inspect}))
             end
           RUBY
         end
 
         # @private
-        def self.parse(association, klass, data)
-          data_key = association[:data_key]
-          return {} unless data[data_key]
-
-          klass = klass.her_nearby_class(association[:class_name])
-          { association[:name] => klass.new(data[data_key]) }
+        def self.parse(*args)
+          parse_single(*args)
         end
 
         # Initialize a new object
@@ -75,16 +72,12 @@ module Her
         # @private
         def fetch
           foreign_key_value = @parent.attributes[@opts[:foreign_key].to_sym]
-          return nil if (@parent.attributes.include?(@name) && @parent.attributes[@name].nil? && @query_attrs.empty?) || (@parent.persisted? && foreign_key_value.blank?)
-
-          if @parent.attributes[@name].blank? || @query_attrs.any?
-            path = begin
-              @klass.build_request_path(@parent.attributes.merge(@query_attrs.merge(@klass.primary_key => foreign_key_value)))
-            rescue Her::Errors::PathError
-              return nil
-            end
+          return @opts[:default].try(:dup) if (@parent.attributes.include?(@name) && @parent.attributes[@name].nil? && @params.empty?) || (@parent.persisted? && foreign_key_value.blank?)
 
-            @klass.get_resource(path, @query_attrs)
+          if @parent.attributes[@name].blank? || @params.any?
+            path_params = @parent.attributes.merge(@params.merge(@klass.primary_key => foreign_key_value))
+            path = build_association_path lambda { @klass.build_request_path(path_params) }
+            @klass.get(path, @params)
           else
             @parent.attributes[@name]
           end
@@ -92,11 +85,7 @@ module Her
 
         # @private
         def assign_nested_attributes(attributes)
-          if @parent.attributes[@name].blank?
-            @parent.attributes[@name] = @klass.new(@klass.parse(attributes))
-          else
-            @parent.attributes[@name].assign_attributes(attributes)
-          end
+          assign_single_nested_attributes(attributes)
         end
       end
     end

data/lib/her/model/associations/has_many_association.rb

@@ -3,22 +3,23 @@ module Her
     module Associations
       class HasManyAssociation < Association
         # @private
-        def self.attach(klass, name, attrs)
-          attrs = {
+        def self.attach(klass, name, opts)
+          opts = {
             :class_name     => name.to_s.classify,
             :name           => name,
             :data_key       => name,
+            :default        => Her::Collection.new,
             :path           => "/#{name}",
             :inverse_of => nil
-          }.merge(attrs)
-          klass.associations[:has_many] << attrs
+          }.merge(opts)
+          klass.associations[:has_many] << opts
 
           klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}
               cached_name = :"@_her_association_#{name}"
 
               cached_data = (instance_variable_defined?(cached_name) && instance_variable_get(cached_name))
-              cached_data || instance_variable_set(cached_name, Her::Model::Associations::HasManyAssociation.new(self, #{attrs.inspect}))
+              cached_data || instance_variable_set(cached_name, Her::Model::Associations::HasManyAssociation.new(self, #{opts.inspect}))
             end
           RUBY
         end
@@ -79,24 +80,10 @@ module Her
 
         # @private
         def fetch
-          return Her::Collection.new if @parent.attributes.include?(@name) && @parent.attributes[@name].empty? && @query_attrs.empty?
-
-          output = if @parent.attributes[@name].blank? || @query_attrs.any?
-            path = begin
-              @parent.request_path(@query_attrs)
-            rescue Her::Errors::PathError
-              return nil
-            end
-
-            @klass.get_collection("#{path}#{@opts[:path]}", @query_attrs)
-          else
-            @parent.attributes[@name]
+          super.tap do |o|
+            inverse_of = @opts[:inverse_of] || @parent.singularized_resource_name
+            o.each { |entry| entry.send("#{inverse_of}=", @parent) }
           end
-
-          inverse_of = @opts[:inverse_of] || @parent.singularized_resource_name
-          output.each { |entry| entry.send("#{inverse_of}=", @parent) }
-
-          output
         end
 
         # @private