bitfluent-vestal_versions 1.1.0

data/lib/vestal_versions/reset.rb

@@ -0,0 +1,28 @@
+module VestalVersions
+  # Adds the ability to "reset" (or hard revert) a versioned ActiveRecord::Base instance.
+  module Reset
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Adds the instance methods required to reset an object to a previous version.
+    module InstanceMethods
+      # Similar to +revert_to!+, the +reset_to!+ method reverts an object to a previous version,
+      # only instead of creating a new record in the version history, +reset_to!+ deletes all of
+      # the version history that occurs after the version reverted to.
+      #
+      # The action taken on each version record after the point of reversion is determined by the
+      # <tt>:dependent</tt> option given to the +versioned+ method. See the +versioned+ method
+      # documentation for more details.
+      def reset_to!(value)
+        if saved = skip_version{ revert_to!(value) }
+          versions.send(:delete_records, versions.after(value))
+          reset_version
+        end
+        saved
+      end
+    end
+  end
+end

data/lib/vestal_versions/reversion.rb

@@ -0,0 +1,69 @@
+module VestalVersions
+  # Enables versioned ActiveRecord::Base instances to revert to a previously saved version.
+  module Reversion
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Provides the base instance methods required to revert a versioned instance.
+    module InstanceMethods
+      # Returns the current version number for the versioned object.
+      def version
+        @version ||= last_version
+      end
+
+      # Accepts a value corresponding to a specific version record, builds a history of changes
+      # between that version and the current version, and then iterates over that history updating
+      # the object's attributes until the it's reverted to its prior state.
+      #
+      # The single argument should adhere to one of the formats as documented in the +at+ method of
+      # VestalVersions::Versions.
+      #
+      # After the object is reverted to the target version, it is not saved. In order to save the
+      # object after the reversion, use the +revert_to!+ method.
+      #
+      # The version number of the object will reflect whatever version has been reverted to, and
+      # the return value of the +revert_to+ method is also the target version number.
+      def revert_to(value)
+        to_number = versions.number_at(value)
+
+        changes_between(version, to_number).each do |attribute, change|
+          write_attribute(attribute, change.last)
+        end
+
+        reset_version(to_number)
+      end
+
+      # Behaves similarly to the +revert_to+ method except that it automatically saves the record
+      # after the reversion. The return value is the success of the save.
+      def revert_to!(value)
+        revert_to(value)
+        reset_version if saved = save
+        saved
+      end
+
+      # Returns a boolean specifying whether the object has been reverted to a previous version or
+      # if the object represents the latest version in the version history.
+      def reverted?
+        version != last_version
+      end
+
+      private
+        # Returns the number of the last created version in the object's version history.
+        #
+        # If no associated versions exist, the object is considered at version 1.
+        def last_version
+          @last_version ||= versions.maximum(:number) || 1
+        end
+
+        # Clears the cached version number instance variables so that they can be recalculated.
+        # Useful after a new version is created.
+        def reset_version(version = nil)
+          @last_version = nil if version.nil?
+          @version = version
+        end
+    end
+  end
+end

data/lib/vestal_versions/tagging.rb

@@ -0,0 +1,50 @@
+module VestalVersions
+  # Allows specific versions to be tagged with a custom string. Useful for assigning a more
+  # meaningful value to a version for the purpose of reversion.
+  module Tagging
+    def self.included(base) # :nodoc:
+      Version.send(:include, VersionMethods)
+
+      base.class_eval do
+        include InstanceMethods
+      end
+    end
+
+    # Adds an instance method which allows version tagging through the parent object.
+    module InstanceMethods
+      # Accepts a single string argument which is attached to the version record associated with
+      # the current version number of the parent object.
+      #
+      # Returns the given tag if successful, nil if not. Tags must be unique within the scope of
+      # the parent object. Tag creation will fail if non-unique.
+      #
+      # Version records corresponding to version number 1 are not typically created, but one will
+      # be built to house the given tag if the parent object's current version number is 1.
+      def tag_version(tag)
+        v = versions.at(version) || versions.build(:number => 1)
+        v.tag!(tag)
+      end
+    end
+
+    # Instance methods included into VestalVersions::Version to enable version tagging.
+    module VersionMethods
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          validates_uniqueness_of :tag, :scope => [:versioned_id, :versioned_type], :if => :tagged?
+        end
+      end
+
+      # Attaches the given string to the version tag column. If the uniqueness validation fails,
+      # nil is returned. Otherwise, the given string is returned.
+      def tag!(tag)
+        write_attribute(:tag, tag)
+        save ? tag : nil
+      end
+
+      # Simply returns a boolean signifying whether the version instance has a tag value attached.
+      def tagged?
+        !tag.nil?
+      end
+    end
+  end
+end

