her 0.6.2 → 0.6.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MDYyOTQxNDk5MmVhOGYxZDg4OTI0YTAxN2Y3MzBkYzliODc2MjgzZg==
+    ODI2OTY3MmY1ZmU0OTRiYWJmZmQ5NTk5NTczYzgxYmJhOGVlY2M3Mg==
   data.tar.gz: !binary |-
-    ZWJmNTZiODg5ZWFkYjZjM2M3YmRkNzhhNzk5MzYzOWQxOTdkYmNjNw==
+    Mjg2ZTEwOGExNGZjZTcwYTVjOGQ2YjhiOWIwMDUzZjMzZTllNDc4Zg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    OTM0ZGNmYmRjODRiNDJhMzhkNTY2NGViNjU1Y2EzNzQwMGE2MTE3OWRlZDM4
-    N2Q4MWJlMjYxMjU5ZTg5MGU5MTdmZWEyZGY3ZmJmNThmYzY4NWNlMGQ5YzMw
-    ZGM1ZjcwYmRhZjA4ZWYyNjU4MTJiMzdkYjk4YzE0YmU3ZjY4MTc=
+    MDI1OGYxM2U2ODA3MTRiZGE4NmQ3ZTczMzRiYzAyOTA0NGI5MDYxNWZhMzg0
+    OWI2ODJkMDlhMWY5NThkZmZkNjhhMGVmYjRmY2JkOWU4ZWM2ZmZhYjczMTVk
+    ODg1ODMxOWJhZDZlNjVkZmE1YWE3NjQ4MDFkMjY0MmMxNzNiOTQ=
   data.tar.gz: !binary |-
-    YmU3ODE5Mzk0YmY4YWQxOTA4YjVkMGNlNmFkNzBmZGMzOTAwNTA2MTFmNThl
-    MDFkNDQ2MTlkY2FkNWNlYWE2ZjFjZjFkMmJjZmIxY2UyYjY1ZGUyNjExNjVl
-    ODlmMDUwN2Q2NjhiOGY4ZmMyNmJkNDI4Nzg4OWM5YjZlNWIyNzc=
+    N2U0Yzc3NWM2OGI0MzYwOTdkNjRiNWY2N2M2NGVmNWY5NTMzMmQwZGFiMGVm
+    Zjg3YWUzNDU4ZmM2ZmU1NmE2N2QzNTE4N2FkY2E2Mjk3NTU5ODhlMWE4MTk3
+    ZDM4OGM3NTgyNDA2ZmM5YzQ5MmY0NGM4OGMzNWFlZGFjZjczY2U=

data/.gitignore

@@ -1,8 +1,3 @@
-*.gem
-.bundle
 /Gemfile.lock
