vendor/rails/activerecord/lib/active_record/dirty.rb

   1 module ActiveRecord
   2   # Track unsaved attribute changes.
   3   #
   4   # A newly instantiated object is unchanged:
   5   #   person = Person.find_by_name('uncle bob')
   6   #   person.changed?       # => false
   7   #
   8   # Change the name:
   9   #   person.name = 'Bob'
  10   #   person.changed?       # => true
  11   #   person.name_changed?  # => true
  12   #   person.name_was       # => 'uncle bob'
  13   #   person.name_change    # => ['uncle bob', 'Bob']
  14   #   person.name = 'Bill'
  15   #   person.name_change    # => ['uncle bob', 'Bill']
  16   #
  17   # Save the changes:
  18   #   person.save
  19   #   person.changed?       # => false
  20   #   person.name_changed?  # => false
  21   #
  22   # Assigning the same value leaves the attribute unchanged:
  23   #   person.name = 'Bill'
  24   #   person.name_changed?  # => false
  25   #   person.name_change    # => nil
  26   #
  27   # Which attributes have changed?
  28   #   person.name = 'bob'
  29   #   person.changed        # => ['name']
  30   #   person.changes        # => { 'name' => ['Bill', 'bob'] }
  31   #
  32   # Before modifying an attribute in-place:
  33   #   person.name_will_change!
  34   #   person.name << 'by'
  35   #   person.name_change    # => ['uncle bob', 'uncle bobby']
  36   module Dirty
  37     DIRTY_SUFFIXES = ['_changed?', '_change', '_will_change!', '_was']
  38
  39     def self.included(base)
  40       base.attribute_method_suffix *DIRTY_SUFFIXES
  41       base.alias_method_chain :write_attribute, :dirty
  42       base.alias_method_chain :save,            :dirty
  43       base.alias_method_chain :save!,           :dirty
  44       base.alias_method_chain :update,          :dirty
  45       base.alias_method_chain :reload,          :dirty
  46
  47       base.superclass_delegating_accessor :partial_updates
  48       base.partial_updates = true
  49
  50       base.send(:extend, ClassMethods)
  51     end
  52
  53     # Do any attributes have unsaved changes?
  54     #   person.changed? # => false
  55     #   person.name = 'bob'
  56     #   person.changed? # => true
  57     def changed?
  58       !changed_attributes.empty?
  59     end
  60
  61     # List of attributes with unsaved changes.
  62     #   person.changed # => []
  63     #   person.name = 'bob'
  64     #   person.changed # => ['name']
  65     def changed
  66       changed_attributes.keys
  67     end
  68
  69     # Map of changed attrs => [original value, new value].
  70     #   person.changes # => {}
  71     #   person.name = 'bob'
  72     #   person.changes # => { 'name' => ['bill', 'bob'] }
  73     def changes
  74       changed.inject({}) { |h, attr| h[attr] = attribute_change(attr); h }
  75     end
  76
  77     # Attempts to +save+ the record and clears changed attributes if successful.
  78     def save_with_dirty(*args) #:nodoc:
  79       if status = save_without_dirty(*args)
  80         changed_attributes.clear
  81       end
  82       status
  83     end
  84
  85     # Attempts to <tt>save!</tt> the record and clears changed attributes if successful.
  86     def save_with_dirty!(*args) #:nodoc:
  87       status = save_without_dirty!(*args)
  88       changed_attributes.clear
  89       status
  90     end
  91
  92     # <tt>reload</tt> the record and clears changed attributes.
  93     def reload_with_dirty(*args) #:nodoc:
  94       record = reload_without_dirty(*args)
  95       changed_attributes.clear
  96       record
  97     end
  98
  99     private
 100       # Map of change <tt>attr => original value</tt>.
 101       def changed_attributes
 102         @changed_attributes ||= {}
 103       end
 104
 105       # Handle <tt>*_changed?</tt> for +method_missing+.
 106       def attribute_changed?(attr)
 107         changed_attributes.include?(attr)
 108       end
 109
 110       # Handle <tt>*_change</tt> for +method_missing+.
 111       def attribute_change(attr)
 112         [changed_attributes[attr], __send__(attr)] if attribute_changed?(attr)
 113       end
 114
 115       # Handle <tt>*_was</tt> for +method_missing+.
 116       def attribute_was(attr)
 117         attribute_changed?(attr) ? changed_attributes[attr] : __send__(attr)
 118       end
 119
 120       # Handle <tt>*_will_change!</tt> for +method_missing+.
 121       def attribute_will_change!(attr)
 122         changed_attributes[attr] = clone_attribute_value(:read_attribute, attr)
 123       end
 124
 125       # Wrap write_attribute to remember original attribute value.
 126       def write_attribute_with_dirty(attr, value)
 127         attr = attr.to_s
 128
 129         # The attribute already has an unsaved change.
 130         if changed_attributes.include?(attr)
 131           old = changed_attributes[attr]
 132           changed_attributes.delete(attr) unless field_changed?(attr, old, value)
 133         else
 134           old = clone_attribute_value(:read_attribute, attr)
 135           changed_attributes[attr] = old if field_changed?(attr, old, value)
 136         end
 137
 138         # Carry on.
 139         write_attribute_without_dirty(attr, value)
 140       end
 141
 142       def update_with_dirty
 143         if partial_updates?
 144           # Serialized attributes should always be written in case they've been
 145           # changed in place.
 146           update_without_dirty(changed | self.class.serialized_attributes.keys)
 147         else
 148           update_without_dirty
 149         end
 150       end
 151
 152       def field_changed?(attr, old, value)
 153         if column = column_for_attribute(attr)
 154           if column.type == :integer && column.null && (old.nil? || old == 0)
 155             # For nullable integer columns, NULL gets stored in database for blank (i.e. '') values.
 156             # Hence we don't record it as a change if the value changes from nil to ''.
 157             # If an old value of 0 is set to '' we want this to get changed to nil as otherwise it'll
 158             # be typecast back to 0 (''.to_i => 0)
 159             value = nil if value.blank?
 160           else
 161             value = column.type_cast(value)
 162           end
 163         end
 164
 165         old != value
 166       end
 167
 168     module ClassMethods
 169       def self.extended(base)
 170         base.metaclass.alias_method_chain(:alias_attribute, :dirty)
 171       end
 172
 173       def alias_attribute_with_dirty(new_name, old_name)
 174         alias_attribute_without_dirty(new_name, old_name)
 175         DIRTY_SUFFIXES.each do |suffix|
 176           module_eval <<-STR, __FILE__, __LINE__+1
 177             def #{new_name}#{suffix}; self.#{old_name}#{suffix}; end
 178           STR
 179         end
 180       end
 181     end
 182   end
 183 end