activerecord 4.2.0 → 6.0.0

data/lib/active_record/dynamic_matchers.rb

@@ -1,140 +1,122 @@
+# frozen_string_literal: true
+
 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
-      else
+    private
+      def respond_to_missing?(name, _)
+        if self == Base
+          super
+        else
+          match = Method.match(self, name)
+          match && match.valid? || super
+        end
+      end
+
+      def method_missing(name, *arguments, &block)
         match = Method.match(self, name)
-        match && match.valid? || super
+
+        if match && match.valid?
+          match.define
+          send(name, *arguments, &block)
+        else
+          super
+        end
       end
-    end
 
-    private
+      class Method
+        @matchers = []
 
-    def method_missing(name, *arguments, &block)
-      match = Method.match(self, name)
+        class << self
+          attr_reader :matchers
 
-      if match && match.valid?
-        match.define
-        send(name, *arguments, &block)
-      else
-        super
-      end
-    end
+          def match(model, name)
+            klass = matchers.find { |k| k.pattern.match?(name) }
+            klass.new(model, name) if klass
+          end
 
-    class Method
-      @matchers = []
+          def pattern
+            @pattern ||= /\A#{prefix}_([_a-zA-Z]\w*)#{suffix}\Z/
+          end
 
-      class << self
-        attr_reader :matchers
+          def prefix
+            raise NotImplementedError
+          end
 
-        def match(model, name)
-          klass = matchers.find { |k| name =~ k.pattern }
-          klass.new(model, name) if klass
+          def suffix
+            ""
+          end
         end
 
-        def pattern
-          @pattern ||= /\A#{prefix}_([_a-zA-Z]\w*)#{suffix}\Z/
-        end
+        attr_reader :model, :name, :attribute_names
 
-        def prefix
-          raise NotImplementedError
+        def initialize(model, name)
+          @model           = model
+          @name            = name.to_s
+          @attribute_names = @name.match(self.class.pattern)[1].split("_and_")
+          @attribute_names.map! { |name| @model.attribute_aliases[name] || name }
         end
 
-        def suffix
-          ''
+        def valid?
+          attribute_names.all? { |name| model.columns_hash[name] || model.reflect_on_aggregation(name.to_sym) }
         end
-      end
 
-      attr_reader :model, :name, :attribute_names
+        def define
+          model.class_eval <<-CODE, __FILE__, __LINE__ + 1
+            def self.#{name}(#{signature})
+              #{body}
+            end
+          CODE
+        end
 
-      def initialize(model, name)
-        @model           = model
-        @name            = name.to_s
-        @attribute_names = @name.match(self.class.pattern)[1].split('_and_')
-        @attribute_names.map! { |n| @model.attribute_aliases[n] || n }
-      end
+        private
 
-      def valid?
-        attribute_names.all? { |name| model.columns_hash[name] || model.reflect_on_aggregation(name.to_sym) }
-      end
-
-      def define
-        model.class_eval <<-CODE, __FILE__, __LINE__ + 1
-          def self.#{name}(#{signature})
-            #{body}
+          def body
+            "#{finder}(#{attributes_hash})"
           end
-        CODE
-      end
 
-      def body
-        raise NotImplementedError
-      end
-    end
-
-    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
+          # The parameters in the signature may have reserved Ruby words, in order
+          # to prevent errors, we start each param name with `_`.
+          def signature
+            attribute_names.map { |name| "_#{name}" }.join(", ")
+          end
 
-      # Given that the parameters starts with `_`, the finder needs to use the
-      # same parameter name.
-      def attributes_hash
-        "{" + attribute_names.map { |name| ":#{name} => _#{name}" }.join(',') + "}"
-      end
+          # Given that the parameters starts with `_`, the finder needs to use the
+          # same parameter name.
+          def attributes_hash
+            "{" + attribute_names.map { |name| ":#{name} => _#{name}" }.join(",") + "}"
+          end
 
-      def finder
-        raise NotImplementedError
+          def finder
+            raise NotImplementedError
+          end
       end
-    end
 
-    class FindBy < Method
-      Method.matchers << self
-      include Finder
+      class FindBy < Method
+        Method.matchers << self
 
-      def self.prefix
-        "find_by"
-      end
+        def self.prefix
+          "find_by"
+        end
 
-      def finder
-        "find_by"
+        def finder
+          "find_by"
+        end
       end
-    end
 
-    class FindByBang < Method
-      Method.matchers << self
-      include Finder
+      class FindByBang < Method
+        Method.matchers << self
 
-      def self.prefix
-        "find_by"
-      end
+        def self.prefix
+          "find_by"
+        end
 
-      def self.suffix
-        "!"
-      end
+        def self.suffix
+          "!"
+        end
 
-      def finder
-        "find_by!"
+        def finder
+          "find_by!"
+        end
       end
-    end
   end
 end

data/lib/active_record/enum.rb

@@ -1,4 +1,6 @@
-require 'active_support/core_ext/object/deep_dup'
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
 
 module ActiveRecord
   # Declare an enum attribute where the values map to integers in the database,
@@ -18,10 +20,9 @@ module ActiveRecord
   #   conversation.archived? # => true
   #   conversation.status    # => "archived"
   #
