activerecord 3.2.22.4 → 4.0.13

data/lib/active_record/transactions.rb

@@ -4,6 +4,7 @@ module ActiveRecord
   # See ActiveRecord::Transactions::ClassMethods for documentation.
   module Transactions
     extend ActiveSupport::Concern
+    ACTIONS = [:create, :destroy, :update]
 
     class TransactionError < ActiveRecordError # :nodoc:
     end
@@ -108,10 +109,10 @@ module ActiveRecord
     #
     #   # Suppose that we have a Number model with a unique column called 'i'.
     #   Number.transaction do
-    #     Number.create(:i => 0)
+    #     Number.create(i: 0)
     #     begin
     #       # This will raise a unique constraint error...
-    #       Number.create(:i => 0)
+    #       Number.create(i: 0)
     #     rescue ActiveRecord::StatementInvalid
     #       # ...which we ignore.
     #     end
@@ -119,7 +120,7 @@ module ActiveRecord
     #     # On PostgreSQL, the transaction is now unusable. The following
     #     # statement will cause a PostgreSQL error, even though the unique
     #     # constraint is no longer violated:
-    #     Number.create(:i => 1)
+    #     Number.create(i: 1)
     #     # => "PGError: ERROR:  current transaction is aborted, commands
     #     #     ignored until end of transaction block"
     #   end
@@ -134,9 +135,9 @@ module ActiveRecord
     # transaction. For example, the following behavior may be surprising:
     #
     #   User.transaction do
-    #     User.create(:username => 'Kotori')
+    #     User.create(username: 'Kotori')
     #     User.transaction do
-    #       User.create(:username => 'Nemu')
+    #       User.create(username: 'Nemu')
     #       raise ActiveRecord::Rollback
     #     end
     #   end
@@ -147,25 +148,25 @@ module ActiveRecord
     # real transaction is committed.
     #
     # In order to get a ROLLBACK for the nested transaction you may ask for a real
-    # sub-transaction by passing <tt>:requires_new => true</tt>. If anything goes wrong,
+    # sub-transaction by passing <tt>requires_new: true</tt>. If anything goes wrong,
     # the database rolls back to the beginning of the sub-transaction without rolling
     # back the parent transaction. If we add it to the previous example:
     #
     #   User.transaction do
-    #     User.create(:username => 'Kotori')
-    #     User.transaction(:requires_new => true) do
-    #       User.create(:username => 'Nemu')
+    #     User.create(username: 'Kotori')
+    #     User.transaction(requires_new: true) do
+    #       User.create(username: 'Nemu')
     #       raise ActiveRecord::Rollback
     #     end
     #   end
     #
-    # only "Kotori" is created. (This works on MySQL and PostgreSQL, but not on SQLite3.)
+    # only "Kotori" is created. This works on MySQL and PostgreSQL. SQLite3 version >= '3.6.8' also supports it.
     #
     # Most databases don't support true nested transactions. At the time of
     # writing, the only database that we're aware of that supports true nested
     # transactions, is MS-SQL. Because of this, Active Record emulates nested
     # transactions by using savepoints on MySQL and PostgreSQL. See
-    # http://dev.mysql.com/doc/refman/5.0/en/savepoint.html
+    # http://dev.mysql.com/doc/refman/5.6/en/savepoint.html
     # for more information about savepoints.
     #
     # === Callbacks
@@ -194,7 +195,7 @@ module ActiveRecord
     # automatically released. The following example demonstrates the problem:
     #
     #   Model.connection.transaction do                           # BEGIN
-    #     Model.connection.transaction(:requires_new => true) do  # CREATE SAVEPOINT active_record_1
+    #     Model.connection.transaction(requires_new: true) do  # CREATE SAVEPOINT active_record_1
     #       Model.connection.create_table(...)                    # active_record_1 now automatically released
     #     end                                                     # RELEASE savepoint active_record_1
     #                                                             # ^^^^ BOOM! database error!
@@ -213,22 +214,17 @@ module ActiveRecord
       # You can specify that the callback should only be fired by a certain action with
       # the +:on+ option:
       #
-      #   after_commit :do_foo, :on => :create
-      #   after_commit :do_bar, :on => :update
-      #   after_commit :do_baz, :on => :destroy
+      #   after_commit :do_foo, on: :create
+      #   after_commit :do_bar, on: :update
+      #   after_commit :do_baz, on: :destroy
       #
