paper_trail 1.2.13

data/.gitignore

@@ -0,0 +1,2 @@
+test/debug.log
+test/paper_trail_plugin.sqlite3.db

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Andy Stewart, AirBlade Software Ltd.
+
+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.md

@@ -0,0 +1,180 @@
+# PaperTrail
+
+PaperTrail lets you track changes to your models' data.  It's good for auditing or versioning.  You can see how a model looked at any stage in its lifecycle, revert it to any version, and even undelete it after it's been destroyed.
+
+
+## Features
+
+* Stores every create, update and destroy.
+* Does not store updates which don't change anything.
+* Allows you to get at every version, including the original, even once destroyed.
+* Allows you to get at every version even if the schema has since changed.
+* Automatically records who was responsible if your controller has a `current_user` method.
+* Allows you to set who is responsible at model-level (useful for migrations).
+* Can be turned off/on (useful for migrations).
+* No configuration necessary.
+* Stores everything in a single database table (generates migration for you).
+* Thoroughly tested.
+
+
+## Rails Version
+
+Known to work on Rails 2.3.  Probably works on Rails 2.2 and 2.1.
+
+
+## Basic Usage
+
+PaperTrail is simple to use.  Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
+
+    class Widget < ActiveRecord::Base
+      has_paper_trail
+    end
+
+This gives you a `versions` method which returns the paper trail of changes to your model.
+
+    >> widget = Widget.find 42
+    >> widget.versions             # [<Version>, <Version>, ...]
+
+Once you have a version, you can find out what happened:
+
+    >> v = widget.versions.last
+    >> v.event                     # 'update' (or 'create' or 'destroy')
+    >> v.whodunnit                 # '153'  (if the update was via a controller and
+                                   #         the controller has a current_user method,
+                                   #         here returning the id of the current user)
+    >> v.created_at                # when the update occurred
+    >> widget = v.reify            # the widget as it was before the update;
+                                   # would be nil for a create event
+
+PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version.  This is useful when you start keeping a paper trail for models that already have records in the database.
+
+    >> widget = Widget.find 153
+    >> widget.name                                 # 'Doobly'
+
+    # Add has_paper_trail to Widget model.
+
+    >> widget.versions                             # []
+    >> widget.update_attributes :name => 'Wotsit'
+    >> widget.versions.first.reify.name            # 'Doobly'
+    >> widget.versions.first.event                 # 'update'
+
+This also means that PaperTrail does not waste space storing a version of the object as it currently stands.  The `versions` method gives you previous versions; to get the current one just call a finder on your `Widget` model as usual.
+
+Here's a helpful table showing what PaperTrail stores:
+
+<table>
+  <tr>
+    <th>Event</th>
+    <th>Model Before</th>
+    <th>Model After</th>
+  </tr>
+  <tr>
+    <td>create</td>
+    <td>nil</td>
+    <td>widget</td>
+  </tr>
+  <tr>
+    <td>update</td>
+    <td>widget</td>
+    <td>widget'</td>
+  <tr>
+    <td>destroy</td>
+    <td>widget</td>
+    <td>nil</td>
+  </tr>
+</table>
+
+PaperTrail stores the values in the Model Before column.  Most other auditing/versioning plugins store the After column.
+
+
+## Reverting And Undeleting A Model
+
+PaperTrail makes reverting to a previous version easy:
+
+    >> widget = Widget.find 42
+    >> widget.update_attributes :name => 'Blah blah'
+    # Time passes....
+    >> widget = widget.versions.last.reify  # the widget as it was before the update
+    >> widget.save                          # reverted
+
+Undeleting is just as simple:
+
+    >> widget = Widget.find 42
+    >> widget.destroy
+    # Time passes....
+    >> widget = Version.find(153).reify    # the widget as it was before it was destroyed
+    >> widget.save                         # the widget lives!
+
+In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.
+
+
+## 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:
+
+    >> last_change = Widget.versions.last
+    >> user_who_made_the_change = User.find last_change.whodunnit.to_i
+
+In a migration or in `script/console` you can set who is responsible like this:
+
+    >> PaperTrail.whodunnit = 'Andy Stewart'
+    >> widget.update_attributes :name => 'Wibble'
+    >> widget.versions.last.whodunnit              # Andy Stewart
+
+
+## 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.
+
+If you are about change some widgets and you don't want a paper trail of your changes, you can
+turn PaperTrail off like this:
+
+    >> Widget.paper_trail_off
+
+And on again like this:
+
+    >> Widget.paper_trail_on
+
+
+## Installation
+
+1. Install PaperTrail either as a gem or as a plugin:
+
+    `config.gem 'airblade-paper_trail', :lib => 'paper_trail', :source => 'http://gems.github.com'`
+
+    or:
+
+    `script/plugin install git://github.com/airblade/paper_trail.git`
+
+2. Generate a migration which will add a `versions` table to your database.
+
+    `script/generate paper_trail`
+
+3. Run the migration.
+
+    `rake db:migrate`
+
+4. Add `has_paper_trail` to the models you want to track.
+
+
+## Testing
+
+PaperTrail has a thorough suite of tests.  However they only run when PaperTrail is sitting in a Rails app's `vendor/plugins` directory.  If anyone can tell me how to get them to run outside of a Rails app, I'd love to hear it.
+
+
+## Problems
+
+Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
+
+
+## Inspirations
+
+* [Simply Versioned](http://github.com/github/simply_versioned)
+* [Acts As Audited](http://github.com/collectiveidea/acts_as_audited)
+
+
+## Intellectual Property
+
+Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com).
+Released under the MIT licence.

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'paper_trail'
+    gemspec.summary = "Track changes to your models' data.  Good for auditing or versioning."
+    gemspec.email = 'boss@airbladesoftware.com'
+    gemspec.homepage = 'http://github.com/airblade/paper_trail'
+    gemspec.authors = ['Andy Stewart']
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc 'Test the paper_trail plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+desc 'Generate documentation for the paper_trail plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PaperTrail'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Default: run unit tests.'
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+1.2.13

data/generators/paper_trail/USAGE

@@ -0,0 +1,2 @@
+Description:
+  Generates (but does not run) a migration to add a versions table.

data/generators/paper_trail/paper_trail_generator.rb

@@ -0,0 +1,9 @@
+class PaperTrailGenerator < Rails::Generator::Base
+
+  def manifest
+    record do |m|
+      m.migration_template 'create_versions.rb', 'db/migrate', :migration_file_name => 'create_versions'
+    end
+  end
+
+end

data/generators/paper_trail/templates/create_versions.rb

@@ -0,0 +1,20 @@
+class CreateVersions < ActiveRecord::Migration
+  def self.up
+    create_table :versions do |t|
+      t.string   :item_type, :null => false
+      t.integer  :item_id,   :null => false
+      t.string   :event,     :null => false
+      t.string   :whodunnit
+      t.text     :object
+      t.datetime :created_at
+      t.integer  :user_id,   :null => true
+    end
+    add_index :versions, [:item_type, :item_id]
+    add_index :versions, :user_id
+  end
+
+  def self.down
+    remove_index :versions, [:item_type, :item_id]
+    drop_table :versions
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+# Include hook code here

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/paper_trail.rb

@@ -0,0 +1,43 @@
+require 'yaml'
+require 'paper_trail/config'
+require 'paper_trail/has_paper_trail'
+require 'paper_trail/version'
+
+module PaperTrail
+  @@whodunnit = nil
+
+  def self.config
+    @@config ||= PaperTrail::Config.instance
+  end
+
+  def self.included(base)
+    base.before_filter :set_whodunnit
+  end
+
+  def self.enabled=(value)
+    PaperTrail.config.enabled = value
+  end
+
+  def self.enabled?
+    !!PaperTrail.config.enabled
+  end
+
+  def self.whodunnit
+    @@whodunnit.respond_to?(:call) ? @@whodunnit.call : @@whodunnit
+  end
+
+  def self.whodunnit=(value)
+    @@whodunnit = value
+  end
+
+  private
+
+  def set_whodunnit
+    @@whodunnit = lambda {
+      self.send :current_user rescue nil
+    }
+  end
+
+end
+
+ActionController::Base.send :include, PaperTrail

data/lib/paper_trail/config.rb

@@ -0,0 +1,10 @@
+module PaperTrail
+  class Config
+    include Singleton
+    attr_accessor :enabled
+
+    def initialize
+      @enabled = true
+    end
+  end
+end

data/lib/paper_trail/has_paper_trail.rb

@@ -0,0 +1,142 @@
+module PaperTrail
+
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+
+  module ClassMethods
+    def has_paper_trail
+      send :include, InstanceMethods
+
+      cattr_accessor :paper_trail_active
+      self.paper_trail_active = true
+
+      has_many :versions, :as => :item, :order => 'created_at ASC, id ASC'
+
+      after_create  :record_create
+      before_update :record_update
+      after_destroy :record_destroy
+    end
+
+    def paper_trail_off
+      self.paper_trail_active = false
+    end
+
+    def paper_trail_on
+      self.paper_trail_active = true
+    end
+  end
+
+
+  module InstanceMethods
+    def record_create
+      versions.create(:event     => 'create',
+                      :whodunnit => PaperTrail.whodunnit) if self.class.paper_trail_active && PaperTrail.enabled?
+    end
+
+    def record_update
+      if changed? and self.class.paper_trail_active and PaperTrail.enabled?
+        versions.build :event     => 'update',
+                       :object    => object_to_string(previous_version),
+                       :whodunnit => PaperTrail.whodunnit
+      end
+    end
+
+    def record_destroy
+      versions.create(:event     => 'destroy',
+                      :object    => object_to_string(previous_version),
+                      :whodunnit => PaperTrail.whodunnit) if self.class.paper_trail_active && PaperTrail.enabled?
+    end
+
+    # Returns the object at the version that was valid at the given timestamp.
+    def version_at timestamp
+      # short-circuit if the current state is valid
+      return self if self.updated_at < timestamp
+
+      version = versions.first(
+        :conditions => ['created_at < ?', timestamp],
+        :order => 'created_at DESC')
+      version.reify if version
+    end
+
+    # Walk the versions to construct an audit trail of the edits made
+    # over time, and by whom.
+    def audit_trail options={}
+      options[:attributes_to_ignore] ||= %w(updated_at)
+
+      audit_trail = []
+
+      versions_desc = versions_including_current_in_descending_order
+
+      versions_desc.each_with_index do |version, index|
+        previous_version = versions_desc[index + 1]
+        break if previous_version.nil?
+
+        attributes_after = yaml_to_hash(version.object)
+        attributes_before = yaml_to_hash(previous_version.object)
+
+        # remove some attributes that we don't need to report
+        [attributes_before, attributes_after].each do |hash|
+          hash.reject! { |k,v| k.in? Array(options[:attributes_to_ignore]) }
+        end
+
+        audit_trail << {
+          :event => previous_version.event,
+          :changed_by => transform_whodunnit(previous_version.whodunnit),
+          :changed_at => previous_version.created_at,
+          :changes => differences(attributes_before, attributes_after)
+          }
+      end
+
+      audit_trail
+    end
+
+    protected
+
+    def transform_whodunnit(whodunnit)
+      whodunnit
+    end
+
+
+    private
+
+    def previous_version
+      previous = self.clone
+      previous.id = id
+      changes.each do |attr, ary|
+        previous.send "#{attr}=", ary.first
+      end
+      previous
+    end
+
+    def object_to_string(object)
+      object.attributes.to_yaml
+    end
+
+    def yaml_to_hash(yaml)
+      return {} if yaml.nil?
+      YAML::load(yaml).to_hash
+    end
+
+    # Returns an array of hashes, where each hash specifies the +:attribute+,
+    # value +:before+ the change, and value +:after+ the change.
+    def differences(before, after)
+      before.diff(after).keys.sort.inject([]) do |diffs, k|
+        diff = { :attribute => k, :before => before[k], :after => after[k] }
+        diffs << diff; diffs
+      end
+    end
+
+    def versions_including_current_in_descending_order
+      v = self.versions.dup
+      v << Version.new(:event => 'update',
+        :object => object_to_string(self),
+        :created_at => self.updated_at)
+      v.reverse # newest first
+    end
+  end
+
+end
+
+ActiveRecord::Base.send :include, PaperTrail

data/lib/paper_trail/version.rb

@@ -0,0 +1,77 @@
+class Version < ActiveRecord::Base
+  belongs_to :item, :polymorphic => true
+  belongs_to :user
+  before_save :set_user_id
+  validates_presence_of :event
+
+  named_scope :for_item_type, lambda { |item_types|
+    { :conditions => { :item_type => item_types } }
+  }
+
+  named_scope :created_after, lambda { |time|
+    { :conditions => ['versions.created_at > ?', time] }
+  }
+
+  named_scope :by_created_at_ascending, :order => 'versions.created_at asc'
+
+  def reify
+    unless object.nil?
+      # Attributes
+
+      attrs = YAML::load object
+
+      # Normally a polymorphic belongs_to relationship allows us
+      # to get the object we belong to by calling, in this case,
+      # +item+.  However this returns nil if +item+ has been
+      # destroyed, and we need to be able to retrieve destroyed
+      # objects.
+      #
+      # In this situation we constantize the +item_type+ to get hold of
+      # the class...except when the stored object's attributes
+      # include a +type+ key.  If this is the case, the object
+      # we belong to is using single table inheritance and the
+      # +item_type+ will be the base class, not the actual subclass.
+      # If +type+ is present but empty, the class is the base class.
+
+      if item
+        model = item
+      else
+        class_name = attrs['type'].blank? ? item_type : attrs['type']
+        klass = class_name.constantize
+        model = klass.new
+      end
+
+      attrs.each do |k, v|
+        begin
+          model.send "#{k}=", v
+        rescue NoMethodError
+          RAILS_DEFAULT_LOGGER.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
+        end
+      end
+
+      model
+    end
+  end
+
+  def next
+    Version.first :conditions => ["id > ? AND item_type = ? AND item_id = ?", id, item_type, item_id],
+                  :order => 'id ASC'
+  end
+
+  def previous
+    Version.first :conditions => ["id < ? AND item_type = ? AND item_id = ?", id, item_type, item_id],
+                  :order => 'id DESC'
+  end
+
+  def index
+    Version.all(:conditions => ["item_type = ? AND item_id = ?", item_type, item_id],
+                :order => 'id ASC').index(self)
+  end
+  
+  private
+
+  def set_user_id
+    self.user_id = self.whodunnit.id if self.whodunnit.is_a?(ActiveRecord::Base)
+    return true
+  end
+end

data/paper_trail.gemspec

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{paper_trail}
+  s.version = "1.2.13"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Andy Stewart", "Jeremy Weiskotten", "Joe Lind"]
+  s.date = %q{2009-10-02}
+  s.email = %q{jeremy@weiskotten.com}
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "generators/paper_trail/USAGE",
+     "generators/paper_trail/paper_trail_generator.rb",
+     "generators/paper_trail/templates/create_versions.rb",
+     "init.rb",
+     "install.rb",
+     "lib/paper_trail.rb",
+     "lib/paper_trail/config.rb",
+     "lib/paper_trail/has_paper_trail.rb",
+     "lib/paper_trail/version.rb",
+     "paper_trail.gemspec",
+     "rails/init.rb",
+     "tasks/paper_trail_tasks.rake",
+     "test/database.yml",
+     "test/paper_trail_controller_test.rb",
+     "test/paper_trail_model_test.rb",
+     "test/paper_trail_schema_test.rb",
+     "test/schema.rb",
+     "test/schema_change.rb",
+     "test/test_helper.rb",
+     "uninstall.rb"
+  ]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/jeremyw/paper_trail}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Track changes to your models' data.  Good for auditing or versioning.}
+  s.test_files = [
+    "test/paper_trail_controller_test.rb",
+     "test/paper_trail_model_test.rb",
+     "test/paper_trail_schema_test.rb",
+     "test/schema.rb",
+     "test/schema_change.rb",
+     "test/test_helper.rb"
+  ]
+
+  # if s.respond_to? :specification_version then
+  #   current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+  #   s.specification_version = 2
+  #
+  #   if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+  #   else
+  #   end
+  # else
+  # end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'paper_trail'

