activerecord 3.2.22.5 → 4.0.0.beta1

data/lib/active_record/nested_attributes.rb

@@ -1,8 +1,6 @@
 require 'active_support/core_ext/hash/except'
 require 'active_support/core_ext/object/try'
-require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/hash/indifferent_access'
-require 'active_support/core_ext/class/attribute'
 
 module ActiveRecord
   module NestedAttributes #:nodoc:
@@ -12,17 +10,17 @@ module ActiveRecord
     extend ActiveSupport::Concern
 
     included do
-      class_attribute :nested_attributes_options, :instance_writer => false
+      class_attribute :nested_attributes_options, instance_writer: false
       self.nested_attributes_options = {}
     end
 
     # = Active Record Nested Attributes
     #
     # Nested attributes allow you to save attributes on associated records
-    # through the parent. By default nested attribute updating is turned off,
-    # you can enable it using the accepts_nested_attributes_for class method.
-    # When you enable nested attributes an attribute writer is defined on
-    # the model.
+    # through the parent. By default nested attribute updating is turned off
+    # and you can enable it using the accepts_nested_attributes_for class
+    # method. When you enable nested attributes an attribute writer is
+    # defined on the model.
     #
     # The attribute writer is named after the association, which means that
     # in the following example, two new methods are added to your model:
@@ -52,15 +50,15 @@ module ActiveRecord
     # Enabling nested attributes on a one-to-one association allows you to
     # create the member and avatar in one go:
     #
-    #   params = { :member => { :name => 'Jack', :avatar_attributes => { :icon => 'smiling' } } }
+    #   params = { member: { name: 'Jack', avatar_attributes: { icon: 'smiling' } } }
     #   member = Member.create(params[:member])
     #   member.avatar.id # => 2
     #   member.avatar.icon # => 'smiling'
     #
     # It also allows you to update the avatar through the member:
     #
-    #   params = { :member => { :avatar_attributes => { :id => '2', :icon => 'sad' } } }
-    #   member.update_attributes params[:member]
+    #   params = { member: { avatar_attributes: { id: '2', icon: 'sad' } } }
+    #   member.update params[:member]
     #   member.avatar.icon # => 'sad'
     #
     # By default you will only be able to set and update attributes on the
@@ -70,13 +68,13 @@ module ActiveRecord
     #
     #   class Member < ActiveRecord::Base
     #     has_one :avatar
-    #     accepts_nested_attributes_for :avatar, :allow_destroy => true
+    #     accepts_nested_attributes_for :avatar, allow_destroy: true
     #   end
     #
     # Now, when you add the <tt>_destroy</tt> key to the attributes hash, with a
     # value that evaluates to +true+, you will destroy the associated model:
     #
-    #   member.avatar_attributes = { :id => '2', :_destroy => '1' }
+    #   member.avatar_attributes = { id: '2', _destroy: '1' }
     #   member.avatar.marked_for_destruction? # => true
     #   member.save
     #   member.reload.avatar # => nil
@@ -92,23 +90,22 @@ module ActiveRecord
     #     accepts_nested_attributes_for :posts
     #   end
     #
-    # You can now set or update attributes on the associated posts through
-    # an attribute hash for a member: include the key +:posts_attributes+
-    # with an array of hashes of post attributes as a value.
+    # You can now set or update attributes on an associated post model through
+    # the attribute hash.
     #
     # For each hash that does _not_ have an <tt>id</tt> key a new record will
     # be instantiated, unless the hash also contains a <tt>_destroy</tt> key
     # that evaluates to +true+.
     #
-    #   params = { :member => {
-    #     :name => 'joe', :posts_attributes => [
-    #       { :title => 'Kari, the awesome Ruby documentation browser!' },
-    #       { :title => 'The egalitarian assumption of the modern citizen' },
-    #       { :title => '', :_destroy => '1' } # this will be ignored
+    #   params = { member: {
+    #     name: 'joe', posts_attributes: [
+    #       { title: 'Kari, the awesome Ruby documentation browser!' },
+    #       { title: 'The egalitarian assumption of the modern citizen' },
+    #       { title: '', _destroy: '1' } # this will be ignored
     #     ]
     #   }}
     #
-    #   member = Member.create(params['member'])
+    #   member = Member.create(params[:member])
     #   member.posts.length # => 2
     #   member.posts.first.title # => 'Kari, the awesome Ruby documentation browser!'
     #   member.posts.second.title # => 'The egalitarian assumption of the modern citizen'
@@ -117,48 +114,48 @@ module ActiveRecord
     # hashes if they fail to pass your criteria. For example, the previous
     # example could be rewritten as:
     #
