activerecord 4.2.11.3 → 5.0.0.beta1

data/lib/active_record/dynamic_matchers.rb

@@ -1,10 +1,5 @@
 module ActiveRecord
   module DynamicMatchers #:nodoc:
-    # This code in this file seems to have a lot of indirection, but the indirection
-    # is there to provide extension points for the activerecord-deprecated_finders
-    # gem. When we stop supporting activerecord-deprecated_finders (from Rails 5),
-    # then we can remove the indirection.
-
     def respond_to?(name, include_private = false)
       if self == Base
         super
@@ -72,26 +67,14 @@ module ActiveRecord
         CODE
       end
 
-      def body
-        raise NotImplementedError
-      end
-    end
+      private
 
-    module Finder
-      # Extended in activerecord-deprecated_finders
       def body
-        result
-      end
-
-      # Extended in activerecord-deprecated_finders
-      def result
         "#{finder}(#{attributes_hash})"
       end
 
       # The parameters in the signature may have reserved Ruby words, in order
       # to prevent errors, we start each param name with `_`.
-      #
-      # Extended in activerecord-deprecated_finders
       def signature
         attribute_names.map { |name| "_#{name}" }.join(', ')
       end
@@ -109,7 +92,6 @@ module ActiveRecord
 
     class FindBy < Method
       Method.matchers << self
-      include Finder
 
       def self.prefix
         "find_by"
@@ -122,7 +104,6 @@ module ActiveRecord
 
     class FindByBang < Method
       Method.matchers << self
-      include Finder
 
       def self.prefix
         "find_by"

data/lib/active_record/enum.rb

@@ -31,6 +31,12 @@ module ActiveRecord
   #   Conversation.active
   #   Conversation.archived
   #
+  # Of course, you can also query them directly if the scopes don't fit your
+  # needs:
+  #
+  #   Conversation.where(status: [:active, :archived])
+  #   Conversation.where.not(status: :active)
+  #
   # You can set the default value from the database declaration, like:
   #
   #   create_table :conversations do |t|
@@ -40,13 +46,13 @@ module ActiveRecord
   # Good practice is to let the first declared status be the default.
   #
   # Finally, it's also possible to explicitly map the relation between attribute and
-  # database integer with a +Hash+:
+  # database integer with a hash:
   #
   #   class Conversation < ActiveRecord::Base
   #     enum status: { active: 0, archived: 1 }
   #   end
   #
-  # Note that when an +Array+ is used, the implicit mapping from the values to database
+  # Note that when an array is used, the implicit mapping from the values to database
   # integers is derived from the order the values appear in the array. In the example,
   # <tt>:active</tt> is mapped to +0+ as it's the first element, and <tt>:archived</tt>
   # is mapped to +1+. In general, the +i+-th element is mapped to <tt>i-1</tt> in the
@@ -54,22 +60,42 @@ module ActiveRecord
   #
   # Therefore, once a value is added to the enum array, its position in the array must
   # be maintained, and new values should only be added to the end of the array. To
-  # remove unused values, the explicit +Hash+ syntax should be used.
+  # remove unused values, the explicit hash syntax should be used.
   #
   # In rare circumstances you might need to access the mapping directly.
   # The mappings are exposed through a class method with the pluralized attribute
-  # name:
+  # name, which return the mapping in a +HashWithIndifferentAccess+:
   #
-  #   Conversation.statuses # => { "active" => 0, "archived" => 1 }
+  #   Conversation.statuses[:active]    # => 0
+  #   Conversation.statuses["archived"] # => 1
   #
-  # Use that class method when you need to know the ordinal value of an enum:
+  # Use that class method when you need to know the ordinal value of an enum.
+  # For example, you can use that when manually building SQL strings:
   #
   #   Conversation.where("status <> ?", Conversation.statuses[:archived])
   #