data/lib/vestal_versions/users.rb

@@ -0,0 +1,57 @@
+module VestalVersions
+  # Provides a way for information to be associated with specific versions as to who was
+  # responsible for the associated update to the parent.
+  module Users
+    def self.included(base) # :nodoc:
+      Version.send(:include, VersionMethods)
+
+      base.class_eval do
+        include InstanceMethods
+
+        attr_accessor :updated_by
+        alias_method_chain :version_attributes, :user
+      end
+    end
+
+    # Methods added to versioned ActiveRecord::Base instances to enable versioning with additional
+    # user information.
+    module InstanceMethods
+      private
+        # Overrides the +version_attributes+ method to include user information passed into the
+        # parent object, by way of a +updated_by+ attr_accessor.
+        def version_attributes_with_user
+          version_attributes_without_user.merge(:user => updated_by)
+        end
+    end
+
+    # Instance methods added to VestalVersions::Version to accomodate incoming user information.
+    module VersionMethods
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          belongs_to :user, :polymorphic => true
+
+          alias_method_chain :user, :name
+          alias_method_chain :user=, :name
+        end
+      end
+
+      # Overrides the +user+ method created by the polymorphic +belongs_to+ user association. If
+      # the association is absent, defaults to the +user_name+ string column. This allows
+      # VestalVersions::Version#user to either return an ActiveRecord::Base object or a string,
+      # depending on what is sent to the +user_with_name=+ method.
+      def user_with_name
+        user_without_name || user_name
+      end
+
+      # Overrides the +user=+ method created by the polymorphic +belongs_to+ user association.
+      # Based on the class of the object given, either the +user+ association columns or the
+      # +user_name+ string column is populated.
+      def user_with_name=(value)
+        case value
+          when ActiveRecord::Base then self.user_without_name = value
+          else self.user_name = value
+        end
+      end
+    end
+  end
+end

data/lib/vestal_versions/version.rb

@@ -0,0 +1,32 @@
+module VestalVersions
+  # The ActiveRecord model representing versions.
+  class Version < ActiveRecord::Base
+    include Comparable
+
+    # Associate polymorphically with the parent record.
+    belongs_to :versioned, :polymorphic => true
+
+    # ActiveRecord::Base#changes is an existing method, so before serializing the +changes+ column,
+    # the existing +changes+ method is undefined. The overridden +changes+ method pertained to 
+    # dirty attributes, but will not affect the partial updates functionality as that's based on
+    # an underlying +changed_attributes+ method, not +changes+ itself.
+    undef_method :changes
+    def changes
+      self[:modifications]
+    end
+    serialize :modifications, Hash
+
+    # In conjunction with the included Comparable module, allows comparison of version records
+    # based on their corresponding version numbers, creation timestamps and IDs.
+    def <=>(other)
+      [number, created_at, id].map(&:to_i) <=> [other.number, other.created_at, other.id].map(&:to_i)
+    end
+
+    # Returns whether the version has a version number of 1. Useful when deciding whether to ignore
+    # the version during reversion, as initial versions have no serialized changes attached. Helps
+    # maintain backwards compatibility.
+    def initial?
+      number == 1
+    end
+  end
+end

data/lib/vestal_versions/versioned.rb

@@ -0,0 +1,30 @@
+module VestalVersions
+  # Simply adds a flag to determine whether a model class if versioned.
+  module Versioned
+    def self.extended(base) # :nodoc:
+      base.class_eval do
+        class << self
+          alias_method_chain :versioned, :flag
+        end
+      end
+    end
+
+    # Overrides the +versioned+ method to first define the +versioned?+ class method before
+    # deferring to the original +versioned+.
+    def versioned_with_flag(*args)
+      versioned_without_flag(*args)
+
+      class << self
+        def versioned?
+          true
+        end
+      end
+    end
+
+    # For all ActiveRecord::Base models that do not call the +versioned+ method, the +versioned?+
+    # method will return false.
+    def versioned?
+      false
+    end
+  end
+end

