paper_trail 4.2.0 → 5.0.0

data/lib/paper_trail/serializers/json.rb

@@ -1,7 +1,8 @@
-require 'active_support/json'
+require "active_support/json"
 
 module PaperTrail
   module Serializers
+    # An alternate serializer for, e.g. `versions.object`.
     module JSON
       extend self # makes all instance methods become module methods as well
 
@@ -25,8 +26,7 @@ module PaperTrail
         # 123.
         if value.is_a? Numeric
           arel_field.matches("%\"#{field}\":#{json_value},%").
-            or(
-          arel_field.matches("%\"#{field}\":#{json_value}}%"))
+            or(arel_field.matches("%\"#{field}\":#{json_value}}%"))
         else
           arel_field.matches("%\"#{field}\":#{json_value}%")
         end

data/lib/paper_trail/serializers/yaml.rb

@@ -1,7 +1,8 @@
-require 'yaml'
+require "yaml"
 
 module PaperTrail
   module Serializers
+    # The default serializer for, e.g. `versions.object`.
     module YAML
       extend self # makes all instance methods become module methods as well
 
@@ -23,13 +24,31 @@ module PaperTrail
       # in the serialized object_changes
       def where_object_changes_condition(arel_field, field, value)
         # Need to check first (before) and secondary (after) fields
-        if (defined?(::YAML::ENGINE) && ::YAML::ENGINE.yamler == 'psych') ||
-          (defined?(::Psych) && ::YAML == ::Psych)
-          arel_field.matches("%\n#{field}:\n- #{value}\n%").
-            or(arel_field.matches("%\n#{field}:\n-%\n- #{value}\n%"))
-        else # Syck adds extra spaces into array dumps
-          arel_field.matches("%\n#{field}: \n%- #{value}\n%").
-            or(arel_field.matches("%\n#{field}: \n-%\n- #{value}\n%"))
+        m1 = nil
+        m2 = nil
+        case yaml_engine_id
+        when :psych
+          m1 = "%\n#{field}:\n- #{value}\n%"
+          m2 = "%\n#{field}:\n-%\n- #{value}\n%"
+        when :syck
+          # Syck adds extra spaces into array dumps
+          m1 = "%\n#{field}: \n%- #{value}\n%"
+          m2 = "%\n#{field}: \n-%\n- #{value}\n%"
+        else
+          raise "Unknown yaml engine"
+        end
+        arel_field.matches(m1).or(arel_field.matches(m2))
+      end
+
+      # Returns a symbol identifying the YAML engine. Syck was removed from
+      # the ruby stdlib in ruby 2.0, but is still available as a gem.
+      # @api private
+      def yaml_engine_id
+        if (defined?(::YAML::ENGINE) && ::YAML::ENGINE.yamler == "psych") ||
+            (defined?(::Psych) && ::YAML == ::Psych)
+          :psych
+        else
+          :syck
         end
       end
     end

data/lib/paper_trail/version_association_concern.rb

@@ -1,6 +1,8 @@
-require 'active_support/concern'
+require "active_support/concern"
 
 module PaperTrail
+  # Functionality for `PaperTrail::VersionAssociation`. Exists in a module
+  # for the same reasons outlined in version_concern.rb.
   module VersionAssociationConcern
     extend ::ActiveSupport::Concern
 

data/lib/paper_trail/version_concern.rb

@@ -1,18 +1,22 @@
-require 'active_support/concern'
+require "active_support/concern"
 
 module PaperTrail
+  # Originally, PaperTrail did not provide this module, and all of this
+  # functionality was in `PaperTrail::Version`. That model still exists (and is
+  # used by most apps) but by moving the functionality to this module, people
+  # can include this concern instead of sub-classing the `Version` model.
   module VersionConcern
     extend ::ActiveSupport::Concern
 
     included do
-      belongs_to :item, :polymorphic => true
+      belongs_to :item, polymorphic: true
 
       # Since the test suite has test coverage for this, we want to declare
       # the association when the test suite is running. This makes it pass when
       # DB is not initialized prior to test runs such as when we run on Travis
       # CI (there won't be a db in `test/dummy/db/`).
       if PaperTrail.config.track_associations?
-        has_many :version_associations, :dependent => :destroy
+        has_many :version_associations, dependent: :destroy
       end
 
       validates_presence_of :event
@@ -32,28 +36,29 @@ module PaperTrail
 
       after_create :enforce_version_limit!
 
-      scope :within_transaction, lambda { |id| where :transaction_id => id }
+      scope :within_transaction, ->(id) { where transaction_id: id }
     end
 
