paper_trail 1.5.1 → 1.5.2

data/README.md

@@ -25,7 +25,7 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 
 ## Rails Version
 
-Known to work on Rails 2.3.  Probably works on Rails 2.2 and 2.1.
+Reported to work on Rails 3 (though I haven't yet tried myself).  Known to work on Rails 2.3.  Probably works on Rails 2.2 and 2.1.
 
 
 ## Basic Usage
@@ -192,6 +192,25 @@ In a migration or in `script/console` you can set who is responsible like this:
     >> widget.update_attributes :name => 'Wibble'
     >> widget.versions.last.whodunnit              # Andy Stewart
 
+N.B. A `version`'s `whodunnit` records who changed the object causing the `version` to be stored.  Because a `version` stores the object as it looked before the change (see the table above), `whodunnit` returns who stopped the object looking like this -- not who made it look like this.  Hence `whodunnit` is aliased as `terminator`.
+
+To find out who made a `version`'s object look that way, use `version.originator`.  And to find out who made a "live" object look like it does, use `originator` on the object.
+
+    >> widget = Widget.find 153                    # assume widget has 0 versions
+    >> PaperTrail.whodunnit = 'Alice'
+    >> widget.update_attributes :name => 'Yankee'
+    >> widget.originator                           # 'Alice'
+    >> PaperTrail.whodunnit = 'Bob'
+    >> widget.update_attributes :name => 'Zulu'
+    >> widget.originator                           # 'Bob'
+    >> first_version, last_version = widget.versions.first, widget.versions.last
+    >> first_version.whodunnit                     # 'Alice'
+    >> first_version.originator                    # nil
+    >> first_version.terminator                    # 'Alice'
+    >> last_version.whodunnit                      # 'Bob'
+    >> last_version.originator                     # 'Alice'
+    >> last_version.terminator                     # 'Bob'
+
 
 ## Storing metadata
 
@@ -220,6 +239,26 @@ You can also store any information you like from your controller.  Just override
 Remember to add those extra columns to your `versions` table ;)
 
 
