houston-vestal_versions 2.0.0

data/lib/vestal_versions/control.rb

@@ -0,0 +1,199 @@
+module VestalVersions
+  # The control feature allows use of several code blocks that provide finer control over whether
+  # a new version is created, or a previous version is updated.
+  module Control
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_skip_version, :instance_writer => false
+    end
+
+
+    # Control blocks are called on ActiveRecord::Base instances as to not cause any conflict with
+    # other instances of the versioned class whose behavior could be inadvertently altered within
+    # a control block.
+    
+    # The +skip_version+ block simply allows for updates to be made to an instance of a versioned
+    # ActiveRecord model while ignoring all new version creation. The <tt>:if</tt> and
+    # <tt>:unless</tt> conditions (if given) will not be evaulated inside a +skip_version+ block.
+    #
+    # When the block closes, the instance is automatically saved, so explicitly saving the
+    # object within the block is unnecessary.
+    #
+    # == Example
+    #
+    #   user = User.find_by_first_name("Steve")
+    #   user.version # => 1
+    #   user.skip_version do
+    #     user.first_name = "Stephen"
+    #   end
+    #   user.version # => 1
+    def skip_version
+      _with_version_flag(:_skip_version) do
+        yield if block_given?
+        save
+      end
+    end
+
+    # Behaving almost identically to the +skip_version+ block, the only difference with the
+    # +skip_version!+ block is that the save automatically performed at the close of the block
+    # is a +save!+, meaning that an exception will be raised if the object cannot be saved.
+    def skip_version!
+      _with_version_flag(:_skip_version) do
+        yield if block_given?
+        save!
+      end
+    end
+
+    # Merging versions with the +merge_version+ block will take all of the versions that would
+    # be created within the block and merge them into one version and pushing that single version
+    # onto the ActiveRecord::Base instance's version history. A new version will be created and
+    # the instance's version number will be incremented.
+    #
+    # == Example
+    #
+    #   user = User.find_by_first_name("Steve")
+    #   user.version # => 1
+    #   user.merge_version do
+    #     user.update_attributes(:first_name => "Steven", :last_name => "Tyler")
+    #     user.update_attribute(:first_name, "Stephen")
+    #     user.update_attribute(:last_name, "Richert")
+    #   end
+    #   user.version # => 2
+    #   user.versions.last.changes
+    #   # => {"first_name" => ["Steve", "Stephen"], "last_name" => ["Jobs", "Richert"]}
+    #
+    # See VestalVersions::Changes for an explanation on how changes are appended.
+    def merge_version
+      _with_version_flag(:merge_version) do
+        yield if block_given?
+      end
+      save
+    end
+
+    # Behaving almost identically to the +merge_version+ block, the only difference with the
+    # +merge_version!+ block is that the save automatically performed at the close of the block
+    # is a +save!+, meaning that an exception will be raised if the object cannot be saved.
+    def merge_version!
+      _with_version_flag(:merge_version) do
+        yield if block_given?
+      end
+      save!
+    end
+
+    # A convenience method for determining whether a versioned instance is set to merge its next
+    # versions into one before version creation.
+    def merge_version?
+      !!@merge_version
+    end
+
+    # Appending versions with the +append_version+ block acts similarly to the +merge_version+
+    # block in that all would-be version creations within the block are defered until the block
+    # closes. The major difference is that with +append_version+, a new version is not created.
+    # Rather, the cumulative changes are appended to the serialized changes of the instance's
+    # last version. A new version is not created, so the version number is not incremented.
+    #
+    # == Example
+    #
+    #   user = User.find_by_first_name("Steve")
+    #   user.version # => 2
+    #   user.versions.last.changes
+    #   # => {"first_name" => ["Stephen", "Steve"]}
+    #   user.append_version do
+    #     user.last_name = "Jobs"
+    #   end
+    #   user.versions.last.changes
+    #   # => {"first_name" => ["Stephen", "Steve"], "last_name" => ["Richert", "Jobs"]}
+    #   user.version # => 2
+    #
+    # See VestalVersions::Changes for an explanation on how changes are appended.
+    def append_version
+      _with_version_flag(:merge_version) do
+        yield if block_given?
+      end
+
+      _with_version_flag(:append_version) do
+        save
+      end
+    end
+
+    # Behaving almost identically to the +append_version+ block, the only difference with the
+    # +append_version!+ block is that the save automatically performed at the close of the block
+    # is a +save!+, meaning that an exception will be raised if the object cannot be saved.
+    def append_version!
+      _with_version_flag(:merge_version) do
+        yield if block_given?
+      end
+
+      _with_version_flag(:append_version) do
+        save!
+      end
+    end
+
+    # A convenience method for determining whether a versioned instance is set to append its next
+    # version's changes into the last version changes.
+    def append_version?
+      !!@append_version
+    end
+
+    # Used for each control block, the +_with_version_flag+ method sets a given variable to
+    # true and then executes the given block, ensuring that the variable is returned to a nil
+    # value before returning. This is useful to be certain that one of the control flag
+    # instance variables isn't inadvertently left in the "on" position by execution within the
+    # block raising an exception.
+    def _with_version_flag(flag)
+      instance_variable_set("@#{flag}", true)
+      yield
+    ensure
+      remove_instance_variable("@#{flag}")
+    end
+
+    # Overrides the basal +create_version?+ method to make sure that new versions are not
+    # created when inside any of the control blocks (until the block terminates).
+    def create_version?
+      !_skip_version? && !merge_version? && !append_version? && super
+    end
+
+    # Overrides the basal +update_version?+ method to allow the last version of an versioned
+    # ActiveRecord::Base instance to be updated at the end of an +append_version+ block.
+    def update_version?
+      append_version?
+    end
+    
+    module ClassMethods
+      # The +skip_version+ block simply allows for updates to be made to an instance of a versioned
+      # ActiveRecord model while ignoring all new version creation. The <tt>:if</tt> and
+      # <tt>:unless</tt> conditions (if given) will not be evaulated inside a +skip_version+ block.
+      #
+      # When the block closes, the instance is automatically saved, so explicitly saving the
+      # object within the block is unnecessary.
+      #
+      # == Example
+      #
+      #   user = User.find_by_first_name("Steve")
+      #   user.version # => 1
+      #   user.skip_version do
+      #     user.first_name = "Stephen"
+      #   end
+      #   user.version # => 1
+      def skip_version
+        _with_version_flag(:_skip_version) do
+          yield if block_given?
+        end
+      end
+
+      # Used for each control block, the +with_version_flag+ method sets a given variable to
+      # true and then executes the given block, ensuring that the variable is returned to a nil
+      # value before returning. This is useful to be certain that one of the control flag
+      # instance variables isn't inadvertently left in the "on" position by execution within the
+      # block raising an exception.
+      def _with_version_flag(flag)
+        self.send("#{flag}=", true)
+        yield
+      ensure
+        self.send("#{flag}=", nil)
+      end
+
+    end
+  end
+end

