brianjlandau-vestal_versions 1.3.0

data/lib/vestal_versions/associations.rb

@@ -0,0 +1,67 @@
+module VestalVersions
+  # Allows associations to be automatically reverted_to a given instance method.
+  module Associations
+    def self.extended(base) # :nodoc:
+      base.class_eval do
+        valid_keys_for_belongs_to_association               << :versioned
+        valid_keys_for_has_and_belongs_to_many_association  << :versioned
+        valid_keys_for_has_many_association                 << :versioned
+        valid_keys_for_has_one_association                  << :versioned
+      end
+
+      ActiveRecord::Associations::AssociationProxy.send(:include, AssociationProxy::Reversion)
+      ActiveRecord::Associations::AssociationProxy.send(:include, AssociationProxy)
+      ActiveRecord::Associations::AssociationCollection.send(:include, AssociationProxy)
+      ActiveRecord::Associations::AssociationCollection.send(:include, AssociationCollection)
+    end
+
+    module AssociationCollection
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          alias_method_chain :first, :reversion
+          alias_method_chain :last, :reversion
+        end
+      end
+
+      def first_with_reversion(*args)
+        record = first_without_reversion(*args)
+        revert_record(record) if record
+        record
+      end
+      
+      def last_with_reversion(*args)
+        record = last_without_reversion(*args)
+        revert_record(record) if record
+        record
+      end
+    end
+
+    module AssociationProxy
+      def self.included(base) # :nodoc:
+        base.class_eval do
+          alias_method_chain :load_target, :reversion
+        end
+      end
+
+      def load_target_with_reversion
+        @target = load_target_without_reversion
+        revert_target if @reflection.options[:versioned]
+        @target
+      end
+
+      module Reversion
+        private
+          def revert_target
+            case @target
+              when ActiveRecord::Base then revert_record(@target)
+              when Array then @target.each{|r| revert_record(r) }
+            end
+          end
+
+          def revert_record(record)
+            record.revert_to(@owner.version) if record.class.versioned?
+          end
+      end
+    end
+  end
+end

data/lib/vestal_versions/changes.rb

