hierarchy_snapshot 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Shaun Mangelsdorf
+
+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.md

@@ -0,0 +1,80 @@
+# HierarchySnapshot
+
+This project adds the ability for ActiveRecord-based projects to automatically
+maintain a snapshot of an object hierarchy when it is updated.
+
+# Usage
+
+This example was hastily taken from the test cases:
+
+    class Parent < ActiveRecord::Base
+      has_many :children                         # Standard association
+
+      keep_hierarchy_snapshot do                 # Invoke the plugin
+        attrs :name                              # Attributes to retrieve from 'self'
+        many :children do                        # Associations to invoke on 'self'
+          attrs :name                            # Attributes to retrieve from each child
+          many :grandchildren do                 # Associations to invoke on each child
+            attrs :name                          # Attributes to retrieve from each grandchild
+          end
+        end
+      end
+    end
+
+When a parent object is created, like:
+
+    p = Parent.create :name => 'test',
+      :children_attributes => [ {:name => 'test2',
+        :grandchildren_attributes => [ {:name => 'test3'} ],
+    } ]
+
+This will create a snapshot containing a JSON object that looks like:
+
+    {"name":"test",
+      "children":[{"name":"test2",
+        "grandchildren":[{"name":"test3"}]
+      }]
+    }
+
+Creating a snapshot when the child records are updated directly requires:
+
+    p = Parent.find params[:id]
+    p.with_snapshot do
+      p.children.first.update_attributes! :name => 'test3'
+    end
+
+Creating an object without triggering a snapshot:
+
+    p = Parent.find params[:id]
+    p.without_snapshot do
+      p.update_attributes! :name => 'test2'
+    end
+
+Requiring a user to be recorded with a snapshot:
+
+    class Parent < ActiveRecord::Base
+      has_many :children
+
+      keep_hierarchy_snapshot do
+        require_user
+        attrs :name
+      end
+    end
+
+    p = Parent.find params[:id]
+    p.name = 'test2'
+    p.save                                       # Throws an exception
+    p.snapshot_user = current_user               # snapshot_user is automatically added to your snapshotted models
+    p.save                                       # Works correctly
+
+or
+
+    p = Parent.find params[:id]
+
+    p.with_snapshot do
+      p.children.create :name => 'test2'
+    end                                          # Throws an exception
+
+    p.with_snapshot current_user do
+      p.children.create :name => 'test2'
+    end                                          # Works correctly

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HierarchySnapshot'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/lib/generators/hierarchy_snapshot_migration/hierarchy_snapshot_migration_generator.rb

@@ -0,0 +1,16 @@
+# Released under the MIT license. See the LICENSE file for details
+
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record/migration'
+
+class HierarchySnapshotMigrationGenerator < Rails::Generators::NamedBase
+  include Rails::Generators::Migration
+  extend ActiveRecord::Generators::Migration
+
+  source_root File.join(File.dirname(__FILE__), 'templates')
+
+  def manifest
+    migration_template 'migration.rb', "db/migrate/#{file_name}"
+  end
+end

data/lib/generators/hierarchy_snapshot_migration/templates/migration.rb

@@ -0,0 +1,15 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+    create_table :hierarchy_snapshots, :force => true do |t|
+      t.references :source, :polymorphic => {}
+      t.references :user, :polymorphic => {}
+      t.text :data
+      t.timestamp :created_at
+    end
+    add_index :hierarchy_snapshots, [:source_id, :source_type], :name => 'source_index'
+  end
+
+  def self.down
+    drop_table :hierarchy_snapshots
+  end
+end

data/lib/hierarchy_snapshot.rb

@@ -0,0 +1,12 @@
+module HierarchySnapshot
+  autoload :ActiveRecord, 'hierarchy_snapshot/active_record'
+  autoload :Configuration, 'hierarchy_snapshot/configuration'
+
+  class Snapshot < ::ActiveRecord::Base
+    self.table_name = 'hierarchy_snapshots'
+    belongs_to :source, :polymorphic => true
+    belongs_to :user, :polymorphic => true
+  end
+end
+
+require 'hierarchy_snapshot/railtie' if defined? Rails

data/lib/hierarchy_snapshot/active_record.rb