-    #   class Member < ActiveRecord::Base
-    #     has_many :posts
-    #     accepts_nested_attributes_for :posts, :reject_if => proc { |attributes| attributes['title'].blank? }
-    #   end
+    #    class Member < ActiveRecord::Base
+    #      has_many :posts
+    #      accepts_nested_attributes_for :posts, reject_if: proc { |attributes| attributes['title'].blank? }
+    #    end
     #
-    #   params = { :member => {
-    #     :name => 'joe', :posts_attributes => [
-    #       { :title => 'Kari, the awesome Ruby documentation browser!' },
-    #       { :title => 'The egalitarian assumption of the modern citizen' },
-    #       { :title => '' } # this will be ignored because of the :reject_if proc
+    #   params = { member: {
+    #     name: 'joe', posts_attributes: [
+    #       { title: 'Kari, the awesome Ruby documentation browser!' },
+    #       { title: 'The egalitarian assumption of the modern citizen' },
+    #       { title: '' } # this will be ignored because of the :reject_if proc
     #     ]
     #   }}
     #
-    #   member = Member.create(params['member'])
+    #   member = Member.create(params[:member])
     #   member.posts.length # => 2
     #   member.posts.first.title # => 'Kari, the awesome Ruby documentation browser!'
     #   member.posts.second.title # => 'The egalitarian assumption of the modern citizen'
     #
     # Alternatively, :reject_if also accepts a symbol for using methods:
     #
-    #   class Member < ActiveRecord::Base
-    #     has_many :posts
-    #     accepts_nested_attributes_for :posts, :reject_if => :new_record?
-    #   end
+    #    class Member < ActiveRecord::Base
+    #      has_many :posts
+    #      accepts_nested_attributes_for :posts, reject_if: :new_record?
+    #    end
     #
-    #   class Member < ActiveRecord::Base
-    #     has_many :posts
-    #     accepts_nested_attributes_for :posts, :reject_if => :reject_posts
+    #    class Member < ActiveRecord::Base
+    #      has_many :posts
+    #      accepts_nested_attributes_for :posts, reject_if: :reject_posts
     #
-    #     def reject_posts(attributed)
-    #       attributed['title'].blank?
-    #     end
-    #   end
+    #      def reject_posts(attributed)
+    #        attributed['title'].blank?
+    #      end
+    #    end
     #
     # If the hash contains an <tt>id</tt> key that matches an already
     # associated record, the matching record will be modified:
     #
     #   member.attributes = {
-    #     :name => 'Joe',
-    #     :posts_attributes => [
-    #       { :id => 1, :title => '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!' },
-    #       { :id => 2, :title => '[UPDATED] other post' }
+    #     name: 'Joe',
+    #     posts_attributes: [
+    #       { id: 1, title: '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!' },
+    #       { id: 2, title: '[UPDATED] other post' }
     #     ]
     #   }
     #
@@ -173,42 +170,19 @@ module ActiveRecord
     #
     #   class Member < ActiveRecord::Base
     #     has_many :posts
-    #     accepts_nested_attributes_for :posts, :allow_destroy => true
+    #     accepts_nested_attributes_for :posts, allow_destroy: true
     #   end
     #
-    #   params = { :member => {
-    #     :posts_attributes => [{ :id => '2', :_destroy => '1' }]
+    #   params = { member: {
+    #     posts_attributes: [{ id: '2', _destroy: '1' }]
     #   }}
     #
-    #   member.attributes = params['member']
+    #   member.attributes = params[:member]
     #   member.posts.detect { |p| p.id == 2 }.marked_for_destruction? # => true
     #   member.posts.length # => 2
     #   member.save
     #   member.reload.posts.length # => 1
     #
-    # Nested attributes for an associated collection can also be passed in
-    # the form of a hash of hashes instead of an array of hashes:
-    #
-    #   Member.create(:name             => 'joe',
-    #                 :posts_attributes => { :first  => { :title => 'Foo' },
-    #                                        :second => { :title => 'Bar' } })
-    #
-    # has the same effect as
-    #
-    #   Member.create(:name             => 'joe',
-    #                 :posts_attributes => [ { :title => 'Foo' },
-    #                                        { :title => 'Bar' } ])
-    #
-    # The keys of the hash which is the value for +:posts_attributes+ are
-    # ignored in this case.
-    # However, it is not allowed to use +'id'+ or +:id+ for one of
-    # such keys, otherwise the hash will be wrapped in an array and
-    # interpreted as an attribute hash for a single post.
-    #
-    # Passing attributes for an associated collection in the form of a hash
-    # of hashes can be used with hashes generated from HTTP/HTML parameters,
-    # where there maybe no natural way to submit an array of hashes.
-    #
     # === Saving
     #
     # All changes to models, including the destruction of those marked for
