archivist 1.0.2 → 1.0.5

data/README.md

@@ -3,31 +3,160 @@ README.md
 
 This gem is intended as a direct replacement for acts\_as\_archive (AAA)
 in Rails 3 apps with most of the same functionality and wrapping AAA's 
-methods in aliases to maintain compatibilty for some time. Thanks to 
+methods in aliases to maintain compatibility for some time. Thanks to 
 [Winton Welsh](https://github.com/winton "Winton on github") for his 
 original work on AAA, it is good solution to a problem that makes 
 maintaining audit records a breeze.
 
-More Later
+TOC
+---
+1. <a href="#requirements">Requirements</a>
+2. <a href="#install">Install</a>
+2. <a href="#update_models">Update models</a>
+2. <a href="#add_archive_tables">Add Archive tables</a>
+1. <a href="#basic_usage">Basic Usage</a>
+1. <a href="#additional_options">Additional Options</a>
+    1. <a href="#multiple_archives">Allowing multiple archived copies</a>
+    1. <a href="#associating">Associating archive to original</a>
+    1. <a href="#including">Including External modules</a>
+    1. <a href="#customizing">Customizing `copy_self_to_archive`</a>
+1. <a href="#contributing">Contributing</a>
+1. <a href="#todo">TODO</a>
 
+<a name="requirements"></a>
+Requirements
+------------
+This gem is intended to be used with ActiveRecord/ActiveSupport 3.0.1 and later.
+
+<a name="install"></a>
+Install
+-------
+**Gemfile**:
+    gem 'archivist'
+
+<a name="update_models"></a>
+Update models
+-------------
+add `has_archive` to your models:
+    class SomeModel < ActiveRecord::Base
+      has_archive
+    end
+
+N.B. if you have any serialized attributes the has\_archive declaration *MUST* be after the serialization declarations or they will not be preserved and things will break when you try to deserialize the attributes. This is an unfortunate side effect of the declarative nature of both `serialize` and `has_archive` and I couldn't think of any way of getting around it that wouldn't make the entire gem really slow, any suggestions on this are welcome.
+
+i.e.
+    class AnotherModel < ActiveRecord::Base
+      serialize(:some_array,Array)
+      has_archive
+    end
+
+*NOT*
+    class ThisModel < ActiveRecord::Base
+      has_archive
+      serialize(:a_hash,Hash)
+    end
+
+<a name="add_archive_tables"></a>
+Add Archive tables
+------------------
+There are two ways to do this, the first is to use the built in updater like acts as archive.
+`Archivist.update SomeModel`
+Currently this doesn't support adding indexes automatically (AAA does) but I'm working on doing multi column indexes (any help is greatly appreciated)
+
+The second way of adding archive tables is to build a migration yourself, if you're wanting to keep track of who triggered the archive or inject some other information you'll have to add those columns manually and pass a block into `copy_self_to_archive` before calling `delete!` or `destroy!`.
+
+<a name="basic_usage"></a>
+Basic Usage
+-----------
+Use `destroy`, `delete`, `destroy_all` as usual and the data will get moved to the archive table. If you really want the data to go away you can still do so by simply calling `destroy!` etc. This bypasses the archiving step but leaves your callback chain intact where appropriate. 
+
+Migrations affecting the columns on the original model's table will be applied to the archive table as well.
+
+<a name="additional_options"></a>
+Additional Options
+------------------
+<a name="multiple_archives"></a>
+###Allowing multiple archived copies
+By default `copy_self_to_archive` just keeps updating a single instance of the archived record, this behavior is find if you're just trying to keep your main working table clean but can be problematic if you need a history of changes to a record.
+This behavior can be changed to allow multiple copies of a archived record to be created by setting the `:allow_multiple_archives` to true in the options hash when calling `has_archive`.
+
+####Example:
+<pre>
+  class SpecialModel &lt; AR::Base
+    has_archive :allow_multiple_archives=&gt; true
+  end
+</pre>
+
+<a name="associating"></a>
+### Associating archive to original
+The default here is to not associate the archived records in any way to the originals. But, if you're keeping a history of changes to a record the archived copies can be associated automatically with the 'original' by setting the `associate_with_original` option to true.
+
+*N.B.* Using this option automatically sets `allow_multiple_archives` to true
+
+####Example
+<pre>
+  class SpecialModel &lt; AR::Base
+    has_archive :associate_with_original=&gt;true
+  end
+</pre>
+
+allows for calls like:
+
+`SpecialModel.first.archived_special_models`
+
+or
+
+`SpecialModel::Archive.first.special_model`
+
+<a name="including"></a>
+###Including External modules
+If you want to include additional functionality in the `Archive` class you can pass in an array of module constants, this will allow adding scopes and methods to this class without any monkey patching.
+
+####Example
+<pre>
+  class MyModel &lt; AR:Base
+    has\_archive :included\_modules=&gt;BigBadModule
+  end
+</pre>
+or if multiple modules are needed
+<pre>
+  class MyModel &lt; AR:Base
+    has\_archive :included\_modules=&gt;[BigBadModule,MyScopes,MyArchiveMethods]
+  end
+</pre>
+
+<a name="customizing"></a>
+###Customizing copy\_self\_to\_archive
+A block can be passed into `copy_self_to_archive` which takes a single argument (the new archived record)
+
+####Example:
+Supposing we have added an archiver\_id column to our archive table we can pass a block into the `copy_self_to_archive` method setting this value. The block gets called immediately before saving the archived record so all of the attributes have been copied over from the original and are available for use in the block.
+<pre>
+  class SpecialModel &lt; AR:Base
+    has_archive
+    def archive!(user)
+      self.copy_self_to_archive do |archive|
+        archive.archiver_id = user.id
+      end
+    end
+  end
+</pre>
+
+<a name="contributing"></a>
+Contributing
+------------
+If you'd like to help out please feel free to fork and browse the TODO list below or  add a feature that you're in need of. Then send a pull request my way and I'll happily merge in well tested changes.
+
+Also, I use autotest and MySQL but [nertzy (Grant Hutchins)](https://github.com/nertzy "Grant on github") was kind enough to add support for testing against Postgres using the pg gem.
+
+<a name="todo"></a>
 TODO
------------------
-
-v1.0
-
- *  <del>License</del>
- *  <del>Base Module</del>
-     *  <del> Inserting Subclass (SomeModel::Archive) </del>
-     *  <del> Archive method </del>
-     *  <del> Intercept destroy/deletes </del>
-     *  <del>Restore archive</del>
-     *  <del> Build archive table for existing models </del>
- *  <del>Migrations Module</del>
-     *  <del>rewrite method_missing to act on the archived table</del>
-
-Future
-
- *  give subclass Archive its parent's methods
- *  give Archive relations
- *  give Archive scopes
- *  make archive\_all method chain-able with scopes 
+----
+
+ *  <del>Maintain seralized attributes from original model</del>
+ *  <del>allow passing of a block into copy\_to\_archive</del>
+ *  give Archive scopes from parent (may only work w/ 1.9 since scopes are Procs)
+ *  <del>give subclass Archive its parent's methods (method\_missing?)</del>
+ *  <del>associate SomeModel::Archive with SomeModel (if archiving more than one copy)</del>
+ *  associate Archive with other models (SomeModel.reflect\_on\_all\_associations?)
+ *  make archive\_all method chain-able with scopes and other finder type items

data/lib/archivist/archive.rb

@@ -0,0 +1,53 @@
+module Archivist
+  module ArchiveMethods
+    def self.included(base)
+      base.class_eval do
+        extend ArchiveClassMethods
+        protected :get_klass,:get_klass_name,:get_klass_instance_methods,:build_proxy_method
+      end
+    end
+
+    def method_missing(method,*args,&block)
+      if get_klass_instance_methods.include?(method.to_s)
+        build_proxy_method(method.to_s)
+        self.method(method).call(*args,&block)
+      else
+        super(method,*args,&block)
+      end
+    end
+
+    def respond_to?(method,include_private=false)
+      if get_klass_instance_methods.include?(method.to_s)
+        return true
+      else
+        super(method,include_private)
+      end
+    end
+
+    def get_klass
+      @klass ||= Kernel.const_get(get_klass_name)
+    end
+    
+    def get_klass_name
+      @klass_name ||= self.class.to_s.split("::").first
+    end
+
+    def get_klass_instance_methods
+      @klass_instance_methods ||= get_klass.instance_methods(false)
+    end
+    
+    def build_proxy_method(method_name)
+      class_eval <<-EOF
+        def #{method_name}(*args,&block)
+          instance = #{get_klass_name}.new
+          attrs = self.attributes.select{|k,v| #{get_klass.new.attribute_names.inspect}.include?(k.to_s)}
+          instance.attributes= attrs,false
+          instance.#{method_name}(*args,&block)
+        end
+      EOF
+    end
+
+    module ArchiveClassMethods;end
+  end
+end
+

data/lib/archivist/base/db.rb

@@ -5,10 +5,11 @@ module Archivist
       def self.included(base)
         base.send(:extend, ClassMethods)
         base.send(:include, InstanceMethods)
+        connection_class = base.connection.class.to_s.downcase
 
-        if base.connection.class.to_s.include?("Mysql")
+        if connection_class.include?("mysql")
           base.send(:extend, MySQL)
-        elsif base.connection.class.to_s.include?("Postgresql")
+        elsif connection_class.include?("postgresql")
           base.send(:extend, PostgreSQL)
         else
           raise "DB type not supported by Archivist!"
@@ -22,14 +23,21 @@ module Archivist
 
         def create_archive_table
           if table_exists? && !archive_table_exists?
-            cols = self.content_columns
+            cols = self.columns.reject { |column| column.name == primary_key }
             connection.create_table("archived_#{table_name}")
             cols.each do |c|
               connection.add_column("archived_#{table_name}",c.name,c.type)
             end
             connection.add_column("archived_#{table_name}",:deleted_at,:datetime)
+            if archive_options[:associate_with_original]
+              connection.add_column("archived_#{table_name}","#{self.new.class.to_s.underscore}_id",:integer)
+            end
           end
         end
+
+        def create_archive_indexes
+          # TODO?
+        end
       end
 
       module InstanceMethods

data/lib/archivist/base.rb

@@ -6,12 +6,18 @@ end
 
 module Archivist
   module Base
+
+    DEFAULT_OPTIONS = {:associate_with_original=>false,:allow_multiple_archives=>false}
+
     def self.included(base)
       base.extend ClassMethods
     end
     
     module ClassMethods
       def has_archive(options={})
+        options = DEFAULT_OPTIONS.merge(options)
+        options[:allow_multiple_archives] = true if options[:associate_with_original]
+        
         class_eval <<-EOF
           alias_method :delete!, :delete
           
@@ -22,6 +28,10 @@ module Archivist
           def self.archive_indexes
             #{Array(options[:indexes]).collect{|i| i.to_s}.inspect}
           end
+
+          def self.archive_options
+            #{options.inspect}
+          end
           
           def self.has_archive?
             true
@@ -31,11 +41,21 @@ module Archivist
             warn "DEPRECATION WARNING: #acts_as_archive is provided for compatibility with AAA and will be removed soon, please use has_archive?"
             has_archive?
           end
+
           class Archive < ActiveRecord::Base
             self.record_timestamps = false
             self.table_name = "archived_#{self.table_name}"
+            #{build_serialization_strings(self.serialized_attributes)}
+            #{build_belongs_to_association(options[:associate_with_original])}
+            #{build_inclusion_strings(options[:included_modules])}
+            include Archivist::ArchiveMethods
           end
+
+          #{build_has_many_association(options[:associate_with_original])}
+          
+          #{build_copy_self_to_archive(options[:allow_multiple_archives])}
         EOF
+        
         include InstanceMethods
         extend ClassExtensions
         include DB
@@ -44,11 +64,75 @@ module Archivist
       def acts_as_archive(options={})
         has_archive(options)
       end
+
+      def build_inclusion_strings(included_modules)
+        modules = ""
+        included_modules = [included_modules] unless included_modules.is_a?(Array)
+        included_modules.each do |mod|
+          modules << "include #{mod.to_s}\n"
+        end
+        return modules
+      end
+      
+      def build_serialization_strings(serializde_attributes)
+        serializations = ""
+        self.serialized_attributes.each do |key,value|
+          serializations << "serialize(:#{key},#{value.to_s})\n"
+        end
+        return serializations
+      end
+      
+      def build_has_many_association(associate=false)
+        associate ? "has_many :archived_#{self.table_name},:class_name=>'#{self.new.class.to_s}::Archive'" : ""
+      end
+      
+      def build_belongs_to_association(associate=false)
+        associate ? "belongs_to :#{self.table_name},:class_name=>'#{self.new.class.to_s}'" : ""
+      end
+      
+      def build_copy_self_to_archive(allow_multiple=false)
+        if allow_multiple #we put the original pk in the fk instead
+          "def copy_self_to_archive
+            self.class.transaction do
+              attrs = self.attributes.merge(:deleted_at=>DateTime.now)
+              archived = #{self.to_s}::Archive.new(attrs.reject{|k,v| k=='id'})
+              archived.#{self.to_s.underscore}_id = attrs['id']
+              #{yield_and_save}
+            end
+          end"
+        else
+          "def copy_self_to_archive
+            self.class.transaction do #it would be really shitty for us to loose data in the middle of this
+              attrs = self.attributes.merge(:deleted_at=>DateTime.now)
+              archived = #{self.to_s}::Archive.new
+              if archived.class.where(:id=>self.id).empty? #create a new one if necessary, else update
+                archived.id = attrs[\"id\"]
+                archived.attributes = attrs.reject{|k,v| k=='id'}
+              else
+                archived = archived.class.where(:id=>attrs[\"id\"]).first
+                archived.update_attributes(attrs)
+              end
+              #{yield_and_save}
+            end
+          end"
+        end
+      end
+
+      def yield_and_save
+        "yield(archived) if block_given?
+        archived.save"
+      end
+      
+      private :build_inclusion_strings,:build_serialization_strings,
+              :build_has_many_association,:build_belongs_to_association,
+              :build_copy_self_to_archive,:yield_and_save
     end
     
     module InstanceMethods #these defs can't happen untill after we've aliased their respective originals
+
       def delete
-        self.class.copy_to_archive({:id=>self.id}) unless new_record?
+        result = self.copy_self_to_archive unless new_record?
+        self.delete! if result
         @destroyed = true
         freeze
       end
@@ -68,25 +152,14 @@ module Archivist
       end
     end
 
-    module ClassExtensions #these can't get included in the class def untill after all aliases are done
-      def copy_to_archive(conditions,delete=true)
+    module ClassExtensions #these can't get included in the class def until after all aliases are done
+      def copy_to_archive(conditions,delete=true,&block)
         where = sanitize_sql(conditions)
         found = self.where(where)
         
         found.each do |m|
-          self.transaction do # I would hate for something to happen in the middle of all of this
-            attrs = m.attributes.merge(:deleted_at=>DateTime.now)
-            
-            if self::Archive.where(:id=>m.id).empty? #create a new one if necessary, else update
-              archived = self::Archive.new
-              archived.id = m.id
-              archived.attributes = attrs.reject{|k,v| k==:id}
-              archived.save
-            else
-              self::Archive.where(:id=>m.id).first.update_attributes(attrs)
-            end
-            m.destroy! if delete
-          end
+          result = m.copy_self_to_archive(&block)
+          m.destroy! if delete && result
         end
       end
       
@@ -101,7 +174,9 @@ module Archivist
 
         found.each do |m|
           self.transaction do
-            attrs = m.attributes.reject{|k,v| k=="deleted_at"}
+            my_attribute_names = self.new.attribute_names
+            #this should be Hash.select but 1.8.7 returns an array from select but a hash from reject... dumb
+            attrs = m.attributes.reject{|k,v| !my_attribute_names.include?(k.to_s)} 
 
             if self.where(:id=>m.id).empty?
               new_m = self.create(attrs)

data/lib/archivist.rb

@@ -1,4 +1,4 @@
-#require dependancies eventhough starting a rails app will already have them in place
+#require dependencies even though starting a rails app will already have them in place
 require 'rubygems'
 gem 'activerecord','~>3.0.1' #enforce rails 3+
 require 'active_record'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: archivist
 version: !ruby/object:Gem::Version 
-  hash: 19
-  prerelease: false
+  hash: 29
+  prerelease: 
   segments: 
   - 1
   - 0
-  - 2
-  version: 1.0.2
+  - 5
+  version: 1.0.5
 platform: ruby
 authors: 
 - Tyler Pickett
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-11 00:00:00 -06:00
+date: 2011-02-15 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -61,6 +61,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/archivist/archive.rb
 - lib/archivist/base/db.rb
 - lib/archivist/base.rb
 - lib/archivist/migration.rb
@@ -97,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.1
 signing_key: 
 specification_version: 3
 summary: A rails 3 model archiving system based on acts_as_archive