-      # Also, to have the callback fired on create and update, but not on destroy:
-      #
-      #   after_commit :do_zoo, :if => :persisted?
+      #   after_commit :do_foo_bar, on: [:create, :update]
+      #   after_commit :do_bar_baz, on: [:update, :destroy]
       #
       # Note that transactional fixtures do not play well with this feature. Please
       # use the +test_after_commit+ gem to have these hooks fired in tests.
       def after_commit(*args, &block)
-        options = args.last
-        if options.is_a?(Hash) && options[:on]
-          options[:if] = Array.wrap(options[:if])
-          options[:if] << "transaction_include_action?(:#{options[:on]})"
-        end
+        set_options_for_callbacks!(args)
         set_callback(:commit, :after, *args, &block)
       end
 
@@ -236,12 +232,27 @@ module ActiveRecord
       #
       # Please check the documentation of +after_commit+ for options.
       def after_rollback(*args, &block)
+        set_options_for_callbacks!(args)
+        set_callback(:rollback, :after, *args, &block)
+      end
+
+      private
+
+      def set_options_for_callbacks!(args)
         options = args.last
         if options.is_a?(Hash) && options[:on]
-          options[:if] = Array.wrap(options[:if])
-          options[:if] << "transaction_include_action?(:#{options[:on]})"
+          assert_valid_transaction_action(options[:on])
+          options[:if] = Array(options[:if])
+          fire_on = Array(options[:on])
+          options[:if] << "transaction_include_any_action?(#{fire_on})"
+        end
+      end
+
+      def assert_valid_transaction_action(actions)
+        actions = Array(actions)
+        if (actions - ACTIONS).any?
+          raise ArgumentError, ":on conditions for after_commit and after_rollback callbacks have to be one of #{ACTIONS.join(",")}"
         end
-        set_callback(:rollback, :after, *args, &block)
       end
     end
 
@@ -264,35 +275,40 @@ module ActiveRecord
       with_transaction_returning_status { super }
     end
 
+    def touch(*) #:nodoc:
+      with_transaction_returning_status { super }
+    end
+
     # Reset id and @new_record if the transaction rolls back.
     def rollback_active_record_state!
       remember_transaction_record_state
       yield
     rescue Exception
-      IdentityMap.remove(self) if IdentityMap.enabled?
       restore_transaction_record_state
       raise
     ensure
       clear_transaction_record_state
     end
 
-    # Call the after_commit callbacks
+    # Call the +after_commit+ callbacks.
+    #
+    # Ensure that it is not called if the object was never persisted (failed create),
+    # but call it after the commit of a destroyed object.
     def committed! #:nodoc:
-      run_callbacks :commit
+      run_callbacks :commit if destroyed? || persisted?
     ensure
-      clear_transaction_record_state
+      @_start_transaction_state.clear
     end
 
-    # Call the after rollback callbacks. The restore_state argument indicates if the record
+    # Call the +after_rollback+ callbacks. The +force_restore_state+ argument indicates if the record
     # state should be rolled back to the beginning or just to the last savepoint.
     def rolledback!(force_restore_state = false) #:nodoc:
       run_callbacks :rollback
     ensure
-      IdentityMap.remove(self) if IdentityMap.enabled?
       restore_transaction_record_state(force_restore_state)
     end
 
-    # Add the record to the current transaction so that the :after_rollback and :after_commit callbacks
+    # Add the record to the current transaction so that the +after_rollback+ and +after_commit+ callbacks
     # can be called.
     def add_to_transaction
       if self.class.connection.add_transaction_record(self)
@@ -310,7 +326,13 @@ module ActiveRecord
       status = nil
       self.class.transaction do
         add_to_transaction
-        status = yield
+        begin
+          status = yield
+        rescue ActiveRecord::Rollback
+          @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+          status = nil
+        end
+
         raise ActiveRecord::Rollback unless status
       end
       status
@@ -320,7 +342,6 @@ module ActiveRecord
 
     # Save the new record state and id of a record so it can be restored later if a transaction fails.
     def remember_transaction_record_state #:nodoc:
-      @_start_transaction_state ||= {}
       @_start_transaction_state[:id] = id if has_attribute?(self.class.primary_key)
       unless @_start_transaction_state.include?(:new_record)
         @_start_transaction_state[:new_record] = @new_record
@@ -334,47 +355,48 @@ module ActiveRecord
 
     # Clear the new record state and id of a record.
     def clear_transaction_record_state #:nodoc:
-      if defined?(@_start_transaction_state)
-        @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
-        remove_instance_variable(:@_start_transaction_state) if @_start_transaction_state[:level] < 1
-      end
+      @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
+      @_start_transaction_state.clear if @_start_transaction_state[:level] < 1
     end
 
     # Restore the new record state and id of a record that was previously saved by a call to save_record_state.
     def restore_transaction_record_state(force = false) #:nodoc:
-      if defined?(@_start_transaction_state)
+      unless @_start_transaction_state.empty?
         @_start_transaction_state[:level] = (@_start_transaction_state[:level] || 0) - 1
         if @_start_transaction_state[:level] < 1 || force
-          restore_state = remove_instance_variable(:@_start_transaction_state)
+          restore_state = @_start_transaction_state
           was_frozen = restore_state[:frozen?]
           @attributes = @attributes.dup if @attributes.frozen?
           @new_record = restore_state[:new_record]
           @destroyed  = restore_state[:destroyed]
           if restore_state.has_key?(:id)
-            self.id = restore_state[:id]
+            write_attribute(self.class.primary_key, restore_state[:id])
           else
             @attributes.delete(self.class.primary_key)
             @attributes_cache.delete(self.class.primary_key)
           end
           @attributes.freeze if was_frozen
+          @_start_transaction_state.clear
         end
       end
     end
 
     # Determine if a record was created or destroyed in a transaction. State should be one of :new_record or :destroyed.
     def transaction_record_state(state) #:nodoc:
-      @_start_transaction_state[state] if defined?(@_start_transaction_state)
+      @_start_transaction_state[state]
     end
 
     # Determine if a transaction included an action for :create, :update, or :destroy. Used in filtering callbacks.
-    def transaction_include_action?(action) #:nodoc:
-      case action
-      when :create
-        transaction_record_state(:new_record)
-      when :destroy
-        destroyed?
-      when :update
-        !(transaction_record_state(:new_record) || destroyed?)
+    def transaction_include_any_action?(actions) #:nodoc:
+      actions.any? do |action|
+        case action
+        when :create
+          transaction_record_state(:new_record)
+        when :destroy
+          destroyed?
+        when :update
+          !(transaction_record_state(:new_record) || destroyed?)
+        end
       end
     end
   end

data/lib/active_record/validations/associated.rb

@@ -1,6 +1,6 @@
 module ActiveRecord
   module Validations
-    class AssociatedValidator < ActiveModel::EachValidator
+    class AssociatedValidator < ActiveModel::EachValidator #:nodoc:
       def validate_each(record, attribute, value)
         if Array.wrap(value).reject {|r| r.marked_for_destruction? || r.valid?}.any?
           record.errors.add(attribute, :invalid, options.merge(:value => value))
@@ -9,7 +9,8 @@ module ActiveRecord
     end
 
     module ClassMethods
-      # Validates whether the associated object or objects are all valid themselves. Works with any kind of association.
+      # Validates whether the associated object or objects are all valid.
+      # Works with any kind of association.
       #
       #   class Book < ActiveRecord::Base
       #     has_many :pages
@@ -18,23 +19,28 @@ module ActiveRecord
       #     validates_associated :pages, :library
       #   end
       #
-      # WARNING: This validation must not be used on both ends of an association. Doing so will lead to a circular dependency and cause infinite recursion.
+      # WARNING: This validation must not be used on both ends of an association.
+      # Doing so will lead to a circular dependency and cause infinite recursion.
       #
-      # NOTE: This validation will not fail if the association hasn't been assigned. If you want to
-      # ensure that the association is both present and guaranteed to be valid, you also need to
-      # use +validates_presence_of+.
+      # NOTE: This validation will not fail if the association hasn't been
+      # assigned. If you want to ensure that the association is both present and
+      # guaranteed to be valid, you also need to use +validates_presence_of+.
       #
       # Configuration options:
-      # * <tt>:message</tt> - A custom error message (default is: "is invalid")
+      #
+      # * <tt>:message</tt> - A custom error message (default is: "is invalid").
       # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
       #   validation contexts by default (+nil+), other options are <tt>:create</tt>
       #   and <tt>:update</tt>.
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The
-      #   method, proc or string should return or evaluate to a true or false value.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to
+      #   determine if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or +false+
+      #   value.
       def validates_associated(*attr_names)
         validates_with AssociatedValidator, _merge_attributes(attr_names)
       end

data/lib/active_record/validations/presence.rb