@@ -0,0 +1,125 @@
+module VestalVersions
+  # Provides the ability to manipulate hashes in the specific format that ActiveRecord gives to
+  # dirty attribute changes: string keys and unique, two-element array values.
+  module Changes
+    def self.included(base) # :nodoc:
+      Hash.send(:include, HashMethods)
+
+      base.class_eval do
+        include InstanceMethods
+
+        after_update :merge_version_changes
+      end
+    end
+
+    # Methods available to versioned ActiveRecord::Base instances in order to manage changes used
+    # for version creation.
+    module InstanceMethods
+      # Collects an array of changes from a record's versions between the given range and compiles
+      # them into one summary hash of changes. The +from+ and +to+ arguments can each be either a
+      # version number, a symbol representing an association proxy method, a string representing a
+      # version tag or a version object itself.
+      def changes_between(from, to)
+        from_number, to_number = versions.number_at(from), versions.number_at(to)
+        return {} if from_number == to_number
+        chain = versions.between(from_number, to_number).reject(&:initial?)
+        return {} if chain.empty?
+
+        backward = from_number > to_number
+        backward ? chain.pop : chain.shift unless from_number == 1 || to_number == 1
+
+        chain.inject({}) do |changes, version|
+          changes.append_changes!(backward ? version.changes.reverse_changes : version.changes)
+        end
+      end
+
+      private
+        # Before a new version is created, the newly-changed attributes are appended onto a hash
+        # of previously-changed attributes. Typically the previous changes will be empty, except in
+        # the case that a control block is used where versions are to be merged. See
+        # VestalVersions::Control for more information.
+        def merge_version_changes
+          version_changes.append_changes!(incremental_version_changes)
+        end
+
+        # Stores the cumulative changes that are eventually used for version creation.
+        def version_changes
+          @version_changes ||= {}
+        end
+
+        # Stores the incremental changes that are appended to the cumulative changes before version
+        # creation. Incremental changes are reset when the record is saved because they represent
+        # a subset of the dirty attribute changes, which are reset upon save.
+        def incremental_version_changes
+          changes.slice(*versioned_columns)
+        end
+
+        # Simply resets the cumulative changes after version creation.
+        def reset_version_changes
+          @version_changes = nil
+        end
+    end
+
+    # Instance methods included into Hash for dealing with manipulation of hashes in the specific
+    # format of ActiveRecord::Base#changes.
+    module HashMethods
+      # When called on a hash of changes and given a second hash of changes as an argument,
+      # +append_changes+ will run the second hash on top of the first, updating the last element
+      # of each array value with its own, or creating its own key/value pair for missing keys.
+      # Resulting non-unique array values are removed.
+      #
+      # == Example
+      #
+      # first = {
+      #   "first_name" => ["Steve", "Stephen"],
+      #   "age" => [25, 26]
+      # }
+      # second = {
+      #   "first_name" => ["Stephen", "Steve"],
+      #   "last_name" => ["Richert", "Jobs"],
+      #   "age" => [26, 54]
+      # }
+      # first.append_changes(second)
+      # # => {
+      #   "last_name" => ["Richert", "Jobs"],
+      #   "age" => [25, 54]
+      # }
+      def append_changes(changes)
+        changes.inject(self) do |new_changes, (attribute, change)|
+          new_change = [new_changes.fetch(attribute, change).first, change.last]
+          new_changes.merge(attribute => new_change)
+        end.reject do |attribute, change|
+          change.first == change.last
+        end
+      end
+
+      # Destructively appends a given hash of changes onto an existing hash of changes.
+      def append_changes!(changes)
+        replace(append_changes(changes))
+      end
+
+      # Appends the existing hash of changes onto a given hash of changes. Relates to the
+      # +append_changes+ method in the same way that Hash#reverse_merge relates to
+      # Hash#merge.
+      def prepend_changes(changes)
+        changes.append_changes(self)
+      end
+
+      # Destructively prepends a given hash of changes onto an existing hash of changes.
+      def prepend_changes!(changes)
+        replace(prepend_changes(changes))
+      end
+
+      # Reverses the array values of a hash of changes. Useful for reversion both backward and
+      # forward through a record's history of changes.
+      def reverse_changes
+        inject({}){|nc,(a,c)| nc.merge!(a => c.reverse) }
+      end
+
+      # Destructively reverses the array values of a hash of changes.
+      def reverse_changes!
+        replace(reverse_changes)
+      end
+    end
+  end
+end

data/lib/vestal_versions/conditions.rb

