magic_userstamp 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.*~
+*.log
+*.sqlite3
+/coverage
+/pkg

data/CHANGELOG

@@ -0,0 +1,26 @@
+2.0 (2-17-2008)
+    * [Ben  Wyrosdick] - Added a migration helper that gives migration scripts a <tt>userstamps</tt>
+                         method.
+    * [Marshall Roch]  - Stamping can be temporarily turned off using the 'without_stamps' class
+                         method. 
+      Example:
+        Post.without_stamps do
+          post = Post.find(params[:id])
+          post.update_attributes(params[:post])
+          post.save
+        end
+
+    * Models that should receive updates made by 'stampers' now use the acts_as_stampable class
+      method. This sets up the belongs_to relationships and also injects private methods for use by
+      the individual callback filter methods.
+
+    * Models that are responsible for updating now use the acts_as_stamper class method. This
+      injects the stamper= and stamper methods that are thread safe and should be updated per
+      request by a controller.
+
+    * The Userstamp module is now meant to be included with one of your project's controllers (the
+      Application Controller is recommended). It creates a before filter called 'set_stampers' that
+      is responsible for setting all the current Stampers.
+
+1.0 (01-18-2006)
+    * Initial Release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2008 DeLynn Berry
+
+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.original

@@ -0,0 +1,179 @@
+= Userstamp Plugin (v 2.0)
+
+== Overview
+
+The Userstamp Plugin extends ActiveRecord::Base[http://api.rubyonrails.com/classes/ActiveRecord/Base.html] to add automatic updating of 'creator',
+'updater', and 'deleter' attributes. It is based loosely on the ActiveRecord::Timestamp[http://api.rubyonrails.com/classes/ActiveRecord/Timestamp.html] module.
+
+Two class methods (<tt>model_stamper</tt> and <tt>stampable</tt>) are implemented in this plugin.
+The <tt>model_stamper</tt> method is used in models that are responsible for creating, updating, or
+deleting other objects. The <tt>stampable</tt> method is used in models that are subject to being
+created, updated, or deleted by 'stampers'.
+
+
+== Installation
+Installation of the plugin can be done using the built in Rails plugin script. Issue the following
+command from the root of your application:
+
+  script/plugin install git://github.com/delynn/userstamp.git
+
+Once installed you will need to restart your application for the plugin to be loaded into the Rails
+environment.
+
+You might also be interested in using Piston[http://piston.rubyforge.org/index.html] to manage the
+importing and future updating of this plugin.
+
+== Usage
+In this new version of the Userstamp plug-in, the assumption is that you have two different
+categories of objects; those that mani˝pulate, and those that are manipulated. For those objects
+that are being manipulated there's the Stampable module and for the manipulators there's the
+Stamper module. There's also the actual Userstamp module for your controllers that assists in
+setting up your environment on a per request basis.
+
+To better understand how all this works, I think an example is in order. For this example we will
+assume that a weblog application is comprised of User and Post objects. The first thing we need to
+do is create the migrations for these objects, and the plug-in gives you a <tt>userstamps</tt>
+method for very easily doing this:
+
+  class CreateUsers < ActiveRecord::Migration
+    def self.up
+      create_table :users, :force => true do |t|
+        t.timestamps
+        t.userstamps
+        t.name
+      end
+    end
+    
+    def self.down
+      drop_table :users
+    end
+  end
+  
+  class CreatePosts < ActiveRecord::Migration
+    def self.up
+      create_table :posts, :force => true do |t|
+        t.timestamps
+        t.userstamps
+        t.title
+      end
+    end
+    
+    def self.down
+      drop_table :posts
+    end
+  end
+
+Second, since Users are going to manipulate other objects in our project, we'll use the
+<tt>model_stamper</tt> method in our User class:
+
+  class User < ActiveRecord::Base
+    model_stamper
+  end
+
+Finally, we need to setup a controller to set the current user of the application. It's
+recommended that you do this in your ApplicationController:
+
+  class ApplicationController < ActionController::Base
+    include Userstamp
+  end
+
+If all you are interested in is making sure all tables that have the proper columns are stamped
+by the currently logged in user you can stop right here. More than likely you want all your
+associations setup on your stamped objects, and that's where the <tt>stampable</tt> class method
+comes in. So in our example we'll want to use this method in both our User and Post classes:
+
+  class User < ActiveRecord::Base
+    model_stamper
+    stampable
+  end
+  
+  class Post < ActiveRecord::Base
+    stampable
+  end
+
+Okay, so what all have we done? The <tt>model_stamper</tt> class method injects two methods into the
+User class. They are #stamper= and #stamper and look like this:
+
+  def stamper=(object)
+    object_stamper = if object.is_a?(ActiveRecord::Base)
+      object.send("#{object.class.primary_key}".to_sym)
+    else
+      object
+    end
+    
+    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"] = object_stamper
+  end
+
+  def stamper
+    Thread.current["#{self.to_s.downcase}_#{self.object_id}_stamper"]
+  end
+
+The big change with this new version is that we are now using Thread.current to save the current
+stamper so as to avoid conflict with concurrent requests.
+
+The <tt>stampable</tt> method allows you to customize what columns will get stamped, and also
+creates the +creator+, +updater+, and +deleter+ associations.
+
+The Userstamp module that we included into our ApplicationController uses the setter method to
+set which user is currently making the request. By default the 'set_stampers' method works perfectly
+with the RestfulAuthentication[http://svn.techno-weenie.net/projects/plugins/restful_authentication] plug-in:
+
+  def set_stampers
+    User.stamper = self.current_user
+  end
+
+If you aren't using ActsAsAuthenticated, then you need to create your own version of the
+<tt>set_stampers</tt> method in the controller where you've included the Userstamp module.
+
+Now, let's get back to the Stampable module (since it really is the interesting one). The Stampable
+module sets up before_* filters that are responsible for setting those attributes at the appropriate
+times. It also creates the belongs_to relationships for you.
+
+If you need to customize the columns that are stamped, the <tt>stampable</tt> method can be
+completely customized. Here's an quick example:
+
+  class Post < ActiveRecord::Base
+    acts_as_stampable :stamper_class_name => :person,
+                      :creator_attribute  => :create_user,
+                      :updater_attribute  => :update_user,
+                      :deleter_attribute  => :delete_user
+  end
+
+If you are upgrading your application from the old version of Userstamp, there is a compatibility
+mode to have the plug-in use the old "_by" columns by default. To enable this mode, add the
+following line to the RAILS_ROOT/config/environment.rb file:
+
+  Ddb::Userstamp.compatibility_mode = true
+  
+If you are having a difficult time getting the Userstamp plug-in to work, I recommend you checkout
+the sample application that I created. You can find this application on GitHub[http://github.com/delynn/userstamp_sample]
+
+== Uninstall
+Uninstalling the plugin can be done using the built in Rails plugin script. Issue the following
+command from the root of your application:
+
+  script/plugin remove userstamp
+
+
+== Documentation
+RDoc has been run on the plugin directory and is available in the doc directory.
+
+
+== Running Unit Tests
+There are extensive unit tests in the "test" directory of the plugin. These test can be run
+individually by executing the following command from the userstamp directory:
+
+ ruby test/compatibility_stamping_test.rb
+ ruby test/stamping_test.rb
+ ruby test/userstamp_controller_test.rb
+
+
+== Bugs & Feedback
+Bug reports and feedback are welcome via my delynn+userstamp@gmail.com email address. I also
+encouraged everyone to clone the git repository and make modifications--I'll be more than happy
+to merge any changes from other people's branches that would be beneficial to the whole project.
+
+
+== Credits and Special Thanks
+The original idea for this plugin came from the Rails Wiki article entitled
+{Extending ActiveRecord}[http://wiki.rubyonrails.com/rails/pages/ExtendingActiveRecordExample].

data/README.rdoc

@@ -0,0 +1,64 @@
+= MagicUserstamp
+
+== Install
+
+=== as a plugin
+ ruby script/plugin install git://github.com/akm/magic_userstamp.git
+
+=== as a gem
+insert following line to config/environment.rb
+  config.gem 'magic_userstamp', :version => '0.1.0'
+and 
+ $ sudo rake gems:install
+
+Or install gem manually
+
+ $ sudo gem install gemcutter
+ $ sudo gem tumble
+ $ sudo gem install magic_userstamp
+
+== Setting
+make config/initializers/magic_userstamp.rb
+
+The most simple setting
+ Userstamp::Config.setup.defaults
+
+Specify User class name
+ Userstamp::Config.setup.defaults(:stamper_class_name => 'AdminUser')
+
+Actually
+ Userstamp::Config.setup.defaults
+means
+ Userstamp.config.setup do |config|
+   config.with_options(:stamper_class_name => 'User') do |c|
+     c.on(:create , :creator_id)
+     c.on(:update , :updater_id)
+     c.on(:destroy, :deleter_id)
+   end
+ end
+
+
+Specify User class name and creator/updater columns
+ Userstamp.config.setup do |config|
+   config.with_options(:stamper_class_name => 'Person') do |c|
+     c.on(:create , :creator_person_id)
+     c.on(:update , :updater_person_id)
+     c.on(:destroy, :deleter_person_id)
+   end
+ end
+
+Specify target stampable class names
+ Userstamp.config.setup do |config|
+   config.defaults(:stampable_class_names => %w(Book Schedule))
+
+Specify target stampable class names and columns
+ Userstamp.config.setup do |config|
+   config.with_options(:stampable_class_names => %w(Book Schedule)) do |c|
+     c.on(:create , :creator_user_id)
+     c.on(:update , :updater_user_id)
+     c.on(:destroy, :deleter_user_id)
+   end
+ end
+
+-----
+Copyright (c) 2009 'Takeshi AKIMA, released under the MIT license

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "magic_userstamp"
+    gem.summary = %Q{creator_id/updater_id/deleter_id support with setting outside models}
+    gem.description = %Q{This Rails plugin extends ActiveRecord::Base to add automatic updating of created_by and updated_by attributes of your models in much the same way that the ActiveRecord::Timestamp module updates created_(at/on) and updated_(at/on) attributes.}
+    gem.email = "akm2000@gmail.com"
+    gem.homepage = "http://github.com/akm/magic_userstamp"
+    gem.authors = ["akimatter"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+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 :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 = "magic_userstamp #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+require 'userstamp'
+# コントローラへは自身でincludeしてください。
+# ActionController::Base.send(:include, Userstamp::Controller) if defined?(ActionController)
+ActiveRecord::ConnectionAdapters::TableDefinition.send(:include, Userstamp::MigrationHelper)
+if defined?(ActiveRecord)
+  ActiveRecord::Base.module_eval do 
+    include Userstamp::Stampable
+    include Userstamp::Stamper
+    include Userstamp::MagicColumns # mest be included after Userstamp::Stampable
+  end
+end

data/lib/userstamp/config.rb

@@ -0,0 +1,119 @@
+# -*- coding: utf-8 -*-
+require 'userstamp'
+
+module Userstamp
+
+  def self.config
+    Config.instance
+  end
+  
+  class Config
+
+    class << self
+      def instance
+        @instance || setup
+      end
+      
+      def setup
+        @instance = Config.new
+        yield(@instance) if block_given?
+        @instance
+      end
+
+      def clear
+        @instance = nil
+      end
+    end
+
+    attr_reader :patterns
+    attr_accessor :with_destroy
+    attr_accessor :verbose
+
+    def initialize
+      @patterns = []
+      @with_destroy = defined?(Caboose::Acts::Paranoid)
+    end
+    
+    def pattern_for(klass, column_name)
+      patterns.detect{|pattern| pattern.stampable?(klass, column_name)}
+    end
+
+    def on(event_name, column_name, options = nil)
+      result = Pattern.new(event_name, column_name, options)
+      patterns << result
+      result
+    end
+
+    def defaults(options = nil)
+      on(:create , :creator_id, options)
+      on(:update , :updater_id, options)
+      on(:destroy, :deleter_id, options) if with_destroy
+    end
+
+    def compatibles(options = nil)
+      on(:create , :created_by, options)
+      on(:update , :updated_by, options)
+      on(:destroy, :deleted_by, options) if with_destroy
+    end
+
+    def verbose?(klass, column_name)
+      case verbose
+      when Hash then
+        verbose_match?(verbose, klass, column_name)
+      when Array then
+        verbose.any?{|setting| verbose_match?(setting, klass, column_name)}
+      else
+        !!verbose
+      end
+    end
+
+    private
+
+    def verbose_match?(setting, klass, column_name)
+      classes = []
+      columns = []
+      {:classes => classes, :columns => columns}.each do |key, dest|
+        if value = setting[key]
+          dest.concat(value.is_a?(Array) ? value : [value])
+        end
+      end
+      classes = classes.map{|s| s.to_s}
+      columns = columns.map{|s| s.to_s}
+      (classes.empty? || classes.include?(klass.name)) && 
+        (columns.empty? || columns.include?(column_name.to_s))
+    end
+ 
+     
+    class Pattern
+      attr_reader :event_name, :column_name, :stampable_class_names
+      attr_reader :stamper_class_name, :stamper_attr_name
+      attr_reader :options_for_stampable_on
+      
+      def initialize(event_name, column_name, options = nil)
+        @event_name = event_name
+        @column_name = column_name
+        options = {
+          :stampable_class_names => nil,
+          :stamper_class_name => 'User',
+          :stamper_attr_name => nil # sholuld not be only 'id' but PK column name
+        }.update(options || {})
+        @stampable_class_names = options.delete(:stampable_class_names)
+        Userstamp.raise_unless_valid_options_for_stampable_on(options)
+        @options_for_stampable_on = options
+        @stamper_class_name = options[:stamper_class_name]
+        @stamper_attr_name = options[:stamper_attr_name]
+      end
+      
+      def stampable?(klass, column_name)
+        (stampable_class_names.nil? ? true : stampable_class_names.include?(klass.name)) &&
+          (column_name.to_s == self.column_name.to_s)
+      end
+
+      def args_for_stampable_on(column_name = nil)
+        [event_name, {:attribute => column_name || self.column_name}.update(@options_for_stampable_on)]
+      end
+      
+    end
+
+  end
+end

data/lib/userstamp/controller.rb

@@ -0,0 +1,43 @@
+require 'userstamp'
+
+module Userstamp
+  module Controller
+    # The Userstamp module, when included into a controller, adds a before filter
+    # (named <tt>set_stamper</tt>) and an after filter (name <tt>reset_stamper</tt>).
+    # These methods assume a couple of things, but can be re-implemented in your
+    # controller to better suite your application.
+    #
+    # See the documentation for <tt>set_stamper</tt> and <tt>reset_stamper</tt> for
+    # specific implementation details.
+
+    def self.included(base) # :nodoc:
+      base.send           :include, InstanceMethods
+      base.before_filter  :set_stamper
+      base.after_filter   :reset_stamper
+    end
+
+    module InstanceMethods
+      private
+        # The <tt>set_stamper</tt> method as implemented here assumes a couple
+        # of things. First, that you are using a +User+ model as the stamper
+        # and second that your controller has a <tt>current_user</tt> method
+        # that contains the currently logged in stamper. If either of these
+        # are not the case in your application you will want to manually add
+        # your own implementation of this method to the private section of
+        # the controller where you are including the Userstamp module.
+        def set_stamper
+          User.stamper = self.current_user
+        end
+
+        # The <tt>reset_stamper</tt> method as implemented here assumes that a
+        # +User+ model is being used as the stamper. If this is not the case then
+        # you will need to manually add your own implementation of this method to
+        # the private section of the controller where you are including the
+        # Userstamp module.
+        def reset_stamper
+          User.reset_stamper
+        end
+      #end private
+    end
+  end
+end

data/lib/userstamp/event.rb

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+require 'userstamp'
+
+module Userstamp
+
+  class Event 
+    attr_reader :name, :actor, :actual_hook, :after_callback
+    attr_reader:default_attribute, :default_attribute_compatible
+
+    def initialize(name, actor, default_attribute_compatible, options = nil)
+      @name, @actor = name.to_s, actor.to_s
+      @default_attribute = "#{@actor}_id"
+      @default_attribute_compatible = default_attribute_compatible
+      options = {
+        :actual_hook => "before_#{@name.to_s}"
+      }.update(options || {})
+      @actual_hook = options[:actual_hook]
+      @after_callback = options[:after_callback]
+    end
+    
+    class << self
+      def create(name, actor, default_attribute_compatible, options = nil, &block)
+        result = self.new(name, actor, default_attribute_compatible, options, &block)
+        @name_hash ||= HashWithIndifferentAccess.new
+        @name_hash[name] = result
+        @instances ||= []
+        @instances << result
+        result
+      end
+
+      def [](event_name)
+        raise_unless_valid_name(event_name)
+        @name_hash[event_name]
+      end
+
+      def each(&block)
+        return unless block
+        (@instances || []).each(&block)
+      end
+
+      def actor_name(event_name)
+        self[event_name].actor
+      end
+
+      def valid_names
+        (@instances || []).map(&:name)
+      end
+      
+      def valid_name?(event_name)
+        valid_names.include?(event_name.to_s)
+      end
+
+      def raise_unless_valid_name(event_name)
+        return if valid_name?(event_name)
+        raise UserstampError, "Invalid event name '#{event_name.inspect}'. Event name must be one of #{valid_names.inspect}"
+      end
+    end
+  end
+
+  Event.create(:create , :creator, 'created_by')
+  Event.create(:update , :updater, 'updated_by', :actual_hook => :before_save)
+  Event.create(:destroy, :deleter, 'deleted_by') #, :after_callback => "save")
+end

data/lib/userstamp/magic_columns.rb

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+require 'userstamp'
+
+module Userstamp
+
+  module MagicColumns
+    def self.included(mod)
+      mod.extend(ClassMethods)
+      mod.instance_eval do
+        alias :columns_without_userstamp :columns
+        alias :columns :columns_with_userstamp
+        alias :stampable_on_without_magic_columns :stampable_on
+        alias :stampable_on :stampable_on_with_magic_columns
+      end
+    end
+
+    module ClassMethods
+      def ignore_userstamp(value = nil)
+        @ignore_userstamp = value unless value.nil?
+        !!@ignore_userstamp
+      end
+
+      def stampable_on_with_magic_columns(*args, &block)
+        ignore_userstamp(true)
+        stampable_on_without_magic_columns(*args, &block)
+      end
+
+      def columns_with_userstamp
+        result = columns_without_userstamp
+        unless @ignore_userstamp || @magic_columns_loaded
+          setup_userstamp(result)
+          @magic_columns_loaded = true
+        end
+        result
+      end
+
+      def setup_userstamp(columns)
+        config = Userstamp.config
+        columns.each do |column|
+          next if column.primary
+          if pattern = config.pattern_for(self, column.name)
+            stampable_on(*pattern.args_for_stampable_on(column.name))
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/userstamp/migration_helper.rb

@@ -0,0 +1,17 @@
+require 'userstamp'
+
+module Userstamp
+  module MigrationHelper
+    def self.included(base) # :nodoc:
+      base.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      def userstamps(include_deleted_by = false)
+        column(Userstamp.compatibility_mode ? :created_by : :creator_id, :integer)
+        column(Userstamp.compatibility_mode ? :updated_by : :updater_id, :integer)
+        column(Userstamp.compatibility_mode ? :deleted_by : :deleter_id, :integer) if include_deleted_by
+      end
+    end
+  end
+end