-  # Where conditions on an enum attribute must use the ordinal value of an enum.
+  # You can use the +:_prefix+ or +:_suffix+ options when you need to define
+  # multiple enums with same values. If the passed value is +true+, the methods
+  # are prefixed/suffixed with the name of the enum. It is also possible to
+  # supply a custom value:
+  #
+  #   class Conversation < ActiveRecord::Base
+  #     enum status: [:active, :archived], _suffix: true
+  #     enum comments_status: [:active, :inactive], _prefix: :comments
+  #   end
+  #
+  # With the above example, the bang and predicate methods along with the
+  # associated scopes are now prefixed and/or suffixed accordingly:
+  #
+  #   conversation.active_status!
+  #   conversation.archived_status? # => false
+  #
+  #   conversation.comments_inactive!
+  #   conversation.comments_active? # => false
+
   module Enum
     def self.extended(base) # :nodoc:
-      base.class_attribute(:defined_enums, instance_writer: false)
+      base.class_attribute(:defined_enums)
       base.defined_enums = {}
     end
 
@@ -78,8 +104,48 @@ module ActiveRecord
       super
     end
 
+    class EnumType < Type::Value # :nodoc:
+      def initialize(name, mapping)
+        @name = name
+        @mapping = mapping
+      end
+
+      def cast(value)
+        return if value.blank?
+
+        if mapping.has_key?(value)
+          value.to_s
+        elsif mapping.has_value?(value)
+          mapping.key(value)
+        else
+          assert_valid_value(value)
+        end
+      end
+
+      def deserialize(value)
+        return if value.nil?
+        mapping.key(value.to_i)
+      end
+
+      def serialize(value)
+        mapping.fetch(value, value)
+      end
+
+      def assert_valid_value(value)
+        unless value.blank? || mapping.has_key?(value) || mapping.has_value?(value)
+          raise ArgumentError, "'#{value}' is not a valid #{name}"
+        end
+      end
+
+      protected
+
+      attr_reader :name, :mapping
+    end
+
     def enum(definitions)
       klass = self
+      enum_prefix = definitions.delete(:_prefix)
+      enum_suffix = definitions.delete(:_suffix)
       definitions.each do |name, values|
         # statuses = { }
         enum_values = ActiveSupport::HashWithIndifferentAccess.new
@@ -89,45 +155,39 @@ module ActiveRecord
         detect_enum_conflict!(name, name.to_s.pluralize, true)
         klass.singleton_class.send(:define_method, name.to_s.pluralize) { enum_values }
 
-        _enum_methods_module.module_eval do
-          # def status=(value) self[:status] = statuses[value] end
-          klass.send(:detect_enum_conflict!, name, "#{name}=")
-          define_method("#{name}=") { |value|
-            if enum_values.has_key?(value) || value.blank?
-              self[name] = enum_values[value]
-            elsif enum_values.has_value?(value)
-              # Assigning a value directly is not a end-user feature, hence it's not documented.
-              # This is used internally to make building objects from the generated scopes work
-              # as expected, i.e. +Conversation.archived.build.archived?+ should be true.
-              self[name] = value
-            else
-              raise ArgumentError, "'#{value}' is not a valid #{name}"
-            end
-          }
+        detect_enum_conflict!(name, name)
+        detect_enum_conflict!(name, "#{name}=")
 
-          # def status() statuses.key self[:status] end
-          klass.send(:detect_enum_conflict!, name, name)
-          define_method(name) { enum_values.key self[name] }
-
-          # def status_before_type_cast() statuses.key self[:status] end
-          klass.send(:detect_enum_conflict!, name, "#{name}_before_type_cast")
-          define_method("#{name}_before_type_cast") { enum_values.key self[name] }
+        attribute name, EnumType.new(name, enum_values)
 
+        _enum_methods_module.module_eval do
           pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
           pairs.each do |value, i|
+            if enum_prefix == true
+              prefix = "#{name}_"
+            elsif enum_prefix
+              prefix = "#{enum_prefix}_"
+            end
+            if enum_suffix == true
+              suffix = "_#{name}"
+            elsif enum_suffix
+              suffix = "_#{enum_suffix}"
+            end
+
+            value_method_name = "#{prefix}#{value}#{suffix}"
             enum_values[value] = i
 
             # def active?() status == 0 end
