after_do 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1a27fee536c317e5ba1edbfe81e495dccad4f1fc
-  data.tar.gz: d0c51288921b665794ec7b89130d3b27584eef36
+  metadata.gz: 8a511da98cd0406b771b511abda97039ba62ed9e
+  data.tar.gz: 7d8fdb3c67e82a5d88cc1860257c260b5f302cf9
 SHA512:
-  metadata.gz: fd71a09544a38876a753c5f24cc01fb5e607152167d061f4616504645b9867952ff4b719d8b1ae9f3f5ce428a9d80da74612f3c3d9b2e9d86aa275cd7edb8bec
-  data.tar.gz: f8a079648a8b52de280ccd31a8d7b117eac59e862614ea34beafd05a82e12406bcfa62de2ba393b92b65c6fe86c4062942a6c396914120b4a138d496996cc09d
+  metadata.gz: 4bf5a61e4f96913d67dd4b748f4459dd77f38f0f901a5c2194995e4c4b146e5ecef90a54e34b46a37d19f100e5fca198b152b8be47b1ecd49dd34cf728f7196a
+  data.tar.gz: 1db2f852508993f9aab51d23bf9300721050a42d4097c69601da50c5266fc1cd445f4cc9037993dd61d37fbbed3a7cf3eec8d17bf554b9c7d09b254f8eca893c

data/.ruby-version

@@ -1 +1 @@
-ruby-2.0.0-p247
+ruby-2.0.0-p353

data/.travis.yml

@@ -1,6 +1,6 @@
 language: ruby
 rvm:
-  - rbx-19mode
+  - rbx-2.2.1
   - jruby-19mode
   - 1.9.3
   - 2.0

data/Gemfile

@@ -3,9 +3,14 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in after_do.gemspec
 gemspec
 
+gem 'rubysl', platform: :rbx
+gem 'rubinius-coverage', platform: :rbx
+gem 'json', platform: :rbx
+
 gem 'bundler', '~> 1.3'
 gem 'rake'
 gem 'rspec'
 gem 'guard-rspec'
 gem 'simplecov'
-gem 'coveralls'
+gem 'coveralls'
+gem 'rdoc'

data/README.md

@@ -1,15 +1,17 @@
-# AfterDo [![Gem Version](https://badge.fury.io/rb/after_do.png)](http://badge.fury.io/rb/after_do)[![Build Status](https://travis-ci.org/PragTob/after_do.png?branch=master)](https://travis-ci.org/PragTob/after_do)[![Code Climate](https://codeclimate.com/github/PragTob/after_do.png)](https://codeclimate.com/github/PragTob/after_do)[![Coverage Status](https://coveralls.io/repos/PragTob/after_do/badge.png)](https://coveralls.io/r/PragTob/after_do)
+# after_do [![Gem Version](https://badge.fury.io/rb/after_do.png)](http://badge.fury.io/rb/after_do)[![Build Status](https://travis-ci.org/PragTob/after_do.png?branch=master)](https://travis-ci.org/PragTob/after_do)[![Code Climate](https://codeclimate.com/github/PragTob/after_do.png)](https://codeclimate.com/github/PragTob/after_do)[![Coverage Status](https://coveralls.io/repos/PragTob/after_do/badge.png)](https://coveralls.io/r/PragTob/after_do)
 
-AfterDo is simple gem, that allows you to execute a specified block after specified method of a class are called. If the class extends `AfterDo` you can simply do this by
+after_do is simple gem, that allows you to execute some blocks (callbacks) after specific method of a class are called. If the class extends `AfterDo` you can simply do this by
 
 ```
 MyClass.after :some_method do whatever_you_want end
 ```
 
