activerecord 4.1.15 → 4.2.0.beta1

data/lib/active_record/associations.rb

@@ -202,12 +202,13 @@ module ActiveRecord
     # For instance, +attributes+ and +connection+ would be bad choices for association names.
     #
     # == Auto-generated methods
+    # See also Instance Public methods below for more details.
     #
     # === Singular associations (one-to-one)
     #                                     |            |  belongs_to  |
     #   generated methods                 | belongs_to | :polymorphic | has_one
     #   ----------------------------------+------------+--------------+---------
-    #   other                             |     X      |      X       |    X
+    #   other(force_reload=false)         |     X      |      X       |    X
     #   other=(other)                     |     X      |      X       |    X
     #   build_other(attributes={})        |     X      |              |    X
     #   create_other(attributes={})       |     X      |              |    X
@@ -217,7 +218,7 @@ module ActiveRecord
     #                                     |       |          | has_many
     #   generated methods                 | habtm | has_many | :through
     #   ----------------------------------+-------+----------+----------
-    #   others                            |   X   |    X     |    X
+    #   others(force_reload=false)        |   X   |    X     |    X
     #   others=(other,other,...)          |   X   |    X     |    X
     #   other_ids                         |   X   |    X     |    X
     #   other_ids=(id,id,...)             |   X   |    X     |    X
@@ -419,6 +420,10 @@ module ActiveRecord
     #     has_many :birthday_events, ->(user) { where starts_on: user.birthday }, class_name: 'Event'
     #   end
     #
+    # Note: Joining, eager loading and preloading of these associations is not fully possible.
+    # These operations happen before instance creation and the scope will be called with a +nil+ argument.
+    # This can lead to unexpected behavior and is deprecated.
+    #
     # == Association callbacks
     #
     # Similar to the normal callbacks that hook into the life cycle of an Active Record object,
@@ -536,8 +541,8 @@ module ActiveRecord
     #   end
     #
     #   @firm = Firm.first
-    #   @firm.clients.collect { |c| c.invoices }.flatten # select all invoices for all clients of the firm
-    #   @firm.invoices                                   # selects all invoices by going through the Client join model
+    #   @firm.clients.flat_map { |c| c.invoices } # select all invoices for all clients of the firm
+    #   @firm.invoices                            # selects all invoices by going through the Client join model
     #
     # Similarly you can go through a +has_one+ association on the join model:
     #
@@ -712,9 +717,9 @@ module ActiveRecord
     # == Eager loading of associations
     #
     # Eager loading is a way to find objects of a certain class and a number of named associations.
-    # This is one of the easiest ways of to prevent the dreaded 1+N problem in which fetching 100
+    # This is one of the easiest ways of to prevent the dreaded N+1 problem in which fetching 100
     # posts that each need to display their author triggers 101 database queries. Through the
-    # use of eager loading, the 101 queries can be reduced to 2.
+    # use of eager loading, the number of queries will be reduced from 101 to 2.
     #
     #   class Post < ActiveRecord::Base
     #     belongs_to :author
@@ -774,16 +779,15 @@ module ActiveRecord
     # In the above example posts with no approved comments are not returned at all, because
     # the conditions apply to the SQL statement as a whole and not just to the association.
     #
+    # You must disambiguate column references for this fallback to happen, for example
+    # <tt>order: "author.name DESC"</tt> will work but <tt>order: "name DESC"</tt> will not.
+    #
     # If you want to load all posts (including posts with no approved comments) then write
     # your own LEFT OUTER JOIN query using ON
     #
-    #   Post.joins('LEFT OUTER JOIN comments ON comments.post_id = posts.id AND comments.approved = true')
+    #   Post.joins("LEFT OUTER JOIN comments ON comments.post_id = posts.id AND comments.approved = '1'")
     #
-    # You must disambiguate column references for this fallback to happen, for example
-    # <tt>order: "author.name DESC"</tt> will work but <tt>order: "name DESC"</tt> will not.
-    #
-    # If you do want eager load only some members of an association it is usually more natural
-    # to include an association which has conditions defined on it:
+    # In this case it is usually more natural to include an association which has conditions defined on it:
     #
     #   class Post < ActiveRecord::Base
     #     has_many :approved_comments, -> { where approved: true }, class_name: 'Comment'
@@ -1048,6 +1052,9 @@ module ActiveRecord
       # Specifies a one-to-many association. The following methods for retrieval and query of
       # collections of associated objects will be added:
       #
