paper_trail_without_deprecated 3.0.0.beta1

data/Rakefile

@@ -0,0 +1,18 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+desc 'Run tests on PaperTrail with Test::Unit.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+require 'rspec/core/rake_task'
+desc 'Run PaperTrail specs for the RSpec helper.'
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Default: run all available test suites'
+task :default => [:test, :spec]

data/gemfiles/3.0.gemfile

@@ -0,0 +1,31 @@
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 3.0'
+
+group :development, :test do
+  gem 'rake'
+  gem 'shoulda', '~> 3.5'
+  gem 'ffaker',  '>= 1.15'
+
+  # Testing of Rails
+  gem 'railties', '~> 3.0'
+
+  # Testing of Sinatra
+  gem 'sinatra', '~> 1.0'
+  gem 'rack-test', '>= 0.6'
+
+  # Use sqlite3 gem for regular Ruby
+  gem 'sqlite3', '~> 1.2', :platform => :ruby
+
+  # RSpec testing
+  gem 'rspec-rails', '~> 2.14'
+
+  platforms :jruby, :ruby_18 do
+    # shoulda-matchers > 2.0 is not compatible with Ruby18.
+    # Since we can't specify difference between JRuby 18/19, we need to use shoulda-matchers 1.5 for all JRuby testing.
+    gem 'shoulda-matchers', '~> 1.5'
+  end
+
+  # Use jRuby's sqlite3 adapter for jRuby
+  gem 'activerecord-jdbcsqlite3-adapter', '~> 1.2.9', :platform => :jruby
+end

data/lib/generators/paper_trail/USAGE

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

data/lib/generators/paper_trail/install_generator.rb

@@ -0,0 +1,23 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module PaperTrail
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+    class_option :with_changes, :type => :boolean, :default => false, :desc => "Store changeset (diff) with each version"
+
+    desc 'Generates (but does not run) a migration to add a versions table.'
+
+    def create_migration_file
+      migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
+      migration_template 'add_object_changes_column_to_versions.rb', 'db/migrate/add_object_changes_column_to_versions.rb' if options.with_changes?
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+  end
+end

data/lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb

@@ -0,0 +1,9 @@
+class AddObjectChangesColumnToVersions < ActiveRecord::Migration
+  def self.up
+    add_column :versions, :object_changes, :text
+  end
+
+  def self.down
+    remove_column :versions, :object_changes
+  end
+end

data/lib/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/lib/paper_trail.rb

@@ -0,0 +1,115 @@
+require 'paper_trail/config'
+require 'paper_trail/has_paper_trail'
+require 'paper_trail/cleaner'
+
+# Require all frameworks and serializers
+Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'frameworks', '*.rb')].each { |file| require file }
+Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'serializers', '*.rb')].each { |file| require file }
+
+# PaperTrail's module methods can be called in both models and controllers.
+module PaperTrail
+  extend PaperTrail::Cleaner
+
+  # Switches PaperTrail on or off.
+  def self.enabled=(value)
+    PaperTrail.config.enabled = value
+  end
+
+  # Returns `true` if PaperTrail is on, `false` otherwise.
+  # PaperTrail is enabled by default.
+  def self.enabled?
+    !!PaperTrail.config.enabled
+  end
+
+  # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+  #
+  # See `PaperTrail::Controller#paper_trail_enabled_for_controller`.
+  def self.enabled_for_controller?
+    !!paper_trail_store[:request_enabled_for_controller]
+  end
+
+  # Sets whether PaperTrail is enabled or disabled for the current request.
+  def self.enabled_for_controller=(value)
+    paper_trail_store[:request_enabled_for_controller] = value
+  end
+
+  # Set the field which records when a version was created.
+  def self.timestamp_field=(field_name)
+    PaperTrail.config.timestamp_field = field_name
+  end
+
+  # Returns the field which records when a version was created.
+  def self.timestamp_field
+    PaperTrail.config.timestamp_field
+  end
+
+  # Returns who is reponsible for any changes that occur.
+  def self.whodunnit
+    paper_trail_store[:whodunnit]
+  end
+
+  # Sets who is responsible for any changes that occur.
+  # You would normally use this in a migration or on the console,
+  # when working with models directly.  In a controller it is set
+  # automatically to the `current_user`.
+  def self.whodunnit=(value)
+    paper_trail_store[:whodunnit] = value
+  end
+
+  # Returns any information from the controller that you want
+  # PaperTrail to store.
+  #
+  # See `PaperTrail::Controller#info_for_paper_trail`.
+  def self.controller_info
+    paper_trail_store[:controller_info]
+  end
+
+  # Sets any information from the controller that you want PaperTrail
+  # to store.  By default this is set automatically by a before filter.
+  def self.controller_info=(value)
+    paper_trail_store[:controller_info] = value
+  end
+
+  # Getter and Setter for PaperTrail Serializer
+  def self.serializer=(value)
+    PaperTrail.config.serializer = value
+  end
+
+  def self.serializer
+    PaperTrail.config.serializer
+  end
+
+  def self.active_record_protected_attributes?
+    @active_record_protected_attributes ||= ActiveRecord::VERSION::STRING.to_f < 4.0 || defined?(ProtectedAttributes)
+  end
+
+  private
+
+  # Thread-safe hash to hold PaperTrail's data.
+  # Initializing with needed default values.
+  def self.paper_trail_store
+    Thread.current[:paper_trail] ||= { :request_enabled_for_controller => true }
+  end
+
+  # Returns PaperTrail's configuration object.
+  def self.config
+    @@config ||= PaperTrail::Config.instance
+  end
+
+  def self.configure
+    yield config
+  end
+
+end
+
+require 'paper_trail/version'
+
+ActiveSupport.on_load(:active_record) do
+  include PaperTrail::Model
+end
+
+if defined?(ActionController)
+  ActiveSupport.on_load(:action_controller) do
+    include PaperTrail::Rails::Controller
+  end
+end

