monadic 0.1.1 → 0.2.0

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.2.0 (not released)
+**BREAKING CHANGES**
+
+`Monad#map` does not recognize `Enumerables` automatically anymore. It just maps, as a `Functor`.  
+Instead the new `Monad#flat_map` function operates on the underlying value as on `Enumerable`.
+
+`Either#else` allows to exchange the inner value of  `Nothing` to an alternative value.
+
+    Either(false == true).else('false was not true')          == Failure(false was not true)
+    Success('truth needs no sugar coating').else('all lies')  == Success('truth needs no sugar coating')
+
 ## v0.1.1
 
 `Either()` coerces only `StandardError` to `Failure`, other exceptions higher in the hierarchy are will break the flow.  

data/README.md

@@ -64,12 +64,17 @@ Map, select:
 ```ruby    
 Maybe(123).map   { |value| User.find(value) } == Just(someUser)      # if user found
 Maybe(0).map     { |value| User.find(value) } == Nothing             # if user not found
-Maybe([1,2]).map { |value| value.to_s }       == Just(["1", "2"])    # for all Enumerables
+Maybe([1,2]).map { |value| value.to_s }       == Just(["1, 2"])      # for all Enumerables
 
 Maybe('foo').select { |value| value.start_with?('f') } == Just('foo')
 Maybe('bar').select { |value| value.start_with?('f') } == Nothing
 ```
 
+For `Enumerable` use `#flat_map`:
+```ruby
+Maybe([1, 2]).flat_map {|v| v + 1 }           == Just([2, 3])
+```
+
 Treat it like an array:
 
 ```ruby
@@ -137,7 +142,7 @@ What is specific to this implementation is that exceptions are caught within the
 `Success` represents a successfull execution of an operation (Right in Scala, Haskell).  
 `Failure` represents a failure to execute an operation (Left in Scala, Haskell).  
 
-The `Either()` wrapper will treat all falsey values `nil`, `false` or `empty?` as a `Failure` and all others as `Success`. If that does not suit you, use `Success` or `Failure` only.
+The `Either()` wrapper works like a coercon. It will treat all falsey values `nil`, `false` or `empty?` as a `Failure` and all others as `Success`. If that does not suit you, use `Success` or `Failure` only. However as ruby cannot enforce the value returned from within a bind, it will auto-magically coerce the return value into an `Either`.
 
 ```ruby
 result = parse_and_validate_params(params).                 # must return a Success or Failure inside