+      # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.
+      #
       # [collection(force_reload = false)]
       #   Returns an array of all the associated objects.
       #   An empty array is returned if none are found.
@@ -1106,9 +1113,6 @@ module ActiveRecord
       #   Does the same as <tt>collection.create</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_many :clients</tt> would add among others <tt>clients.empty?</tt>.)
-      #
       # === Example
       #
       # A <tt>Firm</tt> class declares <tt>has_many :clients</tt>, which will add:
@@ -1127,7 +1131,7 @@ module ActiveRecord
       # * <tt>Firm#clients.build</tt> (similar to <tt>Client.new("firm_id" => id)</tt>)
       # * <tt>Firm#clients.create</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save; c</tt>)
       # * <tt>Firm#clients.create!</tt> (similar to <tt>c = Client.new("firm_id" => id); c.save!</tt>)
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # === Options
       # [:class_name]
@@ -1205,7 +1209,7 @@ module ActiveRecord
       # Option examples:
       #   has_many :comments, -> { order "posted_on" }
       #   has_many :comments, -> { includes :author }
-      #   has_many :people, -> { where("deleted = 0").order("name") }, class_name: "Person"
+      #   has_many :people, -> { where(deleted: false).order("name") }, class_name: "Person"
       #   has_many :tracks, -> { order "position" }, dependent: :destroy
       #   has_many :comments, dependent: :nullify
       #   has_many :tags, as: :taggable
@@ -1223,6 +1227,9 @@ module ActiveRecord
       #
       # The following methods for retrieval and query of a single associated object will be added:
       #
+      # +association+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.
+      #
       # [association(force_reload = false)]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
@@ -1241,9 +1248,6 @@ module ActiveRecord
       #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (+association+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_one :manager</tt> would add among others <tt>manager.nil?</tt>.)
-      #
       # === Example
       #
       # An Account class declares <tt>has_one :beneficiary</tt>, which will add:
@@ -1255,7 +1259,7 @@ module ActiveRecord
       #
       # === Options
       #
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
       #
       # Options are:
       # [:class_name]
@@ -1305,6 +1309,10 @@ module ActiveRecord
       #   that is the inverse of this <tt>has_one</tt> association. Does not work in combination
       #   with <tt>:through</tt> or <tt>:as</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
+      # [:required]
+      #   When set to +true+, the association will also have its presence validated.
+      #   This will validate the association itself, not the id. You can use
+      #   +:inverse_of+ to avoid an extra query during validation.
       #
       # Option examples:
       #   has_one :credit_card, dependent: :destroy  # destroys the associated credit card
@@ -1316,6 +1324,7 @@ module ActiveRecord
       #   has_one :boss, readonly: :true
       #   has_one :club, through: :membership
       #   has_one :primary_address, -> { where primary: true }, through: :addressables, source: :addressable
+      #   has_one :credit_card, required: true
       def has_one(name, scope = nil, options = {})
         reflection = Builder::HasOne.build(self, name, scope, options)
         Reflection.add_reflection self, name, reflection
@@ -1329,6 +1338,9 @@ module ActiveRecord
       # Methods will be added for retrieval and query for a single associated object, for which
       # this object holds an id:
       #
+      # +association+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.
+      #
       # [association(force_reload = false)]
       #   Returns the associated object. +nil+ is returned if none is found.
       # [association=(associate)]
@@ -1344,9 +1356,6 @@ module ActiveRecord
       #   Does the same as <tt>create_association</tt>, but raises <tt>ActiveRecord::RecordInvalid</tt>
       #   if the record is invalid.
       #
-      # (+association+ is replaced with the symbol passed as the first argument, so
-      # <tt>belongs_to :author</tt> would add among others <tt>author.nil?</tt>.)
-      #
       # === Example
       #
       # A Post class declares <tt>belongs_to :author</tt>, which will add:
@@ -1355,7 +1364,18 @@ module ActiveRecord
       # * <tt>Post#build_author</tt> (similar to <tt>post.author = Author.new</tt>)
       # * <tt>Post#create_author</tt> (similar to <tt>post.author = Author.new; post.author.save; post.author</tt>)
       # * <tt>Post#create_author!</tt> (similar to <tt>post.author = Author.new; post.author.save!; post.author</tt>)
