retroactive_module_inclusion 1.1.0 → 1.2.0

data/.yardopts

@@ -1,3 +1,2 @@
---private
 lib/*.rb
 README.rdoc History.rdoc

data/History.rdoc

@@ -1,9 +1,20 @@
+=== 1.2.0 / 2011-01-23
+
+* 2 minor enhancements
+
+  * Chaged #retroactively_include visibility to public and updated tests accordingly
+    * motivated by this discussion {this discussion}[https://github.com/lsegal/yard/issues/issue/242/] with Loren Segal
+
+  * Better documentation:
+    * many README and History fixes and improvements
+    * code documentation enhanced with YARD tags
+
 === 1.1.0 / 2011-01-22
 
 * 2 minor enhancements
 
   * Refactored retroactively_include method from ::Module to
-    CoreExt::Module::RetroactiveModuleInclusion, after Ola Bini suggested
+    CoreExt::Module::RetroactiveModuleInclusion, after what Ola Bini suggested
     in his post {SAFE(R) MONKEY PATCHING}[http://olabini.com/blog/2011/01/safeer-monkey-patching/]
 
   * Finally, managed to make yard document the retroactively_include method:

data/README.rdoc

@@ -39,7 +39,7 @@ included Enumerable (e.g., the Range class). Unfortunately, this is not the case
   (1..2).mean  #=>  NoMethodError: undefined method `mean' for 1..2:Range
 
 Surely this behaviour does not conform to the least surprise principle.
-In fact, this inconsistency stems from implementation efficienty concerns
+In fact, this inconsistency stems from efficienty concerns
 and characterize a limitation in Ruby's object model (see {Dynamic Module Include Problem}[http://eigenclass.org/hiki/The+double+inclusion+problem]).
 
 In face of that, one has basically two possible solutions. The first is to give up Stats and define the method directly inside Enumerable
@@ -53,8 +53,19 @@ In face of that, one has basically two possible solutions. The first is to give
 
 The second, more concise and elegant, is to use this gem
 
+  Enumerable.retroactively_include Stats
+
+Note that the method retroactively_include, which was private in early
+versions, became public in v1.2.0. Nevertheless, one can still call
+
   Enumerable.module_eval { retroactively_include Stats }
 
+or
+
+  Enumerable.send :retroactively_include, Stats
+
+to the same effect.
+
 == FEATURES:
 
 * Tested on all major Ruby interpreters (100% coverage, 0% failure):
@@ -67,9 +78,13 @@ The second, more concise and elegant, is to use this gem
 == SYNOPSIS:
 
   SomeModule.module_eval { retroactively_include AnotherModule }
-  
+
 or equivalently
 
+  SomeModule.send :retroactively_include, AnotherModule
+
+or still
+
   module SomeModule
     retroactively_include AnotherModule
   end

data/Rakefile

@@ -8,7 +8,7 @@ require 'hoe'
 Hoe.spec 'retroactive_module_inclusion' do
   developer('Adriano Mitre', 'adriano.mitre@gmail.com')
   
-  self.version = '1.1.0'
+  self.version = '1.2.0'
 
   self.readme_file = 'README.rdoc'
   self.history_file = 'History.rdoc'

data/lib/retroactive_module_inclusion.rb

@@ -2,12 +2,10 @@ module CoreExt
   module Module
     module RetroactiveModuleInclusion
 
-      private
-
       # Includes +mod+ retroactively, i.e., extending to all classes and modules which
       # had included +self+ _beforehand_.
       #
-      # Example:
+      # @example Retroactively include a module in Enumerable.
       #
       #   module Stats
       #     def mean
@@ -19,17 +17,23 @@ module CoreExt
       #
       #   (1..2).mean  #=>  1.5
       #
-      def retroactively_include(mod) # :doc:
+      # @return self
+      #
+      def retroactively_include(mod)
         raise TypeError, "wrong argument type #{mod.class} (expected Module)" unless mod.is_a? ::Module # ::Module would in general be equivalent to Object::Module and simply Module would mean CoreExt::Module in this context
-
-        # Although one would expect +A.module_eval("include B")+ to make methods
-        # from module +B+ available to all classes and modules that had previously
-        # included module +A+, this is not the case due to a limitation in Ruby's
-        # object model (see [dynamic module include problem][1]). Thus, one has two
-        # possible solutions:
-        #   * use Module#include_retroactively instead of Module#include
-        #   * reopen +A+ and define the methods directly inside it
-        #
+        
+        pseudo_descendants.each do |pd|
+          pd.module_eval { include mod }
+        end
+        
+        self
+      end
+      
+      private
+      
+      # @return [Array] All modules and classes which have self in its ancestors tree, including self itself.
+      #
+      def pseudo_descendants
         # JRuby (at least up to version 1.5.6) has ObjectSpace disabled by default,
         # thus it must be enabled manually ([reference][2]).
         #
@@ -42,14 +46,16 @@ module CoreExt
           prev_jruby_objectspace_state = JRuby.objectspace
           JRuby.objectspace = true
         end
+        result = []
         ObjectSpace.each_object(::Module) do |m|
           if m <= self # equiv. to "if m.include?(self) || m == self"
-            m.module_eval { include mod }
+            result << m
           end
         end
         if defined?(RUBY_DESCRIPTION) && RUBY_DESCRIPTION =~ /jruby/i
           JRuby.objectspace = prev_jruby_objectspace_state
         end
+        result
       end
       
       ::Module.class_eval { include CoreExt::Module::RetroactiveModuleInclusion }

data/test/test_retroactive_module_inclusion.rb

@@ -1,10 +1,14 @@
 require "test/unit"
 require File.expand_path("../../lib/retroactive_module_inclusion", __FILE__)
 
-module Stats
-  def mean
-    inject(&:+) / count.to_f
-  end
+[1,2].each do |n|
+  eval <<-EOS
+    module Stats#{n}
+      def mean#{n}
+        inject(&:+) / count.to_f
+      end
+    end
+  EOS
 end
 
 class TestRetroactiveInclude < Test::Unit::TestCase
@@ -18,13 +22,33 @@ class TestRetroactiveInclude < Test::Unit::TestCase
     type_ok(Numeric, Math)
   end
   
-  def test_retroactively_include
-    assert_raise(NoMethodError) { (1..2).mean }
-    Enumerable.module_eval { include Stats }
-    assert_raise(NoMethodError, 'include should not work retroactively ') { (1..2).mean }
-    Enumerable.module_eval { retroactively_include Stats }
-    assert_nothing_raised('retroactively_include should do the job') { (1..2).mean }
-    assert_equal 1.5, (1..2).mean
+  def test_retroactively_include_private
+    assert_raise(NoMethodError) { (1..2).mean1 }
+    Enumerable.module_eval { include Stats1 }
+    assert_raise(NoMethodError, 'include should not work retroactively ') { (1..2).mean1 }
+    Enumerable.module_eval { retroactively_include Stats1 }
+    assert_nothing_raised('retroactively_include should do the job') { (1..2).mean1 }
+    assert_equal 1.5, (1..2).mean1
+  end
+  
+  def test_retroactively_include_public
+    assert_raise(NoMethodError) { (1..2).mean2 }
+    Enumerable.module_eval { include Stats2 }
+    assert_raise(NoMethodError, 'include should not work retroactively ') { (1..2).mean2 }
+    Enumerable.module_eval { retroactively_include Stats2 }
+    assert_nothing_raised('retroactively_include should do the job') { (1..2).mean2 }
+    assert_equal 1.5, (1..2).mean2
+  end
+  
+  def test_jruby_object_space_prev_state
+    if defined?(RUBY_DESCRIPTION) && RUBY_DESCRIPTION =~ /jruby/i
+      require 'jruby'
+      [true, false].each do |prev_state|
+        JRuby.objectspace = prev_state
+        Enumerable.module_eval { include Stats1 }
+        assert_equal prev_state, JRuby.objectspace
+      end
+    end
   end
   
   private

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: retroactive_module_inclusion
 version: !ruby/object:Gem::Version 
-  hash: 19
-  prerelease: 
+  prerelease: false
   segments: 
   - 1
-  - 1
+  - 2
   - 0
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Adriano Mitre
@@ -36,7 +35,7 @@ cert_chain:
   9u8N6mQNneIVRh6Xfdko/Q==
   -----END CERTIFICATE-----
 
-date: 2011-01-22 00:00:00 -02:00
+date: 2011-01-23 00:00:00 -02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,7 +46,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 47
         segments: 
         - 2
         - 8
@@ -98,7 +96,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -107,14 +104,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: retroactive_module_inclusion
-rubygems_version: 1.4.1
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: This gem circumvents the "dynamic module include" (aka "double inclusion") problem, which is the fact that M.module_eval { include N } does not make the methods of module N available to modules and classes which had included module M beforehand, only to the ones that include it thereafter