kb-acts_as_revisable 1.0.3

data/lib/acts_as_revisable/acts/revisable.rb

@@ -0,0 +1,491 @@
+module WithoutScope
+  module ActsAsRevisable
+    
+    # This module is mixed into the revision classes.
+    # 
+    # ==== Callbacks
+    # 
+    # * +before_revise+ is called before the record is revised.
+    # * +after_revise+ is called after the record is revised.
+    # * +before_revert+ is called before the record is reverted.
+    # * +after_revert+ is called after the record is reverted.
+    # * +before_changeset+ is called before a changeset block is called.
+    # * +after_changeset+ is called after a changeset block is called.
+    # * +after_branch_created+ is called on the new revisable instance
+    #   created by branching after it's been created.
+    module Revisable
+      def self.included(base) #:nodoc:
+        base.send(:extend, ClassMethods)
+                
+        class << base
+          attr_accessor :revisable_revision_class, :revisable_columns
+        end
+        
+        base.class_inheritable_hash :revisable_shared_objects
+        base.revisable_shared_objects = {}
+        
+        base.instance_eval do
+          attr_accessor :revisable_new_params, :revisable_revision
+          
+          define_callbacks :before_revise, :after_revise, :before_revert, :after_revert, :before_changeset, :after_changeset, :after_branch_created
+                    
+          before_create :before_revisable_create
+          before_update :before_revisable_update
+          after_update :after_revisable_update
+          after_save :clear_revisable_shared_objects!, :unless => :is_reverting?
+          
+          default_scope :conditions => {:revisable_is_current => true}
+          
+          [:revisions, revisions_association_name.to_sym].each do |assoc|
+            has_many assoc, (revisable_options.revision_association_options || {}).merge({:class_name => revision_class_name, :foreign_key => :revisable_original_id, :order => "#{quoted_table_name}.#{connection.quote_column_name(:revisable_number)} DESC", :dependent => :destroy})
+          end
+        end
+        
+        if !Object.const_defined?(base.revision_class_name) && base.revisable_options.generate_revision_class?
+          Object.const_set(base.revision_class_name, Class.new(ActiveRecord::Base)).class_eval do
+            acts_as_revision
+          end            
+        end
+      end
+      
+      # Finds a specific revision of self.
+      # 
+      # The +by+ parameter can be a revision_class instance, 
+      # the symbols :first, :previous or :last, a Time instance
+      # or an Integer.
+      # 
+      # When passed a revision_class instance, this method
+      # simply returns it. This is used primarily by revert_to!.
+      # 
+      # When passed :first it returns the first revision created.
+      # 
+      # When passed :previous or :last it returns the last revision
+      # created.
+      # 
+      # When passed a Time instance it returns the revision that
+      # was the current record at the given time.
+      # 
+      # When passed an Integer it returns the revision with that
+      # revision_number.
+      def find_revision(by)
+        by = Integer(by) if by.is_a?(String) && by.match(/[0-9]+/)
+          
+        case by
+        when self.class
+          by
+        when self.class.revision_class
+          by
+        when :first
+          revisions.last
+        when :previous
+          revisions.first
+        when Time
+          revisions.find(:first, :conditions => ["? >= ? and ? <= ?", :revisable_revised_at, by, :revisable_current_at, by])
+        when self.revisable_number
+          self
+        else
+          revisions.find_by_revisable_number(by)
+        end
+      end
+            
+      # Returns a revisable_class instance initialized with the record
+      # found using find_revision.
+      # 
+      # The +what+ parameter is simply passed to find_revision and the
+      # returned record forms the basis of the reverted record.
+      # 
+      # ==== Callbacks
+      # 
+      # * +before_revert+ is called before the record is reverted.
+      # * +after_revert+ is called after the record is reverted.
+      # 
+      # If :without_revision => true has not been passed the 
+      # following callbacks are also called:
+      # 
+      # * +before_revise+ is called before the record is revised.
+      # * +after_revise+ is called after the record is revised.
+      def revert_to(what, *args, &block) #:yields:
+        is_reverting!
+        
+        unless run_callbacks(:before_revert) { |r, o| r == false}
+          raise ActiveRecord::RecordNotSaved
+        end
+      
+        options = args.extract_options!
+    
+        rev = find_revision(what)
+        self.reverting_to, self.reverting_from = rev, self
+        
+        unless rev.run_callbacks(:before_restore) { |r, o| r == false}
+          raise ActiveRecord::RecordNotSaved
+        end
+    
+        self.class.column_names.each do |col|
+          next unless self.class.revisable_should_clone_column? col
+          self[col] = rev[col]
+        end
+    
+        self.no_revision! if options.delete :without_revision
+        self.revisable_new_params = options
+        
+        yield(self) if block_given?
+        rev.run_callbacks(:after_restore)
+        run_callbacks(:after_revert)
+        self
+      ensure
+        is_reverting!(false)
+        clear_revisable_shared_objects!
+      end
+    
+      # Same as revert_to except it also saves the record.
+      def revert_to!(what, *args)
+        revert_to(what, *args) do
+          self.no_revision? ? save! : revise!
+        end
+      end
+      
+      # Equivalent to:
+      #   revert_to(:without_revision => true)
+      def revert_to_without_revision(*args)
+        options = args.extract_options!
+        options.update({:without_revision => true})
+        revert_to(*(args << options))
+      end
+      
+      # Equivalent to:
+      #   revert_to!(:without_revision => true)
+      def revert_to_without_revision!(*args)
+        options = args.extract_options!
+        options.update({:without_revision => true})
+        revert_to!(*(args << options))
+      end
+      
+      # Globally sets the reverting state of this record.
+      def is_reverting!(val=true) #:nodoc:
+        set_revisable_state(:reverting, val)
+      end
+      
+      # Returns true if the _record_ (not just this instance 
+      # of the record) is currently being reverted.
+      def is_reverting?
+        get_revisable_state(:reverting) || false
+      end
+      
+      # Sets whether or not to force a revision.
+      def force_revision!(val=true) #:nodoc:
+        set_revisable_state(:force_revision, val)
+      end
+      
+      # Returns true if a revision should be forced.
+      def force_revision? #:nodoc:
+        get_revisable_state(:force_revision) || false
+      end
+      
+      # Sets whether or not a revision should be created.
+      def no_revision!(val=true) #:nodoc:
+        set_revisable_state(:no_revision, val)
+      end
+      
+      # Returns true if no revision should be created.
+      def no_revision? #:nodoc:
+        get_revisable_state(:no_revision) || false
+      end
+            
+      # Force an immediate revision whether or
+      # not any columns have been modified.
+      # 
+      # The +args+ catch-all argument is not used. It's primarily
+      # there to allow +revise!+ to be used directly as an association
+      # callback since association callbacks are passed an argument.
+      # 
+      # ==== Callbacks
+      # 
+      # * +before_revise+ is called before the record is revised.
+      # * +after_revise+ is called after the record is revised.
+      def revise!(*args)
+        return if in_revision?
+        
+        begin
+          force_revision!
+          in_revision!
+          save!
+        ensure
+          in_revision!(false)
+          force_revision!(false)
+        end
+      end
+            
+      # Groups statements that could trigger several revisions into
+      # a single revision. The revision is created once #save is called.
+      # 
+      # ==== Example
+      # 
+      #   @project.revision_number # => 1
+      #   @project.changeset do |project|
+      #     # each one of the following statements would 
+      #     # normally trigger a revision
+      #     project.update_attribute(:name, "new name")
+      #     project.revise!
+      #     project.revise!
+      #   end
+      #   @project.save
+      #   @project.revision_number # => 2
+      # 
+      # ==== Callbacks
+      # 
+      # * +before_changeset+ is called before a changeset block is called.
+      # * +after_changeset+ is called after a changeset block is called.      
+      def changeset(&block)
+        return unless block_given?
+        
+        return yield(self) if in_revision?
+        
+        unless run_callbacks(:before_changeset) { |r, o| r == false}
+          raise ActiveRecord::RecordNotSaved
+        end
+        
+        begin
+          force_revision!
+          in_revision!
+        
+          returning(yield(self)) do
+            run_callbacks(:after_changeset)
+          end
+        ensure
+          in_revision!(false)       
+        end
+      end
+      
+      # Same as +changeset+ except it also saves the record.
+      def changeset!(&block)
+        changeset do
+          block.call(self)
+          save!
+        end
+      end
+      
+      def without_revisions!
+        return if in_revision? || !block_given?
+        
+        begin
+          no_revision!
+          in_revision!
+          yield
+          save!
+        ensure
+          in_revision!(false)
+          no_revision!(false)
+        end
+      end
+      
+      # acts_as_revisable's override for ActiveRecord::Base's #save!
+      def save!(*args) #:nodoc:
+        self.revisable_new_params ||= args.extract_options!
+        self.no_revision! if self.revisable_new_params.delete :without_revision
+        super
+      end
+      
+      # acts_as_revisable's override for ActiveRecord::Base's #save  
+      def save(*args) #:nodoc:
+        self.revisable_new_params ||= args.extract_options!
+        self.no_revision! if self.revisable_new_params.delete :without_revision
+        super(args)
+      end
+      
+      # Set some defaults for a newly created +Revisable+ instance.
+      def before_revisable_create #:nodoc:
+        self[:revisable_is_current] = true
+        self.revision_number ||= 0
+      end
+      
+      # Checks whether or not a +Revisable+ should be revised.
+      def should_revise? #:nodoc:
+        return false if new_record?
+        return true if force_revision?
+        return false if no_revision?
+        return false unless self.changed?
+        !(self.changed.map(&:downcase) & self.class.revisable_watch_columns).blank?
+      end
+      
+      # Checks whether or not a revision should be stored.
+      # If it should be, it initialized the revision_class
+      # and stores it in an accessor for later saving.
+      def before_revisable_update #:nodoc:
+        return unless should_revise?
+        in_revision!
+        
+        unless run_callbacks(:before_revise) { |r, o| r == false}
+          in_revision!(false)
+          return false
+        end
+        
+        self.revisable_revision = self.to_revision
+      end
+      
+      # Checks if an initialized revision_class has been stored
+      # in the accessor. If it has been, this instance is saved.
+      def after_revisable_update #:nodoc:
+        if no_revision? # check and see if no_revision! was called in a callback 
+          self.revisable_revision = nil
+          return true
+        elsif self.revisable_revision
+          if self.class.revision_class.respond_to?(:without_stamps)
+            self.class.revision_class.without_stamps do
+              self.revisable_revision.save
+            end
+          else
+            self.revisable_revision.save
+          end
+          revisions.reload
+          run_callbacks(:after_revise)
+        end
+        in_revision!(false)
+        force_revision!(false)
+        true
+      end
+      
+      # Returns true if the _record_ (not just this instance 
+      # of the record) is currently being revised.
+      def in_revision?
+        get_revisable_state(:revision)
+      end
+
+      # Manages the internal state of a +Revisable+ controlling 
+      # whether or not a record is being revised. This works across
+      # instances and is keyed on primary_key.
+      def in_revision!(val=true) #:nodoc:
+        set_revisable_state(:revision, val)
+      end
+            
+      # This returns a new +Revision+ instance with all the appropriate
+      # values initialized.
+      def to_revision #:nodoc:
+        rev = self.class.revision_class.new(self.revisable_new_params)
+
+        rev.revisable_original_id = self.id
+        
+        new_revision_number = revisions.maximum(:revisable_number) + 1 rescue self.revision_number
+        rev.revision_number = new_revision_number
+        self.revision_number = new_revision_number + 1
+        
+        self.class.column_names.each do |col|
+          next unless self.class.revisable_should_clone_column? col
+          val = self.send("#{col}_changed?") ? self.send("#{col}_was") : self.send(col)
+          rev.send("#{col}=", val)
+        end
+
+        self.revisable_new_params = nil
+
+        rev
+      end
+      
+      # This returns
+      def current_revision
+        self
+      end
+      
+      def for_revision
+        key = self.read_attribute(self.class.primary_key)
+        self.class.revisable_shared_objects[key] ||= {}
+      end
+      
+      def reverting_to
+        for_revision[:reverting_to]
+      end
+      
+      def reverting_to=(val)
+        for_revision[:reverting_to] = val
+      end
+      
+      def reverting_from
+        for_revision[:reverting_from]
+      end
+      
+      def reverting_from=(val)
+        for_revision[:reverting_from] = val
+      end
+
+      def clear_revisable_shared_objects!
+        key = self.read_attribute(self.class.primary_key)
+        self.class.revisable_shared_objects.delete(key)
+      end
+            
+      module ClassMethods
+        # acts_as_revisable's override for with_scope that allows for
+        # including revisions in the scope.
+        # 
+        # ==== Example
+        # 
+        #   with_scope(:with_revisions => true) do
+        #     ...
+        #   end
+        def with_scope(*args, &block) #:nodoc:
+          options = (args.grep(Hash).first || {})[:find]
+
+          if options && options.delete(:with_revisions)
+            with_exclusive_scope do
+              super(*args, &block)
+            end
+          else
+            super(*args, &block)
+          end
+        end
+        
+        # acts_as_revisable's override for find that allows for
+        # including revisions in the find.
+        # 
+        # ==== Example
+        # 
+        #   find(:all, :with_revisions => true)
+        def find(*args) #:nodoc:
+          options = args.grep(Hash).first
+        
+          if options && options.delete(:with_revisions)
+            with_exclusive_scope do
+              super(*args)
+            end
+          else
+            super(*args)
+          end
+        end
+              
+        # Returns the +revision_class_name+ as configured in
+        # +acts_as_revisable+.
+        def revision_class_name #:nodoc:
+          self.revisable_options.revision_class_name || "#{self.class_name}Revision"
+        end
+      
+        # Returns the actual +Revision+ class based on the 
+        # #revision_class_name.
+        def revision_class #:nodoc:
+          self.revisable_revision_class ||= self.revision_class_name.constantize
+        end
+        
+        # Returns the revisable_class which in this case is simply +self+.
+        def revisable_class #:nodoc:
+          self
+        end
+        
+        # Returns the name of the association acts_as_revisable
+        # creates.
+        def revisions_association_name #:nodoc:
+          revision_class_name.pluralize.underscore
+        end
+        
+        # Returns an Array of the columns that are watched for changes.
+        def revisable_watch_columns #:nodoc:
+          return self.revisable_columns unless self.revisable_columns.blank?
+          return self.revisable_columns ||= [] if self.revisable_options.except == :all
+          return self.revisable_columns ||= [self.revisable_options.only].flatten.map(&:to_s).map(&:downcase) unless self.revisable_options.only.blank?
+                    
+          except = [self.revisable_options.except].flatten || []
+          except += REVISABLE_SYSTEM_COLUMNS
+          except += REVISABLE_UNREVISABLE_COLUMNS
+          except.uniq!
+
+          self.revisable_columns ||= (column_names - except.map(&:to_s)).flatten.map(&:downcase)
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_revisable/acts/revision.rb