data/test/database.yml

@@ -0,0 +1,22 @@
+sqlite:
+  :adapter: sqlite
+  :dbfile: vendor/plugins/paper_trail/test/paper_trail_plugin.sqlite.db
+
+sqlite3:
+  :adapter: sqlite3
+  :dbfile: vendor/plugins/paper_trail/test/paper_trail_plugin.sqlite3.db
+
+postgresql:
+  :adapter: postgresql
+  :username: postgres
+  :password: postgres
+  :database: paper_trail_plugin_test
+  :min_messages: ERROR
+
+mysql:
+  :adapter: mysql
+  :host: localhost
+  :username: andy
+  :password: 
+  :database: paper_trail_plugin_test
+  :socket: /tmp/mysql.sock

data/test/paper_trail_controller_test.rb

@@ -0,0 +1,72 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+require 'application_controller'
+require 'action_controller/test_process'
+
+class ApplicationController
+  def rescue_action(e)
+    raise e
+  end
+
+  # Returns id of hypothetical current user
+  def current_user
+    153
+  end
+end
+
+class WidgetsController < ApplicationController
+  def create
+    @widget = Widget.create params[:widget]
+    head :ok
+  end
+
+  def update
+    @widget = Widget.find params[:id]
+    @widget.update_attributes params[:widget]
+    head :ok
+  end
+
+  def destroy
+    @widget = Widget.find params[:id]
+    @widget.destroy
+    head :ok
+  end
+end
+
+
+class PaperTrailControllerTest < ActionController::TestCase #Test::Unit::TestCase
+  def setup
+    @controller = WidgetsController.new
+    @request = ActionController::TestRequest.new
+    @response = ActionController::TestResponse.new
+
+    ActionController::Routing::Routes.draw do |map|
+      map.resources :widgets
+    end
+  end
+
+  test 'create' do
+    post :create, :widget => { :name => 'Flugel' }
+    widget = assigns(:widget)
+    assert_equal 1, widget.versions.length
+    assert_equal 153, widget.versions.last.whodunnit.to_i
+  end
+
+  test 'update' do
+    w = Widget.create :name => 'Duvel'
+    assert_equal 1, w.versions.length
+    put :update, :id => w.id, :widget => { :name => 'Bugle' }
+    widget = assigns(:widget)
+    assert_equal 2, widget.versions.length
+    assert_equal 153, widget.versions.last.whodunnit.to_i
+  end
+
+  test 'destroy' do
+    w = Widget.create :name => 'Roundel'
+    assert_equal 1, w.versions.length
+    delete :destroy, :id => w.id
+    widget = assigns(:widget)
+    assert_equal 2, widget.versions.length
+    assert_equal 153, widget.versions.last.whodunnit.to_i
+  end
+end
+

