memento 0.3.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Yolk Sebastian Munz & Julia Soergel GbR
+
+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.rdoc

@@ -0,0 +1,85 @@
+= memento
+
+RubyGem/Plugin for undo in Rails/ActiveRecord - covers destroy, update and create actions.
+
+== Install
+
+memento will only work with Rails 2.3 or above.
+
+== as a ruby-gem
+
+Add this line to your config/environment.rb:
+
+  config.gem "yolk-memento", :lib => 'memento', :source => 'http://gems.github.com'
+
+and run
+
+  rake gems:install
+
+=== as rails plugin
+
+  script/plugin install git://github.com/yolk/memento.git
+
+== Setup
+
+memento needs two tables in your database, one to store "sessions" (sets of states) and the other to store "states" (aka snapshots of single models). To generate the necessary migration and migrate your database run:
+
+  script/generate memento_migration
+  rake db:migrate
+  
+memento assumes you have a user-model. Every session is owned by a user.
+  
+== Configure your models
+
+Then you have to tell every model you want to undo actions on that it should be watched by memento:
+
+  class Person < ActiveRecord::Base
+    memento_changes
+  end
+
+This will tell memento to create snapshots of the model when an new instance is created, an exisiting one is updated or destroyed.
+
+If you want memento to only take snapshots on specific actions:
+
+  memento_changes :update, :destroy
+  
+This will take a snapshot only when an instance is updated or destroyed.
+
+By default memento will ignore changes to the :updated_at and :created_at attributes. You can add further attributes to ignore with the :ignore option:
+
+  memento_changes :ignore => [:calculated_birthday, :friends_count]
+  
+This will ignore changes on the calculated_birthday and the firends_count-attributes. When memento saves a whole instance of your model before it is destroyed, those attributes will not be stored for later recovery. Only ignore attributes you can re-calculate from other data!
+
+== Action!
+
+When you perform any of the configured actions on your model in isolation in your controller memento will not store any changes:
+
+  Person.create!(:name => "Blah")
+  Memento::Session.count # => 0
+  
+You have to wrap every action block you want memento to track in your controller with the memento-method:
+
+  memento do
+    Person.create!(:name => "Blah")
+  end
+  Memento::Session.count # => 1
+  
+This assumes there is an method called "current_user" in your controllers. It will set the HTTP-Header 'X-Memento-Session-Id' on your response.
+
+If you want memento to watch changes outside of your controllers (for example inside the console) you can use:
+
+  Memento.instance.memento(user) do
+    Person.create!(:name => "Blah")
+  end
+  
+Where the variable user is assumed to hold an instance of User.
+
+== Undo!
+
+Undoing this changes is as simple as calling #undo on an memento-session-instance.
+
+  Memento::Session.first.undo
+
+
+Copyright (c) 2009-2010 Yolk Sebastian Munz & Julia Soergel GbR. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "memento"
+    gem.summary = %Q{Undo for Rails/ActiveRecord - covers destroy, update and create}
+    gem.email = "sebastian@yo.lk"
+    gem.homepage = "http://github.com/yolk/memento"
+    gem.authors = ["Yolk Sebastian Munz & Julia Soergel GbR"]
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new  
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+

data/TODO

@@ -0,0 +1,3 @@
+* [DONE] scrip/generate memento_migration
+* configs for current_user & User-Object
+* [DONE] readme/documentation

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:build: 
+:patch: 0
+:major: 0
+:minor: 3

data/generators/memento_migration/memento_migration_generator.rb

@@ -0,0 +1,10 @@
+class MementoMigrationGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.migration_template("migration.rb", 'db/migrate',
+                           :assigns => {  },
+                           :migration_file_name => "memento_migration"
+                           )
+    end
+  end
+end

data/generators/memento_migration/templates/migration.rb

@@ -0,0 +1,23 @@
+class MementoMigration < ActiveRecord::Migration
+  
+  def self.up
+    create_table :memento_sessions do |t|
+      t.references :user
+      t.timestamps
+    end
+  
+    create_table :memento_states do |t|
+      t.string :action_type
+      t.binary :record_data, :limit => 1.megabytes
+      t.references :record, :polymorphic => true
+      t.references :session
+      t.timestamps
+    end
+  end
+  
+  def self.down
+    drop_table :memento_states
+    drop_table :memento_sessions
+  end
+  
+end

data/lib/memento.rb

@@ -0,0 +1,59 @@
+class Memento
+  include Singleton
+  
+  class ErrorOnRewind < StandardError;end
+  
+  def memento(user)
+    start(user)
+    yield
+    !@session.states.count.zero? && @session rescue false
+  ensure
+    stop
+  end
+  
+  def start(user_or_id)
+    user = User.find_by_id(user_or_id)
+    @session = user ? Memento::Session.new(:user => user) : nil
+  end
+  
+  def stop
+    @session.destroy if @session && @session.states.count.zero?
+    @session = nil
+  end
+  
+  def add_state(action_type, record)
+    return unless save_session
+    @session.add_state(action_type, record)
+  end
+  
+  def active?
+    !!(defined?(@session) && @session) && !ignore?
+  end
+  
+  def ignore
+    @ignore = true
+    yield
+  ensure
+    @ignore = false
+  end
+  
+  cattr_accessor :serializer
+  self.serializer = YAML
+  
+  private
+  
+  def ignore?
+    defined?(@ignore) && @ignore
+  end
+  
+  def save_session
+    active? && (!@session.changed? || @session.save)
+  end
+end
+
+require 'memento/result'
+require 'memento/action'
+require 'memento/active_record_methods'
+require 'memento/action_controller_methods'
+require 'memento/state'
+require 'memento/session'

data/lib/memento/action.rb

@@ -0,0 +1,40 @@
+module Memento::Action
+  class Base
+    def initialize(state)
+      @state = state
+    end
+    
+    attr_reader :state
+    
+    def record
+      @state.record
+    end
+    
+    def record_data
+      @state.record_data
+    end
+    
+    def fetch?
+      true
+    end
+    
+    def self.inherited(child)
+      action_type = child.name.demodulize.underscore
+      write_inheritable_attribute(:action_types, action_types << action_type)
+    end
+    
+    def self.action_types
+      read_inheritable_attribute(:action_types) || []
+    end
+    
+    private
+    
+    def new_object
+      object = @state.record_type.constantize.new
+      yield(object) if block_given?
+      object
+    end
+  end
+end
+
+Dir["#{File.dirname(__FILE__)}/action/*.rb"].each { |action| require action }

data/lib/memento/action/create.rb

@@ -0,0 +1,37 @@
+class Memento::Action::Create < Memento::Action::Base
+  
+  def fetch;end
+  
+  def undo
+    if record.nil?
+      build_fake_object
+    elsif record_was_changed?
+      was_changed
+    else
+      destroy_record
+    end
+  end
+  
+  private
+  
+  def record_was_changed?
+    record.updated_at > record.created_at rescue false
+  end
+  
+  def build_fake_object
+    new_object do |object|
+      object.id = state.record_id
+    end
+  end
+  
+  def was_changed
+    record.errors.add(:memento_undo, ActiveSupport::StringInquirer.new("was_changed"))
+    record
+  end
+  
+  def destroy_record
+    record.destroy
+    record
+  end
+  
+end

data/lib/memento/action/destroy.rb

@@ -0,0 +1,30 @@
+class Memento::Action::Destroy < Memento::Action::Base
+  
+  def fetch
+    record.attributes_for_memento
+  end
+  
+  def undo
+    rebuild_object do |object|
+      begin
+        object.save!
+      rescue
+        object.id = nil
+        object.save!
+      end
+      state.update_attribute(:record, object)
+    end
+  end
+  
+  private
+  
+  def rebuild_object
+    new_object do |object|
+      state.record_data.each do |attribute, value|
+        object.send(:"#{attribute}=", value)
+      end
+      yield(object) if block_given?
+    end
+  end
+  
+end

data/lib/memento/action/update.rb

@@ -0,0 +1,55 @@
+class Memento::Action::Update < Memento::Action::Base
+  
+  def fetch
+    record.changes_for_memento
+  end
+  
+  def fetch?
+    record.changes_for_memento.any?
+  end
+  
+  def undo
+    if !record
+      was_destroyed
+    elsif mergable?
+      update_record
+    else
+      was_changed
+    end
+  end
+  
+  private
+  
+  def update_record
+    returning(record) do |object|
+      record_data.each do |attribute, values|
+        object.send(:"#{attribute}=", values.first)
+      end
+      object.save!
+    end
+  end
+  
+  def mergable?
+    record_data.all? do |attribute, values|
+      # ugly fix to compare times
+      values = values.map{|v| v.is_a?(Time) ? v.to_s(:db) : v }
+      current_value = record.send(:"#{attribute}")
+      current_value = current_value.utc.to_s(:db) if current_value.is_a?(Time)
+      
+      values.include?(current_value) 
+    end || record_data.size.zero?
+  end
+  
+  def was_destroyed
+    new_object do |object|
+      object.errors.add(:memento_undo, ActiveSupport::StringInquirer.new("was_destroyed"))
+      object.id = state.record_id
+    end
+  end
+  
+  def was_changed
+    record.errors.add(:memento_undo, ActiveSupport::StringInquirer.new("was_changed"))
+    record
+  end
+  
+end

data/lib/memento/action_controller_methods.rb

@@ -0,0 +1,19 @@
+class Memento
+  module ActionControllerMethods
+    
+    private
+    
+    def memento
+      block_result = nil
+      memento_session = Memento.instance.memento(current_user) do
+        block_result = yield
+      end
+      if memento_session
+        response.headers["X-Memento-Session-Id"] = memento_session.id.to_s
+      end
+      block_result
+    end
+  end
+end
+
+ActionController::Base.send(:include, Memento::ActionControllerMethods) if defined?(ActionController::Base)