-            klass.send(:detect_enum_conflict!, name, "#{value}?")
-            define_method("#{value}?") { self[name] == i }
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+            define_method("#{value_method_name}?") { self[name] == value.to_s }
 
             # def active!() update! status: :active end
-            klass.send(:detect_enum_conflict!, name, "#{value}!")
-            define_method("#{value}!") { update! name => value }
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
+            define_method("#{value_method_name}!") { update! name => value }
 
             # scope :active, -> { where status: 0 }
-            klass.send(:detect_enum_conflict!, name, value, true)
-            klass.scope value, -> { klass.where name => i }
+            klass.send(:detect_enum_conflict!, name, value_method_name, true)
+            klass.scope value_method_name, -> { klass.where name => value }
           end
         end
         defined_enums[name.to_s] = enum_values
@@ -137,25 +197,7 @@ module ActiveRecord
     private
       def _enum_methods_module
         @_enum_methods_module ||= begin
-          mod = Module.new do
-            private
-              def save_changed_attribute(attr_name, old)
-                if (mapping = self.class.defined_enums[attr_name.to_s])
-                  value = _read_attribute(attr_name)
-                  if attribute_changed?(attr_name)
-                    if mapping[old] == value
-                      clear_attribute_changes([attr_name])
-                    end
-                  else
-                    if old != value
-                      set_attribute_was(attr_name, mapping.key(old))
-                    end
-                  end
-                else
-                  super
-                end
-              end
-          end
+          mod = Module.new
           include mod
           mod
         end
@@ -168,30 +210,22 @@ module ActiveRecord
 
       def detect_enum_conflict!(enum_name, method_name, klass_method = false)
         if klass_method && dangerous_class_method?(method_name)
-          raise ArgumentError, ENUM_CONFLICT_MESSAGE % {
-            enum: enum_name,
-            klass: self.name,
-            type: 'class',
-            method: method_name,
-            source: 'Active Record'
-          }
+          raise_conflict_error(enum_name, method_name, type: 'class')
         elsif !klass_method && dangerous_attribute_method?(method_name)
-          raise ArgumentError, ENUM_CONFLICT_MESSAGE % {
-            enum: enum_name,
-            klass: self.name,
-            type: 'instance',
-            method: method_name,
-            source: 'Active Record'
-          }
+          raise_conflict_error(enum_name, method_name)
         elsif !klass_method && method_defined_within?(method_name, _enum_methods_module, Module)
-          raise ArgumentError, ENUM_CONFLICT_MESSAGE % {
-            enum: enum_name,
-            klass: self.name,
-            type: 'instance',
-            method: method_name,
-            source: 'another enum'
-          }
+          raise_conflict_error(enum_name, method_name, source: 'another enum')
         end
       end
+
+      def raise_conflict_error(enum_name, method_name, type: 'instance', source: 'Active Record')
+        raise ArgumentError, ENUM_CONFLICT_MESSAGE % {
+          enum: enum_name,
+          klass: self.name,
+          type: type,
+          method: method_name,
+          source: source
+        }
+      end
   end
 end

data/lib/active_record/errors.rb

@@ -7,8 +7,10 @@ module ActiveRecord
   end
 
   # Raised when the single-table inheritance mechanism fails to locate the subclass
-  # (for example due to improper usage of column that +inheritance_column+ points to).
-  class SubclassNotFound < ActiveRecordError #:nodoc:
+  # (for example due to improper usage of column that
+  # {ActiveRecord::Base.inheritance_column}[rdoc-ref:ModelSchema::ClassMethods#inheritance_column]
+  # points to).
+  class SubclassNotFound < ActiveRecordError
   end
 
   # Raised when an object assigned to an association has an incorrect type.
