multimethod 0.1.0 → 0.2.0

data/ChangeLog

@@ -1,3 +1,8 @@
+2006-11-29  Kurt A. Stephens  <kurt@umleta.com>
+
+	* Major cleanup and documentation
+	* Fixed default parameter scoring.
+
 2006-11-18  Kurt A. Stephens  <kurt@umleta.com>
 
 	* Initial release

data/README.txt

@@ -15,7 +15,7 @@ gem install multimethod
 The RubyForge package multimethod
 implements multi-method dispatching on argument types.
 
-See also: ?????http://umleta.com/node/?????
+See also: http://umleta.com/node/7
 
 == Home page
 

data/Rakefile

@@ -30,7 +30,7 @@ def get_release_notes(relfile = "Releases.txt")
 
   File.open(relfile) do |f|
     while ! f.eof? && line = f.readline
-      if md = /^== Release ([\d\.]+)/i.match(line)
+      if md = /^=+ Release ([\d\.]+)/i.match(line)
         release = md[1]
         notes << line
         break
@@ -38,14 +38,14 @@ def get_release_notes(relfile = "Releases.txt")
     end
 
     while ! f.eof? && line = f.readline
-      if md = /^== Release ([\d\.]+)/i.match(line)
+      if md = /^=+ Release ([\d\.]+)/i.match(line)
         break
       end
       notes << line
     end
   end
 
-  $stderr.puts "Release #{release.inspect}"
+  # $stderr.puts "Release #{release.inspect}"
   [ release, notes.join('') ]
 end
 
@@ -83,10 +83,10 @@ version_rb = "lib/#{PKG_NAME}/#{PKG_NAME}_version.rb"
 task :update_version do
   announce "Updating #{PKG_Name} version to #{PKG_VERSION}: #{version_rb}"
   open(version_rb, "w") do |f|
+    f.puts "module #{PKG_Name}"
     f.puts "# DO NOT EDIT"
     f.puts "# This file is auto-generated by build scripts."
     f.puts "# See:  rake update_version"
-    f.puts "module #{PKG_Name}"
     f.puts "  #{PKG_Name}Version = '#{PKG_VERSION}'"
     f.puts "end"
   end

data/Releases.txt

@@ -1,14 +1,21 @@
 = Multimethod Release History
 
+== Release 0.2.0: 2006/11/29
+
+* Fixed default parameter scoring.
+* Added more documentation.
+* TODO:
+  * Need ambigious method test cases.
+
 == Release 0.1.0: 2006/11/24
 
 * Multimethods can be added and removed.
 * Better internal design: signatures vs methods.
 * TODO
-  *  Fix how default parameters are scored.
+  * Fix how default parameters are scored.
 
 == Release 0.0.1: 2006/11/18
 
 * Initial Release
 * TODO
-  *  Fix how default parameters are scored.
+  * Fix how default parameters are scored.

data/lib/multimethod.rb

@@ -1,3 +1,68 @@
+# == Introduction
+#
+# The Multimethod package implements dispatch of messages to 
+# multiple methods based on argument types.
+#
+# Variadic methods and default values are supported.
+#
+# Methods can be added and removed at run-time.
+#
+# == Examples
+#
+#  require 'multimethod'
+#
+#  class A
+#    multimethod %q{
+#    def foo(x) # matches any argument type
+#       "#{x.inspect}"
+#    end
+#    }
+#  
+#    multimethod %q{
+#    def foo(Fixnum x) # matches any Fixnum
+#       "Fixnum #{x.inspect}"
+#    end
+#    }
+#  
+#    multimethod %q{
+#    def foo(Numeric x) # matches any Numeric
+#       "Numeric #{x.inspect}"
+#    end
+#    }
+#  end
+#  
+#  a = A.new
+#  puts a.foo(:symbol) # ==> ":symbol"
+#  puts a.foo(45)      # ==> "Fixnum 45"
+#  puts a.foo(12.34)   # ==> "Numeric 12.34"
+#
+# == Known Issues
+#
+# This library is not yet thread-safe, due to caching mechanisms
+# used to increase performance.  This will be fixed in a future release.
+#
+# == Home page
+#
+# * {Multimethod Home}[http://multimethod.rubyforge.org]
+#
+# == Credits
+#
+# Multimethod was developed by:
+#
+# * Kurt Stephens -- ruby-multimethod(at)umleta.com, sponsored by umleta.com
+#
+# == Contributors
+#
+# Maybe you?
+#
+# == See Also
+#
+# * http://en.wikipedia.org/wiki/Multimethod
+# * http://rubyforge.org/projects/multi/
+#
+module Multimethod
+end
+
 $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