-  #   # conversation.update! status: 1
+  #   # conversation.status = 1
   #   conversation.status = "archived"
   #
-  #   # conversation.update! status: nil
   #   conversation.status = nil
   #   conversation.status.nil? # => true
   #   conversation.status      # => nil
@@ -30,7 +31,15 @@ module ActiveRecord
   # as well. With the above example:
   #
   #   Conversation.active
+  #   Conversation.not_active
   #   Conversation.archived
+  #   Conversation.not_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:
   #
@@ -41,13 +50,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
@@ -55,23 +64,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)
-      base.defined_enums = {}
+      base.class_attribute(:defined_enums, instance_writer: false, default: {})
     end
 
     def inherited(base) # :nodoc:
@@ -79,119 +107,167 @@ module ActiveRecord
       super
     end
 
+    class EnumType < Type::Value # :nodoc:
+      delegate :type, to: :subtype
+
+      def initialize(name, mapping, subtype)
+        @name = name
+        @mapping = mapping
+        @subtype = subtype
+      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(subtype.deserialize(value))
+      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
+
+      private
+        attr_reader :name, :mapping, :subtype
+    end
+
     def enum(definitions)
       klass = self
+      enum_prefix = definitions.delete(:_prefix)
+      enum_suffix = definitions.delete(:_suffix)
+      enum_scopes = definitions.delete(:_scopes)
       definitions.each do |name, values|
+        assert_valid_enum_definition_values(values)
         # statuses = { }
         enum_values = ActiveSupport::HashWithIndifferentAccess.new
-        name        = name.to_sym
+        name = name.to_s
+
+        # def self.statuses() statuses end
+        detect_enum_conflict!(name, name.pluralize, true)
+        singleton_class.define_method(name.pluralize) { enum_values }
+        defined_enums[name] = enum_values
 
-        # def self.statuses statuses end
-        detect_enum_conflict!(name, name.to_s.pluralize, true)
-        klass.singleton_class.send(:define_method, name.to_s.pluralize) { enum_values }
+        detect_enum_conflict!(name, name)
+        detect_enum_conflict!(name, "#{name}=")
+
+        attr = attribute_alias?(name) ? attribute_alias(name) : name
+        decorate_attribute_type(attr, :enum) do |subtype|
+          EnumType.new(attr, enum_values, subtype)
+        end
 
         _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}"
+          pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
+          pairs.each do |label, value|
+            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
-          }
 
-          # def status() statuses.key self[:status] end
-          klass.send(:detect_enum_conflict!, name, name)
-          define_method(name) { enum_values.key self[name] }
+            value_method_name = "#{prefix}#{label}#{suffix}"
+            enum_values[label] = value
+            label = label.to_s
 
-          # 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] }
+            # def active?() status == "active" end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}?")
+            define_method("#{value_method_name}?") { self[attr] == label }
 
-          pairs = values.respond_to?(:each_pair) ? values.each_pair : values.each_with_index
-          pairs.each do |value, i|
-            enum_values[value] = i
+            # def active!() update!(status: 0) end
+            klass.send(:detect_enum_conflict!, name, "#{value_method_name}!")
+            define_method("#{value_method_name}!") { update!(attr => value) }
 
-            # def active?() status == 0 end
-            klass.send(:detect_enum_conflict!, name, "#{value}?")
-            define_method("#{value}?") { self[name] == i }
+            # scope :active, -> { where(status: 0) }
+            # scope :not_active, -> { where.not(status: 0) }
+            if enum_scopes != false
+              klass.send(:detect_negative_condition!, value_method_name)
 
-            # 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, true)
+              klass.scope value_method_name, -> { where(attr => 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, "not_#{value_method_name}", true)
+              klass.scope "not_#{value_method_name}", -> { where.not(attr => value) }
+            end
           end
         end
-        defined_enums[name.to_s] = enum_values
+        enum_values.freeze
       end
     end
 
     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
       end
 
+      def assert_valid_enum_definition_values(values)
+        unless values.is_a?(Hash) || values.all? { |v| v.is_a?(Symbol) } || values.all? { |v| v.is_a?(String) }
+          error_message = <<~MSG
+            Enum values #{values} must be either a hash, an array of symbols, or an array of strings.
+          MSG
+          raise ArgumentError, error_message
+        end
+
+        if values.is_a?(Hash) && values.keys.any?(&:blank?) || values.is_a?(Array) && values.any?(&:blank?)
+          raise ArgumentError, "Enum label name must not be blank."
+        end
+      end
+
       ENUM_CONFLICT_MESSAGE = \
         "You tried to define an enum named \"%{enum}\" on the model \"%{klass}\", but " \
         "this will generate a %{type} method \"%{method}\", which is already defined " \
         "by %{source}."
+      private_constant :ENUM_CONFLICT_MESSAGE
 
       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 && method_defined_within?(method_name, Relation)
+          raise_conflict_error(enum_name, method_name, type: "class", source: Relation.name)
         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: name,
+          type: type,
+          method: method_name,
+          source: source
+        }
+      end
+
+      def detect_negative_condition!(method_name)
+        if method_name.start_with?("not_") && logger
+          logger.warn "An enum element in #{self.name} uses the prefix 'not_'." \
+            " This will cause a conflict with auto generated negative scopes."
         end
       end
   end