rumonade 0.2.2 → 0.3.0

data/.gitignore

@@ -6,4 +6,5 @@ pkg/*
 html
 rdoc
 .yardoc
+doc
 

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.2

data/HISTORY.md

@@ -1,5 +1,10 @@
 # HISTORY
 
+## v0.3.0 (Apr 29, 2012)
+
+  - added Either#lift_to_a (and #lift)
+  - See full list @ https://github.com/ms-ati/rumonade/compare/v0.2.2...v0.3.0
+
 ## v0.2.2 (Apr 26, 2012)
 
   - added Either#+ to allow combining validations

data/README.rdoc

@@ -1,8 +1,10 @@
+{<img src="https://secure.travis-ci.org/ms-ati/rumonade.png?branch=master" alt="Build Status" />}[http://travis-ci.org/ms-ati/rumonade]
+
 = Rumonade[https://rubygems.org/gems/rumonade]
 
 Project: github[http://github.com/ms-ati/rumonade]
 
-Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/0.2.1/file/README.rdoc]
+Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/frames]
 
 == 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]
 
@@ -28,8 +30,7 @@ results. If this proves useful (and a good fit for Ruby), then more narrow funct
 
 == Usage
 
-Using Option, one can transform _possibly_ _nil_ values in a _functional_ fashion, which can increase clarity while
-eliminating opportunities for bugs:
+==== {Rumonade::Option Option}: handle _possibly_ _nil_ values in a _functional_ fashion:
 
   def format_date_in_march(time_or_date_or_nil)
     Option(time_or_date_or_nil).      # wraps possibly-nil value in an Option monad (Some or None)
@@ -48,6 +49,36 @@ Note:
 * each step of the chained computations above are functionally isolated
 * the value can notionally _start_ as nil, or _become_ nil during a computation, without effecting any other chained computations
 
+==== {Rumonade::Either Either}: handle failures ({Rumonade::Left Left}) and successes ({Rumonade::Right Right}) in a _functional_ fashion:
+
+  def find_person(name)
+    case name
+      when /Jack/i, /John/i
+        Right(name.capitalize)
+      else
+        Left("No such person: #{name.capitalize}")
+    end
+  end
+
+  # success looks like this:
+  find_person("Jack")
+  # => Right("Jack")
+
+  # failure looks like this:
+  find_person("Jill")
+  # => Left("No such person: Jill")
+
+  # on the 'happy path', we can functionally combine and transform successes:
+  (find_person("Jack").lift_to_a + find_person("John").lift_to_a).right.map { |*names| names.join(" and ") }
+  # => Right("Jack and John")
+
+  # while the failure cases are easily handled as well:
+  (find_person("Jack").lift_to_a +
+   find_person("John").lift_to_a +
+   find_person("Jill").lift_to_a +
+   find_person("Joan").lift_to_a).right.map { |*names| names.join(" and ") }
+  # => Left("No such person: Jill", "No such person: Joan")
+
 (_more_ _examples_ _coming_ _soon_...)
 
 == Approach

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 
+task :default => [:test]
+
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/*_test.rb'

data/lib/rumonade/either.rb

@@ -44,14 +44,47 @@ module Rumonade
       RightProjection.new(self)
     end
 
-    # @param [Either] other the either to combine with
-    # @return [Either] Returns a +Left+ with all Left values (if any), otherwise a +Right+ with all Right values
-    def +(other)
-      if [self, other].any?(&:left?)
-        Left([self, other].map { |either| either.left.to_opt }.flatten)
-      else
-        Right([self, other].map { |either| either.right.to_opt }.flatten)
-      end
+    # Default concatenation function used by {#+}
+    DEFAULT_CONCAT = lambda { |a,b| a + b }
+
+    # @param [Either] other the other +Either+ to concatenate
+    # @param [Hash] opts the options to concatenate with
+    # @option opts [Proc] :concat_left (DEFAULT_CONCAT) The function to concatenate +Left+ values
+    # @option opts [Proc] :concat_right (DEFAULT_CONCAT) the function to concatenate +Right+ values
+    # @yield [right_value] optional block to transform concatenated +Right+ values
+    # @yieldparam [Object] right_values the concatenated +Right+ values yielded to optional block
+    # @return [Either] if both are +Right+, returns +Right+ with +right_value+'s concatenated,
+    #                  otherwise a +Left+ with +left_value+'s concatenated
+    def +(other, opts = {})
+      opts = { :concat_left  => DEFAULT_CONCAT, :concat_right => DEFAULT_CONCAT }.merge(opts)
+      result =
+        case self
+          when Left
+            case other
+              when Left then Left(opts[:concat_left].call(self.left_value, other.left_value))
+              when Right then Left(self.left_value)
+            end
+          when Right
+            case other
+              when Left then Left(other.left_value)
+              when Right then Right(opts[:concat_right].call(self.right_value, other.right_value))
+            end
+        end
+      if block_given? then result.right.map { |right_values| yield right_values } else result end
+    end
+    alias_method :concat, :+
+
+    # @return [Either] returns an +Either+ of the same type, with the +left_value+ or +right_value+
+    #                  lifted into an +Array+
+    def lift_to_a
+      lift(Array)
+    end
+
+    # @param [#unit] monad_class the {Monad} to lift the +Left+ or +Right+ value into
+    # @return [Either] returns an +Either+of the same type, with the +left_value+ or +right_value+
+    #                  lifted into +monad_class+
+    def lift(monad_class)
+      fold(lambda {|l| Left(monad_class.unit(l)) }, lambda {|r| Right(monad_class.unit(r))})
     end
   end
 
@@ -74,6 +107,11 @@ module Rumonade
     def to_s
       "Left(#{left_value})"
     end
+
+    # @return [String] Returns a +String+ containing a human-readable representation of this object.
+    def inspect
+      "Left(#{left_value.inspect})"
+    end
   end
 
   # The right side of the disjoint union, as opposed to the Left side.
@@ -95,6 +133,11 @@ module Rumonade
     def to_s
       "Right(#{right_value})"
     end
+
+    # @return [String] Returns a +String+ containing a human-readable representation of this object.
+    def inspect
+      "Right(#{right_value.inspect})"
+    end
   end
 
   # @param (see Left#initialize)
@@ -184,6 +227,11 @@ module Rumonade
       def to_s
         "LeftProjection(#{either_value})"
       end
+
+      # @return [String] Returns a +String+ containing a human-readable representation of this object.
+      def inspect
+        "LeftProjection(#{either_value.inspect})"
+      end
     end
 
     # Projects an Either into a Right.
@@ -260,6 +308,11 @@ module Rumonade
       def to_s
         "RightProjection(#{either_value})"
       end
+
+      # @return [String] Returns a +String+ containing a human-readable representation of this object.
+      def inspect
+        "RightProjection(#{either_value.inspect})"
+      end
     end
   end
 end

data/lib/rumonade/version.rb

@@ -1,3 +1,3 @@
 module Rumonade
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/rumonade.gemspec

@@ -20,5 +20,5 @@ Gem::Specification.new do |s|
 
   # specify any dependencies here; for example:
   s.add_development_dependency "test-unit"
-  #s.add_development_dependency "rr"
+  s.add_development_dependency "rake"
 end

data/test/either_test.rb

@@ -160,8 +160,44 @@ class EitherTest < Test::Unit::TestCase
     assert_equal "LeftProjection(Right(42))", Right(42).left.to_s
   end
 
-  def test_plus_for_left_and_right
-    assert_equal Left(["bad", "worse"]), Left("bad") + Right(:good) + Left("worse") + Right(:good)
-    assert_equal Right([:good, :better]), Right(:good) + Right(:better)
+  def test_inspect_for_left_and_right_and_their_projections
+    assert_equal "Left(\"error\")", Left("error").inspect
+    assert_equal "Right(\"success\")", Right("success").inspect
+    assert_equal "RightProjection(Left(\"error\"))", Left("error").right.inspect
+    assert_equal "LeftProjection(Right(\"success\"))", Right("success").left.inspect
+  end
+
+  def test_plus_concatenates_left_and_right_using_plus_operator
+    assert_equal Left("badworse"), Left("bad") + Right(1) + Left("worse") + Right(2)
+    assert_equal Left(["bad", "worse"]), Left(["bad"]) + Right(1) + Left(["worse"]) + Right(2)
+    assert_equal Right(3), Right(1) + Right(2)
+  end
+
+  def test_concat_concatenates_left_and_right_with_custom_concatenation_function
+    multiply = lambda { |a, b| a * b }
+    assert_equal Left(33), Left(3).concat(Left(11), :concat_left => multiply)
+    assert_equal Left(14), Left(3).concat(Left(11), :concat_right => multiply)
+    assert_equal Right(44), Right(4).concat(Right(11), :concat_right => multiply)
+    assert_equal Right(15), Right(4).concat(Right(11), :concat_left => multiply)
+  end
+
+  def test_lift_to_a_wraps_left_and_right_values_in_array
+    assert_equal Left(["error"]), Left("error").lift_to_a
+    assert_equal Right([42]), Right(42).lift_to_a
+  end
+
+  def test_plus_and_lift_to_a_work_together_to_concatenate_errors
+    assert_equal Left([1, 2]), Left(1).lift_to_a + Right(:a).lift_to_a + Left(2).lift_to_a + Right(:b).lift_to_a
+    assert_equal Right([:a, :b]), Right(:a).lift_to_a + Right(:b).lift_to_a
+  end
+
+  Person = Struct.new(:name, :age, :address)
+
+  def test_concat_maps_concatenated_right_values_through_a_block
+    assert_equal Right(Person.new("Joe", 23, ["123 Some St", "Boston"])),
+                 Right(["Joe"]).concat(Right([23])).concat(Right([["123 Some St", "Boston"]])) { |n, a, addr| Person.new(n, a, addr) }
+    # this usage is equivalent, but since ruby can't pass a block to a binary operator, must use .right.map on result:
+    assert_equal Right(Person.new("Joe", 23, ["123 Some St", "Boston"])),
+                 (Right(["Joe"]) + Right([23]) + Right([["123 Some St", "Boston"]])).right.map { |n, a, addr| Person.new(n, a, addr) }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rumonade
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-27 00:00:00.000000000 Z
+date: 2012-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -27,6 +27,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Scala-inspired Monad library for Ruby, aiming to share the most common
   idioms for folks working in both languages. Includes Option, Array, etc.
 email:
@@ -36,6 +52,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .travis.yml
 - Gemfile
 - HISTORY.md
 - MIT-LICENSE.txt