rumonade 0.1.2 → 0.2.0

data/CHANGELOG.rdoc

@@ -1,3 +1,7 @@
+=== 0.2.0 / 2011-10-18
+
+* scala-like Either class w/ LeftProjection and RightProjection monads
+
 === 0.1.2 / 2011-10-12
 
 * Progress towards Either

data/README.rdoc

@@ -2,7 +2,7 @@
 
 Project: github[http://github.com/ms-ati/rumonade]
 
-Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/file/README.rdoc]
+Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/0.2.0/file/README.rdoc]
 
 == A Ruby[http://www.ruby-lang.org] Monad[http://en.wikipedia.org/wiki/Monad_(functional_programming)] Library, Inspired by Scala[http://www.scala-lang.org]
 
@@ -71,5 +71,5 @@ The priorities for Rumonade are:
 
 == Status
 
-This code is in a very early state, but the Option monad is already present.
+Option, Either, and Array are complete.
 Please try it out, and let me know what you think!

data/lib/rumonade.rb

@@ -21,6 +21,7 @@
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #++
 require "rumonade/version"
+require "rumonade/errors"
 require "rumonade/monad"
 require "rumonade/lazy_identity"
 require "rumonade/option"

data/lib/rumonade/either.rb

@@ -60,6 +60,11 @@ module Rumonade
     def ==(other)
       other.is_a?(Left) && other.left_value == self.left_value
     end
+
+    # @return [String] Returns a +String+ representation of this object.
+    def to_s
+      "Left(#{left_value})"
+    end
   end
 
   # The right side of the disjoint union, as opposed to the Left side.
@@ -76,6 +81,11 @@ module Rumonade
     def ==(other)
       other.is_a?(Right) && other.right_value == self.right_value
     end
+
+    # @return [String] Returns a +String+ representation of this object.
+    def to_s
+      "Right(#{right_value})"
+    end
   end
 
   # @param (see Left#initialize)
@@ -93,6 +103,18 @@ module Rumonade
   class Either
     # Projects an Either into a Left.
     class LeftProjection
+      class << self
+        # @return [LeftProjection] Returns a +LeftProjection+ of the +Left+ of the given value
+        def unit(value)
+          self.new(Left(value))
+        end
+
+        # @return [LeftProjection] Returns the empty +LeftProjection+
+        def empty
+          self.new(Right(nil))
+        end
+      end
+
       # @param either_value [Object] the Either value to project
       def initialize(either_value)
         @either_value = either_value
@@ -101,18 +123,74 @@ module Rumonade
       # @return Returns the Either value
       attr_reader :either_value
 
+      # @return [Boolean] Returns +true+ if other is a +LeftProjection+ with an equal +Either+ value
       def ==(other)
         other.is_a?(LeftProjection) && other.either_value == self.either_value
       end
 
+      # Binds the given function across +Left+.
       def bind(lam = nil, &blk)
-        !either_value.left? ? either_value : (lam || blk).call(either_value.left_value)
+        if !either_value.left? then either_value else (lam || blk).call(either_value.left_value) end
+      end
+
+      include Monad
+
+      # @return [Boolean] Returns +false+ if +Right+ or returns the result of the application of the given function to the +Left+ value.
+      def any?(lam = nil, &blk)
+        either_value.left? && bind(lam || blk)
+      end
+
+      # @return [Option] Returns +None+ if this is a +Right+ or if the given predicate does not hold for the +left+ value, otherwise, returns a +Some+ of +Left+.
+      def select(lam = nil, &blk)
+        Some(self).select { |lp| lp.any?(lam || blk) }.map { |lp| lp.either_value }
+      end
+
+      # @return [Boolean] Returns +true+ if +Right+ or returns the result of the application of the given function to the +Left+ value.
+      def all?(lam = nil, &blk)
+        !either_value.left? || bind(lam || blk)
+      end
+
+      # Returns the value from this +Left+ or raises +NoSuchElementException+ if this is a +Right+.
+      def get
+        if either_value.left? then either_value.left_value else raise NoSuchElementError end
+      end
+
+      # Returns the value from this +Left+ or the given argument if this is a +Right+.
+      def get_or_else(val_or_lam = nil, &blk)
+        v_or_f = val_or_lam || blk
+        if either_value.left? then either_value.left_value else (v_or_f.respond_to?(:call) ? v_or_f.call : v_or_f) end
+      end
+
+      # @return [Option] Returns a +Some+ containing the +Left+ value if it exists or a +None+ if this is a +Right+.
+      def to_opt
+        Option(get_or_else(nil))
+      end
+
+      # @return [Either] Maps the function argument through +Left+.
+      def map(lam = nil, &blk)
+        bind { |v| Left((lam || blk).call(v)) }
+      end
+
+      # @return [String] Returns a +String+ representation of this object.
+      def to_s
+        "LeftProjection(#{either_value})"
       end
-      alias_method :flat_map, :bind
     end
 
     # Projects an Either into a Right.
     class RightProjection
+      class << self
+        # @return [RightProjection] Returns a +RightProjection+ of the +Right+ of the given value
+        def unit(value)
+          self.new(Right(value))
+        end
+
+        # @return [RightProjection] Returns the empty +RightProjection+
+        def empty
+          self.new(Left(nil))
+        end
+      end
+
       # @param either_value [Object] the Either value to project
       def initialize(either_value)
         @either_value = either_value
@@ -121,14 +199,58 @@ module Rumonade
       # @return Returns the Either value
       attr_reader :either_value
 
+      # @return [Boolean] Returns +true+ if other is a +RightProjection+ with an equal +Either+ value
       def ==(other)
         other.is_a?(RightProjection) && other.either_value == self.either_value
       end
 
+      # Binds the given function across +Right+.
       def bind(lam = nil, &blk)
-        !either_value.right? ? either_value : (lam || blk).call(either_value.right_value)
+        if !either_value.right? then either_value else (lam || blk).call(either_value.right_value) end
+      end
+
+      include Monad
+
+      # @return [Boolean] Returns +false+ if +Left+ or returns the result of the application of the given function to the +Right+ value.
+      def any?(lam = nil, &blk)
+        either_value.right? && bind(lam || blk)
+      end
+
+      # @return [Option] Returns +None+ if this is a +Left+ or if the given predicate does not hold for the +Right+ value, otherwise, returns a +Some+ of +Right+.
+      def select(lam = nil, &blk)
+        Some(self).select { |lp| lp.any?(lam || blk) }.map { |lp| lp.either_value }
+      end
+
+      # @return [Boolean] Returns +true+ if +Left+ or returns the result of the application of the given function to the +Right+ value.
+      def all?(lam = nil, &blk)
+        !either_value.right? || bind(lam || blk)
+      end
+
+      # Returns the value from this +Right+ or raises +NoSuchElementException+ if this is a +Left+.
+      def get
+        if either_value.right? then either_value.right_value else raise NoSuchElementError end
+      end
+
+      # Returns the value from this +Right+ or the given argument if this is a +Left+.
+      def get_or_else(val_or_lam = nil, &blk)
+        v_or_f = val_or_lam || blk
+        if either_value.right? then either_value.right_value else (v_or_f.respond_to?(:call) ? v_or_f.call : v_or_f) end
+      end
+
+      # @return [Option] Returns a +Some+ containing the +Right+ value if it exists or a +None+ if this is a +Left+.
+      def to_opt
+        Option(get_or_else(nil))
+      end
+
+      # @return [Either] Maps the function argument through +Right+.
+      def map(lam = nil, &blk)
+        bind { |v| Right((lam || blk).call(v)) }
+      end
+
+      # @return [String] Returns a +String+ representation of this object.
+      def to_s
+        "RightProjection(#{either_value})"
       end
-      alias_method :flat_map, :bind
     end
   end
 end

data/lib/rumonade/errors.rb

@@ -0,0 +1,6 @@
+module Rumonade
+
+  # Exception raised on attempts to access non-existent wrapped values
+  class NoSuchElementError < RuntimeError; end
+
+end

data/lib/rumonade/option.rb

@@ -35,22 +35,24 @@ module Rumonade # :nodoc:
   #       puts "No name value"
   #   end
   #
+  # @abstract
   class Option
     class << self
-      # Returns a new Option containing the given value
+      # @return [Option] Returns an +Option+ containing the given value
       def unit(value)
         Rumonade.Option(value)
       end
 
-      # Returns the empty Option (None)
+      # @return [Option] Returns the empty +Option+
       def empty
         None
       end
     end
 
-    def initialize # :nodoc:
+    def initialize
       raise(TypeError, "class Option is abstract; cannot be instantiated") if self.class == Option
     end
+    private :initialize
 
     # Returns None if None, or the result of executing the given block or lambda on the contents if Some
     def bind(lam = nil, &blk)
@@ -59,7 +61,7 @@ module Rumonade # :nodoc:
 
     include Monad
 
-    # Returns +true+ if None, +false+ if Some
+    # @return [Boolean] Returns +true+ if +None+, +false+ if +Some+
     def empty?
       raise(NotImplementedError)
     end
@@ -89,6 +91,7 @@ module Rumonade # :nodoc:
 
     attr_reader :value # :nodoc:
 
+    # @return (see Option#empty?)
     def empty?
       false
     end
@@ -106,6 +109,7 @@ module Rumonade # :nodoc:
   class NoneClass < Option
     include Singleton
 
+    # @return (see Option#empty?)
     def empty?
       true
     end
@@ -119,15 +123,12 @@ module Rumonade # :nodoc:
     end
   end
 
-  # Exception raised on attempts to access the value of None
-  class NoSuchElementError < RuntimeError; end
-
   # Returns an Option wrapping the given value: Some if non-nil, None if nil
   def Option(value)
     value.nil? ? None : Some(value)
   end
 
-  # Returns a Some wrapping the given value, for convenience
+  # @return [Some] Returns a +Some+ wrapping the given value, for convenience
   def Some(value)
     Some.new(value)
   end

data/lib/rumonade/version.rb

@@ -1,3 +1,3 @@
 module Rumonade
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/test/either_test.rb

@@ -50,4 +50,113 @@ class EitherTest < Test::Unit::TestCase
     assert_equal Right("ERROR"), Left("error").left.flat_map { |n| Right(n.upcase) }
     assert_equal Left("error"), Left("error").right.flat_map { |n| Right(n.upcase) }
   end
+
+  def test_any_predicate_for_left_and_right_projections_returns_true_if_correct_type_and_block_returns_true
+    assert Left("error").left.any? { |s| s == "error" }
+    assert !Left("error").left.any? { |s| s != "error" }
+    assert !Left("error").right.any? { |s| s == "error" }
+
+    assert Right(42).right.any? { |n| n == 42 }
+    assert !Right(42).right.any? { |n| n != 42 }
+    assert !Right(42).left.any? { |n| n == 42 }
+  end
+
+  def test_select_for_left_and_right_projects_returns_option_of_either_if_correct_type_and_block_returns_true
+    assert_equal Some(Left("error")), Left("error").left.select { |s| s == "error" }
+    assert_equal None, Left("error").left.select { |s| s != "error" }
+    assert_equal None, Left("error").right.select { |s| s == "error" }
+
+    assert_equal Some(Right(42)), Right(42).right.select { |n| n == 42 }
+    assert_equal None, Right(42).right.select { |n| n != 42 }
+    assert_equal None, Right(42).left.select { |n| n == 42 }    
+  end
+  
+  def test_all_predicate_for_left_and_right_projections_returns_true_if_correct_type_and_block_returns_true
+    assert Left("error").left.all? { |s| s == "error" }
+    assert !Left("error").left.all? { |s| s != "error" }
+    assert Left("error").right.all? { |s| s == "error" }
+
+    assert Right(42).right.all? { |n| n == 42 }
+    assert !Right(42).right.all? { |n| n != 42 }
+    assert Right(42).left.all? { |n| n == 42 }
+  end  
+
+  def test_each_for_left_and_right_projections_executes_block_if_correct_type
+    def side_effect_occurred_on_each(projection)
+      side_effect_occurred = false
+      projection.each { |s| side_effect_occurred = true }
+      side_effect_occurred
+    end
+
+    assert side_effect_occurred_on_each(Left("error").left)
+    assert !side_effect_occurred_on_each(Left("error").right)
+
+    assert side_effect_occurred_on_each(Right(42).right)
+    assert !side_effect_occurred_on_each(Right(42).left)
+  end
+
+  def test_unit_for_left_and_right_projections
+    assert_equal Left("error").left, Either::LeftProjection.unit("error")
+    assert_equal Right(42).right, Either::RightProjection.unit(42)
+  end
+
+  def test_empty_for_left_and_right_projections
+    assert_equal Right(nil).left, Either::LeftProjection.empty
+    assert_equal Left(nil).right, Either::RightProjection.empty
+  end
+
+  def test_monad_axioms_for_left_and_right_projections
+    assert_monad_axiom_1(Either::LeftProjection, "error", lambda { |x| Left(x * 2).left })
+    assert_monad_axiom_2(Left("error").left)
+    assert_monad_axiom_3(Left("error").left, lambda { |x| Left(x * 2).left }, lambda { |x| Left(x * 5).left })
+
+    assert_monad_axiom_1(Either::RightProjection, 42, lambda { |x| Right(x * 2).right })
+    assert_monad_axiom_2(Right(42).right)
+    assert_monad_axiom_3(Right(42).right, lambda { |x| Right(x * 2).right }, lambda { |x| Right(x * 5).right })
+  end
+
+  def test_get_for_left_and_right_projections_returns_value_if_correct_type_or_raises
+    assert_equal "error", Left("error").left.get
+    assert_raises(NoSuchElementError) { Left("error").right.get }
+    assert_equal 42, Right(42).right.get
+    assert_raises(NoSuchElementError) { Right(42).left.get }
+  end
+
+  def test_get_or_else_for_left_and_right_projections_returns_value_if_correct_type_or_returns_value_or_executes_block
+    assert_equal "error", Left("error").left.get_or_else(:other_value)
+    assert_equal :other_value, Left("error").right.get_or_else(:other_value)
+    assert_equal :value_of_block, Left("error").right.get_or_else(lambda { :value_of_block })
+
+    assert_equal 42, Right(42).right.get_or_else(:other_value)
+    assert_equal :other_value, Right(42).left.get_or_else(:other_value)
+    assert_equal :value_of_block, Right(42).left.get_or_else(lambda { :value_of_block })
+  end
+
+  def test_to_opt_for_left_and_right_projections_returns_Some_if_correct_type_or_None
+    assert_equal Some("error"), Left("error").left.to_opt
+    assert_equal None, Left("error").right.to_opt
+    assert_equal Some(42), Right(42).right.to_opt
+    assert_equal None, Right(42).left.to_opt
+  end
+
+  def test_to_a_for_left_and_right_projections_returns_single_element_Array_if_correct_type_or_zero_element_Array
+    assert_equal ["error"], Left("error").left.to_a
+    assert_equal [], Left("error").right.to_a
+    assert_equal [42], Right(42).right.to_a
+    assert_equal [], Right(42).left.to_a
+  end
+
+  def test_map_for_left_and_right_projections_returns_same_projection_type_of_new_value_if_correct_type
+    assert_equal Left(:ERROR), Left("error").left.map { |s| s.upcase.to_sym }
+    assert_equal Left("error"), Left("error").right.map { |s| s.upcase.to_sym }
+    assert_equal Right(420), Right(42).right.map { |s| s * 10 }
+    assert_equal Right(42), Right(42).left.map { |s| s * 10 }
+  end
+
+  def test_to_s_for_left_and_right_and_their_projections
+    assert_equal "Left(error)", Left("error").to_s
+    assert_equal "Right(42)", Right(42).to_s
+    assert_equal "RightProjection(Left(error))", Left("error").right.to_s
+    assert_equal "LeftProjection(Right(42))", Right(42).left.to_s
+  end
 end

metadata

@@ -2,7 +2,7 @@
 name: rumonade
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Marc Siegel
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-13 00:00:00 Z
+date: 2011-10-18 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: test-unit
@@ -42,6 +42,7 @@ files:
 - lib/rumonade.rb
 - lib/rumonade/array.rb
 - lib/rumonade/either.rb
+- lib/rumonade/errors.rb
 - lib/rumonade/lazy_identity.rb
 - lib/rumonade/monad.rb
 - lib/rumonade/option.rb