@@ -216,18 +190,6 @@ module ActiveRecord
     # the parent model is saved. This happens inside the transaction initiated
     # by the parents save method. See ActiveRecord::AutosaveAssociation.
     #
-    # === Using with attr_accessible
-    #
-    # The use of <tt>attr_accessible</tt> can interfere with nested attributes
-    # if you're not careful. For example, if the <tt>Member</tt> model above
-    # was using <tt>attr_accessible</tt> like this:
-    #
-    #   attr_accessible :name
-    #
-    # You would need to modify it to look like this:
-    #
-    #   attr_accessible :name, :posts_attributes
-    #
     # === Validating the presence of a parent model
     #
     # If you want to validate that a child record is associated with a parent
@@ -235,20 +197,18 @@ module ActiveRecord
     # <tt>inverse_of</tt> as this example illustrates:
     #
     #   class Member < ActiveRecord::Base
-    #     has_many :posts, :inverse_of => :member
+    #     has_many :posts, inverse_of: :member
     #     accepts_nested_attributes_for :posts
     #   end
     #
     #   class Post < ActiveRecord::Base
-    #     belongs_to :member, :inverse_of => :posts
+    #     belongs_to :member, inverse_of: :posts
     #     validates_presence_of :member
     #   end
     module ClassMethods
       REJECT_ALL_BLANK_PROC = proc { |attributes| attributes.all? { |key, value| key == '_destroy' || value.blank? } }
 
-      # Defines an attributes writer for the specified association(s). If you
-      # are using <tt>attr_protected</tt> or <tt>attr_accessible</tt>, then you
-      # will need to add the attribute writer to the allowed list.
+      # Defines an attributes writer for the specified association(s).
       #
       # Supported options:
       # [:allow_destroy]
@@ -267,23 +227,32 @@ module ActiveRecord
       #   any value for _destroy.
       # [:limit]
       #   Allows you to specify the maximum number of the associated records that
-      #   can be processed with the nested attributes. If the size of the
+      #   can be processed with the nested attributes. Limit also can be specified as a
+      #   Proc or a Symbol pointing to a method that should return number. If the size of the
       #   nested attributes array exceeds the specified limit, NestedAttributes::TooManyRecords
       #   exception is raised. If omitted, any number associations can be processed.
       #   Note that the :limit option is only applicable to one-to-many associations.
       # [:update_only]
-      #   Allows you to specify that an existing record may only be updated.
-      #   A new record may only be created when there is no existing record.
-      #   This option only works for one-to-one associations and is ignored for
-      #   collection associations. This option is off by default.
+      #   For a one-to-one association, this option allows you to specify how
+      #   nested attributes are to be used when an associated record already
+      #   exists. In general, an existing record may either be updated with the
+      #   new set of attribute values or be replaced by a wholly new record
+      #   containing those values. By default the :update_only option is +false+
+      #   and the nested attributes are used to update the existing record only
+      #   if they include the record's <tt>:id</tt> value. Otherwise a new
+      #   record will be instantiated and used to replace the existing one.
+      #   However if the :update_only option is +true+, the nested attributes
+      #   are used to update the record's attributes always, regardless of
+      #   whether the <tt>:id</tt> is present. The option is ignored for collection
+      #   associations.
       #
       # Examples:
       #   # creates avatar_attributes=
-      #   accepts_nested_attributes_for :avatar, :reject_if => proc { |attributes| attributes['name'].blank? }
+      #   accepts_nested_attributes_for :avatar, reject_if: proc { |attributes| attributes['name'].blank? }
       #   # creates avatar_attributes=
-      #   accepts_nested_attributes_for :avatar, :reject_if => :all_blank
+      #   accepts_nested_attributes_for :avatar, reject_if: :all_blank
       #   # creates avatar_attributes= and posts_attributes=
-      #   accepts_nested_attributes_for :avatar, :posts, :allow_destroy => true
+      #   accepts_nested_attributes_for :avatar, :posts, allow_destroy: true
       def accepts_nested_attributes_for(*attr_names)
         options = { :allow_destroy => false, :update_only => false }
         options.update(attr_names.extract_options!)
@@ -301,16 +270,15 @@ module ActiveRecord
 
             type = (reflection.collection? ? :collection : :one_to_one)
 
-            # remove_possible_method :pirate_attributes=
-            #
             # def pirate_attributes=(attributes)
             #   assign_nested_attributes_for_one_to_one_association(:pirate, attributes, mass_assignment_options)
             # end
