use 1.0.0 → 1.1.0

data/CHANGES

@@ -1,2 +1,11 @@
-== 1-Aug-2005
-* Initial release
+== 1.1.0 - 20-Jan-2006
+* Using 'use' with no arguments is now the same as if you used 'include',
+  i.e. all methods are mixed in.  Previously, this would not mixin any methods.
+* Added finer control of mixed in methods by allowing the use of three keyword
+  arguments - 'include', 'exclude' and 'alias'.  See the documentation for
+  more details.
+* Added more inline documentation.
+* More tests and examples.
+
+== 1.0.0 - 1-Aug-2005
+* Initial release

data/MANIFEST

@@ -4,6 +4,8 @@ README
 install.rb
 use.gemspec
 
+examples/example_use.rb
+
 lib/use.rb
 
 test/tc_use.rb

data/README

@@ -1,54 +1,76 @@
-== Description
-	The 'use' package allows you to selectively mixin methods from a given
-	module.
-
-== Prerequisites
-	Ruby 1.8.0 or later
-	
-== Installation
-=== Standard
-	ruby test/tc_use.rb (optional)
-	ruby install.rb
-	
-=== Gem install
-	ruby test/tc_use.rb (optional)
-	ruby use.gemspec
-	gem install use.gem
-
-== Synopsis
-	module Foo
-		def bar
-			"hello"
-		end
-		def baz
-			"world"
-		end
-	end
-
-	class Zap
-		use Foo, :bar
-	end
-
-	z = Zap.new
-
-	z.bar # "hello"
-	z.baz # NoMethodError
-
-== Acknowledgements
-	Thanks go to Ara Howard for providing the solution.
-
-== Known Bugs
-   None that I'm aware of.  If you find any, please log them on the project
-   page at http://www.rubyforge.org/projects/shards.
-
-== License
-   Ruby's
-
-== Copyright
-   (C) 2005, Daniel J. Berger
-   All Rights Reserved
-
-== Author
-   Daniel J. Berger
-   djberg96@yahoo.com
-   IRC nickname: imperator/rubyhacker1
+== Description
+   The 'use' package allows you to selectively mixin methods from a given
+   module.
+
+== Prerequisites
+   Ruby 1.8.0 or later
+	
+== Installation
+=== Standard
+   ruby test/tc_use.rb (optional)
+   ruby install.rb
+	
+=== Gem install
+   ruby test/tc_use.rb (optional)
+   ruby use.gemspec
+   gem install use.gem
+
+== Synopsis
+   module Foo
+      def bar
+         "hello"
+      end
+      def baz
+         "world"
+      end
+   end
+
+   module Test
+      def bar
+         "goodbye"
+      end
+      def blah
+         "new york"
+      end
+   end
+
+   class Zap
+      use Foo, :bar
+      use Test, :blah
+   end
+
+   z = Zap.new
+
+   z.bar  # "hello"
+   z.baz  # NoMethodError
+   z.blah # "new york"
+   
+   # Using the new keywords
+   class MyKlass
+      use Foo :alias => {:bar, :test}
+   end
+   
+   m = MyKlass.new
+   m.test # "hello"
+   m.bar  # NoMethodError
+
+== Acknowledgements
+   Thanks go to Ara Howard for providing the original solution and to
+   Mauricio Fernandez, who's blog I plagiarized to get the spoonful style
+   mixins.
+
+== Known Bugs
+   None that I'm aware of.  If you find any, please log them on the project
+   page at http://www.rubyforge.org/projects/shards.
+
+== License
+   Ruby's
+
+== Copyright
+   (C) 2005-2006, Daniel J. Berger
+   All Rights Reserved
+
+== Author
+   Daniel J. Berger
+   djberg96 at gmail dot com
+   IRC nickname: imperator/mok (freenode)

data/lib/use.rb

