snusnu-dm-accepts_nested_attributes 0.0.1

data/.gitignore

@@ -0,0 +1,23 @@
+test_log
+pkg
+pkg/*
+*/pkg/*
+bundle
+bundle/*
+doc
+*.log
+log
+!log*.rb
+*/log
+log/*
+*/log/*
+coverage
+*/coverage
+lib/dm-more.rb
+*.db
+nbproject
+.DS_Store
+rspec_report.html
+*.swp
+_Yardoc
+*/ri

data/History.txt

@@ -0,0 +1 @@
+

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Martin Gamsjäger
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,29 @@
+.gitignore
+History.txt
+LICENSE
+Manifest.txt
+README.textile
+Rakefile
+TODO
+lib/dm-accepts_nested_attributes.rb
+lib/dm-accepts_nested_attributes/associations.rb
+lib/dm-accepts_nested_attributes/nested_attributes.rb
+lib/dm-accepts_nested_attributes/version.rb
+spec/fixtures/person.rb
+spec/fixtures/profile.rb
+spec/fixtures/project.rb
+spec/fixtures/project_membership.rb
+spec/fixtures/task.rb
+spec/integration/belongs_to_spec.rb
+spec/integration/has_1_spec.rb
+spec/integration/has_n_spec.rb
+spec/integration/has_n_through_spec.rb
+spec/shared/rspec_tmbundle_support.rb
+spec/spec.opts
+spec/spec_helper.rb
+spec/unit/accepts_nested_attributes_for_spec.rb
+spec/unit/resource_spec.rb
+tasks/gemspec.rb
+tasks/hoe.rb
+tasks/install.rb
+tasks/spec.rb

data/README.textile

