activemodel 7.0.8 → 7.1.0

data/lib/active_model/serialization.rb

@@ -3,7 +3,7 @@
 require "active_support/core_ext/enumerable"
 
 module ActiveModel
-  # == Active \Model \Serialization
+  # = Active \Model \Serialization
   #
   # Provides a basic serialization to a serializable_hash for your objects.
   #
@@ -33,8 +33,8 @@ module ActiveModel
   # at the private method +read_attribute_for_serialization+.
   #
   # ActiveModel::Serializers::JSON module automatically includes
-  # the <tt>ActiveModel::Serialization</tt> module, so there is no need to
-  # explicitly include <tt>ActiveModel::Serialization</tt>.
+  # the +ActiveModel::Serialization+ module, so there is no need to
+  # explicitly include +ActiveModel::Serialization+.
   #
   # A minimal implementation including JSON would be:
   #

data/lib/active_model/serializers/json.rb

@@ -4,7 +4,7 @@ require "active_support/json"
 
 module ActiveModel
   module Serializers
-    # == Active \Model \JSON \Serializer
+    # = Active \Model \JSON \Serializer
     module JSON
       extend ActiveSupport::Concern
       include ActiveModel::Serialization

data/lib/active_model/translation.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module ActiveModel
-  # == Active \Model \Translation
+  # = Active \Model \Translation
   #
-  # Provides integration between your object and the Rails internationalization
+  # Provides integration between your object and the \Rails internationalization
   # (i18n) framework.
   #
   # A minimal implementation could be:
@@ -16,7 +16,7 @@ module ActiveModel
   #   # => "My attribute"
   #
   # This also provides the required class methods for hooking into the
-  # Rails internationalization API, including being able to define a
+  # \Rails internationalization API, including being able to define a
   # class-based +i18n_scope+ and +lookup_ancestors+ to find translations in
   # parent classes.
   module Translation
@@ -35,6 +35,8 @@ module ActiveModel
       ancestors.select { |x| x.respond_to?(:model_name) }
     end
 
+    MISSING_TRANSLATION = -(2**60) # :nodoc:
+
     # Transforms attribute names into a more human format, such as "First name"
     # instead of "first_name".
     #
@@ -42,29 +44,29 @@ module ActiveModel
     #
     # Specify +options+ with additional translating options.
     def human_attribute_name(attribute, options = {})
-      options   = { count: 1 }.merge!(options)
-      parts     = attribute.to_s.split(".")
-      attribute = parts.pop
-      namespace = parts.join("/") unless parts.empty?
-      attributes_scope = "#{i18n_scope}.attributes"
+      attribute = attribute.to_s
+
+      if attribute.include?(".")
+        namespace, _, attribute = attribute.rpartition(".")
+        namespace.tr!(".", "/")
 
-      if namespace
         defaults = lookup_ancestors.map do |klass|
-          :"#{attributes_scope}.#{klass.model_name.i18n_key}/#{namespace}.#{attribute}"
+          :"#{i18n_scope}.attributes.#{klass.model_name.i18n_key}/#{namespace}.#{attribute}"
         end
-        defaults << :"#{attributes_scope}.#{namespace}.#{attribute}"
+        defaults << :"#{i18n_scope}.attributes.#{namespace}.#{attribute}"
       else
         defaults = lookup_ancestors.map do |klass|
-          :"#{attributes_scope}.#{klass.model_name.i18n_key}.#{attribute}"
+          :"#{i18n_scope}.attributes.#{klass.model_name.i18n_key}.#{attribute}"
         end
       end
 
       defaults << :"attributes.#{attribute}"
-      defaults << options.delete(:default) if options[:default]
-      defaults << attribute.humanize
+      defaults << options[:default] if options[:default]
+      defaults << MISSING_TRANSLATION
 
-      options[:default] = defaults
-      I18n.translate(defaults.shift, **options)
+      translation = I18n.translate(defaults.shift, count: 1, **options, default: defaults)
+      translation = attribute.humanize if translation == MISSING_TRANSLATION
+      translation
     end
   end
 end

data/lib/active_model/type/big_integer.rb

@@ -4,7 +4,29 @@ require "active_model/type/integer"
 
 module ActiveModel
   module Type
-    class BigInteger < Integer # :nodoc:
+    # = Active Model \BigInteger \Type
+    #
+    # Attribute type for integers that can be serialized to an unlimited number
+    # of bytes. This type is registered under the +:big_integer+ key.
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :id, :big_integer
+    #   end
+    #
+    #   person = Person.new
+    #   person.id = "18_000_000_000"
+    #
+    #   person.id # => 18000000000
+    #
+    # All casting and serialization are performed in the same way as the
+    # standard ActiveModel::Type::Integer type.
+    class BigInteger < Integer
+      def serialize_cast_value(value) # :nodoc:
+        value
+      end
+
       private
         def max_value
           ::Float::INFINITY

data/lib/active_model/type/binary.rb

@@ -2,7 +2,13 @@
 
 module ActiveModel
   module Type
-    class Binary < Value # :nodoc:
+    # = Active Model \Binary \Type
+    #
+    # Attribute type for representation of binary data. This type is registered
+    # under the +:binary+ key.
+    #
+    # Non-string values are coerced to strings using their +to_s+ method.
+    class Binary < Value
       def type
         :binary
       end

data/lib/active_model/type/boolean.rb

@@ -2,17 +2,15 @@
 
 module ActiveModel
   module Type
-    # == Active \Model \Type \Boolean
+    # = Active Model \Boolean \Type
     #
-    # A class that behaves like a boolean type, including rules for coercion of user input.
+    # A class that behaves like a boolean type, including rules for coercion of
+    # user input.
     #
-    # === Coercion
-    # Values set from user input will first be coerced into the appropriate ruby type.
-    # Coercion behavior is roughly mapped to Ruby's boolean semantics.
-    #
-    # - "false", "f" , "0", +0+ or any other value in +FALSE_VALUES+ will be coerced to +false+
-    # - Empty strings are coerced to +nil+
-    # - All other values will be coerced to +true+
+    # - <tt>"false"</tt>, <tt>"f"</tt>, <tt>"0"</tt>, +0+ or any other value in
+    #   +FALSE_VALUES+ will be coerced to +false+.
+    # - Empty strings are coerced to +nil+.
+    # - All other values will be coerced to +true+.
     class Boolean < Value
       FALSE_VALUES = [
         false, 0,
@@ -33,6 +31,10 @@ module ActiveModel
         cast(value)
       end
 
+      def serialize_cast_value(value) # :nodoc:
+        value
+      end
+
       private
         def cast_value(value)
           if value == ""

data/lib/active_model/type/date.rb

@@ -2,7 +2,28 @@
 
 module ActiveModel
   module Type
-    class Date < Value # :nodoc:
+    # = Active Model \Date \Type
+    #
+    # Attribute type for date representation. It is registered under the
+    # +:date+ key.
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :birthday, :date
+    #   end
+    #
+    #   person = Person.new
+    #   person.birthday = "1989-07-13"
+    #
+    #   person.birthday.class # => Date
+    #   person.birthday.year  # => 1989
+    #   person.birthday.month # => 7
+    #   person.birthday.day   # => 13
+    #
+    # String values are parsed using the ISO 8601 date format. Any other values
+    # are cast using their +to_date+ method, if it exists.
+    class Date < Value
       include Helpers::Timezone
       include Helpers::AcceptsMultiparameterTime.new
 
@@ -34,7 +55,12 @@ module ActiveModel
         end
 
         def fallback_string_to_date(string)
-          new_date(*::Date._parse(string, false).values_at(:year, :mon, :mday))
+          parts = begin
+            ::Date._parse(string, false)
+          rescue ArgumentError
+          end
+
+          new_date(*parts.values_at(:year, :mon, :mday)) if parts
         end
 
         def new_date(year, mon, mday)

data/lib/active_model/type/date_time.rb

@@ -2,12 +2,49 @@
 
 module ActiveModel
   module Type
-    class DateTime < Value # :nodoc:
+    # = Active Model \DateTime \Type
+    #
+    # Attribute type to represent dates and times. It is registered under the
+    # +:datetime+ key.
+    #
+    #   class Event
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :start, :datetime
+    #   end
+    #
+    #   event = Event.new
+    #   event.start = "Wed, 04 Sep 2013 03:00:00 EAT"
+    #
+    #   event.start.class # => Time
+    #   event.start.year  # => 2013
+    #   event.start.month # => 9
+    #   event.start.day   # => 4
+    #   event.start.hour  # => 3
+    #   event.start.min   # => 0
+    #   event.start.sec   # => 0
+    #   event.start.zone  # => "EAT"
+    #
+    # String values are parsed using the ISO 8601 datetime format. Partial
+    # time-only formats are also accepted.
+    #
+    #   event.start = "06:07:08+09:00"
+    #   event.start.utc # => 1999-12-31 21:07:08 UTC
+    #
+    # The degree of sub-second precision can be customized when declaring an
+    # attribute:
+    #
+    #   class Event
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :start, :datetime, precision: 4
+    #   end
+    class DateTime < Value
       include Helpers::Timezone
-      include Helpers::TimeValue
       include Helpers::AcceptsMultiparameterTime.new(
         defaults: { 4 => 0, 5 => 0 }
       )
+      include Helpers::TimeValue
 
       def type
         :datetime
@@ -28,7 +65,12 @@ module ActiveModel
         end
 
         def fallback_string_to_time(string)
-          time_hash = ::Date._parse(string)
+          time_hash = begin
+            ::Date._parse(string)
+          rescue ArgumentError
+          end
+          return unless time_hash
+
           time_hash[:sec_fraction] = microseconds(time_hash)
 
           new_time(*time_hash.values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset))

