activerecord 2.2.3 → 2.3.2

data/lib/active_record/locale/en.yml

@@ -37,7 +37,7 @@ en:
       #           blank: "This is a custom blank message for User login"
       # Will define custom blank validation message for User model and 
       # custom blank validation message for login attribute of User model.
-      models:
+      #models:
         
     # Translate model names. Used in Model.human_name().
     #models:

data/lib/active_record/locking/optimistic.rb

@@ -23,6 +23,16 @@ module ActiveRecord
     #   p2.first_name = "should fail"
     #   p2.save # Raises a ActiveRecord::StaleObjectError
     #
+    # Optimistic locking will also check for stale data when objects are destroyed.  Example:
+    #
+    #   p1 = Person.find(1)
+    #   p2 = Person.find(1)
+    #
+    #   p1.first_name = "Michael"
+    #   p1.save
+    #
+    #   p2.destroy # Raises a ActiveRecord::StaleObjectError
+    #
     # You're then responsible for dealing with the conflict by rescuing the exception and either rolling back, merging,
     # or otherwise apply the business logic needed to resolve the conflict.
     #
@@ -39,6 +49,7 @@ module ActiveRecord
         base.lock_optimistically = true
 
         base.alias_method_chain :update, :lock
+        base.alias_method_chain :destroy, :lock
         base.alias_method_chain :attributes_from_column_definition, :lock
 
         class << base
@@ -98,6 +109,28 @@ module ActiveRecord
           end
         end
 
+  def destroy_with_lock #:nodoc:
+    return destroy_without_lock unless locking_enabled?
+
+    unless new_record?
+      lock_col = self.class.locking_column
+      previous_value = send(lock_col).to_i
+
+      affected_rows = connection.delete(
+        "DELETE FROM #{self.class.quoted_table_name} " +
+        "WHERE #{connection.quote_column_name(self.class.primary_key)} = #{quoted_id} " +
+              "AND #{self.class.quoted_locking_column} = #{quote_value(previous_value)}",
+        "#{self.class.name} Destroy"
+      )
+
+      unless affected_rows == 1
+        raise ActiveRecord::StaleObjectError, "Attempted to delete a stale object"
+      end
+    end
+
+    freeze
+  end
+
       module ClassMethods
         DEFAULT_LOCKING_COLUMN = 'lock_version'
 

data/lib/active_record/migration.rb

@@ -130,7 +130,9 @@ module ActiveRecord
   # To run migrations against the currently configured database, use
   # <tt>rake db:migrate</tt>. This will update the database by running all of the
   # pending migrations, creating the <tt>schema_migrations</tt> table
-  # (see "About the schema_migrations table" section below) if missing.
+  # (see "About the schema_migrations table" section below) if missing. It will also 
+  # invoke the db:schema:dump task, which will update your db/schema.rb file
+  # to match the structure of your database.
   #
   # To roll the database back to a previous migration version, use
   # <tt>rake db:migrate VERSION=X</tt> where <tt>X</tt> is the version to which
@@ -336,6 +338,10 @@ module ActiveRecord
         self.verbose = save
       end
 
+      def connection
+        ActiveRecord::Base.connection
+      end
+
       def method_missing(method, *arguments, &block)
         arg_list = arguments.map(&:inspect) * ', '
 
@@ -343,7 +349,7 @@ module ActiveRecord
           unless arguments.empty? || method == :execute
             arguments[0] = Migrator.proper_table_name(arguments.first)
           end
-          ActiveRecord::Base.connection.send(method, *arguments, &block)
+          connection.send(method, *arguments, &block)
         end
       end
     end

data/lib/active_record/named_scope.rb

@@ -1,11 +1,12 @@
 module ActiveRecord
   module NamedScope
-    # All subclasses of ActiveRecord::Base have two named \scopes:
-    # * <tt>all</tt> - which is similar to a <tt>find(:all)</tt> query, and
+    # All subclasses of ActiveRecord::Base have one named scope:
     # * <tt>scoped</tt> - which allows for the creation of anonymous \scopes, on the fly: <tt>Shirt.scoped(:conditions => {:color => 'red'}).scoped(:include => :washing_instructions)</tt>
     #
     # These anonymous \scopes tend to be useful when procedurally generating complex queries, where passing
     # intermediate values (scopes) around as first-class objects is convenient.
+    #
+    # You can define a scope that applies to all finders using ActiveRecord::Base.default_scope.
     def self.included(base)
       base.class_eval do
         extend ClassMethods
@@ -39,7 +40,7 @@ module ActiveRecord
       # Nested finds and calculations also work with these compositions: <tt>Shirt.red.dry_clean_only.count</tt> returns the number of garments
       # for which these criteria obtain. Similarly with <tt>Shirt.red.dry_clean_only.average(:thread_count)</tt>.
       #