-            class_eval <<-eoruby, __FILE__, __LINE__ + 1
-              remove_possible_method(:#{association_name}_attributes=)
-
+            generated_feature_methods.module_eval <<-eoruby, __FILE__, __LINE__ + 1
+              if method_defined?(:#{association_name}_attributes=)
+                remove_method(:#{association_name}_attributes=)
+              end
               def #{association_name}_attributes=(attributes)
-                assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes, mass_assignment_options)
+                assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes)
               end
             eoruby
           else
@@ -337,31 +305,34 @@ module ActiveRecord
 
     # Assigns the given attributes to the association.
     #
-    # If update_only is false and the given attributes include an <tt>:id</tt>
-    # that matches the existing record's id, then the existing record will be
-    # modified. If update_only is true, a new record is only created when no
-    # object exists. Otherwise a new record will be built.
+    # If an associated record does not yet exist, one will be instantiated. If
+    # an associated record already exists, the method's behavior depends on
+    # the value of the update_only option. If update_only is +false+ and the
+    # given attributes include an <tt>:id</tt> that matches the existing record's
+    # id, then the existing record will be modified. If no <tt>:id</tt> is provided
+    # it will be replaced with a new record. If update_only is +true+ the existing
+    # record will be modified regardless of whether an <tt>:id</tt> is provided.
     #
     # If the given attributes include a matching <tt>:id</tt> attribute, or
     # update_only is true, and a <tt>:_destroy</tt> key set to a truthy value,
     # then the existing record will be marked for destruction.
-    def assign_nested_attributes_for_one_to_one_association(association_name, attributes, assignment_opts = {})
+    def assign_nested_attributes_for_one_to_one_association(association_name, attributes)
       options = self.nested_attributes_options[association_name]
       attributes = attributes.with_indifferent_access
 
       if (options[:update_only] || !attributes['id'].blank?) && (record = send(association_name)) &&
           (options[:update_only] || record.id.to_s == attributes['id'].to_s)
-        assign_to_or_mark_for_destruction(record, attributes, options[:allow_destroy], assignment_opts) unless call_reject_if(association_name, attributes)
+        assign_to_or_mark_for_destruction(record, attributes, options[:allow_destroy]) unless call_reject_if(association_name, attributes)
 
-      elsif attributes['id'].present? && !assignment_opts[:without_protection]
+      elsif attributes['id'].present?
         raise_nested_attributes_record_not_found(association_name, attributes['id'])
 
       elsif !reject_new_record?(association_name, attributes)
         method = "build_#{association_name}"
         if respond_to?(method)
-          send(method, attributes.except(*unassignable_keys(assignment_opts)), assignment_opts)
+          send(method, attributes.except(*UNASSIGNABLE_KEYS))
         else
-          raise ArgumentError, "Cannot build association #{association_name}. Are you trying to build a polymorphic one-to-one association?"
+          raise ArgumentError, "Cannot build association `#{association_name}'. Are you trying to build a polymorphic one-to-one association?"
         end
       end
     end
@@ -377,37 +348,48 @@ module ActiveRecord
     # For example:
     #
     #   assign_nested_attributes_for_collection_association(:people, {
-    #     '1' => { :id => '1', :name => 'Peter' },
-    #     '2' => { :name => 'John' },
-    #     '3' => { :id => '2', :_destroy => true }
+    #     '1' => { id: '1', name: 'Peter' },
+    #     '2' => { name: 'John' },
+    #     '3' => { id: '2', _destroy: true }
     #   })
     #
     # Will update the name of the Person with ID 1, build a new associated
-    # person with the name `John', and mark the associated Person with ID 2
+    # person with the name 'John', and mark the associated Person with ID 2
     # for destruction.
     #
     # Also accepts an Array of attribute hashes:
     #
     #   assign_nested_attributes_for_collection_association(:people, [
-    #     { :id => '1', :name => 'Peter' },
-    #     { :name => 'John' },
-    #     { :id => '2', :_destroy => true }
+    #     { id: '1', name: 'Peter' },
+    #     { name: 'John' },
+    #     { id: '2', _destroy: true }
     #   ])
-    def assign_nested_attributes_for_collection_association(association_name, attributes_collection, assignment_opts = {})
+    def assign_nested_attributes_for_collection_association(association_name, attributes_collection)
       options = self.nested_attributes_options[association_name]
 
       unless attributes_collection.is_a?(Hash) || attributes_collection.is_a?(Array)
         raise ArgumentError, "Hash or Array expected, got #{attributes_collection.class.name} (#{attributes_collection.inspect})"
       end
 
-      if options[:limit] && attributes_collection.size > options[:limit]
-        raise TooManyRecords, "Maximum #{options[:limit]} records are allowed. Got #{attributes_collection.size} records instead."
+      if limit = options[:limit]
+        limit = case limit
+        when Symbol
+          send(limit)
+        when Proc
+          limit.call
+        else
+          limit
+        end
+
+        if limit && attributes_collection.size > limit
+          raise TooManyRecords, "Maximum #{limit} records are allowed. Got #{attributes_collection.size} records instead."
+        end
       end
 
       if attributes_collection.is_a? Hash
         keys = attributes_collection.keys
         attributes_collection = if keys.include?('id') || keys.include?(:id)
-          Array.wrap(attributes_collection)
+          [attributes_collection]
         else
           attributes_collection.values
         end
@@ -419,7 +401,7 @@ module ActiveRecord
         association.target
       else
         attribute_ids = attributes_collection.map {|a| a['id'] || a[:id] }.compact
-        attribute_ids.empty? ? [] : association.scoped.where(association.klass.primary_key => attribute_ids)
+        attribute_ids.empty? ? [] : association.scope.where(association.klass.primary_key => attribute_ids)
       end
 
       attributes_collection.each do |attributes|
@@ -427,7 +409,7 @@ module ActiveRecord
 
         if attributes['id'].blank?
           unless reject_new_record?(association_name, attributes)
-            association.build(attributes.except(*unassignable_keys(assignment_opts)), assignment_opts)
+            association.build(attributes.except(*UNASSIGNABLE_KEYS))
           end
         elsif existing_record = existing_records.detect { |record| record.id.to_s == attributes['id'].to_s }
           unless association.loaded? || call_reject_if(association_name, attributes)
@@ -440,14 +422,11 @@ module ActiveRecord
             else
               association.add_to_target(existing_record)
             end
-
           end
 
           if !call_reject_if(association_name, attributes)
-            assign_to_or_mark_for_destruction(existing_record, attributes, options[:allow_destroy], assignment_opts)
+            assign_to_or_mark_for_destruction(existing_record, attributes, options[:allow_destroy])
           end
-        elsif assignment_opts[:without_protection]
-          association.build(attributes.except(*unassignable_keys(assignment_opts)), assignment_opts)
         else
           raise_nested_attributes_record_not_found(association_name, attributes['id'])
         end
@@ -456,8 +435,8 @@ module ActiveRecord
 
     # Updates a record with the +attributes+ or marks it for destruction if
     # +allow_destroy+ is +true+ and has_destroy_flag? returns +true+.
-    def assign_to_or_mark_for_destruction(record, attributes, allow_destroy, assignment_opts)
-      record.assign_attributes(attributes.except(*unassignable_keys(assignment_opts)), assignment_opts)
+    def assign_to_or_mark_for_destruction(record, attributes, allow_destroy)
+      record.assign_attributes(attributes.except(*UNASSIGNABLE_KEYS))
       record.mark_for_destruction if has_destroy_flag?(attributes) && allow_destroy
     end
 
@@ -470,12 +449,11 @@ module ActiveRecord
     # has_destroy_flag? or if a <tt>:reject_if</tt> proc exists for this
     # association and evaluates to +true+.
     def reject_new_record?(association_name, attributes)
-      will_be_destroyed?(association_name, attributes) || call_reject_if(association_name, attributes)
+      has_destroy_flag?(attributes) || call_reject_if(association_name, attributes)
     end
 
     def call_reject_if(association_name, attributes)
-      return false if will_be_destroyed?(association_name, attributes)
-
+      return false if has_destroy_flag?(attributes)
       case callback = self.nested_attributes_options[association_name][:reject_if]
       when Symbol
         method(callback).arity == 0 ? send(callback) : send(callback, attributes)
@@ -484,21 +462,8 @@ module ActiveRecord
       end
     end
 
-    # Only take into account the destroy flag if <tt>:allow_destroy</tt> is true
-    def will_be_destroyed?(association_name, attributes)
-      allow_destroy?(association_name) && has_destroy_flag?(attributes)
-    end
-
-    def allow_destroy?(association_name)
-      self.nested_attributes_options[association_name][:allow_destroy]
-    end
-
     def raise_nested_attributes_record_not_found(association_name, record_id)
       raise RecordNotFound, "Couldn't find #{self.class.reflect_on_association(association_name).klass.name} with ID=#{record_id} for #{self.class.name} with ID=#{id}"
     end
-
-    def unassignable_keys(assignment_opts)
-      assignment_opts[:without_protection] ? UNASSIGNABLE_KEYS - %w[id] : UNASSIGNABLE_KEYS
-    end
   end
 end