@@ -40,27 +42,40 @@ module ActiveRecord
   class AdapterNotFound < ActiveRecordError
   end
 
-  # Raised when connection to the database could not been established (for
-  # example when +connection=+ is given a nil object).
+  # Raised when connection to the database could not been established (for example when
+  # {ActiveRecord::Base.connection=}[rdoc-ref:ConnectionHandling#connection]
+  # is given a nil object).
   class ConnectionNotEstablished < ActiveRecordError
   end
 
-  # Raised when Active Record cannot find record by given id or set of ids.
+  # Raised when Active Record cannot find a record by given id or set of ids.
   class RecordNotFound < ActiveRecordError
+    attr_reader :model, :primary_key, :id
+
+    def initialize(message = nil, model = nil, primary_key = nil, id = nil)
+      @primary_key = primary_key
+      @model = model
+      @id = id
+
+      super(message)
+    end
   end
 
-  # Raised by ActiveRecord::Base.save! and ActiveRecord::Base.create! methods when record cannot be
-  # saved because record is invalid.
+  # Raised by {ActiveRecord::Base#save!}[rdoc-ref:Persistence#save!] and
+  # {ActiveRecord::Base.create!}[rdoc-ref:Persistence::ClassMethods#create!]
+  # methods when a record is invalid and can not be saved.
   class RecordNotSaved < ActiveRecordError
     attr_reader :record
 
-    def initialize(message, record = nil)
+    def initialize(message = nil, record = nil)
       @record = record
       super(message)
     end
   end
 
-  # Raised by ActiveRecord::Base.destroy! when a call to destroy would return false.
+  # Raised by {ActiveRecord::Base#destroy!}[rdoc-ref:Persistence#destroy!]
+  # when a call to {#destroy}[rdoc-ref:Persistence#destroy!]
+  # would return false.
   #
   #   begin
   #     complex_operation_that_internally_calls_destroy!
@@ -71,7 +86,7 @@ module ActiveRecord
   class RecordNotDestroyed < ActiveRecordError
     attr_reader :record
 
-    def initialize(message, record = nil)
+    def initialize(message = nil, record = nil)
       @record = record
       super(message)
     end
@@ -79,18 +94,26 @@ module ActiveRecord
 
   # Superclass for all database execution errors.
   #
-  # Wraps the underlying database error as +original_exception+.
+  # Wraps the underlying database error as +cause+.
   class StatementInvalid < ActiveRecordError
-    attr_reader :original_exception
 
-    def initialize(message, original_exception = nil)
-      super(message)
-      @original_exception = original_exception
+    def initialize(message = nil, original_exception = nil)
+      if original_exception
+        ActiveSupport::Deprecation.warn("Passing #original_exception is deprecated and has no effect. " \
+                                        "Exceptions will automatically capture the original exception.", caller)
+      end
+
+      super(message || $!.try(:message))
+    end
+
+    def original_exception
+      ActiveSupport::Deprecation.warn("#original_exception is deprecated. Use #cause instead.", caller)
+      cause
     end
   end
 
   # Defunct wrapper class kept for compatibility.
-  # +StatementInvalid+ wraps the original exception now.
+  # StatementInvalid wraps the original exception now.
   class WrappedDatabaseException < StatementInvalid
   end
 
@@ -103,8 +126,8 @@ module ActiveRecord
   end
 
   # Raised when number of bind variables in statement given to +:condition+ key
-  # (for example, when using +find+ method) does not match number of expected
-  # values supplied.
+  # (for example, when using {ActiveRecord::Base.find}[rdoc-ref:FinderMethods#find] method)
+  # does not match number of expected values supplied.
   #
   # For example, when there are two placeholders with only one value supplied:
   #
@@ -125,16 +148,22 @@ module ActiveRecord
   class StaleObjectError < ActiveRecordError
     attr_reader :record, :attempted_action
 