data/test/paper_trail_model_test.rb

@@ -0,0 +1,370 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class Widget < ActiveRecord::Base
+  has_paper_trail
+  has_one :wotsit
+  has_many :fluxors, :order => :name
+end
+
+class FooWidget < Widget
+end
+
+class Wotsit < ActiveRecord::Base
+  belongs_to :widget
+end
+
+class Fluxor < ActiveRecord::Base
+  belongs_to :widget
+end
+
+
+class HasPaperTrailModelTest < Test::Unit::TestCase
+  load_schema
+
+  context 'A new record' do
+    setup { @widget = Widget.new }
+
+    should 'not have any previous versions' do
+      assert_equal [], @widget.versions
+    end
+
+
+    context 'which is then created' do
+      setup { @widget.update_attributes :name => 'Henry' }
+
+      should 'have one previous version' do
+        assert_equal 1, @widget.versions.length
+      end
+
+      should 'be nil in its previous version' do
+        assert_nil @widget.versions.first.object
+        assert_nil @widget.versions.first.reify
+      end
+
+      should 'record the correct event' do
+        assert_match /create/i, @widget.versions.first.event
+      end
+
+
+      context 'and then updated without any changes' do
+        setup { @widget.save }
+
+        should 'not have a new version' do
+          assert_equal 1, @widget.versions.length
+        end
+      end
+
+
+      context 'and then updated with changes' do
+        setup { @widget.update_attributes :name => 'Harry' }
+
+        should 'have two previous versions' do
+          assert_equal 2, @widget.versions.length
+        end
+
+        should 'be available in its previous version' do
+          assert_equal 'Harry', @widget.name
+          assert_not_nil @widget.versions.last.object
+          widget = @widget.versions.last.reify
+          assert_equal 'Henry', widget.name
+          assert_equal 'Harry', @widget.name
+        end
+
+        should 'have the same ID in its previous version' do
+          assert_equal @widget.id, @widget.versions.last.reify.id
+        end
+
+        should 'record the correct event' do
+          assert_match /update/i, @widget.versions.last.event
+        end
+
+        
+        context 'and has one associated object' do
+          setup do
+            @wotsit = @widget.create_wotsit :name => 'John'
+            @reified_widget = @widget.versions.last.reify
+          end
+
+          should 'copy the has_one association when reifying' do
+            assert_equal @wotsit, @reified_widget.wotsit
+          end
+        end
+
+
+        context 'and has many associated objects' do
+          setup do
+            @f0 = @widget.fluxors.create :name => 'f-zero'
+            @f1 = @widget.fluxors.create :name => 'f-one'
+            @reified_widget = @widget.versions.last.reify
+          end
+
+          should 'copy the has_many associations when reifying' do
+            assert_equal @widget.fluxors.length, @reified_widget.fluxors.length
+            assert_same_elements @widget.fluxors, @reified_widget.fluxors
+
+            assert_equal @widget.versions.length, @reified_widget.versions.length
+            assert_same_elements @widget.versions, @reified_widget.versions
+          end
+        end
+
+
+        context 'and then destroyed' do
+          setup do
+            @fluxor = @widget.fluxors.create :name => 'flux'
+            @widget.destroy
+            @reified_widget = @widget.versions.last.reify
+          end
+
+          should 'record the correct event' do
+            assert_match /destroy/i, @widget.versions.last.event
+          end
+
+          should 'have three previous versions' do
+            assert_equal 3, @widget.versions.length
+          end
+
+          should 'be available in its previous version' do
+            assert_equal @widget.id, @reified_widget.id
+            assert_equal @widget.attributes, @reified_widget.attributes
+          end
+
+          should 'be re-creatable from its previous version' do
+            assert @reified_widget.save
+          end
+
+          should 'restore its associations on its previous version' do
+            @reified_widget.save
+            assert_equal 1, @reified_widget.fluxors.length
+          end
+        end
+      end
+    end
+  end
+
+
+  # Test the serialisation and deserialisation.
+  # TODO: binary
+  context "A record's papertrail" do
+    setup do
+      @date_time = DateTime.now.utc
+      @time = Time.now
+      @date = Date.new 2009, 5, 29
+      @widget = Widget.create :name        => 'Warble',
+                              :a_text      => 'The quick brown fox',
+                              :an_integer  => 42,
+                              :a_float     => 153.01,
+                              :a_decimal   => 2.71828,
+                              :a_datetime  => @date_time,
+                              :a_time      => @time,
+                              :a_date      => @date,
+                              :a_boolean   => true
+
+      @widget.update_attributes :name      => nil,
+                              :a_text      => nil,
+                              :an_integer  => nil,
+                              :a_float     => nil,
+                              :a_decimal   => nil,
+                              :a_datetime  => nil,
+                              :a_time      => nil,
+                              :a_date      => nil,
+                              :a_boolean   => false
+      @previous = @widget.versions.last.reify
+    end
+
+    should 'handle strings' do
+      assert_equal 'Warble', @previous.name
+    end
+
+    should 'handle text' do
+      assert_equal 'The quick brown fox', @previous.a_text
+    end
+
+    should 'handle integers' do
+      assert_equal 42, @previous.an_integer
+    end
+
+    should 'handle floats' do
+      assert_in_delta 153.01, @previous.a_float, 0.001
+    end
+
+    should 'handle decimals' do
+      assert_in_delta 2.71828, @previous.a_decimal, 0.00001
+    end
+
+    should 'handle datetimes' do
+      # Is there a better way to test equality of two datetimes?
+      format = '%a, %d %b %Y %H:%M:%S %z' # :rfc822
+      assert_equal @date_time.strftime(format), @previous.a_datetime.strftime(format)
+    end
+
+    should 'handle times' do
+      assert_equal @time, @previous.a_time
+    end
+
+    should 'handle dates' do
+      assert_equal @date, @previous.a_date
+    end
+
+    should 'handle booleans' do
+      assert @previous.a_boolean
+    end
+
+
+    context "after a column is removed from the record's schema" do
+      setup do
+        change_schema
+        Widget.reset_column_information
+        assert_raise(NoMethodError) { Widget.new.sacrificial_column }
+        @last = @widget.versions.last
+      end
+
+      should 'reify previous version' do
+        assert_kind_of Widget, @last.reify
+      end
+
+      should 'restore all forward-compatible attributes' do
+        format = '%a, %d %b %Y %H:%M:%S %z' # :rfc822
+        assert_equal    'Warble',                    @last.reify.name
+        assert_equal    'The quick brown fox',       @last.reify.a_text
+        assert_equal    42,                          @last.reify.an_integer
+        assert_in_delta 153.01,                      @last.reify.a_float,   0.001
+        assert_in_delta 2.71828,                     @last.reify.a_decimal, 0.00001
+        assert_equal    @date_time.strftime(format), @last.reify.a_datetime.strftime(format)
+        assert_equal    @time,                       @last.reify.a_time
+        assert_equal    @date,                       @last.reify.a_date
+        assert          @last.reify.a_boolean
+      end
+    end
+  end
+
+
+  context 'A record' do
+    setup { @widget = Widget.create :name => 'Zaphod' }
+
+    context 'with its paper trail turned off' do
+      setup do
+        Widget.paper_trail_off
+        @count = @widget.versions.length
+      end
+
+      teardown { Widget.paper_trail_on }
+
+      context 'when updated' do
+        setup { @widget.update_attributes :name => 'Beeblebrox' }
+
+        should 'not add to its trail' do
+          assert_equal @count, @widget.versions.length
+        end
+      end
+
+      context 'and then its paper trail turned on' do
+        setup { Widget.paper_trail_on }
+
+        context 'when updated' do
+          setup { @widget.update_attributes :name => 'Ford' }
+
+          should 'add to its trail' do
+            assert_equal @count + 1, @widget.versions.length
+          end
+        end
+      end
+    end
+  end
+
+
+  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 }
+
+      should 'track who made the change' do
+        assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+      end
+
+      context 'when a record is updated' do
+        setup { @widget.update_attributes :name => 'Rivet' }
+
+        should 'track who made the change' do
+          assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+        end
+
+        context 'when a record is destroyed' do
+          setup { @widget.destroy }
+
+          should 'track who made the change' do
+            assert_equal 'Colonel Mustard', @widget.versions.last.whodunnit
+          end
+        end
+      end
+    end
+  end
+
+
+  context 'A subclass' do
+    setup do
+      @foo = FooWidget.create
+      @foo.update_attributes :name => 'Fooey'
+    end
+
+    should 'reify with the correct type' do
+      thing = @foo.versions.last.reify
+      assert_kind_of FooWidget, thing
+    end
+
+
+    context 'when destroyed' do
+      setup { @foo.destroy }
+
+      should 'reify with the correct type' do
+        thing = @foo.versions.last.reify
+        assert_kind_of FooWidget, thing
+      end
+    end
+  end
+
+
+  context 'An item with versions' do
+    setup do
+      @widget = Widget.create :name => 'Widget'
+      @widget.update_attributes :name => 'Fidget'
+      @widget.update_attributes :name => 'Digit'
+    end
+
+    context 'on the first version' do
+      setup { @version = @widget.versions.first }
+
+      should 'have a nil previous version' do
+        assert_nil @version.previous
+      end
+
+      should 'return the next version' do
+        assert_equal @widget.versions[1], @version.next
+      end
+
+      should 'return the correct index' do
+        assert_equal 0, @version.index
+      end
+    end
+
+    context 'on the last version' do
+      setup { @version = @widget.versions.last }
+
+      should 'return the previous version' do
+        assert_equal @widget.versions[@widget.versions.length - 2], @version.previous
+      end
+
+      should 'have a nil next version' do
+        assert_nil @version.next
+      end
+
+      should 'return the correct index' do
+        assert_equal @widget.versions.length - 1, @version.index
+      end
+    end
+  end
+
+end

