monadic 0.1.0 → 0.1.1

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.1.1
+
+`Either()` coerces only `StandardError` to `Failure`, other exceptions higher in the hierarchy are will break the flow.  
+Thanks to @pithyless for the suggestion. 
+
+Monad is now a Module instead of a Class as previously. This fits the Monad metaphor better. Each monad must now implement the unit method itself, which is the correct way to do anyway.
+
+
 ## v0.1.0
 
 You can now chain Eithers with `+` without providing a block or a proc:
@@ -12,7 +20,10 @@ All monads now have the `#to_ary` and `#to_a` method, which coerces the inner va
 I am considering the Api now almost stable, the only thing I am not so sure about, 
 is whether to apply the magic coercion or not.
 
-`Validation()` now returns the successfully validated values. See examples/validation.rb
+`Validation()` now returns the successfully validated values.
+See [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)
+
 
 ## v0.0.7 
 

data/README.md

@@ -23,61 +23,72 @@ Most people probably will be interested in the Maybe monad, as it solves the pro
 
 Maybe is an optional type, which helps to handle error conditions gracefully. The one thing to remember about option is: 'What goes into the Maybe, stays in the Maybe'. 
 
-    Maybe(User.find(123)).name._         # ._ is a shortcut for .fetch 
 
-    # if you prefer the alias Maybe instead of option
-    Maybe(User.find(123)).name._
+```ruby
+Maybe(User.find(123)).name._         # ._ is a shortcut for .fetch 
 
-    # confidently diving into nested hashes
-    Maybe({})[:a][:b][:c]                   == Nothing
-    Maybe({})[:a][:b][:c].fetch('unknown')  == "unknown"
-    Maybe(a: 1)[:a]._                       == 1
+# if you prefer the alias Maybe instead of option
+Maybe(User.find(123)).name._
+
+# confidently diving into nested hashes
+Maybe({})[:a][:b][:c]                   == Nothing
+Maybe({})[:a][:b][:c].fetch('unknown')  == "unknown"
+Maybe(a: 1)[:a]._                       == 1
+```
 
 Basic usage examples:
 
-    # handling nil (None serves as NullObject)
-    Maybe(nil).a.b.c            == Nothing
-
-    # Nothing
-    Maybe(nil)._                == Nothing
-    "#{Maybe(nil)}"             == "Nothing"
-    Maybe(nil)._("unknown")     == "unknown"
-    Maybe(nil).empty?           == true
-    Maybe(nil).truly?           == false
-
-    # Just stays Just, unless you unbox it
-    Maybe('FOO').downcase       == Just('foo') 
-    Maybe('FOO').downcase.fetch == "foo"          # unboxing the value
-    Maybe('FOO').downcase._     == "foo"          
-    Maybe('foo').empty?         == false          # always non-empty
-    Maybe('foo').truly?         == true           # depends on the boxed value
-    Maybe(false).empty?         == false
-    Maybe(false).truly?         == false
+```ruby
+# handling nil (None serves as NullObject)
+Maybe(nil).a.b.c            == Nothing
+
+# Nothing
+Maybe(nil)._                == Nothing
+"#{Maybe(nil)}"             == "Nothing"
+Maybe(nil)._("unknown")     == "unknown"
+Maybe(nil).empty?           == true
+Maybe(nil).truly?           == false
+
+# Just stays Just, unless you unbox it
+Maybe('FOO').downcase       == Just('foo') 
+Maybe('FOO').downcase.fetch == "foo"          # unboxing the value
+Maybe('FOO').downcase._     == "foo"          
+Maybe('foo').empty?         == false          # always non-empty
+Maybe('foo').truly?         == true           # depends on the boxed value
+Maybe(false).empty?         == false
+Maybe(false).truly?         == false
+```
 
 Map, select:
     
-    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
+```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('foo').select { |value| value.start_with?('f') } == Just('foo')
-    Maybe('bar').select { |value| value.start_with?('f') } == Nothing
+Maybe('foo').select { |value| value.start_with?('f') } == Just('foo')
+Maybe('bar').select { |value| value.start_with?('f') } == Nothing
+```
 
 Treat it like an array:
 