data/lib/paper_trail/cleaner.rb

@@ -0,0 +1,34 @@
+module PaperTrail
+  module Cleaner
+    # Destroys all but the most recent version(s) for items on a given date (or on all dates). Useful for deleting drafts.
+    #
+    # Options:
+    # :keeping      An `integer` indicating the number of versions to be kept for each item per date.
+    #               Defaults to `1`.
+    # :date         Should either be a `Date` object specifying which date to destroy versions for or `:all`,
+    #               which will specify that all dates should be cleaned. Defaults to `:all`.
+    # :item_id      The `id` for the item to be cleaned on, or `nil`, which causes all items to be cleaned.
+    #               Defaults to `nil`.
+    def clean_versions!(options = {})
+      options = {:keeping => 1, :date => :all}.merge(options)
+      gather_versions(options[:item_id], options[:date]).each do |item_id, versions|
+        versions.group_by { |v| v.created_at.to_date }.each do |date, versions| # now group the versions by date and iterate through those
+          versions.pop(options[:keeping]) # remove the number of versions we wish to keep from the collection of versions prior to destruction
+          versions.map(&:destroy)
+        end
+      end
+    end
+
+    private
+
+    # Returns a hash of versions grouped by the `item_id` attribute formatted like this: {:item_id => PaperTrail::Version}.
+    # If `item_id` or `date` is set, versions will be narrowed to those pointing at items with those ids that were created on specified date.
+    def gather_versions(item_id = nil, date = :all)
+      raise "`date` argument must receive a Timestamp or `:all`" unless date == :all || date.respond_to?(:to_date)
+      versions = item_id ? PaperTrail::Version.where(:item_id => item_id) : PaperTrail::Version
+      versions = versions.between(date.to_date, date.to_date + 1.day) unless date == :all
+      versions = PaperTrail::Version.all if versions == PaperTrail::Version # if versions has not been converted to an ActiveRecord::Relation yet, do so now
+      versions.group_by(&:item_id)
+    end
+  end
+end

data/lib/paper_trail/config.rb

@@ -0,0 +1,14 @@
+require 'singleton'
+
+module PaperTrail
+  class Config
+    include Singleton
+    attr_accessor :enabled, :timestamp_field, :serializer, :version_limit
+
+    def initialize
+      @enabled         = true # Indicates whether PaperTrail is on or off.
+      @timestamp_field = :created_at
+      @serializer      = PaperTrail::Serializers::Yaml
+    end
+  end
+end

data/lib/paper_trail/frameworks/cucumber.rb

@@ -0,0 +1,31 @@
+if defined? World
+  # before hook for Cucumber
+  before do
+    ::PaperTrail.enabled = false
+    ::PaperTrail.whodunnit = nil
+    ::PaperTrail.controller_info = {} if defined? ::Rails
+  end
+
+  module PaperTrail
+    module Cucumber
+      module Extensions
+        # :call-seq:
+        # with_versioning
+        #
+        # enable versioning for specific blocks
+
+        def with_versioning
+          was_enabled = ::PaperTrail.enabled?
+          ::PaperTrail.enabled = true
+          begin
+            yield
+          ensure
+            ::PaperTrail.enabled = was_enabled
+          end
+        end
+      end
+    end
+  end
+
+  World PaperTrail::Cucumber::Extensions
+end

data/lib/paper_trail/frameworks/rails.rb

