revo-paper_trail 1.4.2

data/.gitignore

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

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,226 @@
+# 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.
+* Does not store updates which only change attributes you are ignoring.
+* 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).
+* Allows you to store arbitrary metadata with each version (useful for filtering versions).
+* Can be turned off/on (useful for migrations).
+* No configuration necessary.
+* Stores everything in a single database table (generates migration for you).
+* Thoroughly tested.
+* Thread safe
+
+
+## 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.
+
+
+## Ignoring changes to certain attributes
+
+You can ignore changes to certain attributes like this:
+
+    class Article < ActiveRecord::Base
+      has_paper_trail :ignore => [:title, :rating]
+    end
+
+This means that changes to just the `title` or `rating` will not store another version of the article.  It does not mean that the `title` and `rating` attributes will be ignored if some other change causes a new `Version` to be crated.  For example:
+
+    >> a = Article.create
+    >> a.versions.length                         # 1
+    >> a.update_attributes :title => 'My Title', :rating => 3
+    >> a.versions.length                         # 1
+    >> a.update_attributes :content => 'Hello'
+    >> a.versions.length                         # 2
+    >> a.versions.last.reify.title               # 'My Title'
+
+
+## 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
+
+
+## Storing metadata
+
+You can store arbitrary metadata alongside each version like this:
+
+    class Article < ActiveRecord::Base
+      belongs_to :author
+      has_paper_trail :meta => { :author_id => Proc.new { |article| article.author_id },
+                                 :answer    => 42 }
+    end
+
+PaperTrail will call your proc with the current article and store the result in the `author_id` column of the `versions` table.  (Remember to add your metadata columns to the table.)
+
+Why would you do this?  In this example, `author_id` is an attribute of `Article` and PaperTrail will store it anyway in serialized (YAML) form in the `object` column of the `version` record.  But let's say you wanted to pull out all versions for a particular author; without the metadata you would have to deserialize (reify) each `version` object to see if belonged to the author in question.  Clearly this is inefficient.  Using the metadata you can find just those versions you want:
+
+    Version.all(:conditions => ['author_id = ?', author_id])
+
+
+## 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 (from Gemcutter; the ones on GitHub are obsolete) or as a plugin:
+
+    `config.gem 'paper_trail', :source => 'http://gemcutter.org'`
+
+    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.  Thanks to [Zachery Hostens](http://github.com/zacheryph) for making them able to run standalone, i.e. without needing PaperTrail to be sitting in a Rails app.
+
+
+## Problems
+
+Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
+
+
+## Contributors
+
+Many thanks to:
+
+* [Zachery Hostens](http://github.com/zacheryph)
+
+
+## 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,50 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = 'revo-paper_trail'
+    gemspec.summary = "Track changes to your models' data.  Good for auditing or versioning."
+    gemspec.email = 'boss@airbladesoftware.com, ge_developers@playup.com'
+    gemspec.homepage = 'http://github.com/airblade/paper_trail'
+    gemspec.authors = ['Andy Stewart', 'Revo Developers']
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+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.4.2

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,18 @@
+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
+    end
+    add_index :versions, [:item_type, :item_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,21 @@
+require 'yaml'
+require 'paper_trail/has_paper_trail'
+require 'paper_trail/version'
+
+module PaperTrail
+  
+  def self.included(base)
+    base.before_filter :set_whodunnit
+  end
+
+  def self.whodunnit
+    Thread.current[:whodunnit]
+  end
+
+  private
+  def set_whodunnit
+    Thread.current[:whodunnit] = self.send :current_user rescue nil
+  end
+end
+
+ActionController::Base.send :include, PaperTrail

data/lib/paper_trail/has_paper_trail.rb

@@ -0,0 +1,95 @@
+module PaperTrail
+
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+
+  module ClassMethods
+    # Options:
+    # :ignore    an array of attributes for which a new +Version+ will not be created if only they change.
+    # :meta      a hash of extra data to store.  You must add a column to the versions table for each key.
+    #            Values are objects or procs (which are called with +self+, i.e. the model with the paper
+    #            trail).
+    def has_paper_trail(options = {})
+      send :include, InstanceMethods
+
+      cattr_accessor :ignore
+      self.ignore = (options[:ignore] || []).map &:to_s
+
+      cattr_accessor :meta
+      self.meta = options[:meta] || {}
+      
+      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
+      if self.class.paper_trail_active
+        versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
+      end
+    end
+
+    def record_update
+      if changed_and_we_care? and self.class.paper_trail_active
+        versions.build merge_metadata(:event     => 'update',
+                                      :object    => object_to_string(previous_version),
+                                      :whodunnit => PaperTrail.whodunnit)
+      end
+    end
+
+    def record_destroy
+      if self.class.paper_trail_active
+        versions.create merge_metadata(:event     => 'destroy',
+                                       :object    => object_to_string(previous_version),
+                                       :whodunnit => PaperTrail.whodunnit)
+      end
+    end
+
+    private
+
+    def merge_metadata(data)
+      meta.each do |k,v|
+        data[k] = v.respond_to?(:call) ? v.call(self) : v
+      end
+      data
+    end
+
+    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 changed_and_we_care?
+      changed? and !(changed - self.class.ignore).empty?
+    end
+  end
+
+end
+
+ActiveRecord::Base.send :include, PaperTrail