-pkg/*
-rake
-tmp
-.env
-*.db
+/pkg
+/tmp

data/README.md

@@ -653,9 +653,9 @@ Just like with ActiveRecord, you can define named scopes for your models. Scopes
 class User
   include Her::Model
 
-  scope :by_role, lambda { |role| where(role: role) }
-  scope :admins, lambda { by_role('admin') }
-  scope :active, lambda { where(active: 1) }
+  scope :by_role, -> { |role| where(role: role) }
+  scope :admins, -> { by_role('admin') }
+  scope :active, -> { where(active: 1) }
 end
 
 @admins = User.admins

data/UPGRADE.md

@@ -4,71 +4,78 @@ Here is a list of backward-incompatible changes that were introduced while Her i
 
 ## 0.6
 
-* Associations have been refactored so that calling the association name method doesn’t immediately load or fetch the data.
+Associations have been refactored so that calling the association name method doesn’t immediately load or fetch the data.
 
-        class User
-          include Her::Model
-          has_many :comments
-        end
+```ruby
+class User
+  include Her::Model
+  has_many :comments
+end
 
-        # This doesn’t fetch the data yet
-        comments = User.find(1).comments
+# This doesn’t fetch the data yet and it’s still chainable
+comments = User.find(1).comments
 
-        # This actually fetches the data
-        puts comments.inspect
+# This actually fetches the data
+puts comments.inspect
 
-        # This is no longer possible
-        comments = User.find(1).comments(:approved => 1)
+# This is no longer possible in her-0.6
+comments = User.find(1).comments(:approved => 1)
 
-        # To pass additional parameters to the HTTP request, we now have to do this
-        comments = User.find(1).comments.where(:approved => 1)
-
-## 0.5.4
-
-* Her does not support Ruby 1.8.7 anymore. You should upgrade to 1.9.2, 1.9.3 or 2.0.0.
+# To pass additional parameters to the HTTP request, we now have to do this
+comments = User.find(1).comments.where(:approved => 1)
+```
 
 ## 0.5
 
-* Her is now compatible with `ActiveModel` and includes `ActiveModel::Validations`.
+Her is now compatible with `ActiveModel` and includes `ActiveModel::Validations`.
 
-  Before 0.5, the `errors` method on an object would return an error list received from the server (the `:errors` key defined by the parsing middleware). But now, `errors` returns the error list generated after calling the `valid?` method (or any other similar validation method from `ActiveModel::Validations`). The error list returned from the server is now accessible from the `response_errors` method.
+Before 0.5, the `errors` method on an object would return an error list received from the server (the `:errors` key defined by the parsing middleware). But now, `errors` returns the error list generated after calling the `valid?` method (or any other similar validation method from `ActiveModel::Validations`). The error list returned from the server is now accessible from the `response_errors` method.
 
-  Since 0.5.5, Her provides a `store_response_errors` method, which allows you to choose the method which will return the response errors. You can use it to revert Her back to its original behavior (ie. `errors` returning the response errors):
+Since 0.5.5, Her provides a `store_response_errors` method, which allows you to choose the method which will return the response errors. You can use it to revert Her back to its original behavior (ie. `errors` returning the response errors):
 
-        class User
-          include Her::Model
+```ruby
+class User
+  include Her::Model
+  store_response_errors :errors
+end
 
-          store_response_errors :errors
-        end
-
-        user = User.create(:email => "foo") # POST /users returns { :errors => ["Email is invalid"] }
-        user.errors # => ["Email is invalid"]
+user = User.create(:email => "foo") # POST /users returns { :errors => ["Email is invalid"] }
+user.errors # => ["Email is invalid"]
+```
 
 ## 0.2.4
 
-* Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
+Her no longer includes default middleware when making HTTP requests. The user has now to define all the needed middleware. Before:
 
-        Her::API.setup :url => "https://api.example.com" do |connection|
-          connection.insert(0, FaradayMiddle::OAuth)
-        end
+```ruby
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.insert(0, FaradayMiddle::OAuth)
+end
+```
 
-  Now:
+Now:
 
-        Her::API.setup :url => "https://api.example.com" do |connection|
-          connection.use FaradayMiddle::OAuth
-          connection.use Her::Middleware::FirstLevelParseJSON
-          connection.use Faraday::Request::UrlEncoded
-          connection.use Faraday::Adapter::NetHttp
-        end
+```ruby
+Her::API.setup :url => "https://api.example.com" do |connection|
+  connection.use FaradayMiddle::OAuth
+  connection.use Her::Middleware::FirstLevelParseJSON
+  connection.use Faraday::Request::UrlEncoded
+  connection.use Faraday::Adapter::NetHttp
+end
+```
 
 ## 0.2
 
-* The default parser middleware has been replaced to treat first-level JSON data as the resource or collection data. Before it expected this:
-
-        { "data": { "id": 1, "name": "Foo" }, "errors": [] }
+The default parser middleware has been replaced to treat first-level JSON data as the resource or collection data. Before it expected this:
 
-   Now it expects this (the `errors` key is not treated as resource data):
+```json
+{ "data": { "id": 1, "name": "Foo" }, "errors": [] }
+```
 
-        { "id": 1, "name": "Foo", "errors": [] }
+Now it expects this (the `errors` key is not treated as resource data):
+  
+```json
+{ "id": 1, "name": "Foo", "errors": [] }
+```
 
-   If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.
+If you still want to get the old behavior, you can use `Her::Middleware::SecondLevelParseJSON` instead of `Her::Middleware::FirstLevelParseJSON` in your middleware stack.

data/lib/her/model.rb

@@ -1,4 +1,5 @@
 require "her/model/base"
+require "her/model/deprecated_methods"
 require "her/model/http"
 require "her/model/attributes"
 require "her/model/relation"
@@ -26,6 +27,7 @@ module Her
 
     # Her modules
     include Her::Model::Base
+    include Her::Model::DeprecatedMethods
     include Her::Model::Attributes
     include Her::Model::ORM
     include Her::Model::HTTP

data/lib/her/model/associations.rb

@@ -10,17 +10,19 @@ module Her
       extend ActiveSupport::Concern
 
       # Returns true if the model has a association_name association, false otherwise.
+      #
+      # @private
       def has_association?(association_name)
         associations = self.class.associations.values.flatten.map { |r| r[:name] }
         associations.include?(association_name)
       end
-      alias :has_relationship? :has_association?
 
       # Returns the resource/collection corresponding to the association_name association.
+      #
+      # @private
       def get_association(association_name)
         send(association_name) if has_association?(association_name)
       end
-      alias :get_relationship :get_association
 
       module ClassMethods
         # Return @_her_associations, lazily initialized with copy of the
@@ -32,7 +34,6 @@ module Her
             superclass.respond_to?(:associations) ? superclass.associations.dup : Hash.new { |h,k| h[k] = [] }
           end
         end
-        alias :relationships :associations
 
         # Parse associations data after initializing a new object
         #
@@ -40,29 +41,21 @@ module Her
         def parse_associations(data)
           associations.each_pair do |type, definitions|
             definitions.each do |association|
-              data_key = association[:data_key]
-              next unless data[data_key]
-
-              klass = self.her_nearby_class(association[:class_name])
-              name = association[:name]
-
-              data[name] = case type
-                when :has_many
-                  Her::Model::Attributes.initialize_collection(klass, :data => data[data_key])
-                when :has_one, :belongs_to
-                  klass.new(data[data_key])
-                else
-                  nil
-              end
+              association_class = "her/model/associations/#{type}_association".classify.constantize
+              data.merge! association_class.parse(association, self, data)
             end
           end
+
           data
         end
 
         # Define an *has_many* association.
         #
-        # @param [Symbol] name The name of the model
-        # @param [Hash] attrs Options (currently not used)
+        # @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}`)
         #
         # @example
         #   class User
@@ -83,8 +76,10 @@ module Her
 
         # Define an *has_one* association.
         #
-        # @param [Symbol] name The name of the model
-        # @param [Hash] attrs Options
+        # @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}`)
         #
         # @example
         #   class User
@@ -105,8 +100,11 @@ module Her
 
         # Define a *belongs_to* association.
         #
-        # @param [Symbol] name The name of the model
-        # @param [Hash] attrs Options
+        # @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`)
         #
         # @example
         #   class User

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

@@ -14,11 +14,12 @@ module Her
           @name = @opts[:name]
         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) }
         end
-        alias :all :where
+        alias all where
 
         # @private
         def nil?
@@ -34,7 +35,7 @@ module Her
         def ==(other)
           fetch.eql?(other)
         end
-        alias :eql? :==
+        alias eql? ==
 
         # ruby 1.8.7 compatibility
         # @private

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

@@ -13,20 +13,59 @@ module Her
           }.merge(attrs)
           klass.associations[:belongs_to] << attrs
 
-          klass.instance_eval do
-            define_method(name) do
+          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))
+              cached_data || instance_variable_set(cached_name, Her::Model::Associations::BelongsToAssociation.new(self, #{attrs.inspect}))
             end
-          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]) }
         end
 
+        # Initialize a new object
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     belongs_to :organization
+        #   end
+        #
+        #   class Organization
+        #     include Her::Model
+        #   end
+        #
+        #   user = User.find(1)
+        #   new_organization = user.organization.build(:name => "Foo Inc.")
+        #   new_organization # => #<Organization name="Foo Inc.">
         def build(attributes = {})
           @klass.new(attributes)
         end
 
+        # Create a new object, save it and associate it to the parent
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     belongs_to :organization
+        #   end
+        #
+        #   class Organization
+        #     include Her::Model
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.organization.create(:name => "Foo Inc.")
+        #   user.organization # => #<Organization id=2 name="Foo Inc.">
         def create(attributes = {})
           resource = build(attributes)
           @parent.attributes[@name] = resource if resource.save
@@ -36,7 +75,7 @@ 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?) || foreign_key_value.blank?
+          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
@@ -50,6 +89,15 @@ module Her
             @parent.attributes[@name]
           end
         end
+
+        # @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
+        end
       end
     end
   end

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

@@ -13,20 +13,59 @@ module Her
           }.merge(attrs)
           klass.associations[:has_many] << attrs
 
-          klass.instance_eval do
-            define_method(name) do
+          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))
+              cached_data || instance_variable_set(cached_name, Her::Model::Associations::HasManyAssociation.new(self, #{attrs.inspect}))
             end
-          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] => Her::Model::Attributes.initialize_collection(klass, :data => data[data_key]) }
         end
 
+        # Initialize a new object with a foreign key to the parent
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :comments
+        #   end
+        #
+        #   class Comment
+        #     include Her::Model
+        #   end
+        #
+        #   user = User.find(1)
+        #   new_comment = user.comments.build(:body => "Hello!")
+        #   new_comment # => #<Comment user_id=1 body="Hello!">
         def build(attributes = {})
           @klass.new(attributes.merge(:"#{@parent.singularized_resource_name}_id" => @parent.id))
         end
 
+        # Create a new object, save it and add it to the associated collection
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :comments
+        #   end
+        #
+        #   class Comment
+        #     include Her::Model
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.create(:body => "Hello!")
+        #   user.comments # => [#<Comment id=2 user_id=1 body="Hello!">]
         def create(attributes = {})
           resource = build(attributes)
 
@@ -59,6 +98,11 @@ module Her
 
           output
         end
+
+        # @private
+        def assign_nested_attributes(attributes)
+          @parent.attributes[@name] = Her::Model::Attributes.initialize_collection(@klass, :data => attributes)
+        end
       end
     end
   end