data/lib/vestal_versions/creation.rb

@@ -0,0 +1,93 @@
+module VestalVersions
+  # Adds the functionality necessary to control version creation on a versioned instance of
+  # ActiveRecord::Base.
+  module Creation
+    extend ActiveSupport::Concern
+
+    included do
+      after_create :create_initial_version, :if => :create_initial_version?
+      after_update :create_version, :if => :create_version?
+      after_update :update_version, :if => :update_version?
+    end
+
+    # Class methods added to ActiveRecord::Base to facilitate the creation of new versions.
+    module ClassMethods
+      # Overrides the basal +prepare_versioned_options+ method defined in VestalVersions::Options
+      # to extract the <tt>:only</tt>, <tt>:except</tt> and <tt>:initial_version</tt> options
+      # into +vestal_versions_options+.
+      def prepare_versioned_options(options)
+        result = super(options)
+
+        self.vestal_versions_options[:only] = Array(options.delete(:only)).map(&:to_s).uniq if options[:only]
+        self.vestal_versions_options[:except] = Array(options.delete(:except)).map(&:to_s).uniq if options[:except]
+        self.vestal_versions_options[:initial_version] = options.delete(:initial_version)
+        
+        result
+      end
+    end
+
+    # Instance methods that determine whether to save a version and actually perform the save.
+    
+    private
+    
+    # Returns whether an initial version should be created upon creation of the parent record.
+    def create_initial_version?
+      vestal_versions_options[:initial_version] == true
+    end
+
+    # Creates an initial version upon creation of the parent record.
+    def create_initial_version
+      versions.create(version_attributes.merge(:number => 1))
+      reset_version_changes
+      reset_version
+    end
+            
+    # Returns whether a new version should be created upon updating the parent record.
+    def create_version?
+      !version_changes.blank?
+    end
+
+    # Creates a new version upon updating the parent record.
+    def create_version(attributes = nil)
+      versions.create(attributes || version_attributes)
+      reset_version_changes
+      reset_version
+    end
+
+    # Returns whether the last version should be updated upon updating the parent record.
+    # This method is overridden in VestalVersions::Control to account for a control block that
+    # merges changes onto the previous version.
+    def update_version?
+      false
+    end
+
+    # Updates the last version's changes by appending the current version changes.
+    def update_version
+      return create_version unless v = versions.last
+      v.modifications_will_change!
+      v.update_attribute(:modifications, v.changes.append_changes(version_changes))
+      reset_version_changes
+      reset_version
+    end
+
+    # Returns an array of column names that should be included in the changes of created
+    # versions. If <tt>vestal_versions_options[:only]</tt> is specified, only those columns
+    # will be versioned. Otherwise, if <tt>vestal_versions_options[:except]</tt> is specified,
+    # all columns will be versioned other than those specified. Without either option, the
+    # default is to version all columns. At any rate, the four "automagic" timestamp columns
+    # maintained by Rails are never versioned.
+    def versioned_columns
+      case
+        when vestal_versions_options[:only] then self.class.column_names & vestal_versions_options[:only]
+        when vestal_versions_options[:except] then self.class.column_names - vestal_versions_options[:except]
+        else self.class.column_names
+      end - %w(created_at created_on updated_at updated_on)
+    end
+
+    # Specifies the attributes used during version creation. This is separated into its own
+    # method so that it can be overridden by the VestalVersions::Users feature.
+    def version_attributes
+      {:modifications => version_changes, :number => last_version + 1}
+    end
+  end
+end