data/test/paper_trail_schema_test.rb

@@ -0,0 +1,14 @@
+require 'test_helper'
+
+class PaperTrailSchemaTest < ActiveSupport::TestCase
+  def setup
+    load_schema
+  end
+
+  def test_schema_has_loaded_correctly
+    assert_equal [], Widget.all
+    assert_equal [], Version.all
+    assert_equal [], Wotsit.all
+    assert_equal [], Fluxor.all
+  end
+end

data/test/schema.rb

@@ -0,0 +1,38 @@
+ActiveRecord::Schema.define(:version => 0) do
+
+  create_table :widgets, :force => true do |t|
+    t.string    :name
+    t.text      :a_text
+    t.integer   :an_integer
+    t.float     :a_float
+    t.decimal   :a_decimal
+    t.datetime  :a_datetime
+    t.time      :a_time
+    t.date      :a_date
+    t.boolean   :a_boolean
+    t.datetime  :created_at, :updated_at
+    t.string    :sacrificial_column
+    t.string    :type
+  end
+
+  create_table :versions, :force => true do |t|
+    t.string   :item_type, :null => false
+    t.integer  :item_id,   :null => false
+    t.string   :event,     :null => false
+    t.string   :whodunnit
+    t.text     :object
+    t.datetime :created_at
+  end
+  add_index :versions, [:item_type, :item_id]
+
+  create_table :wotsits, :force => true do |t|
+    t.integer :widget_id
+    t.string  :name
+  end
+
+  create_table :fluxors, :force => true do |t|
+    t.integer :widget_id
+    t.string  :name
+  end
+
+end