-Why would you want to do this? Well to fight cross-cutting concerns such as logging. E.g. there are concerns in an applications that apply to multiple objects (e.g. they cross-cut). A popular example is logging - you might want to log multiple actions but logging is not the primary concern of the class in question. With logging you litter all your code with logging statements - that concern is spread over many files. With AfterDo you could put all the logging in one file. Other use cases include gathering business statistics or redrawing timing of elements. Personally I extracted this gem from a project where I wanted to decouple my domain objects from the way they are saved (for fun and profit!).
+Why would you want to do this? Well to fight cross-cutting concerns such as logging. E.g. there are concerns in an applications that apply to multiple objects (e.g. they cross-cut). A popular example is logging - you might want to log multiple actions but logging is not the primary concern of the class in question. With logging you litter all your code with logging statements - that concern is spread over many files. With after_do you could put all the logging in one file. Other use cases include gathering business statistics or redrawing timing of elements. Personally I extracted this gem from a project where I wanted to decouple my domain objects from the way they are saved (for fun and profit!).
 This should generally not be done to alter behavior of the class and its instances - this makes programs more confusing rather than easier to understand.
 
-AfterDo has no external runtime dependencies and the code is around 120 lines of code (blank lines included) with lots of small methods. So simplecov reports there are not even 70 relevant lines.
+The idea for this is inspired by Aspect Oriented Programming - e.g. do something when specific methods are executed. However I doubt that this formally fulfills the lingo (join points, aspects, advice...)
+
+after_do has no external runtime dependencies and the code is around 160 lines of code (blank lines and documentation included) with lots of small methods. So simplecov reports there are a little above 70 relevant lines code (it ignores blank lines, docs etc.).
 
 ## Installation
 
@@ -27,18 +29,18 @@ Or install it yourself as:
 
 ## Usage
 
-This section is dedicated to show of the general usage and effects of AfterDo. You can also check out the samples directory for some samples or the specs in the spec folder.
+This section is dedicated to show of the general usage and effects of after_do. You can also check out the samples directory for some samples or the specs in the spec folder.
 
 ### General usage
 
-In order to use AfterDo the class/module you want to use it with first has to extend the `AfterDo` module. You can do this right in the class definition or afterwards like this: `MyClass.extend AfterDo`.
+In order to use after_do the class/module you want to use it with first has to extend the `AfterDo` module. You can do this right in the class definition or afterwards like this: `MyClass.extend AfterDo`.
 With this setup you can add a callback to `method` like this:
 
 ```ruby
 MyClass.after :method do magic end
 ```
 
-With AfterDo you can do simple things like printing something out every time a method is called as in this example:
+With after_do you can do simple things like printing something out every time a method is called as in this example:
 
 ```ruby
 class Dog
@@ -66,7 +68,7 @@ dog2.bark
 
 ### How does it work?
 
-When you attach a callback to a method with AfterDo what it basically does is it creates a copy of that method and then redefines the method to basically look like this (pseudo code):
+When you attach a callback to a method with after_do what it basically does is it creates a copy of that method and then redefines the method to basically look like this (pseudo code):
 
 ```ruby
 execute_before_callbacks
@@ -79,7 +81,7 @@ To do this some helper methods are defined in the AfterDo module. As classes hav
 
 ### Getting a hold of the method arguments and the object
 
-With AfterDo both the arguments to the method you are attaching the callback to and the object for which the callback is executed are passed into the callback block.
+With after_do both the arguments to the method you are attaching the callback to and the object for which the callback is executed are passed into the callback block.
 
 So if you have a method that takes two arguments you can get those like this:
 
@@ -139,7 +141,7 @@ e.two 'one', 'two'
 
 ### Attaching a callback to multiple methods
 
-In AfterDo you can attach a callback to multiple methods by just listing them:
+In after_do you can attach a callback to multiple methods by just listing them:
 
 ```ruby
 SomeClass.after :one_method, :another_method do something end
@@ -177,7 +179,7 @@ The callbacks are executed in the order in which they were added.
 
 ### Working with inheritance
 
-AfterDo also works with inheritance. E.g. if you attach a callback to a method in a super class and that method is called in a sub class the callback is still executed.
+after_do also works with inheritance. E.g. if you attach a callback to a method in a super class and that method is called in a sub class the callback is still executed.
 
 See this sample:
 
@@ -198,6 +200,59 @@ b = B.new
 b.a #prints out: a was called
 ```
 
+### Usage from within a class
+
+If you got some repetitive tasks, that needs to be done after/before a lot of methods in a class then you can also use after_do for this. This works a bit like `before_action`/`after_action` which you might know from Ruby on Rails.
+
+E.g. like this:
+
+```
+class MyClass
+  extend AfterDo
+
+  # ...
+
+  after :my_method, :method2, :m3 do |args*, instance| instance.a_method end
+end
+```
+
+See this example:
+
+```ruby
+class Team
+  extend AfterDo
+  
+  def add_member(member)
+    # ...
+  end
+  
+  def remove_member(member)
+    # ..
+  end
+  
+  def change_name(new_name)
+    # ..
+  end
+  
+  def save
+   # ..
+   puts 'saving...'
+  end
+  
+  after :add_member, :remove_member, :change_name do |*, team| team.save end
+end
+
+team = Team.new
+team.add_member 'Maren'
+team.change_name 'Ruby Cherries'
+team.remove_member 'Guilia'
+
+# Output is:
+# saving...
+# saving...
+# saving...
+```
+
 ### Removing callbacks
 
 You can remove all callbacks you added to a class by doing:
@@ -206,9 +261,11 @@ You can remove all callbacks you added to a class by doing:
 MyClass.remove_all_callbacks
 ```
 
+Note that this not remove callbacks defined in super classes.
+
 ### Errors
 
-There are some custom errors that AfterDo throws. When you try to add a callback to a method which that class does not understand it will throw `AfterDo::NonExistingMethodError`.
+There are some custom errors that after_do throws. When you try to add a callback to a method which that class does not understand it will throw `AfterDo::NonExistingMethodError`.
 
 When an error occurs during one of the callbacks that are attached to a method it will throw `AfterDo::CallbackError` with information about the original error and where the block/callback causing this error was defined to help pinpoint the error.
 
@@ -245,7 +302,7 @@ m.value = 'new value'
 
 ### Method granularity
 
-AfterDo works on the granularity of methods. That means that you can only attach callbacks to methods. This is no problem however, since if it's your code you can always define new methods. E.g. you want to attach callbacks to the end of some operation that happens in the middle of a method just define a new method for that piece of code.
+after_do works on the granularity of methods. That means that you can only attach callbacks to methods. This is no problem however, since if it's your code you can always define new methods. E.g. you want to attach callbacks to the end of some operation that happens in the middle of a method just define a new method for that piece of code.
 
 I sometimes do this for evaluating the block, as I want to do something when that block finished evaluating so I define a method `eval_block` wherein I just evaluate the block.
 

data/after_do.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = AfterDo::VERSION
   spec.authors       = ["Tobias Pfeiffer"]
   spec.email         = ["pragtob@gmail.com"]
-  spec.description   = %q{after_do is a gem that let's you execute a block of your choice after a specific method was called on a class.}
-  spec.summary       = %q{after_do allows you to do simple after hooks on methods}
+  spec.description   = %q{after_do is a gem that let's you execute a block of your choice after or before a specific method is called on a class. This is inspired by Aspect Oriented Programming and should be used to fight cross-cutting concerns.}
+  spec.summary       = %q{after_do allows you to add simple after/before hooks to methods}
   spec.homepage      = "https://github.com/PragTob/after_do"
   spec.license       = "MIT"
 

data/lib/after_do.rb

@@ -1,36 +1,67 @@
+# The after_do library to add callbacks to methods in Ruby. Before using this
+# with any class, that class has to extend the AfterDo module first e.g.
+#    MyClass.extend AfterDo
+#    MyClass.after :some_method do awesome_stuff end
+#
+# More information at the github page: https://github.com/PragTob/after_do
 module AfterDo
+  # The prefix for the copies of the original methods made by after_do
   ALIAS_PREFIX = '__after_do_orig_'
 
+  # ::nodoc::
   def self.extended(klazz)
     klazz.send(:include, AfterDo::Instance)
     klazz.send(:extend, AfterDo::Class)
   end
 
+  # Raised when trying to attach a callback to a non existing method
   class NonExistingMethodError < StandardError ; end
+
+  # Raised when an error occurs in one of the callbacks of a method. Provides
+  # additional information as to for which method and where the block was
+  # defined.
   class CallbackError < StandardError ; end
 
+  # These methods become available on a class after the AfterDo module was
+  # extended (e.g. extending the AfterDo module results in extending
+  # AfterDo::Class)
   module Class
-
-    def _after_do_callbacks
-      @_after_do_callbacks || _after_do_basic_hash
-    end
-
+    # A method to add a callback to a method or a list of methods to be executed
+    # after the original method was executed. E.g.:
+    #    MyClass.after :some_method do awesome_stuff end
+    # It can only take a list of methods after which a block should be executed:
+    #    MyClass.after :method1, :method2, :method3 do puts 'jay!' end
+    # The list might also be an Array.
     def after(*methods, &block)
       _after_do_define_callback(:after, methods, block)
     end
 
+    # This method works much like .after - just that the blocks are executed
+    # before the method is called.
     def before(*methods, &block)
       _after_do_define_callback(:before, methods, block)
     end
 
+    # Removes all callbacks attach to methods in this class.
     def remove_all_callbacks
-      @_after_do_callbacks = _after_do_basic_hash if @_after_do_callbacks
+      @_after_do_callbacks = _after_do_basic_hash
+    end
+
+    # It's not really meant for you to mess with - therefore the
+    # _after_do prefix (it's an internal structure but needs to be accessible)
+    # from instances.
+    # However it's an accessor for the after_do callbacks associated with this
+    # class. This is a hash of the following form:
+    #    {after:  {method: [callback1, callback2, ...]},
+    #     before: {method: [callback1, callback2, ...]}
+    def _after_do_callbacks
+      @_after_do_callbacks || _after_do_basic_hash
     end
 
     private
     def _after_do_define_callback(type, methods, block)
       @_after_do_callbacks ||= _after_do_basic_hash
-      methods.flatten! #in case someone used an Array
+      methods = methods.flatten #in case someone used an Array
       _after_do_raise_no_method_specified(type) if methods.empty?
       methods.each do |method|
         _after_do_add_callback_to_method(type, method, block)
@@ -98,7 +129,11 @@ module AfterDo
     end
   end
 
+  # These methods become available on instances of a class after extending the
+  # AfterDo module. They are just needed for the callback lookup/execution and
+  # all of them are private - you should not call them.
   module Instance
+    private
     def _after_do_execute_callbacks(type, method, *args)
       callback_classes = self.class.ancestors.select do |klazz|
         _after_do_has_callback_for?(klazz, type, method)
@@ -123,4 +158,4 @@ module AfterDo
       end
     end
   end
-end
+end

data/lib/after_do/version.rb

@@ -1,3 +1,4 @@
 module AfterDo
-  VERSION = "0.2.2"
+  # ::nodoc::
+  VERSION = "0.2.3"
 end

data/samples/within_class.rb

@@ -20,10 +20,15 @@ class Team
    puts 'saving...'
   end
   
-  after :add_member, :remove_member, :change_name do |*args, team| team.save end
+  after :add_member, :remove_member, :change_name do |*, team| team.save end
 end
 
 team = Team.new
 team.add_member 'Maren'
 team.change_name 'Ruby Cherries'
 team.remove_member 'Guilia'
+
+# Output is:
+# saving...
+# saving...
+# saving...

data/spec/after_do_spec.rb

@@ -27,13 +27,17 @@ describe AfterDo do
   end
 
   shared_examples_for 'calling callbacks' do |callback_adder|
-    it 'responds to before/after' do
-      @dummy_class.should respond_to callback_adder
+    it 'does not monkey patch Class' do
+      expect(Class.new).not_to respond_to callback_adder
+    end
+
+    it 'responds to before/after extended with AfterDo' do
+      expect(@dummy_class).to respond_to callback_adder
     end
 
     def simple_callback_called_test(callback_adder)
       @dummy_class.send callback_adder, :zero do mockie.call_method end
-      mockie.should_receive :call_method
+      expect(mockie).to receive :call_method
       dummy_instance.zero
     end
 
@@ -50,21 +54,21 @@ describe AfterDo do
       before_return_value = dummy_instance.zero
       @dummy_class.send callback_adder, :zero do 42 end
       after_return_value = dummy_instance.zero
-      after_return_value.should eq before_return_value
+      expect(after_return_value).to eq before_return_value
     end
 
     it 'marks the copied method as private' do
       @dummy_class.send callback_adder,  :zero do end
       copied_method_name = (AfterDo::ALIAS_PREFIX + 'zero').to_sym
-      dummy_instance.respond_to?(copied_method_name).should be_false
+      expect(dummy_instance).not_to respond_to copied_method_name
     end
 
     it 'can add multiple call backs' do
-      mockie.should_receive :call_method
+      expect(mockie).to receive :call_method
       mock2 = double
-      mock2.should_receive :call_another_method
+      expect(mock2).to receive :call_another_method
       mock3 = double
-      mock3.should_receive :bla
+      expect(mock3).to receive :bla
       @dummy_class.send callback_adder, :zero do mockie.call_method end
       @dummy_class.send callback_adder, :zero do mock2.call_another_method end
       @dummy_class.send callback_adder, :zero do mock3.bla end
@@ -73,14 +77,14 @@ describe AfterDo do
 
     describe 'removing callbacks' do
       it 'can remove all callbacks' do
-        mockie.should_not_receive :call_method
+        expect(mockie).not_to receive :call_method
         @dummy_class.send callback_adder, :zero do mockie.call_method end
         @dummy_class.remove_all_callbacks
         dummy_instance.zero
       end
 
       it 'does not crash the addition of new callbacks afterwards' do
-        mockie.should_receive :call_method
+        expect(mockie).to receive :call_method
         @dummy_class.send callback_adder, :zero do mockie.call_method end
         @dummy_class.remove_all_callbacks
         @dummy_class.send callback_adder, :zero do mockie.call_method end
@@ -141,7 +145,7 @@ describe AfterDo do
     describe 'with parameters' do
 
       before :each do
-        mockie.should_receive :call_method
+        expect(mockie).to receive :call_method
       end
 
       it 'can handle methods with a parameter' do
@@ -157,13 +161,13 @@ describe AfterDo do
 
     describe 'with parameters for the given block' do
       it 'can handle one block parameter' do
-        mockie.should_receive(:call_method).with(5)
+        expect(mockie).to receive(:call_method).with(5)
         @dummy_class.send callback_adder,  :one do |i| mockie.call_method i end
         dummy_instance.one 5
       end
 
       it 'can handle two block parameters' do
-        mockie.should_receive(:call_method).with(5, 8)
+        expect(mockie).to receive(:call_method).with(5, 8)
         @dummy_class.send callback_adder,  :two do |i, j| mockie.call_method i, j end
         dummy_instance.two 5, 8
       end
@@ -177,34 +181,42 @@ describe AfterDo do
       end
 
       it 'can take multiple method names as arguments' do
-        mockie.should_receive(:call_method).exactly(3).times
-        @dummy_class.send callback_adder,  :zero, :one, :two do mockie.call_method end
+        expect(mockie).to receive(:call_method).exactly(3).times
+        @dummy_class.send callback_adder,  :zero, :one, :two do
+          mockie.call_method
+        end
         call_all_3_methods
       end
 
       it 'can get the methods as an Array' do
-        mockie.should_receive(:call_method).exactly(3).times
-        @dummy_class.send callback_adder,  [:zero, :one, :two] do mockie.call_method end
+        expect(mockie).to receive(:call_method).exactly(3).times
+        @dummy_class.send callback_adder,  [:zero, :one, :two] do
+          mockie.call_method
+        end
         call_all_3_methods
       end
 
       it 'raises an error when no method is specified' do
         expect do
-          @dummy_class.send callback_adder do mockie.call_method end
+          @dummy_class.send callback_adder do
+            mockie.call_method
+          end
         end.to raise_error ArgumentError
       end
     end
 
     describe 'it can get a hold of self, if needbe' do
       it 'works for a method without arguments' do
-        mockie.should_receive(:call_method).with(dummy_instance)
-        @dummy_class.send callback_adder,  :zero do |object| mockie.call_method(object) end
+        expect(mockie).to receive(:call_method).with(dummy_instance)
+        @dummy_class.send callback_adder,  :zero do |object|
+          mockie.call_method(object)
+        end
         dummy_instance.zero
       end
 
       it 'works for a method with 2 arguments' do
-        mockie.should_receive(:call_method).with(1, 2, dummy_instance)
-        @dummy_class.send callback_adder,  :two do |first, second, object|
+        expect(mockie).to receive(:call_method).with(1, 2, dummy_instance)
+        @dummy_class.send callback_adder, :two do |first, second, object|
           mockie.call_method(first, second, object)
         end
         dummy_instance.two 1, 2
@@ -223,7 +235,7 @@ describe AfterDo do
       end
 
       it 'class knows about the after/before method' do
-        @inherited_class.should respond_to callback_adder
+        expect(@inherited_class).to respond_to callback_adder
       end
 
       describe 'callback on parent class' do
@@ -232,18 +244,18 @@ describe AfterDo do
         end
 
         it 'works when we have a callback on the parent class' do
-          mockie.should_receive :call
+          expect(mockie).to receive :call
           inherited_instance.zero
         end
 
         it 'remove_callbacks does not remove the callbacks on parent class' do
-          mockie.should_receive :call
+          expect(mockie).to receive :call
           @inherited_class.remove_all_callbacks
           inherited_instance.zero
         end
 
         it 'remove_callbacks on the parent does remove the callbacks' do
-          mockie.should_not_receive :call
+          expect(mockie).not_to receive :call
           @dummy_class.remove_all_callbacks
           inherited_instance.zero
         end
@@ -263,18 +275,18 @@ describe AfterDo do
     end
 
     it 'calls the before callback' do
-      callback.should_receive :before_call
+      expect(callback).to receive :before_call
       dummy_instance.zero
     end
 
     it 'calls the after callback' do
-      callback.should_receive :after_call
+      expect(callback).to receive :after_call
       dummy_instance.zero
     end
 
     it 'receives the calls in the right order' do
-      callback.should_receive(:before_call).ordered
-      callback.should_receive(:after_call).ordered
+      expect(callback).to receive(:before_call).ordered
+      expect(callback).to receive(:after_call).ordered
       dummy_instance.zero
     end
   end

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: after_do
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Tobias Pfeiffer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-15 00:00:00.000000000 Z
+date: 2013-12-19 00:00:00.000000000 Z
 dependencies: []
 description: after_do is a gem that let's you execute a block of your choice after
-  a specific method was called on a class.
+  or before a specific method is called on a class. This is inspired by Aspect Oriented
+  Programming and should be used to fight cross-cutting concerns.
 email:
 - pragtob@gmail.com
 executables: []
@@ -58,10 +59,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.6
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
-summary: after_do allows you to do simple after hooks on methods
+summary: after_do allows you to add simple after/before hooks to methods
 test_files:
 - spec/after_do_spec.rb
 - spec/spec_helper.rb