undestroy 0.0.2 → 0.1.0

data/ARCH.md

@@ -6,32 +6,18 @@ modular and easy to tailor to your specific needs.
 ### `Config`
 
 Holds configuration information for Undestroy.  An instance is created
-globally and serves as defaults for each model using Undestroy.  Each
-model also creates its own instance of Config allowing any model to
-override any of the globally configurable options.
+globally and serves as defaults for each model using Undestroy, but each
+model has its own unique configuration allowing developer flexibility.
 
-To change global defaults use this configuration DSL:
+Each of the core classes `Archive`, `Restore`, and `Transfer` can be
+configured in the `:internals` hash option on a per model basis allowing
+the developer to provide custom classes for the various actions
+Undestroy provides.
 
-```ruby
-Undestroy::Config.configure do |config|
-  config.abstract_class = ArchiveModel
-  config.fields = {
-    :deleted_at => proc { Time.now },
-    :deleted_by_id => proc { User.current.id if User.current }
-  }
-end
-```
-
-This changes the default abstract class from ActiveRecord::Base to a
-model called ArchiveModel.  This also sets the default fields to include
-a deleted_by_id which automatically sets the current user as the deleter
-of the record.
-
-Possible configuration options are listed in the _Usage_ section above.
 
 ### `Archive`
 
-Map the source model's schema to the archive model's and initiate the
+Map the source model's schema to the target model's and initiate the
 transfer through `Transfer`.  When `run` is called the Transfer is
 initialized with a primitive hash mapping the schema to the archive
 table.
@@ -44,7 +30,9 @@ Initialized with:
 ### `Restore`
 
 Map the archive model's schema to the source model's and initiate the
-transfer through `Transfer`
+transfer through `Transfer` When `run` is called the `Transfer` is
+initialized with a primitive hash mapping the schema from the archive
+table to the source table.
 
 Initialized with:
 
@@ -71,14 +59,15 @@ is bound to the `before_destroy` callback that performs the archiving
 functions.  Any of the code that handles ActiveRecord specific logic
 lives in here.
 
-Initialized with: *Config options from above*
+Initialized with: *Options for `Config` class*
 
 Attributes:
 
+* `model`: The AR model ths instance binds
 * `config`: Returns this model's config object
-* `model`: The AR model this instnace was created for
 
 Methods:
 
 * `before_destroy`: Perform the archive process
+* `self.add(klass)`: Performs patch to provided klass needed for binding
 

data/README.md

@@ -1,11 +1,12 @@
 # Undestroy
 
-Allow copying records to alternate table before destroying an
-ActiveRecord model for archiving purposes.  Data will be mapped
-one-to-one to the archive table schema.  Additional fields can also be
-configured for additional tracking information.  -Archive table schema
-will automatically be updated when the parent model's table is migrated
-through Rails.- (not yet)
+Provides automatic archiving of ActiveRecord models before the object is
+destroyed.  It is designed to be database agnostic and easy to extend
+with custom functionality.  Migrations will be run in parallel on the
+archive table when run on the original table.  Additional archive schema
+can be appended to the archive table for storing tracking data (default:
+deleted_at).
+
 
 ## Installation
 
@@ -41,23 +42,48 @@ class Person < ActiveRecord::Base
 end
 ```
 
-This method can also accept an options hash to further customize
-Undestroy to your needs.
+This method can also accept an options hash or block to further
+customize Undestroy to your needs.  Here are some of the common options:
 
 * `:table_name`:  use this table for archiving (Defaults to the
-  source class's table_name prefixed with "archive_").
+  source class's table_name prefixed with the :prefix option).
+* `:prefix`: use this prefix for table names -- if :table_name is set
+  this option does nothing (default: "archive_")
 * `:abstract_class`:  use this as the base class for the target_class
-  specify an alternate for custom extensions / DB connections (defaults
-  to ActiveRecord::Base)
-* `:fields`:  Specify a hash of fields to values for additional fields
-  you would like to include on the archive table -- lambdas will be
-  called with the instance being destroyed and returned value will be
-  used (default: `{ :deleted_at => proc { |instance| Time.now } }`).
-* `:migrate`:  Should Undestroy migrate the archive table together with
-  this model's table (default: true)
+  specify an alternate for custom extensions (defaults to
+  ActiveRecord::Base)
+* `:migrate`:  Determines whether Undestroy will handle automatic
+  migrations (default: true)
+* `:indexes`: When :migrate is true should indexes be migrated as well?
+  (default: false) 
+* `add_field(name, type, value=nil, &block)`:  method on the Config
+  object that configures a new field for the archive table.  The return
+  value of the block or value of `value` is used as the value of the 
+  field.  The block will be passed the instance of the object to be
+  archived as an argument.
+
+You can also use a block to handle the configuration:
+
+```ruby
+class Post < ActiveRecord::Base
+  undestroy do |config|
+    config.prefix = "old_"
+    config.add_field :deleted_by_id, :integer do |instance|
+      User.current.id if User.current
+    end
+  end
+end
+```
 
-Internal Options (for advanced users):
+Advanced Options:
 
+* `:fields`:  Specify a hash of Field objects describing additional
+  fields you would like to include on the archive table.  The preferred
+  method of specificying fields is through the add_field method with the
+  block configuration method.  (defaults to deleted_at timestamp).
+* `:model_paths`: Array of paths where Undestroy models live.  This is
+  used to autoload models before migrations are run (default:
+  `Rails.root.join('app', 'models')`).
 * `:source_class`:  the AR model of the originating data.  Set
   automatically to class `undestroy` method is called on.
 * `:target_class`:  use this AR model for archiving.  Set automatically
@@ -66,11 +92,19 @@ Internal Options (for advanced users):
   keys are `:archive`, `:transfer` and `:restore`.  Defaults to
   corresponding internal classes.  Customize to your heart's content.
 
-```
-$ person = Person.find(1)
-$ person.destroy
-# => Inserts person data into archive_people table
-# => Deletes person data from people table
+```ruby
+person = Person.create(:name => "Billy Mcgeeferson")
+# Creates a new person record in people table
+person.destroy
+# => Inserts record in archive_people table
+# => Deletes record from people table
+People.restore(person.id)
+People.archived.where(:name => "Billy Mcgeeferson").restore_all
+# => Two ways to restore the record back to the people table
+People.archived.find(person.id).restore_copy
+# => Restores the record, but doesn't remove the archived record
+People.find(person.id).destroy!
+# => Destroys the record without archiving
 ```
 
 ## Configuring
@@ -81,10 +115,9 @@ configuration block in your application initializer:
 ```ruby
 Undestroy::Config.configure do |config|
   config.abstract_class = ArchiveModelBase
-  config.fields = {
-    :deleted_at => proc { Time.now },
-    :deleted_by_id => proc { User.current.id if User.current }
-  }
+  config.add_field :deleted_by_id, :datetime do |instance|
+    User.current.id if User.current
+  end
 end
 ```
 
@@ -92,6 +125,18 @@ Options set in this block will be the default for all models with
 undestroy activated.  They can be overriden with options passed to the
 `undestroy` method
 
+## Architecture
+
+Checkout the ARCH.md file for docs on how the gem is setup internally,
+or just read the code.  My goal was to make it easy to understand and
+extend.
+
+Enjoy!
+
+## Acknowledgements
+
+* acts_as_archive author Winton Welsh for inspiration
+
 ## Contributing
 
 1. Fork it

data/lib/undestroy/binding.rb

@@ -3,6 +3,7 @@ module Undestroy::Binding
 
   def self.bind
     Undestroy::Binding::ActiveRecord.add(::ActiveRecord::Base)
+    Undestroy::Binding::ActiveRecord::MigrationStatement.add(::ActiveRecord::Migration)
   end
 end
 

data/lib/undestroy/binding/active_record.rb

@@ -1,13 +1,17 @@
 require 'active_record'
 
 class Undestroy::Binding::ActiveRecord
-  attr_accessor :config, :model
+
+  attr_accessor :config, :model, :active
+  alias :active? :active
 
   def initialize(model, options={})
     ensure_is_ar! model
 
     self.model = model
     self.config = Undestroy::Config.config.merge(options)
+    yield self.config if block_given?
+    self.active = true
 
     set_defaults
   end
@@ -16,11 +20,23 @@ class Undestroy::Binding::ActiveRecord
     config.internals[:archive].new(:config => config, :source => instance).run
   end
 
+  def prefix_table_name(name)
+    self.config.prefix.to_s + name.to_s
+  end
+
+  def deactivated
+    previously = self.active
+    self.active = false
+    yield
+  ensure
+    self.active = previously
+  end
+
   protected
 
   def set_defaults
     self.config.source_class = self.model
-    self.config.table_name ||= table_prefix + self.model.table_name if self.model.respond_to?(:table_name)
+    self.config.table_name ||= prefix_table_name(self.model.table_name) if self.model.respond_to?(:table_name)
     self.config.target_class ||= create_target_class
     ensure_is_ar! self.config.target_class
   end
@@ -29,13 +45,12 @@ class Undestroy::Binding::ActiveRecord
   def create_target_class
     Class.new(self.config.abstract_class || ActiveRecord::Base).tap do |target_class|
       target_class.table_name = self.config.table_name
+      target_class.class_attribute :undestroy_model_binding, :instance_writer => false
+      target_class.undestroy_model_binding = self
+      target_class.send :include, Restorable
     end
   end
 
-  def table_prefix
-    "archive_"
-  end
-
   def ensure_is_ar!(klass)
     raise ArgumentError, "#{klass.inspect} must be an ActiveRecord model" unless is_ar?(klass)
   end
@@ -47,17 +62,44 @@ class Undestroy::Binding::ActiveRecord
   # Add binding to the given class if it doesn't already have it
   def self.add(klass=ActiveRecord::Base)
     klass.class_eval do
-      class_attribute :undestroy_model_binding, :instance_writer => false
 
       def self.undestroy(options={})
-        before_destroy do
-          self.undestroy_model_binding.before_destroy(self) if undestroy_model_binding
-        end unless self.undestroy_model_binding
+        class_eval do
+          class_attribute :undestroy_model_binding, :instance_writer => false
+
+          before_destroy { undestroy_model_binding.before_destroy(self) }
+
+          def self.archived
+            undestroy_model_binding.config.target_class
+          end
+
+          def self.restore(*args)
+            [*archived.find(*args)].each(&:restore)
+          end
+
+          def destroy!
+            undestroy_model_binding.deactivated do
+              destroy
+            end
+          end
+
+        end unless respond_to?(:undestroy_model_binding)
+
         self.undestroy_model_binding = Undestroy::Binding::ActiveRecord.new(self, options)
       end
 
-    end unless klass.respond_to?(:undestroy_model_binding)
+
+    end unless klass.respond_to?(:undestroy)
+  end
+
+  def self.load_models(path)
+    Dir[File.join(path, '**', '*.rb')].each do |file|
+      require_dependency file
+    end
   end
 
 end
 
+require 'undestroy/binding/active_record/migration_statement'
+require 'undestroy/binding/active_record/restorable'
+

data/lib/undestroy/binding/active_record/migration_statement.rb

@@ -0,0 +1,118 @@
+
+class Undestroy::Binding::ActiveRecord::MigrationStatement
+
+  SCHEMA = [
+    :create_table, :drop_table, :rename_table,
+    :add_column, :rename_column, :change_column, :remove_column,
+  ]
+
+  INDEX = [
+    :add_index, :remove_index
+  ]
+
+  attr_accessor :method_name, :arguments, :block
+
+  def self.add(klass=ActiveRecord::Migration)
+    klass.class_eval do
+
+      def method_missing_with_undestroy(method, *args, &block)
+        original = method(:method_missing_without_undestroy)
+        original.call method, *args, &block
+        stmt = Undestroy::Binding::ActiveRecord::MigrationStatement.new(method, *args, &block)
+        stmt.run!(original) if stmt.run?
+      end
+
+      alias :method_missing_without_undestroy :method_missing
+      alias :method_missing :method_missing_with_undestroy
+
+    end
+  end
+
+  def initialize(method_name, *args, &block)
+    self.class.ensure_models_loaded
+    self.method_name = method_name
+    self.arguments = args
+    self.block = block
+  end
+
+  def source_table_name
+    self.arguments[0]
+  end
+
+  def target_table_name
+    config.target_class.table_name if config
+  end
+
+  def config
+    Undestroy::Config.catalog.select do |c|
+      c.source_class.respond_to?(:table_name) &&
+      c.source_class.table_name.to_s == source_table_name.to_s
+    end.first
+  end
+
+  def target_arguments
+    self.arguments.dup.tap do |args|
+      args[0] = target_table_name
+      args[1] = binding.prefix_table_name(args[1]) if rename_table?
+    end
+  end
+
+  def schema_action?
+    SCHEMA.include?(method_name)
+  end
+
+  def index_action?
+    INDEX.include?(method_name)
+  end
+
+  def run?
+    (
+      arguments.present? &&
+      config && config.migrate &&
+      !rename_table_exception? &&
+      (
+        schema_action? ||
+        index_action? && config.indexes
+      )
+    )
+  end
+
+  def run!(callable)
+    callable.call(method_name, *target_arguments, &block)
+
+    if create_table?
+      config.fields.values.sort.each do |field|
+        callable.call(:add_column, target_table_name, field.name, field.type)
+      end
+    end
+  end
+
+  def self.ensure_models_loaded
+    Undestroy::Config.config.model_paths.each do |path|
+      Undestroy::Binding::ActiveRecord.load_models(path)
+    end
+  end
+
+  protected
+
+  # We don't want to run rename_table on the target when the table name is
+  # explicitly set in the configuration.  The user must do manual migrating
+  # in that case.
+  def rename_table_exception?
+    rename_table? && config.table_name
+  end
+
+  def create_table?
+    method_name == :create_table
+  end
+
+  def rename_table?
+    method_name == :rename_table
+  end
+
+  def binding
+    config.source_class.undestroy_model_binding
+  end
+
+end
+

data/lib/undestroy/binding/active_record/restorable.rb

@@ -0,0 +1,28 @@
+module Undestroy::Binding::ActiveRecord::Restorable
+
+  def restore
+    restore_copy
+    destroy
+  end
+
+  def restore_copy
+    config = undestroy_model_binding.config
+    config.internals[:restore].new(:target => self, :config => config).run
+  end
+
+  module RelationExtensions
+
+    def restore_all
+      to_a.collect { |record| record.restore }.tap { reset }
+    end
+
+  end
+
+  def self.included(receiver)
+    receiver.send(:relation).singleton_class.class_eval do
+      include Undestroy::Binding::ActiveRecord::Restorable::RelationExtensions
+    end
+  end
+
+end
+