@@ -7,3 +72,4 @@ require 'multimethod/method'
 require 'multimethod/signature'
 require 'multimethod/parameter'
 require 'multimethod/core_extensions'
+

data/lib/multimethod/core_extensions.rb

@@ -1,5 +1,6 @@
 module Multimethod
 
+  # See Multimethod::ObjectExtension::ClassMethods
   module ObjectExtension
     def self.append_features(base) # :nodoc:
       # puts "append_features{#{base}}"
@@ -7,7 +8,25 @@ module Multimethod
       base.extend(ClassMethods)
     end
 
+
+    # This module is included into Object
+    # It is the "glue" for Multmethod.
     module ClassMethods
+      # Installs a new Multimethod Method using the multimethod syntax:
+      #
+      #    class A
+      #      multimethod q{
+      #        def foo(x)
+      #          ...
+      #        end
+      #      }
+      #      multimethod q{
+      #        def foo(A x)
+      #        end
+      #      }
+      #    end
+      #
+      # Interfaces to Multimethod::Table.instance.
       def multimethod(body, file = nil, line = nil)
         unless file && line
           fileline = caller(1)[0]
@@ -24,12 +43,17 @@ module Multimethod
         
         ::Multimethod::Table.instance.install_method(self, body, file, line)
       end
-    end
 
-    def remove_multimethod(signature)
-      ::Multimethod::Table.instance.remove_method(signature)
-    end
+      # Removes a Multimethod using a signature:
+      #
+      #    class A
+      #      remove_multimethod "def foo(A x)"
+      #    end
+      def remove_multimethod(signature)
+        ::Multimethod::Table.instance.remove_method(signature)
+      end
 
+    end # mixin
   end # class
 end # module
 

data/lib/multimethod/method.rb

@@ -1,11 +1,29 @@
 module Multimethod
 
+  # Represents a Method implementation in a Multimethod.
+  #
+  # A Method is bound to a Module using a unique implementation name for the Multimethod.
+  #
+  # A Multimethod may have multiple implementation Methods.
+  #
+  # The Multimethod is responsible for determining the correct Method based on the
+  # relative scoring of the Method Signature.
+  #
   class Method
+    # The Method's Signature used for relative scoring of applicability to an argument list.
     attr_accessor :signature
+    
+    # The Method's underlying method name.
+    # This method name is unique.
     attr_accessor :impl_name
 
+    # The Method's Multimethod.
     attr_accessor :multimethod
 
+    # Initialize a new Method.
+    # 
+    #   Method.new(impl_name, signature)
+    #   Method.new(impl_name, mod, name, parameter_list)
     def initialize(impl_name, *args)
       if args.size == 1
         @signature = args[0]
@@ -23,19 +41,20 @@ module Multimethod
     end
     
 
+    # Returns true if this Method matches the Signature.
     def matches_signature(signature)
       @signature == signature
     end
 
 
+    # Remove the method implementation from the receiver Module.
     def remove_implementation
-      # Remove the method implementation
       # $stderr.puts "Removing implementation for #{signature.to_s} => #{impl_name}"
       signature.mod.class_eval("remove_method #{impl_name.inspect}")
     end
 
 
-    # For score sort
+    # Returns 0.
     def <=>(x)
       0
     end
@@ -47,40 +66,50 @@ module Multimethod
     end
 
 
-    # Scoring this method.
+    # Score of this Method based on the argument types.
+    # The receiver type is the first element of args.
     def score(args)
       @signature.score(args)
     end
 
 