-      # The declaration can also include an options hash to specialize the behavior of the association.
+      # The declaration can also include an +options+ hash to specialize the behavior of the association.
+      #
+      # === Scopes
+      #
+      # You can pass a second argument +scope+ as a callable (i.e. proc or
+      # lambda) to retrieve a specific record or customize the generated query
+      # when you access the associated object.
+      #
+      # Scope examples:
+      #   belongs_to :user, -> { where(id: 2) }
+      #   belongs_to :user, -> { joins(:friends) }
+      #   belongs_to :level, ->(level) { where("game_level > ?", level.current) }
       #
       # === Options
       #
@@ -1409,7 +1429,7 @@ module ActiveRecord
       #
       #   Note that <tt>accepts_nested_attributes_for</tt> sets <tt>:autosave</tt> to <tt>true</tt>.
       # [:touch]
-      #   If true, the associated object will be touched (the updated_at/on attributes set to now)
+      #   If true, the associated object will be touched (the updated_at/on attributes set to current time)
       #   when this record is either saved or destroyed. If you specify a symbol, that attribute
       #   will be updated with the current time in addition to the updated_at/on attribute.
       # [:inverse_of]
@@ -1417,6 +1437,10 @@ module ActiveRecord
       #   object that is the inverse of this <tt>belongs_to</tt> association. Does not work in
       #   combination with the <tt>:polymorphic</tt> options.
       #   See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail.
+      # [:required]
+      #   When set to +true+, the association will also have its presence validated.
+      #   This will validate the association itself, not the id. You can use
+      #   +:inverse_of+ to avoid an extra query during validation.
       #
       # Option examples:
       #   belongs_to :firm, foreign_key: "client_of"
@@ -1429,6 +1453,7 @@ module ActiveRecord
       #   belongs_to :post, counter_cache: true
       #   belongs_to :company, touch: true
       #   belongs_to :company, touch: :employees_last_updated_at
+      #   belongs_to :company, required: true
       def belongs_to(name, scope = nil, options = {})
         reflection = Builder::BelongsTo.build(self, name, scope, options)
         Reflection.add_reflection self, name, reflection
@@ -1466,6 +1491,9 @@ module ActiveRecord
       #
       # Adds the following methods for retrieval and query:
       #
+      # +collection+ is a placeholder for the symbol passed as the +name+ argument, so
+      # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.
+      #
       # [collection(force_reload = false)]
       #   Returns an array of all the associated objects.
       #   An empty array is returned if none are found.
@@ -1507,9 +1535,6 @@ module ActiveRecord
       #   with +attributes+, linked to this object through the join table, and that has already been
       #   saved (if it passed the validation).
       #
-      # (+collection+ is replaced with the symbol passed as the first argument, so
-      # <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>.)
-      #
       # === Example
       #
       # A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:
@@ -1527,7 +1552,7 @@ module ActiveRecord
       # * <tt>Developer#projects.exists?(...)</tt>
       # * <tt>Developer#projects.build</tt> (similar to <tt>Project.new("developer_id" => id)</tt>)
       # * <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new("developer_id" => id); c.save; c</tt>)
-      # The declaration may include an options hash to specialize the behavior of the association.
+      # The declaration may include an +options+ hash to specialize the behavior of the association.
       #
       # === Options
       #
@@ -1573,7 +1598,7 @@ module ActiveRecord
           scope   = nil
         end
 
-        habtm_reflection = ActiveRecord::Reflection::AssociationReflection.new(:has_and_belongs_to_many, name, scope, options, self)
+        habtm_reflection = ActiveRecord::Reflection::HasAndBelongsToManyReflection.new(name, scope, options, self)
 
         builder = Builder::HasAndBelongsToMany.new name, self, options
 
@@ -1588,7 +1613,7 @@ module ActiveRecord
 
         Builder::HasMany.define_callbacks self, middle_reflection
         Reflection.add_reflection self, middle_reflection.name, middle_reflection