@@ -0,0 +1,149 @@
+module WithoutScope
+  module ActsAsRevisable
+    # This module is mixed into the revision classes.
+    # 
+    # ==== Callbacks
+    # 
+    # * +before_restore+ is called on the revision class before it is 
+    #   restored as the current record.
+    # * +after_restore+ is called on the revision class after it is 
+    #   restored as the current record.
+    module Revision
+      def self.included(base) #:nodoc:
+        base.send(:extend, ClassMethods)
+        
+        class << base
+          attr_accessor :revisable_revisable_class, :revisable_cloned_associations
+        end
+        
+        base.instance_eval do
+          set_table_name(revisable_class.table_name)
+          default_scope :conditions => {:revisable_is_current => false}
+                  
+          define_callbacks :before_restore, :after_restore
+          before_create :revision_setup
+          after_create :grab_my_branches
+          
+          named_scope :deleted, :conditions => ["? is not null", :revisable_deleted_at]
+          
+          [:current_revision, revisable_association_name.to_sym].each do |a|
+            belongs_to a, :class_name => revisable_class_name, :foreign_key => :revisable_original_id
+          end
+          
+          [[:ancestors, "<"], [:descendants, ">"]].each do |a|
+            # Jumping through hoops here to try and make sure the
+            # :finder_sql is cross-database compatible. :finder_sql
+            # in a plugin is evil but, I see no other option.
+            has_many a.first, :class_name => revision_class_name, :finder_sql => "select * from #{quoted_table_name} where #{quote_bound_value(:revisable_original_id)} = \#{revisable_original_id} and #{quote_bound_value(:revisable_number)} #{a.last} \#{revisable_number} and #{quote_bound_value(:revisable_is_current)} = #{quote_value(false)} order by #{quote_bound_value(:revisable_number)} #{(a.last.eql?("<") ? "DESC" : "ASC")}"
+          end
+        end
+      end
+      
+      def find_revision(*args)
+        current_revision.find_revision(*args)
+      end
+      
+      # Return the revision prior to this one.
+      def previous_revision
+        self.class.find(:first, :conditions => {:revisable_original_id => revisable_original_id, :revisable_number => revisable_number - 1})
+      end
+      
+      # Return the revision after this one.
+      def next_revision
+        self.class.find(:first, :conditions => {:revisable_original_id => revisable_original_id, :revisable_number => revisable_number + 1})
+      end
+      
+      # Setter for revisable_name just to make external API more pleasant.
+      def revision_name=(val) #:nodoc:
+        self[:revisable_name] = val
+      end
+    
+      # Accessor for revisable_name just to make external API more pleasant.
+      def revision_name #:nodoc:
+        self[:revisable_name]
+      end
+      
+      # Sets some initial values for a new revision.
+      def revision_setup #:nodoc:
+        now = Time.zone.now
+        prev = current_revision.revisions.first
+        prev.update_attribute(:revisable_revised_at, now) if prev
+        self[:revisable_current_at] = now + 1.second
+        self[:revisable_is_current] = false
+        self[:revisable_branched_from_id] = current_revision[:revisable_branched_from_id]
+        self[:revisable_type] = current_revision[:type]
+        self[:revisable_number] = (self.class.maximum(:revisable_number, :conditions => {:revisable_original_id => self[:revisable_original_id]}) || 0) + 1
+      end
+      
+      def grab_my_branches
+        self.class.revisable_class.update_all(["revisable_branched_from_id = ?", self[:id]], ["revisable_branched_from_id = ?", self[:revisable_original_id]])
+      end
+      
+      def from_revisable
+        current_revision.for_revision
+      end
+      
+      def reverting_from
+        from_revisable[:reverting_from]
+      end
+      
+      def reverting_from=(val)
+        from_revisable[:reverting_from] = val
+      end
+
+      def reverting_to
+        from_revisable[:reverting_to]
+      end
+      
+      def reverting_to=(val)
+        from_revisable[:reverting_to] = val
+      end
+
+      module ClassMethods
+        # Returns the +revisable_class_name+ as configured in
+        # +acts_as_revisable+.
+        def revisable_class_name #:nodoc:
+          self.revisable_options.revisable_class_name || self.class_name.gsub(/Revision/, '')
+        end
+      
+        # Returns the actual +Revisable+ class based on the 
+        # #revisable_class_name.
+        def revisable_class #:nodoc:
+          self.revisable_revisable_class ||= self.revisable_class_name.constantize
+        end
+        
+        # Returns the revision_class which in this case is simply +self+.
+        def revision_class #:nodoc:
+          self
+        end
+        
+        def revision_class_name #:nodoc:
+          self.name
+        end
+        
+        # Returns the name of the association acts_as_revision
+        # creates.
+        def revisable_association_name #:nodoc:
+          revisable_class_name.underscore
+        end
+        
+        # Returns an array of the associations that should be cloned.
+        def revision_cloned_associations #:nodoc:
+          clone_associations = self.revisable_options.clone_associations
+        
+          self.revisable_cloned_associations ||= if clone_associations.blank?
+            []
+          elsif clone_associations.eql? :all
+            revisable_class.reflect_on_all_associations.map(&:name)
+          elsif clone_associations.is_a? [].class
+            clone_associations
+          elsif clone_associations[:only]
+            [clone_associations[:only]].flatten
+          elsif clone_associations[:except]
+            revisable_class.reflect_on_all_associations.map(&:name) - [clone_associations[:except]].flatten
+          end        
+        end
+      end
+    end
+  end
+end