-    def initialize(record, attempted_action)
-      super("Attempted to #{attempted_action} a stale object: #{record.class.name}")
-      @record = record
-      @attempted_action = attempted_action
+    def initialize(record = nil, attempted_action = nil)
+      if record && attempted_action
+        @record = record
+        @attempted_action = attempted_action
+        super("Attempted to #{attempted_action} a stale object: #{record.class.name}.")
+      else
+        super("Stale object error.")
+      end
     end
 
   end
 
   # Raised when association is being configured improperly or user tries to use
-  # offset and limit together with +has_many+ or +has_and_belongs_to_many+
+  # offset and limit together with
+  # {ActiveRecord::Base.has_many}[rdoc-ref:Associations::ClassMethods#has_many] or
+  # {ActiveRecord::Base.has_and_belongs_to_many}[rdoc-ref:Associations::ClassMethods#has_and_belongs_to_many]
   # associations.
   class ConfigurationError < ActiveRecordError
   end
@@ -143,9 +172,10 @@ module ActiveRecord
   class ReadOnlyRecord < ActiveRecordError
   end
 
-  # ActiveRecord::Transactions::ClassMethods.transaction uses this exception
-  # to distinguish a deliberate rollback from other exceptional situations.
-  # Normally, raising an exception will cause the +transaction+ method to rollback
+  # {ActiveRecord::Base.transaction}[rdoc-ref:Transactions::ClassMethods#transaction]
+  # uses this exception to distinguish a deliberate rollback from other exceptional situations.
+  # Normally, raising an exception will cause the
+  # {.transaction}[rdoc-ref:Transactions::ClassMethods#transaction] method to rollback
   # the database transaction *and* pass on the exception. But if you raise an
   # ActiveRecord::Rollback exception, then the database transaction will be rolled back,
   # without passing on the exception.
@@ -179,38 +209,29 @@ module ActiveRecord
   end
 
   # Raised when unknown attributes are supplied via mass assignment.
-  class UnknownAttributeError < NoMethodError
-
-    attr_reader :record, :attribute
-
-    def initialize(record, attribute)
-      @record = record
-      @attribute = attribute.to_s
-      super("unknown attribute '#{attribute}' for #{@record.class}.")
-    end
-
-  end
+  UnknownAttributeError = ActiveModel::UnknownAttributeError
 
   # Raised when an error occurred while doing a mass assignment to an attribute through the
-  # +attributes=+ method. The exception has an +attribute+ property that is the name of the
-  # offending attribute.
+  # {ActiveRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=] method.
+  # The exception has an +attribute+ property that is the name of the offending attribute.
   class AttributeAssignmentError < ActiveRecordError
     attr_reader :exception, :attribute
 
-    def initialize(message, exception, attribute)
+    def initialize(message = nil, exception = nil, attribute = nil)
       super(message)
       @exception = exception
       @attribute = attribute
     end
   end
 
-  # Raised when there are multiple errors while doing a mass assignment through the +attributes+
+  # Raised when there are multiple errors while doing a mass assignment through the
+  # {ActiveRecord::Base#attributes=}[rdoc-ref:AttributeAssignment#attributes=]
   # method. The exception has an +errors+ property that contains an array of AttributeAssignmentError
   # objects, each corresponding to the error while assigning to an attribute.
   class MultiparameterAssignmentErrors < ActiveRecordError
     attr_reader :errors
 
-    def initialize(errors)
+    def initialize(errors = nil)
       @errors = errors
     end
   end
@@ -219,11 +240,15 @@ module ActiveRecord
   class UnknownPrimaryKey < ActiveRecordError
     attr_reader :model
 
-    def initialize(model, description = nil)
-      message = "Unknown primary key for table #{model.table_name} in model #{model}."
-      message += "\n#{description}" if description
-      super(message)
-      @model = model
+    def initialize(model = nil, description = nil)
+      if model
+        message = "Unknown primary key for table #{model.table_name} in model #{model}."
+        message += "\n#{description}" if description
+        @model = model
+        super(message)
+      else
+        super("Unknown primary key.")
+      end
     end
   end