data/lib/vestal_versions/deletion.rb

@@ -0,0 +1,37 @@
+module VestalVersions
+  # Allows version creation to occur conditionally based on given <tt>:if</tt> and/or
+  # <tt>:unless</tt> options.
+  module Deletion
+    extend ActiveSupport::Concern
+
+    included do
+      before_destroy :create_destroyed_version, :if => :delete_version?
+    end
+
+    # Class methods on ActiveRecord::Base
+    module ClassMethods
+      # After the original +prepare_versioned_options+ method cleans the given options, this alias
+      # also extracts the <tt>:depedent</tt> if it set to <tt>:tracking</tt>
+      def prepare_versioned_options(options)
+        result = super(options)
+        if result[:dependent] == :tracking
+          self.vestal_versions_options[:track_destroy] = true
+          options.delete(:dependent)
+        end
+
+        result
+      end
+    end
+
+    private
+
+    def delete_version?
+      vestal_versions_options[:track_destroy]
+    end
+
+    def create_destroyed_version
+      create_version({:modifications => attributes, :number => last_version + 1, :tag => 'deleted'})
+    end
+  
+  end
+end

data/lib/vestal_versions/options.rb

@@ -0,0 +1,41 @@
+module VestalVersions
+  # Provides +versioned+ options conversion and cleanup.
+  module Options
+    extend ActiveSupport::Concern
+
+    # 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!(VestalVersions.config)
+        options.reverse_merge!(
+          :class_name => 'VestalVersions::Version',
+          :dependent => :delete_all
+        )
+        # options.reverse_merge!(
+        #   :order => "#{options[:class_name].constantize.table_name}.#{connection.quote_column_name('number')} ASC"
+        # )
+
+        class_attribute :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,16 @@
+module VestalVersions
+  # Ties into the existing ActiveRecord::Base#reload method to ensure that version information
+  # is properly reset.
+  module Reload
+    extend ActiveSupport::Concern
+
+    # Adds instance methods into ActiveRecord::Base to tap into the +reload+ method.
+    
+    # Overrides ActiveRecord::Base#reload, resetting the instance-variable-cached version number
+    # before performing the original +reload+ method.
+    def reload(*args)
+      reset_version
+      super
+    end
+  end
+end

data/lib/vestal_versions/reset.rb

@@ -0,0 +1,24 @@
+module VestalVersions
+  # Adds the ability to "reset" (or hard revert) a versioned ActiveRecord::Base instance.
+  module Reset
+    extend ActiveSupport::Concern
+
+    # Adds the instance methods required to reset an object to a previous version.
+    
+    # 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, versions.after(value))
+        reset_version
+      end
+      saved
+    end
+    
+  end
+end

data/lib/vestal_versions/reversion.rb

@@ -0,0 +1,81 @@
+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,54 @@
+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 UserVersionMethods }
+    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
+  end
+
+  # Instance methods added to VestalVersions::Version to accomodate incoming user information.
+  module UserVersionMethods
+    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

data/lib/vestal_versions/version.rb

@@ -0,0 +1,84 @@
+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
+
+    if ActiveRecord::VERSION::MAJOR == 3
+      attr_accessible :modifications, :number, :user, :tag, :reverted_from
+    end
+
+    # 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.where(:versioned_id => versioned_id, :versioned_type => versioned_type, :tag => 'deleted').first
+        latest_version.nil? ? nil : latest_version.restore
+      end
+    end
+  end
+end

data/lib/vestal_versions/version_tagging.rb

@@ -0,0 +1,51 @@
+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)
+      t = v.tag!(tag)
+      versions.reload
+      t
+    end
+  end
+
+  # Instance methods included into VestalVersions::Version to enable version tagging.
+  module TaggingVersionMethods
+    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
+
+    Version.class_eval{ include TaggingVersionMethods }
+  end
+end