data/lib/vestal_versions/versions.rb

@@ -0,0 +1,74 @@
+module VestalVersions
+  # An extension module for the +has_many+ association with versions.
+  module Versions
+    # Returns all versions between (and including) the two given arguments. See documentation for
+    # the +at+ extension method for what arguments are valid. If either of the given arguments is
+    # invalid, an empty array is returned.
+    #
+    # The +between+ method preserves returns an array of version records, preserving the order
+    # given by the arguments. If the +from+ value represents a version before that of the +to+
+    # value, the array will be ordered from earliest to latest. The reverse is also true.
+    def between(from, to)
+      from_number, to_number = number_at(from), number_at(to)
+      return [] if from_number.nil? || to_number.nil?
+
+      condition = (from_number == to_number) ? to_number : Range.new(*[from_number, to_number].sort)
+      all(
+        :conditions => {:number => condition},
+        :order => "#{aliased_table_name}.number #{(from_number > to_number) ? 'DESC' : 'ASC'}"
+      )
+    end
+
+    # Returns all version records created before the version associated with the given value.
+    def before(value)
+      return [] if (number = number_at(value)).nil?
+      all(:conditions => "#{aliased_table_name}.number < #{number}")
+    end
+
+    # Returns all version records created after the version associated with the given value.
+    #
+    # This is useful for dissociating records during use of the +reset_to!+ method.
+    def after(value)
+      return [] if (number = number_at(value)).nil?
+      all(:conditions => "#{aliased_table_name}.number > #{number}")
+    end
+
+    # Returns a single version associated with the given value. The following formats are valid:
+    # * A Date or Time object: When given, +to_time+ is called on the value and the last version
+    #   record in the history created before (or at) that time is returned.
+    # * A Numeric object: Typically a positive integer, these values correspond to version numbers
+    #   and the associated version record is found by a version number equal to the given value
+    #   rounded down to the nearest integer.
+    # * A String: A string value represents a version tag and the associated version is searched
+    #   for by a matching tag value. *Note:* Be careful with string representations of numbers.
+    # * A Symbol: Symbols represent association class methods on the +has_many+ versions
+    #   association. While all of the built-in association methods require arguments, additional
+    #   extension modules can be defined using the <tt>:extend</tt> option on the +versioned+
+    #   method. See the +versioned+ documentation for more information.
+    # * A Version object: If a version object is passed to the +at+ method, it is simply returned
+    #   untouched.
+    def at(value)
+      case value
+        when Date, Time then last(:conditions => ["#{aliased_table_name}.created_at <= ?", value.to_time])
+        when Numeric then find_by_number(value.floor)
+        when String then find_by_tag(value)
+        when Symbol then respond_to?(value) ? send(value) : nil
+        when Version then value
+      end
+    end
+
+    # Returns the version number associated with the given value. In many cases, this involves
+    # simply passing the value to the +at+ method and then returning the subsequent version number.
+    # Hoever, for Numeric values, the version number can be returned directly and for Date/Time
+    # values, a default value of 1 is given to ensure that times prior to the first version
+    # still return a valid version number (useful for reversion).
+    def number_at(value)
+      case value
+        when Date, Time then (v = at(value)) ? v.number : 1
+        when Numeric then value.floor
+        when String, Symbol then (v = at(value)) ? v.number : nil
+        when Version then value.number
+      end
+    end
+  end
+end

data/test/changes_test.rb

