functor 0.3.1

data/doc/HISTORY

@@ -0,0 +1,3 @@
+0.1 - Initial implemention of Functor class.
+0.2 - Added method dispatch, to_proc support, tests.
+0.3 - Added support for guards and redefinition.

data/doc/README

@@ -0,0 +1,45 @@
+Functor provides pattern-based function and method dispatch for Ruby. To use it in a class:
+
+  class Repeater
+    attr_accessor :times
+    include Functor::Method
+    functor( :repeat, Integer ) { |x| x * @times }
+    functor( :repeat, String ) { |s| [].fill( s, 0..@times ).join(' ') }
+  end
+
+  r = Repeater.new
+  r.times = 5
+  r.repeat( 5 )   # => 25
+  r.repeat( "-" ) # => "- - - - -"
+  r.repeat( 7.3 ) # => RuntimeError!
+
+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:
+
+  A.functors[ :foo ].apply( self, 'bar' )
+
+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 ) }
+  end
+  
+You can use functors directly with functions taking a block like this:
+
+  [ *0..10 ].map( &fib )  # => [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]
+  
+You can explicitly bind self using #bind:
+
+  fun.bind( obj )
+  
+which is actually how the method dispatch is implemented.
+
+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:
+
+  stripe ||= Functor.new do
+    given( lambda { |x| x % 2 == 0 } ) { 'white' }
+    given( lambda { |x| x % 2 == 1 } ) { 'silver' }
+  end
+
+which will return "white" and "silver" alternately for a sequence of numbers.

data/lib/functor.rb

@@ -0,0 +1,64 @@
+require 'lib/object'
+
+class Functor
+  
+  module Method
+    def self.included( k )
+      def k.functors ; @__functors ||= {} ; end
+      def k.functor( name, *args, &block )
+        unless functors[ name ]
+          functors[ name ] = Functor.new
+          klass = self.name ; module_eval <<-CODE
+            def #{name}( *args, &block ) 
+              begin
+                #{klass}.functors[ :#{name} ].apply( self, *args, &block ) 
+              rescue ArgumentError => e
+                begin
+                  super
+                rescue NoMethodError => f
+                  raise e
+                end
+              end
+            end
+          CODE
+        end
+        functors[ name ].given( *args, &block )
+      end
+    end
+  end
+  
+  def initialize( &block ) 
+    @rules = [] ; instance_eval( &block ) if block_given?
+  end
+  
+  def given( *pattern, &action )
+    @rules.delete_if { |p,a| p == pattern }
+    @rules << [ pattern, action ]
+  end
+  
+  def apply( object, *args, &block )
+    object.instance_exec( *args, &match( *args, &block ) )
+  end
+  
+  def call( *args, &block )
+    args.push( block ) if block_given?
+    match( *args, &block ).call( *args )
+  end
+  
+  def to_proc ; lambda { |*args| self.call( *args ) } ; end
+  
+  private
+  
+  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
+    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
+  end
+  
+end

data/lib/object.rb

@@ -0,0 +1,17 @@
+class Object
+  # This is an extremely powerful little function that will be built-in to Ruby 1.9.
+  # This version is from Mauricio Fernandez via ruby-talk. Works like instance_eval
+  # except that you can pass parameters to the block. This means you can define a block
+  # intended for use with instance_eval, pass it to another method, which can then
+  # invoke with parameters. This is used quite a bit by the Waves::Mapping code.
+  def instance_exec(*args, &block)
+    mname = "__instance_exec_#{Thread.current.object_id.abs}"
+    class << self; self end.class_eval{ define_method(mname, &block) }
+    begin
+      ret = send(mname, *args)
+    ensure
+      class << self; self end.class_eval{ undef_method(mname) } rescue nil
+    end
+    ret
+  end
+end

data/test/fib.rb

@@ -0,0 +1,16 @@
+require "#{File.dirname(__FILE__)}/helpers"
+
+fib ||= Functor.new do
+  given( 0 ) { 0 }
+  given( 1 ) { 1 }
+  given( Integer ) { | n | self.call( n - 1 ) + self.call( n - 2 ) }
+end
+
+describe "Dispatch on a functor object should" do
+  
+  specify "be able to implement the Fibonacci function" do
+    [*0..10].map( &fib ).should == [ 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55 ]
+  end
+  
+end
+  

data/test/functor.rb