data/test/schema_change.rb

@@ -0,0 +1,3 @@
+ActiveRecord::Schema.define do
+  remove_column :widgets, :sacrificial_column
+end

data/test/test_helper.rb

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'active_support'
+require 'active_support/test_case'
+require 'shoulda'
+
+ENV['RAILS_ENV'] = 'test'
+ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
+
+require 'test/unit'
+require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
+
+def connect_to_database
+  config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+  ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+
+  db_adapter = ENV['DB']
+
+  # no db passed, try one of these fine config-free DBs before bombing.
+  db_adapter ||=
+    begin
+      require 'rubygems'
+      require 'sqlite'
+      'sqlite'
+    rescue MissingSourceFile
+      begin
+        require 'sqlite3'
+        'sqlite3'
+      rescue MissingSourceFile
+      end
+    end
+
+  if db_adapter.nil?
+    raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
+  end
+
+  ActiveRecord::Base.establish_connection(config[db_adapter])
+end
+
+def load_schema
+  connect_to_database
+  load(File.dirname(__FILE__) + "/schema.rb")
+  require File.dirname(__FILE__) + '/../rails/init.rb'
+end
+
+def change_schema
+  load(File.dirname(__FILE__) + "/schema_change.rb")
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: paper_trail
+version: !ruby/object:Gem::Version 
+  version: 1.2.13
+platform: ruby
+authors: 
+- Andy Stewart
+- Jeremy Weiskotten
+- Joe Lind
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-02 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: 
+email: jeremy@weiskotten.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.md
+- Rakefile
+- VERSION
+- generators/paper_trail/USAGE
+- generators/paper_trail/paper_trail_generator.rb
+- generators/paper_trail/templates/create_versions.rb
+- init.rb
+- install.rb
+- lib/paper_trail.rb
+- lib/paper_trail/config.rb
+- lib/paper_trail/has_paper_trail.rb
+- lib/paper_trail/version.rb
+- paper_trail.gemspec
+- rails/init.rb
+- tasks/paper_trail_tasks.rake
+- test/database.yml
+- test/paper_trail_controller_test.rb
+- test/paper_trail_model_test.rb
+- test/paper_trail_schema_test.rb
+- test/schema.rb
+- test/schema_change.rb
+- test/test_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/jeremyw/paper_trail
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Track changes to your models' data.  Good for auditing or versioning.
+test_files: 
+- test/paper_trail_controller_test.rb
+- test/paper_trail_model_test.rb
+- test/paper_trail_schema_test.rb
+- test/schema.rb
+- test/schema_change.rb
+- test/test_helper.rb