acts_as_revisable 1.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 JamLab, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,221 @@
+= acts_as_revisable
+
+http://github.com/rich/acts_as_revisable
+
+== DESCRIPTION:
+
+acts_as_revisable enables revision tracking, querying, reverting and branching of ActiveRecord models. It does this while providing more Rails-like API than similar plugins. This includes extensions of standard ActiveRecord methods and numerous custom callbacks for the entire AAR life-cycle.
+
+This plugin wouldn't exist without Rick Olsen's acts_as_versioned. AAV has been a critical part of practically every Rails project I've developed. It's only through extensive usage of AAV that the concepts for AAR came about.
+
+== FEATURES:
+
+* Both the revisable and revision models must be explicitly defined.
+  Yes, this is a feature. The less magic needed the better. This allows you to build up your revision models just as you would any other. 
+  
+  If you absolutely need a generated revision model, you may pass ":generate_revision_class => true" to acts_as_revisable and it will generate the class at runtime for you. Think of this like scaffolding and not to be kept around for a real application.
+
+* Numerous custom callbacks for both revisable and revision models.
+  * revisable models
+    * before_revise
+    * after_revise
+    * before_revert
+    * after_revert
+    * before_changeset
+    * after_changeset
+    * after_branch_created
+    * before_revise_on_destroy (when :on_destroy => :revise is set)
+    * after_revise_on_destroy (when :on_destroy => :revise is set)
+  * revision models
+    * before_restore
+    * after_restore
+  * both revisable and revision models
+    * before_branch
+    * after_branch
+  These work like any other ActiveRecord callbacks. The before_* callbacks can stop the the action. This uses the Callbacks module in ActiveSupport.
+* Works with a single table.
+  * Provides migration generators to add the revisable columns.
+* Grouping several revisable actions into a single revision (changeset).
+* Monitor all or just specified columns to trigger a revision.
+* Uses ActiveRecord's dirty attribute tracking.
+* Several ways to find revisions including:
+  * revision number
+  * relative keywords (:first, :previous and :last)
+  * timestamp
+* Reverting
+* Branching
+* Selectively disable revision tracking
+* Naming revisions  
+
+== SYNOPSIS:
+
+Given a simple model:
+
+  class Project < ActiveRecord::Base
+    # columns: id, name, unimportant, created_at
+  end
+
+Let's make the projects table revisable:
+
+  ruby script/generate revisable_migration Project
+  rake db:migrate
+
+Now Project itself:
+  
+  class Project < ActiveRecord::Base
+    has_one :owner
+    
+    acts_as_revisable do
+      revision_class_name "Session"
+      except :unimportant
+    end
+  end
+
+Create the revision class:
+
+  class Session < ActiveRecord::Base
+    # we can accept the more standard hash syntax
+    acts_as_revision :revisable_class_name => "Project"
+  end
+
+Some example usage:
+
+  @project = Project.create(:name => "Rich", :unimportant => "some text")
+  @project.revision_number        # => 0
+
+  @project.update_attribute(:unimportant, "more text")
+  @project.revision_number        # => 0
+  
+  @project.name = "Stephen"
+  @project.save(:without_revision => true)
+  @project.name                   # => "Stephen"
+  @project.revision_number        # => 0
+  
+  @project.name = "Sam"
+  @project.save(:revision_name => "Changed name")
+  @project.revision_number        # => 1
+  
+  @project.updated_attribute(:name, "Third")
+  @project.revision_number        # => 2
+  
+Navigating revisions:
+  
+  @previous = @project.find_revision(:previous)
+  # or
+  @previous = @project.revisions.first
+  
+  @previous.name                  # => "Sam"
+  @previous.current_revision.name # => "Third"
+  @previous.project.name          # => "Third"
+  @previous.revision_name         # => "Changed name"
+  
+  @previous.previous.name         # => "Rich"
+  
+  # Forcing the creation of a new revision.
+  @project.updated_attribute("Rogelio")
+  @project.revision_number        # => 3
+  
+  @newest = @project.find_revision(:previous)
+  @newest.ancestors.map(&:name)   # => ["Third", "Rich"]
+  
+  @oldest = @project.find_revision(:first)
+  @oldest.descendants.map(&:name) # => ["Sam", "Third"]
+  
+Reverting:
+
+  @project.revert_to!(:previous)
+  @project.revision_number        # => 2
+  @project.name                   # => "Rich"
+  
+  @project.revert_to!(1, :without_revision => true)
+  @project.revision_number        # => 2
+  @project.name                   # => "Sam"
+
+Branching:
+  
+  @branch = @project.branch(:name => "Bruno")
+  @branch.revision_number         # => 0
+  @branch.branch_source.name      # => "Sam"
+
+Changesets:
+  
+  @project.revision_number        # => 2
+  
+  @project.changeset! do 
+    @project.name = "Josh"
+    
+    # save would normally trigger a revision
+    @project.save
+    
+    # update_attribute triggers a save triggering a revision (normally)
+    @project.updated_attribute(:name, "Chris")
+    
+    # revise! normally forces a revision to be created
+    @project.revise!
+  end
+  
+  # our revision number has only incremented by one
+  @project.revision_number        # => 3
+  
+Maybe we don't want to be able to branch from revisions:
+
+  class Session < ActiveRecord::Base
+    # assuming we still have the other code from Session above
+    
+    before_branch do
+      false
+    end
+  end
+  
+  @project.revisions.first.branch # Raises an exception
+  @project.branch                 # works as expected
+  
+If the owner isn't set let's prevent reverting:
+
+  class Project < ActiveRecord::Base
+    # assuming we still have the other code from Project above
+    
+    before_revert :check_owner_befor_reverting
+    def check_owner_befor_reverting
+      false unless self.owner?
+    end
+  end
+
+== REQUIREMENTS:
+
+This plugin requires Rails 2.3. Use version 0.9.8 of this plugin for Rails 2.1 and 2.2.
+
+== INSTALL:
+
+acts_as_revisable uses Rails' new ability to use gems as plugins. Installing AAR is as simple as installing a gem:
+
+  sudo gem install rich-acts_as_revisable --source=http://gems.github.com
+
+Once the gem is installed you'll want to activate it in your Rails app by adding the following line to config/environment.rb:
+
+  config.gem "rich-acts_as_revisable", :lib => "acts_as_revisable", :source => "http://gems.github.com"
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Rich Cavanaugh
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,44 @@
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'fileutils'
+require "#{File.dirname(__FILE__)}/lib/acts_as_revisable/version"
+require "#{File.dirname(__FILE__)}/lib/acts_as_revisable/gem_spec_options"
+
+Rake::RDocTask.new do |rdoc|
+  files = ['README.rdoc','LICENSE','lib/**/*.rb','doc/**/*.rdoc','spec/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = 'README.rdoc'
+  rdoc.title = 'acts_as_revisable RDoc'
+  rdoc.rdoc_dir = 'doc'
+  rdoc.options << '--line-numbers' << '--inline-source'
+end
+
+spec = Gem::Specification.new do |s|
+  WithoutScope::ActsAsRevisable::GemSpecOptions::HASH.each do |key, value|
+    s.send("#{key.to_s}=",value)
+  end
+end
+
+Rake::GemPackageTask.new(spec) do |package|
+  package.gem_spec = spec
+end
+
+desc "Generate the static gemspec required for github."
+task :generate_gemspec do
+  options = WithoutScope::ActsAsRevisable::GemSpecOptions::HASH.clone
+  options[:name] = "acts_as_revisable"
+  
+  spec = ["Gem::Specification.new do |s|"]
+  options.each do |key, value|
+    spec << "  s.#{key.to_s} = #{value.inspect}"
+  end
+  spec << "end"
+  
+  open("acts_as_revisable.gemspec", "w").write(spec.join("\n"))
+end
+
+desc "Install acts_as_revisable"
+task :install => :repackage do
+    options = WithoutScope::ActsAsRevisable::GemSpecOptions::HASH.clone
+    sh %{sudo gem install pkg/#{options[:name]}-#{spec.version} --no-rdoc --no-ri}
+end

data/generators/revisable_migration/revisable_migration_generator.rb

@@ -0,0 +1,21 @@
+class RevisableMigrationGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      revisable_columns = [
+        ["revisable_original_id",      "integer"],
+        ["revisable_branched_from_id", "integer"],
+        ["revisable_number",           "integer", 0],
+        ["revisable_name",             "string"],
+        ["revisable_type",             "string"],
+        ["revisable_current_at",       "datetime"],
+        ["revisable_revised_at",       "datetime"],
+        ["revisable_deleted_at",       "datetime"],
+        ["revisable_is_current",       "boolean", 1]
+      ]
+      
+      m.migration_template 'migration.rb', 'db/migrate',
+        :migration_file_name => "make_#{class_name.underscore.pluralize}_revisable",
+        :assigns => { :cols => revisable_columns }
+    end
+  end
+end

data/generators/revisable_migration/templates/migration.rb

@@ -0,0 +1,14 @@
+<% table_name = class_name.underscore.pluralize -%>
+class Make<%= class_name.underscore.pluralize.camelize %>Revisable < ActiveRecord::Migration
+  def self.up
+    <% cols.each do |column_name,column_type,default| -%>
+    add_column :<%= table_name %>, :<%= column_name %>, :<%= column_type %><%= ", :default => #{default}" unless default.blank? %>
+    <% end -%>
+  end
+
+  def self.down
+    <% cols.each do |column_name,_| -%>
+    remove_column :<%= table_name %>, :<%= column_name %>
+    <% end -%>
+  end
+end

data/lib/acts_as_revisable.rb

@@ -0,0 +1,10 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'activesupport' unless defined? ActiveSupport
+require 'activerecord' unless defined? ActiveRecord
+
+require 'acts_as_revisable/version.rb'
+require 'acts_as_revisable/base'
+
+ActiveRecord::Base.send(:include, WithoutScope::ActsAsRevisable)

data/lib/acts_as_revisable/acts/common.rb

@@ -0,0 +1,209 @@
+module WithoutScope
+  module ActsAsRevisable
+    # This module is mixed into the revision and revisable classes.
+    # 
+    # ==== Callbacks
+    # 
+    # * +before_branch+ is called on the +Revisable+ or +Revision+ that is 
+    #   being branched
+    # * +after_branch+ is called on the +Revisable+ or +Revision+ that is 
+    #   being branched
+    module Common
+      def self.included(base) #:nodoc:
+        base.send(:extend, ClassMethods)
+        
+        base.class_inheritable_hash :revisable_after_callback_blocks
+        base.revisable_after_callback_blocks = {}
+        
+        base.class_inheritable_hash :revisable_current_states
+        base.revisable_current_states = {}
+        
+        base.instance_eval do
+          define_callbacks :before_branch, :after_branch      
+          has_many :branches, (revisable_options.revision_association_options || {}).merge({:class_name => base.name, :foreign_key => :revisable_branched_from_id})
+                    
+          belongs_to :branch_source, :class_name => base.name, :foreign_key => :revisable_branched_from_id
+          after_save :execute_blocks_after_save
+        end        
+      end
+            
+      # Executes the blocks stored in an accessor after a save.
+      def execute_blocks_after_save #:nodoc:
+        return unless revisable_after_callback_blocks[:save]
+        revisable_after_callback_blocks[:save].each do |block|
+          block.call
+        end
+        revisable_after_callback_blocks.delete(:save)
+      end
+      
+      # Stores a block for later execution after a given callback.
+      # The parameter +key+ is the callback the block should be 
+      # executed after.
+      def execute_after(key, &block) #:nodoc:
+        return unless block_given?
+        revisable_after_callback_blocks[key] ||= []
+        revisable_after_callback_blocks[key] << block
+      end
+            
+      # Branch the +Revisable+ or +Revision+ and return the new 
+      # +revisable+ instance. The instance has not been saved yet.
+      # 
+      # ==== Callbacks
+      # * +before_branch+ is called on the +Revisable+ or +Revision+ that is 
+      #   being branched
+      # * +after_branch+ is called on the +Revisable+ or +Revision+ that is 
+      #   being branched
+      # * +after_branch_created+ is called on the newly created 
+      #   +Revisable+ instance.
+      def branch(*args, &block)
+        is_branching!
+        
+        unless run_callbacks(:before_branch) { |r, o| r == false}
+          raise ActiveRecord::RecordNotSaved
+        end
+
+        options = args.extract_options!
+        options[:revisable_branched_from_id] = self.id
+        self.class.column_names.each do |col|
+          next unless self.class.revisable_should_clone_column? col
+          options[col.to_sym] = self[col] unless options.has_key?(col.to_sym)
+        end
+        
+        br = self.class.revisable_class.new(options)
+        br.is_branching!
+        
+        br.execute_after(:save) do
+          begin
+            run_callbacks(:after_branch)
+            br.run_callbacks(:after_branch_created)
+          ensure
+            br.is_branching!(false)
+            is_branching!(false)
+          end
+        end
+        
+        block.call(br) if block_given?
+        
+        br
+      end
+      
+      # Same as #branch except it calls #save! on the new +Revisable+ instance.
+      def branch!(*args)
+        branch(*args) do |br|
+          br.save!
+        end
+      end
+      
+      # Globally sets the reverting state of this record.
+      def is_branching!(value=true) #:nodoc:
+        set_revisable_state(:branching, value)
+      end
+      
+      # Returns true if the _record_ (not just this instance 
+      # of the record) is currently being branched.
+      def is_branching?
+        get_revisable_state(:branching)
+      end
+      
+      # When called on a +Revision+ it returns the original id. When
+      # called on a +Revisable+ it returns the id.
+      def original_id
+        self[:revisable_original_id] || self[:id]
+      end
+      
+      # Globally sets the state for a given record. This is keyed
+      # on the primary_key of a saved record or the object_id
+      # on a new instance.
+      def set_revisable_state(type, value) #:nodoc:
+        key = self.read_attribute(self.class.primary_key)
+        key = object_id if key.nil?
+        revisable_current_states[type] ||= {}
+        revisable_current_states[type][key] = value
+        revisable_current_states[type].delete(key) unless value
+      end
+      
+      # Returns the state of the given record.
+      def get_revisable_state(type) #:nodoc:
+        key = self.read_attribute(self.class.primary_key)
+        revisable_current_states[type] ||= {}
+        revisable_current_states[type][key] || revisable_current_states[type][object_id] || false
+      end
+      
+      # Returns true if the instance is the first revision.
+      def first_revision?
+        self.revision_number == 1
+      end
+      
+      # Returns true if the instance is the most recent revision.
+      def latest_revision?
+        self.revision_number == self.current_revision.revision_number
+      end
+      
+      # Returns true if the instance is the current record and not a revision.
+      def current_revision?
+        self.is_a? self.class.revisable_class
+      end
+      
+      # Accessor for revisable_number just to make external API more pleasant.
+      def revision_number
+        self[:revisable_number] ||= 0
+      end
+      
+      def revision_number=(value)
+        self[:revisable_number] = value
+      end
+      
+      def diffs(what)
+        what = current_revision.find_revision(what)
+        returning({}) do |changes|
+          self.class.revisable_class.revisable_watch_columns.each do |c|
+            changes[c] = [self[c], what[c]] unless self[c] == what[c]
+          end
+        end
+      end
+      
+      def deleted?
+        self.revisable_deleted_at.present?
+      end
+      
+      module ClassMethods        
+        # Returns true if the revision should clone the given column.    
+        def revisable_should_clone_column?(col) #:nodoc:
+          return false if (REVISABLE_SYSTEM_COLUMNS + REVISABLE_UNREVISABLE_COLUMNS).member? col
+          true
+        end
+        
+        # acts_as_revisable's override for instantiate so we can
+        # return the appropriate type of model based on whether
+        # or not the record is the current record.
+        def instantiate(record) #:nodoc:
+          is_current = columns_hash["revisable_is_current"].type_cast(
+                record["revisable_is_current"])
+
+          if (is_current && self == self.revisable_class) || (!is_current && self == self.revision_class)
+            return super(record)
+          end
+
+          object = if is_current
+            self.revisable_class
+          else
+            self.revision_class
+          end.allocate
+
+          object.instance_variable_set("@attributes", record)
+          object.instance_variable_set("@attributes_cache", Hash.new)
+
+          if object.respond_to_without_attributes?(:after_find)
+            object.send(:callback, :after_find)
+          end
+
+          if object.respond_to_without_attributes?(:after_initialize)
+            object.send(:callback, :after_initialize)
+          end
+
+          object      
+        end
+      end
+    end
+  end
+end