@@ -1,18 +1,122 @@
-class Module
-   # VERSION 1.0.0
-
-   # use(module, methods)
-   #
-   # The 'use' directive allows you to selectively mixin +methods+ from the
-   # given +module+.  The +methods+ may be either strings or symbols.
-   def use(mod, *methods)
-      m = Module.new
-      m.module_eval do
-         include mod
-         all_methods = mod.instance_methods
-         unn_methods = all_methods - methods.map{ |method| method.to_s }
-         unn_methods.each{ |method| undef_method(method) }  
-      end
-      module_eval{ include m }
-   end
-end
+class Module
+   # VERSION = "1.1.0"
+
+   # :call-seq:
+   # use module, methods
+   # # or
+   # use module, option => value, ...
+   #
+   # The 'use' directive allows you to selectively mixin +methods+ from the
+   # given +module+.  The +methods+ may be either strings or symbols.  If
+   # no methods are provided then 'use' is effectively the same thing as
+   # 'include', i.e. all methods are mixed in.
+   #
+   # If a Hash is provided, there are three keywords available to you:
+   #
+   # * 'include'
+   #   This option lets you specify one or more methods to explicitly include.
+   #   If you wish to include more than one method, use an array as the value.
+   #
+   # * 'exclude'
+   #   This option lets you specify one or more methods to explicitly exclude.
+   #   If you wish to exclude more than one method, use an array as the value.
+   #
+   # * 'alias'
+   #   This option lets you include a method, but as a different method name.
+   #   Use a hash as the value to +alias+, e.g. :alias => {:old, :new, ... }.
+   #   Using this option doubles as an explicit include, so you do not need
+   #   to both include and alias in the same statement.
+   #
+   #   Note that the original method name is NOT included if aliased this way.
+   #
+   #   Also note that you cannot include and exclude in the same statement,
+   #   or an ArgumentError is raised.  You can, however, exclude and alias.
+   #
+   def use(mod, *methods)
+      valid    = %w/include exclude alias/
+      included = []
+      excluded = []
+      aliased  = []
+
+      m = Module.new
+
+      # If the first argument is a Hash, verify the keywords and push values
+      # onto the appropriate array for later processing.
+      #
+      if methods.first.kind_of?(Hash)
+         methods = methods.first
+         methods.each{ |key, val|
+            unless valid.include?(key.to_s.downcase)
+               raise ArgumentError, "invalid key: #{key}"
+            end
+
+            if key.to_s == "include"
+               if val.respond_to?(:each)
+                  val.each{ |arg| included.push(arg.to_sym) } 
+               else
+                  included.push(val.to_sym)
+               end
+            end
+
+            if key.to_s == "exclude"
+               if val.respond_to?(:each)
+                  val.each{ |arg| excluded.push(arg.to_sym) } 
+               else
+                  excluded.push(val.to_sym)
+               end
+            end
+
+            if key.to_s == "alias"
+               aliased.push(val)
+            end
+         }          
+      else
+         if methods.empty?
+            module_eval{ include mod } # Mixin all methods if no arguments
+         else
+            m.module_eval do
+               include mod
+               all_methods = mod.instance_methods
+               unn_methods = all_methods - methods.map{ |method| method.to_s }
+               undef_method(*unn_methods)
+            end
+            module_eval{ include m }
+         end
+         return
+      end
+
+      unless included.empty? || excluded.empty?
+         err = "you cannot include and exclude in the same statement"
+         raise ArgumentError, err
+      end
+
+      m.module_eval{
+         include mod
+
+         aliased.each{ |pair|
+            pair.each{ |old, new|
+               included.push(old)      # Aliased methods automatically included
+               alias_method(new, old)  # Alias the old method
+               undef_method(old)       # Then remove the old method
+            }
+         }
+
+         # Undef all methods not in the 'included' array
+         unless included.empty?
+            mod.instance_methods.each{ |method|
+               method = method.to_sym
+               unless included.include?(method)
+                  undef_method(method) if method_defined?(method)
+              end
+            }
+         end
+
+         # Undef all methods in the 'excluded' array
+         excluded.each{ |method|
+            undef_method(method) if method_defined?(method)
+         }
+      }
+
+      module_eval{ include m }
+   end
+end

data/test/tc_use.rb

