vestal_versions 0.8.3 → 1.0.0

data/lib/vestal_versions/options.rb

@@ -0,0 +1,42 @@
+module VestalVersions
+  # Provides +versioned+ options conversion and cleanup.
+  module Options
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    # Class methods that provide preparation of options passed to the +versioned+ method.
+    module ClassMethods
+      # The +prepare_versioned_options+ method has three purposes:
+      # 1. Populate the provided options with default values where needed
+      # 2. Prepare options for use with the +has_many+ association
+      # 3. Save user-configurable options in a class-level variable
+      #
+      # Options are given priority in the following order:
+      # 1. Those passed directly to the +versioned+ method
+      # 2. Those specified in an initializer +configure+ block
+      # 3. Default values specified in +prepare_versioned_options+
+      #
+      # The method is overridden in feature modules that require specific options outside the
+      # standard +has_many+ associations.
+      def prepare_versioned_options(options)
+        options.symbolize_keys!
+        options.reverse_merge!(Configuration.options)
+        options.reverse_merge!(
+          :class_name => 'VestalVersions::Version',
+          :dependent => :delete_all
+        )
+
+        class_inheritable_accessor :vestal_versions_options
+        self.vestal_versions_options = options.dup
+
+        options.merge!(
+          :as => :versioned,
+          :extend => Array(options[:extend]).unshift(Versions)
+        )
+      end
+    end
+  end
+end

data/lib/vestal_versions/reload.rb

@@ -0,0 +1,23 @@
+module VestalVersions
+  # Ties into the existing ActiveRecord::Base#reload method to ensure that version information
+  # is properly reset.
+  module Reload
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+
+        alias_method_chain :reload, :versions
+      end
+    end
+
+    # Adds instance methods into ActiveRecord::Base to tap into the +reload+ method.
+    module InstanceMethods
+      # Overrides ActiveRecord::Base#reload, resetting the instance-variable-cached version number
+      # before performing the original +reload+ method.
+      def reload_with_versions(*args)
+        reset_version
+        reload_without_versions(*args)
+      end
+    end
+  end
+end

data/lib/vestal_versions/reset.rb

@@ -0,0 +1,56 @@
+module VestalVersions
+  # Adds the ability to "reset" (or hard revert) a versioned ActiveRecord::Base instance.
+  module Reset
+    def self.included(base) # :nodoc:
+      Version.send(:include, VersionMethods)
+
+      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.after(value).each(&version_reset_method)
+          reset_version
+        end
+        saved
+      end
+
+      private
+        # The method used to individually remove versions from the version history by way of the
+        # +reset_to!+ method. There are three options for the <tt>:dependent</tt> option given
+        # to the +versioned+ method: <tt>:delete_all</tt>, <tt>:destroy</tt> and <tt>:nullify</tt>.
+        # If none is given, <tt>:delete_all</tt> is the default.
+        #
+        # If <tt>:delete_all</tt> is given, each version will be deleted from the database,
+        # triggering no callbacks. If <tt>:destroy</tt> is given, each version will likewise be
+        # deleted from the database, but any callbacks associated with version destruction will be
+        # triggered. If <tt>:nullify</tt> is specified, the version records will simply be
+        # dissociated from the versioned parent record by setting its foreign key to nil.
+        def version_reset_method
+          vestal_versions_options[:dependent].to_s.sub(/_all$/, '').to_sym
+        end
+    end
+
+    # Instance methods added to the VestalVersions::Version model to accomodate resetting the
+    # parent ActiveRecord::Base instance.
+    module VersionMethods
+      # The +nullify+ method is meant to mimic the behavior of ActiveRecord when the parent of a
+      # +has_many+ association (with <tt>:dependent => :nullify</tt>) is destroyed and the child
+      # records are dissociated from the parent's primary key.
+      def nullify
+        update_attribute(:versioned_id, nil)
+      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
+
+    # Order versions by number, ascending by default.
+    default_scope :order => "#{table_name}.number ASC"
+
+    # 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
+    serialize :changes, 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 at(value).try(:number) || 1
+        when Numeric then value.floor
+        when String, Symbol then at(value).try(:number)
+        when Version then value.number
+      end
+    end
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), '..', 'lib', 'vestal_versions')