+    # Score this Method based on the argument types
+    # using a cache.
     def score_cached(args)
       @signature.score_cached(args)
     end
 
 
+    # Returns a string representation using the 
+    # implementation name.
     def to_s(name = nil)
       name ||= @impl_name
       @signature.to_s(name)
     end
 
 
+    # Returns the "def foo(...)" string
+    # using the implementation name by default.
     def to_ruby_def(name = nil)
       name ||= @impl_name
       @signature.to_ruby_def(name)
     end
 
 
+    # Returns a ruby signature
+    # using the implementation name by default.
     def to_ruby_signature(name = nil)
       name ||= @impl_name
       @signature.to_ruby_signature(name)
     end
 
 
+    # Returns a string representing the Ruby parameters.
     def to_ruby_arg
       @signature.to_ruby_arg
     end
 
-
+    # Same as #to_s.
     def inspect
       to_s
     end

data/lib/multimethod/multimethod.rb

@@ -1,10 +1,23 @@
 module Multimethod
+  # Represents a Multimethod.
+  #
+  # A Multimethod has multiple implementations of a method based on the relative scoring
+  # of the Methods based on the argument types of the message.
+  # 
+  # A Multimethod has a name.
+  #
   class Multimethod
 
+    # The Multimethod's name.
     attr_accessor :name
+
+    # A list of Method's that implement this Multimethod.
     attr_accessor :method
+
+    # The Multimethod::Table that owns this Multimethod.
     attr_accessor :table
 
+    # Initialize a new Multimethod.
     def initialize(name, *opts)
       raise NameError, "multimethod name not specified" unless name && name.to_s.size > 0
  
@@ -17,19 +30,22 @@ module Multimethod
     end
 
 
+    # Generates a unique symbol for a method name.
+    # Method implementations will use a unique name for the implementation method.
+    # For example, for a Multimethod named "foo", the Method name might be "_multimethod_12_foo".
     def gensym(name = nil)
       name ||= @name
       "_multimethod_#{@name_i = @name_i + 1}_#{name}"
     end
 
-
+    # Creates a new Method object bound to mod by name.
     def new_method(mod, name, *args)
       m = Method.new(gensym(name), mod, name, *args)
       add_method(m)
       m
     end
 
-
+    # Create a new Method object using the Signature.
     def new_method_from_signature(signature)
       m = Method.new(gensym(name), signature)
       add_method(m)
@@ -37,6 +53,7 @@ module Multimethod
     end
 
 
+    # Adds the new Method object to this Multimethod.
     def add_method(method)
       # THREAD CRITICAL BEGIN
       remove_method(method.signature)
@@ -47,18 +64,20 @@ module Multimethod
     end
 
 
+    # Returns true if this Multimethod matches the Signature.
     def matches_signature(signature)
       @name == signature.name
     end
 
 
+    # Returns a list of all Methods that match the Signature.
     def find_method(signature)
       m = @method.select{|x| x.matches_signature(signature)}
 
       m
     end
 
-
+    # Removes the method.
     def remove_method(x)
       case x
       when Signature
@@ -139,6 +158,8 @@ module Multimethod
     end
 
 
+    # Returns a sorted list of scores and Methods that
+    # match the argument types.
     def score_methods(meths, args)
       scores = meths.collect do |meth|
         score = meth.score_cached(args)
@@ -154,23 +175,14 @@ module Multimethod
       scores.compact!
       scores.sort!
       
-      # $stderr.puts "score_methods(#{args.inspect}) => \n#{scores.inspect}"
+      # $stderr.puts %{  score_methods(#{args.inspect}) => \n#{scores.collect{|x| x.inspect}.join("\n")}}
 
       scores
     end
 
 
-    def remove_dispatch(mod)
-      # THREAD CRITICAL BEGIN
-      if @dispatch[mod]
-        @dispatch[mod] = false
-        # $stderr.puts "Removing dispatch for #{mod.name}##{name}"
-        mod.class_eval("remove_method #{name.inspect}")
-      end
-      # THREAD CRITICAL END
-    end
-
-
+    # Installs a dispatching method in the Module.
+    # This method will dispatch to the Multimethod for Method lookup and application.
     def install_dispatch(mod)
       # THREAD CRITICAL BEGIN
       unless @dispatch[mod]
