retroactive_module_inclusion 1.0.0

data/.autotest

@@ -0,0 +1,23 @@
+# -*- ruby -*-
+
+require 'autotest/restart'
+
+# Autotest.add_hook :initialize do |at|
+#   at.extra_files << "../some/external/dependency.rb"
+#
+#   at.libs << ":../some/external"
+#
+#   at.add_exception 'vendor'
+#
+#   at.add_mapping(/dependency.rb/) do |f, _|
+#     at.files_matching(/test_.*rb$/)
+#   end
+#
+#   %w(TestA TestB).each do |klass|
+#     at.extra_class_map[klass] = "test/test_misc.rb"
+#   end
+# end
+
+# Autotest.add_hook :run_command do |at|
+#   system "rake build"
+# end

data/History.rdoc

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2011-01-19
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+.autotest
+History.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/retroactive_module_inclusion.rb
+test/test_retroactive_module_inclusion.rb

data/README.rdoc

@@ -0,0 +1,118 @@
+= retroactive_module_inclusion
+
+* http://github.com/adrianomitre/retroactive_module_inclusion
+
+== DESCRIPTION:
+
+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. This
+behaviour hurts the least surprise principle, specially because if K is a
+class, then
+  K.class_eval { include M }
+_does_ make all methods of M available to all classes which had previously
+inherited it. This inconsistency stems from implementation efficienty concerns
+and characterize a limitation in Ruby's object model (see {Dynamic Module Include Problem}[http://eigenclass.org/hiki/The+double+inclusion+problem]).
+
+== AN EXAMPLE OF THE "DYNAMIC MODULE INCLUDE" PROBLEM
+
+Let's begin by defining a one-method module:
+
+  module Stats
+    def mean
+      n = 1
+      inject {|s,k| n += 1 ; s + k }.to_f / count
+    end
+  end
+
+Including it in Array makes Stats#mean available to all arrays:
+  
+  Array.class_eval { include Stats }
+  [1, 2].mean  #=>  1.5
+  
+Therefore one could reasonably expect that if we include Stats into Enumerable,
+Stats#mean would be available to all classes and modules who had previously
+included Enumerable (e.g., the Range class). Unfortunately, this is not the case:
+
+  Enumerable.module_eval { include Stats }
+  (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
+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
+
+  module Enumerable
+    def mean
+      n = 1
+      inject {|s,k| n += 1 ; s + k }.to_f / count
+    end
+  end
+
+The second, more concise and elegant, is to use this gem
+
+  Enumerable.module_eval { retroactively_include Stats }
+
+== FEATURES/PROBLEMS:
+
+* Tested on all major Ruby interpreters (100% coverage, 0% failures):
+  * ruby-1.9.2-p136
+  * ruby-1.8.7-p330
+  * ree-1.8.7-2010.02
+  * jruby-1.5.6
+  * rbx-1.2.0-20101221
+
+== SYNOPSIS:
+
+  SomeModule.module_eval { retroactively_include AnotherModule }
+  
+or equivalently
+
+  module SomeModule
+    retroactively_include AnotherModule
+  end
+
+== REQUIREMENTS:
+
+* None: this gem does not depend on any other gem.
+
+== INSTALL:
+
+* sudo gem install retroactive_module_inclusion
+
+== DEVELOPERS:
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Adriano Mitre
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,38 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+
+# Hoe.plugin :compiler
+# Hoe.plugin :cucumberfeatures
+# Hoe.plugin :gem_prelude_sucks
+# Hoe.plugin :inline
+# Hoe.plugin :manifest
+# Hoe.plugin :newgem
+# Hoe.plugin :racc
+# Hoe.plugin :rubyforge
+# Hoe.plugin :website
+
+Hoe.spec 'retroactive_module_inclusion' do
+  # HEY! If you fill these out in ~/.hoe_template/Rakefile.erb then
+  # you'll never have to touch them again!
+  # (delete this comment too, of course)
+
+  developer('Adriano Mitre', 'adriano.mitre@gmail.com')
+  
+  self.version = '1.0.0'
+
+  self.readme_file = 'README.rdoc'
+  self.history_file = 'History.rdoc'
+  self.extra_rdoc_files += ['README.rdoc', 'History.rdoc']
+  self.extra_rdoc_files << ['Wishlist.rdoc'] if File.exist? 'Wishlist.rdoc'
+
+  # self.rubyforge_name = 'retroactive_module_inclusionx' # if different than 'retroactive_module_inclusion'
+end
+
+# vim: syntax=ruby
+
+task :tests => [:test] do
+  # aliasing :test with :tests for RVM ('rvm tests')
+end
+

data/lib/retroactive_module_inclusion.rb

@@ -0,0 +1,38 @@
+class Module
+
+  private
+
+  def retroactively_include(mod)
+    raise TypeError, 'wrong argument type #{mod.class} (expected Module)' unless mod.is_a? Module
+
+    # 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
+    #
+    # JRuby (at least up to version 1.5.6) has ObjectSpace disabled by default,
+    # thus it must be enabled manually ([reference][2]).
+    #
+    # [1]: http://eigenclass.org/hiki/The+double+inclusion+problem                      "Dynamic Module Include Problem"
+    # [2]: http://ola-bini.blogspot.com/2007/07/objectspace-to-have-or-not-to-have.html "ObjectSpace: to have or not to have"
+    #
+    prev_jruby_objectspace_state = nil # only for scope reasons
+    if defined?(RUBY_DESCRIPTION) && RUBY_DESCRIPTION =~ /jruby/i
+      require 'jruby'
+      prev_jruby_objectspace_state = JRuby.objectspace
+      JRuby.objectspace = true
+    end
+    ObjectSpace.each_object(Module) do |m|
+      if m <= self # equiv. to "if m.include?(self) || m == self"
+        m.module_eval { include mod }
+      end
+    end
+    if defined?(RUBY_DESCRIPTION) && RUBY_DESCRIPTION =~ /jruby/i
+      JRuby.objectspace = prev_jruby_objectspace_state
+    end
+  end
+  
+end

data/test/test_retroactive_module_inclusion.rb

@@ -0,0 +1,46 @@
+require "test/unit"
+require File.expand_path("../../lib/retroactive_module_inclusion", __FILE__)
+
+module Stats
+  def mean
+    n = 1
+    inject {|s,k| n += 1 ; s + k }.to_f / count
+  end
+end
+
+class TestRetroactiveInclude < Test::Unit::TestCase
+
+  def test_argument_type
+    type_error(Enumerable, Array)
+    type_error(Comparable, Range)
+    type_error(Math, Numeric)
+    type_ok(Array, Enumerable)
+    type_ok(Range, Comparable)
+    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
+  end
+  
+  private
+  
+  def type_error(a, b)
+    assert_raise(TypeError, 'shold raise TypeError for non Module inclusion') do
+      a.module_eval { retroactively_include b }
+    end
+  end
+  
+  def type_ok(a, b)
+    assert_nothing_raised('shold not raise Exception for Module inclusion') do
+      a.module_eval { retroactively_include b }
+    end
+  end
+  
+end
+

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: retroactive_module_inclusion
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Adriano Mitre
+autorequire: 
+bindir: bin
+cert_chain: 
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDPDCCAiSgAwIBAgIBADANBgkqhkiG9w0BAQUFADBEMRYwFAYDVQQDDA1hZHJp
+  YW5vLm1pdHJlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJk/IsZAEZ
+  FgNjb20wHhcNMTEwMTE3MDYxMzM3WhcNMTIwMTE3MDYxMzM3WjBEMRYwFAYDVQQD
+  DA1hZHJpYW5vLm1pdHJlMRUwEwYKCZImiZPyLGQBGRYFZ21haWwxEzARBgoJkiaJ
+  k/IsZAEZFgNjb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC0jjDX
+  O0FdShLgTHub1H7nzZEM/6V26DwJwAn9J8SsLP2tPMO3m0whJF1/cCsy7kofevpo
+  uoJVhLC3W8FxQ30Kue9CpMTBGLeHkGlB9hqIRSuHUPtG49nqCSbtew3/uZb7NTYk
+  i4guvx/AKwVIJkvgzoxp+BVdmslylZW8kf6xvM6TI+lI3b1oISJRnZaJ5wSG1e62
+  A0jJ6rCWowdBhfV2Lc3GvqGWKpFkZiujRWEjf3DuyRJALUjRFt3og5S1LFTC/E8k
+  22l7fNhFtQQWIQ0bvWgr1CVjaC+Mj7Yd/dH1YjFjNSGjeVC70uvwcpa+GAHUTvW+
+  3MJwcABAEx3/k1dVAgMBAAGjOTA3MAkGA1UdEwQCMAAwHQYDVR0OBBYEFCe5ttae
+  SfcWo9+mP1ZzFzPfo2N1MAsGA1UdDwQEAwIEsDANBgkqhkiG9w0BAQUFAAOCAQEA
+  NWDEWS5ZRu2tDbMmAHsNqjxQmdbICp0GiUa4LT5ihdRpaObHp9r+DbcHXmshYiTg
+  rJmflLzpoUvuNYkvgMOXtu7zzLlrm7RsY2r0Z/BbHkxSdX0dpg6s0PcROUnUCdbZ
+  CLiXywPX9ZUvOcF35Cz/HZkWo1zSBz5WtUjSodH9L0ASMboQIIWM8aNd80aV+qYC
+  3UBBz1sni91YXPxf7FQxJtIXlNO04DAAHy9J7M22zWpUFRZOJynnDZWsOx3lifKX
+  1PyL4lke+kXB8DF3QA2RqMPmEZp/FgDqYZy1VT1ROlxyatgDgcFBmrsyjnb9hi9N
+  9u8N6mQNneIVRh6Xfdko/Q==
+  -----END CERTIFICATE-----
+
+date: 2011-01-20 00:00:00 -02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 8
+        - 0
+        version: 2.8.0
+  type: :development
+  version_requirements: *id001
+description: |-
+  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. This
+  behaviour hurts the least surprise principle, specially because if K is a
+  class, then
+    K.class_eval { include M }
+  _does_ make all methods of M available to all classes which had previously
+  inherited it. This inconsistency stems from implementation efficienty concerns
+  and characterize a limitation in Ruby's object model (see {Dynamic Module Include Problem}[http://eigenclass.org/hiki/The+double+inclusion+problem]).
+email: 
+- adriano.mitre@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- README.rdoc
+- History.rdoc
+files: 
+- .autotest
+- History.rdoc
+- Manifest.txt
+- README.rdoc
+- Rakefile
+- lib/retroactive_module_inclusion.rb
+- test/test_retroactive_module_inclusion.rb
+has_rdoc: true
+homepage: http://github.com/adrianomitre/retroactive_module_inclusion
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: retroactive_module_inclusion
+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
+test_files: 
+- test/test_retroactive_module_inclusion.rb

metadata.gz.sig

@@ -0,0 +1,2 @@
+��k?�1w-
+68S�K��;�c��ȫ��rC"yn�Šnu��v�~׿����F�[|{"3���k��:�[��R�Ic�!Vf7���?�و�������̅Mq��/悢vId��c2��u���5O���r�0V��Ĕq�-Yf�d�o‡����`�Yp����?�-�5�F����~�/� 
#��