activerecord-reactor 1.0.0 → 1.0.2

data/CHANGELOG

@@ -0,0 +1,4 @@
+1.0.1
+
+Remove incorrect class definitions
+Update docs

data/README.md

@@ -1,4 +1,79 @@
-activerecord-reactor
-====================
+[![Gem Version](https://badge.fury.io/rb/activerecord-reactor.png)](http://badge.fury.io/rb/activerecord-reactor) [![Code Climate](https://codeclimate.com/github/mtgrosser/activerecord-reactor.png)](https://codeclimate.com/github/mtgrosser/activerecord-reactor)
 
-Unobtrusive observers for Rails models
+Reactor - Controlled reactions on ActiveRecord callbacks
+========================================================
+
+ActiveRecord Reactors provide a defined way to react on default or custom Active Record callbacks. You may think of them as Observers without the magic, and without the hassle.
+
+## Install
+```
+# In your Gemfile
+gem 'activerecord-reactor'
+```
+
+## Usage
+
+Define a custom reactor class, where you would use an Observer:
+
+```ruby
+class YummyReactor < ActiveRecord::Reactor
+  after_create(record)
+    puts "Yummy, #{record.color} #{record.class.name} created!" if record.is_a?(Fruit)
+  end
+end
+```
+
+Connect your models to the reactor:
+
+```ruby
+class Fruit < ActiveRecord::Base
+  attr_accessor :peel
+  
+  reactor :yummy
+
+  def color; end
+end
+```
+
+You can also use custom model callbacks:
+
+```ruby
+class Tidy < ActiveRecord::Reactor
+  def before_peel(record)
+    record.wash!
+  end
+
+  def after_peel(record)
+    GarbageCollector.dispose(record.peel)
+  end
+end
+
+class Banana < Fruit
+  # Use instead of define_model_callbacks if you want to register
+  # the callback with reactors
+  define_reactor_callbacks :peel
+
+  # You can use the actual class if you do not want the reactor name end with 'Reactor'
+  reactor Tidy
+
+  def color
+    'yellow'
+  end
+
+  def peel!
+    run_callbacks :peel do
+      self.peel = Object.new
+    end
+  end
+end
+```
+
+Finally, you can temporarily shutdown any reactions on a reactor:
+
+```ruby
+class Apple < Fruit; end
+
+YummyReactor.scram do
+  Apple.create! # hide this one from YummyReactor
+end
+```

data/Rakefile

@@ -15,8 +15,8 @@ end
 desc 'Generate documentation'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'ActiveModel::Reactor'
+  rdoc.title    = 'ActiveRecord::Reactor'
   rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('README.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/lib/active_record/reactor/callbacks.rb

@@ -4,7 +4,7 @@ module ActiveRecord
 
     module Callbacks
 
-      def self.included(base)
+      def self.included(base) # :nodoc:
         base.extend ClassMethods
         base.class_attribute :reactor_callbacks
         base.reactor_callbacks = ActiveRecord::Base::CALLBACKS.dup
@@ -12,11 +12,18 @@ module ActiveRecord
 
       module ClassMethods
 
+        # Define a custom model callback, which is available to reactors registered with
+        # that model. Works like <tt>ActiveModel::define_model_callbacks</tt>, but does not
+        # define <tt>around</tt> callbacks by default.
+        #
+        # Make sure to define any custom callbacks before registering any reactors
+        # with your model that should react on that callback.
+        #
         def define_reactor_callbacks(*args)
           options = args.extract_options!
           options[:only] ||= [:before, :after] # TODO: implement around callbacks
           types = Array.wrap(options[:only])
-          define_model_callbacks(*(args << options))
+          define_model_callbacks(*(args.dup << options))
           def args.combine(other, &block)
             return product(other) unless block_given?
             product(other).inject([]) { |result, ab| result << yield(ab.first, ab.last) }
@@ -24,6 +31,19 @@ module ActiveRecord
           self.reactor_callbacks = (reactor_callbacks + args.combine(types) { |arg, type| :"#{type}_#{arg}" }).uniq
         end
 
+        # Register a reactor with the model. Note that only callbacks defined on the reactor at
+        # the time of registration will be called.
+        #
+        # <tt>klass_or_name<tt> can be an actual reactor class, or a string or symbol.
+        #
+        #  class Banana < ActiveRecord::Base
+        #    # register YummyReactor
+        #    reactor :yummy
+        #
+        #    # register reactor CustomName
+        #    reactor CustomName
+        #  end
+        #
         def reactor(klass_or_name)
           reactor = klass_or_name.is_a?(Class) ? klass_or_name : "#{klass_or_name.to_s.camelize}Reactor".constantize
           (reactor.callbacks & self.reactor_callbacks).each do |callback|

data/lib/active_record/reactor/version.rb

@@ -1,5 +1,5 @@
 module ActiveRecord
   class Reactor
-    VERSION = '1.0.0'
+    VERSION = '1.0.2'
   end
 end

data/lib/active_record/reactor.rb

@@ -1,20 +1,59 @@
 require 'singleton'
 
 module ActiveRecord
-
+  # = Active Record Reactors
+  #
+  # ActiveRecord Reactors provide a defined way to react on default or custom <tt>ActiveRecord::Callbacks</tt>.
+  # You may think of a Reactor as an <tt>Observer</tt> which is explicitly registered with one or more models,
+  # and does not define any magic methods.
+  #
+  # When a Reactor is registered with a model, it checks which of the model's callbacks are also defined as
+  # reactor instance methods, and adds these to the model's callback chain.
+  #
+  # Reactor callbacks will always return <tt>true</tt>, therefore it is not possible to halt the callback
+  # chain from a reactor. If you want to do that, you should consider moving the code inside the model.
+  #
+  # Examples:
+  #
+  #   class YummyReactor < ActiveRecord::Reactor
+  #     after_create(record)
+  #       puts "Yummy, #{record.color} #{record.class.name} created!" if record.is_a?(Fruit)
+  #     end
+  #   end
+  #
+  #   class Fruit < ActiveRecord::Base
+  #     attr_accessor :peel
+  #
+  #     # Connect your model to the reactor
+  #     reactor :yummy
+  #
+  #     def color; end
+  #   end
+  #
+  # == Reactor scramming
+  #
+  # Reactors can be halted temporarily using the <tt>scram</tt> class method.
+  #
+  #   class Apple < Fruit; end
+  #
+  #   YummyReactor.scram do
+  #     Apple.create! # do not trigger reaction on YummyReactor
+  #   end
+  #
   class Reactor
 
     include Singleton
 
     class << self
-      def callbacks
+      def callbacks # :nodoc:
         (self.public_instance_methods - ActiveRecord::Reactor.public_instance_methods).grep(/\A(before|around|after)_.+/)
       end
-
-      def scrammed?
+      
+      def scrammed? # :nodoc:
         !!@scrammed
       end
 
+      # Stops all reactions while inside the (required) block.
       def scram(&block)
         previously_scrammed = @scrammed
         @scrammed = true

data/lib/activerecord-reactor.rb

@@ -1,7 +1,7 @@
 require 'active_record'
-require 'active_record/reactor'
-require 'active_record/reactor/callbacks'
-require 'active_record/reactor/version'
+require_relative 'active_record/reactor'
+require_relative 'active_record/reactor/callbacks'
+require_relative 'active_record/reactor/version'
 
 ActiveRecord::Base.class_eval do
   include ActiveRecord::Reactor::Callbacks

data/test/cases/reactor_test.rb

@@ -9,6 +9,14 @@ class ReactorTest < ActiveSupport::TestCase
     PeelReactor.calls.clear
   end
 
+  test 'Callbacks are defined' do
+    klass = Class.new(ActiveRecord::Base)
+    assert_equal ActiveRecord::Base::CALLBACKS, klass.reactor_callbacks
+    assert_equal ActiveRecord::Base::CALLBACKS + [:before_peel, :after_peel], Fruit.reactor_callbacks
+    assert_equal ActiveRecord::Base::CALLBACKS + [:before_peel, :after_peel, :before_foo], Cherry.reactor_callbacks
+    assert_equal ActiveRecord::Base::CALLBACKS + [:before_peel, :after_peel], Fruit.reactor_callbacks
+  end
+
   test 'Callbacks are invoked' do
     b = Banana.create(color: 'blue')
     b.peel!
@@ -25,5 +33,5 @@ class ReactorTest < ActiveSupport::TestCase
     end
     assert_empty FruitReactor.calls
     assert_equal false, FruitReactor.scrammed?
-  end  
+  end
 end

data/test/models/cherry.rb

@@ -1,3 +1,3 @@
 class Cherry < Fruit
-
+  define_reactor_callbacks :foo, only: :before
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-reactor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-22 00:00:00.000000000 Z
+date: 2013-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2151926240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,15 +21,10 @@ dependencies:
         version: 3.2.3
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 3.2.3
+  version_requirements: *2151926240
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2151925700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -37,15 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *2151925700
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2151925080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -53,15 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *2151925080
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2151924320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -69,15 +54,10 @@ dependencies:
         version: 0.8.7
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 0.8.7
+  version_requirements: *2151924320
 - !ruby/object:Gem::Dependency
   name: debugger
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &2151923520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -85,35 +65,31 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-description: ''
+  version_requirements: *2151923520
+description: ActiveRecord Reactors provide a defined way to react on default or custom
+  Active Record callbacks. Observers without the magic, and without the hassle.
 email: mtgrosser@gmx.net
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/active_record/active_record.rb
 - lib/active_record/reactor/callbacks.rb
 - lib/active_record/reactor/version.rb
 - lib/active_record/reactor.rb
 - lib/activerecord-reactor.rb
 - MIT-LICENSE
 - README.md
+- CHANGELOG
 - Rakefile
+- test/cases/reactor_test.rb
 - test/models/banana.rb
+- test/models/cherry.rb
 - test/models/fruit.rb
 - test/models/fruit_reactor.rb
 - test/models/peel_reactor.rb
-- test/models/cherry.rb
-- test/cases/reactor_test.rb
-- test/test_helper.rb
-- test/support/custom_assertions.rb
 - test/schema.rb
+- test/support/custom_assertions.rb
+- test/test_helper.rb
 homepage: https://github.com/mtgrosser/activerecord-reactor
 licenses: []
 post_install_message: 
@@ -134,17 +110,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: Unobtrusive observers for Rails models
+summary: Controlled reactions on ActiveRecord callbacks
 test_files:
+- test/cases/reactor_test.rb
 - test/models/banana.rb
+- test/models/cherry.rb
 - test/models/fruit.rb
 - test/models/fruit_reactor.rb
 - test/models/peel_reactor.rb
-- test/models/cherry.rb
-- test/cases/reactor_test.rb
-- test/test_helper.rb
-- test/support/custom_assertions.rb
 - test/schema.rb
+- test/support/custom_assertions.rb
+- test/test_helper.rb

data/lib/active_record/active_record.rb

@@ -1,12 +0,0 @@
-require 'active_record'
-
-module ActiveRecord
-  class Reactor < ActiveModel::Reactor
-  end
-
-  Base.class_eval do
-    include ActiveModel::Reactor::Callbacks
-    self.reactor_callbacks = Base::CALLBACKS.dup
-  end
-end
-