data/lib/acts_as_revisable/base.rb

@@ -0,0 +1,52 @@
+require 'acts_as_revisable/options'
+require 'acts_as_revisable/quoted_columns'
+require 'acts_as_revisable/acts/common'
+require 'acts_as_revisable/acts/revision'
+require 'acts_as_revisable/acts/revisable'
+require 'acts_as_revisable/acts/deletable'
+
+module WithoutScope
+  # define the columns used internall by AAR
+  REVISABLE_SYSTEM_COLUMNS = %w(revisable_original_id revisable_branched_from_id revisable_number revisable_name revisable_type revisable_current_at revisable_revised_at revisable_deleted_at revisable_is_current)
+  
+  # define the ActiveRecord magic columns that should not be monitored
+  REVISABLE_UNREVISABLE_COLUMNS = %w(id type created_at updated_at)
+  
+  module ActsAsRevisable
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+    
+    module ClassMethods
+      
+      # This +acts_as+ extension provides for making a model the 
+      # revisable model in an acts_as_revisable pair.
+      def acts_as_revisable(*args, &block)
+        revisable_shared_setup(args, block)
+        self.send(:include, Revisable)
+        self.send(:include, Deletable) if self.revisable_options.on_delete == :revise
+      end
+      
+      # This +acts_as+ extension provides for making a model the 
+      # revision model in an acts_as_revisable pair.
+      def acts_as_revision(*args, &block)
+        revisable_shared_setup(args, block)
+        self.send(:include, Revision)        
+      end
+      
+      private
+        # Performs the setup needed for both kinds of acts_as_revisable
+        # models.
+        def revisable_shared_setup(args, block)
+          class << self
+            attr_accessor :revisable_options
+          end
+          options = args.extract_options!
+          self.revisable_options = Options.new(options, &block)
+          
+          self.send(:include, Common)
+          self.send(:include, WithoutScope::QuotedColumnConditions)
+        end
+    end
+  end
+end