@@ -187,6 +199,18 @@ end_eval
     end
 
 
+    # Removes the dispatching method in the Module.
+    def remove_dispatch(mod)
+      # THREAD CRITICAL BEGIN
+      if @dispatch[mod]
+        @dispatch[mod] = false
+        # $stderr.puts "Removing dispatch for #{mod.name}##{name}"
+        mod.class_eval("remove_method #{name.inspect}")
+      end
+      # THREAD CRITICAL END
+    end
+
+
     ##################################################
     # Support
     #

data/lib/multimethod/multimethod_version.rb

@@ -1,6 +1,6 @@
+module Multimethod
 # DO NOT EDIT
 # This file is auto-generated by build scripts.
 # See:  rake update_version
-module Multimethod
-  MultimethodVersion = '0.1.0'
+  MultimethodVersion = '0.2.0'
 end

data/lib/multimethod/parameter.rb

@@ -1,18 +1,51 @@
 module Multimethod
+
+  # Represents a Parameter in a Signature.
+  #
+  # A Parameter has a name, type and position.
+  #
+  # Parameters may also have a default value or may be a restarg, a parameter that
+  # collects all remaining arguments.
+  #
+  # Restarg parameters have a lower score than other arguments.
+  #
+  # Unlike Ruby parameters, Parameters are typed.  Unspecified Parameter types default to Kernel.
+  #
   class Parameter
     include Comparable
 
-    RESTARG_SCORE = 9999
+    # The score base used for all Parameters with defaults.
+    DEFAULT_SCORE_BASE = 200
+
+    # The score used for all Parameters with defaults and no argument.
+    DEFAULT_SCORE = DEFAULT_SCORE_BASE + 100
 
+    # The score used for all restarg Parameters.
+    RESTARG_SCORE = DEFAULT_SCORE + 100
+    
+    # The Parameter name.
     attr_accessor :name
+
+    # The Parameter's offset in the Signature's parameter list.
+    # Parameter 0 is the implied "self" Parameter.
     attr_accessor :i
+
+    # The Paremeter's type, defaults to Kernel.
     attr_accessor :type
+
+    # The Parameter's default value expression.
     attr_accessor :default
+
+    # True if the Parameter is a restarg: e.g.: "*args"
     attr_accessor :restarg
 
+    # The Parameter's owning Signature.
     attr_accessor :signature
+
+    # Defines level of verbosity during processing.
     attr_accessor :verbose
 
+    # Initialize a new Parameter.
     def initialize(name = nil, type = nil, default = nil, restarg = false)
       # $stderr.puts "initialize(#{name.inspect}, #{type}, #{default.inspect}, #{restarg.inspect})"
       if name
@@ -44,7 +77,8 @@ module Multimethod
       @name = name
     end
 
-
+    # Compare two Parameters.
+    # Only type and restarg are significant.
     def <=>(p)
       x = @type <=> p.type 
       x = ! @restarg == ! p.restarg ? 0 : 1 if x == 0
@@ -54,6 +88,7 @@ module Multimethod
     end
 
 
+    # Scan a string for a Parameter specification.
     def scan_string(str, need_names = true)
       str.sub!(/\A\s+/, '')
       
@@ -130,17 +165,37 @@ module Multimethod
     end
 
 
+    # Returns the score of this Parameter matching an argument type.
+    #
+    # The score is determined by the relative distance of the Parameter
+    # to the argument type.  A lower distance means a tighter match
+    # of this Parameter.
+    #
+    # Parameters with restargs or unspecfied default arguments score lower, see RESTARG_SCORE, DEFAULT_SCORE.
     def score(arg)