@@ -0,0 +1,169 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'test_helper'))
+
+class ChangesTest < Test::Unit::TestCase
+  context "A version's changes" do
+    setup do
+      @user = User.create(:name => 'Steve Richert')
+      @user.update_attribute(:last_name, 'Jobs')
+      @changes = @user.versions.last.changes
+    end
+
+    should 'be a hash' do
+      assert_kind_of Hash, @changes
+    end
+
+    should 'not be empty' do
+      assert !@changes.empty?
+    end
+
+    should 'have string keys' do
+      @changes.keys.each do |key|
+        assert_kind_of String, key
+      end
+    end
+
+    should 'have array values' do
+      @changes.values.each do |value|
+        assert_kind_of Array, value
+      end
+    end
+
+    should 'have two-element values' do
+      @changes.values.each do |value|
+        assert_equal 2, value.size
+      end
+    end
+
+    should 'have unique-element values' do
+      @changes.values.each do |value|
+        assert_equal value.uniq, value
+      end
+    end
+
+    should "equal the model's changes" do
+      @user.first_name = 'Stephen'
+      model_changes = @user.changes
+      @user.save
+      changes = @user.versions.last.changes
+      assert_equal model_changes, changes
+    end
+  end
+
+  context 'A hash of changes' do
+    setup do
+      @changes = {'first_name' => ['Steve', 'Stephen']}
+      @other = {'first_name' => ['Catie', 'Catherine']}
+    end
+
+    should 'properly append other changes' do
+      expected = {'first_name' => ['Steve', 'Catherine']}
+      changes = @changes.append_changes(@other)
+      assert_equal expected, changes
+      @changes.append_changes!(@other)
+      assert_equal expected, @changes
+    end
+
+    should 'properly prepend other changes' do
+      expected = {'first_name' => ['Catie', 'Stephen']}
+      changes = @changes.prepend_changes(@other)
+      assert_equal expected, changes
+      @changes.prepend_changes!(@other)
+      assert_equal expected, @changes
+    end
+
+    should 'be reversible' do
+      expected = {'first_name' => ['Stephen', 'Steve']}
+      changes = @changes.reverse_changes
+      assert_equal expected, changes
+      @changes.reverse_changes!
+      assert_equal expected, @changes
+    end
+  end
+
+  context 'The changes between two versions' do
+    setup do
+      name = 'Steve Richert'
+      @user = User.create(:name => name)              # 1
+      @user.update_attribute(:last_name, 'Jobs')      # 2
+      @user.update_attribute(:first_name, 'Stephen')  # 3
+      @user.update_attribute(:last_name, 'Richert')   # 4
+      @user.update_attribute(:name, name)             # 5
+      @version = @user.version
+    end
+
+    should 'be a hash' do
+      1.upto(@version) do |i|
+        1.upto(@version) do |j|
+          changes = @user.changes_between(i, j)
+          assert_kind_of Hash, changes
+        end
+      end
+    end
+
+    should 'have string keys' do
+      1.upto(@version) do |i|
+        1.upto(@version) do |j|
+          changes = @user.changes_between(i, j)
+          changes.keys.each do |key|
+            assert_kind_of String, key
+          end
+        end
+      end
+    end
+
+    should 'have array values' do
+      1.upto(@version) do |i|
+        1.upto(@version) do |j|
+          changes = @user.changes_between(i, j)
+          changes.values.each do |value|
+            assert_kind_of Array, value
+          end
+        end
+      end
+    end
+
+    should 'have two-element values' do
+      1.upto(@version) do |i|
+        1.upto(@version) do |j|
+          changes = @user.changes_between(i, j)
+          changes.values.each do |value|
+            assert_equal 2, value.size
+          end
+        end
+      end
+    end
+
+    should 'have unique-element values' do
+      1.upto(@version) do |i|
+        1.upto(@version) do |j|
+          changes = @user.changes_between(i, j)
+          changes.values.each do |value|
+            assert_equal value.uniq, value
+          end
+        end
+      end
+    end
+
+    should 'be empty between identical versions' do
+      assert @user.changes_between(1, @version).empty?
+      assert @user.changes_between(@version, 1).empty?
+    end
+
+    should 'be should reverse with direction' do
+      1.upto(@version) do |i|
+        i.upto(@version) do |j|
+          up    = @user.changes_between(i, j)
+          down  = @user.changes_between(j, i)
+          assert_equal up, down.reverse_changes
+        end
+      end
+    end
+
+    should 'be empty with invalid arguments' do
+      1.upto(@version) do |i|
+        assert @user.changes_between(i, nil)
+        assert @user.changes_between(nil, i)
+      end
+    end
+  end
+end