@@ -0,0 +1,250 @@
+h2. dm-accepts_nested_attributes
+
+A DataMapper plugin that allows nested model attribute assignment like activerecord does.
+
+At the end of this file, you can see a list of all current integration specs.
+
+For more information on the progress, have a look at this README and also at
+"this article":http://sick.snusnu.info/2009/04/08/dm-accepts_nested_attributes/ on my blog, where I will try to comment on the
+development (problems).
+
+h3. Why isn't this implemented as options on association declarations?
+
+* I somehow like the declarative style of @accepts_nested_attributes_for@ better. it jumps out immediately.
+* The API for datamapper and activerecord is the same.
+* association definitions can already get quite long and "unreadable". chances are you overlook it!
+
+h3. Why doesn't accepts_nested_attributes_for take more than one association_name?
+
+While writing the unit specs for this method, I realised that there are way too many ways to call this
+method, which makes it "hard" to spec all possible calls. That's why I started to list Pros and Cons, and
+decided to support only one @association_name@ per call, at least for now.
+
+h4. Pros
+
+* less complex code
+* fewer ways to call the method (simpler to understand, easier to spec)
+* easier to read (nr of calls == nr of accessible associations, this could be seen as a con also)
+* easier (and more extensible) option handling
+** options don't implicitly apply to _all_ associations (could be seen as a con also?)
+** options can explicitly be applied to _only the desired_ associations
+** reject_if option maybe often makes more sense on exactly _one_ associaton (maybe not?)
+* no question what happens if the association_name is invalid (the whole call is invalid)
+** with at least one _invalid_ association_name, what happens for the other _valid_ ones?  
+
+h4. Cons
+
+* needs more method calls (overhead should be minimal)
+* options that apply to more than one attribute need to be duplicated (maybe a Pro because of readability)
+
+h3. Examples
+
+The following example illustrates the use of this plugin.
+
+<pre>
+<code>
+require "rubygems"
+
+gem 'dm-core',                      '0.9.11'
+gem 'dm-validations',               '0.9.11'
+gem 'dm-accepts_nested_attributes', '0.0.1'
+
+require "dm-core"
+require "dm-validations"
+require "dm-accepts_nested_attributes"
+
+DataMapper::Logger.new(STDOUT, :debug)  
+DataMapper.setup(:default, 'sqlite3::memory:')
+  
+class Person
+  include DataMapper::Resource
+  property :id,   Serial
+  property :name, String
+  has 1, :profile
+  has n, :project_memberships
+  has n, :projects, :through => :project_memberships
+  accepts_nested_attributes_for :profile
+  accepts_nested_attributes_for :projects
+  
+  # adds the following instance methods
+  # #profile_attributes
+  # #projects_attributes
+end
+
+class Profile
+  include DataMapper::Resource
+  property :id,      Serial
+  property :person_id, Integer
+  belongs_to :person
+  accepts_nested_attributes_for :person
+  
+  # adds the following instance methods
+  # #person_attributes
+end
+
+class Project
+  include DataMapper::Resource
+  property :id, Serial
+  has n, :tasks
+  has n, :project_memberships
+  has n, :people, :through => :project_memberships
+  accepts_nested_attributes_for :tasks
+  accepts_nested_attributes_for :people
+  
+  # adds the following instance methods
+  # #tasks_attributes
+  # #people_attributes
+end
+
+class ProjectMembership
+  include DataMapper::Resource
+  property :id,         Serial
+  property :person_id,  Integer
+  property :project_id, Integer
+  belongs_to :person
+  belongs_to :project
+  
+  # nothing added here
+  # code only listed to provide complete example env
+end
+
+class Task
+  include DataMapper::Resource
+  property :id,         Serial
+  property :project_id, Integer
+  belongs_to :project
+  
+  # nothing added here
+  # code only listed to provide complete example env
+end
+
+DataMapper.auto_migrate!
+</code>
+</pre>
+
+h2. Current Integration Specs
+
+<pre>
+<code>
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person)
+- should allow to create a new person via Profile#person_attributes
+- should allow to update an existing person via Profile#person_attributes
+- should not allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person, :allow_destroy => false)
+- should allow to create a new person via Profile#person_attributes
+- should allow to update an existing person via Profile#person_attributes
+- should not allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for(:person, :allow_destroy = true)
+- should allow to create a new person via Profile#person_attributes
+- should allow to update an existing person via Profile#person_attributes
+- should allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => :foo
+- should allow to create a new person via Profile#person_attributes
+- should allow to update an existing person via Profile#person_attributes
+- should not allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => lambda { |attrs| true }
+- should not allow to create a new person via Profile#person_attributes
+- should not allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Profile.belongs_to(:person) accepts_nested_attributes_for :person,  :reject_if => lambda { |attrs| false }
+- should allow to create a new person via Profile#person_attributes
+- should allow to update an existing person via Profile#person_attributes
+- should not allow to delete an existing person via Profile#person_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile)
+- should allow to create a new profile via Person#profile_attributes
+- should allow to update an existing profile via Person#profile_attributes
+- should not allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile, :allow_destroy => false)
+- should allow to create a new profile via Person#profile_attributes
+- should allow to update an existing profile via Person#profile_attributes
+- should not allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for(:profile, :allow_destroy => true)
+- should allow to create a new profile via Person#profile_attributes
+- should allow to update an existing profile via Person#profile_attributes
+- should allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => :foo
+- should allow to create a new profile via Person#profile_attributes
+- should allow to update an existing profile via Person#profile_attributes
+- should not allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => lambda { |attrs| true }
+- should not allow to create a new profile via Person#profile_attributes
+- should not allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Person.has(1, :profile) accepts_nested_attributes_for :profile,  :reject_if => lambda { |attrs| false }
+- should allow to create a new profile via Person#profile_attributes
+- should allow to update an existing profile via Person#profile_attributes
+- should not allow to delete an existing profile via Person#profile_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks)
+- should allow to create a new task via Project#tasks_attributes
+- should allow to update an existing task via Project#tasks_attributes
+- should not allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks, :allow_destroy => false)
+- should allow to create a new task via Project#tasks_attributes
+- should allow to update an existing task via Project#tasks_attributes
+- should not allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for(:tasks, :allow_destroy => true)
+- should allow to create a new task via Project#tasks_attributes
+- should allow to update an existing task via Project#tasks_attributes
+- should allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => :foo
+- should allow to create a new task via Project#tasks_attributes
+- should allow to update an existing task via Project#tasks_attributes
+- should not allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => lambda { |attrs| true }
+- should not allow to create a new task via Project#tasks_attributes
+- should not allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Project.has(n, :tasks) accepts_nested_attributes_for :tasks,  :reject_if => lambda { |attrs| false }
+- should allow to create a new task via Project#tasks_attributes
+- should allow to update an existing task via Project#tasks_attributes
+- should not allow to delete an existing task via Profile#tasks_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects)
+- should allow to create a new project via Person#projects_attributes
+- should allow to update an existing project via Person#projects_attributes
+- should not allow to delete an existing project via Person#projects_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects, :allow_destroy => false)
+- should allow to create a new project via Person#projects_attributes
+- should allow to update an existing project via Person#projects_attributes
+- should not allow to delete an existing project via Person#projects_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for(:projects, :allow_destroy = true)
+- should allow to create a new project via Person#projects_attributes
+- should allow to update an existing project via Person#projects_attributes
+- should allow to delete an existing project via Person#projects_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => :foo
+- should allow to create a new project via Person#projects_attributes
+- should allow to update an existing project via Person#projects_attributes
+- should not allow to delete an existing project via Person#projects_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => lambda { |attrs| true }
+- should not allow to create a new project via Person#projects_attributes
+- should not allow to delete an existing project via Person#projects_attributes
+
+DataMapper::NestedAttributes Person.has(n, :projects, :through => :project_memberships) accepts_nested_attributes_for :projects,  :reject_if => lambda { |attrs| false }
+- should allow to create a new project via Person#projects_attributes
+- should allow to update an existing project via Person#projects_attributes
+- should not allow to delete an existing project via Person#projects_attributes
+</code>
+</pre>
+
+h2. TODO
+
+* add more specs and fix bugs
+* Adapt to datamapper/next

data/Rakefile

@@ -0,0 +1,32 @@
+require 'pathname'
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+ 
+ROOT = Pathname(__FILE__).dirname.expand_path
+JRUBY = RUBY_PLATFORM =~ /java/
+WINDOWS = Gem.win_platform?
+SUDO = (WINDOWS || JRUBY) ? '' : ('sudo' unless ENV['SUDOLESS'])
+ 
+require ROOT + 'lib/dm-accepts_nested_attributes/version'
+ 
+AUTHOR = "Martin Gamsjäger"
+EMAIL  = "gamsnjaga [a] gmail [d] com"
+GEM_NAME = "dm-accepts_nested_attributes"
+GEM_VERSION = DataMapper::NestedAttributes::VERSION
+
+GEM_DEPENDENCIES = [
+  ["dm-core",         '>=0.9.11'],
+  ['addressable',     '~>2.0.2' ]
+]
+
+GEM_CLEAN = %w[ log pkg coverage ]
+GEM_EXTRAS = { :has_rdoc => true, :extra_rdoc_files => %w[ README.textile LICENSE TODO History.txt ] }
+
+PROJECT_NAME = "dm-accepts_nested_attributes"
+PROJECT_URL  = "http://github.com/snusnu/dm-accepts_nested_attributes/tree/master"
+PROJECT_DESCRIPTION = PROJECT_SUMMARY = %{
+A DataMapper plugin that adds the possibility to perform nested model attribute assignment
+}
+ 
+Pathname.glob(ROOT.join('tasks/**/*.rb').to_s).each { |f| require f }

data/TODO

@@ -0,0 +1,3 @@
+TODO
+====
+

data/lib/dm-accepts_nested_attributes.rb

@@ -0,0 +1,18 @@
+# Needed to import datamapper and other gems
+require 'rubygems'
+require 'pathname'
+
+# Add all external dependencies for the plugin here
+gem 'dm-core',          '>=0.9.11'
+gem 'dm-validations',   '>=0.9.11'
+
+require 'dm-core'
+require 'dm-validations'
+
+# Require plugin-files
+require Pathname(__FILE__).dirname.expand_path / 'dm-accepts_nested_attributes' / 'nested_attributes'
+# monkeypatches for dm-core/associations/(many_to_one.rb and one_to_many.rb)
+require Pathname(__FILE__).dirname.expand_path / 'dm-accepts_nested_attributes' / 'associations'
+
+# Include the plugin in Model
+DataMapper::Resource.append_inclusions DataMapper::NestedAttributes