@@ -192,6 +197,13 @@ Success(params).
   bind ->(path)     { load_stuff(params)          }        # 
 ```
 
+`Either#else` allows to provide alternate values in case of `Failure`:
+
+```ruby
+Either(false == true).else('false was not true')          == Failure(false was not true)
+Success('truth needs no sugar coating').else('all lies')  == Success('truth needs no sugar coating')
+```
+
 Storing intermediate results in instance variables is possible, although it is not very elegant:
 
 ```ruby
@@ -247,13 +259,21 @@ The above example, returns either `Success([32, :sober, :male])` or `Failure(['A
 See also [examples/validation.rb](https://github.com/pzol/monadic/blob/master/examples/validation.rb) and [examples/validation_module](https://github.com/pzol/monadic/blob/master/examples/validation_module.rb) 
 
 ### Monad 
-All Monads inherit from this class. Standalone it is an Identity monad. Not useful on its own. It's methods are usable on all its descendants.
+All Monads include this module. Standalone it is an Identity monad. Not useful on its own. It's methods are usable on all its descendants.
 
 __#map__ is used to map the inner value
 
 ```ruby
-Monad.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Monad(Hello Foo)
-Monad.unit([1,2]).map {|v| v + 1}                             == Monad([2, 3])
+# minimum implementation of a monad
+class Identity 
+  include Monadic::Monad
+  def self.unit(value)
+    new(value)
+  end
+end
+
+Identity.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Identity(Hello Foo)
+Identity.unit([1,2]).map {|v| v + 1}                             == Identity([2, 3])
 ```
 
 __#bind__ allows (priviledged) access to the boxed value. This is the traditional _no-magic_ `#bind` as found in Haskell, 
@@ -262,16 +282,16 @@ You` are responsible for re-wrapping the value into a Monad again.
 ```ruby  
 # due to the way it works, it will simply return the value, don't rely on this though, different Monads may
 # implement bind differently (e.g. Maybe involves some _magic_)
-Monad.unit('foo').bind(&:capitalize)                          == Foo
+Identity.unit('foo').bind(&:capitalize)                          == Foo
 
 # proper use
-Monad.unit('foo').bind {|v| Monad.unit(v.capitalize) }        == Monad(Foo)
+Identity.unit('foo').bind {|v| Identity.unit(v.capitalize) }     == Identity(Foo)
 ```
 
 __#fetch__ extracts the inner value of the Monad, some Monads will override this standard behaviour, e.g. the Maybe Monad
 
 ```ruby
-Monad.unit('foo').fetch                                       == "foo"
+Identity.unit('foo').fetch                                       == "foo"
 ```
 
 ## References

data/lib/monadic/either.rb

@@ -32,6 +32,13 @@ module Monadic
     alias :>=  :bind
     alias :+   :bind
 
+    # If it is a Failure it will return a new Failure with the provided value
+    # @return [Success, Failure] 
+    def else(value)
+      return Failure(value) if failure?
+      return self
+    end
+
     def fetch(default=@value)
       return default if failure?
       return @value

data/lib/monadic/maybe.rb

@@ -18,8 +18,9 @@ module Monadic
 
     # @return [Failure, Success] the Maybe Monad filtered with the block or proc expression
     def select(proc = nil, &block)
-      return Maybe(@value.select(&block)) if @value.is_a?(::Enumerable)
-      return Nothing unless (proc || block).call(@value)
+      func = (proc || block)
+      return Maybe(@value.select {|v| func.call(v) }) if @value.respond_to? :select
+      return Nothing unless func.call(@value)
       return self
     end
 

data/lib/monadic/monad.rb

@@ -23,15 +23,19 @@ module Monadic
     end
     alias :_ :fetch
 
-    # A functor applying the proc or block on the boxed `value` and returning the Monad with the transformed values.
-    # If the underlying `value` is an `Enumerable`, the map is applied on each element of the collection.
+    # A Functor applying the proc or block on the boxed `value` and returning the Monad with the transformed values.
     # (A -> B) -> M[A] -> M[B]
     def map(proc = nil, &block)
       func = (proc || block)
-      return self.class.unit(@value.map {|v| func.call(v) }) if @value.is_a?(::Enumerable)
       return self.class.unit(func.call(@value))
     end
 
+    def flat_map(proc = nil, &block)
+      fail "Underlying value does not respond to #map" unless @value.respond_to? :map
+      func = (proc || block)
+      return self.class.unit(@value.map {|v| func.call(v) }) if @value.respond_to? :map
+    end
+
     # @return [Array] a with the values inside the monad
     def to_ary
       Array(@value)

data/lib/monadic/version.rb

@@ -1,3 +1,3 @@
 module Monadic
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/spec/either_spec.rb

@@ -53,6 +53,14 @@ describe Monadic::Either do
     error.message.should == 'error'
   end
 
+  it '#else returns an alternative value considered Success if it is Nothing' do
+    Failure(false).else(true).should == Failure(true)
+    Either(nil).else(true).should == Failure(true)
+    Success(true).else(false).should == Success(true)
+    Either(true).else(false).should == Success(true)
+    Success(false).else(true).should == Success(false)
+  end
+
   class User
     attr :age, :gender, :sobriety
     def self.find(id)

data/spec/maybe_spec.rb

@@ -105,7 +105,7 @@ describe Monadic::Maybe do
   it 'allows to use map' do
     Maybe(nil).map { |e| Hash.new(:key => e) }.should == Nothing
     Maybe('foo').map { |e| Hash.new(:key => e) }.should == Just(Hash.new(:key => 'foo'))
-    Maybe([1,2]).map { |e| e.to_s }.should == Just(["1", "2"])
+    Maybe([1,2]).map { |e| e.to_s }.should == Just("[1, 2]")
   end
 
   it 'allows to use select' do

data/spec/monad_axioms.rb

@@ -34,24 +34,5 @@ shared_examples 'a Monad' do
       id1.should == id2
     end
   end
-
-  describe '#map functor' do
-    add100 = ->(value) { value + 100 }
-    it 'on value types, returns the transformed value, wrapped in the Monad' do
-      res = monad.unit(1).map {|v| add100.(v) }
-      res.should == monad.unit(101)
-
-      res = monad.unit(1).map {|v| monad.unit(v + 100) }
-      res.should == monad.unit(101)
-    end
-
-    it 'on enumerables, returns the transformed collection, wrapped in the Monad' do
-      res = monad.unit([1,2,3]).map {|v| add100.(v) }
-      res.should == monad.unit([101,102,103])
-
-      # The following does not work... not sure whether it should
-      # res = monad.unit([1,2,3]).map {|v| monad.unit(v + 100) }
-      # res.should == monad.unit([101,102,103])
-    end
-  end
 end
+

data/spec/monad_spec.rb

@@ -15,27 +15,27 @@ describe Monadic::Monad do
   it '#to_s shows the monad name and its value' do
     Identity.unit(1).to_s.should == 'Identity(1)'
     Identity.unit(nil).to_s.should == 'Identity(nil)'
-    Identity.unit([1, 2]).map(&:to_s).should == Identity.unit(["1", "2"])
+    Identity.unit([1, 2]).map(&:to_s).should == Identity.unit("[1, 2]")
 
     # can be done also
     Identity.unit([1, 2]).bind {|v| Identity.unit(v.map(&:to_s)) }.should == Identity.unit(["1", "2"])
   end
 
-  describe '#map' do
-    it 'applies the function to the underlying value directly' do
-      Identity.unit(1).map {|v| v + 2}.should == Identity.unit(3)
-      Identity.unit('foo').map(&:upcase).should == Identity.unit('FOO')
-    end
+  it '#map applies the function to the underlying value directly' do
+    Identity.unit(1).map {|v| v + 2}.should == Identity.unit(3)
+    Identity.unit('foo').map(&:upcase).should == Identity.unit('FOO')
+  end
 
-    it 'delegates #map to an underlying collection and wraps the resulting collection' do
-      Identity.unit([1,2]).map {|v| v + 1}.should == Identity.unit([2, 3])
-      Identity.unit(['foo', 'bar']).map(&:upcase).should == Identity.unit(['FOO', 'BAR'])
-    end
+  it 'delegates #flat_map to an underlying collection and wraps the resulting collection' do
+    Identity.unit([1,2]).flat_map {|v| v + 1}.should == Identity.unit([2, 3])
+    Identity.unit(['foo', 'bar']).flat_map(&:upcase).should == Identity.unit(['FOO', 'BAR'])
+    expect { Identity.unit(1).flat_map {|v| v + 1 } }.to raise_error(RuntimeError)
   end
 
-  describe '#to_ary #to_a' do
+  it '#to_ary #to_a' do
     Identity.unit([1, 2]).to_a.should == [1, 2]
     Identity.unit(nil).to_a.should == []
     Identity.unit('foo').to_a.should == ['foo']
   end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-08 00:00:00.000000000 Z
+date: 2012-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec