activemodel 4.2.11.3 → 5.0.0.beta1

data/lib/active_model/callbacks.rb

@@ -6,7 +6,7 @@ module ActiveModel
   # Provides an interface for any class to have Active Record like callbacks.
   #
   # Like the Active Record methods, the callback chain is aborted as soon as
-  # one of the methods in the chain returns +false+.
+  # one of the methods throws +:abort+.
   #
   # First, extend ActiveModel::Callbacks from the class you are creating:
   #
@@ -49,7 +49,7 @@ module ActiveModel
   #    puts 'block successfully called.'
   #  end
   #
-  # You can choose not to have all three callbacks by passing a hash to the
+  # You can choose to have only specific callbacks by passing a hash to the
   # +define_model_callbacks+ method.
   #
   #   define_model_callbacks :create, only: [:after, :before]
@@ -103,7 +103,7 @@ module ActiveModel
     def define_model_callbacks(*callbacks)
       options = callbacks.extract_options!
       options = {
-        terminator: ->(_,result) { result == false },
+        terminator: deprecated_false_terminator,
         skip_after_callbacks_if_terminated: true,
         scope: [:kind, :name],
         only: [:before, :around, :after]

data/lib/active_model/conversion.rb

@@ -22,7 +22,7 @@ module ActiveModel
   module Conversion
     extend ActiveSupport::Concern
 
-    # If your object is already designed to implement all of the Active Model
+    # If your object is already designed to implement all of the \Active \Model
     # you can use the default <tt>:to_model</tt> implementation, which simply
     # returns +self+.
     #
@@ -33,9 +33,9 @@ module ActiveModel
     #   person = Person.new
     #   person.to_model == person # => true
     #
-    # If your model does not act like an Active Model object, then you should
+    # If your model does not act like an \Active \Model object, then you should
     # define <tt>:to_model</tt> yourself returning a proxy object that wraps
-    # your object with Active Model compliant methods.
+    # your object with \Active \Model compliant methods.
     def to_model
       self
     end

data/lib/active_model/dirty.rb

@@ -1,6 +1,5 @@
 require 'active_support/hash_with_indifferent_access'
 require 'active_support/core_ext/object/duplicable'
-require 'active_support/core_ext/string/filters'
 
 module ActiveModel
   # == Active \Model \Dirty
@@ -13,7 +12,7 @@ module ActiveModel
   # * <tt>include ActiveModel::Dirty</tt> in your object.
   # * Call <tt>define_attribute_methods</tt> passing each method you want to
   #   track.
-  # * Call <tt>attr_name_will_change!</tt> before each change to the tracked
+  # * Call <tt>[attr_name]_will_change!</tt> before each change to the tracked
   #   attribute.
   # * Call <tt>changes_applied</tt> after the changes are persisted.
   # * Call <tt>clear_changes_information</tt> when you want to reset the changes
@@ -81,9 +80,11 @@ module ActiveModel
   #
   # Reset the changes:
   #
-  #   person.previous_changes # => {"name" => ["Uncle Bob", "Bill"]}
+  #   person.previous_changes         # => {"name" => ["Uncle Bob", "Bill"]}
+  #   person.name_previously_changed? # => true
+  #   person.name_previous_change     # => ["Uncle Bob", "Bill"]
   #   person.reload!
-  #   person.previous_changes # => {}
+  #   person.previous_changes         # => {}
   #
   # Rollback the changes:
   #
@@ -105,10 +106,10 @@ module ActiveModel
   #   person.changes # => {"name" => ["Bill", "Bob"]}
   #
   # If an attribute is modified in-place then make use of
-  # +[attribute_name]_will_change!+ to mark that the attribute is changing.
-  # Otherwise Active Model can't track changes to in-place attributes. Note
+  # <tt>[attribute_name]_will_change!</tt> to mark that the attribute is changing.
+  # Otherwise \Active \Model can't track changes to in-place attributes. Note
   # that Active Record can detect in-place modifications automatically. You do
-  # not need to call +[attribute_name]_will_change!+ on Active Record models.
+  # not need to call <tt>[attribute_name]_will_change!</tt> on Active Record models.
   #
   #   person.name_will_change!
   #   person.name_change # => ["Bill", "Bill"]
@@ -120,11 +121,11 @@ module ActiveModel
 
     included do
       attribute_method_suffix '_changed?', '_change', '_will_change!', '_was'
-      attribute_method_affix prefix: 'reset_', suffix: '!'
+      attribute_method_suffix '_previously_changed?', '_previous_change'
       attribute_method_affix prefix: 'restore_', suffix: '!'
     end
 
-    # Returns +true+ if any attribute have unsaved changes, +false+ otherwise.
+    # Returns +true+ if any of the attributes have unsaved changes, +false+ otherwise.
     #
     #   person.changed? # => false
     #   person.name = 'bob'
@@ -172,7 +173,7 @@ module ActiveModel
       @changed_attributes ||= ActiveSupport::HashWithIndifferentAccess.new
     end
 
-    # Handle <tt>*_changed?</tt> for +method_missing+.
+    # Handles <tt>*_changed?</tt> for +method_missing+.
     def attribute_changed?(attr, options = {}) #:nodoc:
       result = changes_include?(attr)
       result &&= options[:to] == __send__(attr) if options.key?(:to)
@@ -180,11 +181,16 @@ module ActiveModel
       result
     end
 
-    # Handle <tt>*_was</tt> for +method_missing+.
+    # Handles <tt>*_was</tt> for +method_missing+.
     def attribute_was(attr) # :nodoc:
       attribute_changed?(attr) ? changed_attributes[attr] : __send__(attr)
     end
 
+    # Handles <tt>*_previously_changed?</tt> for +method_missing+.
+    def attribute_previously_changed?(attr, options = {}) #:nodoc:
+      previous_changes_include?(attr)
+    end
+
     # Restore all previous data of the provided attributes.
     def restore_attributes(attributes = changed)
       attributes.each { |attr| restore_attribute! attr }
@@ -192,38 +198,41 @@ module ActiveModel
 
     private
 
+      # Returns +true+ if attr_name is changed, +false+ otherwise.
       def changes_include?(attr_name)
         attributes_changed_by_setter.include?(attr_name)
       end
       alias attribute_changed_by_setter? changes_include?
 
+      # Returns +true+ if attr_name were changed before the model was saved,
+      # +false+ otherwise.
+      def previous_changes_include?(attr_name)
+        previous_changes.include?(attr_name)
+      end
+
       # Removes current changes and makes them accessible through +previous_changes+.
       def changes_applied # :doc:
         @previously_changed = changes
         @changed_attributes = ActiveSupport::HashWithIndifferentAccess.new
       end
 
-      # Clear all dirty data: current changes and previous changes.
+      # Clears all dirty data: current changes and previous changes.
       def clear_changes_information # :doc:
         @previously_changed = ActiveSupport::HashWithIndifferentAccess.new
         @changed_attributes = ActiveSupport::HashWithIndifferentAccess.new
       end
 
-      def reset_changes
-        ActiveSupport::Deprecation.warn(<<-MSG.squish)
-          `#reset_changes` is deprecated and will be removed on Rails 5.
-          Please use `#clear_changes_information` instead.
-        MSG
-
-        clear_changes_information
-      end
-
-      # Handle <tt>*_change</tt> for +method_missing+.
+      # Handles <tt>*_change</tt> for +method_missing+.
       def attribute_change(attr)
         [changed_attributes[attr], __send__(attr)] if attribute_changed?(attr)
       end
 
-      # Handle <tt>*_will_change!</tt> for +method_missing+.
+      # Handles <tt>*_previous_change</tt> for +method_missing+.
+      def attribute_previous_change(attr)
+        previous_changes[attr] if attribute_previously_changed?(attr)
+      end
+
+      # Handles <tt>*_will_change!</tt> for +method_missing+.
       def attribute_will_change!(attr)
         return if attribute_changed?(attr)
 
@@ -236,17 +245,7 @@ module ActiveModel
         set_attribute_was(attr, value)
       end
 
-      # Handle <tt>reset_*!</tt> for +method_missing+.
-      def reset_attribute!(attr)
-        ActiveSupport::Deprecation.warn(<<-MSG.squish)
-          `#reset_#{attr}!` is deprecated and will be removed on Rails 5.
-          Please use `#restore_#{attr}!` instead.
-        MSG
-
-        restore_attribute!(attr)
-      end
-
-      # Handle <tt>restore_*!</tt> for +method_missing+.
+      # Handles <tt>restore_*!</tt> for +method_missing+.
       def restore_attribute!(attr)
         if attribute_changed?(attr)
           __send__("#{attr}=", changed_attributes[attr])
@@ -255,7 +254,7 @@ module ActiveModel
       end
 
       # This is necessary because `changed_attributes` might be overridden in
-      # other implemntations (e.g. in `ActiveRecord`)
+      # other implementations (e.g. in `ActiveRecord`)
       alias_method :attributes_changed_by_setter, :changed_attributes # :nodoc:
 
       # Force an attribute to have a particular "before" value

data/lib/active_model/errors.rb

@@ -1,7 +1,7 @@
-# -*- coding: utf-8 -*-
-
 require 'active_support/core_ext/array/conversions'
 require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/object/deep_dup'
+require 'active_support/core_ext/string/filters'
 
 module ActiveModel
   # == Active \Model \Errors
@@ -23,7 +23,7 @@ module ActiveModel
   #     attr_reader   :errors
   #
   #     def validate!
-  #       errors.add(:name, "cannot be nil") if name.nil?
+  #       errors.add(:name, :blank, message: "cannot be nil") if name.nil?
   #     end
   #
   #     # The following methods are needed to be minimally implemented
@@ -32,20 +32,20 @@ module ActiveModel
   #       send(attr)
   #     end
   #
-  #     def Person.human_attribute_name(attr, options = {})
+  #     def self.human_attribute_name(attr, options = {})
   #       attr
   #     end
   #
-  #     def Person.lookup_ancestors
+  #     def self.lookup_ancestors
   #       [self]
   #     end
   #   end
   #
-  # The last three methods are required in your object for Errors to be
+  # The last three methods are required in your object for +Errors+ to be
   # able to generate error messages correctly and also handle multiple
-  # languages. Of course, if you extend your object with ActiveModel::Translation
+  # languages. Of course, if you extend your object with <tt>ActiveModel::Translation</tt>
   # you will not need to implement the last two. Likewise, using
-  # ActiveModel::Validations will handle the validation related methods
+  # <tt>ActiveModel::Validations</tt> will handle the validation related methods
   # for you.
   #
   # The above allows you to do:
@@ -58,8 +58,9 @@ module ActiveModel
     include Enumerable
 
     CALLBACKS_OPTIONS = [:if, :unless, :on, :allow_nil, :allow_blank, :strict]
+    MESSAGE_OPTIONS = [:message]
 
-    attr_reader :messages
+    attr_reader :messages, :details
 
     # Pass in the instance of the object that is using the errors object.
     #
@@ -70,14 +71,28 @@ module ActiveModel
     #   end
     def initialize(base)
       @base     = base
-      @messages = {}
+      @messages = Hash.new { |messages, attribute| messages[attribute] = [] }
+      @details  = Hash.new { |details, attribute| details[attribute] = [] }
     end
 
     def initialize_dup(other) # :nodoc:
       @messages = other.messages.dup
+      @details  = other.details.deep_dup
       super
     end
 
+    # Copies the errors from <tt>other</tt>.
+    #
+    # other - The ActiveModel::Errors instance.
+    #
+    # Examples
+    #
+    #   person.errors.copy!(other)
+    def copy!(other) # :nodoc:
+      @messages = other.messages.dup
+      @details  = other.details.dup
+    end
+
     # Clear the error messages.
     #
     #   person.errors.full_messages # => ["name cannot be nil"]
@@ -85,6 +100,7 @@ module ActiveModel
     #   person.errors.full_messages # => []
     def clear
       messages.clear
+      details.clear
     end
 
     # Returns +true+ if the error messages include an error for the given key
@@ -96,35 +112,46 @@ module ActiveModel
     def include?(attribute)
       messages[attribute].present?
     end
-    # aliases include?
     alias :has_key? :include?
-    # aliases include?
     alias :key? :include?
 
     # Get messages for +key+.
     #
     #   person.errors.messages   # => {:name=>["cannot be nil"]}
     #   person.errors.get(:name) # => ["cannot be nil"]
-    #   person.errors.get(:age)  # => nil
+    #   person.errors.get(:age)  # => []
     def get(key)
+      ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+        ActiveModel::Errors#get is deprecated and will be removed in Rails 5.1.
+
+        To achieve the same use model.errors[:#{key}].
+      MESSAGE
+
       messages[key]
     end
 
     # Set messages for +key+ to +value+.
     #
-    #   person.errors.get(:name) # => ["cannot be nil"]
+    #   person.errors[:name] # => ["cannot be nil"]
     #   person.errors.set(:name, ["can't be nil"])
-    #   person.errors.get(:name) # => ["can't be nil"]
+    #   person.errors[:name] # => ["can't be nil"]
     def set(key, value)
+      ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+        ActiveModel::Errors#set is deprecated and will be removed in Rails 5.1.
+
+        Use model.errors.add(:#{key}, #{value.inspect}) instead.
+      MESSAGE
+
       messages[key] = value
     end
 
     # Delete messages for +key+. Returns the deleted messages.
     #
-    #   person.errors.get(:name)    # => ["cannot be nil"]
+    #   person.errors[:name]    # => ["cannot be nil"]
     #   person.errors.delete(:name) # => ["cannot be nil"]
-    #   person.errors.get(:name)    # => nil
+    #   person.errors[:name]    # => []
     def delete(key)
+      details.delete(key)
       messages.delete(key)
     end
 
@@ -134,7 +161,7 @@ module ActiveModel
     #   person.errors[:name]  # => ["cannot be nil"]
     #   person.errors['name'] # => ["cannot be nil"]
     def [](attribute)
-      get(attribute.to_sym) || set(attribute.to_sym, [])
+      messages[attribute.to_sym]
     end
 
     # Adds to the supplied attribute the supplied error message.
@@ -142,38 +169,45 @@ module ActiveModel
     #   person.errors[:name] = "must be set"
     #   person.errors[:name] # => ['must be set']
     def []=(attribute, error)
-      self[attribute] << error
+      ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+        ActiveModel::Errors#[]= is deprecated and will be removed in Rails 5.1.
+
+        Use model.errors.add(:#{attribute}, #{error.inspect}) instead.
+      MESSAGE
+
+      messages[attribute.to_sym] << error
     end
 
     # Iterates through each error key, value pair in the error messages hash.
     # Yields the attribute and the error for that attribute. If the attribute
     # has more than one error message, yields once for each error message.
     #
-    #   person.errors.add(:name, "can't be blank")
+    #   person.errors.add(:name, :blank, message: "can't be blank")
     #   person.errors.each do |attribute, error|
     #     # Will yield :name and "can't be blank"
     #   end
     #
-    #   person.errors.add(:name, "must be specified")
+    #   person.errors.add(:name, :not_specified, message: "must be specified")
     #   person.errors.each do |attribute, error|
     #     # Will yield :name and "can't be blank"
     #     # then yield :name and "must be specified"
     #   end
     def each
       messages.each_key do |attribute|
-        self[attribute].each { |error| yield attribute, error }
+        messages[attribute].each { |error| yield attribute, error }
       end
     end
 
     # Returns the number of error messages.
     #
-    #   person.errors.add(:name, "can't be blank")
+    #   person.errors.add(:name, :blank, message: "can't be blank")
     #   person.errors.size # => 1
-    #   person.errors.add(:name, "must be specified")
+    #   person.errors.add(:name, :not_specified, message: "must be specified")
     #   person.errors.size # => 2
     def size
       values.flatten.size
     end
+    alias :count :size
 
     # Returns all message values.
     #
@@ -191,40 +225,20 @@ module ActiveModel
       messages.keys
     end
 
-    # Returns an array of error messages, with the attribute name included.
-    #
-    #   person.errors.add(:name, "can't be blank")
-    #   person.errors.add(:name, "must be specified")
-    #   person.errors.to_a # => ["name can't be blank", "name must be specified"]
-    def to_a
-      full_messages
-    end
-
-    # Returns the number of error messages.
-    #
-    #   person.errors.add(:name, "can't be blank")
-    #   person.errors.count # => 1
-    #   person.errors.add(:name, "must be specified")
-    #   person.errors.count # => 2
-    def count
-      to_a.size
-    end
-
     # Returns +true+ if no errors are found, +false+ otherwise.
     # If the error message is a string it can be empty.
     #
     #   person.errors.full_messages # => ["name cannot be nil"]
     #   person.errors.empty?        # => false
     def empty?
-      all? { |k, v| v && v.empty? && !v.is_a?(String) }
+      size.zero?
     end
-    # aliases empty?
-    alias_method :blank?, :empty?
+    alias :blank? :empty?
 
     # Returns an xml formatted representation of the Errors hash.
     #
-    #   person.errors.add(:name, "can't be blank")
-    #   person.errors.add(:name, "must be specified")
+    #   person.errors.add(:name, :blank, message: "can't be blank")
+    #   person.errors.add(:name, :not_specified, message: "must be specified")
     #   person.errors.to_xml
     #   # =>
     #   #  <?xml version=\"1.0\" encoding=\"UTF-8\"?>
@@ -261,17 +275,20 @@ module ActiveModel
       end
     end
 
-    # Adds +message+ to the error messages on +attribute+. More than one error
-    # can be added to the same +attribute+. If no +message+ is supplied,
-    # <tt>:invalid</tt> is assumed.
+    # Adds +message+ to the error messages and used validator type to +details+ on +attribute+.
+    # More than one error can be added to the same +attribute+.
+    # If no +message+ is supplied, <tt>:invalid</tt> is assumed.
     #
     #   person.errors.add(:name)
     #   # => ["is invalid"]
-    #   person.errors.add(:name, 'must be implemented')
+    #   person.errors.add(:name, :not_implemented, message: "must be implemented")
     #   # => ["is invalid", "must be implemented"]
     #
     #   person.errors.messages
-    #   # => {:name=>["must be implemented", "is invalid"]}
+    #   # => {:name=>["is invalid", "must be implemented"]}
+    #
+    #   person.errors.details
+    #   # => {:name=>[{error: :not_implemented}, {error: :invalid}]}
     #
     # If +message+ is a symbol, it will be translated using the appropriate
     # scope (see +generate_message+).
@@ -283,9 +300,9 @@ module ActiveModel
     # ActiveModel::StrictValidationFailed instead of adding the error.
     # <tt>:strict</tt> option can also be set to any other exception.
     #
-    #   person.errors.add(:name, nil, strict: true)
+    #   person.errors.add(:name, :invalid, strict: true)
     #   # => ActiveModel::StrictValidationFailed: name is invalid
-    #   person.errors.add(:name, nil, strict: NameIsInvalid)
+    #   person.errors.add(:name, :invalid, strict: NameIsInvalid)
     #   # => NameIsInvalid: name is invalid
     #
     #   person.errors.messages # => {}
@@ -293,17 +310,23 @@ module ActiveModel
     # +attribute+ should be set to <tt>:base</tt> if the error is not
     # directly associated with a single attribute.
     #
-    #   person.errors.add(:base, "either name or email must be present")
+    #   person.errors.add(:base, :name_or_email_blank,
+    #     message: "either name or email must be present")
     #   person.errors.messages
     #   # => {:base=>["either name or email must be present"]}
+    #   person.errors.details
+    #   # => {:base=>[{error: :name_or_email_blank}]}
     def add(attribute, message = :invalid, options = {})
+      message = message.call if message.respond_to?(:call)
+      detail  = normalize_detail(attribute, message, options)
       message = normalize_message(attribute, message, options)
       if exception = options[:strict]
         exception = ActiveModel::StrictValidationFailed if exception == true
         raise exception, full_message(attribute, message)
       end
 
-      self[attribute] << message
+      details[attribute.to_sym]  << detail
+      messages[attribute.to_sym] << message
     end
 
     # Will add an error message to each of the attributes in +attributes+
@@ -313,6 +336,14 @@ module ActiveModel
     #   person.errors.messages
     #   # => {:name=>["can't be empty"]}
     def add_on_empty(attributes, options = {})
+      ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+        ActiveModel::Errors#add_on_empty is deprecated and will be removed in Rails 5.1
+
+        To achieve the same use:
+
+          errors.add(attribute, :empty, options) if value.nil? || value.empty?
+      MESSAGE
+
       Array(attributes).each do |attribute|
         value = @base.send(:read_attribute_for_validation, attribute)
         is_empty = value.respond_to?(:empty?) ? value.empty? : false
@@ -327,6 +358,14 @@ module ActiveModel
     #   person.errors.messages
     #   # => {:name=>["can't be blank"]}
     def add_on_blank(attributes, options = {})
+      ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+        ActiveModel::Errors#add_on_blank is deprecated and will be removed in Rails 5.1
+
+        To achieve the same use:
+
+          errors.add(attribute, :empty, options) if value.blank?
+      MESSAGE
+
       Array(attributes).each do |attribute|
         value = @base.send(:read_attribute_for_validation, attribute)
         add(attribute, :blank, options) if value.blank?
@@ -339,6 +378,7 @@ module ActiveModel
     #   person.errors.add :name, :blank
     #   person.errors.added? :name, :blank # => true
     def added?(attribute, message = :invalid, options = {})
+      message = message.call if message.respond_to?(:call)
       message = normalize_message(attribute, message, options)
       self[attribute].include? message
     end
@@ -356,6 +396,7 @@ module ActiveModel
     def full_messages
       map { |attribute, message| full_message(attribute, message) }
     end
+    alias :to_a :full_messages
 
     # Returns all the full error messages for a given attribute in an array.
     #
@@ -368,7 +409,7 @@ module ActiveModel
     #   person.errors.full_messages_for(:name)
     #   # => ["Name is too short (minimum is 5 characters)", "Name can't be blank"]
     def full_messages_for(attribute)
-      (get(attribute) || []).map { |message| full_message(attribute, message) }
+      messages[attribute].map { |message| full_message(attribute, message) }
     end
 
     # Returns a full message for a given attribute.
@@ -388,8 +429,8 @@ module ActiveModel
     # Translates an error message in its default scope
     # (<tt>activemodel.errors.messages</tt>).
     #
-    # Error messages are first looked up in <tt>models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>,
-    # if it's not there, it's looked up in <tt>models.MODEL.MESSAGE</tt> and if
+    # Error messages are first looked up in <tt>activemodel.errors.models.MODEL.attributes.ATTRIBUTE.MESSAGE</tt>,
+    # if it's not there, it's looked up in <tt>activemodel.errors.models.MODEL.MESSAGE</tt> and if
     # that is not there also, it returns the translation of the default message
     # (e.g. <tt>activemodel.errors.messages.MESSAGE</tt>). The translated model
     # name, translated attribute name and the value are available for
@@ -421,7 +462,6 @@ module ActiveModel
         defaults = []
       end
 
-      defaults << options.delete(:message)
       defaults << :"#{@base.class.i18n_scope}.errors.messages.#{type}" if @base.class.respond_to?(:i18n_scope)
       defaults << :"errors.attributes.#{attribute}.#{type}"
       defaults << :"errors.messages.#{type}"
@@ -430,6 +470,7 @@ module ActiveModel
       defaults.flatten!
 
       key = defaults.shift
+      defaults = options.delete(:message) if options[:message]
       value = (attribute != :base ? @base.send(:read_attribute_for_validation, attribute) : nil)
 
       options = {
@@ -447,12 +488,14 @@ module ActiveModel
       case message
       when Symbol
         generate_message(attribute, message, options.except(*CALLBACKS_OPTIONS))
-      when Proc
-        message.call
       else
         message
       end
     end
+
+    def normalize_detail(attribute, message, options)
+      { error: message }.merge(options.except(*CALLBACKS_OPTIONS + MESSAGE_OPTIONS))
+    end
   end
 
   # Raised when a validation cannot be corrected by end users and are considered
@@ -472,4 +515,15 @@ module ActiveModel
   #   # => ActiveModel::StrictValidationFailed: Name can't be blank
   class StrictValidationFailed < StandardError
   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
+      super("unknown attribute '#{attribute}' for #{@record.class}.")
+    end
+  end
 end