data/lib/dm-accepts_nested_attributes/associations.rb

@@ -0,0 +1,55 @@
+module DataMapper
+  module Associations
+    
+    module ManyToOne
+      
+      class Proxy
+        
+        def save
+          
+          return false if @parent.nil?
+          
+          # original dm-core-0.9.11 code:
+          # return true unless parent.new_record?
+          
+          # and the backwards compatible extension to it (allows update of belongs_to model)
+          if !parent.new_record? && !@relationship.child_model.autosave_associations.key?(@relationship.name)
+            return true
+          end
+
+          @relationship.with_repository(parent) do
+            result = parent.marked_for_destruction? ? parent.destroy : parent.save
+            @relationship.child_key.set(@child, @relationship.parent_key.get(parent)) if result
+            result
+          end
+          
+        end
+        
+      end
+      
+    end
+    
+    
+    module OneToMany
+    
+      class Proxy
+        
+        private
+        
+        def save_resource(resource, parent = @parent)
+          @relationship.with_repository(resource) do |r|
+            if parent.nil? && resource.model.respond_to?(:many_to_many)
+              resource.destroy
+            else
+              @relationship.attach_parent(resource, parent)
+              resource.marked_for_destruction? ? resource.destroy : resource.save
+            end
+          end
+        end
+        
+      end
+      
+    end
+    
+  end
+end

data/lib/dm-accepts_nested_attributes/nested_attributes.rb

