rumonade 0.1.1 → 0.1.2

data/.gitignore

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

data/CHANGELOG.rdoc

@@ -1,3 +1,8 @@
+=== 0.1.2 / 2011-10-12
+
+* Progress towards Either
+  * changed documentation to yard from rdoc
+
 === 0.1.1 / 2011-09-19
 
 * Maintenance

data/README.rdoc

@@ -1,5 +1,9 @@
 = Rumonade[https://rubygems.org/gems/rumonade]
 
+Project: github[http://github.com/ms-ati/rumonade]
+
+Documentation: rubydoc.info[http://rubydoc.info/gems/rumonade/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]
 
 Are you working in both the Scala[http://www.scala-lang.org] and Ruby[http://www.ruby-lang.org] worlds,
@@ -8,11 +12,11 @@ monads[http://james-iry.blogspot.com/2007/09/monads-are-elephants-part-1.html] i
 Then Rumonade is for you.
 
 The goal of this library is to make the most common and useful Scala monadic idioms available in Ruby via the following classes:
-* Rumonade::Option
-* Array
-* Either
-* Hash
-* (more TBD)
+* {Rumonade::Option Option}
+* {Rumonade::ArrayExtensions Array}
+* {Rumonade::Either Either}
+* Hash -- _coming_ _soon!_
+* (_more_ _TBD_)
 
 Syntactic support for scala-like for-comprehensions[http://www.scala-lang.org/node/111] will be implemented
 as a sequence of calls to #flat_map, #select, etc, modelling Scala's
@@ -24,23 +28,27 @@ results. If this proves useful (and a good fit for Ruby), then more narrow funct
 
 == Usage
 
-You can transform possibly nil values in a functional fashion, which many find more clear and elegant:
-
-  require 'date'
-  require 'time'
-  require 'rumonade'
+Using Option, one can transform _possibly_ _nil_ values in a _functional_ fashion, which can increase clarity while
+eliminating opportunities for bugs:
 
   def format_date_in_march(time_or_date_or_nil)
-    Option(time_or_date_or_nil).
-        map(&:to_date).select {|d| d.month == 3}.
-        map(&:to_s).map {|s| s.gsub('-', '')}.get_or_else("not in march!")
+    Option(time_or_date_or_nil).      # wraps possibly-nil value in an Option monad (Some or None)
+        map(&:to_date).               # transforms a contained Time value into a Date value
+        select {|d| d.month == 3}.    # filters out non-matching Date values (Some becomes None)
+        map(&:to_s).                  # transforms a contained Date value into a String value
+        map {|s| s.gsub('-', '')}.    # transforms a contained String value by removing '-'
+        get_or_else("not in march!")  # returns the contained value, or the alternative if None
   end
 
   format_date_in_march(nil)                            # => "not in march!"
-  format_date_in_march(Time.parse('2011-01-01 12:34')) # => "not in march!"
+  format_date_in_march(Time.parse('2009-01-01 01:02')) # => "not in march!"
   format_date_in_march(Time.parse('2011-03-21 12:34')) # => "20110321"
 
-(more examples coming soon...)
+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
+
+(_more_ _examples_ _coming_ _soon_...)
 
 == Approach
 
@@ -54,7 +62,7 @@ Rumonade wants to be a practical drop-in Monad solution that will fit well into
 
 The priorities for Rumonade are:
 1. Practical usability in day-to-day Ruby
-   * <b>don't</b> mess up normal idioms of the language (e.g., Array#map)
+   * <b>don't</b> mess up normal idioms of the language (e.g., Hash#map)
    * <b>don't</b> slow down normal idioms of the language (e.g., Array#map)
 2. Rubyish-ness of usage
    * Monad is a mix-in, requiring methods self.unit and #bind be implemented by target classes

data/Rakefile

@@ -5,21 +5,3 @@ Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/*_test.rb'
 end
-
-#require "rdoc/task"
-#RDoc::Task.new do |rdoc|
-#  rdoc.main = "README.rdoc"
-#  rdoc.rdoc_files.include("README.rdoc", "CHANGELOG.rdoc", "lib/**/*.rb")
-#end
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  require File.expand_path("../lib/rumonade/version", __FILE__)
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.title = "Rumonade #{Rumonade::VERSION}"
-  rdoc.main = 'README.rdoc'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('CHANGELOG.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end

data/lib/rumonade.rb

@@ -25,6 +25,7 @@ require "rumonade/monad"
 require "rumonade/lazy_identity"
 require "rumonade/option"
 require "rumonade/array"
+require "rumonade/either"
 
 # = Rumonade
 #

data/lib/rumonade/array.rb

@@ -1,6 +1,7 @@
 require 'rumonade/monad'
 
 module Rumonade
+  # TODO: Document use of Array as a Monad
   module ArrayExtensions
     module ClassMethods
       def unit(value)
@@ -14,8 +15,7 @@ module Rumonade
 
     module InstanceMethods
       def bind(lam = nil, &blk)
-        f = lam || blk
-        inject([]) { |arr, elt| arr + f.call(elt).to_a }
+        inject(self.class.empty) { |arr, elt| arr + (lam || blk).call(elt).to_a }
       end
     end
   end

data/lib/rumonade/either.rb

@@ -0,0 +1,134 @@
+require 'singleton'
+require 'rumonade/monad'
+
+module Rumonade
+  # Represents a value of one of two possible types (a disjoint union).
+  # The data constructors {Rumonade::Left} and {Rumonade::Right} represent the two possible values.
+  # The +Either+ type is often used as an alternative to {Rumonade::Option} where {Rumonade::Left} represents
+  # failure (by convention) and {Rumonade::Right} is akin to {Rumonade::Some}.
+  # @abstract
+  class Either
+    def initialize
+      raise(TypeError, "class Either is abstract; cannot be instantiated") if self.class == Either
+    end
+    private :initialize
+
+    # @return [Boolean] Returns +true+ if this is a {Rumonade::Left}, +false+ otherwise.
+    def left?
+      is_a?(Left)
+    end
+
+    # @return [Boolean] Returns +true+ if this is a {Rumonade::Right}, +false+ otherwise.
+    def right?
+      is_a?(Right)
+    end
+
+    # @return [Boolean] If this is a Left, then return the left value in Right or vice versa.
+    def swap
+      if left? then Right(left_value) else Left(right_value) end
+    end
+
+    # @param [Proc] function_of_left_value the function to apply if this is a Left
+    # @param [Proc] function_of_right_value the function to apply if this is a Right
+    # @return Returns the results of applying the function
+    def fold(function_of_left_value, function_of_right_value)
+      if left? then function_of_left_value.call(left_value) else function_of_right_value.call(right_value) end
+    end
+
+    # @return [LeftProjection] Projects this Either as a Left.
+    def left
+      LeftProjection.new(self)
+    end
+
+    # @return [RightProjection] Projects this Either as a Right.
+    def right
+      RightProjection.new(self)
+    end
+  end
+
+  # The left side of the disjoint union, as opposed to the Right side.
+  class Left < Either
+    # @param left_value the value to store in a +Left+, usually representing a failure result
+    def initialize(left_value)
+      @left_value = left_value
+    end
+
+    # @return Returns the left value
+    attr_reader :left_value
+
+    # @return [Boolean] Returns +true+ if other is a +Left+ with an equal left value
+    def ==(other)
+      other.is_a?(Left) && other.left_value == self.left_value
+    end
+  end
+
+  # The right side of the disjoint union, as opposed to the Left side.
+  class Right < Either
+    # @param right_value the value to store in a +Right+, usually representing a success result
+    def initialize(right_value)
+      @right_value = right_value
+    end
+
+    # @return Returns the right value
+    attr_reader :right_value
+
+    # @return [Boolean] Returns +true+ if other is a +Right+ with an equal right value
+    def ==(other)
+      other.is_a?(Right) && other.right_value == self.right_value
+    end
+  end
+
+  # @param (see Left#initialize)
+  # @return [Left]
+  def Left(left_value)
+    Left.new(left_value)
+  end
+
+  # @param (see Right#initialize)
+  # @return [Right]
+  def Right(right_value)
+    Right.new(right_value)
+  end
+
+  class Either
+    # Projects an Either into a Left.
+    class LeftProjection
+      # @param either_value [Object] the Either value to project
+      def initialize(either_value)
+        @either_value = either_value
+      end
+
+      # @return Returns the Either value
+      attr_reader :either_value
+
+      def ==(other)
+        other.is_a?(LeftProjection) && other.either_value == self.either_value
+      end
+
+      def bind(lam = nil, &blk)
+        !either_value.left? ? either_value : (lam || blk).call(either_value.left_value)
+      end
+      alias_method :flat_map, :bind
+    end
+
+    # Projects an Either into a Right.
+    class RightProjection
+      # @param either_value [Object] the Either value to project
+      def initialize(either_value)
+        @either_value = either_value
+      end
+
+      # @return Returns the Either value
+      attr_reader :either_value
+
+      def ==(other)
+        other.is_a?(RightProjection) && other.either_value == self.either_value
+      end
+
+      def bind(lam = nil, &blk)
+        !either_value.right? ? either_value : (lam || blk).call(either_value.right_value)
+      end
+      alias_method :flat_map, :bind
+    end
+  end
+end

data/lib/rumonade/version.rb

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

data/rumonade.gemspec

@@ -19,7 +19,6 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   # specify any dependencies here; for example:
-  #s.add_development_dependency "rdoc"
-  #s.add_development_dependency "test-unit"
+  s.add_development_dependency "test-unit"
   #s.add_development_dependency "rr"
 end

data/test/either_test.rb

@@ -0,0 +1,53 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+class EitherTest < Test::Unit::TestCase
+  include Rumonade
+  include MonadAxiomTestHelpers
+
+  def test_when_either_constructor_raises
+    assert_raise(TypeError) { Either.new }
+  end
+
+  def test_when_left_or_right_returns_new_left_or_right
+    assert_equal Left.new("error"), Left("error")
+    assert_equal Right.new(42), Right(42)
+  end
+
+  def test_predicates_for_left_and_right
+    assert Left("error").left?
+    assert !Right(42).left?
+    assert Right(42).right?
+    assert !Left("error").right?
+  end
+
+  def test_swap_for_left_and_right
+    assert_equal Left(42), Right(42).swap
+    assert_equal Right("error"), Left("error").swap
+  end
+
+  def test_fold_for_left_and_right
+    times_two = lambda { |v| v * 2 }
+    times_ten = lambda { |v| v * 10 }
+    assert_equal "errorerror", Left("error").fold(times_two, times_ten)
+    assert_equal 420, Right(42).fold(times_two, times_ten)
+  end
+
+  def test_projections_for_left_and_right
+    assert_equal Either::LeftProjection.new(Left("error")), Left("error").left
+    assert_equal Either::RightProjection.new(Left("error")), Left("error").right
+    assert_equal Either::LeftProjection.new(Right(42)), Right(42).left
+    assert_equal Either::RightProjection.new(Right(42)), Right(42).right
+
+    assert_not_equal Either::LeftProjection.new(Left("error")), Left("error").right
+    assert_not_equal Either::RightProjection.new(Left("error")), Left("error").left
+    assert_not_equal Either::LeftProjection.new(Right(42)), Right(42).right
+    assert_not_equal Either::RightProjection.new(Right(42)), Right(42).left
+  end
+
+  def test_flat_map_for_left_and_right_projections_returns_eithers
+    assert_equal Left("42"), Right(42).right.flat_map { |n| Left(n.to_s) }
+    assert_equal Right(42), Right(42).left.flat_map { |n| Left(n.to_s) }
+    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
+end

data/test/test_helper.rb

@@ -1,7 +1,6 @@
 $:.unshift(File.dirname(File.dirname(File.expand_path(__FILE__))) + '/lib')
 require "rubygems"
 require "test/unit"
-require "rr"
 require "rumonade"
 
 # see http://stackoverflow.com/questions/2709361/monad-equivalent-in-ruby

metadata

@@ -2,7 +2,7 @@
 name: rumonade
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Marc Siegel
@@ -10,9 +10,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-20 00:00:00 Z
-dependencies: []
-
+date: 2011-10-13 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
 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: 
 - marc@usainnov.com
@@ -31,12 +41,14 @@ files:
 - Rakefile
 - lib/rumonade.rb
 - lib/rumonade/array.rb
+- lib/rumonade/either.rb
 - lib/rumonade/lazy_identity.rb
 - lib/rumonade/monad.rb
 - lib/rumonade/option.rb
 - lib/rumonade/version.rb
 - rumonade.gemspec
 - test/array_test.rb
+- test/either_test.rb
 - test/lazy_identity_test.rb
 - test/option_test.rb
 - test/test_helper.rb
@@ -69,6 +81,7 @@ specification_version: 3
 summary: A Scala-inspired Monad library for Ruby
 test_files: 
 - test/array_test.rb
+- test/either_test.rb
 - test/lazy_identity_test.rb
 - test/option_test.rb
 - test/test_helper.rb