paper_trail 1.5.0 → 1.5.1

data/README.md

@@ -140,6 +140,37 @@ Undeleting is just as simple:
 In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.
 
 
+## Navigating Versions
+
+You can call `previous_version` and `next_version` on an item to get it as it was/became.  Note that these methods reify the item for you.
+
+    >> widget = Widget.find 42
+    >> widget.versions.length              # 4 for example
+    >> widget = widget.previous_version    # => widget == widget.versions.last.reify
+    >> widget = widget.previous_version    # => widget == widget.versions[-2].reify
+    >> widget.next_version                 # => widget == widget.versions.last.reify
+    >> widget.next_version                 # nil
+
+As an aside, I'm undecided about whether `widget.versions.last.next_version` should return `nil` or `self` (i.e. `widget`).  Let me know if you have a view.
+
+If instead you have a particular `version` of an item you can navigate to the previous and next versions.
+
+    >> widget = Widget.find 42
+    >> version = widget.versions[-2]    # assuming widget has several versions
+    >> previous = version.previous
+    >> next = version.next
+
+You can find out which of an item's versions yours is:
+
+    >> current_version_number = version.index    # 0-based
+
+Finally, if you got an item by reifying one of its versions, you can navigate back to the version it came from:
+
+    >> latest_version = Widget.find(42).versions.last
+    >> widget = latest_version.reify
+    >> widget.version == latest_version    # true
+
+
 ## Finding Out Who Was Responsible For A Change
 
 If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the `version`'s `whodunnit` column.  Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:

data/VERSION

@@ -1 +1 @@
-1.5.0
+1.5.1

data/lib/paper_trail.rb

@@ -1,3 +1,4 @@
+require 'singleton'
 require 'yaml'
 require 'paper_trail/config'
 require 'paper_trail/controller'

data/lib/paper_trail/has_paper_trail.rb

@@ -3,11 +3,13 @@ module PaperTrail
 
     def self.included(base)
       base.send :extend, ClassMethods
+
+      # The version this instance was reified from.
+      attr_accessor :version
     end
 
 
     module ClassMethods
-
       # Declare this in your model to track every create, update, and destroy.  Each version of
       # the model is available in the `versions` association.
       #
@@ -18,6 +20,8 @@ module PaperTrail
       #            trail).  See `PaperTrail::Controller.info_for_paper_trail` for how to store data from
       #            the controller.
       def has_paper_trail(options = {})
+        # Lazily include the instance methods so we don't clutter up
+        # any more ActiveRecord models than we have to.
         send :include, InstanceMethods
 
         cattr_accessor :ignore
@@ -49,7 +53,8 @@ module PaperTrail
       end
     end
 
-
+    # Wrap the following methods in a module so we can include them only in the
+    # ActiveRecord models that declare `has_paper_trail`.
     module InstanceMethods
       def record_create
         if switched_on?
@@ -60,7 +65,7 @@ module PaperTrail
       def record_update
         if switched_on? && changed_and_we_care?
           versions.build merge_metadata(:event     => 'update',
-                                        :object    => object_to_string(previous_version),
+                                        :object    => object_to_string(item_before_change),
                                         :whodunnit => PaperTrail.whodunnit)
         end
       end
@@ -68,7 +73,7 @@ module PaperTrail
       def record_destroy
         if switched_on?
           versions.create merge_metadata(:event     => 'destroy',
-                                         :object    => object_to_string(previous_version),
+                                         :object    => object_to_string(item_before_change),
                                          :whodunnit => PaperTrail.whodunnit)
         end
       end
@@ -81,10 +86,24 @@ module PaperTrail
         # timestamp because a version stores how the object looked before the
         # change.
         version = versions.first :conditions => ['created_at > ?', timestamp],
-          :order      => 'created_at ASC'
+                                 :order      => 'created_at ASC'
         version.reify if version
       end
 
+      # Returns the object (not a Version) as it was most recently.
+      def previous_version
+        last_version = version ? version.previous : versions.last
+        last_version.reify if last_version
+      end
+
+      # Returns the object (not a Version) as it became next.
+      def next_version
+        # NOTE: if self (the item) was not reified from a version, i.e. it is the
+        # "live" item, we return nil.  Perhaps we should return self instead?
+        subsequent_version = version ? version.next : nil
+        subsequent_version.reify if subsequent_version
+      end
+
       private
 
       def merge_metadata(data)
