dyoder-functor 0.3.1 → 0.4.0

data/doc/README

@@ -1,4 +1,8 @@
-Functor provides pattern-based function and method dispatch for Ruby. To use it in a class:
+Functor provides pattern-based function and method dispatch for Ruby, originally inspired by Topher Cyll's multi gem. 
+
+= Method Functors
+
+To use it in a class:
 
   class Repeater
     attr_accessor :times
@@ -13,16 +17,18 @@ Functor provides pattern-based function and method dispatch for Ruby. To use it
   r.repeat( "-" ) # => "- - - - -"
   r.repeat( 7.3 ) # => ArgumentError!
 
-Warning: This defines a class instance variable @__functors behind the scenes as a side-effect. Also, although inheritance works within a functor method, super does not. To call the parent method, you need to call it explicitly using the #functors class method, like this:
+Warning: This defines a class instance variable <tt>@__functors</tt> behind the scenes as a side-effect. Also, although inheritance works within a functor method, super does not. To call the parent method, you need to call it explicitly using the <tt>#functors</tt> class method, like this:
 
   A.functors[ :foo ].apply( self, 'bar' )
 
+= Stand-Alone Functors
+
 You can also define Functor objects directly:
 
   fib = Functor.new do
     given( 0 ) { 0 }
     given( 1 ) { 1 }
-    given( 2..10000 ) { |n| self.call( n - 1 ) + self.call( n - 2 ) }
+    given( Integer ) { |n| self.call( n - 1 ) + self.call( n - 2 ) }
   end
   
 You can use functors directly with functions taking a block like this:
@@ -33,7 +39,9 @@ You can call a functor as a method using #apply:
 
   fun.apply( obj, 7 )
   
-which is actually how the method dispatch is implemented.
+which is actually how the method functors are implemented.
+
+= Pattern Matching
 
 Arguments are matched first using === and then ==, so anything that supports these methods can be matched against. In addition, you may pass "guards," any object that responds to #call and which take and object (the argument) and return true or false. This allows you to do things like this:
 
@@ -42,4 +50,22 @@ Arguments are matched first using === and then ==, so anything that supports the
     given( lambda { |x| x % 2 == 1 } ) { 'silver' }
   end
 
-which will return "white" and "silver" alternately for a sequence of numbers.
+which will return "white" and "silver" alternately for a sequence of numbers.
+
+= Precedence
+
+Precedence is defined in order of declaration: first-come, first-serve, aka FIFO. Thus, you need to be careful in how you define your functor. The Fibonacci example above would not work properly if the Integer pattern was given first. That said, it is possible to redefine earlier cases, which, in effect, "demotes" it, as if it had not been declared before. So the following will work properly:
+
+  fib = Functor.new do
+    given( Integer ) { |n| raise "this would start an infinite loop ..." }
+    given( 0 ) { 0 }
+    given( 1 ) { 1 }
+    # but this will "demote" the Integer pattern and now it will work ...
+    given( Integer ) { |n| self.call( n - 1 ) + self.call( n - 2 ) }
+  end
+
+This isn't perfect, but it is very easy to predict, simple to implement, and reasonably fast, which other approaches (such as implementing a precedence scheme) are not.
+
+= Credits And Support
+
+Functor was written by Dan Yoder, Matthew King, and Lawrence Pit. Send email to dan at zeraweb.com for support or questions.

data/lib/functor.rb

@@ -11,7 +11,7 @@ class Functor
           klass = self.name ; module_eval <<-CODE
             def #{name}( *args, &block ) 
               begin
-                #{klass}.functors[ :#{name} ].apply( self, *args, &block ) 
+                rval = #{klass}.functors[ :#{name} ].apply( self, *args, &block ) 
               rescue ArgumentError => e
                 begin
                   super
@@ -19,6 +19,11 @@ class Functor
                   raise e
                 end
               end
+              if rval.is_a? Continuation
+                super ; rval.call
+              else
+                rval
+              end
             end
           CODE
         end
