overridable 0.3.0 → 0.3.1

data/README.markdown

@@ -4,36 +4,36 @@ Overridable is a pure ruby library which helps you to make your methods which ar
 
 ## Why?
 
-We all know that it's impossible for modules to override methods that are defined in classes when they are included. For example:
+Some people are overusing `alias_method_chain` in their codes like what wycats mentioned in [his post][post]. One of the reasons that people like using `alias_method_chain` is because it's impossible for modules to override methods that are defined in classes when they are included. For example:
     class Thing
       def foo
         'Thing.foo'
       end
     end
     
-    module Redef
+    module Extension
       def foo
-        'Redef.foo'
+        'Extension.foo'
       end
     end
     
-    Thing.send :include, Redef
-    Thing.new.foo #=> Thing.foo # not Redef.foo
+    Thing.send :include, Extension
+    Thing.new.foo #=> Thing.foo # not Extension.foo
 
-Usually, in order to achieve that goal, we will write the Redef module like this:
-    module Redef
+In order to achieve that goal, some will write the Extension module like this:
+    module Extension
       def foo_with_redef
-        'Redef.foo'
+        'Extension.foo'
       end
       # you can also do this by: alias_method_chain :foo, :redef, if you use ActiveSupport.
       alias foo_without_redef foo
       alias foo foo_with_redef
     end
     
-    Thing.send :include, Redef
-    Thing.new.foo #=> Redef.foo
+    Thing.send :include, Extension
+    Thing.new.foo #=> Extension.foo
 