@@ -96,7 +115,7 @@ module PaperTrail
         data.merge(PaperTrail.controller_info || {})
       end
 
-      def previous_version
+      def item_before_change
         previous = self.clone
         previous.id = id
         changes.each do |attr, ary|

data/lib/paper_trail/version.rb

@@ -4,8 +4,6 @@ class Version < ActiveRecord::Base
 
   def reify
     unless object.nil?
-      # Attributes
-
       attrs = YAML::load object
 
       # Normally a polymorphic belongs_to relationship allows us
@@ -37,6 +35,7 @@ class Version < ActiveRecord::Base
         end
       end
 
+      model.version = self
       model
     end
   end

data/paper_trail.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{paper_trail}
-  s.version = "1.5.0"
+  s.version = "1.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andy Stewart"]
-  s.date = %q{2010-03-19}
+  s.date = %q{2010-06-22}
   s.email = %q{boss@airbladesoftware.com}
   s.extra_rdoc_files = [
     "README.md"
@@ -44,7 +44,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://github.com/airblade/paper_trail}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
+  s.rubygems_version = %q{1.3.7}
   s.summary = %q{Track changes to your models' data.  Good for auditing or versioning.}
   s.test_files = [
     "test/paper_trail_controller_test.rb",
@@ -60,7 +60,7 @@ Gem::Specification.new do |s|
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
     else
     end
   else

data/test/paper_trail_model_test.rb

@@ -481,7 +481,7 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
       end
 
 
-      context 'and destroyd' do
+      context 'and destroyed' do
         setup { @article.destroy }
 
         should 'store fixed meta data' do
@@ -500,5 +500,71 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     end
   end
 
+  context 'A reified item' do
+    setup do
+      widget = Widget.create :name => 'Bob'
+      %w( Tom Dick Jane ).each { |name| widget.update_attributes :name => name }
+      @version = widget.versions.last
+      @widget = @version.reify
+    end
+
+    should 'know which version it came from' do
+      assert_equal @version, @widget.version
+    end
+
+    should 'return its previous self' do
+      assert_equal @widget.versions[-2].reify, @widget.previous_version
+    end
+
+  end
+
+
+  context 'A non-reified item' do
+    setup { @widget = Widget.new }
+
+    should 'not have a previous version' do
+      assert_nil @widget.previous_version
+    end
+
+    should 'not have a next version' do
+      assert_nil @widget.next_version
+    end
+
+    context 'with versions' do
+      setup do
+        @widget.save
+        %w( Tom Dick Jane ).each { |name| @widget.update_attributes :name => name }
+      end
+
+      should 'have a previous version' do
+        assert_equal @widget.versions.last.reify, @widget.previous_version
+      end
+
+      should 'have a next version' do
+        assert_nil @widget.next_version
+      end
+    end
+  end
+
+  context 'A reified item' do
+    setup do
+      widget = Widget.create :name => 'Bob'
+      %w( Tom Dick Jane ).each { |name| widget.update_attributes :name => name }
+      @versions      = widget.versions
+      @second_widget = @versions[1].reify  # first widget is null
+      @last_widget   = @versions.last.reify
+    end
+
+    should 'have a previous version' do
+      assert_nil @second_widget.previous_version
+      assert_equal @versions[-2].reify, @last_widget.previous_version
+    end
+
+    should 'have a next version' do
+      assert_equal @versions[2].reify, @second_widget.next_version
+      assert_nil @last_widget.next_version
+    end
+  end
+
 
 end

data/test/schema.rb

@@ -45,8 +45,8 @@ ActiveRecord::Schema.define(:version => 0) do
   end
 
   create_table :articles, :force => true do |t|
-    t.integer :title
-    t.string  :content
+    t.string :title
+    t.string :content
   end
 
 end

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  version: 1.5.0
+  hash: 1
+  prerelease: false
+  segments: 
+  - 1
+  - 5
+  - 1
+  version: 1.5.1
 platform: ruby
 authors: 
 - Andy Stewart
@@ -9,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-03-19 00:00:00 +00:00
+date: 2010-06-22 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -57,21 +63,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Track changes to your models' data.  Good for auditing or versioning.