@@ -0,0 +1,66 @@
+module HierarchySnapshot
+  module ActiveRecord
+    module ClassMethods
+      def keep_hierarchy_snapshot(&bl)
+        unless respond_to? :hierarchy_snapshot_save
+          send :include, InstanceMethods
+        end
+        after_create :hierarchy_snapshot_save
+        after_update :hierarchy_snapshot_save
+
+        class_attribute :hierarchy_snapshot_config
+        attr_accessor :snapshot_user
+        
+        self.hierarchy_snapshot_config = Configuration.new(true).tap{|c| c.instance_eval(&bl)}
+      end
+
+      def without_snapshot
+        old = Thread.current[:skip_hierarchy_snapshot]
+        begin
+          Thread.current[:skip_hierarchy_snapshot] = true
+          return yield
+        ensure
+          Thread.current[:skip_hierarchy_snapshot] = old
+        end
+      end
+    end
+
+    module InstanceMethods
+      def with_snapshot(user=nil)
+        self.snapshot_user = user
+        yield
+        hierarchy_snapshot_save
+      end
+
+      def without_snapshot(&bl)
+        self.class.without_snapshot(&bl)
+      end
+
+      def hierarchy_snapshot_save
+        return if Thread.current[:skip_hierarchy_snapshot]
+
+        if hierarchy_snapshot_config.require_user? and snapshot_user.nil?
+          raise 'No snapshot user was specified, but one is required'
+        end
+        Snapshot.create :source => self, :data => hierarchy_snapshot_data, :user => snapshot_user
+      end
+
+      def hierarchy_snapshot_data
+        hierarchy_snapshot_data_for(self, hierarchy_snapshot_config).to_json
+      end
+
+      def hierarchy_snapshot_data_for(obj, config)
+        {}.tap do |map|
+          config.attrs.each do |sym|
+            map[sym] = obj.send(sym)
+          end
+          config.many(nil).each do |sym, config|
+            map[sym] = obj.send(sym).to_a.collect do |child|
+              hierarchy_snapshot_data_for(child, config)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hierarchy_snapshot/configuration.rb

@@ -0,0 +1,28 @@
+module HierarchySnapshot
+  class Configuration
+    def initialize(top=false)
+      @top = top
+    end
+
+    def require_user
+      raise 'Only valid at top level' unless @top
+      @require_user = true
+    end
+
+    def require_user?
+      !!@require_user
+    end
+
+    def attrs(*args)
+      @attrs ||= []
+      @attrs += args.flatten
+      @attrs
+    end
+
+    def many(assoc, &bl)
+      @many ||= {}
+      @many[assoc] = Configuration.new.tap{|c| c.instance_eval(&bl)} unless assoc.nil?
+      @many
+    end
+  end
+end

data/lib/hierarchy_snapshot/railtie.rb

@@ -0,0 +1,10 @@
+require 'hierarchy_snapshot'
+require 'rails'
+
+module HierarchySnapshot
+  class Railtie < Rails::Railtie
+    initializer 'hierarchy_snapshot.active_record_hooks' do
+      ::ActiveRecord::Base.send :extend, HierarchySnapshot::ActiveRecord::ClassMethods
+    end
+  end
+end

data/lib/hierarchy_snapshot/version.rb

@@ -0,0 +1,3 @@
+module HierarchySnapshot
+  VERSION = "0.0.1"
+end

data/lib/tasks/hierarchy_snapshot_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :hierarchy_snapshot do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification 
+name: hierarchy_snapshot
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Shaun Mangelsdorf
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-11-20 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: rails
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        version: "3.0"
+    - - <
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 3
+        - 3
+        version: "3.3"
+  requirement: *id001
+  type: :development
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: rspec
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id002
+  type: :development
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: sqlite3
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id003
+  type: :development
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: ruby-debug
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  requirement: *id004
+  type: :development
+description: This project adds the ability for ActiveRecord-based projects to automatically maintain a snapshot of an object hierarchy when it is updated.
+email: 
+- s.mangelsdorf@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/hierarchy_snapshot/configuration.rb
+- lib/hierarchy_snapshot/version.rb
+- lib/hierarchy_snapshot/railtie.rb
+- lib/hierarchy_snapshot/active_record.rb
+- lib/tasks/hierarchy_snapshot_tasks.rake
+- lib/hierarchy_snapshot.rb
+- lib/generators/hierarchy_snapshot_migration/hierarchy_snapshot_migration_generator.rb
+- lib/generators/hierarchy_snapshot_migration/templates/migration.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: https://github.com/smangelsdorf/hierarchy_snapshot
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Add object hierarchy snapshot capabilities to ActiveRecord
+test_files: []
+