@@ -1,49 +1,115 @@
-###############################################
-# tc_use.rb
-#
-# Test suite for the "use" package.
-###############################################
-base = File.basename(Dir.pwd)
-
-if base == "test" || base =~ /use/
-   Dir.chdir("..") if base == "test"
-   $LOAD_PATH.unshift(Dir.pwd)
-   $LOAD_PATH.unshift(Dir.pwd + "/lib")
-   Dir.chdir("test") rescue nil
-end
-
-require "test/unit"
-require "use"
-
-module Foo
-   def bar; self; end
-   def baz; self; end
-end
-
-class User
-   use Foo, :bar
-end
-
-class TC_Use < Test::Unit::TestCase
-   def setup
-      @user = User.new
-   end
-   
-   def test_mod_methods
-      assert_equal(["baz","bar"], Foo.instance_methods)
-   end
-   
-   def test_bar_legal
-      assert_respond_to(@user, :bar)
-      assert_nothing_raised{ @user.bar }
-      assert_kind_of(User, @user.bar)
-   end
-   
-   def test_baz_not_legal
-      assert_raises(NoMethodError){ @user.baz }
-   end
-   
-   def teardown
-      @user = nil
-   end
-end
+###############################################
+# tc_use.rb
+#
+# Test suite for the "use" package.
+###############################################
+base = File.basename(Dir.pwd)
+
+if base == "test" || base =~ /use/
+   Dir.chdir("..") if base == "test"
+   $LOAD_PATH.unshift(Dir.pwd)
+   $LOAD_PATH.unshift(Dir.pwd + "/lib")
+   Dir.chdir("test") rescue nil
+end
+
+require "use"
+require "test/unit"
+
+module Foo
+   def bar; self; end
+   def baz; "hello"; end
+   def zap; "world"; end
+end
+
+module Bar
+   def bar; "bar!"; end
+   def baz; "baz!"; end
+end
+
+class User
+   use Foo, :bar
+end
+
+class Temp
+   use Foo,
+      :include => :zap,
+      :alias => {:baz, :test}
+end
+
+class Zapr
+   use Foo, :exclude => [:bar, :baz]
+   use Bar
+
+   def zap
+      "zap"
+   end
+end
+
+class Bogus
+   use Foo,
+      :alias   => {"zap", :test1, :baz, :test2},
+      :exclude => :bar
+end
+
+class TC_Use < Test::Unit::TestCase
+   def setup
+      @user = User.new
+      @temp = Temp.new
+      @zapr = Zapr.new
+   end
+
+   def test_user_mod_methods
+      assert_equal(["bar","baz","zap"], Foo.instance_methods.sort)
+   end
+
+   def test_zapr_legal_methods
+      assert_respond_to(@zapr, :zap)
+      assert_respond_to(@zapr, :bar)
+      assert_equal("zap", @zapr.zap) # Existing method not overridden
+   end
+
+   def test_temp_legal_methods
+      assert_respond_to(@temp, :zap)
+      assert_respond_to(@temp, :test)
+      assert_equal("world", @temp.zap)
+      assert_equal("hello", @temp.test)
+   end
+
+   def test_temp_expected_errors
+      assert_raises(NoMethodError){ @temp.bar }
+      assert_raises(NoMethodError){ @temp.baz } # Aliased
+   end
+   
+   def test_user_legal_methods
+      assert_respond_to(@user, :bar)
+      assert_nothing_raised{ @user.bar }
+      assert_kind_of(User, @user.bar)
+   end
+   
+   def test_user_expected_errors
+      assert_raises(NoMethodError){ @user.baz }
+      assert_raises(NoMethodError){ @user.zap }
+   end
+
+   # Don't allow exclude and include
+   def test_mutual_exclusion
+      assert_raises(ArgumentError){
+         eval{
+            "class Bogus
+               use Foo, :include => :bar, :exclude => :zap
+            end"
+         }
+      }
+      assert_raises(ArgumentError){
+         eval{
+            "class Bogus
+               use Foo, :alias => {:bar,:blah}, :exclude => :zap
+            end"
+         }
+      }
+   end
+   
+   def teardown
+      @user = nil
+   end
+end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.6
+rubygems_version: 0.8.11
 specification_version: 1
 name: use
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
-date: 2005-08-01
+  version: 1.1.0
+date: 2006-01-20 00:00:00 -07:00
 summary: Selectively mixin methods from a given module
 require_paths: 
   - lib
@@ -24,15 +24,15 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
         version: 0.0.0
   version: 
 platform: ruby
+signing_key: 
+cert_chain: 
 authors: 
   - Daniel J. Berger
 files: 
   - lib/use.rb
   - CHANGES
-  - CVS
   - MANIFEST
   - README
-  - test/CVS
   - test/tc_use.rb
 test_files: 
   - test/tc_use.rb