@@ -0,0 +1,65 @@
+module ActiveRecord
+  module Validations
+    class PresenceValidator < ActiveModel::Validations::PresenceValidator # :nodoc:
+      def validate(record)
+        super
+        attributes.each do |attribute|
+          next unless record.class.reflect_on_association(attribute)
+          associated_records = Array.wrap(record.send(attribute))
+
+          # Superclass validates presence. Ensure present records aren't about to be destroyed.
+          if associated_records.present? && associated_records.all? { |r| r.marked_for_destruction? }
+            record.errors.add(attribute, :blank, options)
+          end
+        end
+      end
+    end
+
+    module ClassMethods
+      # Validates that the specified attributes are not blank (as defined by
+      # Object#blank?), and, if the attribute is an association, that the
+      # associated object is not marked for destruction. Happens by default
+      # on save.
+      #
+      #   class Person < ActiveRecord::Base
+      #     has_one :face
+      #     validates_presence_of :face
+      #   end
+      #
+      # The face attribute must be in the object and it cannot be blank or marked
+      # for destruction.
+      #
+      # If you want to validate the presence of a boolean field (where the real values
+      # are true and false), you will want to use
+      # <tt>validates_inclusion_of :field_name, in: [true, false]</tt>.
+      #
+      # This is due to the way Object#blank? handles boolean values:
+      # <tt>false.blank? # => true</tt>.
+      #
+      # This validator defers to the ActiveModel validation for presence, adding the
+      # check to see that an associated object is not marked for destruction. This
+      # prevents the parent object from validating successfully and saving, which then
+      # deletes the associated object, thus putting the parent object into an invalid
+      # state.
+      #
+      # Configuration options:
+      # * <tt>:message</tt> - A custom error message (default is: "can't be blank").
+      # * <tt>:on</tt> - Specifies when this validation is active. Runs in all
+      #   validation contexts by default (+nil+), other options are <tt>:create</tt>
+      #   and <tt>:update</tt>.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if
+      #   the validation should occur (e.g. <tt>if: :allow_validation</tt>, or
+      #   <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method, proc
+      #   or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should not occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:strict</tt> - Specifies whether validation should be strict.
+      #   See <tt>ActiveModel::Validation#validates!</tt> for more information.
+      def validates_presence_of(*attr_names)
+        validates_with PresenceValidator, _merge_attributes(attr_names)
+      end
+    end
+  end
+end

data/lib/active_record/validations/uniqueness.rb

@@ -1,10 +1,12 @@
-require 'active_support/core_ext/array/wrap'
-
 module ActiveRecord
   module Validations
-    class UniquenessValidator < ActiveModel::EachValidator
+    class UniquenessValidator < ActiveModel::EachValidator # :nodoc:
       def initialize(options)
-        super(options.reverse_merge(:case_sensitive => true))
+        if options[:conditions] && !options[:conditions].respond_to?(:call)
+          raise ArgumentError, "#{options[:conditions]} was passed as :conditions but is not callable. " \
+                               "Pass a callable instead: `conditions: -> { where(approved: true) }`"
+        end
+        super({ case_sensitive: true }.merge!(options))
       end
 
       # Unfortunately, we have to tie Uniqueness validators to a class.
@@ -15,23 +17,19 @@ module ActiveRecord
       def validate_each(record, attribute, value)
         finder_class = find_finder_class_for(record)
         table = finder_class.arel_table
-
-        coder = record.class.serialized_attributes[attribute.to_s]
-
-        if value && coder
-          value = coder.dump value
-        end
+        value = deserialize_attribute(record, attribute, value)
 
         relation = build_relation(finder_class, table, attribute, value)
-        relation = relation.and(table[finder_class.primary_key.to_sym].not_eq(record.send(:id))) if record.persisted?
+        relation = relation.and(table[finder_class.primary_key.to_sym].not_eq(record.id)) if record.persisted?
+        relation = scope_relation(record, table, relation)
+        relation = finder_class.unscoped.where(relation)
+        relation = relation.merge(options[:conditions]) if options[:conditions]
 
-        Array.wrap(options[:scope]).each do |scope_item|
-          scope_value = record.read_attribute(scope_item)
-          relation = relation.and(table[scope_item].eq(scope_value))
-        end
+        if relation.exists?
+          error_options = options.except(:case_sensitive, :scope, :conditions)
+          error_options[:value] = value
 
-        if finder_class.unscoped.where(relation).exists?
-          record.errors.add(attribute, :taken, options.except(:case_sensitive, :scope).merge(:value => value))
+          record.errors.add(attribute, :taken, error_options)
         end
       end
 