data/lib/active_model/type/decimal.rb

@@ -4,7 +4,45 @@ require "bigdecimal/util"
 
 module ActiveModel
   module Type
-    class Decimal < Value # :nodoc:
+    # = Active Model \Decimal \Type
+    #
+    # Attribute type for decimal, high-precision floating point numeric
+    # representation. It is registered under the +:decimal+ key.
+    #
+    #   class BagOfCoffee
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :weight, :decimal
+    #   end
+    #
+    # Numeric instances are converted to BigDecimal instances. Any other objects
+    # are cast using their +to_d+ method, except for blank strings, which are
+    # cast to +nil+. If a +to_d+ method is not defined, the object is converted
+    # to a string using +to_s+, which is then cast using +to_d+.
+    #
+    #   bag = BagOfCoffee.new
+    #
+    #   bag.weight = 0.01
+    #   bag.weight # => 0.1e-1
+    #
+    #   bag.weight = "0.01"
+    #   bag.weight # => 0.1e-1
+    #
+    #   bag.weight = ""
+    #   bag.weight # => nil
+    #
+    #   bag.weight = :arbitrary
+    #   bag.weight # => nil (the result of `.to_s.to_d`)
+    #
+    # Decimal precision defaults to 18, and can be customized when declaring an
+    # attribute:
+    #
+    #   class BagOfCoffee
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :weight, :decimal, precision: 24
+    #   end
+    class Decimal < Value
       include Helpers::Numeric
       BIGDECIMAL_PRECISION = 18
 

data/lib/active_model/type/float.rb

@@ -4,7 +4,36 @@ require "active_support/core_ext/object/try"
 
 module ActiveModel
   module Type
-    class Float < Value # :nodoc:
+    # = Active Model \Float \Type
+    #
+    # Attribute type for floating point numeric values. It is registered under
+    # the +:float+ key.
+    #
+    #   class BagOfCoffee
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :weight, :float
+    #   end
+    #
+    # Values are cast using their +to_f+ method, except for the following
+    # strings:
+    #
+    # - Blank strings are cast to +nil+.
+    # - <tt>"Infinity"</tt> is cast to +Float::INFINITY+.
+    # - <tt>"-Infinity"</tt> is cast to <tt>-Float::INFINITY</tt>.
+    # - <tt>"NaN"</tt> is cast to +Float::NAN+.
+    #
+    #   bag = BagOfCoffee.new
+    #
+    #   bag.weight = "0.25"
+    #   bag.weight # => 0.25
+    #
+    #   bag.weight = ""
+    #   bag.weight # => nil
+    #
+    #   bag.weight = "NaN"
+    #   bag.weight # => Float::NAN
+    class Float < Value
       include Helpers::Numeric
 
       def type

