super_module 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9bd0e7f146de1366ca97c760ab283ca3f3623c44
-  data.tar.gz: ce3dad2bf81e80135bfaaea2fbdf2e305359e8b6
+  metadata.gz: 2417fe4ac87bcf7e975d971de2f86caa01f1f357
+  data.tar.gz: 305eda58e8250ce45e24af27325ba09f2f34c9f1
 SHA512:
-  metadata.gz: 6f28bdb35c1cf93c1a0b4a98d3f22726ca95e02e1f95458b1965fa2d097f6497da7c2359ae6dcb656db49c0443f5f8fe0c1f270efffee6a5ee0da91571247547
-  data.tar.gz: d698ce744051e84c772eb32c38fed978e8b4711e846012a2c6cd8b3cc3058f8a95de27f2a28b01cdb7ca3ef01f44c5f249f282086d6187830adfbff7a6e96c8b
+  metadata.gz: f4eea83f2a17b20dd8c40ab3f5e710f702c501936fea5782dbfb8295ee5c3a8a7889479d742777bbfa6151d8aa6ccfdc71ab4fdbd9431e2a13dbd4f0986f1f1a
+  data.tar.gz: 071b746e0e94003c5716724e9b51744986bd28c388492ed55284d9c65f8c445393d2688e2e8be0046b101bbb6bccaed75a97a472c2356c4b748012541efbad2a

data/README.md