-        middle_reflection.parent_reflection = [name.to_sym, habtm_reflection]
+        middle_reflection.parent_reflection = [name.to_s, habtm_reflection]
 
         include Module.new {
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
@@ -1609,7 +1634,7 @@ module ActiveRecord
         end
 
         has_many name, scope, hm_options, &extension
-        self._reflections[name.to_sym].parent_reflection = [name.to_sym, habtm_reflection]
+        self._reflections[name.to_s].parent_reflection = [name.to_s, habtm_reflection]
       end
     end
   end

data/lib/active_record/attribute.rb

@@ -0,0 +1,131 @@
+module ActiveRecord
+  class Attribute # :nodoc:
+    class << self
+      def from_database(name, value, type)
+        FromDatabase.new(name, value, type)
+      end
+
+      def from_user(name, value, type)
+        FromUser.new(name, value, type)
+      end
+
+      def null(name)
+        Null.new(name)
+      end
+
+      def uninitialized(name, type)
+        Uninitialized.new(name, type)
+      end
+    end
+
+    attr_reader :name, :value_before_type_cast, :type
+
+    # This method should not be called directly.
+    # Use #from_database or #from_user
+    def initialize(name, value_before_type_cast, type)
+      @name = name
+      @value_before_type_cast = value_before_type_cast
+      @type = type
+    end
+
+    def value
+      # `defined?` is cheaper than `||=` when we get back falsy values
+      @value = original_value unless defined?(@value)
+      @value
+    end
+
+    def original_value
+      type_cast(value_before_type_cast)
+    end
+
+    def value_for_database
+      type.type_cast_for_database(value)
+    end
+
+    def changed_from?(old_value)
+      type.changed?(old_value, value, value_before_type_cast)
+    end
+
+    def changed_in_place_from?(old_value)
+      type.changed_in_place?(old_value, value)
+    end
+
+    def with_value_from_user(value)
+      self.class.from_user(name, value, type)
+    end
+
+    def with_value_from_database(value)
+      self.class.from_database(name, value, type)
+    end
+
+    def type_cast(*)
+      raise NotImplementedError
+    end
+
+    def initialized?
+      true
+    end
+
+    def ==(other)
+      self.class == other.class &&
+        name == other.name &&
+        value_before_type_cast == other.value_before_type_cast &&
+        type == other.type
+    end
+
+    protected
+
+    def initialize_dup(other)
+      if defined?(@value) && @value.duplicable?
+        @value = @value.dup
+      end
+    end
+
+    class FromDatabase < Attribute # :nodoc:
+      def type_cast(value)
+        type.type_cast_from_database(value)
+      end
+    end
+
+    class FromUser < Attribute # :nodoc:
+      def type_cast(value)
+        type.type_cast_from_user(value)
+      end
+    end
+
+    class Null < Attribute # :nodoc:
+      def initialize(name)
+        super(name, nil, Type::Value.new)
+      end
+
+      def value
+        nil
+      end
+
+      def with_value_from_database(value)
+        raise ActiveModel::MissingAttributeError, "can't write unknown attribute `#{name}`"
+      end
+      alias_method :with_value_from_user, :with_value_from_database
+    end
+
+    class Uninitialized < Attribute # :nodoc:
+      def initialize(name, type)
+        super(name, nil, type)
+      end
+
+      def value
+        if block_given?
+          yield name
+        end
+      end
+
+      def value_for_database
+      end
+
+      def initialized?
+        false
+      end
+    end
+    private_constant :FromDatabase, :FromUser, :Null, :Uninitialized
+  end
+end

data/lib/active_record/attribute_assignment.rb

@@ -11,6 +11,15 @@ module ActiveRecord
     # If the passed hash responds to <tt>permitted?</tt> method and the return value
     # of this method is +false+ an <tt>ActiveModel::ForbiddenAttributesError</tt>
     # exception is raised.
+    #
+    #   cat = Cat.new(name: "Gorby", status: "yawning")
+    #   cat.attributes # =>  { "name" => "Gorby", "status" => "yawning", "created_at" => nil, "updated_at" => nil}
+    #   cat.assign_attributes(status: "sleeping")
+    #   cat.attributes # =>  { "name" => "Gorby", "status" => "sleeping", "created_at" => nil, "updated_at" => nil }
+    #
+    # New attributes will be persisted in the database when the object is saved.
+    #
+    # Aliased to <tt>attributes=</tt>.
     def assign_attributes(new_attributes)
       if !new_attributes.respond_to?(:stringify_keys)
         raise ArgumentError, "When assigning attributes, you must pass a hash as an argument."
@@ -43,7 +52,7 @@ module ActiveRecord
 
     def _assign_attribute(k, v)
       public_send("#{k}=", v)
-    rescue NoMethodError, NameError
+    rescue NoMethodError
       if respond_to?("#{k}=")
         raise
       else
@@ -106,7 +115,7 @@ module ActiveRecord
     end
 
     class MultiparameterAttribute #:nodoc:
-      attr_reader :object, :name, :values, :column
+      attr_reader :object, :name, :values, :cast_type
 
       def initialize(object, name, values)
         @object = object
@@ -117,22 +126,22 @@ module ActiveRecord
       def read_value
         return if values.values.compact.empty?
 
-        @column = object.class.reflect_on_aggregation(name.to_sym) || object.column_for_attribute(name)
-        klass   = column.klass
+        @cast_type = object.type_for_attribute(name)
+        klass = cast_type.klass
 
         if klass == Time
           read_time
         elsif klass == Date
           read_date
         else
-          read_other(klass)
+          read_other
         end
       end
 
       private
 
       def instantiate_time_object(set_values)
-        if object.class.send(:create_time_zone_conversion_attribute?, name, column)
+        if object.class.send(:create_time_zone_conversion_attribute?, name, cast_type)
           Time.zone.local(*set_values)
         else
           Time.send(object.class.default_timezone, *set_values)
@@ -140,9 +149,9 @@ module ActiveRecord
       end
 
       def read_time
-        # If column is a :time (and not :date or :timestamp) there is no need to validate if
+        # If column is a :time (and not :date or :datetime) there is no need to validate if
         # there are year/month/day fields
-        if column.type == :time
+        if cast_type.type == :time
           # if the column is a time set the values to their defaults as January 1, 1970, but only if they're nil
           { 1 => 1970, 2 => 1, 3 => 1 }.each do |key,value|
             values[key] ||= value
@@ -172,13 +181,12 @@ module ActiveRecord
         end
       end
 
-      def read_other(klass)
+      def read_other
         max_position = extract_max_param
         positions    = (1..max_position)
         validate_required_parameters!(positions)
 
-        set_values = values.values_at(*positions)
-        klass.new(*set_values)
+        values.slice(*positions)
       end
 
       # Checks whether some blank date parameter exists. Note that this is different

data/lib/active_record/attribute_decorators.rb

@@ -0,0 +1,66 @@
+module ActiveRecord
+  module AttributeDecorators # :nodoc:
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :attribute_type_decorations, instance_accessor: false # :internal:
+      self.attribute_type_decorations = TypeDecorator.new
+    end
+
+    module ClassMethods # :nodoc:
+      def decorate_attribute_type(column_name, decorator_name, &block)
+        matcher = ->(name, _) { name == column_name.to_s }
+        key = "_#{column_name}_#{decorator_name}"
+        decorate_matching_attribute_types(matcher, key, &block)
+      end
+
+      def decorate_matching_attribute_types(matcher, decorator_name, &block)
+        clear_caches_calculated_from_columns
+        decorator_name = decorator_name.to_s
+
+        # Create new hashes so we don't modify parent classes
+        self.attribute_type_decorations = attribute_type_decorations.merge(decorator_name => [matcher, block])
+      end
+
+      private
+
+      def add_user_provided_columns(*)
+        super.map do |column|
+          decorated_type = attribute_type_decorations.apply(column.name, column.cast_type)
+          column.with_type(decorated_type)
+        end
+      end
+    end
+
+    class TypeDecorator # :nodoc:
+      delegate :clear, to: :@decorations
+
+      def initialize(decorations = {})
+        @decorations = decorations
+      end
+
+      def merge(*args)
+        TypeDecorator.new(@decorations.merge(*args))
+      end
+
+      def apply(name, type)
+        decorations = decorators_for(name, type)
+        decorations.inject(type) do |new_type, block|
+          block.call(new_type)
+        end
+      end
+
+      private
+
+      def decorators_for(name, type)
+        matching(name, type).map(&:last)
+      end
+
+      def matching(name, type)
+        @decorations.values.select do |(matcher, _)|
+          matcher.call(name, type)
+        end
+      end
+    end
+  end
+end

data/lib/active_record/attribute_methods/before_type_cast.rb

@@ -43,7 +43,7 @@ module ActiveRecord
       #   task.read_attribute_before_type_cast('completed_on') # => "2012-10-21"
       #   task.read_attribute_before_type_cast(:completed_on)  # => "2012-10-21"
       def read_attribute_before_type_cast(attr_name)
-        @attributes[attr_name.to_s]
+        @attributes[attr_name.to_s].value_before_type_cast
       end
 
       # Returns a hash of attributes before typecasting and deserialization.
@@ -57,7 +57,7 @@ module ActiveRecord
       #   task.attributes_before_type_cast
       #   # => {"id"=>nil, "title"=>nil, "is_done"=>true, "completed_on"=>"2012-10-21", "created_at"=>nil, "updated_at"=>nil}
       def attributes_before_type_cast
-        @attributes
+        @attributes.values_before_type_cast
       end
 
       private