+    # :nodoc:
     module ClassMethods
       def with_item_keys(item_type, item_id)
-        where :item_type => item_type, :item_id => item_id
+        where item_type: item_type, item_id: item_id
       end
 
       def creates
-        where :event => 'create'
+        where event: "create"
       end
 
       def updates
-        where :event => 'update'
+        where event: "update"
       end
 
       def destroys
-        where :event => 'destroy'
+        where event: "destroy"
       end
 
       def not_creates
-        where 'event <> ?', 'create'
+        where "event <> ?", "create"
       end
 
       # Returns versions after `obj`.
@@ -64,12 +69,12 @@ module PaperTrail
       # @return `ActiveRecord::Relation`
       # @api public
       def subsequent(obj, timestamp_arg = false)
-        if timestamp_arg != true && self.primary_key_is_int?
+        if timestamp_arg != true && primary_key_is_int?
           return where(arel_table[primary_key].gt(obj.id)).order(arel_table[primary_key].asc)
         end
 
         obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where(arel_table[PaperTrail.timestamp_field].gt(obj)).order(self.timestamp_sort_order)
+        where(arel_table[PaperTrail.timestamp_field].gt(obj)).order(timestamp_sort_order)
       end
 
       # Returns versions before `obj`.
@@ -80,37 +85,38 @@ module PaperTrail
       # @return `ActiveRecord::Relation`
       # @api public
       def preceding(obj, timestamp_arg = false)
-        if timestamp_arg != true && self.primary_key_is_int?
+        if timestamp_arg != true && primary_key_is_int?
           return where(arel_table[primary_key].lt(obj.id)).order(arel_table[primary_key].desc)
         end
 
         obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where(arel_table[PaperTrail.timestamp_field].lt(obj)).order(self.timestamp_sort_order('desc'))
+        where(arel_table[PaperTrail.timestamp_field].lt(obj)).
+          order(timestamp_sort_order("desc"))
       end
 
       def between(start_time, end_time)
         where(
           arel_table[PaperTrail.timestamp_field].gt(start_time).
           and(arel_table[PaperTrail.timestamp_field].lt(end_time))
-        ).order(self.timestamp_sort_order)
+        ).order(timestamp_sort_order)
       end
 
       # Defaults to using the primary key as the secondary sort order if
       # possible.
-      def timestamp_sort_order(direction = 'asc')
+      def timestamp_sort_order(direction = "asc")
         [arel_table[PaperTrail.timestamp_field].send(direction.downcase)].tap do |array|
-          array << arel_table[primary_key].send(direction.downcase) if self.primary_key_is_int?
+          array << arel_table[primary_key].send(direction.downcase) if primary_key_is_int?
         end
       end
 
       # Performs an attribute search on the serialized object by invoking the
       # identically-named method in the serializer being used.
       def where_object(args = {})
-        raise ArgumentError, 'expected to receive a Hash' unless args.is_a?(Hash)
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
 
-        if columns_hash['object'].type == :jsonb
+        if columns_hash["object"].type == :jsonb
           where("object @> ?", args.to_json)
-        elsif columns_hash['object'].type == :json
+        elsif columns_hash["object"].type == :json
           predicates = []
           values = []
           args.each do |field, value|
@@ -123,18 +129,19 @@ module PaperTrail
           arel_field = arel_table[:object]
           where_conditions = args.map { |field, value|
             PaperTrail.serializer.where_object_condition(arel_field, field, value)
-          }.reduce { |a, e| a.and(e) }
+          }
+          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
           where(where_conditions)
         end
       end
 
       def where_object_changes(args = {})
-        raise ArgumentError, 'expected to receive a Hash' unless args.is_a?(Hash)
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
 
-        if columns_hash['object_changes'].type == :jsonb
+        if columns_hash["object_changes"].type == :jsonb
           args.each { |field, value| args[field] = [value] }
           where("object_changes @> ?", args.to_json)
-        elsif columns_hash['object'].type == :json
+        elsif columns_hash["object"].type == :json
           predicates = []
           values = []
           args.each do |field, value|
@@ -149,7 +156,8 @@ module PaperTrail
           arel_field = arel_table[:object_changes]
           where_conditions = args.map { |field, value|
             PaperTrail.serializer.where_object_changes_condition(arel_field, field, value)
-          }.reduce { |a, e| a.and(e) }
+          }
+          where_conditions = where_conditions.reduce { |a, e| a.and(e) }
           where(where_conditions)
         end
       end
@@ -163,13 +171,22 @@ module PaperTrail
       # Returns whether the `object` column is using the `json` type supported
       # by PostgreSQL.
       def object_col_is_json?
-        [:json, :jsonb].include?(columns_hash['object'].type)
+        [:json, :jsonb].include?(columns_hash["object"].type)
       end
 
       # Returns whether the `object_changes` column is using the `json` type
       # supported by PostgreSQL.
       def object_changes_col_is_json?
-        [:json, :jsonb].include?(columns_hash['object_changes'].try(:type))
+        [:json, :jsonb].include?(columns_hash["object_changes"].try(:type))
+      end
+    end
+
+    # @api private
+    def object_deserialized
+      if self.class.object_col_is_json?
+        object
+      else
+        PaperTrail.serializer.load(object)
       end
     end
 
@@ -211,18 +228,18 @@ module PaperTrail
     # `ActiveModel::Dirty#changes`. returns `nil` if your `versions` table does
     # not have an `object_changes` text column.
     def changeset
-      return nil unless self.class.column_names.include? 'object_changes'
+      return nil unless self.class.column_names.include? "object_changes"
       @changeset ||= load_changeset
     end
 
     # Returns who put the item into the state stored in this version.
     def paper_trail_originator
-      @paper_trail_originator ||= previous.whodunnit rescue nil
+      @paper_trail_originator ||= previous.try(:whodunnit)
     end
 
     def originator
       ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
-      self.paper_trail_originator
+      paper_trail_originator
     end
 
     # Returns who changed the item from the state it had in this version. This
@@ -230,7 +247,7 @@ module PaperTrail
     def terminator
       @terminator ||= whodunnit
     end
-    alias_method :version_author, :terminator
+    alias version_author terminator
 
     def sibling_versions(reload = false)
       if reload || @sibling_versions.nil?
@@ -259,19 +276,42 @@ module PaperTrail
 
     # @api private
     def load_changeset
+      # First, deserialize the `object_changes` column.
       changes = HashWithIndifferentAccess.new(object_changes_deserialized)
-      item_type.constantize.unserialize_attribute_changes_for_paper_trail!(changes)
+
+      # The next step is, perhaps unfortunately, called "un-serialization",
+      # and appears to be responsible for custom attribute serializers. For an
+      # example of a custom attribute serializer, see
+      # `Person::TimeZoneSerializer` in the test suite.
+      #
+      # Is `item.class` good enough? Does it handle `inheritance_column`
+      # as well as `Reifier#version_reification_class`? We were using
+      # `item_type.constantize`, but that is problematic when the STI parent
+      # is not versioned. (See `Vehicle` and `Car` in the test suite).
+      #
+      # Note: `item` returns nil if `event` is "destroy".
+      unless item.nil?
+        item.class.unserialize_attribute_changes_for_paper_trail!(changes)
+      end
+
+      # Finally, return a Hash mapping each attribute name to
+      # a two-element array representing before and after.
       changes
-    rescue # TODO: Rescue something specific
-      {}
     end
 
+    # If the `object_changes` column is a Postgres JSON column, then
+    # ActiveRecord will deserialize it for us. Otherwise, it's a string column
+    # and we must deserialize it ourselves.
     # @api private
     def object_changes_deserialized
       if self.class.object_changes_col_is_json?
         object_changes
       else
-        PaperTrail.serializer.load(object_changes)
+        begin
+          PaperTrail.serializer.load(object_changes)
+        rescue # TODO: Rescue something specific
+          {}
+        end
       end
     end
 
@@ -282,7 +322,7 @@ module PaperTrail
       if defined?(::ActiveRecord::IdentityMap) && ::ActiveRecord::IdentityMap.respond_to?(:without)
         ::ActiveRecord::IdentityMap.without(&block)
       else
-        block.call
+        yield
       end
     end
 

data/lib/paper_trail/version_number.rb

@@ -1,18 +1,15 @@
 module PaperTrail
+  # :nodoc:
   module VERSION
-    MAJOR = 4
-    MINOR = 2
-    TINY  = 0
-    PRE   = nil
+    MAJOR = 5
+    MINOR = 0
+    TINY = 0
+    PRE = nil
 
-    STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
+    STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".").freeze
 
     def self.to_s
       STRING
     end
   end
-
-  def self.version
-    VERSION::STRING
-  end
 end

data/paper_trail.gemspec

@@ -1,59 +1,52 @@
-$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
-require 'paper_trail/version_number'
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require "paper_trail/version_number"
 
 Gem::Specification.new do |s|
-  s.name          = 'paper_trail'
-  s.version       = PaperTrail.version
-  s.platform      = Gem::Platform::RUBY
-  s.summary       = "Track changes to your models' data. Good for auditing or versioning."
-  s.description   = s.summary
-  s.homepage      = 'https://github.com/airblade/paper_trail'
-  s.authors       = ['Andy Stewart', 'Ben Atkins']
-  s.email         = 'batkinz@gmail.com'
-  s.license       = 'MIT'
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ['lib']
-
-  s.required_rubygems_version = '>= 1.3.6'
-
-  s.add_dependency 'activerecord', ['>= 3.0', '< 6.0']
-  s.add_dependency 'activesupport', ['>= 3.0', '< 6.0']
-  s.add_dependency 'request_store', '~> 1.1'
-
-  s.add_development_dependency 'rake', '~> 10.1.1'
-  s.add_development_dependency 'shoulda', '~> 3.5'
-  # s.add_development_dependency 'shoulda-matchers', '~> 1.5' # needed for ActiveRecord < 4
-  s.add_development_dependency 'ffaker', '<= 1.31.0'
-  s.add_development_dependency 'railties', ['>= 3.0', '< 5.0']
-  s.add_development_dependency 'sinatra', '~> 1.0'
-  s.add_development_dependency 'rack-test', '>= 0.6'
-  s.add_development_dependency 'rspec-rails', '~> 3.1.0'
-  s.add_development_dependency 'generator_spec'
-  s.add_development_dependency 'database_cleaner', '~> 1.2'
-  s.add_development_dependency 'pry-nav'
-
-  # Allow time travel in testing. timecop is only supported after 1.9.2 but does a better cleanup at 'return'
-  if RUBY_VERSION < "1.9.2"
-    s.add_development_dependency 'delorean'
-  else
-    s.add_development_dependency 'timecop'
-  end
+  s.name = "paper_trail"
+  s.version = PaperTrail::VERSION::STRING
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Track changes to your models' data. Good for auditing or versioning."
+  s.description = s.summary
+  s.homepage = "https://github.com/airblade/paper_trail"
+  s.authors = ["Andy Stewart", "Ben Atkins"]
+  s.email = "batkinz@gmail.com"
+  s.license = "MIT"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.required_ruby_version = ">= 1.9.3"
+
+  s.add_dependency "activerecord", [">= 3.0", "< 6.0"]
+  s.add_dependency "activesupport", [">= 3.0", "< 6.0"]
+  s.add_dependency "request_store", "~> 1.1"
+
+  s.add_development_dependency "appraisal", "~> 2.1"
+  s.add_development_dependency "rake", "~> 10.4.2"
+  s.add_development_dependency "shoulda", "~> 3.5.0"
+  s.add_development_dependency "ffaker", "~> 2.1.0"
+  s.add_development_dependency "railties", [">= 3.0", "< 6.0"]
+  s.add_development_dependency "sinatra", "~> 1.4.6"
+  s.add_development_dependency "rack-test", "~> 0.6.3"
+  s.add_development_dependency "rspec-rails", "~> 3.4.0"
+  s.add_development_dependency "generator_spec", "~> 0.9.3"
+  s.add_development_dependency "database_cleaner", "~> 1.2"
+  s.add_development_dependency "pry-nav", "~> 0.2.4"
+  s.add_development_dependency "rubocop", "~> 0.37.2"
+  s.add_development_dependency "timecop", "~> 0.8.0"
 
   if defined?(JRUBY_VERSION)
-    s.add_development_dependency 'activerecord-jdbcsqlite3-adapter', '~> 1.3'
-    s.add_development_dependency 'activerecord-jdbcpostgresql-adapter', '~> 1.3'
-    s.add_development_dependency 'activerecord-jdbcmysql-adapter', '~> 1.3'
+    s.add_development_dependency "activerecord-jdbcsqlite3-adapter", "~> 1.3.15"
+    s.add_development_dependency "activerecord-jdbcpostgresql-adapter", "~> 1.3.15"
+    s.add_development_dependency "activerecord-jdbcmysql-adapter", "~> 1.3.15"
   else
-    s.add_development_dependency 'sqlite3', '~> 1.2'
-
-    # We would prefer to only constrain mysql2 to '~> 0.3',
-    # but a rails bug (https://github.com/rails/rails/issues/21544)
-    # requires us to constrain to '~> 0.3.20' for now.
-    s.add_development_dependency 'mysql2', '~> 0.3.20'
+    s.add_development_dependency "sqlite3", "~> 1.2"
+    s.add_development_dependency "pg", "~> 0.17"
 
-    s.add_development_dependency 'pg', '~> 0.17'
+    # activerecord >= 4.2.5 may use mysql2 >= 0.4
+    s.add_development_dependency "mysql2", "~> 0.4.2"
   end
 end