@@ -1,4 +1,4 @@
-# <img src="https://raw.githubusercontent.com/AndyObtiva/super_module/master/SuperModule.jpg" alt="SuperModule" align="left" height="50" /> &nbsp; SuperModule v1.1.1 [2015-04-09]
+# <img src="https://raw.githubusercontent.com/AndyObtiva/super_module/master/SuperModule.jpg" alt="SuperModule" align="left" height="50" /> &nbsp; SuperModule 2 Beta (1.2.0)
 [![Gem Version](https://badge.fury.io/rb/super_module.svg)](http://badge.fury.io/rb/super_module)
 [![Build Status](https://api.travis-ci.org/AndyObtiva/super_module.svg?branch=master)](https://travis-ci.org/AndyObtiva/super_module)
 [![Coverage Status](https://coveralls.io/repos/AndyObtiva/super_module/badge.svg?branch=master)](https://coveralls.io/r/AndyObtiva/super_module?branch=master)
@@ -8,7 +8,7 @@ Calling [Ruby](https://www.ruby-lang.org/en/)'s [`Module#include`](http://ruby-d
 
 [`ActiveSupport::Concern`](http://api.rubyonrails.org/classes/ActiveSupport/Concern.html) is a popular Rails library that attempts to ease some of the boilerplate pain by offering a [DSL](http://www.infoq.com/news/2007/06/dsl-or-not) layer on top of [`Module.included(base)`](http://ruby-doc.org/core-2.2.1/Module.html#method-i-included). Unfortunately, while it improves the readability of the code needed to include class methods, it supports the same boilerplate idiom, thus feeling no more than putting a band-aid on the problem.
 
-Fortunately, [SuperModule](https://rubygems.org/gems/super_module) comes to the rescue. Including `SuperModule` at the top of a Ruby module's body automatically ensures inclusion of class methods whenever a developer mixes it in via [`Module#include`](http://ruby-doc.org/core-2.2.1/Module.html#method-i-include).
+Fortunately, [SuperModule](https://rubygems.org/gems/super_module) comes to the rescue. By declaring your module as a `super_module`, it will automatically include class methods whenever it is mixed into a class or another module via [`Module#include`](http://ruby-doc.org/core-2.2.1/Module.html#method-i-include).
 
 ## Introductory Comparison
 
@@ -72,8 +72,7 @@ A step forward that addresses the boiler-plate repetitive code concern, but is o
 #### 3) [SuperModule](https://github.com/AndyObtiva/super_module)
 
 ```ruby
-module UserIdentifiable
-  include SuperModule
+super_module :UserIdentifiable do
   include ActiveModel::Model
   
   belongs_to :user
@@ -88,13 +87,21 @@ module UserIdentifiable
   end
 end
 ```
+Using `super_module`, 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.
 
-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. 
+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.
 
+By the way, SuperModule 2 Beta supports an alternate syntax as well:
+
+```ruby
+UserIdentifiable = super_module do
+end
+```
+
+
+
 ## Instructions
 
 #### 1) Install and require gem
@@ -115,11 +122,10 @@ Run the following command: <pre>gem install super_module</pre>
 
 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
+#### 2) Call `super_module(name)` and pass it the super module body in a block
 
 ```ruby
-module UserIdentifiable
-  include SuperModule
+super_module :UserIdentifiable do
   include ActiveModel::Model
 
   belongs_to :user
@@ -144,8 +150,7 @@ end
 class CourseEnrollment < ActiveRecord::Base
   include UserIdentifiable
 end
-module Accountable
-  include SuperModule
+super_module :Accountable do
   include UserIdentifiable
 end
 class Activity < ActiveRecord::Base
@@ -188,8 +193,7 @@ Create a ruby file called super_module_irb_example.rb with the following content
 require 'rubygems' # to be backwards compatible with Ruby 1.8.7
 require 'super_module'
 
-module RequiresAttributes
-  include SuperModule
+super_module :RequiresAttributes do
 
   def self.requires(*attributes)
     attributes.each {|attribute| required_attributes << attribute}
@@ -255,85 +259,20 @@ media_authorization.requirements_satisfied?
 
 ## How Does It Work?
 
-Here is the general algorithm from the implementation:
-
-```ruby
-def included(base)
-  __define_super_module_class_methods(base)
-  __invoke_super_module_class_method_calls(base)
-end
-```
-
-#### 1) 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
-
-class Contact < ActiveRecord::Base
-  include Addressable
-# … more code follows
-end
-```
-
-This 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 Ruby [`self.singleton_method_added(method_name)`](http://ruby-doc.org/core-2.2.1/BasicObject.html#method-i-singleton_method_added) hook, reading class method sources using the [method_source](https://rubygems.org/gems/method_source/) gem, and finally upon invocation of `self.included(base)`, `class_eval`ing the recorded class methods on the including base class (or module).
-
-In order to avoid interference with existing class method definitions, there is an exception list for what not to record, such as <code>:included_super_modules, :class_eval, :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>.
-
-Also, the recorded class method sources are altered to handle recording of method calls as well, which is used in the second step explained next.
-
-#### 2) Invoke super module class method calls on the including base class (or module).
-
-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
-```
+V2 has a much simpler algorithm than V1 that goes as follows:
 
-This step guarantees invocation of the two `Locatable` <code>validates</code> method calls on the `Vehicle` object class.
-
-It does so by relying on an interally defined method `__record_method_call(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.
+1. Handle invocation of `super_module(name, &super_module_body)` method anywhere in the Ruby code where the block it receives represents the super module body, including instance methods, and class methods, and class body invocations.
+2. Clone `SuperModule` and store in it the passed in `super_module_body` block
+3. Assign the cloned `SuperModule` to a new constant as defined by name (e.g. 'Utilities::Printer') under a class, module, or the top-level Ruby scope
+4. When calling `include` on the module later on, its stored super_module_body attribute is retrieved and run in the including class or module body via `class_eval`
 
 ## 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.
+ * [SuperModule](https://rubygems.org/gems/super_module) has been designed to be used only in the initial code definition of a module (not supporting later re-opening of the module.)
 
  * Given [SuperModule](https://rubygems.org/gems/super_module)'s implementation relies on `self.included(base)`, 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
+super_module :AdminIdentifiable do
     include UserIdentifiable
     
     class << self
@@ -345,11 +284,19 @@ module AdminIdentifiable
             # or conditional definition of methods
         end
     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.
 
 ## What's New?
 
+### v2 Beta (v1.2.0)
+
+* New `super_module(name)` syntax
+* Much simpler implementation with guaranteed correctness and no performance hit
+* Less memory footprint by not requiring method_source Ruby gem for v2 syntax
+* Backwards compatibility with v1 syntax
+
 ### v1.1.1
 
 * Added support for private and protected methods
@@ -378,5 +325,5 @@ The library is quite new and can use all the feedback and help it can get. So, p
 
 ## Copyright
 
-Copyright (c) 2014-2015 Andy Maleh. See LICENSE.txt for
+Copyright (c) 2014-2016 Andy Maleh. See LICENSE.txt for
 further details.

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

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

@@ -1,7 +1,6 @@
 require_relative '../../../lib/super_module'
 
-module Foo
-  include SuperModule
+super_module :Foo
   def self.hello
     self
   end

data/lib/super_module.rb

@@ -7,35 +7,50 @@
 # This module allows defining class methods and method invocations the same way a super class does without using def included(base).
 
 # 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'))
 
 module SuperModule
-  def self.included(original_base)
-    original_base.class_eval do
-      extend SuperModule::ModuleBodyMethodCallRecorder
-      extend SuperModule::SingletonMethodDefinitionStore
-
-      class << self
-        def __define_super_module_singleton_methods(base)
-          __super_module_singleton_methods.each do |method_name, method_body|
-            # The following is needed for cases where a method is declared public/protected/private after it was added
-            refreshed_access_level_method_body = method_body.sub(/class << self\n(public|protected|private)\n/, "class << self\n#{__singleton_method_access_level(method_name)}\n")
-            base.class_eval(refreshed_access_level_method_body)
-          end
-        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)
-          __define_super_module_singleton_methods(base)
-          __invoke_module_body_method_calls(base)
-        end
+  class << self
+    V1_LIBRARY = File.expand_path(File.join(File.dirname(__FILE__), 'super_module', 'v1'))
+  
+    attr_accessor :super_module_body
+
+    def define(&super_module_body)
+      clone.tap { |super_module| super_module.super_module_body = super_module_body }
+    end
+
+    def included(original_base)
+      if super_module_body
+        original_base.class_eval(&super_module_body)
+      else
+        require V1_LIBRARY
+        original_base.send(:include, SuperModule::V1)
+      end
+    end
+
+    def __super_module_parent(name, ancestor)
+      name_tokens = name.to_s.split('::')
+      name_token_count = name_tokens.size
+      if name_token_count == 1
+        ancestor
+      else
+        top_ancestor = ancestor.const_get(name_tokens.first)
+        sub_module_name = name_tokens[1, name_token_count].join('::')
+        __super_module_parent(sub_module_name, top_ancestor)
       end
     end
+
+  end
+  
+end
+
+def super_module(name=nil, &super_module_body)
+  initial_ancestor = self.class == Object ? Object : self
+  SuperModule.define(&super_module_body).tap do |new_super_module|
+    if name
+      parent = SuperModule.__super_module_parent(name, initial_ancestor)
+      module_name = name.to_s.split('::').last
+      parent.const_set(module_name, new_super_module)
+    end
   end
 end
+

data/lib/super_module/v1.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'v1', 'module_body_method_call_recorder'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'v1', 'singleton_method_definition_store'))
+
+module SuperModule
+  module V1
+    class << self
+      def included(original_base)
+        original_base.class_eval do
+          extend SuperModule::V1::ModuleBodyMethodCallRecorder
+          extend SuperModule::V1::SingletonMethodDefinitionStore
+
+          class << self
+            def __define_super_module_singleton_methods(base)
+              __super_module_singleton_methods.each do |method_name, method_body|
+                # The following is needed for cases where a method is declared public/protected/private after it was added
+                refreshed_access_level_method_body = method_body.sub(/class << self\n(public|protected|private)\n/, "class << self\n#{__singleton_method_access_level(method_name)}\n")
+                base.class_eval(refreshed_access_level_method_body)
+              end
+            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)
+              __define_super_module_singleton_methods(base)
+              __invoke_module_body_method_calls(base)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/super_module/v1/module_body_method_call_recorder.rb

@@ -0,0 +1,42 @@
+module SuperModule
+  module V1
+    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
+end
+   
+

data/lib/super_module/v1/singleton_method_definition_store.rb

@@ -0,0 +1,106 @@
+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 V1
+    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
+          :define,
+          :included, 
+          :included_super_modules,
+          :singleton_method_added,
+          :super_module_body
+        ]
+      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 __all_methods(object)
+        object.public_methods + object.protected_methods + object.private_methods
+      end
+
+      def __super_module_having_method(method_name)
+        included_super_modules.detect {|included_super_module| __all_methods(included_super_module).map(&:to_s).include?(method_name.to_s)}
+      end
+
+      def __singleton_method_definition_regex(method_name)
+        /(public|protected|private)?(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[5]
+      end
+
+      def __singleton_method_access_level(method_name)
+        %w(private protected public).detect do |method_access|
+          method_group = "#{method_access}_methods"
+          send(method_group).map(&:to_s).include?(method_name.to_s)
+        end
+      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\n#{__singleton_method_access_level(method_name)}\ndef #{method_name}(#{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
+end