-      return RESTARG_SCORE if @restarg
-      score = all_types(arg).index(type_object)
+      if @restarg
+        score = RESTARG_SCORE
+      elsif @default && ! arg
+        score = DEFAULT_SCORE
+      else
+        score = all_types(arg).index(type_object) 
+      end
+
+      # $stderr.puts "  score(#{signature.to_s}, #{to_s}, #{arg && arg.name}) => #{score}"
+
+      score
     end
 
 
-    def all_types(arg)
-      arg.ancestors
+    # Returns a list of all parent Modules of an argument type,
+    # including itself, in most-specialized
+    # to least-specialized order.
+    def all_types(arg_type)
+      arg_type.ancestors
     end
 
 
+    # Resolves type by name
     def type_object
       if @type.kind_of?(String)
         @type = Table.instance.name_to_object(@type, 
@@ -152,16 +207,20 @@ module Multimethod
     end
 
 
+    # Returns a String representing this Parameter in a Signature string.
     def to_s
       "#{@type} #{to_ruby_arg}"
     end
     
 
+    # Return a String representing this Parameter as a Ruby method parameter.
     def to_ruby_arg
       "#{to_s_name}#{@default ? ' = ' + @default : ''}"
     end
 
 
+    # Return a String representing this Parameter's name.
+    # Restargs will be prefixed with '*'.
     def to_s_name
       (@restarg ? "*" : '') + (@name.to_s || "_arg_#{@i}")
     end

data/lib/multimethod/signature.rb

@@ -1,24 +1,51 @@
 module Multimethod
 
+  # Represents a method signature.
+  # 
+  # A Signature has a bound Module, a name and a Parameter list.
+  #
+  # Each Parameter contributes to the scoring of the Method based
+  # on the message argument types, including the message receiver.
+  #
   class Signature
     include Comparable
 
-    attr_accessor :mod          # The Module the signature is bound to.
-    attr_accessor :class_method # True if the signature is bound to the class.
-    attr_accessor :name         # The name of the method signature.
-    attr_accessor :parameter    # The parameters of the method, self included.
+    # The Module that the Signature is bound to.
+    attr_accessor :mod
 
-    attr_accessor :min_args     # The minimum # of arguments for this signature
-    attr_accessor :max_args     # The maximum # of arguments for this signature;
-                                #   May be nil, if restargs
-    attr_accessor :restarg      # The "*args" parameter or nil
-    attr_accessor :default      # The first parameter with a default value.
+    # True if the signature is bound to the class.          
+    attr_accessor :class_method 
 
+    # The name of the method.
+    attr_accessor :name
+
+    # The list of Parameters, self is included at position 0.         
+    attr_accessor :parameter
+
+    # The minimum # of arguments for this signature.
+    attr_accessor :min_args
+
+    # The maximum # of arguments for this signature.
+    # May be nil, if this Signature accepts restargs.
+    attr_accessor :max_args
+                          
+    # The "*args" parameter or nil.      
+    attr_accessor :restarg
+
+    # An Array of all Parameters with a default value.
+    # Will be nil if there is not a Parameter with a default values.
+    attr_accessor :default
+
+    # The file where this Signature is specified.
     attr_accessor :file
+
+    # The line in the file where this Signature is specified.
     attr_accessor :line
 
+    # Defines level of verbosity during processing.
     attr_accessor :verbose
 
+    # Initialize a new Signature.
     def initialize(*opts)
       opts = Hash[*opts]
 
@@ -53,7 +80,7 @@ module Multimethod
     end
     
 
-    # For sort
+    # Compares two Signature objects.
     def <=>(s)
       x = @name.to_s <=> s.name.to_s 
       x = (! @class_method == ! s.class_method ? 0 : 1) if x == 0
@@ -63,6 +90,7 @@ module Multimethod
     end
 
 
+    # Returns the bound Module.
     def mod
       # THREAD CRITICAL BEGIN
       if @mod && @mod.kind_of?(String)
@@ -76,7 +104,7 @@ module Multimethod
     end
 
 
-    # Scan
+    # Scan a string as a Signature, e.g.: "def foo(A a, x = true, *restargs)"
     def scan_string(str, need_names = true)
 
       str.sub!(/\A\s+/, '')
@@ -124,6 +152,9 @@ module Multimethod
     end
 
 
+    # Scan the parameter string of a Signature:
+    #
+    #   "A a, x = true, *restargs"
     def scan_parameters_string(str, need_names = true)
       # @verbose = true
 
@@ -161,6 +192,10 @@ module Multimethod
     end
 
 
+    # Scan a programmatic Parameter list:
+    #
+    #   [ A, :a, B, :b, :c, '*d' ]
+    #
     def scan_parameters(params)
       # Add self parameter at front.
       add_self
@@ -194,12 +229,13 @@ module Multimethod
     end
     
 
-    # Add self parameter at front.
+    # Add the implicit "self" parameter at the front of the Parameter list.
     def add_self
       add_parameter(Parameter.new('self', mod)) if @parameter.empty?
     end
 
-
+    
+    # Adds a new Parameter.
     def add_parameter(p)
       if p.restarg
         raise("Too many restargs") if @restarg
@@ -224,17 +260,12 @@ module Multimethod
     end
 
 
-    def score_cached(args)
-      unless x = @score[args]
-        x = @score[args] =
-          score(args)
-      end
-      x
-    end
-
-
+    # Score of this Signature based on the argument types.
+    #
+    # The score is an Array of values that when sorted against 
+    # other Signature scores will
+    # place the best matching Signature at the top of the list.
     def score(args)
-      
       if @min_args > args.size
         # Not enough args
         score = nil
@@ -251,22 +282,35 @@ module Multimethod
         if @restarg || @default
           while (i = i + 1) < @parameter.size
             # $stderr.puts "  Adding score i=#{i}"
-            score << parameter_at(i).score(NilClass)
+            # nil means there is no argument for this parameter.
+            score << parameter_at(i).score(nil)
           end
         end
 
-        # If any argument cannot match, avoid this method.
+        # If any argument cannot match, avoid this method entirely.
+        score.flatten!
         score = nil if score.index(nil)
       end
 
-      # if true || @name =~ /_bar$/
-      #   $stderr.puts "    Method: score #{self.to_s} #{args.inspect} => #{score.inspect}"
-      # end
+      # $stderr.puts "  score(#{to_s}, #{args.inspect} => #{score.inspect})"
 
       score
     end
     
 
+    # Score of this Signature using a cache.
+    def score_cached(args)
+      unless x = @score[args]
+        x = @score[args] =
+          score(args)
+      end
+      x
+    end
+
+
+    # Returns the Parameter at argument position i.
+    # If the Signature has a restarg, it will be used for
+    # argument postitions past the end of the Parameter list.
     def parameter_at(i)
       if i >= @parameter.size && @restarg
         @restarg
@@ -276,6 +320,7 @@ module Multimethod
     end
 
  
+    # Returns a String representing this Signature.
     def to_s(name = nil)
       name ||= @name || '_'
       p = @parameter.clone
@@ -284,18 +329,21 @@ module Multimethod
     end
 
 
+    # Returns a String representing this Signature's Parameters.
     def parameter_to_s(p = nil)
       p ||= @parameter
       p.collect{|x| x.to_s}.join(', ')
     end
 
 
+    # Returns a String representing this Signature's definition in Ruby syntax.
     def to_ruby_def(name = nil)
       name ||= @name || '_'
       "def #{name}(#{to_ruby_arg})"
     end
 
 
+    # Returns a String representing this Signature's definition in Ruby Doc syntax.
     def to_ruby_signature(name = nil)
       name ||= @name || '_'
       p = @parameter.clone
@@ -305,13 +353,14 @@ module Multimethod
     end
 
 
+    # Returns a String representing this Signature's definition parameters in Ruby syntax.
     def to_ruby_arg
       x = @parameter.clone
       x.shift
       x.collect{|x| x.to_ruby_arg}.join(', ')
     end
 
-
+    # Calls #to_s.
     def inspect
       to_s
     end

data/lib/multimethod/table.rb

@@ -1,16 +1,25 @@
 module Multimethod
+  # Represents a Multimethod repository.
+  #
+  # There is typically only one instance.
+  #
+  # It provides the interface to the core extensions.
+  #
   class Table
 
     @@instance = nil
+    # Returns the current instance or creates a new one.
     def self.instance
       # THREAD CRITICAL BEGIN
       @@instance ||= self.new
       # TRREAD CRITICAL END
     end
 
-    @@hook_var = :@@__multimethods
- 
-    attr_accessor :method
+
+    # A list of all Multimethod objects.
+    attr_accessor :multimethod
+
+    # Creates a new Table object.
     def initialize(*opts)
       @multimethod_by_name = { }
       @multimethod = [ ]
@@ -20,7 +29,20 @@ module Multimethod
     end
 
 
-    @@match_def = /^\s*def\s+(\w+)([(](.*)[)])?/
+    # Installs a new Multimethod Method using the multimethod syntax:
+    #
+    #    class A
+    #      multimethod q{
+    #        def foo(x)
+    #          ...
+    #        end
+    #      }
+    #      multimethod q{
+    #        def foo(A x)
+    #        end
+    #      }
+    #    end
+    #
     # Interface to Multimethod::Module mixin multimethod
     def install_method(mod, body, file = nil, line = nil)
       file ||= __FILE__
@@ -55,12 +77,16 @@ module Multimethod
     end
 
 
+    # Returns the Multimethods that matches a signature.
+    # The signature can be a String, Method or Signature object.
     def find_multimethod(x)
       case x
       when String
         signature = Signature.new(:string => x)
-        when Method
+      when Method
         signature = x.signature
+      when Signature
+        signature = x
       end
 
       x = @multimethod.select{|mm| mm.matches_signature(signature)}
@@ -69,12 +95,17 @@ module Multimethod
     end
 
 
+    # Returns a list of all the Methods that match a signature.
+    #
+    # The signature can be a String, Method or Signature object.
     def find_method(x)
       case x
       when String
         signature = Signature.new(:string => x)
       when Method
         signature = x.signature
+      when Signature
+        signature = x
       end
 
       x = @multimethod.select{|mm| mm.matches_signature(signature)}
@@ -86,6 +117,11 @@ module Multimethod
     end
 
 
+    # Removed the Method that match a signature.
+    #
+    # The signature can be a String, Method or Signature object.
+    #
+    # Raises an error if more than one Method is found.
     def remove_method(signature)
       x = find_method(signature)
       raise("Found #{x.size} multimethods: #{x.inspect}") if x.size > 1
@@ -94,6 +130,9 @@ module Multimethod
     end
 
 
+    # Returns a Multimethod object for a method name.
+    #
+    # Will create a new Multimethod if needed.
     def lookup_multimethod(name)
       name = name.to_s
 
@@ -110,7 +149,7 @@ module Multimethod
     end
 
 
-    # Interface to code generated by #install_dispatch.
+    # Dispatches to the appropriate Method based on name, receiver and arguments.
     def dispatch(name, rcvr, args)
       unless mm = @multimethod_by_name[name]
         raise NameError, 'No method for multmethod #{name}' unless mm
@@ -123,6 +162,7 @@ module Multimethod
     # Support
     #
 
+    # Returns the object for name, using the appropriate evaluation scope.
     def name_to_object(name, scope = nil, file = nil, line = nil)
       scope ||= Kernel
       # THREAD CRITICAL BEGIN

data/test/usage_test.rb

@@ -47,39 +47,54 @@ class C < Object
   include Comparable
 end
 
+
 class D < B
   # Variadic
   multimethod %q{
-def bar(x)
-  x = "D#bar(x) : (#{x.class.name})"
+def bbb(x)
+  x = "D#bbb(x) : (#{x.class.name})"
+  x
+end
+}
+
+  multimethod %q{
+def bbb(*rest)
+  x = "D#bbb(*rest) : (#{rest.collect{|x| x.class}.inspect})"
+  x
+end
+}
+
+  multimethod %q{
+def bbb(x, y)
+  x = "D#bbb(x, y) : (#{x.class.name}, #{y.class.name})"
   x
 end
 }
 
   multimethod %q{
-def bar(*rest)
-  x = "D#bar(*rest) : (#{rest.inspect})"
+def bbb(Fixnum x, String y)
+  x = "D#bbb(Fixnum x, String y) : (#{x.class.name}, #{y.class.name})"
   x
 end
 }
 
   multimethod %q{
-def bar(x, y)
-  x = "D#bar(x, y) : (#{x.class.name}, #{y.class.name})"
+def bbb(Fixnum x, Fixnum y = 1)
+  x = "D#bbb(Fixnum x, Fixnum y = 1) : (#{x.class.name}, #{y.class.name})"
   x
 end
 }
 
   multimethod %q{
-def bar(x, y, A a)
-  x = "D#bar(x, y, A a) : (#{x.class.name}, #{y.class.name}, #{a.class.name})"
+def bbb(x, String y, A a)
+  x = "D#bbb(x, String y, A a) : (#{x.class.name}, #{y.class.name}, #{a.class.name})"
   x
 end
 }
 
   multimethod %q{
-def bar(x, y, *rest)
-  x = "D#bar(x, y, *rest) : (#{x.class.name}, #{y.class.name}, #{rest.inspect})"
+def bbb(Fixnum x, y, *rest)
+  x = "D#bbb(Fixnum x, y, *rest) : (#{x.class.name}, #{y.class.name}, #{rest.collect{|x| x.class}.inspect})"
   x
 end
 }
@@ -125,20 +140,38 @@ module Multimethod
       a = A.new
       d = D.new
 
-      assert_equal 'D#bar(*rest) : ([])',
-        d.bar()
+      assert_not_nil bbb_mm = ::Multimethod::Table.instance.multimethod.select{|mm| mm.name == 'bbb'}
+      assert_equal 1, bbb_mm.size
+      assert_kind_of ::Multimethod::Multimethod, bbb_mm = bbb_mm[0]
+
+      assert_equal 7, bbb_mm.method.size
+      
+      assert_equal 'D#bbb(*rest) : ([])',
+        d.bbb()
+
+      assert_equal 'D#bbb(x) : (Symbol)',
+        d.bbb(:x)
+
+      assert_equal 'D#bbb(Fixnum x, String y) : (Fixnum, String)' ,   
+        d.bbb(1, 'a')
+
+      assert_equal 'D#bbb(Fixnum x, Fixnum y = 1) : (Fixnum, Fixnum)' ,   
+        d.bbb(1, 2)
+
+      assert_equal 'D#bbb(x, y) : (Symbol, Symbol)' ,   
+        d.bbb(:x, :y)
 
-      assert_equal 'D#bar(x) : (Fixnum)',
-        d.bar(1)
+      assert_equal 'D#bbb(*rest) : ([Symbol, D, D])' ,   
+        d.bbb(:x, d, d)
 
-      assert_equal 'D#bar(x, y) : (Fixnum, String)' ,   
-        d.bar(1, 'a')
+      assert_equal 'D#bbb(Fixnum x, y, *rest) : (Fixnum, String, [A])' , 
+        d.bbb(1, 'a', a)
 
-      assert_equal 'D#bar(x, y, A a) : (Fixnum, String, A)' , 
-        d.bar(1, 'a', a)
+      assert_equal 'D#bbb(x, String y, A a) : (String, String, A)' , 
+        d.bbb('a', 'b', a)
 
-      assert_equal 'D#bar(x, y, *rest) : (Fixnum, String, [3])' , 
-        d.bar(1, 'a', 3)
+      assert_equal 'D#bbb(Fixnum x, y, *rest) : (Fixnum, String, [Fixnum])' , 
+        d.bbb(1, 'a', 3)
     end
 
   end # class

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: multimethod
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-11-24 00:00:00 -05:00
+  version: 0.2.0
+date: 2006-11-29 00:00:00 -05:00
 summary: "Supports Multimethod dispatching.  For more details, see:  http://multimethod.rubyforge.org/files/lib/multimethod_rb.html  http://multimethod.rubyforge.org/files/README.txt http://multimethod.rubyforge.org/"
 require_paths: 
 - lib