@@ -46,67 +44,122 @@ module ActiveRecord
         class_hierarchy = [record.class]
 
         while class_hierarchy.first != @klass
-          class_hierarchy.insert(0, class_hierarchy.first.superclass)
+          class_hierarchy.unshift(class_hierarchy.first.superclass)
         end
 
         class_hierarchy.detect { |klass| !klass.abstract_class? }
       end
 
       def build_relation(klass, table, attribute, value) #:nodoc:
-        column = klass.columns_hash[attribute.to_s]
-        value = column.limit ? value.to_s.mb_chars[0, column.limit] : value.to_s if value && column.text?
+        if reflection = klass.reflect_on_association(attribute)
+          attribute = reflection.foreign_key
+          value = value.attributes[reflection.primary_key_column.name] unless value.nil?
+        end
+
+        attribute_name = attribute.to_s
+
+        # the attribute may be an aliased attribute
+        if klass.attribute_aliases[attribute_name]
+          attribute = klass.attribute_aliases[attribute_name]
+          attribute_name = attribute.to_s
+        end
+
+        column = klass.columns_hash[attribute_name]
+        value  = klass.connection.type_cast(value, column)
+        value  = value.to_s[0, column.limit] if value && column.limit && column.text?
 
         if !options[:case_sensitive] && value && column.text?
           # will use SQL LOWER function before comparison, unless it detects a case insensitive collation
-          relation = klass.connection.case_insensitive_comparison(table, attribute, column, value)
+          klass.connection.case_insensitive_comparison(table, attribute, column, value)
         else
-          value    = klass.connection.case_sensitive_modifier(value) if value
-          relation = table[attribute].eq(value)
+          value = klass.connection.case_sensitive_modifier(value) unless value.nil?
+          table[attribute].eq(value)
+        end
+      end
+
+      def scope_relation(record, table, relation)
+        Array(options[:scope]).each do |scope_item|
+          if reflection = record.class.reflect_on_association(scope_item)
+            scope_value = record.send(reflection.foreign_key)
+            scope_item  = reflection.foreign_key
+          else
+            scope_value = record.read_attribute(scope_item)
+          end
+          relation = relation.and(table[scope_item].eq(scope_value))
         end
 
         relation
       end
+
+      def deserialize_attribute(record, attribute, value)
+        coder = record.class.serialized_attributes[attribute.to_s]
+        value = coder.dump value if value && coder
+        value
+      end
     end
 
     module ClassMethods
-      # Validates whether the value of the specified attributes are unique across the system.
-      # Useful for making sure that only one user
+      # Validates whether the value of the specified attributes are unique
+      # across the system. Useful for making sure that only one user
       # can be named "davidhh".
       #
       #   class Person < ActiveRecord::Base
       #     validates_uniqueness_of :user_name
       #   end
       #
-      # It can also validate whether the value of the specified attributes are unique based on a scope parameter:
+      # It can also validate whether the value of the specified attributes are
+      # unique based on a <tt>:scope</tt> parameter:
       #
       #   class Person < ActiveRecord::Base
-      #     validates_uniqueness_of :user_name, :scope => :account_id
+      #     validates_uniqueness_of :user_name, scope: :account_id
       #   end
       #
-      # Or even multiple scope parameters. For example, making sure that a teacher can only be on the schedule once
-      # per semester for a particular class.
+      # Or even multiple scope parameters. For example, making sure that a
+      # teacher can only be on the schedule once per semester for a particular
+      # class.
       #
       #   class TeacherSchedule < ActiveRecord::Base
-      #     validates_uniqueness_of :teacher_id, :scope => [:semester_id, :class_id]
+      #     validates_uniqueness_of :teacher_id, scope: [:semester_id, :class_id]
+      #   end
+      #
+      # It is also possible to limit the uniqueness constraint to a set of
+      # records matching certain conditions. In this example archived articles
+      # are not being taken into consideration when validating uniqueness
+      # of the title attribute:
+      #
+      #   class Article < ActiveRecord::Base
+      #     validates_uniqueness_of :title, conditions: -> { where.not(status: 'archived') }
       #   end
       #
-      # When the record is created, a check is performed to make sure that no record exists in the database
-      # with the given value for the specified attribute (that maps to a column). When the record is updated,
+      # When the record is created, a check is performed to make sure that no
+      # record exists in the database with the given value for the specified
+      # attribute (that maps to a column). When the record is updated,
       # the same check is made but disregarding the record itself.
       #
       # Configuration options:
-      # * <tt>:message</tt> - Specifies a custom error message (default is: "has already been taken").
-      # * <tt>:scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint.
-      # * <tt>:case_sensitive</tt> - Looks for an exact match. Ignored by non-text columns (+true+ by default).
-      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
-      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
-      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).
-      #   The method, proc or string should return or evaluate to a true or false value.
-      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or
-      #   <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>). The method, proc or string should
-      #   return or evaluate to a true or false value.
+      #
+      # * <tt>:message</tt> - Specifies a custom error message (default is:
+      #   "has already been taken").
+      # * <tt>:scope</tt> - One or more columns by which to limit the scope of
+      #   the uniqueness constraint.
+      # * <tt>:conditions</tt> - Specify the conditions to be included as a
+      #   <tt>WHERE</tt> SQL fragment to limit the uniqueness constraint lookup
+      #   (e.g. <tt>conditions: -> { where(status: 'active') }</tt>).
+      # * <tt>:case_sensitive</tt> - Looks for an exact match. Ignored by
+      #   non-text columns (+true+ by default).
+      # * <tt>:allow_nil</tt> - If set to +true+, skips this validation if the
+      #   attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to +true+, skips this validation if the
+      #   attribute is blank (default is +false+).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+      #   if the validation should occur (e.g. <tt>if: :allow_validation</tt>,
+      #   or <tt>if: Proc.new { |user| user.signup_step > 2 }</tt>). The method,
+      #   proc or string should return or evaluate to a +true+ or +false+ value.
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to
+      #   determine if the validation should ot occur (e.g. <tt>unless: :skip_validation</tt>,
+      #   or <tt>unless: Proc.new { |user| user.signup_step <= 2 }</tt>). The
+      #   method, proc or string should return or evaluate to a +true+ or +false+
+      #   value.
       #
       # === Concurrency and integrity
       #
@@ -126,11 +179,11 @@ module ActiveRecord
       #  WHERE title = 'My Post'             |
       #                                      |
       #                                      | # User 2 does the same thing and also
-      #                                      | # infers that his title is unique.
+      #                                      | # infers that their title is unique.
       #                                      | SELECT * FROM comments
       #                                      | WHERE title = 'My Post'
       #                                      |
-      #  # User 1 inserts his comment.       |
+      #  # User 1 inserts their comment.     |
       #  INSERT INTO comments                |
       #  (title, content) VALUES             |
       #  ('My Post', 'hi!')                  |
@@ -156,22 +209,22 @@ module ActiveRecord
       # exception. You can either choose to let this error propagate (which
       # will result in the default Rails exception page being shown), or you
       # can catch it and restart the transaction (e.g. by telling the user
-      # that the title already exists, and asking him to re-enter the title).
-      # This technique is also known as optimistic concurrency control:
-      # http://en.wikipedia.org/wiki/Optimistic_concurrency_control
+      # that the title already exists, and asking them to re-enter the title).
+      # This technique is also known as
+      # {optimistic concurrency control}[http://en.wikipedia.org/wiki/Optimistic_concurrency_control].
       #
       # The bundled ActiveRecord::ConnectionAdapters distinguish unique index
       # constraint errors from other types of database errors by throwing an
-      # ActiveRecord::RecordNotUnique exception.
-      # For other adapters you will have to parse the (database-specific) exception
-      # message to detect such a case.
+      # ActiveRecord::RecordNotUnique exception. For other adapters you will
+      # have to parse the (database-specific) exception message to detect such
+      # a case.
+      #
       # The following bundled adapters throw the ActiveRecord::RecordNotUnique exception:
-      # * ActiveRecord::ConnectionAdapters::MysqlAdapter
-      # * ActiveRecord::ConnectionAdapters::Mysql2Adapter
-      # * ActiveRecord::ConnectionAdapters::SQLiteAdapter
-      # * ActiveRecord::ConnectionAdapters::SQLite3Adapter
-      # * ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
       #
+      # * ActiveRecord::ConnectionAdapters::MysqlAdapter.
+      # * ActiveRecord::ConnectionAdapters::Mysql2Adapter.
+      # * ActiveRecord::ConnectionAdapters::SQLite3Adapter.
+      # * ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.
       def validates_uniqueness_of(*attr_names)
         validates_with UniquenessValidator, _merge_attributes(attr_names)
       end