historical 0.2.1 → 0.2.2

data/.gitignore

@@ -2,4 +2,6 @@
 *.db
 *.log
 previous_failures.txt
-pkg
+/pkg
+/.yardoc
+/doc

data/README.markdown

@@ -0,0 +1,121 @@
+# Historical: Versioning and Auditing
+
+There are several plugins available for versioning (e.g. `acts_as_versioned`, `simply_versioned`, `vestal_versions`). Since they try to solve versioning using a relational database they require that you setup table for each model being versioned, clutter your main table or serialize your data into a single `TEXT` or `BLOB` field.
+
+Historical doesn't need to look for workarounds since it uses MongoDB as the backend, a document-database which does not require a fixed schema or table structure.
+
+
+## Rails Version
+
+Developed with/for Rails 3.0, installable using Bundler.
+
+
+## Usage Example
+
+    # models/message.rb
+    
+    class Message < ActiveRecord::Base
+      # string    :title
+      # text      :body
+      # datetime  :published_at
+      # integer   :author_id
+      
+      # This is unnecessary if you use Rails (will be installed by default on boot)
+      extend Historical::ActiveRecord
+      
+      is_historical
+    end
+    
+    # app.rb
+    
+    m = Message.create(:title => "foo", :author_id => 1)
+    m.author = Person.find(2)
+    m.title = "bar"
+    m.save!
+    
+    versions = m.history.versions.all
+    
+    # get old values
+    versions[0].title       #=> "foo"
+    versions[0].author_id   #=> 1
+    
+    # access an old relation
+    old = versions[0].restore     #=> <#Message>
+    old.author                    #=> User(id:1)
+    
+    # what changed?
+    versions[1].diff.to_hash      #=> { :author_id => [1, 2], :title => ["foo", "bar"] }
+    versions[1].diff.changes      #=> [<#AttributeDiff>, <#AttributeDiff>]
+    versions[1].meta.created_at   #=> 2010-01-23 18:56:52 (date when model was saved)
+    
+    
+## Audits (and other Meta-Data)
+
+As you have seen above each version contains a meta-object. You can write custom data to that meta object.
+
+    # YourApp.current_user could be set by a before_filter
+
+    class AuditedMessage < ActiveRecord::Base
+    
+      # This is unnecessary if you use Rails (will be installed by default on boot)
+      extend Historical::ActiveRecord
+      
+      is_historical do
+      
+        meta do
+          # extend that object with MongoMapper helpers
+          key :reason, String
+          
+          belongs_to_active_record :author, :required => true, :class_name => "Person"
+        end
+
+        callback do |version|
+          version.meta.author   = YourApp.current_user
+          version.meta.reason   = "some reason"
+        end
+      end
+    end
+    
+    Historical::Models::ModelVersion.where(:"meta.author_id" => 1).all
+    
+### `belongs_to_active_record`
+
+The MongoMapper extension `belongs_to_active_record` creates `belongs_to` (also polymorphic) relations and will
+handle key generation.
+
+
+## History Model (Quick Overview)
+
+When calling `model.history` you will get a object that contains several methods to operate with the history of a model.
+  
+ - `model.history.versions` will return a PQ containing all versions for that model. It's sorted ascending by creation date.
+ - `model.history.previous_version`, `model.history.next_version`, `model.history.latest_version`, `model.history.original_version` - you get it.
+ - `model.history.find_version(2)` like in `model.history.versions.all[2]` only handled by the database (less db-app traffic).
+ 
+### UseCase for `history.next_version`
+
+    old_message = message.history.original_version.restore
+    not_so_old_message = old_message.history.next_version.restore
+
+### Note: Plucky Query (PQ)
+
+MongoMapper - which is used by Historical - uses Plucky, a query generator. To perform the query you must call `.all` on it (similar to ActiveRecord).
+
+    
+## Interaction with 3rd Party Plugins
+
+Historical won't prevent your model from being destroyed. Should your model be destroyed all versions
+will be destroyed as well. However you might consider to use [`is_paranoid`](http://github.com/semanticart/is_paranoid)
+by [semanticart](http://github.com/semanticart) for that. Historical will then detect updates on the `deleted_at` column
+and store a new version.
+
+**Note:** `is_paranoid` was discontinued by **semanticart** in October 2009. I recommend to
+[read about the whys](http://blog.semanticart.com/killing_is_paranoid/). These are also the reasons
+why such feature isn't implemented in Historical by itself. You might want to use the
+[less hacky `is_paranoid`](http://github.com/mislav/is_paranoid) by [mislav](http://github.com/mislav),
+who developed `will_paginate`.
+
+
+## Intellectual Property
+
+Copyright (c) 2010 Marcel Jackwerth (marcel@northdocks.com). Released under the MIT licence.

data/Rakefile

@@ -34,12 +34,31 @@ task :spec => :check_dependencies
 
 task :default => :spec
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "historical #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+require 'yard'
+class YARD::Handlers::Ruby::Legacy::MongoHandler < YARD::Handlers::Ruby::Legacy::Base
+  handles /^(one|many|key)/
+
+  def process
+    match = statement.tokens.to_s.match(/^(one|many|key)\s+:([a-zA-Z0-9_]+)/)
+    return unless match
+    
+    type, method = match[1], match[2]
+    
+    case type
+    when "many"
+      register(MethodObject.new(namespace, method) do |obj|
+        if obj.tag(:return) && (obj.tag(:return).types || []).empty?
+          obj.tag(:return).types = ['Array']
+        elsif obj.tag(:return).nil?
+          obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Array"))
+        end
+      end)
+    else
+      register MethodObject.new(namespace, method)
+    end
+  end
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = FileList['lib/**/*.rb']
 end

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/historical.gemspec

@@ -5,30 +5,33 @@
 
 Gem::Specification.new do |s|
   s.name = %q{historical}
-  s.version = "0.2.1"
+  s.version = "0.2.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Marcel Jackwerth"]
-  s.date = %q{2010-08-26}
+  s.date = %q{2010-10-08}
   s.description = %q{Rewrite of the original historical-plugin using MongoDB}
   s.email = %q{marcel@northdocks.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.rdoc"
+     "README.markdown"
   ]
   s.files = [
     ".gitignore",
      "LICENSE",
-     "README.rdoc",
+     "README.markdown",
      "Rakefile",
      "VERSION",
      "historical.gemspec",
      "lib/historical.rb",
      "lib/historical/active_record.rb",
+     "lib/historical/class_builder.rb",
      "lib/historical/model_history.rb",
      "lib/historical/models/attribute_diff.rb",
-     "lib/historical/models/model_diff.rb",
      "lib/historical/models/model_version.rb",
+     "lib/historical/models/model_version/diff.rb",
+     "lib/historical/models/model_version/meta.rb",
+     "lib/historical/models/pool.rb",
      "lib/historical/mongo_mapper_enhancements.rb",
      "lib/historical/railtie.rb",
      "rails/init.rb",

data/lib/historical.rb

@@ -1,35 +1,50 @@
-require 'historical/railtie' if defined?(Rails::Railtie)
+require 'historical/railtie'
+require 'active_support'
 
+# Main module for the Historical gem
 module Historical
-  IGNORED_ATTRIBUTES = [:id, :created_at, :updated_at]
-  
-  autoload :ModelHistory, "historical/model_history"
-  autoload :ActiveRecord, "historical/active_record"
-  autoload :MongoMapperEnhancements, "historical/mongo_mapper_enhancements"
+  autoload :ModelHistory,             'historical/model_history'
+  autoload :ActiveRecord,             'historical/active_record'
+  autoload :ClassBuilder,             'historical/class_builder'
+  autoload :MongoMapperEnhancements,  'historical/mongo_mapper_enhancements'
   
+  # MongoDB models used by Historical are stored here
   module Models
-    module Pool
-      # cached classes are stored here
-      
-      def self.pooled(name)
-        @@class_pool ||= {}
-        return @@class_pool[name] if @@class_pool[name]
-        
-        cls = yield
-        
-        Historical::Models::Pool::const_set(name, cls)
-        @@class_pool[name] = cls
-        
-        cls
-      end
-      
-      def self.pooled_name(specialized_for, parent)
-        "#{specialized_for.name.demodulize}#{parent.name.demodulize}"
-      end
+    autoload :Pool,                   'historical/models/pool'
+    autoload :AttributeDiff,          'historical/models/attribute_diff'
+    autoload :ModelVersion,           'historical/models/model_version'
+  end
+  
+  IGNORED_ATTRIBUTES = [:id]
+  
+  @@historical_models = []  
+  @@booted = false
+  
+  mattr_reader :historical_models
+  def self.booted?; @@booted; end
+  
+  # Generates all customized models.
+  def self.boot!
+    return if booted?
+    
+    Historical::Models::Pool.clear!
+    Historical::Models::AttributeDiff.generate_subclasses!
+    
+    historical_models.each do |model|
+      model.generate_historical_models!
+    end
+    
+    @@booted = true
+    @@historical_models = ImmediateLoader.new
+  end
+  
+  class ImmediateLoader
+    def <<(model)
+      model.generate_historical_models!
     end
     
-    autoload :AttributeDiff,  'historical/models/attribute_diff'
-    autoload :ModelDiff,      'historical/models/model_diff'
-    autoload :ModelVersion,   'historical/models/model_version'
+    def each
+      false
+    end
   end
 end

data/lib/historical/active_record.rb

@@ -1,5 +1,6 @@
 module Historical
   module ActiveRecord
+    # converts database fieldtypes to Ruby types
     def self.sql_to_type(type)
       case type.to_sym
       when :datetime then "Time"
@@ -11,57 +12,136 @@ module Historical
       end
     end
     
-    def is_historical(&block)
-      class_eval do
-        cattr_accessor :historical_customizations, :historical_installed
+    # Extensions for a model that is flagged as `is_historical`.
+    module Extensions
+      extend ActiveSupport::Concern
+      
+      included do
+        cattr_accessor :historical_customizations, :historical_callbacks, :historical_installed
+        cattr_accessor :historical_meta_class, :historical_version_class, :historical_diff_class
+        
         attr_accessor :historical_differences, :historical_creation, :historical_version
         
-        # dirty attributes a removed after save, so we need to check it here
-        before_update do |record|
-          record.historical_differences = !record.changes.empty?
-          true
+        before_save :detect_version_spawn
+        after_save :invalidate_history!
+        after_save :spawn_version, :if => :spawn_version?
+        
+        attr_writer :history
+      end
+      
+      module ClassMethods
+        # Generates the customized classes ({Models::ModelVersion}, {Models::ModelVersion::Meta}, {Models::ModelVersion::Diff}) for this model.
+        def generate_historical_models!
+          builder = Historical::ClassBuilder.new(self)
+
+          self.historical_callbacks     ||= []
+          self.historical_callbacks     += builder.callbacks
+
+          self.historical_version_class = builder.version_class
+          self.historical_meta_class    = builder.meta_class
+          self.historical_diff_class    = builder.diff_class
         end
+      end
+      
+      module InstanceMethods
+        # @return [ModelHistory] The history of this model
+        def history
+          @history ||= Historical::ModelHistory.new(self)
+        end
+        
+        # @return [Integer] The version number of this model
+        def version
+          historical_version || history.own_version.version_index
+        end
+        
+        # Invalidates the history of that model
+        # @private
+        def invalidate_history!
+          @history = nil
+        end
+        
+        protected
         
-        # new_record flag is removed after save, so we need to check it here
-        before_save do |record|
-          record.historical_creation = record.new_record?
+        # Set some flags before saving the model (so that after_save-callbacks can be run)
+        # @private
+        def detect_version_spawn
+          if new_record?
+            self.historical_creation = true
+            self.historical_differences = []
+          else
+            self.historical_creation = false
+            self.historical_differences = (changes.empty? ? nil : changes)
+          end
+          
           true
         end
         
-        after_save do |record|
-          next unless record.historical_creation or record.historical_differences
+        # Check whether a new version should be spawned (also see {detect_version_spawn})
+        # @private
+        def spawn_version?
+          historical_creation or historical_differences
+        end
+        
+        # Spawns a new version
+        # @private
+        def spawn_version(mode = :update)
+          mode = :create if historical_creation
           
-          Historical::Models::ModelVersion.for_class(record.class).new.tap do |v|
-            v._record_id    = record.id
-            v._record_type  = record.class.name
+          Historical::Models::ModelVersion.for_class(self.class).new.tap do |v|
+            v._record_id    = id
+            v._record_type  = self.class.name
+            
             
-            record.attribute_names.each do |attr_name|
+            attribute_names.each do |attr_name|
               attr = attr_name.to_sym
               next if Historical::IGNORED_ATTRIBUTES.include? attr
-              v.send("#{attr}=", record[attr])
+              v.send("#{attr}=", self[attr])
+            end
+            
+            previous  = (mode != :create ? v.previous : nil)
+            
+            v.diff    = Historical::Models::ModelVersion::Diff.from_versions(previous, v)
+            v.meta    = self.class.historical_meta_class.new
+            
+            (self.class.historical_callbacks || []).each do |callback|
+              callback.call(v)
             end
             
-            v.diff = Historical::Models::ModelDiff.from_versions(v.previous, v)
             v.save!
           end
         end
-        
-        def history
-          @history ||= Historical::ModelHistory.new(self)
-        end
-        
-        def version
-          historical_version || history.own_version.version_index
-        end
       end
+    end
+  
+    # Enables Historical in this model.
+    #
+    # @example simple
+    #   class Message < ActiveRecord::Base
+    #     is_historical
+    #   end
+    #
+    # @example advanced, with custom meta-data (auditing)
+    #   class Message < ActiveRecord::Base
+    #     is_historical do
+    #       meta do
+    #         belongs_to_active_record :user
+    #         key :cause, String
+    #       end
+    #     
+    #       callback do |version|
+    #         version.meta.cause  = "just because"
+    #         version.meta.user   = App.current_user
+    #       end
+    #     end
+    #   end
+    def is_historical(&block)
+      include Historical::ActiveRecord::Extensions
       
       self.historical_installed         = true
       self.historical_customizations    ||= []
       self.historical_customizations    << block if block_given?
       
-      # generate pooled classes
-      Historical::Models::ModelDiff.for_class(self)
-      Historical::Models::ModelVersion.for_class(self)
+      Historical.historical_models      << self
     end
   end
 end