data/lib/active_model/type/helpers/accepts_multiparameter_time.rb

@@ -6,7 +6,11 @@ module ActiveModel
       class AcceptsMultiparameterTime < Module
         module InstanceMethods
           def serialize(value)
-            super(cast(value))
+            serialize_cast_value(cast(value))
+          end
+
+          def serialize_cast_value(value)
+            value
           end
 
           def cast(value)

data/lib/active_model/type/helpers/numeric.rb

@@ -8,6 +8,10 @@ module ActiveModel
           cast(value)
         end
 
+        def serialize_cast_value(value)
+          value
+        end
+
         def cast(value)
           # Checks whether the value is numeric. Spaceship operator
           # will return nil if value is not numeric.

data/lib/active_model/type/helpers/time_value.rb

@@ -7,7 +7,7 @@ module ActiveModel
   module Type
     module Helpers # :nodoc: all
       module TimeValue
-        def serialize(value)
+        def serialize_cast_value(value)
           value = apply_seconds_precision(value)
 
           if value.acts_like?(:time)
@@ -69,20 +69,36 @@ module ActiveModel
             \z
           /x
 
-          def fast_string_to_time(string)
-            return unless ISO_DATETIME =~ string
-
-            usec = $7.to_i
-            usec_len = $7&.length
-            if usec_len&.< 6
-              usec *= 10**(6 - usec_len)
+          if RUBY_VERSION >= "3.2"
+            def fast_string_to_time(string)
+              return unless ISO_DATETIME.match?(string)
+
+              if is_utc?
+                # XXX: Wrapping the Time object with Time.at because Time.new with `in:` in Ruby 3.2.0 used to return an invalid Time object
+                # see: https://bugs.ruby-lang.org/issues/19292
+                ::Time.at(::Time.new(string, in: "UTC"))
+              else
+                ::Time.new(string)
+              end
+            rescue ArgumentError
+              nil
             end
+          else
+            def fast_string_to_time(string)
+              return unless ISO_DATETIME =~ string
 
-            if $8
-              offset = $8 == "Z" ? 0 : $8.to_i * 3600 + $9.to_i * 60
-            end
+              usec = $7.to_i
+              usec_len = $7&.length
+              if usec_len&.< 6
+                usec *= 10**(6 - usec_len)
+              end
 
-            new_time($1.to_i, $2.to_i, $3.to_i, $4.to_i, $5.to_i, $6.to_i, usec, offset)
+              if $8
+                offset = $8 == "Z" ? 0 : $8.to_i * 3600 + $9.to_i * 60
+              end
+
+              new_time($1.to_i, $2.to_i, $3.to_i, $4.to_i, $5.to_i, $6.to_i, usec, offset)
+            end
           end
       end
     end

data/lib/active_model/type/immutable_string.rb

@@ -2,7 +2,39 @@
 
 module ActiveModel
   module Type
-    class ImmutableString < Value # :nodoc:
+    # = Active Model \ImmutableString \Type
+    #
+    # Attribute type to represent immutable strings. It casts incoming values to
+    # frozen strings.
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :name, :immutable_string
+    #   end
+    #
+    #   person = Person.new
+    #   person.name = 1
+    #
+    #   person.name # => "1"
+    #   person.name.frozen? # => true
+    #
+    # Values are coerced to strings using their +to_s+ method. Boolean values
+    # are treated differently, however: +true+ will be cast to <tt>"t"</tt> and
+    # +false+ will be cast to <tt>"f"</tt>. These strings can be customized when
+    # declaring an attribute:
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :active, :immutable_string, true: "aye", false: "nay"
+    #   end
+    #
+    #   person = Person.new
+    #   person.active = true
+    #
+    #   person.active # => "aye"
+    class ImmutableString < Value
       def initialize(**args)
         @true  = -(args.delete(:true)&.to_s  || "t")
         @false = -(args.delete(:false)&.to_s || "f")