@@ -0,0 +1,29 @@
+require "#{File.dirname(__FILE__)}/helpers"
+
+class Repeater
+  attr_accessor :times
+  include Functor::Method
+  functor( :repeat, Integer ) { |x| x * @times }
+  functor( :repeat, String ) { |s| [].fill( s, 0, @times ).join(' ') }
+  functor( :repeat ) { nil }
+end
+
+describe "Dispatch on instance method should" do
+  
+  before do
+    @r = Repeater.new
+    @r.times = 5
+  end
+  
+  specify "invoke different methods with object scope based on arguments" do
+    @r.repeat( 5 ).should == 25
+    @r.repeat( "-" ).should == '- - - - -'
+    @r.repeat.should == nil
+  end
+  
+  specify "raise an exception if there is no matching value" do
+    lambda { @r.repeat( 7.3 ) }.should.raise(ArgumentError)
+  end
+end
+
+  

data/test/guards.rb

@@ -0,0 +1,15 @@
+require 'test/helpers'
+
+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
+  
+  specify "allowing you to use odd or even numbers as a dispatcher" do
+    [*0..9].map( &stripe ).should == %w( white silver ) * 5
+  end
+  
+end
+  

data/test/helpers.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+%w{ bacon }.each { |dep| require dep }
+Bacon.summary_on_exit
+
+module Kernel
+  private
+  def specification(name, &block)  Bacon::Context.new(name, &block) end
+end
+
+Bacon::Context.instance_eval do
+  alias_method :specify, :it
+end
+
+$:.unshift "#{File.dirname(__FILE__)}/../lib"
+require "functor"

data/test/inheritance.rb

@@ -0,0 +1,28 @@
+require "#{File.dirname(__FILE__)}/helpers"
+
+class A
+  include Functor::Method
+  functor( :foo, Integer ) { |x| [ A, Integer ] }
+  functor( :foo, String ) { |s| [ A, String ] }
+  functor( :foo, Float ) { |h| [ A, Float ] }
+end
+
+class B < A
+  functor( :foo, String ) { |s| [ B, String ] }
+  functor( :foo, Float ) { |f| [ B, *A.functors[:foo].apply( self, f ) ] }
+end
+
+describe "Functor methods should support inheritance" do
+  
+  specify "by inheriting base class implementations" do
+    B.new.foo( 5 ).should == [ A, Integer ]
+  end
+  
+  specify "by allowing derived classes to override an implementation" do
+    B.new.foo( "bar" ).should == [ B, String ]
+  end
+  
+  specify "by allowing you to call base class functors using #functors" do
+    B.new.foo( 1.0 ).should == [ B, A, Float ]
+  end
+end

data/test/matchers.rb

@@ -0,0 +1,24 @@
+require "#{File.dirname(__FILE__)}/helpers"
+
+class C
+  include Functor::Method
+  functor( :foo, 1 ) { |a| "==" }
+  functor( :foo, Integer ) { |a| "===" }
+  functor( :foo, lambda { |a| a == "boo" } ) { |v| "Lambda: #{v}" }
+end
+
+describe "Functors match" do
+
+  specify "using ==" do
+    C.new.foo( 1 ).should == "=="
+  end
+  
+  specify "using ===" do
+    C.new.foo( 2 ).should == "==="
+  end
+
+  specify "using #call" do
+    C.new.foo( "boo" ).should == "Lambda: boo"
+  end
+
+end

data/test/reopening.rb

@@ -0,0 +1,18 @@
+require "#{File.dirname(__FILE__)}/helpers"
+
+class A
+  include Functor::Method
+  functor( :foo, Integer ) { |x| 1 }
+end
+
+class A
+  functor( :foo, Integer ) { |x| 2 }
+end
+
+describe "Functor methods should support reopening" do
+
+  specify "by allowing reopening of a class to override an implementation" do
+    A.new.foo( 5 ).should == 2
+  end
+
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: functor
+version: !ruby/object:Gem::Version 
+  version: 0.3.1
+platform: ruby
+authors: 
+- Dan Yoder
+- Matthew King
+- Lawrence Pit
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-06-15 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: dan@zeraweb.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- doc/HISTORY
+- doc/README
+- lib/functor.rb
+- lib/object.rb
+- test/fib.rb
+- test/functor.rb
+- test/guards.rb
+- test/helpers.rb
+- test/inheritance.rb
+- test/matchers.rb
+- test/reopening.rb
+has_rdoc: true
+homepage: http://dev.zeraweb.com/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: functor
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Pattern-based dispatch for Ruby, inspired by Topher Cyll's multi.
+test_files: []
+