geothird_vestal_versions 1.2.3

data/lib/vestal_versions/reversion.rb

@@ -0,0 +1,80 @@
+module VestalVersions
+  # Enables versioned ActiveRecord::Base instances to revert to a previously saved version.
+  module Reversion
+    extend ActiveSupport::Concern
+
+    # Provides the base instance methods required to revert a versioned instance.
+    # 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
+
+    # Mixes in the reverted_from value if it is currently within a revert
+    def version_attributes
+      attributes = super
+
+      if @reverted_from.nil?
+        attributes
+      else
+        attributes.merge(:reverted_from => @reverted_from)
+      end
+    end
+
+    # 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)
+      if version.nil?
+        @last_version = nil
+        @reverted_from = nil
+      else
+        @reverted_from = version
+      end
+      @version = version
+    end
+  end
+end

data/lib/vestal_versions/users.rb

@@ -0,0 +1,53 @@
+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
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :updated_by
+      Version.class_eval{ include VersionMethods }
+    end
+
+    # Methods added to versioned ActiveRecord::Base instances to enable versioning with additional
+    # user information.
+
+    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
+      super.merge(:user => updated_by)
+    end
+
+    # Instance methods added to VestalVersions::Version to accomodate incoming user information.
+    module VersionMethods
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :user, :polymorphic => true
+
+        alias_method_chain :user, :name
+        alias_method_chain :user=, :name
+      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,81 @@
+require 'active_record'
+require 'active_support/configurable'
+
+module VestalVersions
+  # The ActiveRecord model representing versions.
+  class Version < ActiveRecord::Base
+    include Comparable
+    include ActiveSupport::Configurable
+
+    # Associate polymorphically with the parent record.
+    belongs_to :versioned, :polymorphic => true
+    attr_accessible :modifications, :number, :user
+
+    # 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
+    
+    # Returns the original version number that this version was.
+    def original_number
+      if reverted_from.nil?
+        number
+      else
+        version = versioned.versions.at(reverted_from)
+        version.nil? ? 1 : version.original_number
+      end
+    end
+
+    def restore!
+      model = restore
+      
+      if model
+        model.save!
+        destroy
+      end
+      
+      model
+    end
+    
+    def restore
+      if tag == 'deleted'
+        attrs = modifications
+
+        class_name = attrs['type'].blank? ? versioned_type : attrs['type']
+        klass = class_name.constantize
+        model = klass.new
+
+        attrs.each do |k, v|
+          begin
+            model.send "#{k}=", v
+          rescue NoMethodError
+            logger.warn "Attribute #{k} does not exist on #{class_name} (Version id: #{id})." rescue nil
+          end
+        end
+
+        model
+      else
+        latest_version = self.class.find(:first, :conditions => {:versioned_id => versioned_id, :versioned_type => versioned_type, :tag => 'deleted'})
+        latest_version.nil? ? nil : latest_version.restore
+      end
+    end
+  end
+end

data/lib/vestal_versions/version_num.rb

@@ -0,0 +1,3 @@
+module VestalVersions
+  VERSION = '1.2.3'
+end

data/lib/vestal_versions/version_tagging.rb

@@ -0,0 +1,48 @@
+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 VersionTagging
+    extend ActiveSupport::Concern
+
+    # Adds an instance method which allows version tagging through the parent object.
+    # 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
+
+    # Instance methods included into VestalVersions::Version to enable version tagging.
+    module VersionMethods
+      extend ActiveSupport::Concern
+
+      included do
+        validates_uniqueness_of :tag, :scope => [:versioned_id, :versioned_type], :if => :validate_tags?
+      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
+
+      def validate_tags?
+        tagged? && tag != 'deleted'
+      end
+    end
+
+    Version.class_eval{ include VersionMethods }
+  end
+end

data/lib/vestal_versions/versioned.rb

@@ -0,0 +1,27 @@
+module VestalVersions
+  # Simply adds a flag to determine whether a model class if versioned.
+  module Versioned
+    extend ActiveSupport::Concern
+
+    # Overrides the +versioned+ method to first define the +versioned?+ class method before
+    # deferring to the original +versioned+.
+    module ClassMethods
+      def versioned(*args)
+        super(*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
+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 => "#{table_name}.#{connection.quote_column_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 => "#{table_name}.#{connection.quote_column_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 => "#{table_name}.#{connection.quote_column_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 => ["#{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/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+require 'bundler'
+Bundler.require
+require 'rspec/core'
+
+RSpec.configure do |c|
+  c.before(:suite) do
+    CreateSchema.suppress_messages{ CreateSchema.migrate(:up) }
+  end
+
+  c.after(:suite) do
+    FileUtils.rm_rf(File.expand_path('../test.db', __FILE__))
+  end
+
+  c.after(:each) do
+    VestalVersions::Version.config.clear
+    User.prepare_versioned_options({})
+  end
+end
+
+Dir[File.expand_path('../support/*.rb', __FILE__)].each{|f| require f }

data/spec/support/models.rb

@@ -0,0 +1,19 @@
+class User < ActiveRecord::Base
+  versioned
+
+  def name
+    [first_name, last_name].compact.join(' ')
+  end
+
+  def name= names
+    self[:first_name], self[:last_name] = names.split(' ', 2)
+  end
+end
+
+class DeletedUser < ActiveRecord::Base
+  self.table_name = 'users'
+  versioned :dependent => :tracking
+end
+
+class MyCustomVersion < VestalVersions::Version
+end

data/spec/support/schema.rb

@@ -0,0 +1,25 @@
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => File.expand_path('../../test.db', __FILE__)
+)
+
+class CreateSchema < ActiveRecord::Migration
+  def self.up
+    create_table :users, :force => true do |t|
+      t.string :first_name
+      t.string :last_name
+      t.timestamps
+    end
+
+    create_table :versions, :force => true do |t|
+      t.belongs_to :versioned, :polymorphic => true
+      t.belongs_to :user, :polymorphic => true
+      t.string :user_name
+      t.text :modifications
+      t.integer :number
+      t.integer :reverted_from
+      t.string :tag
+      t.timestamps
+    end
+  end
+end