@@ -22,6 +54,10 @@ module ActiveModel
         end
       end
 
+      def serialize_cast_value(value) # :nodoc:
+        value
+      end
+
       private
         def cast_value(value)
           case value

data/lib/active_model/type/integer.rb

@@ -2,7 +2,46 @@
 
 module ActiveModel
   module Type
-    class Integer < Value # :nodoc:
+    # = Active Model \Integer \Type
+    #
+    # Attribute type for integer representation. This type is registered under
+    # the +:integer+ key.
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :age, :integer
+    #   end
+    #
+    # Values are cast using their +to_i+ method, except for blank strings, which
+    # are cast to +nil+. If a +to_i+ method is not defined or raises an error,
+    # the value will be cast to +nil+.
+    #
+    #   person = Person.new
+    #
+    #   person.age = "18"
+    #   person.age # => 18
+    #
+    #   person.age = ""
+    #   person.age # => nil
+    #
+    #   person.age = :not_an_integer
+    #   person.age # => nil (because Symbol does not define #to_i)
+    #
+    # Serialization also works under the same principle. Non-numeric strings are
+    # serialized as +nil+, for example.
+    #
+    # Serialization also validates that the integer can be stored using a
+    # limited number of bytes. If it cannot, an ActiveModel::RangeError will be
+    # raised. The default limit is 4 bytes, and can be customized when declaring
+    # an attribute:
+    #
+    #   class Person
+    #     include ActiveModel::Attributes
+    #
+    #     attribute :age, :integer, limit: 6
+    #   end
+    class Integer < Value
       include Helpers::Numeric
 
       # Column storage size in bytes.
@@ -28,6 +67,10 @@ module ActiveModel
         ensure_in_range(super)
       end
 
+      def serialize_cast_value(value) # :nodoc:
+        ensure_in_range(value)
+      end
+
       def serializable?(value)
         cast_value = cast(value)
         in_range?(cast_value) || begin

data/lib/active_model/type/serialize_cast_value.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ActiveModel
+  module Type
+    module SerializeCastValue # :nodoc:
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def serialize_cast_value_compatible?
+          return @serialize_cast_value_compatible if defined?(@serialize_cast_value_compatible)
+          @serialize_cast_value_compatible = ancestors.index(instance_method(:serialize_cast_value).owner) <= ancestors.index(instance_method(:serialize).owner)
+        end
+      end
+
+      module DefaultImplementation
+        def serialize_cast_value(value)
+          value
+        end
+      end
+
+      def self.included(klass)
+        klass.include DefaultImplementation unless klass.method_defined?(:serialize_cast_value)
+      end
+
+      def self.serialize(type, value)
+        # Using `type.equal?(type.itself_if_...)` is a performant way to also
+        # ensure that `type` is not just a DelegateClass instance (e.g.
+        # ActiveRecord::Type::Serialized) unintentionally delegating
+        # SerializeCastValue methods.
+        if type.equal?((type.itself_if_serialize_cast_value_compatible rescue nil))
+          type.serialize_cast_value(value)
+        else
+          type.serialize(value)
+        end
+      end
+
+      def itself_if_serialize_cast_value_compatible
+        self if self.class.serialize_cast_value_compatible?
+      end
+
+      def initialize(...)
+        super
+        self.class.serialize_cast_value_compatible? # eagerly compute
+      end
+    end
+  end
+end

data/lib/active_model/type/string.rb

@@ -4,7 +4,15 @@ require "active_model/type/immutable_string"
 
 module ActiveModel
   module Type
-    class String < ImmutableString # :nodoc:
+    # = Active Model \String \Type
+    #
+    # Attribute type for strings. It is registered under the +:string+ key.
+    #
+    # This class is a specialization of ActiveModel::Type::ImmutableString. It
+    # performs coercion in the same way, and can be configured in the same way.
+    # However, it accounts for mutable strings, so dirty tracking can properly
+    # check if a string has changed.
+    class String < ImmutableString
       def changed_in_place?(raw_old_value, new_value)
         if new_value.is_a?(::String)
           raw_old_value != new_value