@@ -0,0 +1,69 @@
+module VestalVersions
+  # Allows version creation to occur conditionally based on given <tt>:if</tt> and/or
+  # <tt>:unless</tt> options.
+  module Conditions
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        extend ClassMethods
+        include InstanceMethods
+
+        alias_method_chain :create_version?, :conditions
+        alias_method_chain :update_version?, :conditions
+
+        class << self
+          alias_method_chain :prepare_versioned_options, :conditions
+        end
+      end
+    end
+
+    # Class methods on ActiveRecord::Base to prepare the <tt>:if</tt> and <tt>:unless</tt> options.
+    module ClassMethods
+      # After the original +prepare_versioned_options+ method cleans the given options, this alias
+      # also extracts the <tt>:if</tt> and <tt>:unless</tt> options, chaning them into arrays
+      # and converting any symbols to procs. Procs are called with the ActiveRecord model instance
+      # as the sole argument.
+      #
+      # If all of the <tt>:if</tt> conditions are met and none of the <tt>:unless</tt> conditions
+      # are unmet, than version creation will proceed, assuming all other conditions are also met.
+      def prepare_versioned_options_with_conditions(options)
+        result = prepare_versioned_options_without_conditions(options)
+
+        self.vestal_versions_options[:if] = Array(options.delete(:if)).map(&:to_proc)
+        self.vestal_versions_options[:unless] = Array(options.delete(:unless)).map(&:to_proc)
+
+        result
+      end
+    end
+
+    # Instance methods that determine based on the <tt>:if</tt> and <tt>:unless</tt> conditions,
+    # whether a version is to be create or updated.
+    module InstanceMethods
+      private
+        # After first determining whether the <tt>:if</tt> and <tt>:unless</tt> conditions are
+        # satisfied, the original, unaliased +create_version?+ method is called to determine
+        # whether a new version should be created upon update of the ActiveRecord::Base instance.
+        def create_version_with_conditions?
+          version_conditions_met? && create_version_without_conditions?
+        end
+
+        # After first determining whether the <tt>:if</tt> and <tt>:unless</tt> conditions are
+        # satisfied, the original, unaliased +update_version?+ method is called to determine
+        # whther the last version should be updated to include changes merged from the current
+        # ActiveRecord::Base instance update.
+        #
+        # The overridden +update_version?+ method simply returns false, effectively delegating
+        # the decision to whether the <tt>:if</tt> and <tt>:unless</tt> conditions are met.
+        def update_version_with_conditions?
+          version_conditions_met? && update_version_without_conditions?
+        end
+
+        # Simply checks whether the <tt>:if</tt> and <tt>:unless</tt> conditions given in the
+        # +versioned+ options are met: meaning that all procs in the <tt>:if</tt> array must
+        # evaluate to a non-false, non-nil value and that all procs in the <tt>:unless</tt> array
+        # must all evaluate to either false or nil.
+        def version_conditions_met?
+          vestal_versions_options[:if].all?{|p| p.call(self) } && !vestal_versions_options[:unless].any?{|p| p.call(self) }
+        end
+    end
+  end
+end

data/lib/vestal_versions/configuration.rb

@@ -0,0 +1,40 @@
+module VestalVersions
+  # Allows for easy application-wide configuration of options passed into the +versioned+ method.
+  module Configuration
+    # The VestalVersions module is extended by VestalVersions::Configuration, allowing the
+    # +configure method+ to be used as follows in a Rails initializer:
+    #
+    #   VestalVersions.configure do |config|
+    #     config.class_name = "MyCustomVersion"
+    #     config.dependent = :destroy
+    #   end
+    #
+    # Each variable assignment in the +configure+ block corresponds directly with the options
+    # available to the +versioned+ method. Assigning common options in an initializer can keep your
+    # models tidy.
+    #
+    # If an option is given in both an initializer and in the options passed to +versioned+, the
+    # value given in the model itself will take precedence.
+    def configure
+      yield Configuration
+    end
+
+    class << self
+      # Simply stores a hash of options given to the +configure+ block.
+      def options
+        @options ||= {}
+      end
+
+      # If given a setter method name, will assign the first argument to the +options+ hash with
+      # the method name (sans "=") as the key. If given a getter method name, will attempt to
+      # a value from the +options+ hash for that key. If the key doesn't exist, defers to +super+.
+      def method_missing(symbol, *args)
+        if (method = symbol.to_s).sub!(/\=$/, '')
+          options[method.to_sym] = args.first
+        else
+          options.fetch(method.to_sym, super)
+        end
+      end
+    end
+  end
+end

data/lib/vestal_versions/control.rb

@@ -0,0 +1,175 @@
+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
+    def self.included(base) # :nodoc:
+      base.class_eval do
+        include InstanceMethods
+
+        alias_method_chain :create_version?, :control
+        alias_method_chain :update_version?, :control
+      end
+    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.
+    module InstanceMethods
+      # 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
+
+      # A convenience method for determining whether a versioned instance is set to skip its next
+      # version creation.
+      def skip_version?
+        !!@skip_version
+      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_attributes(:first_name => "Stephen")
+      #     user.update_attributes(: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
+
+      private
+        # 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)
+          begin
+            instance_variable_set("@#{flag}", true)
+            yield
+          ensure
+            instance_variable_set("@#{flag}", nil)
+          end
+        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_with_control?
+          !skip_version? && !merge_version? && !append_version? && create_version_without_control?
+        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_with_control?
+          append_version?
+        end
+    end
+  end
+end