super_module 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: def423de958bb4f6b3d2c6b3edb60908d42bbe86
-  data.tar.gz: 962866a97336aaeeebd16386e1cf37417e1d2aa9
+  metadata.gz: 5ed999facd85a8593e0e0af6a036c625a68f51ae
+  data.tar.gz: 27219be2a1966b18e253d839b76232e118d27824
 SHA512:
-  metadata.gz: 99668ddec0c2e332493f7cda830428e4915d65eaf35bde9b5a0336233396425c458746734082917028a310b8fa0e4a01d0b430f0f3a78a31b7cd5afdd541e5c1
-  data.tar.gz: fb848a9f6979fe0f079ddc9d3967eb600b85186659ce6457d220ec5ce55be0c460928fe09e5403cfe0689009a4c93ae9a3ce4102e1b07ac27785027f525e7b02
+  metadata.gz: 6bb3130d30bb2bf2baf04c657a828020375f2b3bb0a5504cae2d8da924ba5184deee3aace7cc4f2359c4bb8f85cc603189734e27fecdee6461b75fb873a4144c
+  data.tar.gz: bc3d4b819dbd682c75c8a26b5d58da614615f60f14f5e880f6128dcd2ab15feb947b571d79aed3f95a7907c3ab7fbe68d71a71f398ca72836f638ba011de5ab8

data/README.md