-    Maybe(123).to_a          == [123]
-    Maybe([123, 456]).to_a   == [123, 456]
-    Maybe(nil).to_a          == []
+```ruby
+ Maybe(123).to_a          == [123]
+ Maybe([123, 456]).to_a   == [123, 456]
+ Maybe(nil).to_a          == []
+```
 
 Falsey values (kind-of) examples:
 
-    user = Maybe(User.find(123))
-    user.name._
+```ruby
+user = Maybe(User.find(123))
+user.name._
 
-    user.subscribed?              # always true
-    user.subscribed?.truly?       # true if subscribed is true
-    user.subscribed?.fetch(false) # same as above
-    user.subscribed?.or(false)    # same as above
+user.subscribed?              # always true
+user.subscribed?.truly?       # true if subscribed is true
+user.subscribed?.fetch(false) # same as above
+user.subscribed?.or(false)    # same as above
+```
 
 Remember! a Maybe is never false (in Ruby terms), if you want to know if it is false, call `#empty?` of `#truly?`
 
@@ -85,32 +96,36 @@ Remember! a Maybe is never false (in Ruby terms), if you want to know if it is f
 
 Slug example
 
-    # instead of 
-    def slug(title)
-      if title
-        title.strip.downcase.tr_s('^[a-z0-9]', '-')
-      end
-    end
+```ruby
+# instead of 
+def slug(title)
+  if title
+    title.strip.downcase.tr_s('^[a-z0-9]', '-')
+  end
+end
 
-    # or 
+# or 
 
-    def slug(title)
-      title && title.strip.downcase.tr_s('^[a-z0-9]', '-')
-    end
+def slug(title)
+  title && title.strip.downcase.tr_s('^[a-z0-9]', '-')
+end
 
-    # do it with a default
-    def slug(title)
-      Maybe(title).strip.downcase.tr_s('^[a-z0-9]', '-')._('unknown-title')
-    end
+# do it with a default
+def slug(title)
+  Maybe(title).strip.downcase.tr_s('^[a-z0-9]', '-')._('unknown-title')
+end
+```
 
 ### Object#_?
 Works similar to the Elvis operator _? - ruby does not allow ?: as operator and use it like the excellent [andand](https://github.com/raganwald/andand)
 
-    require 'monadic/core_ext/object'   # this will import _? into the global Object
-    nil._?           == Nothing
-    "foo"._?         == 'foo'
-    {}._?.a.b        == Nothing
-    {}._?[:foo]      == Nothing
+```ruby
+require 'monadic/core_ext/object'   # this will import _? into the global Object
+nil._?           == Nothing
+"foo"._?         == 'foo'
+{}._?.a.b        == Nothing
+{}._?[:foo]      == Nothing
+```
 
 In fact this is a shortcut notation for `Maybe(obj)`
 
@@ -124,61 +139,70 @@ What is specific to this implementation is that exceptions are caught within the
 
 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.
 
-    result = parse_and_validate_params(params).                 # must return a Success or Failure inside
-                bind ->(user_id) { User.find(user_id) }.        # if #find returns null it will become a Failure
-                bind ->(user)    { authorized?(user); user }.   # if authorized? raises an Exception, it will be a Failure 
-                bind ->(user)    { UserDecorator(user) }
-
-    if result.success?
-      @user = result.fetch                                      # result.fetch or result._ contains the 
-      render 'page'
-    else
-      @error = result.fetch
-      render 'error_page'
-    end
+```ruby
+result = parse_and_validate_params(params).                 # must return a Success or Failure inside
+            bind ->(user_id) { User.find(user_id) }.        # if #find returns null it will become a Failure
+            bind ->(user)    { authorized?(user); user }.   # if authorized? raises an Exception, it will be a Failure 
+            bind ->(user)    { UserDecorator(user) }
+
+if result.success?
+  @user = result.fetch                                      # result.fetch or result._ contains the 
+  render 'page'
+else
+  @error = result.fetch
+  render 'error_page'
+end
+```
 
 You can use alternate syntaxes to achieve the same goal:
 
-    # block and Haskell like >= operator
-    Either(operation).
-      >= { successful_method }.
-      >= { failful_operation }
+```ruby
+# block and Haskell like >= operator
+Either(operation).
+  >= { successful_method }.
+  >= { failful_operation }
 
-    # start with a Success, for instance a parameter
-    Success('pzol').
-      bind ->(previous) { good }.
-      bind ->           { bad  }
+# start with a Success, for instance a parameter
+Success('pzol').
+  bind ->(previous) { good }.
+  bind ->           { bad  }
 
-    Either.chain do
-      bind ->                   { good   }                     # >= is not supported for Either.chain, only bind
-      bind ->                   { better }                     # better returns Success(some_int)
-      bind ->(previous_result)  { previous_result + 1 }
-    end
+Either.chain do
+  bind ->                   { good   }                     # >= is not supported for Either.chain, only bind
+  bind ->                   { better }                     # better returns Success(some_int)
+  bind ->(previous_result)  { previous_result + 1 }
+end
 
-    either = Either(something)
-    either += truth? Success('truth, only the truth') : Failure('lies, damn lies')
+either = Either(something)
+either += truth? Success('truth, only the truth') : Failure('lies, damn lies')
+```
 
 Exceptions are wrapped into a Failure:
 
-    Either(true).
-      bind -> { fail 'get me out of here' }                    # return a Failure(RuntimeError)
+```ruby
+Either(true).
+  bind -> { fail 'get me out of here' }                    # return a Failure(RuntimeError)
+```
 
 Another example:
 
-    Success(params).
-      bind ->(params)   { Either(params.fetch(:path)) }        # fails if params does not contain :path
-      bind ->(path)     { load_stuff(params)          }        # 
+```ruby
+Success(params).
+  bind ->(params)   { Either(params.fetch(:path)) }        # fails if params does not contain :path
+  bind ->(path)     { load_stuff(params)          }        # 
+```
 
 Storing intermediate results in instance variables is possible, although it is not very elegant:
 
-    result = Either.chain do
-      bind { @map = { one: 1, two: 2 } }
-      bind { @map.fetch(:one) }
-      bind { |p| Success(p + 100) }
-    end
-
-    result == Success(101)
+```ruby
+result = Either.chain do
+  bind { @map = { one: 1, two: 2 } }
+  bind { @map.fetch(:one) }
+  bind { |p| Success(p + 100) }
+end
 
+result == Success(101)
+```    
 
 ### Validation 
 The Validation applicative functor, takes a list of checks within a block. Each check must return either Success of Failure.  
@@ -187,60 +211,68 @@ Within the Failure() provide the reason why the check failed.
 
 Example:
 
-    def validate(person)
-      check_age = ->(age_expr) {
-        age = age_expr.to_i
-        case 
-        when age <=  0; Failure('Age must be > 0')
-        when age > 130; Failure('Age must be < 130')
-        else Success(age)
-        end
-      }
-
-      check_sobriety = ->(sobriety) {
-        case sobriety
-        when :sober, :tipsy; Success(sobriety)
-        when :drunk        ; Failure('No drunks allowed')
-        else Failure("Sobriety state '#{sobriety}' is not allowed")
-        end 
-      }
-
-      check_gender = ->(gender) {
-        gender == :male || gender == :female ? Success(gender) : Failure("Invalid gender #{gender}")
-      }
-        
-      Validation() do
-        check { check_age.(person.age);          }
-        check { check_sobriety.(person.sobriety) }
-        check { check_gender.(person.gender)     }
-      end
+```ruby
+def validate(person)
+  check_age = ->(age_expr) {
+    age = age_expr.to_i
+    case 
+    when age <=  0; Failure('Age must be > 0')
+    when age > 130; Failure('Age must be < 130')
+    else Success(age)
     end
+  }
+
+  check_sobriety = ->(sobriety) {
+    case sobriety
+    when :sober, :tipsy; Success(sobriety)
+    when :drunk        ; Failure('No drunks allowed')
+    else Failure("Sobriety state '#{sobriety}' is not allowed")
+    end 
+  }
+
+  check_gender = ->(gender) {
+    gender == :male || gender == :female ? Success(gender) : Failure("Invalid gender #{gender}")
+  }
+    
+  Validation() do
+    check { check_age.(person.age);          }
+    check { check_sobriety.(person.sobriety) }
+    check { check_gender.(person.gender)     }
+  end
+end
+```
 
 The above example, returns either `Success([32, :sober, :male])` or `Failure(['Age must be > 0', 'No drunks allowed'])` with a list of what went wrong during the validation.
 
-See also exmaples/validation.rb
+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.
 
 __#map__ is used to map the inner value
 
-    Monad.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Monad(Hello Foo)
-    Monad.unit([1,2]).map {|v| v + 1}                             == Monad([2, 3])
+```ruby
+Monad.unit('FOO').map(&:capitalize).map {|v| "Hello #{v}"}    == Monad(Hello Foo)
+Monad.unit([1,2]).map {|v| v + 1}                             == Monad([2, 3])
+```
 
 __#bind__ allows (priviledged) access to the boxed value. This is the traditional _no-magic_ `#bind` as found in Haskell, 
-You are responsible for re-wrapping the value into a Monad again.
+You` are responsible for re-wrapping the value into a Monad again.
   
-    # 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
+```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
 
-    # proper use
-    Monad.unit('foo').bind {|v| Monad.unit(v.capitalize) }        == Monad(Foo)
+# proper use
+Monad.unit('foo').bind {|v| Monad.unit(v.capitalize) }        == Monad(Foo)
+```
 
 __#fetch__ extracts the inner value of the Monad, some Monads will override this standard behaviour, e.g. the Maybe Monad
 
-    Monad.unit('foo').fetch                                       == "foo"
+```ruby
+Monad.unit('foo').fetch                                       == "foo"
+```
 
 ## References
 

data/examples/validation.rb

@@ -1,10 +1,13 @@
 require 'monadic'
 
+class AgeTooLowError < ArgumentError;  end
+class AgeTooHighError < ArgumentError; end
+
 valid_age = ->(age_expr) {
   age = age_expr.to_i
   case 
-  when age <=  0; Failure('Age must be > 0')
-  when age > 130; Failure('Age must be < 130')
+  when age <=  0; Failure(AgeTooLowError.new(age_expr))
+  when age > 130; Failure(AgeTooHighError.new(age_expr))
   else Success(age)
   end
 }
@@ -21,11 +24,14 @@ params = {age: 32, name: 'Andrzej', postcode: '50000'}
 Person = Struct.new(:name, :age)
 
 result = Validation() do
-  check { valid_age.(params[:age])   }
   check { valid_name.(params[:name]) }
+  check { valid_age.(params[:age])   }
 end
 
 case result
   when Failure; puts "Something went wrong: #{result.fetch}"
   when Success; person = Person.new(*result.fetch); puts "We have a person #{person.inspect}"
 end
+
+# Failure: Something went wrong: [#<AgeTooHighError: 200>]
+# Success: We have a person #<struct Person name="Andrzej", age=32>

data/examples/validation_module.rb

@@ -0,0 +1,46 @@
+require 'monadic'
+
+Person = Struct.new(:name, :age)
+
+module PersonValidation
+  class AgeTooLowError < ArgumentError;  end
+  class AgeTooHighError < ArgumentError; end
+
+  def self.validate(params)
+    Validation()  do
+      extend PersonValidation
+      check { valid_age(params[:age])  }
+      check { valid_name(params[:name])}
+    end
+  end
+
+  def valid_age(expr)
+    age = expr.to_i
+    case 
+    when expr.nil?; Failure(ArgumentError.new(:age))
+    when age <=  0; Failure(AgeTooLowError.new(expr))
+    when age > 130; Failure(AgeTooHighError.new(expr))
+    else Success(age)
+    end
+  end
+
+  def valid_name(name)
+    case 
+    when name =~ /\w{3,99}/i; Success(name)
+    else Failure('Invalid name')
+    end
+  end
+end
+
+module PersonBuild
+  def self.build(params)
+    result = PersonValidation.validate(params)
+    case result
+    when Failure; result
+    when Success; Person.new(*result.fetch)
+    end
+  end
+end
+
+p person1 = PersonBuild.build({ name: 'Andrzej' })            # Failure([#<ArgumentError: age>])
+p person2 = PersonBuild.build({ name: 'Andrzej', age: 32 })   # <struct Person name=32, age="Andrzej">

data/lib/monadic/either.rb

@@ -1,6 +1,7 @@
 module Monadic
   # @abstract Chains function calls and stops executing if one of them fails.
-  class Either < Monad
+  class Either 
+    include Monadic::Monad
     def self.chain(initial=nil, &block)
       Either::Chain.new(&block).call(initial)
     end
@@ -24,8 +25,8 @@ module Monadic
 
       begin
         Either(call(proc, block))
-      rescue Exception => ex
-        Failure(ex)      
+      rescue StandardError => error
+        Failure(error)      
       end
     end
     alias :>=  :bind

data/lib/monadic/maybe.rb

@@ -1,5 +1,7 @@
 module Monadic
-  class Maybe < Monad
+  class Maybe 
+    include Monadic::Monad
+    
     def self.unit(value)
       return Nothing if value.nil? || (value.respond_to?(:empty?) && value.empty?)
       return Just.new(value)

data/lib/monadic/monad.rb

@@ -1,9 +1,5 @@
 module Monadic 
-  class Monad
-    def self.unit(value)
-      new(value)
-    end
-
+  module Monad
     def initialize(value)
       @value = join(value)
     end
@@ -41,7 +37,7 @@ module Monadic
       Array(@value)
     end
     alias :to_a :to_ary
-    
+      
     # Return the string representation of the Monad
     def to_s
       pretty_class_name = self.class.name.split('::')[-1]

data/lib/monadic/version.rb

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

data/spec/either_spec.rb

@@ -43,7 +43,7 @@ describe Monadic::Either do
     Success(nil).bind { nil }.should == Failure(nil)
   end
 
-  it 'catches exceptions and returns them as Failure' do
+  it 'catches StandardError exceptions and returns them as Failure' do
     either = Success(nil).
       bind { raise 'error' }
 

data/spec/monad_spec.rb

@@ -1,34 +1,41 @@
 require 'spec_helper'
 
 describe Monadic::Monad do
+  class Identity 
+    include Monadic::Monad
+    def self.unit(value)
+      new(value)
+    end
+  end
+
   it_behaves_like 'a Monad' do 
-    let(:monad) { Monad }
+    let(:monad) { Identity }
   end
 
   it '#to_s shows the monad name and its value' do
-    Monad.unit(1).to_s.should == 'Monad(1)'
-    Monad.unit(nil).to_s.should == 'Monad(nil)'
-    Monad.unit([1, 2]).map(&:to_s).should == Monad.unit(["1", "2"])
+    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"])
 
     # can be done also
-    Monad.unit([1, 2]).bind {|v| Monad.unit(v.map(&:to_s)) }.should == Monad.unit(["1", "2"])
+    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
-      Monad.unit(1).map {|v| v + 2}.should == Monad.unit(3)
-      Monad.unit('foo').map(&:upcase).should == Monad.unit('FOO')
+      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
-      Monad.unit([1,2]).map {|v| v + 1}.should == Monad.unit([2, 3])
-      Monad.unit(['foo', 'bar']).map(&:upcase).should == Monad.unit(['FOO', 'BAR'])
+      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
   end
 
   describe '#to_ary #to_a' do
-    Monad.unit([1, 2]).to_a.should == [1, 2]
-    Monad.unit(nil).to_a.should == []
-    Monad.unit('foo').to_a.should == ['foo']
+    Identity.unit([1, 2]).to_a.should == [1, 2]
+    Identity.unit(nil).to_a.should == []
+    Identity.unit('foo').to_a.should == ['foo']
   end
 end

data/spec/spec_helper.rb

@@ -1,5 +1,5 @@
 require 'bundler/setup'
-Bundler.require(:default, :test)
+Bundler.require(:test)
 
 $LOAD_PATH << File.expand_path('../../lib', __FILE__)
 require File.expand_path('../../lib/monadic', __FILE__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monadic
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-06 00:00:00.000000000 Z
+date: 2012-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -140,6 +140,7 @@ files:
 - README.md
 - Rakefile
 - examples/validation.rb
+- examples/validation_module.rb
 - lib/monadic.rb
 - lib/monadic/core_ext/object.rb
 - lib/monadic/either.rb