razenha-vestal_versions 1.2.2

data/lib/vestal_versions/conditions.rb

@@ -0,0 +1,57 @@
+module VestalVersions
+  # Allows version creation to occur conditionally based on given <tt>:if</tt> and/or
+  # <tt>:unless</tt> options.
+  module Conditions
+    extend ActiveSupport::Concern
+
+    # 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(options)
+        result = super(options)
+
+        vestal_versions_options[:if] = Array(options.delete(:if)).map(&:to_proc)
+        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?
+          version_conditions_met? && super
+        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?
+          version_conditions_met? && super
+        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/control.rb

@@ -0,0 +1,200 @@
+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.
+    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
+
+      # 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
+
+    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.
+    module InstanceMethods
+      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
+end

data/lib/vestal_versions/deletion.rb

@@ -0,0 +1,39 @@
+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
+
+    module InstanceMethods
+      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
+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_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,17 @@
+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.
+    module InstanceMethods
+      # 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
+end