-So it will likely become a with/without hell in your code ( you can find dozens of such methods in Rails' code ). And *overridable* is a library that provides a neat mean to resolve this problem.
+But according to the [post][post], this is a bad practice. And *overridable* is a gem that provides a neat mean to resolve this problem.
 
 ## How?
 
@@ -41,17 +41,17 @@ There are two ways to do this with *overridable*: in class or in module.
 
 ### In class
 
-Remember Thing and Redef in our first example? Let's make some changes:
+Remember Thing and Extension in our first example? Let's make some changes:
     require 'overridable'
     
     Thing.class_eval {
       include Overridable
       overrides :foo
       
-      include Redef
+      include Extension
     }
     
-    Thing.new.foo #=> Redef.foo
+    Thing.new.foo #=> Extension.foo
 That's it! You can specify which methods can be overrided by `overrides` method. One more example based on the previous one:
     Thing.class_eval {
       def bar; 'Thing.bar' end
@@ -61,26 +61,26 @@ That's it! You can specify which methods can be overrided by `overrides` method.
       overrides :bar, :baz
     }
     
-    Redef.module_eval {
-      def bar; 'Redef.bar' end
-      def baz; 'Redef baz' end
-      def id;  'Redef'     end
+    Extension.module_eval {
+      def bar; 'Extension.bar' end
+      def baz; 'Extension baz' end
+      def id;  'Extension'     end
     }
     
     thing = Thing.new
-    thing.bar #=> 'Redef.bar'
-    thing.baz #=> 'Redef.baz'
+    thing.bar #=> 'Extension.bar'
+    thing.baz #=> 'Extension.baz'
     thing.id  #=> 'Thing'
-Of course it's not the end of our story ;) How could I call this *override* if we cannot use `super`? Continue our example:
-    Redef.module_eval {
+Of course it's not the end of our story ;) How could I call this *override* if we cannot use `super`? Go on with our example:
+    Extension.module_eval {
       def bar
         parent = super
-        me = 'Redef.bar'
+        me = 'Extension.bar'
         "I'm #{me} and I overrided #{parent}"
       end
     }
 
-    Thing.new.bar => I'm Redef.bar and I overrided Thing.bar
+    Thing.new.bar => I'm Extension.bar and I overrided Thing.bar
 
 ### In module
 
@@ -92,7 +92,7 @@ If you have many methods in your module and find that it's too annoying to use `
       def method_n;   ... end
     end
     
-    module Redef
+    module Extension
       include Overridable::ModuleMixin
     
       def method_one; ... end
@@ -101,7 +101,19 @@ If you have many methods in your module and find that it's too annoying to use `
       def method_n;   ... end
     end
 
-    Thing.send :include, Redef #=> method_one, method_two, ..., method_n are all overrided.
+    Thing.send :include, Extension #=> method_one, method_two, ..., method_n are all overrided.
+
+Since version 0.3.1, you can use `overrides` in your module to specify which method should be overrided and which should not. Let's rewrite the Extension module above:
+    module Extension
+      include Overridable::ModuleMixin
+      overrides :only => [:method_one, :method_two]
+
+      # define methods here...
+    end
+    
+    Thing.send :include, Extension #=> only method_one and method_two will be overrided.
+
+You can also use `overrides :except => [:method_one, :method_two]` to tell the module not to override method_one and method_two in the classes which include it.
 
 ## Install
 
@@ -145,3 +157,5 @@ These features **only** will be added when they are asked for.
 ## Copyright
 
 Copyright (c) 2009 梁智敏. See LICENSE for details.
+
+[post]: http://yehudakatz.com/2009/03/06/alias_method_chain-in-models/

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.3.1

data/lib/overridable.rb

@@ -90,13 +90,45 @@ module Overridable
       def append_features mod #:nodoc:
         # these must be done in `append_features`, not `included`
         mod.send :include, Overridable
-        mod.overrides *(
-          public_instance_methods +
-          protected_instance_methods +
-          private_instance_methods
-        )
+
+        methods =
+          if @override_options && !@override_options[:only].empty?
+              @override_options[:only]
+          else
+            all_methods = 
+              public_instance_methods +
+              protected_instance_methods +
+              private_instance_methods
+
+            if @override_options && !@override_options[:except].empty?
+              all_methods - @override_options[:except]
+            else
+              all_methods
+            end
+          end
+
+        mod.overrides *methods
         super
       end
+
+      # Whitelist and blacklist for to-be-overrided methods.
+      # If this method with the same options is called multiple times within the same module,
+      # only the last call will work.
+      # @param [Hash] options the options describe methods are to be or not to be overrided.
+      # @option options [Symbol, Array<Symbol>] :only only methods specified in this option will be overrided.
+      # @option options [Symbol, Array<Symbol>] :except methods specified in this option will not be overrided.
+      # @example
+      #   overrides :except => [:foo, :bar]
+      #   overrides :except => :baz
+      #   overrides :only => [:foo, :bar]
+      def overrides options = {}
+        raise ArgumentError, "Only :only and :except options are accepted." unless
+          options.keys.all? { |k| [:only, :except].include? k }
+        @override_options ||= {:only => [], :except => []}
+        @override_options[:only] = [options[:only]].flatten.compact if options[:only]
+        @override_options[:except] = [options[:except]].flatten.compact if options[:except]
+        @override_options[:only] = @override_options[:only] - @override_options[:except]
+      end
     end
   end
 
@@ -137,9 +169,9 @@ module Overridable
           end
         }
         $VERBOSE = old_verbose
-
-        nil
       end
+
+      nil
     end
   end
 

data/test/modulemixin_test.rb

@@ -9,9 +9,15 @@ context "A module which includes Overridable::ModuleMixin has some methods defin
         'SomeModule.foo'
       end
 
+      protected
       def bar a
         super + 'SomeModule.bar'
       end
+
+      private
+      def baz
+        super + 'SomeModule.baz'
+      end
     end
 
     SomeModule
@@ -24,10 +30,13 @@ context "A module which includes Overridable::ModuleMixin has some methods defin
           'SomeClass.foo'
         end
 
-        private
         def bar a
           'SomeClass.bar'
         end
+
+        def baz
+          'SomeClass.baz'
+        end
       end
 
       SomeClass
@@ -39,10 +48,80 @@ context "A module which includes Overridable::ModuleMixin has some methods defin
       asserts("foo should be overrided.") {
         topic.new.foo
       }.equals('SomeModule.foo')
+
+      asserts("bar should be overrided.") {
+        topic.new.send :bar, :whatever
+      }.equals('SomeClass.bar' + 'SomeModule.bar')
+
+      asserts("baz should be overrided.") {
+        topic.new.send :baz
+      }.equals('SomeClass.baz' + 'SomeModule.baz')
+    end
+
+    context "We specify which methods can be overrided." do
+      setup {
+        SomeModule.module_eval {
+          overrides :only  => [:foo, :bar]
+        }
+        topic.send :include, SomeModule
+        topic
+      }
+
+      asserts("foo should be overrided.") {
+        topic.new.foo
+      }.equals('SomeModule.foo')
+
+      asserts("bar should be overrided.") {
+        topic.new.send :bar, :whatever
+      }.equals('SomeClass.bar' + 'SomeModule.bar')
+
+      asserts("baz should not be overrided.") {
+        topic.new.baz
+      }.equals('SomeClass.baz')
+    end
+
+    context "We specify which methods cannot be overrided." do
+      setup {
+        SomeModule.module_eval {
+          overrides :except  => :baz
+        }
+        topic.send :include, SomeModule
+        topic
+      }
+
+      asserts("foo should be overrided.") {
+        topic.new.foo
+      }.equals('SomeModule.foo')
+
+      asserts("bar should be overrided.") {
+        topic.new.send :bar, :whatever
+      }.equals('SomeClass.bar' + 'SomeModule.bar')
+
+      asserts("baz should not be overrided.") {
+        topic.new.baz
+      }.equals('SomeClass.baz')
+    end
+
+    context "We specify both the whitelist and blacklist of to-be-overrided methods." do
+      setup {
+        SomeModule.module_eval {
+          overrides :only => [:foo, :bar, :baz], :except  => :baz
+        }
+        topic.send :include, SomeModule
+        topic
+      }
+
+      asserts("foo should be overrided.") {
+        topic.new.foo
+      }.equals('SomeModule.foo')
+
       asserts("bar should be overrided.") {
-        #topic.new.send :bar, :whatever
-        topic.new.bar :whatever
+        topic.new.send :bar, :whatever
       }.equals('SomeClass.bar' + 'SomeModule.bar')
+
+      asserts("baz should not be overrided.") {
+        topic.new.baz
+      }.equals('SomeClass.baz')
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: overridable
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - "\xE6\xA2\x81\xE6\x99\xBA\xE6\x95\x8F(Gimi Liang)"
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-24 00:00:00 +08:00
+date: 2009-11-25 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency