namebox 0.0.4 → 0.1.8

data/lib/namebox.rb

@@ -7,6 +7,12 @@
 #
 # This software is released "AS IS", without any warranty.
 # The author is not responsible for the consequences of use of this software.
+#
+# Version 0.1.8 - This is the last version compatible with Ruby 1.8.7.
+# It's slow, memory-consuming and it has some issues about loosing 'self'
+# when in class methods changed by extending modules in subclasses
+# (self will be the class instead of subclass when namebox is closed).
+# Next versions will be only 1.9+-compatible.
 
 class Namebox
 
@@ -15,9 +21,12 @@ class Namebox
     map { |c| Object.const_get(c) }.
     select { |m| m.is_a? Module }.uniq
 
+  ### FOR RUBY 1.8.7 USE ###
+  CLASS_EIGENCLASS = class << Class; self; end
+
   class << self
 
-    # wrapper to create a namebox only to protect modules when requiring
+    # Wrapper to create a namebox only to protect modules when requiring.
     def require resource, *modules_to_protect
 
       new(*modules_to_protect) do
@@ -29,16 +38,24 @@ class Namebox
 
     end
 
-    # set and get the default modules to protect, for the caller file.
-    def default_modules
-      (@default_modules ||= {})[caller_info[:file]] || []
-    end
-
+    # Set the default modules to protect (file-wide, for the caller file).
+    # Each file you want to use #default_modules, you must define them again.
+    # This is to avoid conflicts when using other people libraries, which
+    # may want to protect different modules by default. See #default_modules
+    #
     def default_modules= modules_to_protect
       (@default_modules ||= {})[caller_info[:file]] = [modules_to_protect].flatten
     end
 
-    # Get the caller info in a structured way (hash)
+    # Array with default modules to protect. You may want redefine this,
+    # protecting Namebox itself inside another namebox, and assign it to
+    # a constant, which can be available thru other files in the project.
+    #
+    def default_modules
+      (@default_modules ||= {})[caller_info[:file]] || []
+    end
+
+    # Get the caller info in a structured way (hash).
     def caller_info
 
       # search for last reference to this file in caller and take the next one
@@ -50,105 +67,33 @@ class Namebox
       m = c.match(/^(.*?):(\d+)(:in `(.*)')?$/)
       raise "Unexpected caller syntax in \"#{c}\"" unless m
 
-      # label it
+      # label them
       {:file => m[1], :line => m[2].to_i, :method => m[4]}
 
     end
 
-    ###################################################
-    # INSTANCE METHODS HELPERS
-    ###################################################
-
-    # Get the super methods from klass' ancestors list.
-    # +is_instance+: boolean for instance or class methods
-    # +limit_ancestor+: the last ancestor to check for methods
-    # +default_method+: the method to return case not found
-    # +first+: returns the first method found; else returns an array
-    #
-    def super_methods(name, klass, is_instance, limit_ancestor, default_method,
-                      first = false, &validator)
-
-      ancestors = is_instance ? klass.ancestors : class_ancestors(klass)
-
-      sm = []
-      limit_index = ancestors.index(limit_ancestor) || ancestors.length - 1
-
-      # skip first ancestor (0) - the class itself
-      #
-      for i in 1..limit_index
-        super_ancestor = ancestors[i]
-        begin
-          m = super_ancestor.instance_method(name)
-        rescue NameError
-          m = nil
-        end
-
-        # only owners (and the last) are interesting
-        next unless m && m.owner == super_ancestor || i == limit_index
-
-        # check if it matches the requisites
-        next unless validator.call(m)
-
-        return m if first
-
-        sm << m
-
-      end
-
-      # return found methods
-      return sm unless sm.empty?
-
-      # not found
-      first ? default_method : [default_method]
-    end
-
-    ###################################################
-    # CLASS METHODS HELPERS
-    ###################################################
-
-    # build ancestors list for class methods lookup
-    def class_ancestors(c)
+    # Raises NoMethodError, limiting the length of +obj.inspect+.
+    def no_method_error(obj, m_name)
 
-      # only classes have superclass
-      return c.ancestors if c.instance_of? Module
+      # if inspect is too big, shorten it
+      obj_name = obj.inspect.to_s
+      obj_name = obj_name[0..45] + '...' + obj_name[-1] if obj_name.length > 50
 
-      list = []
-      eigenclass = class << c; self; end
-      mod_class = eigenclass.included_modules
+      msg = "Undefined method `#{m_name}' for #{obj_name}:#{obj.class}"
 
-      while c
-
-        s = c.superclass
-        eigensuper = class << s; self; end
-
-        # if there's no superclass, consider Kernel as included module;
-        # so it won't be added now, but later, in the correct order.
-        mod_super = s ? eigensuper.included_modules : [Kernel]
-
-        # add eigenclass and its included modules
-        # (discarding the ones inherited from superclasses)
-        list << eigenclass
-        list += mod_class - mod_super
-
-        # rotate values
-        c, eigenclass, mod_class = s, eigensuper, mod_super
-
-      end
-
-      # finally adds Class's ancestors (including Kernel)
-      list += Class.ancestors
+      raise NoMethodError.new(msg)
     end
 
   end
 
   # +modules_to_protect+ must be the classes themselves, e.g., String, Symbol,
-  # not their names ("String" or :Symbol).
-  # Special names are:
-  # :all => protect all known modules and submodules. It's safer but slooow.
-  # :core => protect the known top-level modules.
-  # :default => protect the modules defined in Namebox.default_modules.
-  # Obs.: :core and :default can be used together and/or with other classes,
-  # but :all must be the only parameter if it is used.
+  # not their names ("String" or :Symbol).<br>
+  # Special names are:<br>
+  # +:all+ => protect all known modules and submodules. It's safer but slower.<br>
+  # +:core+ => protect the known top-level modules.<br>
+  # +:default+ => protect the modules defined in +Namebox.default_modules+.<br>
+  # Obs.: +:core+ and +:default+ can be used together and/or with other classes,
+  # but +:all+ must be the only parameter if it is used.
   #
   def initialize *modules_to_protect, &blk
 
@@ -156,6 +101,9 @@ class Namebox
     @enabled_files = []
     @protected_methods = []
 
+    # this_nb will be useful in a closure, where self will be different
+    this_nb = self
+
     # by default, get Namebox.default_modules
     modules_to_protect = Namebox.default_modules if modules_to_protect.empty?
 
@@ -173,7 +121,8 @@ class Namebox
     else
 
       # take off the symbols
-      @modules = modules_to_protect.select { |m| m.is_a? Module }
+      modules = modules_to_protect.select { |m| m.is_a? Module }
+      @modules = modules
 
       # include default modules if wanted
       @modules += Namebox.default_modules if modules_to_protect.include? :default
@@ -184,6 +133,11 @@ class Namebox
       # avoid redundancy
       @modules.uniq!
 
+      # include all ancestors for modules and eigenclasses of classes
+      modules.each do |m|
+        @modules |= m.ancestors
+        @modules |= class << m; self; end.ancestors if m.is_a? Class
+      end
     end
 
     # modules must be given or Namebox.default_modules must be set
@@ -193,7 +147,22 @@ class Namebox
             Namebox.caller_info[:file])
     end
 
-    # save preexisting methods
+    # select classes to protect against included modules
+    @classes = @modules.select { |m| m.is_a? Class }
+
+    # hash for fast search for instances of eigenclasses
+    @eigen_instances = Hash[*@classes.map { |c| [class << c; self; end, c] }.flatten]
+
+    # include eigenclasses in @classes
+    @classes |= @eigen_instances.keys
+
+    # eigen_instances will be useful as bound local variable in a closure
+    # for another object; so we can't use instance var @eigen_instances
+    #
+    eigen_instances = @eigen_instances
+
+    # save preexisting methods and included modules
+    inc_mods_before = get_included_modules
     methods_before = get_methods
 
     # ###############################################################
@@ -203,155 +172,174 @@ class Namebox
     #
     # ###############################################################
 
-    # get methods after changes
+    # get data after changes
+    inc_mods_after = get_included_modules
     methods_after = get_methods
 
-    # compare with preexisting data to discover affected methods
-    unless methods_after == methods_before
+    # compare with preexisting data to discover affected methods and modules
 
-      # thru closure, this namebox will be useful inside redefined methods
-      this_nb = self
-      methods_after.each do |fullname, info|
+    # compare included modules (before vs after)
+    unless inc_mods_after == inc_mods_before
 
-        # get old method
-        info_old = methods_before[fullname] || {}
-        new_m = info[:method]
-        old_m = info_old[:method]
+      inc_mods_after.each do |klass, inc_mods|
 
-        # don't touch unmodified methods
-        next if new_m == old_m
+        old_modules = inc_mods_before[klass]
+        new_modules = inc_mods - old_modules
 
-        # method was modified! take some info
-        name = info[:name]
-        klass = info[:class]
-        is_instance = info[:is_instance]
-        old_owner = old_m && old_m.owner
+        # there's no new included module for this class
+        next if new_modules.empty?
 
-        # instance and class methods are managed differently
-        if is_instance
+        new_modules.each do |new_module|
 
-          ##########################################################
+          # Create a protector module to protect the changed methods.
+          # This protector module is specifc to new_module and klass.
           #
-          # PROTECT INSTANCE METHODS
+          protector = Module.new
+
+          # Create a module to enable a tunnel to bypass the new_module
+          # in super method lookup when namebox is closed to new_module.
           #
-          ##########################################################
+          super_tunnel = Module.new
 
-          # new methods to skip
-          new_methods = Namebox.super_methods(name, klass, is_instance,
-                                              old_owner, new_m) do |sm|
-            sm != old_m
+          # Give name to protector module; useful when using Method#owner.
+          #
+          class << protector; self; end.send(:define_method, :to_s) do
+            "Protector:#{new_module}/#{klass}"
           end
 
-          # redefine the method, which will check namebox visibility dinamically
-          klass.send :define_method, name do |*args, &blk|
+          new_module.instance_methods.each do |method_name|
 
-            # check namebox visibility
-            if this_nb.open?
+            new_method = new_module.instance_method(method_name)
 
-              # call the protected (by namebox) method
-              # instance methods are unbound; must bind to self
-              new_m.bind(self).call(*args, &blk)
+            protector.send :define_method, method_name do |*args, &blk|
+              if this_nb.open?
+                new_method.bind(self).call(*args, &blk)
+              else
+                begin
+                  super_tunnel.instance_method(method_name).bind(self).call(*args, &blk)
+                rescue NoMethodError
 
-            else
+                  # Can throw error in two cases:
+                  # 1. There's really no super method (Ruby >= 1.9)
+                  # 2. 1.8.7 does not find super when in a module after binding.
+                  #
+                  raise if RUBY_VERSION >= '1.9.0'
 
-              # search a different method to call
-              # must be dynamic because it can change anytime
-              # (someone can attach a new definition to some ancestor)
+                  # future method
+                  m = nil
 
-              m = Namebox.super_methods(name, klass, is_instance,
-                                        old_owner, old_m, true) do |sm|
-                !new_methods.include?(sm)
-              end
+                  # search the method in old modules
+                  old_modules.each do |old_module|
+                    begin
+                      m = old_module.instance_method(method_name).bind(self)
+                      break
+                    rescue NameError
+                      # try next
+                    end
+                  end
 
-              unless m
+                  unless m
 
-                # didn't find a method; raise NoMethodError
+                    # last try: superklass
+                    begin
+                      superklass = klass.superclass
 
-                # if inspect is too big, shorten it
-                obj = self.inspect.to_s
-                obj = obj[0..45] + '...' + obj[-1] if obj.length > 50
+                      # superklass exist?
+                      raise NameError unless superklass
 
-                raise NoMethodError.new("Undefined instance method `#{name}' " +
-                                        "for #{obj}:#{self.class}")
-              end
+                      # Ruby 1.8.7 get wrong superclass for eigenclasses
+                      if superklass == CLASS_EIGENCLASS
 
-              # play as self
-              m.bind(self).call(*args, &blk)
-            end
-          end
+                        # Get a bound method for superclass (although self
+                        # won't be the same: superclass instead of klass).
+                        # Can raise NameError if method does not exist.
+                        #
+                        m = eigen_instances[klass].superclass.method(method_name)
 
-        else
+                      else
 
-          ##########################################################
-          #
-          # PROTECT CLASS METHODS
-          #
-          ##########################################################
+                        # Try to get method; raises NameError if it doesn't exist.
+                        m = superklass.instance_method(method_name).bind(self)
 
-          # new methods to skip
-          new_methods = Namebox.super_methods(name, klass, is_instance,
-                                              old_owner, new_m) do |sm|
-            sm != old_m
-          end
+                      end
 
-          # redefine the method thru eigenclass
-          class << klass; self; end.send :define_method, name do |*args, &blk|
+                    rescue NameError
+                      Namebox.no_method_error(self, method_name)
+                    end
+                  end
 
-            # check namebox visibility
-            if this_nb.open?
+                  m.call(*args, &blk)
+                end
+              end
+            end
 
-              # call the protected (by namebox) method
-              # new_m is already bound to self; just call it
-              new_m.call(*args, &blk)
+            super_tunnel.send :define_method, method_name do |*args, &blk|
+              super(*args, &blk)
+            end
 
-            else
+          end
 
-              # search a different method to call
-              # must be dynamic because it can change anytime
-              # (someone can attach a new definition to some ancestor)
+          # include super_tunnel in new_module
+          new_module.send :include, super_tunnel
 
-              m = Namebox.super_methods(name, klass, is_instance,
-                                        old_owner, old_m, true) do |sm|
-                !new_methods.include?(sm)
-              end
+          # reincludes the new_module with super_tunnel to allow bind(self)
+          klass.send :include, new_module
 
-              unless m
+          # finally, include the protector in the class
+          klass.send :include, protector
 
-                # didn't find a method; raise NoMethodError
+        end
+      end
+    end
 
-                # if inspect is too big, shorten it
-                obj = self.inspect.to_s
-                obj = obj[0..45] + '...' + obj[-1] if obj.length > 50
+    # Compare changed methods (before vs after)
+    unless methods_after == methods_before
 
-                raise NoMethodError.new("Undefined class method `#{name}' " +
-                                        "for #{obj}:#{self.class}")
-              end
+      methods_after.each do |fullname, info|
 
-              begin
+        # get old method
+        info_old = methods_before[fullname] || {}
+        new_m = info[:method]
+        old_m = info_old[:method]
 
-                # bind to self (raises TypeError in 1.8.7)
-                m = m.bind(self) if m.instance_of? UnboundMethod
+        # don't touch unmodified methods
+        next if new_m == old_m
 
-              rescue TypeError
+        # method was modified! take some info
+        m_name = info[:name]
+        klass = info[:class]
+        new_bound_m = info[:bound]
+        old_bound_m = info_old[:bound]
 
-                # Ruby 1.8.7 does not bind singleton methods to descendant class;
-                # try to use a pre-bound method
-                m = ObjectSpace.each_object(m.owner).to_a.last.method(name)
+        # redefine the method, which will check namebox visibility dinamically
+        klass.send :define_method, m_name do |*args, &blk|
 
-              end
+          # check namebox visibility
+          if this_nb.open?
 
-              # run!
-              m.call(*args, &blk)
+            # Call the new method. Instance methods are unbound; bind to self.
+            m = (new_bound_m || new_m.bind(self)).call(*args, &blk)
+
+          else
+
+            # old method or super
+            if old_m
+              (old_bound_m || old_m.bind(self)).call(*args, &blk)
+            else
+              begin
+                super(*args, &blk)
+              rescue NoMethodError
+                Namebox.no_method_error(self, m_name)
+              end
             end
-          end
 
+          end
         end
       end
     end
   end
 
-
-  # open a namebox region for visibility in the caller file at caller line
+  # Open a namebox region for visibility in the caller file at caller line.
   def open
     info = ranges_info
 
@@ -365,7 +353,7 @@ class Namebox
   end
 
 
-  # close the namebox region in the caller file
+  # Close the namebox visible region in the caller file.
   def close
     info = ranges_info
 
@@ -388,7 +376,7 @@ class Namebox
     info[:ranges] << r unless info[:ranges].include? r
   end
 
-  # check namebox' visibility
+  # Check namebox visibility (openness).
   def open?
 
     # check file before checking ranges
@@ -414,15 +402,14 @@ class Namebox
     false
   end
 
-
-  # open namebox in entire caller file (valid only after called!)
+  # Open namebox in entire caller file (valid only after called!).
   def file_wide
     @enabled_files << Namebox.caller_info[:file]
   end
 
   private
 
-  # Get line ranges info for the caller file
+  # Get line ranges info for the caller file.
   def ranges_info ci = Namebox.caller_info
 
     ranges = enabled_ranges[ci[:file]] ||= []
@@ -435,30 +422,61 @@ class Namebox
     ci
   end
 
-  # Stores enabled line ranges of caller files for this module
+  # Stores enabled line ranges of caller files for this module.
   def enabled_ranges
     @enabled_ranges ||= {}
   end
 
-  # get methods in use thru modules to protect
+  # Get methods in use on modules to protect.
   def get_methods
     gm = {}
 
     @modules.each do |c|
 
-      c.instance_methods.each do |m|
+      # get eigenclass
+      ec = class << c; self; end
+
+      c.instance_methods(false).each do |m|
         fullname = "#{c}##{m}"
-        gm[fullname] = {:class => c, :is_instance => true, :name => m,
-                        :method => c.instance_method(m) }
+        gm[fullname] = {:class => c, :name => m, :method => c.instance_method(m) }
       end
 
-      c.methods.each do |m|
+      c.methods(false).each do |m|
         fullname = "#{c}.#{m}"
-        gm[fullname] = {:class => c, :name => m, :method => c.method(m) }
+        gm[fullname] = {:class => ec, :name => m, :method => ec.instance_method(m),
+                        :bound => c.method(m) }
       end
 
     end
 
     gm
   end
+
+  # Get modules included by the classes being protected.
+  def get_included_modules
+    inc_mods = {}
+
+    @classes.each do |c|
+      super_c = get_superclass(c)
+
+      # superclass included modules must be [] even when superclass is nil
+      super_inc_mods = super_c && super_c.included_modules || []
+
+      # get modules included by the class only, not by superclasses.
+      inc_mods[c] = c.included_modules - super_inc_mods
+    end
+
+    inc_mods
+  end
+
+  # Get superclass of a class; correct values for eigenclasses in 1.8.7.
+  def get_superclass(c)
+    s = c.superclass
+    if s == CLASS_EIGENCLASS
+      # Ruby 1.8.7 limitation
+      s = class << @eigen_instances[c].superclass; self; end
+    end
+    s
+  end
+
 end

metadata

@@ -1,48 +1,70 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: namebox
-version: !ruby/object:Gem::Version
-  version: 0.0.4
+version: !ruby/object:Gem::Version 
+  hash: 11
   prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 8
+  version: 0.1.8
 platform: ruby
-authors:
+authors: 
 - Sony Santos
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-15 00:00:00.000000000 Z
+
+date: 2013-01-20 00:00:00 Z
 dependencies: []
-description: ! 'Please, note: this version is very unstable and it''s under tests.
-  Came back soon to check new versions with bug fixes.'
+
+description: |-
+  Create namespace boxes to protect the core classes' methods from changes, like refinements.
+  
+  Note: this is the last version compatible with Ruby 1.8.7. It's slow, memory-consuming and it has some issues about loosing 'self' when in class methods changed by extending modules in subclasses (self will be the class instead of subclass when namebox is closed). Next versions will be only 1.9+-compatible.
 email: sony.fermino@gmail.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - lib/namebox.rb
 homepage: http://rubychallenger.blogspot.com.br/2013/01/namebox.html
-licenses:
+licenses: 
 - Public Domain
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
       version: 1.8.7
-required_rubygems_version: !ruby/object:Gem::Requirement
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
-summary: Create namespace boxes to protect the core classes' methods from changes,
-  like refinements
+summary: Create namespace boxes to protect the core classes' methods from changes, like refinements.
 test_files: []
+