@@ -0,0 +1,79 @@
+module PaperTrail
+  module Rails
+    module Controller
+
+      def self.included(base)
+        if defined?(ActionController) && base == ActionController::Base
+          base.before_filter :set_paper_trail_enabled_for_controller
+          base.before_filter :set_paper_trail_whodunnit, :set_paper_trail_controller_info
+        end
+      end
+
+      protected
+
+      # Returns the user who is responsible for any changes that occur.
+      # By default this calls `current_user` and returns the result.
+      #
+      # Override this method in your controller to call a different
+      # method, e.g. `current_person`, or anything you like.
+      def user_for_paper_trail
+        current_user if defined?(current_user)
+      end
+
+      # Returns any information about the controller or request that you
+      # want PaperTrail to store alongside any changes that occur.  By
+      # default this returns an empty hash.
+      #
+      # Override this method in your controller to return a hash of any
+      # information you need.  The hash's keys must correspond to columns
+      # in your `versions` table, so don't forget to add any new columns
+      # you need.
+      #
+      # For example:
+      #
+      #     {:ip => request.remote_ip, :user_agent => request.user_agent}
+      #
+      # The columns `ip` and `user_agent` must exist in your `versions` # table.
+      #
+      # Use the `:meta` option to `PaperTrail::Model::ClassMethods.has_paper_trail`
+      # to store any extra model-level data you need.
+      def info_for_paper_trail
+        {}
+      end
+
+      # Returns `true` (default) or `false` depending on whether PaperTrail should
+      # be active for the current request.
+      #
+      # Override this method in your controller to specify when PaperTrail should
+      # be off.
+      def paper_trail_enabled_for_controller
+        true
+      end
+
+      private
+
+      # Tells PaperTrail whether versions should be saved in the current request.
+      def set_paper_trail_enabled_for_controller
+        ::PaperTrail.enabled_for_controller = paper_trail_enabled_for_controller
+      end
+
+      # Tells PaperTrail who is responsible for any changes that occur.
+      def set_paper_trail_whodunnit
+        ::PaperTrail.whodunnit = user_for_paper_trail if paper_trail_enabled_for_controller
+      end
+
+      # DEPRECATED: please use `set_paper_trail_whodunnit` instead.
+      def set_whodunnit
+        logger.warn '[PaperTrail]: the `set_whodunnit` controller method has been deprecated.  Please rename to `set_paper_trail_whodunnit`.'
+        set_paper_trail_whodunnit
+      end
+
+      # Tells PaperTrail any information from the controller you want
+      # to store alongside any changes that occur.
+      def set_paper_trail_controller_info
+        ::PaperTrail.controller_info = info_for_paper_trail if paper_trail_enabled_for_controller
+      end
+
+    end
+  end
+end

data/lib/paper_trail/frameworks/rspec.rb

@@ -0,0 +1,24 @@
+if defined? RSpec
+  require 'rspec/core'
+  require 'rspec/matchers'
+  require File.expand_path('../rspec/extensions', __FILE__)
+
+  RSpec.configure do |config|
+    config.include ::PaperTrail::RSpec::Extensions
+
+    config.before(:each) do
+      ::PaperTrail.enabled = false
+      ::PaperTrail.whodunnit = nil
+      ::PaperTrail.controller_info = {} if defined?(::Rails) && defined?(::RSpec::Rails)
+    end
+
+    config.before(:each, :versioning => true) do
+      ::PaperTrail.enabled = true
+    end
+  end
+
+  RSpec::Matchers.define :be_versioned do
+    # check to see if the model has `has_paper_trail` declared on it
+    match { |actual| actual.kind_of?(::PaperTrail::Model::InstanceMethods) }
+  end
+end

data/lib/paper_trail/frameworks/rspec/extensions.rb

@@ -0,0 +1,20 @@
+module PaperTrail
+  module RSpec
+    module Extensions
+      # :call-seq:
+      # with_versioning
+      #
+      # enable versioning for specific blocks
+
+      def with_versioning
+        was_enabled = ::PaperTrail.enabled?
+        ::PaperTrail.enabled = true
+        begin
+          yield
+        ensure
+          ::PaperTrail.enabled = was_enabled
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/sinatra.rb

@@ -0,0 +1,31 @@
+module Sinatra
+  module PaperTrail
+
+    # Register this module inside your Sinatra application to gain access to controller-level methods used by PaperTrail
+    def self.registered(app)
+      app.helpers Sinatra::PaperTrail
+      app.before { set_paper_trail_whodunnit }
+    end
+
+    protected
+
+    # Returns the user who is responsible for any changes that occur.
+    # By default this calls `current_user` and returns the result.
+    #
+    # Override this method in your controller to call a different
+    # method, e.g. `current_person`, or anything you like.
+    def user_for_paper_trail
+      current_user if defined?(current_user)
+    end
+
+    private
+
+    # Tells PaperTrail who is responsible for any changes that occur.
+    def set_paper_trail_whodunnit
+      ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled?
+    end
+
+  end
+
+  register Sinatra::PaperTrail if defined?(register)
+end