retroactive_module_inclusion

= 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 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 inject(&:+) / count.to_f 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 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 inject(&:+) / count.to_f end end

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):
  • 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.retroactively_include AnotherModule

or, as in prior versions,

SomeModule.module_eval { retroactively_include AnotherModule }

or equivalently

SomeModule.send :retroactively_include, AnotherModule

and also

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.