-      # All \scopes are available as class methods on the ActiveRecord::Base descendent upon which the \scopes were defined. But they are also available to
+      # All \scopes are available as class methods on the ActiveRecord::Base descendant upon which the \scopes were defined. But they are also available to
       # <tt>has_many</tt> associations. If,
       #
       #   class Person < ActiveRecord::Base
@@ -88,7 +89,12 @@ module ActiveRecord
             when Hash
               options
             when Proc
-              options.call(*args)
+              case parent_scope
+              when Scope
+                with_scope(:find => parent_scope.proxy_options) { options.call(*args) }
+              else
+                options.call(*args)
+              end
           end, &block)
         end
         (class << self; self end).instance_eval do
@@ -98,7 +104,7 @@ module ActiveRecord
         end
       end
     end
-    
+
     class Scope
       attr_reader :proxy_scope, :proxy_options, :current_scoped_methods_when_defined
       NON_DELEGATE_METHODS = %w(nil? send object_id class extend find size count sum average maximum minimum paginate first last empty? any? respond_to?).to_set
@@ -111,6 +117,7 @@ module ActiveRecord
       delegate :scopes, :with_scope, :to => :proxy_scope
 
       def initialize(proxy_scope, options, &block)
+        options ||= {}
         [options[:extend]].flatten.each { |extension| extend extension } if options[:extend]
         extend Module.new(&block) if block_given?
         unless Scope === proxy_scope
@@ -169,7 +176,7 @@ module ActiveRecord
         if scopes.include?(method)
           scopes[method].call(self, *args)
         else
-          with_scope :find => proxy_options, :create => proxy_options[:conditions].is_a?(Hash) ?  proxy_options[:conditions] : {} do
+          with_scope({:find => proxy_options, :create => proxy_options[:conditions].is_a?(Hash) ?  proxy_options[:conditions] : {}}, :reverse_merge) do
             method = :new if method == :build
             if current_scoped_methods_when_defined
               with_scope current_scoped_methods_when_defined do

data/lib/active_record/nested_attributes.rb