@@ -4,143 +4,363 @@
 [![Coverage Status](https://coveralls.io/repos/AndyObtiva/super_module/badge.png?branch=master)](https://coveralls.io/r/AndyObtiva/super_module?branch=master)
 [![Code Climate](https://codeclimate.com/github/AndyObtiva/super_module.png)](https://codeclimate.com/github/AndyObtiva/super_module)
 
-Tired of Ruby's modules not allowing you to mix in class methods easily?
-Tired of writing complex code and using complex libraries like ActiveSupport::Concern to accomplish that goal?
+Tired of [Ruby](https://www.ruby-lang.org/en/)'s modules not allowing you to mix in class methods easily?
+Tired of writing complex `self.included(base)` code or using over-engineered solutions like [`ActiveSupport::Concern`](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html) to accomplish that goal?
+
+Well, worry no more! [SuperModule](https://rubygems.org/gems/super_module) comes to the rescue!
+
+[SuperModule](https://rubygems.org/gems/super_module) allows defining class methods and method invocations the same way a super class does without using [`self.included(base)`](http://ruby-doc.org/core-2.2.1/Module.html#method-i-included).
+
+This succeeds [`ActiveSupport::Concern`](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html) by offering lighter syntax and simpler module dependency support.
+
+## Introductory Comparison
+
+To introduce [SuperModule](https://rubygems.org/gems/super_module), here is a comparison of three different approaches for writing a
+<code>UserIdentifiable</code> module. 
+
+#### 1) [self.included(base)](http://ruby-doc.org/core-2.2.1/Module.html#method-i-included)
+
+```ruby
+module UserIdentifiable
+  include ActiveModel::Model
+
+  def self.included(base_klass)
+    base_klass.extend(ClassMethods)
+    base.class_eval do
+      belongs_to :user
+      validates :user_id, presence: true
+    end
+  end
+  
+  module ClassMethods
+    def most_active_user
+      User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
+    end
+  end
+  
+  def slug
+    "#{self.class.name}_#{user_id}"
+  end
+end
+```
+
+This is a lot to think about and process for simply wanting inclusion of class method definitions (like <code>most_active_user</code>) and class method invocations (like <code>belongs_to</code> and <code>validates</code>). The unnecessary complexity gets in the way of problem-solving; slows down productivity with repetitive boiler-plate code; and breaks expectations set in other similar object-oriented languages, discouraging companies from including [Ruby](https://www.ruby-lang.org/en/) in a polyglot stack, such as [Groupon](http://www.groupon.com)'s [Rails/JVM/Node.js](https://engineering.groupon.com/2013/misc/i-tier-dismantling-the-monoliths/) stack and [SoundCloud](http://www.soundcloud.com)'s [JRuby/Scala/Clojure stack](https://developers.soundcloud.com/blog/building-products-at-soundcloud-part-3-microservices-in-scala-and-finagle).
+
+#### 2) [ActiveSupport::Concern](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html)
+
+```ruby
+module UserIdentifiable
+  extend ActiveSupport::Concern
+  include ActiveModel::Model
+
+  included do
+    belongs_to :user
+    validates :user_id, presence: true
+  end
+  
+  module ClassMethods
+    def most_active_user
+      User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
+    end
+  end
+  
+  def slug
+    "#{self.class.name}_#{user_id}"
+  end
+end
+```
+
+A step forward that addresses the boiler-plate repetitive code concern, but is otherwise really just lipstick on a pig. To explain more, developer problem solving and creativity flow is still disrupted by having to think about the lower-level mechanism of running code on inclusion (using `included`) and structuring class methods in an extra sub-module (`ClassMethods`) instead of simply declaring class methods like they normally would in Ruby and staying focused on the task at hand.
+
+#### 3) [SuperModule](https://github.com/AndyObtiva/super_module)
+
+```ruby
+module UserIdentifiable
+  include SuperModule
+  include ActiveModel::Model
+  
+  belongs_to :user
+  validates :user_id, presence: true
+
+  def self.most_active_user
+    User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
+  end
+
+  def slug
+    "#{self.class.name}_#{user_id}"
+  end
+end
+```
+
+With `include SuperModule` declared on top, developers can directly add class method invocations and definitions inside the module's body, and [`SuperModule`](https://github.com/AndyObtiva/super_module) takes care of automatically mixing them into classes that include the module.
+
+As a result, [SuperModule](https://rubygems.org/gems/super_module) collapses the difference between extending a super class and including a super module, thus encouraging developers to write simpler code while making better Object-Oriented Design decisions. 
+
+In other words, [SuperModule](https://rubygems.org/gems/super_module) furthers Ruby's goal of making programmers happy.
 
-Well, worry no more! SuperModule comes to the rescue!
+## Instructions
 
-![SuperModule](https://raw.githubusercontent.com/AndyObtiva/super_module/master/SuperModule.jpg)
+#### 1) Install and require gem
 
-SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base).
+<b>Using [Bundler](http://bundler.io/)</b>
 
-This succeeds ActiveSupport::Concern by offering lighter syntax and simpler module dependency support.
+Add the following to Gemfile: <pre>gem 'super_module', '1.0.0'</pre>
 
-## Instructions
+And run the following command: <pre>bundle</pre>
 
-### 1) Install and require gem
+Afterwards, [SuperModule](https://rubygems.org/gems/super_module) will automatically get required in the application (e.g. a Rails application) and be ready for use.
 
-<b>Using Bundler</b>
+<b>Using [RubyGem](https://rubygems.org/gems/super_module) Directly</b>
 
-Add the following to Gemfile: <pre>gem 'super_module', '1.0.0'</pre>
-Run: <code>bundle</code>
-
-It will automatically get required in the application when loading with bundler (e.g. in a Rails application)
-
-<b>Using RubyGem Directly</b>
-
-Run: <pre>gem install super_module</pre>
-(add <code>--no-ri --no-rdoc</code> if you wish to skip downloading them for a faster install)
-
-Add <code>require 'super_module'</code> at the top of your Ruby file
-
-### 2) Include SuperModule at the top of the module
-
->     module UserIdentifiable
->       include SuperModule
->
->       belongs_to :user
->       validates :user_id, presence: true
->
->       def self.most_active_user
->         User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
->       end
->
->       def slug
->         "#{self.class.name}_#{user_id}"
->       end
->     end
-
-### 3) Mix newly defined module into a class or another super module
-
->     class ClubParticipation < ActiveRecord::Base
->       include UserIdentifiable
->     end
->     class CourseEnrollment < ActiveRecord::Base
->       include UserIdentifiable
->     end
->     module Accountable
->       include SuperModule
->       include UserIdentifiable
->     end
->     class Activity < ActiveRecord::Base
->       include Accountable
->     end
-
-### 4) Start using by invoking class methods or instance methods
-
->     CourseEnrollment.most_active_user
->     ClubParticipation.most_active_user
->     Activity.last.slug
->     ClubParticipation.create(club_id: club.id, user_id: user.id).slug
->     CourseEnrollment.new(course_id: course.id).valid?
-
-## Example
-
->     require 'super_module'
->
->     module Foo
->       include SuperModule
->
->       validates :credit_card_id, presence: true
->
->       def foo
->         puts 'foo'
->         'foo'
->       end
->
->       def self.foo
->         puts 'self.foo'
->         'self.foo'
->       end
->     end
->
->     module Bar
->       include SuperModule
->       include Foo
->
->       validates :user_id, presence: true
->
->       def bar
->         puts 'bar'
->         'bar'
->       end
->
->       def self.bar
->         puts 'self.bar'
->         'self.bar'
->       end
->     end
->
->     class MediaAuthorization < ActiveRecord::Base
->       include Bar
->     end
->
->     MediaAuthorization.create.errors.messages.inspect
+Run the following command: <pre>gem install super_module</pre>
+
+(add <code>--no-ri --no-rdoc</code> if you wish to skip downloading documentation for a faster install)
+
+Add the following at the top of your [Ruby](https://www.ruby-lang.org/en/) file: <pre>require 'super_module'</pre>
+
+#### 2) Include [`SuperModule`](https://rubygems.org/gems/super_module) at the top of the module
+
+```ruby
+module UserIdentifiable
+  include SuperModule
+  include ActiveModel::Model
+
+  belongs_to :user
+  validates :user_id, presence: true
+
+  def self.most_active_user
+    User.find_by_id(select('count(id) as head_count, user_id').group('user_id').order('count(id) desc').first.user_id)
+  end
+
+  def slug
+    "#{self.class.name}_#{user_id}"
+  end
+end
+```
+
+#### 3) Mix newly defined module into a class or another super module
+
+```ruby
+class ClubParticipation < ActiveRecord::Base
+  include UserIdentifiable
+end
+class CourseEnrollment < ActiveRecord::Base
+  include UserIdentifiable
+end
+module Accountable
+  include SuperModule
+  include UserIdentifiable
+end
+class Activity < ActiveRecord::Base
+  include Accountable
+end
+```
+
+#### 4) Start using by invoking class methods or instance methods
+
+```ruby
+CourseEnrollment.most_active_user
+ClubParticipation.most_active_user
+Activity.last.slug
+ClubParticipation.create(club_id: club.id, user_id: user.id).slug
+CourseEnrollment.new(course_id: course.id).valid?
+```
+
+## Glossary and Definitions
+
+ * SuperModule: name of the library and Ruby module that provides functionality via mixin
+ * Super module: any Ruby module that mixes in SuperModule
+ * Class method definition: Ruby class or module method declared with <code>self.method_name</code> or <code>class << self</code>
+ * Class method invocation: Inherited Ruby class or module method invoked in the body of a class or module (e.g. <code>validates :username, presence: true</code>)
+ * Code-time: Time of writing code in a Ruby file as opposed to Run-time
+ * Run-time: Time of executing Ruby code
+
+## Usage Details
+
+ * SuperModule must always be included at the top of a module's body at code-time
+ * SuperModule inclusion can be optionally followed by other basic or super module inclusions
+ * A super module can only be included in a class or another super module
+ * SuperModule adds <b>zero cost</b> to instantiation of including classes and invocation of included methods (both class and instance)
+
+## Another Example
+
+Copy and paste the following code snippets in <code>irb</code> and you should get the output denoted by double arrows (<code>=></code>).
+
+```ruby
+require 'super_module'
+
+module Foo
+  include SuperModule
+
+  validates :credit_card_id, presence: true
+
+  def foo
+    puts 'foo'
+    'foo'
+  end
+
+  def self.foo
+    puts 'self.foo'
+    'self.foo'
+  end
+end
+
+module Bar
+  include SuperModule
+  include Foo
+
+  validates :user_id, presence: true
+
+  def bar
+    puts 'bar'
+    'bar'
+  end
+
+  def self.bar
+    puts 'self.bar'
+    'self.bar'
+  end
+end
+
+class MediaAuthorization < ActiveRecord::Base
+  include Bar
+end
+
+MediaAuthorization.create.errors.messages.inspect
+```
 
 => "{:credit_card_id=>[\"can't be blank\"], :user_id=>[\"can't be blank\"]}"
 
->     MediaAuthorization.new.foo
+```ruby
+MediaAuthorization.new.foo
+```
 
 => "foo"
 
->     MediaAuthorization.new.bar
+```ruby
+MediaAuthorization.new.bar
+```
 
 => "bar"
 
->     MediaAuthorization.foo
+```ruby
+MediaAuthorization.foo
+```
 
 => "self.foo"
 
->     MediaAuthorization.bar
+```ruby
+MediaAuthorization.bar
+```
 
 => "self.bar"
 
-## Design Limitations
+## How Does It Work?
+
+Here is the general algorithm from the implementation:
+
+```ruby
+def included(base)
+  __invoke_super_module_class_method_calls(base)
+  __define_super_module_class_methods(base)
+end
+```
+
+#### 1) Invoke super module class method calls on the including base class.
+
+For example, suppose we have a super module called `Locatable`:
+
+```ruby
+module Locatable
+  include SuperModule
+  
+  validates :x_coordinate, numericality: true
+  validates :y_coordinate, numericality: true
+  
+  def move(x, y)
+    self.x_coordinate += x
+    self.y_coordinate += y
+  end
+end
+
+class Vehicle < ActiveRecord::Base
+  include Locatable
+# … more code follows
+end
+```
+
+This first step guarantees invocation of the two `Locatable` <code>validates</code> method calls on the `Vehicle` object class.
+
+It does so by relying on `method_missing(method_name, *args, &block)` to record every class method call that happens in the super module class body, and later replaying those calls on the including base class during `self.included(base)` by using Ruby's `send(method_name, *args, &block)` method introspection.
+
+#### 2) Defines super module class methods on the including base class
+
+For example, suppose we have a super module called Addressable:
+
+```ruby
+module Addressable
+  include SuperModule
+  
+  include Locatable
+  validates :city, presence: true, length: { maximum: 255 }
+  validates :state, presence: true, length: { is: 2 }
+
+  def self.merge_duplicates
+    # 1. Look through all Addressable instances in the database
+    # 2. Identify duplicates
+    # 3. Merge duplicate addressables
+  end
+end
 
-This has been designed to be used only in the code definition of a module.
+class Contact < ActiveRecord::Base
+  include Addressable
+# … more code follows
+end
+```
+
+The second step ensures that <code>merge_duplicates</code> is included in Contact as a class method, allowing the call <code>Contact.merge_duplicates</code>
+
+It does so by recording every class method defined using the <code>self.singleton_method_added(method_name)</code> added hook, and then later replaying these class definitions on the including base class during invocation of <code>self.included(base)</code>.
+
+In order to avoid interference with existing class method definitions, there is an exception list for what not to record, such as <code>:included, :method_missing, :singleton_method_added</code> and any other "__" prefixed class methods defined in [SuperModule](https://rubygems.org/gems/super_module), such as <code>__super_module_class_method_calls</code>.
+
+## Limitations and Caveats
+
+ * [SuperModule](https://rubygems.org/gems/super_module) has been designed to be used only in the code definition of a module, not to be mixed in at run-time.
+
+ * Initial Ruby runtime load of a class or module mixing in [SuperModule](https://rubygems.org/gems/super_module) will incur a very marginal performance hit (in the order of nano-to-milliseconds). However, class usage (instantiation and method invocation) will not incur any performance hit, running as fast as any other Ruby class.
+
+ * Given [SuperModule](https://rubygems.org/gems/super_module) relies on <code>self.included(base)</code> in its implementation, if an including super module (or a super module including another super module) must hook into <code>self.included(base)</code> for meta-programming cases that require it, such as conditional `include` statements or method definitions, it would have to alias <code>self.included(base)</code> and then invoke the aliased version in every super module that needs it like in this example: 
+```ruby 
+module AdminIdentifiable
+    include SuperModule
+    include UserIdentifiable
+    
+    class << self
+        alias included_super_module included
+        def included(base)
+            included_super_module(base)
+            # do some extra work 
+            # like conditional inclusion of other modules
+            # or conditional definition of methods
+        end
+    end
+```
+In the future, [SuperModule](https://rubygems.org/gems/super_module) could perhaps provide robust built-in facilities for allowing super modules to easily hook into <code>self.included(base)</code> without interfering with [SuperModule](https://rubygems.org/gems/super_module) behavior.
+
+## Feedback and Contribution
+
+[SuperModule](https://rubygems.org/gems/super_module) is written in a very clean and maintainable test-first approach, so you are welcome to read through the code on GitHub for more in-depth details:
+https://github.com/AndyObtiva/super_module 
+
+The library is quite new and can use all the feedback and help it can get. So, please do not hesitate to add comments if you have any, and please fork [the project on GitHub](https://github.com/AndyObtiva/super_module#fork-destination-box) in order to [make contributions via Pull Requests](https://github.com/AndyObtiva/super_module/pulls).
+
+## Articles and Blog Posts
+
+ * 2015-03-27 - [AirPair](http://www.airpair.com) Article: [Step aside ActiveSupport::Concern. SuperModule is the new sheriff in town!](https://www.airpair.com/ruby/posts/step-aside-activesupportconcern-supermodule-is-the-new-sheriff-in-town)
+ * 2014-03-27 - [Code Painter](http://andymaleh.blogspot.com) Blog Post: [Ruby SuperModule Comes To The Rescue!!](http://andymaleh.blogspot.ca/2014/03/ruby-supermodule-comes-to-rescue.html)
 
 ## Copyright
 
-Copyright (c) 2014 Andy Maleh. See LICENSE.txt for
+Copyright (c) 2014-2015 Andy Maleh. See LICENSE.txt for
 further details.
-

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/examples/reddit-readers/banister/foo.rb

@@ -0,0 +1,8 @@
+require_relative '../../../lib/super_module'
+
+module Foo
+  include SuperModule
+  def self.hello
+    self
+  end
+end

data/examples/reddit-readers/banister/world.rb

@@ -0,0 +1,5 @@
+require_relative 'foo'
+
+class World
+  include Foo
+end

data/lib/super_module.rb

@@ -1,66 +1,39 @@
 # SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base).
 #
 # Author::    Andy Maleh
-# Copyright:: Copyright (c) 2014 Andy Maleh
+# Copyright:: Copyright (c) 2014-2015 Andy Maleh
 # License::   MIT License
 
 # This module allows defining class methods and method invocations the same way a super class does without using def included(base).
 
-module SuperModule
-  EXCLUDED_SINGLETON_METHODS = [
-    :__super_module_class_methods,
-    :__invoke_super_module_class_method_calls,
-    :__define_super_module_class_methods,
-    :__restore_original_method_missing,
-    :included, :method_missing,
-    :singleton_method_added
-  ]
-  def self.included(base)
-    base.class_eval do
-      class << self
-
-        def include(base, &block)
-          method_missing('include', base, &block)
-        end
+# Avoiding require_relative for backwards compatibility with Ruby 1.8.7
+require File.expand_path(File.join(File.dirname(__FILE__), 'super_module', 'module_body_method_call_recorder'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'super_module', 'singleton_method_definition_store'))
 
-        def __super_module_class_method_calls
-          @__super_module_class_method_calls ||= []
-        end
-
-        def __super_module_class_methods
-          @__super_module_class_methods ||= []
-        end
-
-        def singleton_method_added(method_name)
-          __super_module_class_methods << [method_name, method(method_name)] unless EXCLUDED_SINGLETON_METHODS.include?(method_name)
-          super
-        end
-
-        def method_missing(method_name, *args, &block)
-          __super_module_class_method_calls << [method_name, args, block]
-        end
+module SuperModule
+  def self.included(original_base)
+    original_base.class_eval do
+      extend SuperModule::ModuleBodyMethodCallRecorder
+      extend SuperModule::SingletonMethodDefinitionStore
 
-        def __invoke_super_module_class_method_calls(base)
-          __super_module_class_method_calls.each do |method_name, args, block|
-            base.class_eval do
-              send(method_name, *args, &block)
-            end
+      class << self
+        def __define_super_module_singleton_methods(base)
+          __super_module_singleton_methods.each do |method_name, method_body|
+            base.class_eval(method_body)
           end
         end
 
-        def __define_super_module_class_methods(base)
-          __super_module_class_methods.each do |method_name, method|
-            base.class_eval do
-              self.class.send(:define_method, method_name, &method)
-            end
+        def __invoke_module_body_method_calls(base)
+          __all_module_body_method_calls_in_definition_order.each do |method_name, args, block|
+            base.send(method_name, *args, &block)
           end
         end
 
         def included(base)
-          __invoke_super_module_class_method_calls(base)
-          __define_super_module_class_methods(base)
+          __define_super_module_singleton_methods(base)
+          __invoke_module_body_method_calls(base)
         end
       end
     end
   end
-end
+end

data/lib/super_module/module_body_method_call_recorder.rb

@@ -0,0 +1,40 @@
+module SuperModule
+  module ModuleBodyMethodCallRecorder
+    def __super_module_singleton_methods_excluded_from_call_recording
+      @__super_module_singleton_methods_excluded_from_call_recording ||= [
+        :__record_method_call,
+        :__method_signature
+      ]
+    end
+
+    def __module_body_method_calls
+      @__module_body_method_calls ||= []
+    end
+
+    def __method_signature(method_name, args)
+      "#{method_name}(#{args.to_a.map(&:to_s).join(",")})"
+    end
+
+    #TODO handle case of a method call being passed a block (e.g. validates do custom validator end )
+    def __record_method_call(method_name, *args, &block)
+      return if self.is_a?(Class)
+      __module_body_method_calls << [method_name, args, block]
+    end
+
+    def __all_module_body_method_calls_in_definition_order
+      ancestor_module_body_method_calls = included_super_modules.map(&:__module_body_method_calls).flatten(1)
+      all_module_body_method_calls = __module_body_method_calls + ancestor_module_body_method_calls
+      all_module_body_method_calls.reverse
+    end
+
+    def __singleton_method_call_recorder(method_name, method_args)
+      unless __super_module_singleton_methods_excluded_from_call_recording.include?(method_name)
+        method_call_recorder_args = "'#{method_name}'"
+        method_call_recorder_args << ", #{method_args}" unless method_args.to_s.strip == '' 
+        "self.__record_method_call(#{method_call_recorder_args})" 
+      end
+    end
+  end
+end
+   
+

data/lib/super_module/singleton_method_definition_store.rb

@@ -0,0 +1,91 @@
+require 'method_source'
+require File.expand_path(File.join(File.dirname(__FILE__), 'module_body_method_call_recorder')) # backwards compatible with Ruby 1.8.7
+
+module SuperModule
+  module SingletonMethodDefinitionStore
+    # excluded list of singleton methods to define (perhaps give a better name)
+    def __super_module_singleton_methods_excluded_from_base_definition
+      @__super_module_singleton_methods_excluded_from_base_definition ||= [
+        :__all_module_body_method_calls_in_definition_order,
+        :__build_singleton_method_body_source,
+        :__define_super_module_singleton_methods,
+        :__invoke_module_body_method_calls,
+        :__module_body_method_calls,
+        :__overwrite_singleton_method_from_current_super_module,
+        :__singleton_method_args,
+        :__singleton_method_body,
+        :__singleton_method_body_for,
+        :__singleton_method_call_recorder,
+        :__singleton_method_definition_regex,
+        :__super_module_having_method,
+        :__super_module_singleton_methods,
+        :__super_module_singleton_methods_excluded_from_base_definition,
+        :__super_module_singleton_methods_excluded_from_call_recording,
+        :class_eval,
+        :dbg_print, #debugger library friendly exclusion
+        :dbg_puts, #debugger library friendly exclusion
+        :included, 
+        :included_super_modules,
+        :singleton_method_added
+      ]
+    end
+
+    def __super_module_singleton_methods
+      @__super_module_singleton_methods ||= []
+    end
+    
+    def __singleton_method_body_for(super_module, method_name)
+      super_module.__super_module_singleton_methods.detect {|sm_method_name, sm_method_body| sm_method_name == method_name}[1]
+    end
+
+    def included_super_modules
+      included_modules.select {|m| m.include?(SuperModule)}
+    end
+
+    def __super_module_having_method(method_name)
+      included_super_modules.detect {|included_super_module| included_super_module.methods.map(&:to_s).include?(method_name.to_s)}
+    end
+
+    def __singleton_method_definition_regex(method_name)
+      /(send)?[ \t(:"']*def(ine_method)?[ \t,:"']+(self\.)?#{method_name}\)?[ \tdo{(|]*([^\n)|;]*)?[ \t)|;]*/m
+    end
+
+    def __singleton_method_args(method_name, method_body)
+      method_arg_match = method_body.match(__singleton_method_definition_regex(method_name)).to_a[4]
+    end
+
+    def __build_singleton_method_body_source(method_name)
+      method_body = self.method(method_name).source
+      method_args = __singleton_method_args(method_name, method_body)
+      method_body = "def #{method_name}\n#{method_body}\nend" if method_args.nil?
+      class_self_method_def_enclosure = "class << self\ndefine_method('#{method_name}') do |#{method_args}|\n#{__singleton_method_call_recorder(method_name, method_args)}\n"
+      method_body.sub(__singleton_method_definition_regex(method_name), class_self_method_def_enclosure) + "\nend\n"
+    end
+
+    def __singleton_method_body(method_name)
+        super_module_having_method = __super_module_having_method(method_name)
+        super_module_having_method ? __singleton_method_body_for(super_module_having_method, method_name) : __build_singleton_method_body_source(method_name) 
+    end
+
+    def __overwrite_singleton_method_from_current_super_module(method_name, method_body)
+      if __super_module_having_method(method_name).nil?
+        __super_module_singleton_methods_excluded_from_base_definition << method_name
+        class_eval(method_body)
+      end
+    end
+
+    def singleton_method_added(method_name)
+      unless __super_module_singleton_methods_excluded_from_base_definition.include?(method_name)
+        method_body = __singleton_method_body(method_name)
+        __super_module_singleton_methods << [method_name, method_body] 
+        __overwrite_singleton_method_from_current_super_module(method_name, method_body)
+      end
+    end
+
+    def self.extended(base)
+      base.extend(SuperModule::ModuleBodyMethodCallRecorder) unless base.respond_to?(:__record_method_call)
+      base.singleton_method_added(:__method_signature)
+      base.singleton_method_added(:__record_method_call)
+    end
+  end
+end

data/ruby187.Gemfile

@@ -0,0 +1,17 @@
+source "http://rubygems.org"
+
+gem "method_source", "~> 0.8.2"
+
+group :development do
+  gem "jeweler", "~> 2.0.1"
+  gem "rdoc", "~> 4.2.0"
+  gem "rspec", "~> 3.2.0"
+
+  # Ruby 1.8.7 support older gems
+  gem "mime-types", "~> 1.25.1"
+  gem "netrc", "~> 0.9.0"
+  gem "rest-client", "~> 1.6.0"
+  gem "nokogiri", "~> 1.5.0"
+  gem "highline", "~> 1.6.21"
+end
+

data/spec/lib/super_module_spec.rb

@@ -1,80 +1,133 @@
 require 'spec_helper'
 
 describe SuperModule do
-  module Foo
-    include SuperModule
-    validates 'foo', presence: true
 
-    def self.foo
-      'self.foo'
+  class FakeActiveRecord
+    include FakeActiveModel
+  end
+
+  class FooActiveRecord < FakeActiveRecord
+    include Foo
+  end
+
+  class BarActiveRecord < FakeActiveRecord
+    include Bar
+  end
+
+  class BazActiveRecord < FakeActiveRecord
+    include Baz
+  end
+
+  context "included by a module (Foo) that is included by a class (FooActiveRecord)" do
+
+    subject { FooActiveRecord }
+
+    it 'allows invoking class methods' do
+      expect(subject.validations).to include(['foo', {:presence => true}])
     end
 
-    def foo
-      'foo'
+    it 'includes class methods declared via "self.method_name"' do
+      expect(subject.foo).to eq('self.foo')
     end
-  end
-  module Bar
-    include SuperModule
-    validates 'bar', presence: true
 
-    class << self
-      def bar
-        'self.bar'
-      end
+    it 'includes instance methods' do
+      instance = subject.new
+
+      expect(instance.foo).to eq('foo')
     end
 
-    def bar
-      'bar'
+    it 'provides class method self as the including base class as in the class method (meh)' do
+      expect(subject.meh).to eq(subject)
     end
   end
-  class FakeActiveRecord
-    class << self
-      def validates(attribute, options)
-        validations << [attribute, options]
-      end
-      def validations
-        @validations ||= []
-      end
+
+  context "included by a module (Foo) that is included by a second module (Bar) that is included by a class (BarActiveRecord)" do
+
+    subject { BarActiveRecord }
+
+    it 'allows invoking class methods' do
+      expect(subject.validations).to include(['foo', {:presence => true}])
+      expect(subject.validations).to include(['bar', {:presence => true}])
     end
-  end
 
-  context "a base class includes a module enhanced as a super module" do
-    before do
-      FakeActiveRecord.send(:include, Foo)
+    it 'includes class methods declared via "class << self"' do
+      expect(subject.foo).to eq('self.foo')
+      expect(subject.bar).to eq('self.bar')
     end
 
-    it 'allows invoking class methods in the including base class body' do
-      FakeActiveRecord.validations.should include(['foo', {presence: true}])
+    it 'includes instance methods' do
+      instance = subject.new
+
+      expect(instance.foo).to eq('foo')
+      expect(instance.bar).to eq('bar')
+    end
+
+    it 'can include a basic module (Forwardable) into singleton class by placing in class << self' do 
+      instance = subject.new
+      expect(instance.length).to eq(3)
     end
-    it 'includes instance methods in the including base class' do
-      instance = FakeActiveRecord.new
 
-      instance.foo.should == 'foo'
+    it 'applies super module (Bar) class method invocation (make_barrable) on including class (BarActiveRecord), whereby the method that is defined in the same super module that declares it (Bar)' do
+      expect(subject.barrable).to eq(true)
     end
-    it 'includes class methods in the including base class' do
-      FakeActiveRecord.foo.should == 'self.foo'
+
+    it 'can include a basic module (Comparable)' do 
+      now = Time.now
+      allow(Time).to receive(:now).and_return(now)
+      instance = subject.new
+      allow(Time).to receive(:now).and_return(now + 100)
+      instance2 = subject.new
+
+      expect(instance2 > instance).to eq(true)
     end
+
+    it 'provides class method self as the including base class as in the class method (meh)' do
+      expect(subject.meh).to eq(subject)
+    end
+
+         #TODO explicitly declare test cases in support files as it statements
+         #TODO test empty method definition
+         #TODO test empty method definition with comment
+         #TODO test case of method call receiving a block 
   end
 
-  context "a base class includes a base module enhanced as a super module that includes another module enhanced as a super module" do
-    before do
-      Bar.send(:include, Foo)
-      FakeActiveRecord.send(:include, Bar)
+  context "included by a module (Foo), included by another module (Bar), included by a third module (Baz) that is included by a class (BazActiveRecord)" do
+
+    subject { BazActiveRecord }
+
+    it 'allows invoking class methods' do
+      expect(subject.validations).to include(['foo', {:presence => true}])
+      expect(subject.validations).to include(['bar', {:presence => true}])
+      expect(subject.validations).to include(['baz', {:presence => true}])
+    end
+
+    it 'includes class methods declared via "class << self"' do
+      expect(subject.foo).to eq('self.foo')
+      expect(subject.bar).to eq('self.bar')
+      expect(subject.baz).to eq('self.baz')
+    end
+
+    it 'includes instance methods' do
+      instance = BazActiveRecord.new(100)
+
+      expect(instance.foo).to eq('foo')
+      expect(instance.bar).to eq('bar')
+      expect(instance.baz).to eq('baz')
     end
 
-    it 'allows invoking class methods in the including base class body' do
-      FakeActiveRecord.validations.should include(['foo', {presence: true}])
-      FakeActiveRecord.validations.should include(['bar', {presence: true}])
+    it 'invokes singleton method (make_barrable) from super module' do
+      expect(subject.barrable).to eq(true)
     end
-    it 'includes instance methods in the including base class' do
-      instance = FakeActiveRecord.new
 
-      instance.foo.should == 'foo'
-      instance.bar.should == 'bar'
+    it 'can override super module behavior (<=>)' do 
+      instance = subject.new(50)
+      instance2 = subject.new(7)
+
+      expect(instance2 > instance).to eq(false)
     end
-    it 'includes class methods in the including base class' do
-      FakeActiveRecord.foo.should == 'self.foo'
-      FakeActiveRecord.bar.should == 'self.bar'
+
+    it 'provides class method self as the including base class as in the class method (meh)' do
+      expect(subject.meh).to eq(subject)
     end
   end
 

data/spec/support/bar.rb

@@ -0,0 +1,52 @@
+require 'forwardable'
+
+module Bar
+
+  include SuperModule
+  include Foo
+  include Comparable
+  validates 'bar', {:presence => true}
+  attr_reader :created_at
+
+  # Defines singleton methods via class << self to provide as a test case for SuperModule
+  class << self
+    include Forwardable
+
+    def barrable
+      @barrable
+    end
+
+    def barrable=(value)
+      @barrable = value
+    end
+
+    def make_barrable
+      self.barrable = true
+    end
+  end
+
+  make_barrable
+  def_delegators :@bar, :length
+
+  def initialize
+    @bar = bar
+    @created_at = Time.now.to_f
+  end
+
+  def bar
+    'bar'
+  end
+
+  # Defines singleton method via a form of eval (class_eval) to provide as a test case for SuperModule
+  class_eval do
+    def self.bar
+      'self.bar'
+    end
+  end
+  
+  def <=>(other)
+    created_at <=> other.created_at
+  end
+
+end
+

data/spec/support/baz.rb

@@ -0,0 +1,29 @@
+module Baz
+
+  include SuperModule
+  include Bar
+  make_barrable
+  validates 'baz', {:presence => true}
+  attr_reader :baz_factor
+  
+  class << self
+    def baz
+      'self.baz'
+    end
+  end
+  
+  def initialize(baz_factor)
+    super()
+    @baz_factor = baz_factor
+  end
+
+  def baz
+    'baz'
+  end
+
+  def <=>(other)
+    baz_factor <=> other.baz_factor
+  end
+
+end
+

data/spec/support/fake_active_model.rb

@@ -0,0 +1,14 @@
+# Uses CRLF for line breaks to provide a test case for having SuperModule work with it
+# This is done to test support for Windows Ruby files, which usually use CRLF for line breaks
+module FakeActiveModel
+
+  include SuperModule
+
+  # Defines method on a single line to provide as a test case for SuperModule
+  def self.validates(attribute, options); validations << [attribute, options]; end
+
+  # Defines method on a single line to provide as a test case for SuperModule
+  def self.validations; @validations ||= []; end
+
+end
+

data/spec/support/foo.rb

@@ -0,0 +1,23 @@
+module Foo
+
+  include SuperModule
+  include FakeActiveModel
+  validates 'foo', {:presence => true}
+
+  def self.foo
+    'self.foo'
+  end
+
+  # Defines singleton method via define_method to provide as a test case for SuperModule
+  class << self
+    send(:define_method, :meh) do
+      self
+    end
+  end
+
+  def foo
+    'foo'
+  end
+
+end
+

data/spec/support/support.rb

@@ -0,0 +1,4 @@
+require File.join(File.dirname(__FILE__), 'fake_active_model')
+require File.join(File.dirname(__FILE__), 'foo')
+require File.join(File.dirname(__FILE__), 'bar')
+require File.join(File.dirname(__FILE__), 'baz')

data/super_module.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: super_module 1.0.0 ruby lib
+# stub: super_module 1.1.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "super_module"
-  s.version = "1.0.0"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Andy Maleh"]
-  s.date = "2014-03-27"
+  s.date = "2015-04-06"
   s.description = "SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base). This also succeeds ActiveSupport::Concern by offering lighter syntax"
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -23,28 +23,44 @@ Gem::Specification.new do |s|
     "README.md",
     "SuperModule.jpg",
     "VERSION",
+    "examples/reddit-readers/banister/foo.rb",
+    "examples/reddit-readers/banister/world.rb",
     "lib/super_module.rb",
+    "lib/super_module/module_body_method_call_recorder.rb",
+    "lib/super_module/singleton_method_definition_store.rb",
+    "ruby187.Gemfile",
     "spec/lib/super_module_spec.rb",
+    "spec/support/bar.rb",
+    "spec/support/baz.rb",
+    "spec/support/fake_active_model.rb",
+    "spec/support/foo.rb",
+    "spec/support/support.rb",
     "super_module.gemspec"
   ]
   s.homepage = "http://github.com/AndyObtiva/super_module"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.2.2"
+  s.rubygems_version = "2.4.6"
   s.summary = "SuperModule allows defining class methods and method invocations the same way a super class does without using def included(base). This also succeeds ActiveSupport::Concern by offering lighter syntax"
 
   if s.respond_to? :specification_version then
     s.specification_version = 4
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<jeweler>, ["~> 2.0"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_runtime_dependency(%q<method_source>, ["~> 0.8.2"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_development_dependency(%q<rdoc>, ["~> 4.2.0"])
+      s.add_development_dependency(%q<rspec>, ["~> 3.2.0"])
     else
-      s.add_dependency(%q<jeweler>, ["~> 2.0"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<method_source>, ["~> 0.8.2"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_dependency(%q<rdoc>, ["~> 4.2.0"])
+      s.add_dependency(%q<rspec>, ["~> 3.2.0"])
     end
   else
-    s.add_dependency(%q<jeweler>, ["~> 2.0"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<method_source>, ["~> 0.8.2"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    s.add_dependency(%q<rdoc>, ["~> 4.2.0"])
+    s.add_dependency(%q<rspec>, ["~> 3.2.0"])
   end
 end
 

metadata

@@ -1,43 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: super_module
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Andy Maleh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-27 00:00:00.000000000 Z
+date: 2015-04-06 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.2
 - !ruby/object:Gem::Dependency
   name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.0.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.0.1
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 4.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.2.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.12'
+        version: 3.2.0
 description: SuperModule allows defining class methods and method invocations the
   same way a super class does without using def included(base). This also succeeds
   ActiveSupport::Concern by offering lighter syntax
@@ -53,8 +81,18 @@ files:
 - README.md
 - SuperModule.jpg
 - VERSION
+- examples/reddit-readers/banister/foo.rb
+- examples/reddit-readers/banister/world.rb
 - lib/super_module.rb
+- lib/super_module/module_body_method_call_recorder.rb
+- lib/super_module/singleton_method_definition_store.rb
+- ruby187.Gemfile
 - spec/lib/super_module_spec.rb
+- spec/support/bar.rb
+- spec/support/baz.rb
+- spec/support/fake_active_model.rb
+- spec/support/foo.rb
+- spec/support/support.rb
 - super_module.gemspec
 homepage: http://github.com/AndyObtiva/super_module
 licenses:
@@ -76,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: SuperModule allows defining class methods and method invocations the same