+## Diffing Versions
+
+When you're storing every version of an object, as PaperTrail lets you do, you're almost certainly going to want to diff those versions against each other.  However I haven't built a diff method into PaperTrail because I think diffing is best left to dedicated libraries, and also it's hard to come up with a diff method to suit all the use cases.
+
+You might be surprised that PaperTrail doesn't use diffs internally anyway.  When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained.  A version stores all of its object's data, not a diff from the previous version.
+
+So instead here are some specialised diffing libraries which you can use on top of PaperTrail.
+
+For diffing two strings:
+
+* [htmldiff](http://github.com/myobie/htmldiff): expects but doesn't require HTML input and produces HTML output.  Works very well but slows down significantly on large (e.g. 5,000 word) inputs.
+* [differ](http://github.com/pvande/differ): expects plain text input and produces plain text/coloured/HTML/any output.  Can do character-wise, word-wise, line-wise, or arbitrary-boundary-string-wise diffs.  Works very well on non-HTML input.
+* [diff-lcs](http://github.com/halostatue/ruwiki/tree/master/diff-lcs/trunk): old-school, line-wise diffs.
+
+For diffing two ActiveRecord objects:
+
+* [Jeremy Weiskotten's PaperTrail fork](http://github.com/jeremyw/paper_trail/blob/master/lib/paper_trail/has_paper_trail.rb#L151-156): uses ActiveSupport's diff to return an array of hashes of the changes.
+* [activerecord-diff](http://github.com/tim/activerecord-diff): rather like ActiveRecord::Dirty but also allows you to specify which columns to compare.
+
+
 ## Turning PaperTrail Off/On
 
 Sometimes you don't want to store changes.  Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration -- or when testing your application.
@@ -265,6 +304,15 @@ And then use it in your tests like this:
     end
 
 
+## Deleting Old Versions
+
+Over time your `versions` table will grow to an unwieldy size.  Because each version is self-contained (see the Diffing section above for more) you can simply delete any records you don't want any more.  For example:
+
+    sql> delete from versions where created_at < 2010-06-01;
+
+    >> Version.delete_all ["created_at < ?", 1.week.ago]
+
+
 ## Installation
 
 1. Install PaperTrail as a gem via your `config/environment.rb`:

data/VERSION

@@ -1 +1 @@
-1.5.1
+1.5.2

data/lib/paper_trail/has_paper_trail.rb

@@ -78,6 +78,11 @@ module PaperTrail
         end
       end
 
+      # Returns who put the object into its current state.
+      def originator
+        versions.last.try :whodunnit
+      end
+
       # Returns the object (not a Version) as it was at the given timestamp.
       def version_at(timestamp)
         # Short-circuit if the current state is applicable.
@@ -87,13 +92,13 @@ module PaperTrail
         # change.
         version = versions.first :conditions => ['created_at > ?', timestamp],
                                  :order      => 'created_at ASC'
-        version.reify if version
+        version.try :reify
       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
+        last_version.try :reify
       end
 
       # Returns the object (not a Version) as it became next.

data/lib/paper_trail/version.rb

@@ -40,6 +40,17 @@ class Version < ActiveRecord::Base
     end
   end
 
+  # Returns who put the item into the state stored in this version.
+  def originator
+    previous.try :whodunnit
+  end
+
+  # Returns who changed the item from the state it had in this version.
+  # This is an alias for `whodunnit`.
+  def terminator
+    whodunnit
+  end
+
   def next
     Version.first :conditions => ["id > ? AND item_type = ? AND item_id = ?", id, item_type, item_id],
                   :order => 'id ASC'
@@ -54,5 +65,5 @@ class Version < ActiveRecord::Base
     Version.all(:conditions => ["item_type = ? AND item_id = ?", item_type, item_id],
                 :order => 'id ASC').index(self)
   end
-  
+
 end

data/paper_trail.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{paper_trail}
-  s.version = "1.5.1"
+  s.version = "1.5.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andy Stewart"]
-  s.date = %q{2010-06-22}
+  s.date = %q{2010-06-28}
   s.email = %q{boss@airbladesoftware.com}
   s.extra_rdoc_files = [
     "README.md"

data/test/paper_trail_model_test.rb

@@ -310,29 +310,49 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
 
   context 'A papertrail with somebody making changes' do
     setup do
-      PaperTrail.whodunnit = 'Colonel Mustard'
       @widget = Widget.new :name => 'Fidget'
     end
 
     context 'when a record is created' do
-      setup { @widget.save }
+      setup do
+        PaperTrail.whodunnit = 'Alice'
+        @widget.save
+        @version = @widget.versions.last  # only 1 version
+      end
 
       should 'track who made the change' do
-        assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+        assert_equal 'Alice', @version.whodunnit
+        assert_nil   @version.originator
+        assert_equal 'Alice', @version.terminator
+        assert_equal 'Alice', @widget.originator
       end
 
       context 'when a record is updated' do
-        setup { @widget.update_attributes :name => 'Rivet' }
+        setup do
+          PaperTrail.whodunnit = 'Bob'
+          @widget.update_attributes :name => 'Rivet'
+          @version = @widget.versions.last
+        end
 
         should 'track who made the change' do
-          assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+          assert_equal 'Bob',   @version.whodunnit
+          assert_equal 'Alice', @version.originator
+          assert_equal 'Bob',   @version.terminator
+          assert_equal 'Bob',   @widget.originator
         end
 
         context 'when a record is destroyed' do
-          setup { @widget.destroy }
+          setup do
+            PaperTrail.whodunnit = 'Charlie'
+            @widget.destroy
+            @version = @widget.versions.last
+          end
 
           should 'track who made the change' do
-            assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+            assert_equal 'Charlie', @version.whodunnit
+            assert_equal 'Bob',     @version.originator
+            assert_equal 'Charlie', @version.terminator
+            assert_equal 'Charlie', @widget.originator
           end
         end
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 1
+  hash: 7
   prerelease: false
   segments: 
   - 1
   - 5
-  - 1
-  version: 1.5.1
+  - 2
+  version: 1.5.2
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-22 00:00:00 +01:00
+date: 2010-06-28 00:00:00 +01:00
 default_executable: 
 dependencies: []