@@ -0,0 +1,329 @@
+module ActiveRecord
+  module NestedAttributes #:nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_inheritable_accessor :reject_new_nested_attributes_procs, :instance_writer => false
+      base.reject_new_nested_attributes_procs = {}
+    end
+
+    # == 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.
+    #
+    # The attribute writer is named after the association, which means that
+    # in the following example, two new methods are added to your model:
+    # <tt>author_attributes=(attributes)</tt> and
+    # <tt>pages_attributes=(attributes)</tt>.
+    #
+    #   class Book < ActiveRecord::Base
+    #     has_one :author
+    #     has_many :pages
+    #
+    #     accepts_nested_attributes_for :author, :pages
+    #   end
+    #
+    # Note that the <tt>:autosave</tt> option is automatically enabled on every
+    # association that accepts_nested_attributes_for is used for.
+    #
+    # === One-to-one
+    #
+    # Consider a Member model that has one Avatar:
+    #
+    #   class Member < ActiveRecord::Base
+    #     has_one :avatar
+    #     accepts_nested_attributes_for :avatar
+    #   end
+    #
+    # 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' } } }
+    #   member = Member.create(params)
+    #   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']
+    #   member.avatar.icon # => 'sad'
+    #
+    # By default you will only be able to set and update attributes on the
+    # associated model. If you want to destroy the associated model through the
+    # attributes hash, you have to enable it first using the
+    # <tt>:allow_destroy</tt> option.
+    #
+    #   class Member < ActiveRecord::Base
+    #     has_one :avatar
+    #     accepts_nested_attributes_for :avatar, :allow_destroy => true
+    #   end
+    #
+    # Now, when you add the <tt>_delete</tt> key to the attributes hash, with a
+    # value that evaluates to +true+, you will destroy the associated model:
+    #
+    #   member.avatar_attributes = { :id => '2', :_delete => '1' }
+    #   member.avatar.marked_for_destruction? # => true
+    #   member.save
+    #   member.avatar #=> nil
+    #
+    # Note that the model will _not_ be destroyed until the parent is saved.
+    #
+    # === One-to-many
+    #
+    # Consider a member that has a number of posts:
+    #
+    #   class Member < ActiveRecord::Base
+    #     has_many :posts
+    #     accepts_nested_attributes_for :posts
+    #   end
+    #
+    # 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>_delete</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 => '', :_delete => '1' } # this will be ignored
+    #     ]
+    #   }}
+    #
+    #   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'
+    #
+    # You may also set a :reject_if proc to silently ignore any new record
+    # 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
+    #
+    #   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.posts.length # => 2
+    #   member.posts.first.title # => 'Kari, the awesome Ruby documentation browser!'
+    #   member.posts.second.title # => 'The egalitarian assumption of the modern citizen'
+    #
+    # 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' }
+    #     ]
+    #   }
+    #
+    #   member.posts.first.title # => '[UPDATED] An, as of yet, undisclosed awesome Ruby documentation browser!'
+    #   member.posts.second.title # => '[UPDATED] other post'
+    #
+    # By default the associated records are protected from being destroyed. If
+    # you want to destroy any of the associated records through the attributes
+    # hash, you have to enable it first using the <tt>:allow_destroy</tt>
+    # option. This will allow you to also use the <tt>_delete</tt> key to
+    # destroy existing records:
+    #
+    #   class Member < ActiveRecord::Base
+    #     has_many :posts
+    #     accepts_nested_attributes_for :posts, :allow_destroy => true
+    #   end
+    #
+    #   params = { :member => {
+    #     :posts_attributes => [{ :id => '2', :_delete => '1' }]
+    #   }}
+    #
+    #   member.attributes = params['member']
+    #   member.posts.detect { |p| p.id == 2 }.marked_for_destruction? # => true
+    #   member.posts.length #=> 2
+    #   member.save
+    #   member.posts.length # => 1
+    #
+    # === Saving
+    #
+    # All changes to models, including the destruction of those marked for
+    # destruction, are saved and destroyed automatically and atomically when
+    # the parent model is saved. This happens inside the transaction initiated
+    # by the parents save method. See ActiveRecord::AutosaveAssociation.
+    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(*attr_names)
+        options = { :allow_destroy => false }
+        options.update(attr_names.extract_options!)
+        options.assert_valid_keys(:allow_destroy, :reject_if)
+
+        attr_names.each do |association_name|
+          if reflection = reflect_on_association(association_name)
+            type = case reflection.macro
+            when :has_one, :belongs_to
+              :one_to_one
+            when :has_many, :has_and_belongs_to_many
+              :collection
+            end
+
+            reflection.options[:autosave] = true
+            self.reject_new_nested_attributes_procs[association_name.to_sym] = options[:reject_if]
+
+            # def pirate_attributes=(attributes)
+            #   assign_nested_attributes_for_one_to_one_association(:pirate, attributes, false)
+            # end
+            class_eval %{
+              def #{association_name}_attributes=(attributes)
+                assign_nested_attributes_for_#{type}_association(:#{association_name}, attributes, #{options[:allow_destroy]})
+              end
+            }, __FILE__, __LINE__
+          else
+            raise ArgumentError, "No association found for name `#{association_name}'. Has it been defined yet?"
+          end
+        end
+      end
+    end
+
+    # Returns ActiveRecord::AutosaveAssociation::marked_for_destruction? It's
+    # used in conjunction with fields_for to build a form element for the
+    # destruction of this association.
+    #
+    # See ActionView::Helpers::FormHelper::fields_for for more info.
+    def _delete
+      marked_for_destruction?
+    end
+
+    private
+
+    # Attribute hash keys that should not be assigned as normal attributes.
+    # These hash keys are nested attributes implementation details.
+    UNASSIGNABLE_KEYS = %w{ 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)
+      attributes = attributes.stringify_keys
+
+      if attributes['id'].blank?
+        unless reject_new_record?(association_name, attributes)
+          send("build_#{association_name}", attributes.except(*UNASSIGNABLE_KEYS))
+        end
+      elsif (existing_record = send(association_name)) && existing_record.id.to_s == attributes['id'].to_s
+        assign_to_or_mark_for_destruction(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)
+      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 attributes_collection.is_a? Hash
+        attributes_collection = attributes_collection.sort_by { |index, _| index.to_i }.map { |_, attributes| attributes }
+      end
+
+      attributes_collection.each do |attributes|
+        attributes = attributes.stringify_keys
+
+        if attributes['id'].blank?
+          unless reject_new_record?(association_name, attributes)
+            send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+          end
+        elsif existing_record = send(association_name).detect { |record| record.id.to_s == attributes['id'].to_s }
+          assign_to_or_mark_for_destruction(existing_record, attributes, allow_destroy)
+        end
+      end
+    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(record, attributes, allow_destroy)
+      if has_delete_flag?(attributes) && allow_destroy
+        record.mark_for_destruction
+      else
+        record.attributes = attributes.except(*UNASSIGNABLE_KEYS)
+      end
+    end
+
+    # Determines if a hash contains a truthy _delete key.
+    def has_delete_flag?(hash)
+      ConnectionAdapters::Column.value_to_boolean 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)
+      has_delete_flag?(attributes) ||
+        self.class.reject_new_nested_attributes_procs[association_name].try(:call, attributes)
+    end
+  end
+end