@@ -0,0 +1,300 @@
+module DataMapper
+  module NestedAttributes
+    
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_inheritable_accessor :autosave_associations
+      base.autosave_associations = {}
+    end
+    
+    module ClassMethods
+      
+      # 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.
+      #
+      # Supported options:
+      # [:allow_destroy]
+      # If true, destroys any members from the attributes hash with a
+      # <tt>_delete</tt> key and a value that evaluates to +true+
+      # (eg. 1, '1', true, or 'true'). This option is off by default.
+      # [:reject_if]
+      # Allows you to specify a Proc that checks whether a record should be
+      # built for a certain attribute hash. The hash is passed to the Proc
+      # and the Proc should return either +true+ or +false+. When no Proc
+      # is specified a record will be built for all attribute hashes that
+      # do not have a <tt>_delete</tt> that evaluates to true.
+      #
+      # Examples:
+      # # creates avatar_attributes=
+      # accepts_nested_attributes_for :avatar, :reject_if => proc { |attributes| attributes['name'].blank? }
+      # # creates avatar_attributes= and posts_attributes=
+      # accepts_nested_attributes_for :avatar, :posts, :allow_destroy => true
+      def accepts_nested_attributes_for(association_name, options = {})
+        
+        assert_kind_of 'association_name', association_name, Symbol, String
+        assert_kind_of 'options',          options,          Hash
+        
+        options = { :allow_destroy => false }.update(options)
+        
+        # raises if the specified option keys aren't valid
+        assert_valid_autosave_options(options)
+        
+        # raises if the specified association doesn't exist
+        # we don't need the return value here, just the check
+        # ------------------------------------------------------
+        # also, when using the return value from this call to
+        # replace association_name with association.name,
+        # has(1, :through) are broken, because they seem to have
+        # a different name
+        
+        association_for_name(association_name)
+        
+        autosave_associations[association_name] = options
+        
+        type = nr_of_possible_child_instances(association_name) > 1 ? :collection : :one_to_one
+        
+        class_eval %{
+          
+          def #{association_name}_attributes=(attributes)
+            assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes, #{options[:allow_destroy]})
+          end
+          
+          if association_type(:#{association_name}) == :many_to_one || association_type(:#{association_name}) == :one_to_one
+          
+            def get_#{association_name}
+              #{association_name.to_s} || self.class.associated_model_for_name(:#{association_name}).new
+            end
+          
+          end
+          
+        }, __FILE__, __LINE__ + 1
+        
+      end
+      
+      def reject_new_nested_attributes_proc_for(association_name)
+        autosave_associations[association_name] ? autosave_associations[association_name][:reject_if] : nil
+      end
+      
+      
+      # utility methods
+      
+      def nr_of_possible_child_instances(association_name, repository = :default)
+        # belongs_to seems to generate no options[:max]
+        association_for_name(association_name, repository).options[:max] || 1
+      end
+
+      # i have the feeling this should be refactored
+      def associated_model_for_name(association_name, repository = :default)
+        a = association_for_name(association_name, repository)
+        case association_type(association_name)
+        when :many_to_one
+          a.parent_model
+        when :one_to_one
+          a.child_model
+        when :one_to_many
+          a.child_model
+        when :many_to_many
+          Object.full_const_get(a.options[:child_model])
+        else
+          raise ArgumentError, "Unknown association type #{a.inspect}"
+        end
+      end
+      
+      # maybe this should be provided by dm-core somehow
+      # DataMapper::Association::Relationship would be a place maybe?
+      def association_type(association_name)
+        a = association_for_name(association_name)
+        if a.options[:max].nil? # belongs_to
+          :many_to_one
+        elsif a.options[:max] == 1 # has(1)
+          :one_to_one
+        elsif a.options[:max] > 1 && !a.is_a?(DataMapper::Associations::RelationshipChain) # has(n)
+          :one_to_many
+        elsif a.is_a?(DataMapper::Associations::RelationshipChain) # has(n, :through) MUST be checked after has(n) here
+          :many_to_many
+        else
+          raise ArgumentError, "Unknown association type #{a.inspect}"
+        end
+      end
+
+      # avoid nil access by always going through this
+      # this method raises if the association named name is not established in this model
+      def association_for_name(name, repository = :default)
+        association = self.relationships(repository)[name]
+        # TODO think about using a specific Error class like UnknownAssociationError
+        raise(ArgumentError, "Relationship #{name.inspect} does not exist in \#{model}") unless association
+        association
+      end
+      
+      private
+      
+      # think about storing valid options in a classlevel constant
+      def assert_valid_autosave_options(options)
+        unless options.all? { |k,v| [ :allow_destroy, :reject_if ].include?(k) }
+          raise ArgumentError, 'accepts_nested_attributes_for only takes :allow_destroy and :reject_if as options'
+        end
+      end
+  
+    end
+    
+    
+    # instance methods
+    
+    # returns nil if no resource has been associated yet
+    def associated_instance_get(association_name, repository = :default)
+      send(self.class.association_for_name(association_name, repository).name)
+    end
+    
+    # Reloads the attributes of the object as usual and removes a mark for destruction.
+    def reload
+      @marked_for_destruction = false
+      super
+    end
+    
+    def marked_for_destruction?
+      @marked_for_destruction
+    end
+    
+    def mark_for_destruction
+      @marked_for_destruction = true
+    end
+
+
+    private
+
+    # Attribute hash keys that should not be assigned as normal attributes.
+    # These hash keys are nested attributes implementation details.
+    UNASSIGNABLE_KEYS = [ :id, :_delete ]
+    
+    
+    # Assigns the given attributes to the association.
+    #
+    # If the given attributes include an <tt>:id</tt> that matches the existing
+    # record’s id, then the existing record will be modified. Otherwise a new
+    # record will be built.
+    #
+    # If the given attributes include a matching <tt>:id</tt> attribute _and_ a
+    # <tt>:_delete</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, allow_destroy)
+      if attributes[:id].blank?
+        unless reject_new_record?(association_name, attributes)
+          model = self.class.associated_model_for_name(association_name)
+          send("#{association_name}=", model.new(attributes.except(*UNASSIGNABLE_KEYS)))
+        end
+      else (existing_record = associated_instance_get(association_name)) && existing_record.id.to_s == attributes[:id].to_s
+        assign_to_or_mark_for_destruction(association_name, existing_record, attributes, allow_destroy)
+      end
+    end
+    
+    # Assigns the given attributes to the collection association.
+    #
+    # Hashes with an <tt>:id</tt> value matching an existing associated record
+    # will update that record. Hashes without an <tt>:id</tt> value will build
+    # a new record for the association. Hashes with a matching <tt>:id</tt>
+    # value and a <tt>:_delete</tt> key set to a truthy value will mark the
+    # matched record for destruction.
+    #
+    # For example:
+    #
+    # assign_nested_attributes_for_collection_association(:people, {
+    # '1' => { :id => '1', :name => 'Peter' },
+    # '2' => { :name => 'John' },
+    # '3' => { :id => '2', :_delete => true }
+    # })
+    #
+    # Will update the name of the Person with ID 1, build a new associated
+    # person with the name `John', and mark the associatied 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', :_delete => true }
+    # ])
+    def assign_nested_attributes_for_collection_association(association_name, attributes_collection, allow_destroy)
+      
+      assert_kind_of 'association_name',      association_name,      Symbol
+      assert_kind_of 'attributes_collection', attributes_collection, Hash, Array
+       
+      if attributes_collection.is_a? Hash
+        attributes_collection = attributes_collection.sort_by { |index, _| index.to_i }.map { |_, attributes| attributes }
+      end
+       
+      attributes_collection.each do |attributes|
+        if attributes[:id].blank?
+          unless reject_new_record?(association_name, attributes)
+            case self.class.association_type(association_name)
+            when :one_to_many
+              build_new_has_n_association(association_name, attributes)
+            when :many_to_many
+              build_new_has_n_through_association(association_name, attributes)
+            end
+          end
+        elsif existing_record = send(association_name).detect { |record| record.id.to_s == attributes[:id].to_s }
+          assign_to_or_mark_for_destruction(association_name, existing_record, attributes, allow_destroy)
+        end
+      end
+      
+    end
+    
+    def build_new_has_n_association(association_name, attributes)
+      send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+    end
+        
+    def build_new_has_n_through_association(association_name, attributes)
+      # fetch the association to have the information ready
+      association = self.class.association_for_name(association_name)
+      
+      # do what's done in dm-core/specs/integration/association_through_spec.rb
+      
+      # explicitly build the join entry and assign it to the join association
+      join_entry = Extlib::Inflection.constantize(Extlib::Inflection.classify(association.name)).new
+      self.send(association.name) << join_entry
+      self.save
+      # explicitly build the child entry and assign the join entry to its join association
+      child_entry = self.class.associated_model_for_name(association_name).new(attributes)
+      child_entry.send(association.name) << join_entry
+      child_entry.save
+    end
+    
+    # Updates a record with the +attributes+ or marks it for destruction if
+    # +allow_destroy+ is +true+ and has_delete_flag? returns +true+.
+    def assign_to_or_mark_for_destruction(association_name, record, attributes, allow_destroy)
+      if has_delete_flag?(attributes) && allow_destroy
+        if self.class.association_type(association_name) == :many_to_many
+          # destroy the join record
+          record.send(self.class.association_for_name(association_name).name).destroy!
+          # destroy the child record
+          record.destroy
+        else
+          record.mark_for_destruction
+        end
+      else
+        record.attributes = attributes.except(*UNASSIGNABLE_KEYS)
+        if self.class.association_type(association_name) == :many_to_many
+          record.save
+        end
+      end
+    end
+    
+    # Determines if a hash contains a truthy _delete key.
+    def has_delete_flag?(hash)
+      # TODO find out if this activerecord code needs to be ported
+      # ConnectionAdapters::Column.value_to_boolean hash['_delete']
+      hash[:_delete]
+    end
+    
+    # Determines if a new record should be build by checking for
+    # has_delete_flag? or if a <tt>:reject_if</tt> proc exists for this
+    # association and evaluates to +true+.
+    def reject_new_record?(association_name, attributes)
+      guard = self.class.reject_new_nested_attributes_proc_for(association_name)
+      has_delete_flag?(attributes) || (guard.respond_to?(:call) && guard.call(attributes))
+    end
+
+  end
+end