@@ -52,13 +57,16 @@ class Functor
   def match( *args, &block )
     args.push( block ) if block_given? 
     pattern, action = @rules.find { | pattern, action | match?( args, pattern ) }
-    raise ArgumentError.new( "argument mismatch for argument(s): #{args.inspect}." ) unless action
+    raise ArgumentError.new( "argument mismatch for argument(s): #{ args.map { |arg| arg.inspect }.join(', ') }." ) unless action
     return action
   end
   
   def match?( args, pattern )
-    pattern.zip(args).all? { |x,y| x === y or x == y or 
-        ( x.respond_to?(:call) && x.call( y ) ) } if pattern.length == args.length
+    args.zip( pattern ).all? { | arg, rule | pair?( arg, rule ) } if args.length == pattern.length
+  end
+  
+  def pair?( arg, rule )
+    ( rule.is_a?( Proc ) and rule.call( arg ) ) or rule === arg or rule == arg
   end
   
 end

data/test/guards.rb

@@ -1,15 +1,25 @@
 require 'test/helpers'
 
-stripe ||= Functor.new do
-  given( lambda { |x| x % 2 == 0 } ) { 'white' }
-  given( lambda { |x| x % 2 == 1 } ) { 'silver' }
-end
+describe "Dispatch should support guards" do
+  
+  before do
+    @stripe = Functor.new do
+      given( lambda { |x| x % 2 == 0 } ) { 'white' }
+      given( lambda { |x| x % 2 == 1 } ) { 'silver' }
+    end
 
-describe "Dipatch should support guards" do
+    @safe_divide = Functor.new do
+      given( lambda { |x| x == 0 }, Integer ) { |x,y| false }
+      given( Integer, Integer ) { |x,y| ( y / ( x * 1.0 )) }
+    end
+  end
   
-  specify "allowing you to use odd or even numbers as a dispatcher" do
-    [*0..9].map( &stripe ).should == %w( white silver ) * 5
+  specify "such as odd or even numbers" do
+    [*0..9].map( &@stripe ).should == %w( white silver ) * 5
   end
   
-end
+  specify "even with multiple arguments" do
+    @safe_divide.call( 0,7 ).should == false
+  end
   
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dyoder-functor
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors: 
 - Dan Yoder
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-06-15 00:00:00 -07:00
+date: 2008-06-29 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -25,6 +25,35 @@ extra_rdoc_files: []
 
 files: 
 - doc/HISTORY
+- doc/rdoc
+- doc/rdoc/classes
+- doc/rdoc/classes/Functor
+- doc/rdoc/classes/Functor/Method.html
+- doc/rdoc/classes/Functor/Method.src
+- doc/rdoc/classes/Functor/Method.src/M000006.html
+- doc/rdoc/classes/Functor.html
+- doc/rdoc/classes/Functor.src
+- doc/rdoc/classes/Functor.src/M000001.html
+- doc/rdoc/classes/Functor.src/M000002.html
+- doc/rdoc/classes/Functor.src/M000003.html
+- doc/rdoc/classes/Functor.src/M000004.html
+- doc/rdoc/classes/Functor.src/M000005.html
+- doc/rdoc/classes/Object.html
+- doc/rdoc/classes/Object.src
+- doc/rdoc/classes/Object.src/M000007.html
+- doc/rdoc/created.rid
+- doc/rdoc/files
+- doc/rdoc/files/doc
+- doc/rdoc/files/doc/HISTORY.html
+- doc/rdoc/files/doc/README.html
+- doc/rdoc/files/lib
+- doc/rdoc/files/lib/functor_rb.html
+- doc/rdoc/files/lib/object_rb.html
+- doc/rdoc/fr_class_index.html
+- doc/rdoc/fr_file_index.html
+- doc/rdoc/fr_method_index.html
+- doc/rdoc/index.html
+- doc/rdoc/rdoc-style.css
 - doc/README
 - lib/functor.rb
 - lib/object.rb
@@ -57,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: functor
-rubygems_version: 1.0.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: Pattern-based dispatch for Ruby, inspired by Topher Cyll's multi.