include_complete 0.1.2 → 0.1.3

data/README.markdown

@@ -1,21 +1,20 @@
 Include Complete
 ----------------
 
-(c) John Mair (banisterfiend) 
+(c) John Mair (banisterfiend) 2010
 MIT license
 
-Removes the shackles from Module#include - use Module#real_include to
-bring in singleton classes from modules. No more ugly ClassMethods and
-included() hook hacks.
+_Removes the shackles from Module#include_
 
-** This is BETA software and has not yet been thoroughly tested, use
-   at own risk **
+Use `Module#include_complete` to bring in singleton classes from
+modules. No more ugly ClassMethods and included() hook hacks.
 
-install the gem: **for testing purposes only**
-`gem install include_complete`
-
-example: 
+* Install the [gem](https://rubygems.org/gems/include_complete): `gem install include_complete`
+* Read the [documentation](http://rdoc.info/github/banister/include_complete/master/file/README.markdown)
+* See the [source code](http://github.com/banister/include_complete)
 
+example: include_complete():
+----------------------------
     module M
         # class method
         def self.hello
@@ -38,3 +37,76 @@ example:
     # invoke instance method
     A.new.bye #=> bye!
 
+Motivation
+-----------
+
+When a class inherits from another class it inherits both the
+instance methods and class methods from its superclass.
+
+Module inclusion does not work this way, only the module's instance methods
+are mixed into the receiver's ancestor chain. This shortcoming
+necessitates the `ClassMethods` included-hook-hack.
+
+In my opinion this behaviour of modules violates the principle of
+least surprise, though I'm aware not everyone agrees with this.
+
+`include_complete` was written to make module inclusion work more like
+class inheritance.
+
+The extend_complete method
+--------------------------
+
+For completeness the `extend_complete` method has also been
+implemented. Like traditional `extend` it mixes the module's instance
+methods into the singleton class of the receiver. But where do the
+singleton methods on the module end up? On the singleton class of the
+singleton class of the receiver ;)
+
+    module M
+      def self.hello
+        :hello
+      end
+    end
+    
+    class C
+      extend_complete M
+    
+      class << self
+        hello #=> :hello
+      end
+    end
+        
+As a result of this, it is unlikely `extend_complete` will be of much
+use to anyone :)
+
+How does it work?
+-----------------
+
+`include_complete` is a C extension that implements a highly modified
+`rb_include_module()` function. Traditional module inclusion uses the
+class pointer of the Included Module to point to the original module;
+`include_complete` instead uses the class pointer to point to a
+wrapped version of the singleton class of the module and stores the original module in a
+hidden `__module__` instance variable. This wrapped singleton class is
+then injected into the ancestor chain of the receiver's singleton
+class.
+
+Limitations
+------------
+
+`include_complete` uses a recursive function to generate the
+Included Modules, and the base case of this recursion is reached when the singleton class of Module is
+encountered. In the case where the module has a meta-meta class the recursive
+function will not terminate and the program will hang.
+
+It is highly unlikely and, as far as I know, next to useless for
+a module to possess any higher order metaclasses so this limitation is
+unlikely to be a problem in practice.
+
+Contact
+-------
+
+Problems or questions contact me at [github](http://github.com/banister)
+
+
+

data/lib/include_complete.rb

@@ -58,5 +58,6 @@ class Object
   #   o.singleton_class.hello #=> "hello"
   def extend_complete(*mods)
     class << self; self; end.send(:include_complete, *mods)
+    self
   end
 end

data/lib/include_complete/version.rb

@@ -1,3 +1,3 @@
 module IncludeComplete
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/test/stress_test.rb

@@ -1,14 +1,15 @@
-require '../lib/real_include'
+direc = File.dirname(__FILE__)
+require "#{direc}/../lib/include_complete"
 
 5000.times {
   m = Module.new
   n = Module.new
   k = Module.new
-  n.real_include m
-  k.real_include n
+  n.include_complete m
+  k.include_complete n
 
   c = Class.new
-  c.real_include k
+  c.include_complete k
 }
 
 "stress test passed!".display

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: include_complete
 version: !ruby/object:Gem::Version 
+  hash: 29
   prerelease: false
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -53,6 +54,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -61,6 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"